mirror of
https://github.com/Unidata/netcdf-c.git
synced 2025-03-19 17:30:27 +08:00
more internal documentation
This commit is contained in:
Ed Hartnett
parent
11e3e81489
commit
fec74e18ef
@ -795,6 +795,7 @@ INPUT = \
|
||||
@abs_top_srcdir@/libsrc4/nc4type.c \
|
||||
@abs_top_srcdir@/libsrc4/nc4grp.c \
|
||||
@abs_top_srcdir@/libsrc4/ncfunc.c \
|
||||
@abs_top_srcdir@/libsrc4/nc4dim.c \
|
||||
@abs_top_srcdir@/examples/C/simple_xy_wr.c \
|
||||
@abs_top_srcdir@/examples/C/simple_xy_rd.c \
|
||||
@abs_top_srcdir@/examples/C/sfc_pres_temp_wr.c \
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
134
libsrc4/nc4dim.c
134
libsrc4/nc4dim.c
@ -1,22 +1,34 @@
|
||||
/*
|
||||
|
||||
This file is part of netcdf-4, a netCDF-like interface for HDF5, or a
|
||||
HDF5 backend for netCDF, depending on your point of view.
|
||||
|
||||
This file handles the nc4 dimension functions.
|
||||
|
||||
Copyright 2003-5, University Corporation for Atmospheric Research. See
|
||||
the COPYRIGHT file for copying and redistribution conditions.
|
||||
|
||||
$Id: nc4dim.c,v 1.41 2010/05/25 17:54:23 dmh Exp $
|
||||
/**
|
||||
* @file
|
||||
* @internal This file is part of netcdf-4, a netCDF-like interface
|
||||
* for HDF5, or a HDF5 backend for netCDF, depending on your point of
|
||||
* view.
|
||||
*
|
||||
* This file handles the nc4 dimension functions.
|
||||
*
|
||||
* Copyright 2003-5, University Corporation for Atmospheric Research. See
|
||||
* the COPYRIGHT file for copying and redistribution conditions.
|
||||
*
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
|
||||
#include "nc4internal.h"
|
||||
#include "nc4dispatch.h"
|
||||
|
||||
/* Netcdf-4 files might have more than one unlimited dimension, but
|
||||
return the first one anyway. */
|
||||
/* Note that this code is inconsistent with nc_inq */
|
||||
/**
|
||||
* @internal Netcdf-4 files might have more than one unlimited
|
||||
* dimension, but return the first one anyway.
|
||||
*
|
||||
* @note that this code is inconsistent with nc_inq
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param unlimdimidsp Pointer that gets ID of first unlimited
|
||||
* dimension, or -1.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int
|
||||
NC4_inq_unlimdim(int ncid, int *unlimdimidp)
|
||||
{
|
||||
@ -52,8 +64,28 @@ NC4_inq_unlimdim(int ncid, int *unlimdimidp)
|
||||
return NC_NOERR;
|
||||
}
|
||||
|
||||
/* Dimensions are defined in attributes attached to the appropriate
|
||||
group in the data file. */
|
||||
/**
|
||||
* @internal Dimensions are defined in attributes attached to the
|
||||
* appropriate group in the data file.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param name Name of the new dimension.
|
||||
* @param len Length of the new dimension.
|
||||
* @param idp Pointer that gets the ID of the new dimension. Ignored
|
||||
* if NULL.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_EMAXNAME Name is too long.
|
||||
* @return ::NC_EBADNAME Name breaks netCDF name rules.
|
||||
* @return ::NC_EINVAL Invalid input.
|
||||
* @return ::NC_EPERM Read-only file.
|
||||
* @return ::NC_EUNLIMIT Only one unlimited dim for classic model.
|
||||
* @return ::NC_ENOTINDEFINE Not in define mode.
|
||||
* @return ::NC_EDIMSIZE Dim length too large.
|
||||
* @return ::NC_ENAMEINUSE Name already in use in group.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int
|
||||
NC4_def_dim(int ncid, const char *name, size_t len, int *idp)
|
||||
{
|
||||
@ -135,7 +167,18 @@ NC4_def_dim(int ncid, const char *name, size_t len, int *idp)
|
||||
return retval;
|
||||
}
|
||||
|
||||
/* Given dim name, find its id. */
|
||||
/**
|
||||
* @internal Given dim name, find its id.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param name Name of the dimension to find.
|
||||
* @param idp Pointer that gets dimension ID.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_EBADDIM Dimension not found.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int
|
||||
NC4_inq_dimid(int ncid, const char *name, int *idp)
|
||||
{
|
||||
@ -176,9 +219,21 @@ NC4_inq_dimid(int ncid, const char *name, int *idp)
|
||||
return NC_EBADDIM;
|
||||
}
|
||||
|
||||
/* Find out name and len of a dim. For an unlimited dimension, the
|
||||
length is the largest length so far written. If the name of lenp
|
||||
pointers are NULL, they will be ignored. */
|
||||
/**
|
||||
* @internal Find out name and len of a dim. For an unlimited
|
||||
* dimension, the length is the largest length so far written. If the
|
||||
* name of lenp pointers are NULL, they will be ignored.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param dimid Dimension ID.
|
||||
* @param name Pointer that gets name of the dimension.
|
||||
* @param lenp Pointer that gets length of dimension.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_EDIMSIZE Dimension length too large.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int
|
||||
NC4_inq_dim(int ncid, int dimid, char *name, size_t *lenp)
|
||||
{
|
||||
@ -234,7 +289,25 @@ NC4_inq_dim(int ncid, int dimid, char *name, size_t *lenp)
|
||||
return ret;
|
||||
}
|
||||
|
||||
/* Rename a dimension, for those who like to prevaricate. */
|
||||
/**
|
||||
* @internal Rename a dimension, for those who like to prevaricate.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param dimid Dimension ID.
|
||||
* @param name New dimension name.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_EHDFERR HDF5 returned error.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_EINVAL Name must be provided.
|
||||
* @return ::NC_ENAMEINUSE Name is already in use in group.
|
||||
* @return ::NC_EMAXNAME Name is too long.
|
||||
* @return ::NC_EBADDIM Dimension not found.
|
||||
* @return ::NC_EBADNAME Name breaks netCDF name rules.
|
||||
* @return ::NC_EDIMMETA Unable to delete HDF5 dataset.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int
|
||||
NC4_rename_dim(int ncid, int dimid, const char *name)
|
||||
{
|
||||
@ -339,10 +412,21 @@ NC4_rename_dim(int ncid, int dimid, const char *name)
|
||||
return NC_NOERR;
|
||||
}
|
||||
|
||||
/* Returns an array of unlimited dimension ids.The user can get the
|
||||
number of unlimited dimensions by first calling this with NULL for
|
||||
the second pointer.
|
||||
*/
|
||||
/**
|
||||
* @internal Returns an array of unlimited dimension ids.The user can
|
||||
* get the number of unlimited dimensions by first calling this with
|
||||
* NULL for the second pointer.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param nunlimdimsp Pointer that gets the number of unlimited
|
||||
* dimensions. Ignored if NULL.
|
||||
* @param unlimdimidsp Pointer that gets arrray of unlimited dimension
|
||||
* ID. Ignored if NULL.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
NC4_inq_unlimdims(int ncid, int *nunlimdimsp, int *unlimdimidsp)
|
||||
{
|
||||
|
||||
@ -19,7 +19,13 @@
|
||||
* @internal Create a group. It's ncid is returned in the new_ncid
|
||||
* pointer.
|
||||
*
|
||||
* @param parent_ncid Parent group.
|
||||
* @param name Name of new group.
|
||||
* @param new_ncid Pointer that gets ncid for new group.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_ESTRICTNC3 Classic model in use for this file.
|
||||
* @return ::NC_ENOTNC4 Not a netCDF-4 file.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int
|
||||
@ -71,7 +77,14 @@ NC4_def_grp(int parent_ncid, const char *name, int *new_ncid)
|
||||
/**
|
||||
* @internal Rename a group.
|
||||
*
|
||||
* @param grpid Group ID.
|
||||
* @param name New name for group.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_ENOTNC4 Not a netCDF-4 file.
|
||||
* @return ::NC_EPERM File opened read-only.
|
||||
* @return ::NC_EBADGRPID Renaming root forbidden.
|
||||
* @return ::NC_EHDFERR HDF5 function returned error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int
|
||||
@ -145,6 +158,9 @@ NC4_rename_grp(int grpid, const char *name)
|
||||
* @internal Given an ncid and group name (NULL gets root group),
|
||||
* return the ncid of that group.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param name Pointer that gets name.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
@ -187,6 +203,8 @@ NC4_inq_ncid(int ncid, const char *name, int *grp_ncid)
|
||||
* @internal Given a location id, return the number of groups it
|
||||
* contains, and an array of their locids.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
@ -236,6 +254,9 @@ NC4_inq_grps(int ncid, int *numgrps, int *ncids)
|
||||
* @internal Given locid, find name of group. (Root group is named
|
||||
* "/".)
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param name Pointer that gets name.
|
||||
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
@ -268,6 +289,10 @@ NC4_inq_grpname(int ncid, char *name)
|
||||
* third parameter to get the length of the full path name. The length
|
||||
* will not include room for a null pointer.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @param lenp Pointer that gets length of full name.
|
||||
* @param full_name Pointer that gets name.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
@ -329,6 +354,7 @@ NC4_inq_grpname_full(int ncid, size_t *lenp, char *full_name)
|
||||
* wearing nut job would call this function with a NULL pointer for
|
||||
* parent_ncid - Russ Rew!!
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
@ -364,6 +390,7 @@ NC4_inq_grp_parent(int ncid, int *parent_ncid)
|
||||
/**
|
||||
* @internal Given a full name and ncid, find group ncid.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
@ -428,6 +455,7 @@ NC4_inq_grp_full_ncid(int ncid, const char *full_name, int *grp_ncid)
|
||||
/**
|
||||
* @internal Get a list of ids for all the variables in a group.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
@ -484,7 +512,10 @@ NC4_inq_varids(int ncid, int *nvars, int *varids)
|
||||
* ids. Integer comparison: returns negative if b > a and positive if
|
||||
* a > b.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @param a A pointer to an item to compare to b.
|
||||
* @param b A pointer to an item to compare to a.
|
||||
*
|
||||
* @return a - b
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
int int_cmp(const void *a, const void *b)
|
||||
@ -499,6 +530,8 @@ int int_cmp(const void *a, const void *b)
|
||||
* in a group, with or without any of its parents, depending on last
|
||||
* parameter.
|
||||
*
|
||||
* @param ncid File and group ID.
|
||||
|
||||
* @return ::NC_NOERR No error.
|
||||
* @author Ed Hartnett
|
||||
*/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user