NetCDF  4.8.1
The Version 2 API

NetCDF's modern history began with the introduction of the V2 netCDF API by Glenn Davis and Russ Rew in 1991. (The V1 API is lost to mists of time.) More...

Functions

void nc_advise (const char *routine_name, int err, const char *fmt,...)
 
int nc_get_rec (int ncid, size_t recnum, void **datap)
 
int nc_inq_rec (int ncid, size_t *nrecvarsp, int *recvarids, size_t *recsizes)
 
int nc_put_rec (int ncid, size_t recnum, void *const *datap)
 
int ncabort (int ncid)
 
int ncattcopy (int ncid_in, int varid_in, const char *name, int ncid_out, int varid_out)
 
int ncattdel (int ncid, int varid, const char *name)
 
int ncattget (int ncid, int varid, const char *name, void *value)
 
int ncattinq (int ncid, int varid, const char *name, nc_type *datatype, int *len)
 
int ncattname (int ncid, int varid, int attnum, char *name)
 
int ncattput (int ncid, int varid, const char *name, nc_type datatype, int len, const void *value)
 
int ncattrename (int ncid, int varid, const char *name, const char *newname)
 
int ncclose (int ncid)
 
int nccreate (const char *path, int cmode)
 
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 ncendef (int ncid)
 
int ncinquire (int ncid, int *ndims, int *nvars, int *natts, int *recdim)
 
int ncopen (const char *path, int mode)
 
int ncrecget (int ncid, long recnum, void **datap)
 
int ncrecinq (int ncid, int *nrecvars, int *recvarids, long *recsizes)
 
int ncrecput (int ncid, long recnum, void *const *datap)
 
int ncredef (int ncid)
 
int ncsetfill (int ncid, int fillmode)
 
int ncsync (int ncid)
 
int ncvardef (int ncid, const char *name, nc_type datatype, int ndims, const int *dim)
 
int ncvarget (int ncid, int varid, const long *start, const long *count, void *value)
 
int ncvarget1 (int ncid, int varid, const long *index, void *value)
 
int ncvargetg (int ncid, int varid, const long *start, const long *count, const long *stride, const long *map, void *value)
 
int ncvargets (int ncid, int varid, const long *start, const long *count, const long *stride, void *value)
 
int ncvarid (int ncid, const char *name)
 
int ncvarinq (int ncid, int varid, char *name, nc_type *datatype, int *ndims, int *dim, int *natts)
 
int ncvarput (int ncid, int varid, const long *start, const long *count, const void *value)
 
int ncvarput1 (int ncid, int varid, const long *index, const void *value)
 
int ncvarputg (int ncid, int varid, const long *start, const long *count, const long *stride, const long *map, const void *value)
 
int ncvarputs (int ncid, int varid, const long *start, const long *count, const long *stride, const void *value)
 
int ncvarrename (int ncid, int varid, const char *name)
 

Detailed Description

NetCDF's modern history began with the introduction of the V2 netCDF API by Glenn Davis and Russ Rew in 1991. (The V1 API is lost to mists of time.)

The V2 API is still fully supported, but should not be used for new development.

All of the V2 functions have been reimplemented in terms of the V3 API code; see the documentation for the related V3 functions to get more documentation.

The V2 API is tested in test directory nctest.

Function Documentation

◆ nc_advise()

void nc_advise ( const char *  routine_name,
int  err,
const char *  fmt,
  ... 
)

Show an error message and exit (based on ncopts).

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_strerror()

Parameters
routine_name
errerror code
fmtpointer to a char array containing string format

Definition at line 466 of file dv2i.c.

◆ nc_get_rec()

int nc_get_rec ( int  ncid,
size_t  recnum,
void **  datap 
)

Read one record's worth of data, except don't read from variables for which the address of the data to be read is null. Return -1 on error. This is the same as the ncrecget() in the library, except that can handle errors better.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_vara().

Parameters
ncidfile ID
recnumthe record number to read.
datappointer memory to hold one record's worth of data for all variables.
Returns
NC_NOERR No error.
NC_EBADID Bad ncid.
NC_ENOTVAR Invalid variable ID.
NC_EINVAL Invalid input

Definition at line 416 of file dv2i.c.

◆ nc_inq_rec()

int nc_inq_rec ( int  ncid,
size_t *  nrecvarsp,
int *  recvarids,
size_t *  recsizes 
)

