netcdf-2 (3) - Linux Manuals

netcdf-2: Unidata Network Common Data Form (netCDF-2) library

NAME

netcdf - Unidata Network Common Data Form (netCDF-2) library

WARNING

The interface described here is obsolete, but included because the perl module still use it.

SYNOPSIS

#include <netcdf.h>

int nccreate(const char* path, int cmode)

int ncopen(const char* path, int mode)

int ncredef(int ncid)

int ncsetfill(int ncid, int fillmode)

int ncendef(int ncid)

int ncclose(int ncid)

int ncinquire(int ncid, int* ndims, int* nvars, int* natts, int* recdim)

int ncsync(int ncid)

int ncabort(int ncid)

int ncdimdef(int ncid, const char* name, long length)

int ncdimid(int ncid, const char* name)

int ncdiminq(int ncid, int dimid, char* name, long* length)

int ncdimrename(int ncid, int dimid, const char* name)

int ncvardef(int ncid, const char* name, nc_type datatype, int ndims, const int dimids[])

int ncvarid(int ncid, const char* name)

int ncvarinq(int ncid, int varid, char* name, nc_type* datatype, int* ndims, int dimids[], int* natts)

int ncvarput1(int ncid, int varid, const long coords[], const void* value)

int ncvarget1(int ncid, int varid, const long coords[], void* value)

int ncvarput(int ncid, int varid, const long start[], const long count[], const void* value)

int ncvarget(int ncid, int varid, const long start[], const long count[], void* value)

int ncvarputg(int ncid, int varid, const long start[], const long count[], const long stride[], const long imap[], const void* value)

int ncvargetg(int ncid, int varid, const long start[], const long count[], const long stride[], const long imap[], void* value)

int ncrecput(int ncid, long recnum, void* const valuep[])

int ncrecget(int ncid, long recnum, void* valuep[])

int ncrecinq(int ncid, int* nrvars, int rvarids[], long rsizes[])

int ncvarrename(int ncid, int varid, const char* name)

int ncattput(int ncid, int varid, const char* name, nc_type datatype, int len, const void* value)

int ncattinq(int ncid, int varid, const char* name, nc_type* datatype, int* len)

int ncattget(int ncid, int varid, const char* name, void* value)

int ncattcopy(int inncid, int invar, const char* name, int outncid, int outvar)

int ncattname(int ncid, int varid, int attnum, char* name)

int ncattrename(int ncid, int varid, const char* name, const char* newname)

int ncattdel(int ncid, int varid, const char* name)

int nctypelen(nc_type datatype)

FUNCTION DESCRIPTIONS

These routines implement the Unidata netCDF data-access interface for the C programming language. Only those arguments which are unique to the function being described are documented in this section. See the section "COMMON ARGUMENT DESCRIPTIONS" for descriptions of the other arguments.

int nccreate(const char* path, int cmode)

Creates the new netCDF file, returning a netCDF ID that can subsequently be used to refer to the netCDF file. The new netCDF file is placed in define mode. The mode parameter, cmode, should be either NC_CLOBBER or NC_NOCLOBBER. NC_CLOBBER means that even if the file already exists, you want to create a new file with the same name, erasing the old file's contents. NC_NOCLOBBER means you want to create a new netCDF file only if the given file name does not refer to a file that already exists. If an error occurs, this function returns -1.

int ncopen(const char* path, int mode)

Opens the existing netCDF file for access. The mode parameter, mode, should be either NC_WRITE, to open the file for writing, or NC_NOWRITE, to open the file read-only. "Writing" means any kind of change to the file, including appending or changing data, adding or renaming dimensions, variables, or attributes, or deleting attributes. If an error occurs, this function returns -1.

int ncredef(int ncid)

Puts an open netCDF file into define mode, so dimensions, variables, and attributes can be added or renamed and attributes can be deleted. If an error occurs, this function returns -1.

int ncsetfill(int ncid, int fillmode)

