netCDF  4.2.1.1
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
The netCDF File Format

Until version 3.6.0, all versions of netCDF employed only one binary data format, now referred to as netCDF classic format.

NetCDF classic is the default format for all versions of netCDF.

In version 3.6.0 a new binary format was introduced, 64-bit offset format. Nearly identical to netCDF classic format, it uses 64-bit offsets (hence the name), and allows users to create far larger datasets.

In version 4.0.0 a third binary format was introduced: the HDF5 format. Starting with this version, the netCDF library can use HDF5 files as its base format. (Only HDF5 files created with netCDF-4 can be understood by netCDF-4).

By default, netCDF uses the classic format. To use the 64-bit offset or netCDF-4/HDF5 format, set the appropriate constant when creating the file.

To achieve network-transparency (machine-independence), netCDF classic and 64-bit offset formats are implemented in terms of an external representation much like XDR (eXternal Data Representation, see http://www.ietf.org/rfc/rfc1832.txt), a standard for describing and encoding data. This representation provides encoding of data into machine-independent sequences of bits. It has been implemented on a wide variety of computers, by assuming only that eight-bit bytes can be encoded and decoded in a consistent way. The IEEE 754 floating-point standard is used for floating-point data representation.

Descriptions of the overall structure of netCDF classic and 64-bit offset files are provided later in this manual. See Structure.

The details of the classic and 64-bit offset formats are described in an appendix. See File Format. However, users are discouraged from using the format specification to develop independent low-level software for reading and writing netCDF files, because this could lead to compatibility problems if the format is ever modified.

How to Select the Format

With three different base formats, care must be taken in creating data files to choose the correct base format.

The format of a netCDF file is determined at create time.

When opening an existing netCDF file the netCDF library will transparently detect its format and adjust accordingly. However, netCDF library versions earlier than 3.6.0 cannot read 64-bit offset format files, and library versions before 4.0 can't read netCDF-4/HDF5 files. NetCDF classic format files (even if created by version 3.6.0 or later) remain compatible with older versions of the netCDF library.

Users are encouraged to use netCDF classic format to distribute data, for maximum portability.

To select 64-bit offset or netCDF-4 format files, C programmers should use flag NC_64BIT_OFFSET or NC_NETCDF4 in function nc_create. See nc_create.

In Fortran, use flag nf_64bit_offset or nf_format_netcdf4 in function NF_CREATE. See NF_CREATE.

It is also possible to change the default creation format, to convert a large body of code without changing every create call. C programmers see nc_set_default_format. Fortran programs see NF_SET_DEFAULT_FORMAT.

NetCDF Classic Format

The original netCDF format is identified using four bytes in the file header. All files in this format have “CDF\001” at the beginning of the file. In this documentation this format is referred to as “netCDF classic format.”

NetCDF classic format is identical to the format used by every previous version of netCDF. It has maximum portability, and is still the default netCDF format.

For some users, the various 2 GiB format limitations of the classic format become a problem. (see Classic Limitations). 1.4.2 NetCDF 64-bit Offset Format

For these users, 64-bit offset format is a natural choice. It greatly eases the size restrictions of netCDF classic files (see 64 bit Offset Limitations).

Files with the 64-bit offsets are identified with a “CDF\002” at the beginning of the file. In this documentation this format is called “64-bit offset format.”

Since 64-bit offset format was introduced in version 3.6.0, earlier versions of the netCDF library can't read 64-bit offset files.

NetCDF-4 Format

In version 4.0, netCDF included another new underlying format: HDF5.

NetCDF-4 format files offer new features such as groups, compound types, variable length arrays, new unsigned integer types, parallel I/O access, etc. None of these new features can be used with classic or 64-bit offset files.

NetCDF-4 files can't be created at all, unless the netCDF configure script is run with –enable-netcdf-4. This also requires version 1.8.0 of HDF5.

For the netCDF-4.0 release, netCDF-4 features are only available from the C and Fortran interfaces. We plan to bring netCDF-4 features to the CXX API in a future release of netCDF.

NetCDF-4 files can't be read by any version of the netCDF library previous to 4.0. (But they can be read by HDF5, version 1.8.0 or better).

For more discussion of format issues see The NetCDF Tutorial.


Generated on Wed Aug 22 2012 14:39:31 for netCDF. NetCDF is a Unidata library.