netcdf.3

一个用来实现偏微分方程中网格的计算库

.nr yr \n(yr+1900
.af mo 01
.af dy 01
.TH NETCDF 3 "1997-04-18" "Printed: \n(yr-\n(mo-\n(dy" "UNIDATA LIBRARY FUNCTIONS"
.SH NAME
netcdf \- Unidata Network Common Data Form (netCDF) library, version 3 interface
.SH SYNOPSIS
.ft B
.na
.nh
#include "netcdf.h"
.sp

cc ... -lnetcdf

.ad
.hy
.SH "LIBRARY VERSION"
.LP
This document describes version 3 of Unidata netCDF data-access interface
for the C programming language.
.HP
\fBconst char* nc_inq_libvers()\fR
.sp
Returns a string identifying the version of the netCDF library, and
when it was built, like: "3.1a of Aug 22 1996 12:57:47 $".
.LP
The RCS \fBident(1)\fP command will find a string like
"$\|Id: @\|(#) netcdf library version 3.1a of Sep  6 1996 15:56:26 $"
in the library. The SCCS \fBwhat(1)\fP command will find a string like
"netcdf library version 3.1a of Aug 23 1996 16:07:40 $".
.SH "RETURN VALUES"
.LP
All netCDF functions (except
\fBnc_inq_libvers(\|)\fR and \fBnc_strerror(\|)\fR) return an integer status.
This behavior replaces the
\fBncerr()\fR function
used in previous versions of the library.
If this returned status value is not equal to
\fBNC_NOERR\fR (zero), it
indicates that an error occurred. The possible status values are defined in 
system include file <errno.h> and in "netcdf.h".
.HP
\fBconst char* nc_strerror(int \fIstatus\fP)\fR
.sp
Returns a string textual translation of the \fIstatus\fP
value, like "Attribute or variable name contains illegal characters"
or "No such file or directory".
.HP
\fBint nc_create(const char \fIpath\fP[], int \fIcmode\fP, 
int* \fIncid\fP)\fR
.sp
(Corresponds to \fBnccreate(\|)\fR in version 2)
.sp
Creates a new netCDF dataset at \fIpath\fP,
returning a netCDF ID in \fIncid\fP.
The argument \fIcmode\fP may include the bitwise-or
of the following flags:
\fBNC_NOCLOBBER\fR
to protect existing datasets (default
silently blows them away),
\fBNC_SHARE\fR
for synchronous dataset updates
(default is to buffer accesses), and
\fBNC_LOCK\fR
(not yet implemented).
When a netCDF dataset is created, is is opened
\fBNC_WRITE\fR.
The new netCDF dataset is in define mode.
\fBNC_64BIT_OFFSET\fR.
to create a file in the 64-bit offset  
(as opposed to classic , the default). 64-bit 
offset  allows the creation of very large files 
with far fewer restrictions than netCDF classic , 
but can only be read by the netCDF library version 3.6 
or greater. Users are cautioned that files that use the 64-bit offset 
will not be recognized by netCDF applications linked to an earlier
version of the netCDF library than 3.6.  Applications linked to
version 3.6 or later will be able to transparently access either the
classic  or 64-bit offset .
.HP
\fBint nc__create(const char \fIpath\fP[], int \fIcmode\fP, size_t \fIinitialsize\fP, size_t* \fIchunksize\fP, int* \fIncid\fP)\fR
.sp
Like \fBnc_create(\|)\fR but has additional performance tuning parameters.
.sp
The argument \fIinitialsize\fP sets the initial size of the file at
creation time.
.sp
See \fBnc__open(\|)\fR below for an explanation of the \fIchunksize\fP
parameter.
.HP
\fBint nc_open(const char \fIpath\fP[], int \fImode\fP, int* \fIncid\fP)\fR
.sp
(Corresponds to \fBncopen(\|)\fR in version 2)
.sp
Opens a existing netCDF dataset at \fIpath\fP
returning a netCDF ID
in \fIncid\fP.
The type of access is described by the \fImode\fP parameter,
which may include the bitwise-or
of the following flags:
\fBNC_WRITE\fR
for read-write access (default
read-only),
\fBNC_SHARE\fR
for synchronous dataset updates (default is
to buffer accesses), and
\fBNC_LOCK\fR
(not yet implemented).
.HP
\fBint nc__open(const char \fIpath\fP[], int \fImode\fP, size_t* \fIchunksize\fP, int* \fIncid\fP)\fR
.sp
Like \fBnc_open(\|)\fR but has an additional performance tuning parameter.
.sp
The argument referenced by \fIchunksize\fP controls a space versus time
tradeoff, memory allocated in the netcdf library versus number of system
calls.
Because of internal requirements, the value may not be set to exactly
the value requested.
The actual value chosen is returned by reference.
Using the value \fBNC_SIZEHINT_DEFAULT\fR causes the library to choose a
default.
How the system choses the default depends on the system.
On many systems, the "preferred I/O block size" is available from the 
\fBstat()\fR system call, \fBstruct stat\fR member \fBst_blksize\fR.
If this is available it is used. Lacking that, twice the system pagesize
is used.
Lacking a call to discover the system pagesize, we just set default
chunksize to 8192.
.sp
The chunksize is a property of a given open netcdf descriptor
\fIncid\fP, it is not a persistent property of the netcdf dataset.
.HP
\fBint nc_redef(int \fIncid\fP)\fR
.sp
(Corresponds to \fBncredef(\|)\fR in version 2)
.sp
Puts an open netCDF dataset into define mode, 
so dimensions, variables, and attributes can be added or renamed and 
attributes can be deleted.
.HP
\fBint nc_enddef(int \fIncid\fP)\fR
.sp
(Corresponds to \fBncendef(\|)\fR in version 2)
.sp
Takes an open netCDF dataset out of define mode.
The changes made to the netCDF dataset
while it was in define mode are checked and committed to disk if no
problems occurred.  Some data values may be written as well,
see "VARIABLE PREFILLING" below.
After a successful call, variable data can be read or written to the dataset.
.HP
\fBint nc__enddef(int \fIncid\fP, size_t \fIh_minfree\fP, size_t \fIv_align\fP, size_t \fIv_minfree\fP, size_t \fIr_align\fP)\fR
.sp
Like \fBnc_enddef(\|)\fR but has additional performance tuning parameters.
.sp
Caution: this function exposes internals of the netcdf version 1 file
format.
It may not be available on future netcdf implementations.
.sp
The current netcdf file format has three sections,
the "header" section, the data section for fixed size variables, and
the data section for variables which have an unlimited dimension (record
variables).
The header begins at the beginning of the file. The index
(offset) of the beginning of the other two sections is contained in the
header. Typically, there is no space between the sections. This causes
copying overhead to accrue if one wishes to change the size of the
sections,
as may happen when changing names of things, text attribute values,
adding
attributes or adding variables. Also, for buffered i/o, there may be
advantages
to aligning sections in certain ways.
.sp
The minfree parameters allow one to control costs of future calls
to \fBnc_redef(\|)\fR, \fBnc_enddef(\|)\fR by requesting that \fIminfree\fP bytes be
available at the end of the section.
The \fIh_minfree\fP parameter sets the pad
at the end of the "header" section. The \fIv_minfree\fP parameter sets
the pad at the end of the data section for fixed size variables.
.sp
The align parameters allow one to set the alignment of the beginning of
the corresponding sections. The beginning of the section is rounded up
to an index which is a multiple of the align parameter. The flag value
\fBNC_ALIGN_CHUNK\fR tells the library to use the chunksize (see above)
as the align parameter.
The \fIv_align\fP parameter controls the alignment of the beginning of
the data section for fixed size variables.
The \fIr_align\fP parameter controls the alignment of the beginning of
the data section for variables which have an unlimited dimension (record
variables).
.sp
The file format requires mod 4 alignment, so the align parameters
are silently rounded up to multiples of 4. The usual call,
\fBnc_enddef(\fIncid\fP)\fR
is equivalent to
\fBnc__enddef(\fIncid\fP, 0, 4, 0, 4)\fR.
.sp
The file format does not contain a "record size" value, this is
calculated from the sizes of the record variables. This unfortunate fact
prevents us from providing minfree and alignment control of the
"records"
in a netcdf file. If you add a variable which has an unlimited
dimension,
the third section will always be copied with the new variable added.
.HP
\fBint nc_sync(int \fIncid\fP)\fR
.sp
(Corresponds to \fBncsync(\|)\fR in version 2)
.sp
Unless the
\fBNC_SHARE\fR
bit is set in
\fBnc_open(\|)\fR or \fBnc_create(\|)\fR,
accesses to the underlying netCDF dataset are
buffered by the library. This function synchronizes the state of
the underlying dataset and the library.
This is done automatically by
\fBnc_close(\|)\fR and \fBnc_enddef(\|)\fR.
.HP
\fBint nc_abort(int \fIncid\fP)\fR
.sp
(Corresponds to \fBncabort(\|)\fR in version 2)
.sp
You don't need to call this function.
This function is called automatically by
\fBnc_close(\|)\fR
if the netCDF was in define mode and something goes wrong with the commit.
If the netCDF dataset isn't in define mode, then this function is equivalent to
\fBnc_close(\|)\fR.
If it is called after
\fBnc_redef(\|)\fR,
but before
\fBnc_enddef(\|)\fR,
the new definitions are not committed and the dataset is closed.
If it is called after
\fBnc_create(\|)\fR
but before
\fBnc_enddef(\|)\fR,
the dataset disappears.
.HP
\fBint nc_close(int \fIncid\fP)\fR
.sp
(Corresponds to
\fBncclose(\|)\fR in version 2)
.sp
Closes an open netCDF dataset.
If the dataset is in define mode,
\fBnc_enddef(\|)\fR
will be called before closing.
After a dataset is closed, its ID may be reassigned to another dataset.
.HP
\fBint nc_inq(int \fIncid\fP, int* \fIndims\fP, int* \fInvars\fP,
int* \fInatts\fP, int* \fIunlimdimid\fP)\fR
.HP
\fBint nc_inq_ndims(int \fIncid\fP, int* \fIndims\fP)\fR
.HP
\fBint nc_inq_nvars(int \fIncid\fP, int* \fInvars\fP)\fR
.HP
\fBint nc_inq_natts(int \fIncid\fP, int* \fInatts\fP)\fR
.HP
\fBint nc_inq_unlimdim(int \fIncid\fP, int* \fIunlimdimid\fP)\fR
.HP
\fBint nc_inq_format(int \fIncid\fP, int* \fIformatn\fP)\fR
.sp
(Replace \fBncinquire(\|)\fR in version 2)