Determines whether or not variable prefilling will be done (see VARIABLE PREFILLING below). The netCDF file shall be writable. fillmode is either NC_FILL to enable prefilling (the default) or NC_NOFILL to disable prefilling. This function returns the previous setting or -1 if an error occurs.

int ncendef(int ncid)

Takes an open netCDF file out of define mode. The changes made to the netCDF file while it was in define mode are checked and committed to disk if no problems occurred. In particular, non-record variables are filled with their fill-values unless ncsetfill() has been called with the argument NC_NOFILL. The netCDF file is then placed in data mode, so that variable data can be read or written. If an error occurs, this function returns -1.

int ncclose(int ncid)

Closes an open netCDF file. If the file is in define mode, ncendef() will be called before closing. (In this case, if ncendef() returns an error, ncabort() will automatically be called to restore the file to the consistent state before define mode was last entered.) After an open netCDF file is closed, its netCDF ID will be reassigned to the next netCDF file that is opened or created. If an error occurs, this function returns -1.

int ncinquire(int ncid, int* ndims, int* nvars, int* natts, int* recdim)

Returns information about an open netCDF file. Upon successful return, ndims will contain the number of dimensions defined for this netCDF file, nvars will contain the number of variables, natts will contain the number of attributes, and recdim will contain the ID of the unlimited dimension if one exists, or -1 otherwise. If any of the return parameters is a NULL pointer, then the corresponding information will not be returned; hence, no space need be allocated for it. If an error occurs, this function returns -1.

int ncsync(int ncid)

Updates a writable netCDF file. The netCDF file must be in data mode. A netCDF file in define mode is synchronized to disk only when ncendef() is called. It can be expensive in computer resources to always synchronize to disk after every write of variable data or change of an attribute value. There are two reasons you might want to synchronize after writes: 1) to minimize data loss in case of abnormal termination; and 2) to make data available to other processes for reading immediately after it is written. Data is automatically synchronized to disk when a netCDF file is closed, or whenever you leave define mode. If an error occurs, this function returns -1.

int ncabort(int ncid)

Closes or deletes a netCDF file. If the netCDF file isn't in define mode, then the file is closed. If the file is being created and is still in define mode, the file is deleted. If define mode was entered by a call to ncredef(), the netCDF file is restored to its state before definition mode was entered and the file is closed. The main reason for calling ncabort() is to restore the netCDF to a known consistent state in case anything goes wrong during the definition of new dimensions, variables, or attributes. This function is called automatically if ncclose() is called from define mode and the call to leave define mode before closing fails. If an error occurs, this function returns -1.

int ncdimdef(int ncid, const char* name, long length)

Adds a new dimension to an open netCDF file, which must be in define mode. name is the dimension name. If an error occurs, this function returns -1.

int ncdimid(int ncid, const char* name)

Returns the ID of a netCDF dimension, given the name of the dimension. If an error occurs, this function returns -1.

int ncdiminq(int ncid, int dimid, char* name, long* size)

Returns the name and size of a dimension, given its ID. If either the name parameter or size parameter is a NULL pointer, the associated information will not be returned, so no space needs to be allocated. For the unlimited dimension, the returned size is the current maximum value used for writing any record variables, (i.e. the maximum record number). If an error occurs, this function returns -1.

int ncdimrename(int ncid, int dimid, const char* name)

Renames an existing dimension in an open netCDF file. If the new name is longer than the old name, the netCDF must be in define mode. You cannot rename a dimension to have the same name as another dimension. If an error occurs, this function returns -1.

int ncvardef(int ncid, const char* name, nc_type datatype,

int ndims, const int dimids[])

Adds a new variable to an open netCDF file in define mode. It returns a netCDF variable ID. If an error occurs, this function returns -1.

int ncvarid(int ncid, const char* name)

Returns the ID of a netCDF variable, given its name. If an error occurs, this function returns -1.

int ncvarinq(int ncid, int varid, char* name,

nc_type* datatype, int* ndims, int dimids[], int* natts)

Returns information about a netCDF variable, given its ID. If any of the return parameters (name, datatype, ndims, dimids, or natts) is a NULL pointer, then the corresponding information will not be returned; hence, no space need be allocated for it. If an error occurs, this function returns -1.

