NetCDF-4 added support for hierarchical groups within netCDF datasets. More...

Functions
int	nc_def_grp (int parent_ncid, const char name, int new_ncid)
	Define a new group. More...

int	nc_inq_dimids (int ncid, int ndims, int dimids, int include_parents)
	Retrieve a list of dimension ids associated with a group. More...

int	nc_inq_grp_full_ncid (int ncid, const char full_name, int grp_ncid)
	Get the full ncid given a group name. More...

int	nc_inq_grp_ncid (int ncid, const char grp_name, int grp_ncid)
	Get a group ncid given the group name. More...

int	nc_inq_grp_parent (int ncid, int *parent_ncid)
	Get the ID of the parent based on a group ID. More...

int	nc_inq_grpname (int ncid, char *name)
	Get the name of a group given an ID. More...

int	nc_inq_grpname_full (int ncid, size_t lenp, char full_name)
	Get the full path/groupname of a group/subgroup given an ID. More...

int	nc_inq_grpname_len (int ncid, size_t *lenp)
	Get the length of a group name given an ID. More...

int	nc_inq_grps (int ncid, int numgrps, int ncids)
	Get a list of groups or subgroups from a file or groupID. More...

int	nc_inq_ncid (int ncid, const char name, int grp_ncid)
	Return the group ID for a group given the name. More...

int	nc_inq_typeids (int ncid, int ntypes, int typeids)
	Retrieve a list of types associated with a group. More...

int	nc_inq_varids (int ncid, int nvars, int varids)
	Get a list of varids associated with a group given a group ID. More...

int	nc_rename_grp (int grpid, const char *name)
	Rename a group. More...

int	nc_show_metadata (int ncid)
	Print the metadata for a file. More...

Detailed Description

NetCDF-4 added support for hierarchical groups within netCDF datasets.

Groups are identified with a ncid, which identifies both the open file, and the group within that file. When a file is opened with nc_open or nc_create, the ncid for the root group of that file is provided. Using that as a starting point, users can add new groups, or list and navigate existing groups or rename a group.

All netCDF calls take a ncid which determines where the call will take its action. For example, the nc_def_var function takes a ncid as its first parameter. It will create a variable in whichever group its ncid refers to. Use the root ncid provided by nc_create or nc_open to create a variable in the root group. Or use nc_def_grp to create a group and use its ncid to define a variable in the new group.

Variable are only visible in the group in which they are defined. The same applies to attributes. “Global” attributes are associated with the group whose ncid is used.

Dimensions are visible in their groups, and all child groups.

Group operations are only permitted on netCDF-4 files - that is, files created with the HDF5 flag in nc_create(). Groups are not compatible with the netCDF classic data model, so files created with the NC_CLASSIC_MODEL file cannot contain groups (except the root group).

Encoding both the open file id and group id in a single integer currently limits the number of groups per netCDF-4 file to no more than 32767. Similarly, the number of simultaneously open netCDF-4 files in one program context is limited to 32767.

Function Documentation

◆ nc_def_grp()

int nc_def_grp	(	int	parent_ncid,
		const char *	name,
		int *	new_ncid
	)

Define a new group.

The function nc_def_grp() adds a new group to an open netCDF dataset in define mode. It returns (as an argument) a group id, given the parent ncid and the name of the group.

A group may be a top-level group if it is passed the ncid of the file, or a sub-group if passed the ncid of an existing group.

Parameters

[in]	parent_ncid	The ncid of the parent for the group.
[in]	name	Name of the new group.
[out]	new_ncid	Pointer to memory to hold the new ncid.

Returns: Error code or NC_NOERR for no error.

Return values

NC_NOERR	No error.
NC_ENOTNC4	Not an nc4 file.
NC_ENOTINDEFINE	Not in define mode.
NC_ESTRICTNC3	Not permissible in nc4 classic mode.
NC_EPERM	Write to read only.
NC_ENOMEM	Memory allocation (malloc) failure.
NC_ENAMEINUSE	String match to name in use.

Example

Here is an example using nc_def_grp() to create a new group.

#include <netcdf.h>
...
int status, ncid, grpid, latid, recid;
...

Definition at line 268 of file dgroup.c.

◆ nc_inq_dimids()

int nc_inq_dimids	(	int	ncid,
		int *	ndims,
		int *	dimids,
		int	include_parents
	)

Retrieve a list of dimension ids associated with a group.

Parameters

[in]	ncid	The ncid of the group in question.
[out]	ndims	Pointer to memory to contain the number of dimids associated with the group.
[out]	dimids	Pointer to memory to contain the number of dimensions associated with the group.
[in]	include_parents	If non-zero, parent groups are also traversed.

Returns: Error code or NC_NOERR for no error.

Definition at line 205 of file dgroup.c.

◆ nc_inq_grp_full_ncid()

int nc_inq_grp_full_ncid	(	int	ncid,
		const char *	full_name,
		int *	grp_ncid
	)

Get the full ncid given a group name.

Parameters

[in]	ncid	The ncid of the file.
[in]	full_name	The full name of the group in question.
[out]	grp_ncid	Pointer to memory to hold the identifier of the full group in question.

Returns: Error code or NC_NOERR for no error.

Definition at line 169 of file dgroup.c.

