1NETCDF(3) UNIDATA LIBRARY FUNCTIONS NETCDF(3)
2
6 netcdf - Unidata Network Common Data Form (netCDF) library, version 3
7 interface
8
10 #include "netcdf.h"
11 cc ... -lnetcdf
14
17 This document describes version 3 of Unidata netCDF data-access inter‐
18 face for the C programming language.
19 const char* nc_inq_libvers()
21 Returns a string identifying the version of the netCDF library,
23 and when it was built, like: "3.1a of Aug 22 1996 12:57:47 $".
24 The RCS ident(1) command will find a string like "$Id: @(#) netcdf li‐
26 brary version 3.1a of Sep 6 1996 15:56:26 $" in the library. The SCCS
27 what(1) command will find a string like "netcdf library version 3.1a of
28 Aug 23 1996 16:07:40 $".
29
31 All netCDF functions (except nc_inq_libvers() and nc_strerror()) return
32 an integer status. This behavior replaces the ncerr() function used in
33 previous versions of the library. If this returned status value is not
34 equal to NC_NOERR (zero), it indicates that an error occurred. The pos‐
35 sible status values are defined in system include file <errno.h> and in
36 "netcdf.h".
37 const char* nc_strerror(int status)
39 Returns a string textual translation of the status value, like
41 "Attribute or variable name contains illegal characters" or "No
42 such file or directory".
43 int nc_create(const char path[], int cmode, int* ncid)
45 (Corresponds to nccreate() in version 2)
47 Creates a new netCDF dataset at path, returning a netCDF ID in
49 ncid. The argument cmode may include the bitwise-or of the fol‐
50 lowing flags: NC_NOCLOBBER to protect existing datasets (default
51 silently blows them away), NC_SHARE for synchronous dataset up‐
52 dates (default is to buffer accesses), and NC_LOCK (not yet im‐
53 plemented). When a netCDF dataset is created, is is opened
54 NC_WRITE. The new netCDF dataset is in define mode.
55 NC_64BIT_OFFSET. to create a file in the 64-bit offset (as op‐
56 posed to classic , the default). 64-bit offset allows the cre‐
57 ation of very large files with far fewer restrictions than
58 netCDF classic , but can only be read by the netCDF library ver‐
59 sion 3.6 or greater. Users are cautioned that files that use the
60 64-bit offset will not be recognized by netCDF applications
61 linked to an earlier version of the netCDF library than 3.6.
62 Applications linked to version 3.6 or later will be able to
63 transparently access either the classic or 64-bit offset .
64 int nc__create(const char path[], int cmode, size_t initialsize,
66 size_t* chunksize, int* ncid)
67 Like nc_create() but has additional performance tuning parame‐
69 ters.
70 The argument initialsize sets the initial size of the file at
72 creation time.
73 See nc__open() below for an explanation of the chunksize parame‐
75 ter.
76 int nc_open(const char path[], int mode, int* ncid)
78 (Corresponds to ncopen() in version 2)
80 Opens a existing netCDF dataset at path returning a netCDF ID in
82 ncid. The type of access is described by the mode parameter,
83 which may include the bitwise-or of the following flags:
84 NC_WRITE for read-write access (default read-only), NC_SHARE for
85 synchronous dataset updates (default is to buffer accesses), and
86 NC_LOCK (not yet implemented).
87 int nc__open(const char path[], int mode, size_t* chunksize, int* ncid)
89 Like nc_open() but has an additional performance tuning parame‐
91 ter.
92 The argument referenced by chunksize controls a space versus
94 time tradeoff, memory allocated in the netcdf library versus
95 number of system calls. Because of internal requirements, the
96 value may not be set to exactly the value requested. The actual
97 value chosen is returned by reference. Using the value NC_SIZE‐
98 HINT_DEFAULT causes the library to choose a default. How the
99 system choses the default depends on the system. On many sys‐
100 tems, the "preferred I/O block size" is available from the
101 stat() system call, struct stat member st_blksize. If this is
102 available it is used. Lacking that, twice the system pagesize is
103 used. Lacking a call to discover the system pagesize, we just
104 set default chunksize to 8192.
105 The chunksize is a property of a given open netcdf descriptor
107 ncid, it is not a persistent property of the netcdf dataset.
108 int nc_redef(int ncid)
110 (Corresponds to ncredef() in version 2)
112 Puts an open netCDF dataset into define mode, so dimensions,
114 variables, and attributes can be added or renamed and attributes
115 can be deleted.
116 int nc_enddef(int ncid)
118 (Corresponds to ncendef() in version 2)
120 Takes an open netCDF dataset out of define mode. The changes
122 made to the netCDF dataset while it was in define mode are
123 checked and committed to disk if no problems occurred. Some da‐
124 ta values may be written as well, see "VARIABLE PREFILLING" be‐
125 low. After a successful call, variable data can be read or
126 written to the dataset.
127 int nc__enddef(int ncid, size_t h_minfree, size_t v_align, size_t
129 v_minfree, size_t r_align)
130 Like nc_enddef() but has additional performance tuning parame‐
132 ters.
133 Caution: this function exposes internals of the netcdf version 1
135 file format. It may not be available on future netcdf implemen‐
136 tations.
137 The current netcdf file format has three sections, the "header"
139 section, the data section for fixed size variables, and the data
140 section for variables which have an unlimited dimension (record
141 variables). The header begins at the beginning of the file. The
142 index (offset) of the beginning of the other two sections is
143 contained in the header. Typically, there is no space between
144 the sections. This causes copying overhead to accrue if one
145 wishes to change the size of the sections, as may happen when
146 changing names of things, text attribute values, adding at‐
147 tributes or adding variables. Also, for buffered i/o, there may
148 be advantages to aligning sections in certain ways.
149 The minfree parameters allow one to control costs of future
151 calls to nc_redef(), nc_enddef() by requesting that minfree
152 bytes be available at the end of the section. The h_minfree pa‐
153 rameter sets the pad at the end of the "header" section. The
154 v_minfree parameter sets the pad at the end of the data section
155 for fixed size variables.
156 The align parameters allow one to set the alignment of the be‐
158 ginning of the corresponding sections. The beginning of the sec‐
159 tion is rounded up to an index which is a multiple of the align
160 parameter. The flag value NC_ALIGN_CHUNK tells the library to
161 use the chunksize (see above) as the align parameter. The
162 v_align parameter controls the alignment of the beginning of the
163 data section for fixed size variables. The r_align parameter
164 controls the alignment of the beginning of the data section for
165 variables which have an unlimited dimension (record variables).
166 The file format requires mod 4 alignment, so the align parame‐
168 ters are silently rounded up to multiples of 4. The usual call,
169 nc_enddef(ncid) is equivalent to nc__enddef(ncid, 0, 4, 0, 4).
170 The file format does not contain a "record size" value, this is
172 calculated from the sizes of the record variables. This unfortu‐
173 nate fact prevents us from providing minfree and alignment con‐
174 trol of the "records" in a netcdf file. If you add a variable
175 which has an unlimited dimension, the third section will always
176 be copied with the new variable added.
177 int nc_sync(int ncid)
179 (Corresponds to ncsync() in version 2)
181 Unless the NC_SHARE bit is set in nc_open() or nc_create(), ac‐
183 cesses to the underlying netCDF dataset are buffered by the li‐
184 brary. This function synchronizes the state of the underlying
185 dataset and the library. This is done automatically by
186 nc_close() and nc_enddef().
187 int nc_abort(int ncid)
189 (Corresponds to ncabort() in version 2)
191 You don't need to call this function. This function is called
193 automatically by nc_close() if the netCDF was in define mode and
194 something goes wrong with the commit. If the netCDF dataset
195 isn't in define mode, then this function is equivalent to
196 nc_close(). If it is called after nc_redef(), but before
197 nc_enddef(), the new definitions are not committed and the
198 dataset is closed. If it is called after nc_create() but before
199 nc_enddef(), the dataset disappears.
200 int nc_close(int ncid)
202 (Corresponds to ncclose() in version 2)
204 Closes an open netCDF dataset. If the dataset is in define
206 mode, nc_enddef() will be called before closing. After a
207 dataset is closed, its ID may be reassigned to another dataset.
208 int nc_inq(int ncid, int* ndims, int* nvars, int* natts, int* un‐
210 limdimid)
211 int nc_inq_ndims(int ncid, int* ndims)
213 int nc_inq_nvars(int ncid, int* nvars)
215 int nc_inq_natts(int ncid, int* natts)
217 int nc_inq_unlimdim(int ncid, int* unlimdimid)
219 int nc_inq_format(int ncid, int* formatn)
221 (Replace ncinquire() in version 2)
223 Use these functions to find out what is in a netCDF dataset.
225 Upon successful return, ndims will contain the number of dimen‐
226 sions defined for this netCDF dataset, nvars will contain the
227 number of variables, natts will contain the number of at‐
228 tributes, and unlimdimid will contain the dimension ID of the
229 unlimited dimension if one exists, or -1 otherwise. formatn
230 will contain the version number of the dataset <>, one of
231 NC_FORMAT_CLASSIC, NC_FORMAT_64BIT, NC_FORMAT_NETCDF4, or
232 NC_FORMAT_NETCDF4_CLASSIC. If any of the return parameters is a
233 NULL pointer, then the corresponding information will not be re‐
234 turned; hence, no space need be allocated for it.
235 int nc_def_dim(int ncid, const char name[], size_t len, int* dimid)
237 (Corresponds to ncdimdef() in version 2)
239 Adds a new dimension to an open netCDF dataset, which must be in
241 define mode. name is the dimension name. If dimid is not a
242 NULL pointer then upon successful completion dimid will contain
243 the dimension ID of the newly created dimension.
244 int nc_inq_dimid(int ncid, const char name[], int* dimid)
246 (Corresponds to ncdimid() in version 2)
248 Given a dimension name, returns the ID of a netCDF dimension in
250 dimid.
251 int nc_inq_dim(int ncid, int dimid, char name[], size_t* len)
253 int nc_inq_dimname(int ncid, int dimid, char name[])
255 int nc_inq_dimlen(int ncid, int dimid, size_t* len)
257 (Replace ncdiminq() in version 2)
259 Use these functions to find out about a dimension. If either
261 the name argument or len argument is a NULL pointer, then the
262 associated information will not be returned. Otherwise, name
263 should be big enough (NC_MAX_NAME) to hold the dimension name
264 as the name will be copied into your storage. The length return
265 parameter, len will contain the size of the dimension. For the
266 unlimited dimension, the returned length is the current maximum
267 value used for writing into any of the variables which use the
268 dimension.
269 int nc_rename_dim(int ncid, int dimid, const char name[])
271 (Corresponds to ncdimrename() in version 2)
273 Renames an existing dimension in an open netCDF dataset. If the
275 new name is longer than the old name, the netCDF dataset must be
276 in define mode. You cannot rename a dimension to have the same
277 name as another dimension.
278 int nc_def_var(int ncid, const char name[], nc_type xtype, int ndims,
280 const int dimids[], int* varid)
281 (Corresponds to ncvardef() in version 2)
283 Adds a new variable to a netCDF dataset. The netCDF must be in
285 define mode. If not NULL, then varid will be set to the netCDF
286 variable ID.
287 int nc_inq_varid(int ncid, const char name[], int* varid)
289 (Corresponds to ncvarid() in version 2)
291 Returns the ID of a netCDF variable in varid given its name.
293 int nc_inq_var(int ncid, int varid, char name[], nc_type* xtype, int*
295 ndims, int dimids[], int* natts)
296 int nc_inq_varname(int ncid, int varid, char name[])
298 int nc_inq_vartype(int ncid, int varid, nc_type* xtype)
300 int nc_inq_varndims(int ncid, int varid, int* ndims)
302 int nc_inq_vardimid(int ncid, int varid, int dimids[])
304 int nc_inq_varnatts(int ncid, int varid, int* natts)
306 (Replace ncvarinq() in version 2)
308 Returns information about a netCDF variable, given its ID. If
310 any of the return parameters (name, xtype, ndims, dimids, or
311 natts) is a NULL pointer, then the corresponding information
312 will not be returned; hence, no space need be allocated for it.
313 int nc_rename_var(int ncid, int varid, const char name[])
315 (Corresponds to ncvarrename() in version 2)
317 Changes the name of a netCDF variable. If the new name is
319 longer than the old name, the netCDF must be in define mode.
320 You cannot rename a variable to have the name of any existing
321 variable.
322 int nc_put_var_text(int ncid, int varid, const char out[])
324 int nc_put_var_uchar(int ncid, int varid, const unsigned char out[])
326 int nc_put_var_schar(int ncid, int varid, const signed char out[])
328 int nc_put_var_short(int ncid, int varid, const short out[])
330 int nc_put_var_int(int ncid, int varid, const int out[])
332 int nc_put_var_long(int ncid, int varid, const long out[])
334 int nc_put_var_float(int ncid, int varid, const float out[])
336 int nc_put_var_double(int ncid, int varid, const double out[])
338 (Replace ncvarput() in version 2)
340 Writes an entire netCDF variable (i.e. all the values). The
342 netCDF dataset must be open and in data mode. The type of the
343 data is specified in the function name, and it is converted to
344 the external type of the specified variable, if possible, other‐
345 wise an NC_ERANGE error is returned. Note that rounding is not
346 performed during the conversion. Floating point numbers are
347 truncated when converted to integers.
348 int nc_get_var_text(int ncid, int varid, char in[])
350 int nc_get_var_uchar(int ncid, int varid, unsigned char in[])
352 int nc_get_var_schar(int ncid, int varid, signed char in[])
354 int nc_get_var_short(int ncid, int varid, short in[])
356 int nc_get_var_int(int ncid, int varid, int in[])
358 int nc_get_var_long(int ncid, int varid, long in[])
360 int nc_get_var_float(int ncid, int varid, float in[])
362 int nc_get_var_double(int ncid, int varid, double in[])
364 (Replace ncvarget() in version 2)
366 Reads an entire netCDF variable (i.e. all the values). The
368 netCDF dataset must be open and in data mode. The data is con‐
369 verted from the external type of the specified variable, if nec‐
370 essary, to the type specified in the function name. If conver‐
371 sion is not possible, an NC_ERANGE error is returned.
372 int nc_put_var1_text(int ncid, int varid, const size_t index[], char
374 *out)
375 int nc_put_var1_uchar(int ncid, int varid, const size_t index[], un‐
377 signed char *out)
378 int nc_put_var1_schar(int ncid, int varid, const size_t index[], signed
380 char *out)
381 int nc_put_var1_short(int ncid, int varid, const size_t index[], short
383 *out)
384 int nc_put_var1_int(int ncid, int varid, const size_t index[], int
386 *out)
387 int nc_put_var1_long(int ncid, int varid, const size_t index[], long
389 *out)
390 int nc_put_var1_float(int ncid, int varid, const size_t index[], float
392 *out)
393 int nc_put_var1_double(int ncid, int varid, const size_t index[], dou‐
395 ble *out)
396 (Replace ncvarput1() in version 2)
398 Puts a single data value into a variable at the position index
400 of an open netCDF dataset that is in data mode. The type of the
401 data is specified in the function name, and it is converted to
402 the external type of the specified variable, if possible, other‐
403 wise an NC_ERANGE error is returned.
404 int nc_get_var1_text(int ncid, int varid, const size_t index[], char*
406 in)
407 int nc_get_var1_uchar(int ncid, int varid, const size_t index[], un‐
409 signed char* in)
410 int nc_get_var1_schar(int ncid, int varid, const size_t index[], signed
412 char* in)
413 int nc_get_var1_short(int ncid, int varid, const size_t index[], short*
415 in)
416 int nc_get_var1_int(int ncid, int varid, const size_t index[], int* in)
418 int nc_get_var1_long(int ncid, int varid, const size_t index[], long*
420 in)
421 int nc_get_var1_float(int ncid, int varid, const size_t index[], float*
423 in)
424 int nc_get_var1_double(int ncid, int varid, const size_t index[], dou‐
426 ble* in)
427 (Replace ncvarget1() in version 2)
429 Gets a single data value from a variable at the position index
431 of an open netCDF dataset that is in data mode. The data is
432 converted from the external type of the specified variable, if
433 necessary, to the type specified in the function name. If con‐
434 version is not possible, an NC_ERANGE error is returned.
435 int nc_put_vara_text(int ncid, int varid, const size_t start[], const
437 size_t count[], const char out[])
438 int nc_put_vara_uchar(int ncid, int varid, const size_t start[], const
440 size_t count[], const unsigned char out[])
441 int nc_put_vara_schar(int ncid, int varid, const size_t start[], const
443 size_t count[], const signed char out[])
444 int nc_put_vara_short(int ncid, int varid, const size_t start[], const
446 size_t count[], const short out[])
447 int nc_put_vara_int(int ncid, int varid, const size_t start[], const
449 size_t count[], const int out[])
450 int nc_put_vara_long(int ncid, int varid, const size_t start[], const
452 size_t count[], const long out[])
453 int nc_put_vara_float(int ncid, int varid, const size_t start[], const
455 size_t count[], const float out[])
456 int nc_put_vara_double(int ncid, int varid, const size_t start[], const
458 size_t count[], const double out[])
459 (Replace ncvarput() in version 2)
461 Writes an array section of values into a netCDF variable of an
463 open netCDF dataset, which must be in data mode. The array sec‐
464 tion is specified by the start and count vectors, which give the
465 starting index and count of values along each dimension of the
466 specified variable. The type of the data is specified in the
467 function name and is converted to the external type of the spec‐
468 ified variable, if possible, otherwise an NC_ERANGE error is re‐
469 turned.
470 int nc_get_vara_text(int ncid, int varid, const size_t start[], const
472 size_t count[], char in[])
473 int nc_get_vara_uchar(int ncid, int varid, const size_t start[], const
475 size_t count[], unsigned char in[])
476 int nc_get_vara_schar(int ncid, int varid, const size_t start[], const
478 size_t count[], signed char in[])
479 int nc_get_vara_short(int ncid, int varid, const size_t start[], const
481 size_t count[], short in[])
482 int nc_get_vara_int(int ncid, int varid, const size_t start[], const
484 size_t count[], int in[])
485 int nc_get_vara_long(int ncid, int varid, const size_t start[], const
487 size_t count[], long in[])
488 int nc_get_vara_float(int ncid, int varid, const size_t start[], const
490 size_t count[], float in[])
491 int nc_get_vara_double(int ncid, int varid, const size_t start[], const
493 size_t count[], double in[])
494 (Corresponds to ncvarget() in version 2)
496 Reads an array section of values from a netCDF variable of an
498 open netCDF dataset, which must be in data mode. The array sec‐
499 tion is specified by the start and count vectors, which give the
500 starting index and count of values along each dimension of the
501 specified variable. The data is converted from the external
502 type of the specified variable, if necessary, to the type speci‐
503 fied in the function name. If conversion is not possible, an
504 NC_ERANGE error is returned.
505 int nc_put_vars_text(int ncid, int varid, const size_t start[], const
507 size_t count[], const size_t stride[], const char out[])
508 int nc_put_vars_uchar(int ncid, int varid, const size_t start[], const
510 size_t count[], const size_t stride[], const unsigned char
511 out[])
512 int nc_put_vars_schar(int ncid, int varid, const size_t start[], const
514 size_t count[], const size_t stride[], const signed char out[])
515 int nc_put_vars_short(int ncid, int varid, const size_t start[], const
517 size_t count[], const size_t stride[], const short out[])
518 int nc_put_vars_int(int ncid, int varid, const size_t start[], const
520 size_t count[], const size_t stride[], const int out[])
521 int nc_put_vars_long(int ncid, int varid, const size_t start[], const
523 size_t count[], const size_t stride[], const long out[])
524 int nc_put_vars_float(int ncid, int varid, const size_t start[], const
526 size_t count[], const size_t stride[], const float out[])
527 int nc_put_vars_double(int ncid, int varid, const size_t start[], const
529 size_t count[], const size_t stride[], const double out[])
530 (Corresponds to ncvarputg() in version 2)
532 These functions are used for strided output, which is like the
534 array section output described above, except that the sampling
535 stride (the interval between accessed values) is specified for
536 each dimension. For an explanation of the sampling stride vec‐
537 tor, see COMMON ARGUMENTS DESCRIPTIONS below.
538 int nc_get_vars_text(int ncid, int varid, const size_t start[], const
540 size_t count[], const size_t stride[], char in[])
541 int nc_get_vars_uchar(int ncid, int varid, const size_t start[], const
543 size_t count[], const size_t stride[], unsigned char in[])
544 int nc_get_vars_schar(int ncid, int varid, const size_t start[], const
546 size_t count[], const size_t stride[], signed char in[])
547 int nc_get_vars_short(int ncid, int varid, const size_t start[], const
549 size_t count[], const size_t stride[], short in[])
550 int nc_get_vars_int(int ncid, int varid, const size_t start[], const
552 size_t count[], const size_t stride[], int in[])
553 int nc_get_vars_long(int ncid, int varid, const size_t start[], const
555 size_t count[], const size_t stride[], long in[])
556 int nc_get_vars_float(int ncid, int varid, const size_t start[], const
558 size_t count[], const size_t stride[], float in[])
559 int nc_get_vars_double(int ncid, int varid, const size_t start[], const
561 size_t count[], const size_t stride[], double in[])
562 (Corresponds to ncvargetg() in version 2)
564 These functions are used for strided input, which is like the
566 array section input described above, except that the sampling
567 stride (the interval between accessed values) is specified for
568 each dimension. For an explanation of the sampling stride vec‐
569 tor, see COMMON ARGUMENTS DESCRIPTIONS below.
570 int nc_put_varm_text(int ncid, int varid, const size_t start[], const
572 size_t count[], const size_t stride[], imap, const char out[])
573 int nc_put_varm_uchar(int ncid, int varid, const size_t start[], const
575 size_t count[], const size_t stride[], imap, const unsigned char
576 out[])
577 int nc_put_varm_schar(int ncid, int varid, const size_t start[], const
579 size_t count[], const size_t stride[], imap, const signed char
580 out[])
581 int nc_put_varm_short(int ncid, int varid, const size_t start[], const
583 size_t count[], const size_t stride[], imap, const short out[])
584 int nc_put_varm_int(int ncid, int varid, const size_t start[], const
586 size_t count[], const size_t stride[], imap, const int out[])
587 int nc_put_varm_long(int ncid, int varid, const size_t start[], const
589 size_t count[], const size_t stride[], imap, const long out[])
590 int nc_put_varm_float(int ncid, int varid, const size_t start[], const
592 size_t count[], const size_t stride[], imap, const float out[])
593 int nc_put_varm_double(int ncid, int varid, const size_t start[], const
595 size_t count[], const size_t stride[], imap, const double out[])
596 (Corresponds to ncvarputg() in version 2)
598 These functions are used for mapped output, which is like strid‐
600 ed output described above, except that an additional index map‐
601 ping vector is provided to specify the in-memory arrangement of
602 the data values. For an explanation of the index mapping vec‐
603 tor, see COMMON ARGUMENTS DESCRIPTIONS below.
604 int nc_get_varm_text(int ncid, int varid, const size_t start[], const
606 size_t count[], const size_t stride[], imap, char in[])
607 int nc_get_varm_uchar(int ncid, int varid, const size_t start[], const
609 size_t count[], const size_t stride[], imap, unsigned char in[])
610 int nc_get_varm_schar(int ncid, int varid, const size_t start[], const
612 size_t count[], const size_t stride[], imap, signed char in[])
613 int nc_get_varm_short(int ncid, int varid, const size_t start[], const
615 size_t count[], const size_t stride[], imap, short in[])
616 int nc_get_varm_int(int ncid, int varid, const size_t start[], const
618 size_t count[], const size_t stride[], imap, int in[])
619 int nc_get_varm_long(int ncid, int varid, const size_t start[], const
621 size_t count[], const size_t stride[], imap, long in[])
622 int nc_get_varm_float(int ncid, int varid, const size_t start[], const
624 size_t count[], const size_t stride[], imap, float in[])
625 int nc_get_varm_double(int ncid, int varid, const size_t start[], const
627 size_t count[], const size_t stride[], imap, double in[])
628 (Corresponds to ncvargetg() in version 2)
630 These functions are used for mapped input, which is like strided
632 input described above, except that an additional index mapping
633 vector is provided to specify the in-memory arrangement of the
634 data values. For an explanation of the index mapping vector,
635 see COMMON ARGUMENTS DESCRIPTIONS below.
636 int nc_put_att_text(int ncid, int varid, const char name[], nc_type
638 xtype, size_t len, const char out[])
639 int nc_put_att_uchar(int ncid, int varid, const char name[], nc_type
641 xtype, size_t len, const unsigned char out[])
642 int nc_put_att_schar(int ncid, int varid, const char name[], nc_type
644 xtype, size_t len, const signed char out[])
645 int nc_put_att_short(int ncid, int varid, const char name[], nc_type
647 xtype, size_t len, const short out[])
648 int nc_put_att_int(int ncid, int varid, const char name[], nc_type
650 xtype, size_t len, const int out[])
651 int nc_put_att_long(int ncid, int varid, const char name[], nc_type
653 xtype, size_t len, const long out[])
654 int nc_put_att_float(int ncid, int varid, const char name[], nc_type
656 xtype, size_t len, const float out[])
657 int nc_put_att_double(int ncid, int varid, const char name[], nc_type
659 xtype, size_t len, const double out[])
660 (Replace ncattput() in version 2)
662 Unlike variables, attributes do not have separate functions for
664 defining and writing values. This family of functions defines a
665 new attribute with a value or changes the value of an existing
666 attribute. If the attribute is new, or if the space required to
667 store the attribute value is greater than before, the netCDF
668 dataset must be in define mode. The parameter len is the number
669 of values from out to transfer. It is often one, except that
670 for nc_put_att_text() it will usually be strlen(out).
671 For these functions, the type component of the function name
673 refers to the in-memory type of the value, whereas the xtype ar‐
674 gument refers to the external type for storing the value. An
675 NC_ERANGE error results if a conversion between these types is
676 not possible. In this case the value is represented with the
677 appropriate fill-value for the associated external type.
678 int nc_inq_attname(int ncid, int varid, int attnum, char name[])
680 (Corresponds to ncattname() in version 2)
682 Gets the name of an attribute, given its variable ID and at‐
684 tribute number. This function is useful in generic applications
685 that need to get the names of all the attributes associated with
686 a variable, since attributes are accessed by name rather than
687 number in all other attribute functions. The number of an at‐
688 tribute is more volatile than the name, since it can change when
689 other attributes of the same variable are deleted. The at‐
690 tributes for each variable are numbered from 0 (the first at‐
691 tribute) to nvatts-1, where nvatts is the number of attributes
692 for the variable, as returned from a call to nc_inq_varnatts().
693 If the name parameter is a NULL pointer, no name will be re‐
694 turned and no space need be allocated.
695 int nc_inq_att(int ncid, int varid, const char name[], nc_type* xtype,
697 size_t* len)
698 int nc_inq_attid(int ncid, int varid, const char name[], int* attnum)
700 int nc_inq_atttype(int ncid, int varid, const char name[], nc_type*
702 xtype)
703 int nc_inq_attlen(int ncid, int varid, const char name[], size_t* len)
705 (Corresponds to ncattinq() in version 2)
707 These functions return information about a netCDF attribute,
709 given its variable ID and name. The information returned is the
710 external type in xtype and the number of elements in the at‐
711 tribute as len. If any of the return arguments is a NULL point‐
712 er, the specified information will not be returned.
713 int nc_copy_att(int ncid, int varid_in, const char name[], int
715 ncid_out, int varid_out)
716 (Corresponds to ncattcopy() in version 2)
718 Copies an attribute from one netCDF dataset to another. It can
720 also be used to copy an attribute from one variable to another
721 within the same netCDF. ncid_in is the netCDF ID of an input
722 netCDF dataset from which the attribute will be copied.
723 varid_in is the ID of the variable in the input netCDF dataset
724 from which the attribute will be copied, or NC_GLOBAL for a
725 global attribute. name is the name of the attribute in the in‐
726 put netCDF dataset to be copied. ncid_out is the netCDF ID of
727 the output netCDF dataset to which the attribute will be copied.
728 It is permissible for the input and output netCDF ID's to be the
729 same. The output netCDF dataset should be in define mode if the
730 attribute to be copied does not already exist for the target
731 variable, or if it would cause an existing target attribute to
732 grow. varid_out is the ID of the variable in the output netCDF
733 dataset to which the attribute will be copied, or NC_GLOBAL to
734 copy to a global attribute.
735 int nc_rename_att(int ncid, int varid, const char name[], const char
737 newname[])
738 (Corresponds to ncattrename()
740 Changes the name of an attribute. If the new name is longer
742 than the original name, the netCDF must be in define mode. You
743 cannot rename an attribute to have the same name as another at‐
744 tribute of the same variable. name is the original attribute
745 name. newname is the new name to be assigned to the specified
746 attribute. If the new name is longer than the old name, the
747 netCDF dataset must be in define mode.
748 int nc_del_att(int ncid, int varid, const char name[])
750 (Corresponds to ncattdel() in version 2)
752 Deletes an attribute from a netCDF dataset. The dataset must be
754 in define mode.
755 int nc_get_att_text(int ncid, int varid, const char name[], char in[])
757 int nc_get_att_uchar(int ncid, int varid, const char name[], unsigned
759 char in[])
760 int nc_get_att_schar(int ncid, int varid, const char name[], signed
762 char in[])
763 int nc_get_att_short(int ncid, int varid, const char name[], short
765 in[])
766 int nc_get_att_int(int ncid, int varid, const char name[], int in[])
768 int nc_get_att_long(int ncid, int varid, const char name[], long in[])
770 int nc_get_att_float(int ncid, int varid, const char name[], float
772 in[])
773 int nc_get_att_double(int ncid, int varid, const char name[], double
775 in[])
776 (Replace ncattget() in version 2)
778 Gets the value(s) of a netCDF attribute, given its variable ID
780 and name. Converts from the external type to the type specified
781 in the function name, if possible, otherwise returns an
782 NC_ERANGE error. All elements of the vector of attribute values
783 are returned, so you must allocate enough space to hold them.
784 If you don't know how much space to reserve, call nc_inq_at‐
785 tlen() first to find out the length of the attribute.
786
788 In this section we define some common arguments which are used in the
789 "FUNCTION DESCRIPTIONS" section.
790 int ncid
792 is the netCDF ID returned from a previous, successful call to
793 nc_open() or nc_create()
794 char name[]
796 is the name of a dimension, variable, or attribute. The names of
797 dimensions, variables and attributes consist of arbitrary se‐
798 quences of alphanumeric characters (as well as underscore '_',
799 period '.' and hyphen '-'), beginning with a letter or under‐
800 score. (However names commencing with underscore are reserved
801 for system use.) Case is significant in netCDF names. A zero-
802 length name is not allowed. As an input argument, it shall be a
803 pointer to a 0-terminated string; as an output argument, it
804 shall be the address of a buffer in which to hold such a string.
805 The maximum allowable number of characters (excluding the termi‐
806 nating 0) is NC_MAX_NAME.
807 nc_type xtype
809 specifies the external data type of a netCDF variable or at‐
810 tribute and is one of the following: NC_BYTE, NC_CHAR, NC_SHORT,
811 NC_INT, NC_FLOAT, or NC_DOUBLE. These are used to specify 8-bit
812 integers, characters, 16-bit integers, 32-bit integers, 32-bit
813 IEEE floating point numbers, and 64-bit IEEE floating-point num‐
814 bers, respectively. (NC_INT corresponds to NC_LONG in version
815 2, to specify a 32-bit integer).
816 int dimids[]
818 is a vector of dimension ID's and defines the shape of a netCDF
819 variable. The size of the vector shall be greater than or equal
820 to the rank (i.e. the number of dimensions) of the variable
821 (ndims). The vector shall be ordered by the speed with which a
822 dimension varies: dimids[ndims-1] shall be the dimension ID of
823 the most rapidly varying dimension and dimids[0] shall be the
824 dimension ID of the most slowly varying dimension. The maximum
825 possible number of dimensions for a variable is given by the
826 symbolic constant NC_MAX_VAR_DIMS.
827 int dimid
829 is the ID of a netCDF dimension. netCDF dimension ID's are al‐
830 located sequentially from the non-negative integers beginning
831 with 0.
832 int ndims
834 is either the total number of dimensions in a netCDF dataset or
835 the rank (i.e. the number of dimensions) of a netCDF variable.
836 The value shall not be negative or greater than the symbolic
837 constant NC_MAX_VAR_DIMS.
838 int varid
840 is the ID of a netCDF variable or (for the attribute-access
841 functions) the symbolic constant NC_GLOBAL, which is used to
842 reference global attributes. netCDF variable ID's are allocated
843 sequentially from the non-negative integers beginning with 0.
844 int* natts
846 is the number of global attributes in a netCDF dataset for the
847 nc_inquire() function or the number of attributes associated
848 with a netCDF variable for the nc_varinq() function.
849 const size_t index[]
851 specifies the indicial coordinates of the netCDF data value to
852 be accessed. The indices start at 0; thus, for example, the
853 first data value of a two-dimensional variable is (0,0). The
854 size of the vector shall be at least the rank of the associated
855 netCDF variable and its elements shall correspond, in order, to
856 the variable's dimensions.
857 const size_t start[]
859 specifies the starting point for accessing a netCDF variable's
860 data values in terms of the indicial coordinates of the corner
861 of the array section. The indices start at 0; thus, the first
862 data value of a variable is (0, 0, ..., 0). The size of the
863 vector shall be at least the rank of the associated netCDF vari‐
864 able and its elements shall correspond, in order, to the vari‐
865 able's dimensions.
866 const size_t count[]
868 specifies the number of indices selected along each dimension of
869 the array section. Thus, to access a single value, for example,
870 specify count as (1, 1, ..., 1). Note that, for strided I/O,
871 this argument must be adjusted to be compatible with the stride
872 and start arguments so that the interaction of the three does
873 not attempt to access an invalid data co-ordinate. The elements
874 of the count vector correspond, in order, to the variable's di‐
875 mensions.
876 const size_t stride[]
878 specifies the sampling interval along each dimension of the
879 netCDF variable. The elements of the stride vector correspond,
880 in order, to the netCDF variable's dimensions (stride[0]) gives
881 the sampling interval along the most slowly varying dimension of
882 the netCDF variable). Sampling intervals are specified in type-
883 independent units of elements (a value of 1 selects consecutive
884 elements of the netCDF variable along the corresponding dimen‐
885 sion, a value of 2 selects every other element, etc.). A NULL
886 stride argument is treated as (1, 1, ... , 1).
887 imap specifies the mapping between the dimensions of a netCDF vari‐
889 able and the in-memory structure of the internal data array.
890 The elements of the index mapping vector correspond, in order,
891 to the netCDF variable's dimensions (imap[0] gives the distance
892 between elements of the internal array corresponding to the most
893 slowly varying dimension of the netCDF variable). Distances be‐
894 tween elements are specified in type-independent units of ele‐
895 ments (the distance between internal elements that occupy adja‐
896 cent memory locations is 1 and not the element's byte-length as
897 in netCDF 2). A NULL pointer means the memory-resident values
898 have the same structure as the associated netCDF variable.
899
901 By default, the netCDF interface sets the values of all newly-defined
902 variables of finite length (i.e. those that do not have an unlimited,
903 dimension) to the type-dependent fill-value associated with each vari‐
904 able. This is done when nc_enddef() is called. The fill-value for a
905 variable may be changed from the default value by defining the at‐
906 tribute `_FillValue' for the variable. This attribute must have the
907 same type as the variable and be of length one.
908 Variables with an unlimited dimension are also prefilled, but on an `as
910 needed' basis. For example, if the first write of such a variable is
911 to position 5, then positions 0 through 4 (and no others) would be set
912 to the fill-value at the same time.
913 This default prefilling of data values may be disabled by or'ing the
915 NC_NOFILL flag into the mode parameter of nc_open() or nc_create(), or,
916 by calling the function nc_set_fill() with the argument NC_NOFILL. For
917 variables that do not use the unlimited dimension, this call must be
918 made before nc_enddef(). For variables that use the unlimited dimen‐
919 sion, this call may be made at any time.
920 One can obtain increased performance of the netCDF interface by using
922 this feature, but only at the expense of requiring the application to
923 set every single data value. The performance enhancing behavior of
924 this function is dependent on the particulars of the implementation and
925 dataset format. The flag value controlled by nc_set_fill() is per
926 netCDF ID, not per variable or per write. Allowing this to change af‐
927 fects the degree to which a program can be effectively parallelized.
928 Given all of this, we state that the use of this feature may not be
929 available (or even needed) in future releases. Programmers are cau‐
930 tioned against heavy reliance upon this feature.
931 int nc_setfill(int ncid, int fillmode, int* old_fillemode)
933 (Corresponds to ncsetfill() in version 2)
935 Determines whether or not variable prefilling will be done (see
937 above). The netCDF dataset shall be writable. fillmode is ei‐
938 ther NC_FILL to enable prefilling (the default) or NC_NOFILL to
939 disable prefilling. This function returns the previous setting
940 in old_fillmode.
941
943 Additional functions for use on SGI/Cray MPP machines (_CRAYMPP).
944 These are used to set and inquire which PE is the base for MPP for a
945 particular netCDF. These are only relevant when using the SGI/Cray
946 ``global'' Flexible File I/O layer and desire to have only a subset of
947 PEs to open the specific netCDF file. For technical reasons, these
948 functions are available on all platforms. On a platform other than
949 SGI/Cray MPP, it is as if only processor available were processor 0.
950 To use this feature, you need to specify a communicator group and call
952 glio_group_mpi() or glio_group_shmem() prior to the netCDF nc_open()
953 and nc_create() calls.
954 int nc__create_mp(const char path[], int cmode, size_t initialsize, int
956 pe, size_t* chunksize, int* ncid)
957 Like nc__create() but allows the base PE to be set.
959 The argument pe sets the base PE at creation time. In the MPP
961 environment, nc__create() and nc_create() set the base PE to
962 processor zero by default.
963 int nc__open_mp(const char path[], int mode, int pe, size_t* chunksize,
965 int* ncid)
966 Like nc__open() but allows the base PE to be set. The argument
968 pe sets the base PE at creation time. In the MPP environment,
969 nc__open() and nc_open() set the base PE to processor zero by
970 default.
971 int nc_inq_base_pe(int ncid, int* pe)
973 Inquires of the netCDF dataset which PE is being used as the
975 base for MPP use. This is safe to use at any time.
976 int nc_set_base_pe(int ncid, int pe)
978 Resets the base PE for the netCDF dataset. Only perform this
980 operation when the affected communicator group synchronizes be‐
981 fore and after the call. This operation is very risky and
982 should only be contemplated under only the most extreme cases.
983
985 NETCDF_FFIOSPEC
986 Specifies the Flexible File I/O buffers for netCDF I/O when execut‐
987 ing under the UNICOS operating system (the variable is ignored on
988 other operating systems). An appropriate specification can greatly
989 increase the efficiency of netCDF I/O -- to the extent that it can
990 actually surpass FORTRAN binary I/O. This environment variable has
991 been made a little more generalized, such that other FFIO option
992 specifications can now be added. The default specification is bu‐
993 fa:336:2, unless a current FFIO specification is in operation,
994 which will be honored. See UNICOS Flexible File I/O for more in‐
995 formation.
996
998 Both a mailing list and a digest are available for discussion of the
999 netCDF interface and announcements about netCDF bugs, fixes, and en‐
1000 hancements. To begin or change your subscription to either the mail‐
1001 ing-list or the digest, send one of the following in the body (not the
1002 subject line) of an email message to "majordomo@unidata.ucar.edu". Use
1003 your email address in place of jdoe@host.inst.domain.
1004 To subscribe to the netCDF mailing list:
1006 subscribe netcdfgroup jdoe@host.inst.domain
1007 To unsubscribe from the netCDF mailing list:
1008 unsubscribe netcdfgroup jdoe@host.inst.domain
1009 To subscribe to the netCDF digest:
1010 subscribe netcdfdigest jdoe@host.inst.domain
1011 To unsubscribe from the netCDF digest:
1012 unsubscribe netcdfdigest jdoe@host.inst.domain
1013 To retrieve the general introductory information for the mailing list:
1014 info netcdfgroup
1015 To get a synopsis of other majordomo commands:
1016 help
1017
1019 ncdump(1), ncgen(1), netcdf(3), netcdf_f77(3), netcdf_f90(3)).
1020 netCDF User's Guide, published by the Unidata Program Center, Universi‐
1022 ty Corporation for Atmospheric Research, located in Boulder, Colorado.
1023Printed: 2019-06-22 1997-04-18 NETCDF(3)