int ncvarput1(int ncid, int varid, const long coords[],

const void* value)

Puts a single data value into a variable of an open netCDF file that is in data mode. If an error occurs, this function returns -1.

int ncvarget1(int ncid, int varid, const long coords[],

void* value)

Gets a single data value from a variable of an open netCDF file that is in data mode. If an error occurs, this function returns -1.

int ncvarput(int ncid, int varid, const long start[],

const long count[], const void* value)

Writes a hyperslab of values into a netCDF variable of an open netCDF file, which must be in data mode. If an error occurs, this function returns -1.

int ncvarget(int ncid, int varid, const long start[],

const long count[], void* value)

Reads a hyperslab of values from a netCDF variable of an open netCDF file, which must be in data mode. If an error occurs, this function returns -1.

int ncvarputg(int ncid, int varid, const long start[],

const long count[], const long stride[], const long imap[], const void* value)

Writes a general hyperslab of values into a netCDF variable of an open netCDF file, which must be in data mode. The locations of the memory-resident data values may be arbitrary, though they are constrained to have a regular structure. In addition, the values of the netCDF variable may be accessed using non-unity strides. If an error occurs, this function returns -1.

int ncvargetg(int ncid, int varid, const long start[],

const long count[], const long stride[], const long imap[], void* value)

Reads a general hyperslab of values from a netCDF variable of an open netCDF file, which must be in data mode. The locations of the memory-resident data values may be arbitrary, though they are constrained to have a regular structure. In addition, the values of the netCDF variable may be accessed using non-unity strides. If an error occurs, this function returns -1.

int ncrecput(int ncid, long recnum, const void* valuep[])

Writes a record (or a subset of a record) of values into the record variables of an open netCDF file, which must be in data mode. The record number, recnum, must be a nonnegative number that specifies which record (which value of the unlimited or record dimension) to write. The array of pointers to blocks of data to be written, valuep, should have one pointer for each record variable. The pointer to the data to be written to the n-th record variable, valuep[n], points to one record's worth of data of the appropriate type to be written into the recnum-th record of that netCDF variable. If the pointer for any record variable is the NULL pointer, no data is written for that variable. Hence any subset of record variables may be written by specifying non-NULL pointers for the desired record variables. Invoking this function is equivalent to a sequence of invocations of ncvarput() for all record variables for which a non-NULL pointer is specified. If an error occurs, this function returns -1.

int ncrecget(int ncid, long recnum, void* valuep[])

Reads a record (or a subset of a record) of values from the record variables of an open netCDF file, which must be in data mode. The record number, recnum, must be a nonnegative number that specifies which record to read. The array of pointers to blocks of data to be read, valuep, should have one pointer for each record variable. The pointer to the data to be read for the n-th record variable, valuep[n], shall point to enough space to hold one record's worth of data of the appropriate type for that netCDF record variable. If the pointer for any record variable is the NULL pointer, no data is read from that variable. Hence any subset of record variables may be read by specifying non-NULL pointers for only the desired record variables. Invoking this function is equivalent to a sequence of invocations of ncvarget() for all record variables for which a non-NULL pointer is specified. If an error occurs, this function returns -1.

int ncrecinq(int ncid, int* nrvars, int rvarids[], long rsizes[])

Returns information about the record variables (variables that use the unlimited dimension) of an open netCDF file. Upon successful return, nrvars will contain the number of record variables, rvarids will contain the variable IDs of those record variables, and rsizes will contain the size in bytes for a record's worth of data for each record variable. If any of the return parameters (nrvars, rvarids, or rsizes) is a NULL pointer, the specified information will not be returned; hence no space needs to be allocated for it. If an error occurs, this function returns -1.

int ncvarrename(int ncid, int varid, const char* name)

Changes the name of a netCDF variable in an open netCDF. If the new name is longer than the old name, the netCDF must be in define mode. You cannot rename a variable to have the name of any existing variable. If an error occurs, this function returns -1.

