Loading...
Searching...
No Matches
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. More...

## Functions

void | nc_advise (const char *routine_name, int err, const char *fmt,...)
| Show an error message and exit (based on ncopts).
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.
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.
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.
int | ncabort (int ncid)
| Abort defining a file.
int | ncattcopy (int ncid_in, int varid_in, const char *name, int ncid_out, int varid_out)
| Copy an attribute.
int | ncattdel (int ncid, int varid, const char *name)
| Delete an attribute.
int | ncattget (int ncid, int varid, const char *name, void *value)
| Read an attribute.
int | ncattinq (int ncid, int varid, const char *name, nc_type *datatype, int *len)
| Learn about an attribute.
int | ncattname (int ncid, int varid, int attnum, char *name)
| Learn attribute name from its number.
int | ncattput (int ncid, int varid, const char *name, nc_type datatype, int len, const void *value)
| Write an attribute.
int | ncattrename (int ncid, int varid, const char *name, const char *newname)
| Rename an attribute.
int | ncclose (int ncid)
| Close a file.
int | nccreate (const char *path, int cmode)
| Create a netCDF file.
int | ncdimdef (int ncid, const char *name, long length)
| Define a dimension.
int | ncdimid (int ncid, const char *name)
| Find dimension ID from name.
int | ncdiminq (int ncid, int dimid, char *name, long *length)
| Learn about a dimension.
int | ncdimrename (int ncid, int dimid, const char *name)
| Rename a dimension.
int | ncendef (int ncid)
| End define mode for file.
int | ncinquire (int ncid, int *ndims, int *nvars, int *natts, int *recdim)
| Learn about a file.
int | ncopen (const char *path, int mode)
| Open a netCDF file.
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.
int | ncrecinq (int ncid, int *nrecvars, int *recvarids, long *recsizes)
| Learn record variables and the lengths of the record dimension.
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.
int | ncredef (int ncid)
| Put file in define mode.
int | ncsetfill (int ncid, int fillmode)
| Set the fill mode.
int | ncsync (int ncid)
| Sync a file.
int | ncvardef (int ncid, const char *name, nc_type datatype, int ndims, const int *dim)
| Define a variable.
int | ncvarget (int ncid, int varid, const long *start, const long *count, void *value)
| Read some data.
int | ncvarget1 (int ncid, int varid, const long *index, void *value)
| Read 1 data value.
int | ncvargetg (int ncid, int varid, const long *start, const long *count, const long *stride, const long *map, void *value)
| Read mapped data.
int | ncvargets (int ncid, int varid, const long *start, const long *count, const long *stride, void *value)
| Read strided data.
int | ncvarid (int ncid, const char *name)
| Learn a variable ID from the name.
int | ncvarinq (int ncid, int varid, char *name, nc_type *datatype, int *ndims, int *dim, int *natts)
| Learn about a variable.
int | ncvarput (int ncid, int varid, const long *start, const long *count, const void *value)
| Write some data.
int | ncvarput1 (int ncid, int varid, const long *index, const void *value)
| Write 1 data value.
int | ncvarputg (int ncid, int varid, const long *start, const long *count, const long *stride, const long *map, const void *value)
| Write mapped data.
int | ncvarputs (int ncid, int varid, const long *start, const long *count, const long *stride, const void *value)
| Write strided data.
int | ncvarrename (int ncid, int varid, const char *name)
| Rename a variable.

## 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 |
  err | error code
  fmt | pointer 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

  ncid | file ID
  recnum | the record number to read.
  datap | pointer 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

  ncid | file ID
  nrecvarsp | pointer that will get the number of record variables in the file.
  recvarids | pointer to array that will get the variable IDs of all variables that use the record dimension.
  recsizes | pointer 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

  ncid | file ID
  recnum | the record number to write.
  datap | pointer 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

  ncid | file 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_in | file ID to copy from.
  varid_in | the variable ID or NC_GLOBAL to copy from.
  name | the name of the attribute.
  ncid_out | file ID to copy to.
  varid_out | the 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

  ncid | file ID
  varid | the variable ID.
  name | the 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

  ncid | file ID.
  varid | the variable ID or NC_GLOBAL.
  name | the name of the attribute.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  name | the name of the attribute.
  datatype | pointer that will get data type.
  len | pointer 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

  ncid | file ID
  varid | the variable ID.
  attnum | the number of the attribute.
  name | the 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

  ncid | file ID
  varid | the variable ID or NC_GLOBAL.
  name | the name of the attribute.
  datatype | the type of the attribute.
  len | the length of the attribute.
  value | the 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

  ncid | file ID
  varid | the variable ID.
  name | the attribute name.
  newname | the 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

  ncid | file 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

  path | path and filename of the file to be created.
  cmode | see 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

  ncid | file ID
  name | name of dimension.
  length | length 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

  ncid | file ID
  name | name 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

  ncid | file ID
  dimid | the dimension ID to learn about
  name | pointer that will get name of dimension.
  length | pointer 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

  ncid | file ID
  dimid | the dimension ID.
  name | the 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

  ncid | file 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

  ncid | file ID
  ndims | pointer that will get number of dimensions.
  nvars | pointer that will get number of variables.
  natts | pointer that will get number of global attributes.
  recdim | pointer 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

  path | path and filename of the file to be created.
  mode | see 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

  ncid | file ID
  recnum | the record number to read.
  datap | pointer 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

  ncid | file ID
  nrecvars | pointer that will get number of record variables.
  recvarids | pointer that will get array of record variable IDs.
  recsizes | pointer 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

  ncid | file ID
  recnum | the record number to write.
  datap | pointer 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

  ncid | file 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

  ncid | file ID
  fillmode | NC_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

  ncid | file 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

  ncid | file ID
  name | the name of the variable.
  datatype | the data type of the variable.
  ndims | the number of dimensions.
  dim | array 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

  ncid | file ID
  varid | the variable ID.
  start | pointer to array of start values.
  count | pointer to array of count values.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  index | pointer to array of index values.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  start | pointer to array of start values.
  count | pointer to array of count values.
  stride | pointer to array of stride values.
  map | pointer to array of map values.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  start | pointer to array of start values.
  count | pointer to array of count values.
  stride | pointer to array of stride values.
  value | pointer 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

  ncid | file ID
  name | the 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

  ncid | file ID
  varid | the variable ID.
  name | pointer to array of char that will get name of variable.
  datatype | pointer that will get variable data type.
  ndims | pointer that will get number of dimensions.
  dim | pointer to array that will get dimension IDs.
  natts | pointer 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

  ncid | file ID
  varid | the variable ID.
  start | pointer to array of start values.
  count | pointer to array of count values.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  index | pointer to array of index values.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  start | pointer to array of start values.
  count | pointer to array of count values.
  stride | pointer to array of stride values.
  map | pointer to array of map values.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  start | pointer to array of start values.
  count | pointer to array of count values.
  stride | pointer to array of stride values.
  value | pointer 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

  ncid | file ID
  varid | the variable ID.
  name | the new name.

Returns
  varid or -1 for failure.

Definition at line 1373 of file dv2i.c.