Retrieves the number of record variables, the record variable ids, and the record size of each record variable. If any pointer to info to be returned is null, the associated information is not returned. Returns -1 on error.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 functions nc_inq_nvars(), nc_inq_unlimdim(), nc_inq_dim().

Parameters
ncidfile ID
nrecvarsppointer that will get the number of record variables in the file.
recvaridspointer to array that will get the variable IDs of all variables that use the record dimension.
recsizespointer to array that will dimension size of the record dimension for each variable.
Returns
NC_NOERR No error.
NC_EBADID Bad ncid.
NC_ENOTVAR Invalid variable ID.
NC_EINVAL Invalid input

Definition at line 289 of file dv2i.c.

◆ nc_put_rec()

int nc_put_rec ( int  ncid,
size_t  recnum,
void *const *  datap 
)

Write one record's worth of data, except don't write to variables for which the address of the data to be written is NULL. Return -1 on error. This is the same as the ncrecput() in the library, except that can handle errors better.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_put_vara().

Parameters
ncidfile ID
recnumthe record number to write.
datappointer to one record's worth of data for all variables.
Returns
NC_NOERR No error.
NC_EBADID Bad ncid.
NC_ENOTVAR Invalid variable ID.
NC_EINVAL Invalid input

Definition at line 355 of file dv2i.c.

◆ ncabort()

int ncabort ( int  ncid)

Abort defining a file.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_abort().

Parameters
ncidfile ID
Returns
0 for success, -1 for failure.

Definition at line 700 of file dv2i.c.

◆ ncattcopy()

int ncattcopy ( int  ncid_in,
int  varid_in,
const char *  name,
int  ncid_out,
int  varid_out 
)

Copy an attribute.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_att_int(), etc.

Parameters
ncid_infile ID to copy from.
varid_inthe variable ID or NC_GLOBAL to copy from.
namethe name of the attribute.
ncid_outfile ID to copy to.
varid_outthe variable ID or NC_GLOBAL to copy to.
Returns
0 for success or -1 for failure.

Definition at line 1511 of file dv2i.c.

◆ ncattdel()

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

Delete an attribute.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_delete_att().

Parameters
ncidfile ID
varidthe variable ID.
namethe attribute name.
Returns
1 for success or -1 for failure.

Definition at line 1604 of file dv2i.c.

◆ ncattget()

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

Read an attribute.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_att_int(), etc.

Parameters
ncidfile ID.
varidthe variable ID or NC_GLOBAL.
namethe name of the attribute.
valuepointer that will get the attribute data.
Returns
1 for success or -1 for failure.

Definition at line 1479 of file dv2i.c.

◆ ncattinq()

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

Learn about an attribute.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_inq_att().

Parameters
ncidfile ID
varidthe variable ID.
namethe name of the attribute.
datatypepointer that will get data type.
lenpointer that will get length.
Returns
1 for success or -1 for failure. (That's a delightful artifact of a by-gone era of C programming, isn't it?)

Definition at line 1440 of file dv2i.c.

◆ ncattname()

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

Learn attribute name from its number.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_inq_attname().

Parameters
ncidfile ID
varidthe variable ID.
attnumthe number of the attribute.
namethe name of the attribute.
Returns
attnum for success or -1 for failure.

Definition at line 1543 of file dv2i.c.

◆ ncattput()

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

Write an attribute.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_put_att_int(), etc.

Parameters
ncidfile ID
varidthe variable ID or NC_GLOBAL.
namethe name of the attribute.
datatypethe type of the attribute.
lenthe length of the attribute.
valuethe attribute value.
Returns
dimid or -1 for failure.

Definition at line 1405 of file dv2i.c.

◆ ncattrename()

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

Rename an attribute.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_rename_att().

Parameters
ncidfile ID
varidthe variable ID.
namethe attribute name.
newnamethe new name.
Returns
1 for success or -1 for failure.

Definition at line 1574 of file dv2i.c.

◆ ncclose()

int ncclose ( int  ncid)

Close a file.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_close().

Parameters
ncidfile ID
Returns
0 for success, -1 for failure.

Definition at line 606 of file dv2i.c.

◆ nccreate()

int nccreate ( const char *  path,
int  cmode 
)

Create a netCDF file.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_create().

Parameters
pathpath and filename of the file to be created.
cmodesee nc_create() for full discussion of the create mode.
Returns
the ncid of the created file.

Definition at line 511 of file dv2i.c.

◆ ncdimdef()

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

Define a dimension.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_def_dim().

