netcdf.h

该压缩包里包含用于开发读写NC文件的链接库以及NetCDF文件格式的说明文档。

/*
 * Copyright 1993-2005 University Corporation for Atmospheric Research/Unidata
 * 
 * Portions of this software were developed by the Unidata Program at the 
 * University Corporation for Atmospheric Research.
 * 
 * Access and use of this software shall impose the following obligations
 * and understandings on the user. The user is granted the right, without
 * any fee or cost, to use, copy, modify, alter, enhance and distribute
 * this software, and any derivative works thereof, and its supporting
 * documentation for any purpose whatsoever, provided that this entire
 * notice appears in all copies of the software, derivative works and
 * supporting documentation.  Further, UCAR requests that the user credit
 * UCAR/Unidata in any publications that result from the use of this
 * software or in any product that includes this software. The names UCAR
 * and/or Unidata, however, may not be used in any advertising or publicity
 * to endorse or promote any products or commercial entity unless specific
 * written permission is obtained from UCAR/Unidata. The user also
 * understands that UCAR/Unidata is not obligated to provide the user with
 * any support, consulting, training or assistance of any kind with regard
 * to the use, operation and performance of this software nor to provide
 * the user with any updates, revisions, new versions or "bug fixes."
 * 
 * THIS SOFTWARE IS PROVIDED BY UCAR/UNIDATA "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL UCAR/UNIDATA BE LIABLE FOR ANY SPECIAL,
 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE ACCESS, USE OR PERFORMANCE OF THIS SOFTWARE.
 */
/* "$Id: netcdf.h,v 2.105 2006/02/01 19:00:27 ed Exp $" */

#ifndef _NETCDF_
#define _NETCDF_

#include <stddef.h> /* size_t, ptrdiff_t */
#include <errno.h>  /* netcdf functions sometimes return system errors */

