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
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.