Parameters
ncidfile ID
namename of dimension.
lengthlength of the dimension, NC_UNLIMITED for a record dimension.
Returns
dimid or -1 for failure.

Definition at line 726 of file dv2i.c.

◆ ncdimid()

int ncdimid ( int  ncid,
const char *  name 
)

Find dimension ID from name.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_inq_dimid().

Parameters
ncidfile ID
namename of dimension.
Returns
dimid or -1 for failure.

Definition at line 761 of file dv2i.c.

◆ ncdiminq()

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

Learn about a dimension.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_inq_dim().

Parameters
ncidfile ID
dimidthe dimension ID to learn about
namepointer that will get name of dimension.
lengthpointer that will get length of dimension.
Returns
dimid or -1 for failure.

Definition at line 788 of file dv2i.c.

◆ ncdimrename()

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

Rename a dimension.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_rename_dim().

Parameters
ncidfile ID
dimidthe dimension ID.
namethe new name.
Returns
dimid or -1 for failure.

Definition at line 825 of file dv2i.c.

◆ ncendef()

int ncendef ( int  ncid)

End define mode for file.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_enddef().

Parameters
ncidfile ID
Returns
0 for success, -1 for failure.

Definition at line 583 of file dv2i.c.

◆ ncinquire()

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

Learn about a file.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_inq().

Parameters
ncidfile ID
ndimspointer that will get number of dimensions.
nvarspointer that will get number of variables.
nattspointer that will get number of global attributes.
recdimpointer that will get dimension ID of record dimension, or -1 if there is no record dimension.
Returns
0 for success, -1 for failure.

Definition at line 635 of file dv2i.c.

◆ ncopen()

int ncopen ( const char *  path,
int  mode 
)

Open a netCDF file.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_open().

Parameters
pathpath and filename of the file to be created.
modesee nc_open() for full discussion of the open mode.
Returns
the ncid of the created file.

Definition at line 536 of file dv2i.c.

◆ ncrecget()

int ncrecget ( int  ncid,
long  recnum,
void **  datap 
)

Read one record's worth of data, except don't read from variables for which the address of the data to be read is null. Return -1 on error. This is the same as the nc_get_rec(), with poorer error handling.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_vara().

Parameters
ncidfile ID
recnumthe record number to read.
datappointer memory to hold one record's worth of data for all variables.
Returns
0 for success, -1 for error.

Definition at line 1723 of file dv2i.c.

◆ ncrecinq()

int ncrecinq ( int  ncid,
int *  nrecvars,
int *  recvarids,
long *  recsizes 
)

Learn record variables and the lengths of the record dimension.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 functions nc_inq_var()/nc_inq_dim().

Parameters
ncidfile ID
nrecvarspointer that will get number of record variables.
recvaridspointer that will get array of record variable IDs.
recsizespointer that will get array of record dimension length.
Returns
oldmode for success or -1 for failure.

Definition at line 1666 of file dv2i.c.

◆ ncrecput()

int ncrecput ( int  ncid,
long  recnum,
void *const *  datap 
)

Write one record's worth of data, except don't write to variables for which the address of the data to be written is NULL. Return -1 on error. This is the same as the nc_put_rec(), but with poorer error handling.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_put_vara().

Parameters
ncidfile ID
recnumthe record number to write.
datappointer to one record's worth of data for all variables.
Returns
0 for success, -1 for error.

Definition at line 1754 of file dv2i.c.

◆ ncredef()

int ncredef ( int  ncid)

Put file in define mode.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_redef().

Parameters
ncidfile ID
Returns
0 for success, -1 for failure.

Definition at line 560 of file dv2i.c.

◆ ncsetfill()

int ncsetfill ( int  ncid,
int  fillmode 
)

Set the fill mode.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_set_fill().

Parameters
ncidfile ID
fillmodeNC_FILL or NC_NOFILL.
Returns
oldmode for success or -1 for failure.

Definition at line 1636 of file dv2i.c.

◆ ncsync()

int ncsync ( int  ncid)

Sync a file.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_sync().

Parameters
ncidfile ID
Returns
0 for success, -1 for failure.

Definition at line 677 of file dv2i.c.

◆ ncvardef()

int ncvardef ( int  ncid,
const char *  name,
nc_type  datatype,
int  ndims,
const int *  dim 
)

Define a variable.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_def_var().

Parameters
ncidfile ID
namethe name of the variable.
datatypethe data type of the variable.
ndimsthe number of dimensions.
dimarray of dimension IDs.
Returns
varid or -1 for failure.