int ncattput(int ncid, int varid, const char* name,

nc_type datatype, int len, const void* value)

Adds or changes a variable attribute or global attribute of an open netCDF file. If this attribute is new, or if the space required to store the attribute is greater than before, the netCDF file must be in define mode. If an error occurs, this function returns -1.

int ncattinq(int ncid, int varid, const char* name,

nc_type* datatype, int* len)

Returns information about a netCDF attribute, given its variable ID and name. The information returned is the type and length of the attribute. If either of the return parameters is a NULL pointer, the specified information will not be returned; hence no space needs to be allocated for it. If an error occurs, this function returns -1.

int ncattget(int ncid, int varid, const char* name,

void* value)

Gets the value(s) of a netCDF attribute, given its variable ID and name. All elements of the vector of attribute values are returned, so you must allocate enough space to hold them. If you don't know how much space to reserve, call ncattinq() first to find out the length of the attribute. If an error occurs, this function returns -1.

int ncattcopy(int inncid, int invar, const char* name,

int outncid, int outvar)

Copies an attribute from one open netCDF file to another. It can also be used to copy an attribute from one variable to another within the same netCDF. inncid is the netCDF ID of an input netCDF file from which the attribute will be copied. invar is the ID of the variable in the input netCDF file from which the attribute will be copied, or NC_GLOBAL for a global attribute. name is the name of the attribute in the input netCDF file to be copied. outncid is the netCDF ID of the output netCDF file to which the attribute will be copied. It is permissible for the input and output netCDF IDs to be the same. The output netCDF file should be in define mode if the attribute to be copied does not already exist for the target variable, or if it would cause an existing target attribute to grow. outvar is the ID of the variable in the output netCDF file to which the attribute will be copied, or NC_GLOBAL to copy to a global attribute. If an error occurs, this function returns -1.

int ncattname(int ncid, int varid, int attnum,

char* name)

Gets the name of an attribute, given its variable ID and number as an attribute of that variable. This function is useful in generic applications that need to get the names of all the attributes associated with a variable, since attributes are accessed by name rather than number in all other attribute functions. The number of an attribute is more volatile than the name, since it can change when other attributes of the same variable are deleted. This is why an attribute number is not called an attribute ID. attnum is the number of the attribute. The attributes for each variable are numbered from 0 (the first attribute) to nvatts-1, where nvatts is the number of attributes for the variable, as returned from a call to ncvarinq(). If the name parameter is a NULL pointer, no name will be returned and no space need be allocated. If an error occurs, this function returns -1.

int ncattrename(int ncid, int varid, const char* name,

const char* newname)

Changes the name of an attribute. If the new name is longer than the original name, the netCDF must be in define mode. You cannot rename an attribute to have the same name as another attribute of the same variable. name is the original attribute name. newname is the new name to be assigned to the specified attribute. If the new name is longer than the old name, the netCDF file must be in define mode. If an error occurs, this function returns -1.

int ncattdel(int ncid, int varid, const char* name)

Deletes a netCDF attribute from an open netCDF file. The netCDF file must be in define mode. If an error occurs, this function returns -1.

int nctypelen(nc_type datatype)

Returns the number of bytes in a netCDF data type. If an error occurs, this function returns -1.

COMMON ARGUMENT DESCRIPTIONS

char* name