#if defined(__cplusplus)
extern "C" {
#endif

/*
 *  The netcdf external data types
 */
typedef enum {
	NC_NAT =	0,	/* NAT = 'Not A Type' (c.f. NaN) */
	NC_BYTE =	1,	/* signed 1 byte integer */
	NC_CHAR =	2,	/* ISO/ASCII character */
	NC_SHORT =	3,	/* signed 2 byte integer */
	NC_INT =	4,	/* signed 4 byte integer */
	NC_FLOAT =	5,	/* single precision floating point number */
	NC_DOUBLE =	6	/* double precision floating point number */
} nc_type;


/*
 * 	Default fill values, used unless _FillValue attribute is set.
 * These values are stuffed into newly allocated space as appropriate.
 * The hope is that one might use these to notice that a particular datum
 * has not been set.
 */
#define NC_FILL_BYTE	((signed char)-127)
#define NC_FILL_CHAR	((char)0)
#define NC_FILL_SHORT	((short)-32767)
#define NC_FILL_INT	(-2147483647L)
#define NC_FILL_FLOAT	(9.9692099683868690e+36f) /* near 15 * 2^119 */
#define NC_FILL_DOUBLE	(9.9692099683868690e+36)


/*
 * The above values are defaults.
 * If you wish a variable to use a different value than the above
 * defaults, create an attribute with the same type as the variable
 * and the following reserved name. The value you give the attribute
 * will be used as the fill value for that variable.
 */
#define _FillValue	"_FillValue"
#define NC_FILL		0	/* argument to ncsetfill to clear NC_NOFILL */
#define NC_NOFILL	0x100	/* Don't fill data section an records */

/*
 * 'mode' flags for ncopen
 */
#define NC_NOWRITE	0	/* default is read only */
#define NC_WRITE    	0x1	/* read & write */

/*
 * 'mode' flags for nccreate
 */
#define NC_CLOBBER	0
#define NC_NOCLOBBER	0x4	/* Don't destroy existing file on create */
#define NC_64BIT_OFFSET 0x0200  /* Use large (64-bit) file offsets */

/*
 * 'mode' flags for nccreate and ncopen
 */
#define NC_SHARE	0x0800	/* Share updates, limit cacheing */
#define NC_STRICT_NC3  (0x8)

/* The following flag currently is ignored, but use in
 * nc_open() or nc_create() may someday support use of advisory
 * locking to prevent multiple writers from clobbering a file 
 */
#define NC_LOCK		0x0400	/* Use locking if available */

/*
 * Starting with version 3.6, there are different format netCDF
 * files. 4.0 instroduces the third one.
 */
#define NC_FORMAT_CLASSIC (1)
#define NC_FORMAT_64BIT   (2)
#define NC_FORMAT_NETCDF4 (3)
#define NC_FORMAT_NETCDF4_CLASSIC  (4) /* create netcdf-4 files, with NC_STRICT_NC3. */

/*
 * Let nc__create() or nc__open() figure out
 * as suitable chunk size.
 */
#define NC_SIZEHINT_DEFAULT 0

/*
 * In nc__enddef(), align to the chunk size.
 */
#define NC_ALIGN_CHUNK ((size_t)(-1))

/*
 * 'size' argument to ncdimdef for an unlimited dimension
 */
#define NC_UNLIMITED 0L

/*
 * attribute id to put/get a global attribute
 */
#define NC_GLOBAL -1

/* These are in support of the coordinate axis stuff. */
#define NC_NOAXISTYPE 0
#define NC_LATITUDE 1
#define NC_LONGITUDE 2
#define NC_GEOX 3
#define NC_GEOY 4
#define NC_GEOZ 5
#define NC_HEIGHT_UP 6
#define NC_HEIGHT_DOWN 7
#define NC_PRESSURE 8
#define NC_TIME 9
#define NC_RADAZ 10
#define NC_RADEL 11
#define NC_RADDIST 12

/*
 * These maximums are enforced by the interface, to facilitate writing
 * applications and utilities.  However, nothing is statically allocated to
 * these sizes internally.
 */
#define NC_MAX_DIMS	1024	 /* max dimensions per file */
#define NC_MAX_ATTRS	8192	 /* max global or per variable attributes */
#define NC_MAX_VARS	8192	 /* max variables per file */
#define NC_MAX_NAME	256	 /* max length of a name */
#define NC_MAX_VAR_DIMS	NC_MAX_DIMS /* max per variable dimensions */

/*
 * The netcdf version 3 functions all return integer error status.
 * These are the possible values, in addition to certain
 * values from the system errno.h.
 */

#define NC_ISSYSERR(err)	((err) > 0)

#define	NC_NOERR	0	/* No Error */

#define NC2_ERR         (-1)    /* Returned for all errors in the v2 API. */
#define	NC_EBADID	(-33)	/* Not a netcdf id */
#define	NC_ENFILE	(-34)	/* Too many netcdfs open */
#define	NC_EEXIST	(-35)	/* netcdf file exists && NC_NOCLOBBER */
#define	NC_EINVAL	(-36)	/* Invalid Argument */
#define	NC_EPERM	(-37)	/* Write to read only */
#define	NC_ENOTINDEFINE	(-38)	/* Operation not allowed in data mode */
#define	NC_EINDEFINE	(-39)	/* Operation not allowed in define mode */
#define	NC_EINVALCOORDS	(-40)	/* Index exceeds dimension bound */
#define	NC_EMAXDIMS	(-41)	/* NC_MAX_DIMS exceeded */
#define	NC_ENAMEINUSE	(-42)	/* String match to name in use */
#define NC_ENOTATT	(-43)	/* Attribute not found */
#define	NC_EMAXATTS	(-44)	/* NC_MAX_ATTRS exceeded */
#define NC_EBADTYPE	(-45)	/* Not a netcdf data type */
#define NC_EBADDIM	(-46)	/* Invalid dimension id or name */
#define NC_EUNLIMPOS	(-47)	/* NC_UNLIMITED in the wrong index */
#define	NC_EMAXVARS	(-48)	/* NC_MAX_VARS exceeded */
#define NC_ENOTVAR	(-49)	/* Variable not found */
#define NC_EGLOBAL	(-50)	/* Action prohibited on NC_GLOBAL varid */
#define NC_ENOTNC	(-51)	/* Not a netcdf file */
#define NC_ESTS        	(-52)	/* In Fortran, string too short */
#define NC_EMAXNAME    	(-53)	/* NC_MAX_NAME exceeded */
#define NC_EUNLIMIT    	(-54)	/* NC_UNLIMITED size already in use */
#define NC_ENORECVARS  	(-55)	/* nc_rec op when there are no record vars */
#define NC_ECHAR	(-56)	/* Attempt to convert between text & numbers */
#define NC_EEDGE	(-57)	/* Start+count exceeds dimension bound */
#define NC_ESTRIDE	(-58)	/* Illegal stride */
#define NC_EBADNAME	(-59)	/* Attribute or variable name
                                         contains illegal characters */
/* N.B. following must match value in ncx.h */
#define NC_ERANGE	(-60)	/* Math result not representable */
#define NC_ENOMEM	(-61)	/* Memory allocation (malloc) failure */

#define NC_EVARSIZE     (-62)   /* One or more variable sizes violate
				   format constraints */ 
#define NC_EDIMSIZE     (-63)   /* Invalid dimension size */
#define NC_ETRUNC       (-64)   /* File likely truncated or possibly corrupted */

/*
 * The Interface
 */

/* Declaration modifiers for DLL support (MSC et al) */

#if defined(DLL_NETCDF) /* define when library is a DLL */
#  if defined(DLL_EXPORT) /* define when building the library */
#   define MSC_EXTRA __declspec(dllexport)
#  else
#   define MSC_EXTRA __declspec(dllimport)
#  endif
#include <io.h>
#define lseek _lseeki64
#define off_t __int64
#else
#define MSC_EXTRA
#endif	/* defined(DLL_NETCDF) */

# define EXTERNL extern MSC_EXTRA

#if defined(DLL_NETCDF) /* define when library is a DLL */
MSC_EXTRA int ncerr;
MSC_EXTRA int ncopts;
#endif

/* Here are functions for coordinate axis stuff. */

/* Label the axis type of a coordinate var. */
EXTERNL int
nc_def_axis_type(int ncid, int varid, int axis_type);

/* Find out the axis type o a coordinate var. */
EXTERNL int
nc_inq_axis_type(int ncid, int varid, int *axis_type);

/* Define a coordinate system consisting of naxes axes, each axis
 * represented by a coordinate varid in the axis_varids array. This
 * create a new (scalar, NC_CHAR) var, whose varid is returned in
 * system_varid. */
EXTERNL int
nc_def_coord_system(int ncid, const char *name, int naxes, int *axis_varids, 
		    int *system_varid);

/* Find out about a coordinate system, it's name, number of axes, and
 * the varid of each axis coordinate var. */
EXTERNL int
nc_inq_coord_system(int ncid, int system_varid, char *name, 
		    int *naxes, int *axis_varids);

/* Assign a coordinate system to a var. This adds an attriibute to the
 * var. */
EXTERNL int
nc_assign_coord_system(int ncid, int varid, int system_varid);

/* Define a coordinate transform. This adds a (scalar, NC_CHAR) var,
 * which contains some attributes. The varid of this new variable is
 * returned in transform_varid. */
EXTERNL int
nc_def_transform(int ncid, const char *name, const char *transform_type, 
		 const char *transform_name, int *transform_varid);

/* Find out about a coordinate transform, it's name, and the contents
 * of the transform_type and transform_name attributes. Pass NULL for
 * any that you're not interested in. Pass NULL for transform_type and
 * transform_name to get their lengths with type_len and name_len. */
EXTERNL int
nc_inq_transform(int ncid, int transform_varid, char *name, size_t *type_len, 
		 char *transform_type, size_t *name_len, char *transform_name);

/* Assign a coordinate transform to a coordinate system. This adds an
 * attribute to the variable that holds the coordinate system
 * attributes. */
EXTERNL int
nc_assign_transform(int ncid, int system_varid, int transform_varid);

EXTERNL const char *
nc_inq_libvers(void);

EXTERNL const char *
nc_strerror(int ncerr);

EXTERNL int
nc__create(const char *path, int cmode, size_t initialsz,
	 size_t *chunksizehintp, int *ncidp);

EXTERNL int
nc_create(const char *path, int cmode, int *ncidp);

EXTERNL int
nc__open(const char *path, int mode, 
	size_t *chunksizehintp, int *ncidp);

EXTERNL int
nc_open(const char *path, int mode, int *ncidp);

EXTERNL int
nc_set_fill(int ncid, int fillmode, int *old_modep);

EXTERNL int
nc_redef(int ncid);

EXTERNL int
nc__enddef(int ncid, size_t h_minfree, size_t v_align,
	size_t v_minfree, size_t r_align);

EXTERNL int
nc_enddef(int ncid);

EXTERNL int
nc_sync(int ncid);

EXTERNL int
nc_abort(int ncid);

EXTERNL int
nc_close(int ncid);

EXTERNL int
nc_inq(int ncid, int *ndimsp, int *nvarsp, int *nattsp, int *unlimdimidp);

EXTERNL int 
nc_inq_ndims(int ncid, int *ndimsp);

EXTERNL int 
nc_inq_nvars(int ncid, int *nvarsp);

EXTERNL int 
nc_inq_natts(int ncid, int *nattsp);

EXTERNL int 
nc_inq_unlimdim(int ncid, int *unlimdimidp);

EXTERNL int
nc_set_default_format(int format, int *old_formatp);

EXTERNL int
nc_inq_format(int ncid, int *formatp);

/* Begin _dim */

EXTERNL int
nc_def_dim(int ncid, const char *name, size_t len, int *idp);

EXTERNL int
nc_inq_dimid(int ncid, const char *name, int *idp);

EXTERNL int
nc_inq_dim(int ncid, int dimid, char *name, size_t *lenp);

EXTERNL int 
nc_inq_dimname(int ncid, int dimid, char *name);

EXTERNL int 
nc_inq_dimlen(int ncid, int dimid, size_t *lenp);

EXTERNL int
nc_rename_dim(int ncid, int dimid, const char *name);

/* End _dim */
/* Begin _att */

EXTERNL int
nc_inq_att(int ncid, int varid, const char *name,
	   nc_type *xtypep, size_t *lenp);

EXTERNL int 
nc_inq_attid(int ncid, int varid, const char *name, int *idp);