Definition at line 856 of file dv2i.c.

◆ ncvarget()

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

Read some data.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_vara().

Parameters
ncidfile ID
varidthe variable ID.
startpointer to array of start values.
countpointer to array of count values.
valuepointer to data.
Returns
0 for success or -1 for failure.

Definition at line 1082 of file dv2i.c.

◆ ncvarget1()

int ncvarget1 ( int  ncid,
int  varid,
const long *  index,
void *  value 
)

Read 1 data value.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_var1().

Parameters
ncidfile ID
varidthe variable ID.
indexpointer to array of index values.
valuepointer that will get data.
Returns
0 for success or -1 for failure.

Definition at line 1002 of file dv2i.c.

◆ ncvargetg()

int ncvargetg ( int  ncid,
int  varid,
const long *  start,
const long *  count,
const long *  stride,
const long *  map,
void *  value 
)

Read mapped data.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_varm().

Parameters
ncidfile ID
varidthe variable ID.
startpointer to array of start values.
countpointer to array of count values.
stridepointer to array of stride values.
mappointer to array of map values.
valuepointer to data.
Returns
0 for success or -1 for failure.

Definition at line 1304 of file dv2i.c.

◆ ncvargets()

int ncvargets ( int  ncid,
int  varid,
const long *  start,
const long *  count,
const long *  stride,
void *  value 
)

Read strided data.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_vars().

Parameters
ncidfile ID
varidthe variable ID.
startpointer to array of start values.
countpointer to array of count values.
stridepointer to array of stride values.
valuepointer to data.
Returns
0 for success or -1 for failure.

Definition at line 1178 of file dv2i.c.

◆ ncvarid()

int ncvarid ( int  ncid,
const char *  name 
)

Learn a variable ID from the name.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_inq_varid().

Parameters
ncidfile ID
namethe name of the variable.
Returns
varid or -1 for failure.

Definition at line 887 of file dv2i.c.

◆ ncvarinq()

int ncvarinq ( int  ncid,
int  varid,
char *  name,
nc_type datatype,
int *  ndims,
int *  dim,
int *  natts 
)

Learn about a variable.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_inq_var().

Parameters
ncidfile ID
varidthe variable ID.
namepointer to array of char that will get name of variable.
datatypepointer that will get variable data type.
ndimspointer that will get number of dimensions.
dimpointer to array that will get dimension IDs.
nattspointer that will get number of variable attributes.
Returns
varid or -1 for failure.

Definition at line 920 of file dv2i.c.

◆ ncvarput()

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

Write some data.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_put_vara().

Parameters
ncidfile ID
varidthe variable ID.
startpointer to array of start values.
countpointer to array of count values.
valuepointer to data.
Returns
0 for success or -1 for failure.

Definition at line 1040 of file dv2i.c.

◆ ncvarput1()

int ncvarput1 ( int  ncid,
int  varid,
const long *  index,
const void *  value 
)

Write 1 data value.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_put_var1().

Parameters
ncidfile ID
varidthe variable ID.
indexpointer to array of index values.
valuepointer to data.
Returns
0 for success or -1 for failure.

Definition at line 965 of file dv2i.c.

◆ ncvarputg()

int ncvarputg ( int  ncid,
int  varid,
const long *  start,
const long *  count,
const long *  stride,
const long *  map,
const void *  value 
)

Write mapped data.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_get_varm().

Parameters
ncidfile ID
varidthe variable ID.
startpointer to array of start values.
countpointer to array of count values.
stridepointer to array of stride values.
mappointer to array of map values.
valuepointer to data.
Returns
0 for success or -1 for failure.

Definition at line 1231 of file dv2i.c.

◆ ncvarputs()

int ncvarputs ( int  ncid,
int  varid,
const long *  start,
const long *  count,
const long *  stride,
const void *  value 
)

Write strided data.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_put_vars().

Parameters
ncidfile ID
varidthe variable ID.
startpointer to array of start values.
countpointer to array of count values.
stridepointer to array of stride values.
valuepointer to data.
Returns
0 for success or -1 for failure.

Definition at line 1125 of file dv2i.c.

◆ ncvarrename()

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

Rename a variable.

This is part of the legacy V2 API of netCDF. New code should be written with the V3 API. See V3 function nc_rename_var().

Parameters
ncidfile ID
varidthe variable ID.
namethe new name.
Returns
varid or -1 for failure.

Definition at line 1373 of file dv2i.c.