◆ nc_inq_grp_ncid()

int nc_inq_grp_ncid	(	int	ncid,
		const char *	grp_name,
		int *	grp_ncid
	)

Get a group ncid given the group name.

Parameters

[in]	ncid	The ncid of the file.
[in]	grp_name	The name of the group in question.
[out]	grp_ncid	Pointer to memory to hold the identifier of the group in question.

Returns: Error code or NC_NOERR for no error.

Note: {This has same semantics as nc_inq_ncid}

Definition at line 155 of file dgroup.c.

◆ nc_inq_grp_parent()

int nc_inq_grp_parent	(	int	ncid,
		int *	parent_ncid
	)

Get the ID of the parent based on a group ID.

Parameters

[in]	ncid	The ncid of the group in question.
[out]	parent_ncid	Pointer to memory to hold the identifier of the parent of the group in question.

Returns: Error code or NC_NOERR for no error.

Definition at line 136 of file dgroup.c.

◆ nc_inq_grpname()

int nc_inq_grpname	(	int	ncid,
		char *	name
	)

Get the name of a group given an ID.

Parameters

[in]	ncid	The ncid of the file or parent group.
[out]	name	The name of the group associated with the id.

Returns: Error code or NC_NOERR for no error.

Definition at line 88 of file dgroup.c.

◆ nc_inq_grpname_full()

int nc_inq_grpname_full	(	int	ncid,
		size_t *	lenp,
		char *	full_name
	)

Get the full path/groupname of a group/subgroup given an ID.

Parameters

[in]	ncid	The ncid of the file or parent group.
[out]	lenp	Pointer to memory to hold the length of the full name.
[out]	full_name	Pointer to memory to hold the full name of the group including root/parent.

Returns: Error code or NC_NOERR for no error.

Definition at line 106 of file dgroup.c.

◆ nc_inq_grpname_len()

int nc_inq_grpname_len	(	int	ncid,
		size_t *	lenp
	)

Get the length of a group name given an ID.

Parameters

[in]	ncid	The ncid of the group in question.
[out]	lenp	Pointer to memory to hold the length of the name of the group in question.

Returns: Error code or NC_NOERR for no error.

Definition at line 122 of file dgroup.c.

◆ nc_inq_grps()

int nc_inq_grps	(	int	ncid,
		int *	numgrps,
		int *	ncids
	)

Get a list of groups or subgroups from a file or groupID.

Parameters

[in]	ncid	The ncid of the file or parent group.
[out]	numgrps	Pointer to memory to hold the number of groups.
[out]	ncids	Pointer to memory to hold the ncid for each group.

Returns: Error code or NC_NOERR for no error.

Definition at line 73 of file dgroup.c.

◆ nc_inq_ncid()

int nc_inq_ncid	(	int	ncid,
		const char *	name,
		int *	grp_ncid
	)

Return the group ID for a group given the name.

Parameters

[in]	ncid	A valid file or group ncid.
[in]	name	The name of the group you are querying.
[out]	grp_ncid	Pointer to memory to hold the group ncid.

Returns: Error code or NC_NOERR or no error.

Definition at line 56 of file dgroup.c.

◆ nc_inq_typeids()

int nc_inq_typeids	(	int	ncid,
		int *	ntypes,
		int *	typeids
	)

Retrieve a list of types associated with a group.

Parameters

[in]	ncid	The ncid for the group in question.
[out]	ntypes	Pointer to memory to hold the number of typeids contained by the group in question.
[out]	typeids	Pointer to memory to hold the typeids contained by the group in question.

Returns: Error code or NC_NOERR for no error.

Definition at line 223 of file dgroup.c.

◆ nc_inq_varids()

int nc_inq_varids	(	int	ncid,
		int *	nvars,
		int *	varids
	)

Get a list of varids associated with a group given a group ID.

Parameters

[in]	ncid	The ncid of the group in question.
[out]	nvars	Pointer to memory to hold the number of variables in the group in question.
[out]	varids	Pointer to memory to hold the variable ids contained by the group in question.

Returns: Error code or NC_NOERR for no error.

Definition at line 187 of file dgroup.c.

◆ nc_rename_grp()

int nc_rename_grp	(	int	grpid,
		const char *	name
	)

Rename a group.

Parameters

[in]	grpid	The ID for the group in question.
[in]	name	The new name for the group.

Returns: Error code or NC_NOERR for no error.

Definition at line 284 of file dgroup.c.

◆ nc_show_metadata()

int nc_show_metadata ( int ncid )

Print the metadata for a file.

Parameters

[in] ncid The ncid of an open file.

Returns: Error code or NC_NOERR for no error.

Definition at line 299 of file dgroup.c.

Functions

Detailed Description

Function Documentation

◆ nc_def_grp()

Example

◆ nc_inq_dimids()

◆ nc_inq_grp_full_ncid()

◆ nc_inq_grp_ncid()

◆ nc_inq_grp_parent()

◆ nc_inq_grpname()

◆ nc_inq_grpname_full()

◆ nc_inq_grpname_len()

◆ nc_inq_grps()

◆ nc_inq_ncid()

◆ nc_inq_typeids()

◆ nc_inq_varids()

◆ nc_rename_grp()

◆ nc_show_metadata()