is the name of a dimension, variable, or attribute. It shall begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore (`_'). Case is significant. As an input argument, it shall be a pointer to a 0-terminated string; as an output argument, it shall be the address of a buffer in which to hold such a string. The maximum allowable number of characters (excluding the terminating 0) is MAX_NC_NAME. Attribute names that begin with an underscore (`_') are reserved for use by the netCDF interface.

char* path

is the pathname of a netCDF file. It may be absolute or relative.

int ncid

is the netCDF ID returned from a previous, successful call to ncopen() or nccreate().

int dimids[]

is a vector of dimension ID's and defines the shape of a netCDF variable. The size of the vector shall be greater than or equal to the rank (i.e. the number of dimensions) of the variable (ndims). The vector shall be ordered by the speed with which a dimension varies: dimids[ndims-1] shall be the dimension ID of the most rapidly varying dimension and dimids[0] shall be the dimension ID of the most slowly varying dimension. Consequently, if a variable is a record variable, then dimids[0] shall be the dimension ID of the record dimension. The maximum possible number of dimensions for a variable is given by the symbolic constant MAX_VAR_DIMS.

int dimid

is the ID of a netCDF dimension. netCDF dimension ID's are allocated sequentially from the non-negative integers beginning with 0.

int len

is the number of values associated with an attribute. If the attribute is of type NC_CHAR, then this is one more than the string length (since the terminating 0 is stored).

int ndims

is either the total number of dimensions in a netCDF dataset or the rank (i.e. the number of dimensions) of a netCDF variable. The value shall not be negative or greater than the symbolic constant MAX_VAR_DIMS.

int varid

is the ID of a netCDF variable or (for the attribute-access functions) the symbolic constant NC_GLOBAL, which is used to reference global attributes. netCDF variable ID's are allocated sequentially from the non-negative integers beginning with 0.

int natts

is the number of global attributes in a netCDF dataset for the ncinquire() function or the number of attributes associated with a netCDF variable for the ncvarinq() function.

long imap[]

is the index mapping vector that specifies how data values associated with a netCDF variable are arranged in memory. The offset, in bytes, from the memory location pointed to by the value argument to a particular datum is given by the inner (dot) product of the index mapping vector with the coordinates of the datum. For example, on a machine where `sizeof(float) == 4', the index mapping vector for the array `float u[3][5];' is `long imap[2] = {20,4}'. Note that the index mapping vector can be used to access memory-resident data values in a manner that differs radically from the nominal structure of the associated netCDF variable. For example, the following definitions

struct vel {
    int flags;
    float u;
    float v;
} vel[NX][NY];
long imap[2] = {
    sizeof(struct vel),
    sizeof(struct vel)*NY};

can be used to access the memory-resident values of the netCDF variable, `u[NY][NX]', even though the dimensions are transposed and the data is contained in a 2-D array of structures rather than a 2-D array of floating-point values. The index mapping vector may contain negative values if the value argument is appropriately set. A NULL index mapping vector argument obtains the default behavior in which the memory-resident values are assumed to have the same structure as the associated netCDF variable.

long coords[]

specifies the indicial coordinates of the netCDF data value to be accessed. The indices are relative to 0; thus, for example, the first data value of a two-dimensional variable is (0,0). The size of the vector shall be at least the rank of the associated netCDF variable and its elements shall correspond, in order, to the variable's dimensions. Consequently, if the variable is a record variable, then the first index is the record number.

long count[]

specifies the number of data values to be accessed in terms of the lengths of the sides of the hyperslab. Thus, to access a single value, for example, specify count as (1, 1, ..., 1). Note that, for generalized hyperslab I/O, this argument must be adjusted to be compatible with the stride and start arguments so that the interaction of the three does not attempt to access an invalid data co-ordinate. For example, to access every stride(i)'th datum along dimension i beginning with point start(i), counts(i) should be 1+(npts(i)-1-start(i))/stride(i): where npts(i) is the size of dimension i. The size of the count vector shall be at least the rank of the associated netCDF variable and its elements shall correspond, in order, to the variable's dimensions. Consequently, if the variable is a record variable, then the first element of count is the number of records to access.

long length

is the size of a netCDF dimension. As an input argument, it shall be a positive integer or the symbolic constant NC_UNLIMITED. At most one such unlimited size dimension, called the record dimension, shall be defined in a netCDF dataset. As an output argument, it shall be a positive integer.

long start[]

specifies the starting point for accessing a netCDF variable's data values in terms of the indicial coordinates of the corner of the hyperslab. The indices are relative to 0; thus, the first data value of a variable is (0, 0, ..., 0). The size of the vector shall be at least the rank of the associated netCDF variable and its elements shall correspond, in order, to the variable's dimensions. Consequently, if the variable is a record variable, then the first index is the starting record number for accessing the netCDF variable's data values.

long stride[]

specifies, for each dimension, the interval between the accessed values of a netCDF variable. The size of the vector shall be at least the rank of the associated netCDF variable and its elements shall correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. Attempting to access a data value that lies outside the defined data space of a variable is an error. A NULL stride argument obtains the default behavior in which adjacent values are accessed along each dimension.

nc_type datatype

specifies the data type of a netCDF variable and is one of the following: NC_BYTE, NC_CHAR, NC_SHORT, NC_LONG, NC_FLOAT, or NC_DOUBLE.

void* value

points to the start of the memory-resident data values to be accessed. The pointer is declared to be of type void* because it can point to data of any of the basic netCDF types. The data should be of the appropriate type for the netCDF variable:

netCDF Type	C Type
NC_BYTE	unsigned char
NC_CHAR	char
NC_SHORT	short
NC_LONG	nclong
NC_FLOAT	float
NC_DOUBLE	double

NOTE: The C type corresponding to the netCDF type NC_LONG is nclong. This type is defined in the netCDF header file and is guaranteed to hold at least 32 bits. It is defined as either a C `int' or a C `long' -- depending on the platform.

Warning: neither the compiler nor the netCDF software can detect if the wrong type of data is used.

VARIABLE PREFILLING

By default, the netCDF interface sets the values of all newly-defined variables of finite length (i.e. not having an unlimited, record dimension) to the type-dependent fill-value associated with each variable. This is done when `ncendef()' is called. The fill-value for a variable may be changed from the default value by defining the attribute `_FillValue' for the variable. This attribute must have the same type as the variable and be of length one.

Variables with an unlimited record dimension are also prefilled, but on an `as needed' basis. For example, if the first write of a record variable is to position 5, then positions 0 through 4 (and no others) would be set to the fill-value at the same time.

This default prefilling of data values may be disabled by calling the function ncsetfill() with the argument NC_NOFILL. Note that, for non-record variables, this call must be made before ncendef(); whereas, for record-variables, this call may be made at any time.

One can obtain increased performance of the netCDF interface by using this feature, but only at the expense of requiring the application to set every single data value.

GLOBAL OPTIONS

The global variable `ncopts', which is defined in `netcdf.h', affects the actions of the netCDF interface. It may be set by the user to the bitwise OR of any of the following, non-zero, symbolic bit-values:

NC_VERBOSE

Print error-messages on standard error.

NC_FATAL

Abort. Call `exit()' with an error-condition if an error occurs.

By default, `ncopts' is `NC_VERBOSE | NC_FATAL'.

ENVIRONMENT VARIABLES

NETCDF_FFIOSPEC

Specifies the Flexible File I/O buffers for netCDF I/O when executing under the UNICOS operating system (the variable is ignored on other operating systems). An appropriate specification can greatly increase the efficiency of netCDF I/O -- to the extent that it can actually surpass FORTRAN binary I/O. The default specification is bufa:336:2. See UNICOS Flexible File I/O for more information.

MAILING-LISTS

Both a mailing list and a digest are available for discussion of the netCDF interface and announcements about netCDF bugs, fixes, and enhancements. To begin or change your subscription to either the mailing-list or the digest, send one of the following in the body (not the subject line) of an email message to "Majordomo [at] unidata.ucar.edu". Use your email address in place of jdoe [at] host.inst.domain.

To subscribe to the netCDF mailing list:

subscribe netcdfgroup jdoe [at] host.inst.domain

To unsubscribe from the netCDF mailing list:

unsubscribe netcdfgroup jdoe [at] host.inst.domain

To subscribe to the netCDF digest:

subscribe netcdfdigest jdoe [at] host.inst.domain

To unsubscribe from the netCDF digest:

unsubscribe netcdfdigest jdoe [at] host.inst.domain

To retrieve the general introductory information for the mailing list:

info netcdfgroup

To get a synopsis of other majordomo commands:

help