1NETCDF(3)                  UNIDATA LIBRARY FUNCTIONS                 NETCDF(3)
2
3
4

NAME

6       netcdf - Unidata's Network Common Data Form (netCDF) library interface
7

SYNOPSIS

9       #include "netcdf.h"
10
11
12       cc ...  -lnetcdf -lhdf5_hl -lhdf5 -lz -lm
13
14       Complete  documentation  for  the  netCDF libraries can be found at the
15       netCDF website: http://www.unidata.ucar.edu/software/netcdf/.
16
17

LIBRARY VERSION

19       This document describes versions 3 and 4 of Unidata netCDF  data-access
20       interface for the C programming language.
21
22       const char* nc_inq_libvers()
23
24              Returns  a string identifying the version of the netCDF library,
25              and when it was built, like: "3.1a of Aug 22 1996 12:57:47 $".
26
27       The RCS ident(1) command will find a string like "$Id: @(#) netcdf  li‐
28       brary  version 3.1a of Sep  6 1996 15:56:26 $" in the library. The SCCS
29       what(1) command will find a string like "netcdf library version 3.1a of
30       Aug 23 1996 16:07:40 $".
31

RETURN VALUES

33       All netCDF functions (except nc_inq_libvers() and nc_strerror()) return
34       an integer status.
35
36       If this returned status value is not equal to NC_NOERR (zero), it indi‐
37       cates that an error occurred. The possible status values are defined in
38       system include file <errno.h> and in "netcdf.h".
39
40       const char* nc_strerror(int status)
41
42              Returns a string textual translation of the status  value,  like
43              "Attribute  or variable name contains illegal characters" or "No
44              such file or directory".
45
46

FILE OPERATIONS

48       int nc_create(const char path[], int cmode, int* ncid)
49
50              Creates a new netCDF dataset at path, returning a netCDF  ID  in
51              ncid.  The argument cmode may include the bitwise-or of the fol‐
52              lowing flags: NC_NOCLOBBER to protect existing datasets (default
53              silently  blows them away), NC_SHARE for synchronous dataset up‐
54              dates for classic format files (default is to buffer accesses),
55
56              When a netCDF dataset is created, is is  opened  NC_WRITE.   The
57              new netCDF dataset is in define mode.  NC_64BIT_OFFSET.  to cre‐
58              ate a file in the 64-bit offset format (as  opposed  to  classic
59              format,  the  default).  NC_TRUE to create a netCDF-4/HDF5 file,
60              and NC_CLASSIC_MODEL to guarantee that netCDF-4/HDF5 files main‐
61              tain compatibility with the netCDF classic data model.
62
63       int  nc__create(const  char  path[],  int  cmode,  size_t  initialsize,
64              size_t* chunksize, int* ncid)
65
66              Like nc_create() but has additional performance  tuning  parame‐
67              ters.
68
69              The  argument  initialsize  sets the initial size of the file at
70              creation time.
71
72              See nc__open() below for an explanation of the chunksize parame‐
73              ter.
74
75       int nc_open(const char path[], int mode, int* ncid)
76
77              (Corresponds to ncopen() in version 2)
78
79              Opens a existing netCDF dataset at path returning a netCDF ID in
80              ncid.  The type of access is described by  the  mode  parameter,
81              which  may  include  the  bitwise-or  of  the  following  flags:
82              NC_WRITE for read-write access (default read-only), NC_SHARE for
83              synchronous dataset updates (default is to buffer accesses), and
84              NC_LOCK (not yet implemented).
85
86              As of NetCDF version 4.1, and if TRUE support was  enabled  when
87              the  NetCDF  library was built, the path parameter may specify a
88              TRUE URL. In this case, the access mode is forced to be read-on‐
89              ly.
90
91       int nc__open(const char path[], int mode, size_t* chunksize, int* ncid)
92
93              Like  nc_open() but has an additional performance tuning parame‐
94              ter.
95
96              The argument referenced by chunksize  controls  a  space  versus
97              time  tradeoff,  memory  allocated  in the netcdf library versus
98              number of system calls.  Because of internal  requirements,  the
99              value may not be set to exactly the value requested.  The actual
100              value chosen is returned by reference.  Using the value NC_SIZE‐
101              HINT_DEFAULT  causes  the  library to choose a default.  How the
102              system choses the default depends on the system.  On  many  sys‐
103              tems,  the  "preferred  I/O  block  size"  is available from the
104              stat() system call, struct stat member st_blksize.  If  this  is
105              available it is used. Lacking that, twice the system pagesize is
106              used.  Lacking a call to discover the system pagesize,  we  just
107              set default chunksize to 8192.
108
109              The  chunksize  is  a property of a given open netcdf descriptor
110              ncid, it is not a persistent property of the netcdf dataset.
111
112              As with nc__open(), the path parameter may specify a  TRUE  URL,
113              but the tuning parameters are ignored.
114
115       int nc_redef(int ncid)
116
117              (Corresponds to ncredef() in version 2)
118
119              Puts  an  open  netCDF  dataset into define mode, so dimensions,
120              variables, and attributes can be added or renamed and attributes
121              can be deleted.
122
123       int nc_enddef(int ncid)
124
125              (Corresponds to ncendef() in version 2)
126
127              Takes  an  open  netCDF dataset out of define mode.  The changes
128              made to the netCDF dataset while  it  was  in  define  mode  are
129              checked and committed to disk if no problems occurred.  Some da‐
130              ta values may be written as well, see "VARIABLE PREFILLING"  be‐
131              low.   After  a  successful  call,  variable data can be read or
132              written to the dataset.
133
134       int nc__enddef(int  ncid,  size_t  h_minfree,  size_t  v_align,  size_t
135              v_minfree, size_t r_align)
136
137              Like  nc_enddef()  but has additional performance tuning parame‐
138              ters.
139
140              Caution: this function exposes internals of the netcdf version 1
141              file format.  It may not be available on future netcdf implemen‐
142              tations.
143
144              The current netcdf file format has three sections, the  "header"
145              section, the data section for fixed size variables, and the data
146              section for variables which have an unlimited dimension  (record
147              variables).  The header begins at the beginning of the file. The
148              index (offset) of the beginning of the  other  two  sections  is
149              contained  in  the  header. Typically, there is no space between
150              the sections. This causes copying  overhead  to  accrue  if  one
151              wishes  to  change  the size of the sections, as may happen when
152              changing names of things,  text  attribute  values,  adding  at‐
153              tributes  or adding variables. Also, for buffered i/o, there may
154              be advantages to aligning sections in certain ways.
155
156              The minfree parameters allow one  to  control  costs  of  future
157              calls  to  nc_redef(),  nc_enddef()  by  requesting that minfree
158              bytes be available at the end of the section.  The h_minfree pa‐
159              rameter  sets  the  pad  at the end of the "header" section. The
160              v_minfree parameter sets the pad at the end of the data  section
161              for fixed size variables.
162
163              The  align  parameters allow one to set the alignment of the be‐
164              ginning of the corresponding sections. The beginning of the sec‐
165              tion  is rounded up to an index which is a multiple of the align
166              parameter. The flag value NC_ALIGN_CHUNK tells  the  library  to
167              use  the  chunksize  (see  above)  as  the align parameter.  The
168              v_align parameter controls the alignment of the beginning of the
169              data  section  for  fixed size variables.  The r_align parameter
170              controls the alignment of the beginning of the data section  for
171              variables which have an unlimited dimension (record variables).
172
173              The  file  format requires mod 4 alignment, so the align parame‐
174              ters are silently rounded up to multiples of 4. The usual  call,
175              nc_enddef(ncid) is equivalent to nc__enddef(ncid, 0, 4, 0, 4).
176
177              The  file format does not contain a "record size" value, this is
178              calculated from the sizes of the record variables. This unfortu‐
179              nate  fact prevents us from providing minfree and alignment con‐
180              trol of the "records" in a netcdf file. If you  add  a  variable
181              which  has an unlimited dimension, the third section will always
182              be copied with the new variable added.
183
184       int nc_sync(int ncid)
185
186              (Corresponds to ncsync() in version 2)
187
188              Unless the NC_SHARE bit is set in nc_open() or nc_create(),  ac‐
189              cesses  to the underlying netCDF dataset are buffered by the li‐
190              brary. This function synchronizes the state  of  the  underlying
191              dataset   and  the  library.   This  is  done  automatically  by
192              nc_close() and nc_enddef().
193
194       int nc_abort(int ncid)
195
196              (Corresponds to ncabort() in version 2)
197
198              You don't need to call this function.  This function  is  called
199              automatically by nc_close() if the netCDF was in define mode and
200              something goes wrong with the commit.   If  the  netCDF  dataset
201              isn't  in  define  mode,  then  this  function  is equivalent to
202              nc_close().  If  it  is  called  after  nc_redef(),  but  before
203              nc_enddef(),  the  new  definitions  are  not  committed and the
204              dataset is closed.  If it is called after nc_create() but before
205              nc_enddef(), the dataset disappears.
206
207       int nc_close(int ncid)
208
209              (Corresponds to ncclose() in version 2)
210
211              Closes  an  open  netCDF  dataset.   If the dataset is in define
212              mode, nc_enddef()  will  be  called  before  closing.   After  a
213              dataset is closed, its ID may be reassigned to another dataset.
214
215       int  nc_inq(int  ncid,  int*  ndims,  int*  nvars, int* natts, int* un‐
216              limdimid)
217
218       int nc_inq_ndims(int ncid, int* ndims)
219
220       int nc_inq_nvars(int ncid, int* nvars)
221
222       int nc_inq_natts(int ncid, int* natts)
223
224       int nc_inq_unlimdim(int ncid, int* unlimdimid)
225
226       int nc_inq_format(int ncid, int* formatn)
227
228              Use these functions to find out what is  in  a  netCDF  dataset.
229              Upon successful return, ndims will contain  the number of dimen‐
230              sions defined for this netCDF dataset, nvars  will  contain  the
231              number  of  variables,  natts  will  contain  the  number of at‐
232              tributes, and unlimdimid will contain the dimension  ID  of  the
233              unlimited  dimension  if  one  exists, or -1 otherwise.  formatn
234              will contain the version number of the dataset <format>, one  of
235              NC_FORMAT_CLASSIC,    NC_FORMAT_64BIT,   NC_FORMAT_NETCDF4,   or
236              NC_FORMAT_NETCDF4_CLASSIC.  If any of the return parameters is a
237              NULL pointer, then the corresponding information will not be re‐
238              turned; hence, no space need be allocated for it.
239
240       int nc_def_dim(int ncid, const char name[], size_t len, int* dimid)
241
242              (Corresponds to ncdimdef() in version 2)
243
244              Adds a new dimension to an open netCDF dataset, which must be in
245              define  mode.   name  is  the dimension name.  If dimid is not a
246              NULL pointer then upon successful completion dimid will  contain
247              the dimension ID of the newly created dimension.
248
249

USER DEFINED TYPES

251       Users  many  define types for a netCDF-4/HDF5 file (unless the NC_CLAS‐
252       SIC_MODEL was used when the file was creates). Users  may  define  com‐
253       pound  types,  variable  length  arrays,  enumeration types, and opaque
254       types.
255
256
257
258       int nc_def_compound(int ncid, size_t  size,  const  char  name[],  int*
259              typeidp)
260
261              Define a compound type.
262
263       int  nc_insert_compound(int  ncid,  nc_type , const char name[], size_t
264              offset, nc_type field_typeid)
265
266              Insert an element into a compound type. May not  be  done  after
267              type  has  been  used,  or after the type has been written by an
268              enddef.
269
270       int nc_insert_array_compound(int ncid, nc_type  ,  const  char  name[],
271              size_t  offset,  nc_type  field_typeid,  int  ndims,  const  int
272              dim_sizes[])
273
274              Insert an array into a compound type.
275
276       int nc_inq_type(int ncid, nc_type , char name[], size_t* sizep)
277
278              Learn about a type.
279
280       int nc_inq_compound(int ncid, nc_type ,  char  name[],  size_t*  sizep,
281              size_t* nfieldsp)
282
283       int nc_inq_compound_name(int ncid, nc_type , char name[])
284
285       int nc_inq_compound_size(int ncid, nc_type , size_t* sizep)
286
287       int nc_inq_compound_nfields(int ncid, nc_type , size_t* nfieldsp)
288
289       int  nc_inq_compound_fieldname(int  ncid,  nc_type  , int fieldid, char
290              name[])
291
292       int nc_inq_compound_fieldindex(int ncid, nc_type , const  char  name[],
293              int* fieldidp)
294
295       int   nc_inq_compound_fieldoffset(int  ncid,  nc_type  ,  int  fieldid,
296              size_t* offsetp)
297
298       int nc_inq_compound_fieldtype(int ncid, nc_type , int fieldid, nc_type*
299              field_typeid)
300
301       int  nc_inq_compound_fieldndims(int  ncid,  nc_type , int fieldid, int*
302              ndims)
303
304       int nc_inq_compound_fielddim_sizes(int ncid, nc_type , int fieldid, int
305              dim_sizes[])
306
307              Learn about a compound type.
308
309       int  nc_def_vlen(int  ncid,  const  char  name[],  nc_type base_typeid,
310              nc_type* xtypep)
311
312              Create a varaible length array type.
313
314       int nc_inq_vlen(int ncid, nc_type , char name[],  size_t*  datum_sizep,
315              nc_type* base_nc_typep)
316
317              Learn about a varaible length array type.
318
319       int nc_free_vlen(nc_vlen_t *vl)
320
321              Free  memory comsumed by reading data of a varaible length array
322              type.
323
324       int nc_put_vlen_element(int ncid, nc_type , void * vlen_element, size_t
325              len, void * data)
326
327              Write one VLEN.
328
329       int  nc_get_vlen_element(int  ncid,  nc_type  ,  void  ** vlen_element,
330              size_t len, void ** data)
331
332              Read one VLEN.
333
334       int nc_free_string(size_t len, char **data)
335
336              Free memory comsumed by reading data of a string type.
337
338       int  nc_inq_user_type(int  ncid,  nc_type  ,  char  name[],  size_t*  ,
339              nc_type* , size_t* , int* )
340
341              Learn about a user define type.
342
343       int  nc_def_enum(int  ncid,  nc_type  base_typeid,  const  char name[],
344              nc_type* typeidp)
345
346              Define an enumeration type.
347
348       int nc_insert_enum(int ncid, nc_type base_typeid,  const  char  name[],
349              const void *value)
350
351              Insert a name-value pair into enumeration type.
352
353       int  nc_inq_enum_member(int  ncid, nc_type xtype, int idx, char name[],
354              void *value)
355
356       int nc_inq_enum_ident(int ncid, nc_type xtype, int idx, long long  val‐
357              ue, char identifier[])
358
359              Learn about a name-value pair into enumeration type.
360
361       int  nc_def_opaque(int  ncid,  size_t size, const char name[], nc_type*
362              xtypep)
363
364              Create an opaque type.
365
366       int nc_inq_opaque(int ncid, nc_type xtype, char name[], size_t* sizep)
367
368              Learn about opaque type.
369
370
371

GROUPS

373       Users may organize data into hierarchical groups in netCDF-4/HDF5 files
374       (unless NC_CLASSIC_MODEL was used when creating the file).
375
376       int nc_inq_grps(int ncid, int* numgrps, int ncids[])
377
378              Learn  how  many groups (and their ncids) are available from the
379              group represented by ncid.
380
381       int nc_inq_grpname(int ncid, char name[])
382
383       int nc_inq_grpname_full(int ncid, size_t* len, char name[])
384
385       int nc_inq_grpname_len(int ncid, size_t* len)
386
387       int nc_inq_grp_parent(int ncid, int* ncid)
388
389       int nc_inq_grp_ncid(int ncid, char name[], int* ncid)
390
391       int nc_inq_full_ncid(int ncid, char name[], int* ncid)
392
393              Learn about a group.
394
395       int nc_inq_varids(int ncid, int* nvars, int* )
396
397              Get the varids in a group.
398
399       int nc_inq_dimids(int ncid, int* ndims, int* dimids,  int  include_par‐
400              ents)
401
402              Get the dimids in a group and (potentially) its parents.
403
404       int nc_inq_typeids(int ncid, int* ntypes, int typeids[])
405
406              Get the typeids of user-defined types in a group.
407
408       int nc_def_grp(int ncid, char name[], int* ncid)
409
410              Create a group.
411

DIMENSIONS

413       int nc_inq_dimid(int ncid, const char name[], int* dimid)
414
415              (Corresponds to ncdimid() in version 2)
416
417              Given  a dimension name, returns the ID of a netCDF dimension in
418              dimid.
419
420       int nc_inq_dim(int ncid, int dimid, char name[], size_t* len)
421
422       int nc_inq_dimname(int ncid, int dimid, char name[])
423
424       int nc_inq_dimlen(int ncid, int dimid, size_t* len)
425
426              Use these functions to find out about a  dimension.   If  either
427              the  name  argument  or len argument is a NULL pointer, then the
428              associated information will not be  returned.   Otherwise,  name
429              should  be   big enough (NC_MAX_NAME) to hold the dimension name
430              as the name will be copied into your storage.  The length return
431              parameter,  len will contain the size of the dimension.  For the
432              unlimited dimension, the returned length is the current  maximum
433              value  used  for writing into any of the variables which use the
434              dimension.
435
436       int nc_rename_dim(int ncid, int dimid, const char name[])
437
438              (Corresponds to ncdimrename() in version 2)
439
440              Renames an existing dimension in an open netCDF dataset.  If the
441              new name is longer than the old name, the netCDF dataset must be
442              in define mode.  You cannot rename a dimension to have the  same
443              name as another dimension.
444

VARIABLES

446       int  nc_def_var(int  ncid, const char name[], nc_type xtype, int ndims,
447              const int dimids[], int* varid)
448
449              (Corresponds to ncvardef() in version 2)
450
451              Adds a new variable to a netCDF dataset. The netCDF must  be  in
452              define  mode.  If not NULL, then varid will be set to the netCDF
453              variable ID.
454
455       int nc_inq_varid(int ncid, const char name[], int* varid)
456
457              (Corresponds to ncvarid() in version 2)
458
459              Returns the ID of a netCDF variable in varid given its name.
460
461       int nc_inq_var(int ncid, int varid, char name[], nc_type*  xtype,  int*
462              ndims, int dimids[], int* natts)
463
464       int nc_inq_varname(int ncid, int varid, char name[])
465
466       int nc_inq_vartype(int ncid, int varid, nc_type* xtype)
467
468       int nc_inq_varndims(int ncid, int varid, int* ndims)
469
470       int nc_inq_vardimid(int ncid, int varid, int dimids[])
471
472       int nc_inq_varnatts(int ncid, int varid, int* natts)
473
474              Returns  information  about a netCDF variable, given its ID.  If
475              any of the return parameters (name,  xtype,  ndims,  dimids,  or
476              natts)  is  a  NULL  pointer, then the corresponding information
477              will not be returned; hence, no space need be allocated for it.
478
479       int nc_rename_var(int ncid, int varid, const char name[])
480
481              (Corresponds to ncvarrename() in version 2)
482
483              Changes the name of a netCDF  variable.   If  the  new  name  is
484              longer  than  the  old  name, the netCDF must be in define mode.
485              You cannot rename a variable to have the name  of  any  existing
486              variable.
487
488

VARIABLES in NETCDF-4 FILES

490       The   following   functions   may  only  be  used  on  variables  in  a
491       netCDF-4/HDF5 data file. These functions must be called after the vari‐
492       able is defined, but before an enddef call.
493
494       int  nc_def_var_deflate(int  ncid, int varid, int shuffle, int deflate,
495       int deflate_level)
496
497       Turn on compression and/or shuffle filter. (Shuffle filter is only use‐
498       ful for integer data.)
499
500       int  nc_inq_var_deflate(int  ncid,  int  varid, int* shufflep, int* de‐
501              flatep, int* deflate_levelp)
502
503              Learn about a variable's deflate settings.
504
505       int nc_def_var_fletcher32(int ncid, int varid, int fletcher32)
506
507              Turn on checksumming for a variable.
508
509       int nc_inq_var_fletcher32(int ncid, int varid, int* fletcher32)
510
511              Learn about checksumming for a variable.
512
513       int nc_def_var_chunking(int ncid, int varid, int storage, const  size_t
514              chunksizesp[])
515
516              Set chunksizes for a variable.
517
518       int  nc_inq_var_chunking(int  ncid,  int  varid,  int* storagep, size_t
519              chunksizesp[])
520
521              Learn about chunksizes for a variable.
522
523       int nc_def_var_fill(int ncid, int  varid,  int  no_fill,  const  size_t
524              chunksizesp[])
525
526              Set a fill value for a variable.
527
528       int  nc_inq_var_fill(int  ncid, int varid, int* storagep, size_t chunk‐
529              sizesp[])
530
531              Learn the fill value for a variable.
532
533       int nc_def_var_endian(int ncid, int varid, int endian)
534
535              Set endianness of variable.
536
537       int nc_inq_var_endian(int ncid, int varid, int* endianp)
538
539              Learn the endianness of a variable.
540
541
542
543

WRITING AND READING WHOLE VARIABLES

545       int nc_put_var_text(int ncid, int varid, const char out[])
546
547       int nc_put_var_uchar(int ncid, int varid, const unsigned char out[])
548
549       int nc_put_var_schar(int ncid, int varid, const signed char out[])
550
551       int nc_put_var_short(int ncid, int varid, const short out[])
552
553       int nc_put_var_int(int ncid, int varid, const int out[])
554
555       int nc_put_var_long(int ncid, int varid, const long out[])
556
557       int nc_put_var_float(int ncid, int varid, const float out[])
558
559       int nc_put_var_double(int ncid, int varid, const double out[])
560
561       int nc_put_var_ubyte(int ncid, int varid, const unsigned char out[])
562
563       int nc_put_var_ushort(int ncid, int varid, const unsigned short out[])
564
565       int nc_put_var_uint(int ncid, int varid, const unsigned int out[])
566
567       int nc_put_var_int64(int ncid, int varid, const long long out[])
568
569       int nc_put_var_uint64(int ncid, int varid,  const  unsigned  long  long
570              out[])
571
572       int nc_put_var_string(int ncid, int varid, const char * out[])
573
574
575
576              Writes  an  entire  netCDF  variable (i.e. all the values).  The
577              netCDF dataset must be open and in data mode.  The type  of  the
578              data  is  specified in the function name, and it is converted to
579              the external type of the specified variable, if possible, other‐
580              wise  an  NC_ERANGE error is returned. Note that rounding is not
581              performed during the  conversion.  Floating  point  numbers  are
582              truncated when converted to integers.
583
584       int nc_get_var_text(int ncid, int varid, char in[])
585
586       int nc_get_var_uchar(int ncid, int varid, unsigned char in[])
587
588       int nc_get_var_schar(int ncid, int varid, signed char in[])
589
590       int nc_get_var_short(int ncid, int varid, short in[])
591
592       int nc_get_var_int(int ncid, int varid, int in[])
593
594       int nc_get_var_long(int ncid, int varid, long in[])
595
596       int nc_get_var_float(int ncid, int varid, float in[])
597
598       int nc_get_var_double(int ncid, int varid, double in[])
599
600       int nc_get_var_ubyte(int ncid, int varid, unsigned char in[])
601
602       int nc_get_var_ushort(int ncid, int varid, unsigned short in[])
603
604       int nc_get_var_uint(int ncid, int varid, unsigned int in[])
605
606       int nc_get_var_int64(int ncid, int varid, long long in[])
607
608       int nc_get_var_uint64(int ncid, int varid, unsigned long long in[])
609
610       int nc_get_var_string(int ncid, int varid, char * in[])
611
612
613
614              Reads  an  entire  netCDF  variable  (i.e. all the values).  The
615              netCDF dataset must be open and in data mode.  The data is  con‐
616              verted from the external type of the specified variable, if nec‐
617              essary, to the type specified in the function name.  If  conver‐
618              sion is not possible, an NC_ERANGE error is returned.
619

WRITING AND READING ONE DATUM

621       int  nc_put_var1_text(int  ncid,  int varid, const size_t index[], char
622              *out)
623
624       int nc_put_var1_uchar(int ncid, int varid, const  size_t  index[],  un‐
625              signed char *out)
626
627       int nc_put_var1_schar(int ncid, int varid, const size_t index[], signed
628              char *out)
629
630       int nc_put_var1_short(int ncid, int varid, const size_t index[],  short
631              *out)
632
633       int  nc_put_var1_int(int  ncid,  int  varid,  const size_t index[], int
634              *out)
635
636       int nc_put_var1_long(int ncid, int varid, const  size_t  index[],  long
637              *out)
638
639       int  nc_put_var1_float(int ncid, int varid, const size_t index[], float
640              *out)
641
642       int nc_put_var1_double(int ncid, int varid, const size_t index[],  dou‐
643              ble *out)
644
645       int  nc_put_var1_ubyte(int  ncid,  int varid, const size_t index[], un‐
646              signed char *out)
647
648       int nc_put_var1_ushort(int ncid, int varid, const size_t  index[],  un‐
649              signed short *out)
650
651       int  nc_put_var1_uint(int  ncid,  int  varid, const size_t index[], un‐
652              signed int *out)
653
654       int nc_put_var1_int64(int ncid, int varid, const size_t  index[],  long
655              long *out)
656
657       int  nc_put_var1_uint64(int  ncid, int varid, const size_t index[], un‐
658              signed long long *out)
659
660       int nc_put_var1_string(int ncid, int varid, const size_t index[],  char
661              * *out)
662
663
664
665              Puts  a  single data value into a variable at the position index
666              of an open netCDF dataset that is in data mode.  The type of the
667              data  is  specified in the function name, and it is converted to
668              the external type of the specified variable, if possible, other‐
669              wise an NC_ERANGE error is returned.
670
671       int  nc_get_var1_text(int  ncid, int varid, const size_t index[], char*
672              in)
673
674       int nc_get_var1_uchar(int ncid, int varid, const  size_t  index[],  un‐
675              signed char* in)
676
677       int nc_get_var1_schar(int ncid, int varid, const size_t index[], signed
678              char* in)
679
680       int nc_get_var1_short(int ncid, int varid, const size_t index[], short*
681              in)
682
683       int nc_get_var1_int(int ncid, int varid, const size_t index[], int* in)
684
685       int  nc_get_var1_long(int  ncid, int varid, const size_t index[], long*
686              in)
687
688       int nc_get_var1_float(int ncid, int varid, const size_t index[], float*
689              in)
690
691       int  nc_get_var1_double(int ncid, int varid, const size_t index[], dou‐
692              ble* in)
693
694       int nc_get_var1_ubyte(int ncid, int varid, const  size_t  index[],  un‐
695              signed char* in)
696
697       int  nc_get_var1_ushort(int  ncid, int varid, const size_t index[], un‐
698              signed short* in)
699
700       int nc_get_var1_uint(int ncid, int varid,  const  size_t  index[],  un‐
701              signed int* in)
702
703       int  nc_get_var1_int64(int  ncid, int varid, const size_t index[], long
704              long* in)
705
706       int nc_get_var1_uint64(int ncid, int varid, const size_t  index[],  un‐
707              signed long long* in)
708
709       int  nc_get_var1_string(int ncid, int varid, const size_t index[], char
710              ** in)
711
712
713
714              Gets a single data value from a variable at the  position  index
715              of  an  open  netCDF  dataset that is in data mode.  The data is
716              converted from the external type of the specified  variable,  if
717              necessary,  to the type specified in the function name.  If con‐
718              version is not possible, an NC_ERANGE error is returned.
719

WRITING AND READING AN ARRAY

721       int nc_put_vara_text(int ncid, int varid, const size_t  start[],  const
722              size_t count[], const char out[])
723
724       int  nc_put_vara_uchar(int ncid, int varid, const size_t start[], const
725              size_t count[], const unsigned char out[])
726
727       int nc_put_vara_schar(int ncid, int varid, const size_t start[],  const
728              size_t count[], const signed char out[])
729
730       int  nc_put_vara_short(int ncid, int varid, const size_t start[], const
731              size_t count[], const short out[])
732
733       int nc_put_vara_int(int ncid, int varid, const  size_t  start[],  const
734              size_t count[], const int out[])
735
736       int  nc_put_vara_long(int  ncid, int varid, const size_t start[], const
737              size_t count[], const long out[])
738
739       int nc_put_vara_float(int ncid, int varid, const size_t start[],  const
740              size_t count[], const float out[])
741
742       int nc_put_vara_double(int ncid, int varid, const size_t start[], const
743              size_t count[], const double out[])
744
745       int nc_put_vara_ubyte(int ncid, int varid, const size_t start[],  const
746              size_t count[], const unsigned char out[])
747
748       int nc_put_vara_ushort(int ncid, int varid, const size_t start[], const
749              size_t count[], const unsigned short out[])
750
751       int nc_put_vara_uint(int ncid, int varid, const size_t  start[],  const
752              size_t count[], const unsigned int out[])
753
754       int  nc_put_vara_int64(int ncid, int varid, const size_t start[], const
755              size_t count[], const long long out[])
756
757       int nc_put_vara_uint64(int ncid, int varid, const size_t start[], const
758              size_t count[], const unsigned long long out[])
759
760       int nc_put_vara_string(int ncid, int varid, const size_t start[], const
761              size_t count[], const char * out[])
762
763
764
765              Writes an array section of values into a netCDF variable  of  an
766              open netCDF dataset, which must be in data mode.  The array sec‐
767              tion is specified by the start and count vectors, which give the
768              starting  index  and count of values along each dimension of the
769              specified variable.  The type of the data is  specified  in  the
770              function name and is converted to the external type of the spec‐
771              ified variable, if possible, otherwise an NC_ERANGE error is re‐
772              turned.
773
774       int  nc_get_vara_text(int  ncid, int varid, const size_t start[], const
775              size_t count[], char in[])
776
777       int nc_get_vara_uchar(int ncid, int varid, const size_t start[],  const
778              size_t count[], unsigned char in[])
779
780       int  nc_get_vara_schar(int ncid, int varid, const size_t start[], const
781              size_t count[], signed char in[])
782
783       int nc_get_vara_short(int ncid, int varid, const size_t start[],  const
784              size_t count[], short in[])
785
786       int  nc_get_vara_int(int  ncid,  int varid, const size_t start[], const
787              size_t count[], int in[])
788
789       int nc_get_vara_long(int ncid, int varid, const size_t  start[],  const
790              size_t count[], long in[])
791
792       int  nc_get_vara_float(int ncid, int varid, const size_t start[], const
793              size_t count[], float in[])
794
795       int nc_get_vara_double(int ncid, int varid, const size_t start[], const
796              size_t count[], double in[])
797
798       int  nc_get_vara_ubyte(int ncid, int varid, const size_t start[], const
799              size_t count[], unsigned char in[])
800
801       int nc_get_vara_ushort(int ncid, int varid, const size_t start[], const
802              size_t count[], unsigned short in[])
803
804       int  nc_get_vara_uint(int  ncid, int varid, const size_t start[], const
805              size_t count[], unsigned int in[])
806
807       int nc_get_vara_int64(int ncid, int varid, const size_t start[],  const
808              size_t count[], long long in[])
809
810       int nc_get_vara_uint64(int ncid, int varid, const size_t start[], const
811              size_t count[], unsigned long long in[])
812
813       int nc_get_vara_string(int ncid, int varid, const size_t start[], const
814              size_t count[], char * in[])
815
816
817
818              Reads  an  array  section of values from a netCDF variable of an
819              open netCDF dataset, which must be in data mode.  The array sec‐
820              tion is specified by the start and count vectors, which give the
821              starting index and count of values along each dimension  of  the
822              specified  variable.   The  data  is converted from the external
823              type of the specified variable, if necessary, to the type speci‐
824              fied  in  the  function name.  If conversion is not possible, an
825              NC_ERANGE error is returned.
826

WRITING AND READING A SLICED ARRAY

828       int nc_put_vars_text(int ncid, int varid, const size_t  start[],  const
829              size_t count[], const size_t stride[], const char out[])
830
831       int  nc_put_vars_uchar(int ncid, int varid, const size_t start[], const
832              size_t count[],  const  size_t  stride[],  const  unsigned  char
833              out[])
834
835       int  nc_put_vars_schar(int ncid, int varid, const size_t start[], const
836              size_t count[], const size_t stride[], const signed char out[])
837
838       int nc_put_vars_short(int ncid, int varid, const size_t start[],  const
839              size_t count[], const size_t stride[], const short out[])
840
841       int  nc_put_vars_int(int  ncid,  int varid, const size_t start[], const
842              size_t count[], const size_t stride[], const int out[])
843
844       int nc_put_vars_long(int ncid, int varid, const size_t  start[],  const
845              size_t count[], const size_t stride[], const long out[])
846
847       int  nc_put_vars_float(int ncid, int varid, const size_t start[], const
848              size_t count[], const size_t stride[], const float out[])
849
850       int nc_put_vars_double(int ncid, int varid, const size_t start[], const
851              size_t count[], const size_t stride[], const double out[])
852
853       int  nc_put_vars_ubyte(int ncid, int varid, const size_t start[], const
854              size_t count[],  const  size_t  stride[],  const  unsigned  char
855              out[])
856
857       int nc_put_vars_ushort(int ncid, int varid, const size_t start[], const
858              size_t count[], const  size_t  stride[],  const  unsigned  short
859              out[])
860
861       int  nc_put_vars_uint(int  ncid, int varid, const size_t start[], const
862              size_t count[], const size_t stride[], const unsigned int out[])
863
864       int nc_put_vars_int64(int ncid, int varid, const size_t start[],  const
865              size_t count[], const size_t stride[], const long long out[])
866
867       int nc_put_vars_uint64(int ncid, int varid, const size_t start[], const
868              size_t count[], const size_t stride[], const unsigned long  long
869              out[])
870
871       int nc_put_vars_string(int ncid, int varid, const size_t start[], const
872              size_t count[], const size_t stride[], const char * out[])
873
874
875
876              These functions are used for strided output, which is  like  the
877              array  section  output described above, except that the sampling
878              stride (the interval between accessed values) is  specified  for
879              each  dimension.  For an explanation of the sampling stride vec‐
880              tor, see COMMON ARGUMENTS DESCRIPTIONS below.
881
882       int nc_get_vars_text(int ncid, int varid, const size_t  start[],  const
883              size_t count[], const size_t stride[], char in[])
884
885       int  nc_get_vars_uchar(int ncid, int varid, const size_t start[], const
886              size_t count[], const size_t stride[], unsigned char in[])
887
888       int nc_get_vars_schar(int ncid, int varid, const size_t start[],  const
889              size_t count[], const size_t stride[], signed char in[])
890
891       int  nc_get_vars_short(int ncid, int varid, const size_t start[], const
892              size_t count[], const size_t stride[], short in[])
893
894       int nc_get_vars_int(int ncid, int varid, const  size_t  start[],  const
895              size_t count[], const size_t stride[], int in[])
896
897       int  nc_get_vars_long(int  ncid, int varid, const size_t start[], const
898              size_t count[], const size_t stride[], long in[])
899
900       int nc_get_vars_float(int ncid, int varid, const size_t start[],  const
901              size_t count[], const size_t stride[], float in[])
902
903       int nc_get_vars_double(int ncid, int varid, const size_t start[], const
904              size_t count[], const size_t stride[], double in[])
905
906       int nc_get_vars_ubyte(int ncid, int varid, const size_t start[],  const
907              size_t count[], const size_t stride[], unsigned char in[])
908
909       int nc_get_vars_ushort(int ncid, int varid, const size_t start[], const
910              size_t count[], const size_t stride[], unsigned short in[])
911
912       int nc_get_vars_uint(int ncid, int varid, const size_t  start[],  const
913              size_t count[], const size_t stride[], unsigned int in[])
914
915       int  nc_get_vars_int64(int ncid, int varid, const size_t start[], const
916              size_t count[], const size_t stride[], long long in[])
917
918       int nc_get_vars_uint64(int ncid, int varid, const size_t start[], const
919              size_t count[], const size_t stride[], unsigned long long in[])
920
921       int nc_get_vars_string(int ncid, int varid, const size_t start[], const
922              size_t count[], const size_t stride[], char * in[])
923
924
925
926              These functions are used for strided input, which  is  like  the
927              array  section  input  described above, except that the sampling
928              stride (the interval between accessed values) is  specified  for
929              each  dimension.  For an explanation of the sampling stride vec‐
930              tor, see COMMON ARGUMENTS DESCRIPTIONS below.
931

WRITING AND READING A MAPPED ARRAY

933       int nc_put_varm_text(int ncid, int varid, const size_t  start[],  const
934              size_t count[], const size_t stride[], imap, const char out[])
935
936       int  nc_put_varm_uchar(int ncid, int varid, const size_t start[], const
937              size_t count[], const size_t stride[], imap, const unsigned char
938              out[])
939
940       int  nc_put_varm_schar(int ncid, int varid, const size_t start[], const
941              size_t count[], const size_t stride[], imap, const  signed  char
942              out[])
943
944       int  nc_put_varm_short(int ncid, int varid, const size_t start[], const
945              size_t count[], const size_t stride[], imap, const short out[])
946
947       int nc_put_varm_int(int ncid, int varid, const  size_t  start[],  const
948              size_t count[], const size_t stride[], imap, const int out[])
949
950       int  nc_put_varm_long(int  ncid, int varid, const size_t start[], const
951              size_t count[], const size_t stride[], imap, const long out[])
952
953       int nc_put_varm_float(int ncid, int varid, const size_t start[],  const
954              size_t count[], const size_t stride[], imap, const float out[])
955
956       int nc_put_varm_double(int ncid, int varid, const size_t start[], const
957              size_t count[], const size_t stride[], imap, const double out[])
958
959       int nc_put_varm_ubyte(int ncid, int varid, const size_t start[],  const
960              size_t count[], const size_t stride[], imap, const unsigned char
961              out[])
962
963       int nc_put_varm_ushort(int ncid, int varid, const size_t start[], const
964              size_t  count[],  const  size_t  stride[],  imap, const unsigned
965              short out[])
966
967       int nc_put_varm_uint(int ncid, int varid, const size_t  start[],  const
968              size_t  count[], const size_t stride[], imap, const unsigned int
969              out[])
970
971       int nc_put_varm_int64(int ncid, int varid, const size_t start[],  const
972              size_t  count[],  const  size_t  stride[], imap, const long long
973              out[])
974
975       int nc_put_varm_uint64(int ncid, int varid, const size_t start[], const
976              size_t count[], const size_t stride[], imap, const unsigned long
977              long out[])
978
979       int nc_put_varm_string(int ncid, int varid, const size_t start[], const
980              size_t count[], const size_t stride[], imap, const char * out[])
981
982
983
984              These functions are used for mapped output, which is like strid‐
985              ed output described above, except that an additional index  map‐
986              ping  vector is provided to specify the in-memory arrangement of
987              the data values.  For an explanation of the index  mapping  vec‐
988              tor, see COMMON ARGUMENTS DESCRIPTIONS below.
989
990       int  nc_get_varm_text(int  ncid, int varid, const size_t start[], const
991              size_t count[], const size_t stride[], imap, char in[])
992
993       int nc_get_varm_uchar(int ncid, int varid, const size_t start[],  const
994              size_t count[], const size_t stride[], imap, unsigned char in[])
995
996       int  nc_get_varm_schar(int ncid, int varid, const size_t start[], const
997              size_t count[], const size_t stride[], imap, signed char in[])
998
999       int nc_get_varm_short(int ncid, int varid, const size_t start[],  const
1000              size_t count[], const size_t stride[], imap, short in[])
1001
1002       int  nc_get_varm_int(int  ncid,  int varid, const size_t start[], const
1003              size_t count[], const size_t stride[], imap, int in[])
1004
1005       int nc_get_varm_long(int ncid, int varid, const size_t  start[],  const
1006              size_t count[], const size_t stride[], imap, long in[])
1007
1008       int  nc_get_varm_float(int ncid, int varid, const size_t start[], const
1009              size_t count[], const size_t stride[], imap, float in[])
1010
1011       int nc_get_varm_double(int ncid, int varid, const size_t start[], const
1012              size_t count[], const size_t stride[], imap, double in[])
1013
1014       int  nc_get_varm_ubyte(int ncid, int varid, const size_t start[], const
1015              size_t count[], const size_t stride[], imap, unsigned char in[])
1016
1017       int nc_get_varm_ushort(int ncid, int varid, const size_t start[], const
1018              size_t  count[],  const  size_t  stride[],  imap, unsigned short
1019              in[])
1020
1021       int nc_get_varm_uint(int ncid, int varid, const size_t  start[],  const
1022              size_t count[], const size_t stride[], imap, unsigned int in[])
1023
1024       int  nc_get_varm_int64(int ncid, int varid, const size_t start[], const
1025              size_t count[], const size_t stride[], imap, long long in[])
1026
1027       int nc_get_varm_uint64(int ncid, int varid, const size_t start[], const
1028              size_t  count[], const size_t stride[], imap, unsigned long long
1029              in[])
1030
1031       int nc_get_varm_string(int ncid, int varid, const size_t start[], const
1032              size_t count[], const size_t stride[], imap, char * in[])
1033
1034
1035
1036              These functions are used for mapped input, which is like strided
1037              input described above, except that an additional  index  mapping
1038              vector  is  provided to specify the in-memory arrangement of the
1039              data values.  For an explanation of the  index  mapping  vector,
1040              see COMMON ARGUMENTS DESCRIPTIONS below.
1041

ATTRIBUTES

1043       int  nc_put_att_text(int  ncid,  int  varid, const char name[], nc_type
1044              xtype, size_t len, const char out[])
1045
1046       int nc_put_att_uchar(int ncid, int varid, const  char  name[],  nc_type
1047              xtype, size_t len, const unsigned char out[])
1048
1049       int  nc_put_att_schar(int  ncid,  int varid, const char name[], nc_type
1050              xtype, size_t len, const signed char out[])
1051
1052       int nc_put_att_short(int ncid, int varid, const  char  name[],  nc_type
1053              xtype, size_t len, const short out[])
1054
1055       int  nc_put_att_int(int  ncid,  int  varid,  const char name[], nc_type
1056              xtype, size_t len, const int out[])
1057
1058       int nc_put_att_long(int ncid, int varid,  const  char  name[],  nc_type
1059              xtype, size_t len, const long out[])
1060
1061       int  nc_put_att_float(int  ncid,  int varid, const char name[], nc_type
1062              xtype, size_t len, const float out[])
1063
1064       int nc_put_att_double(int ncid, int varid, const char  name[],  nc_type
1065              xtype, size_t len, const double out[])
1066
1067       int  nc_put_att_ubyte(int  ncid,  int varid, const char name[], nc_type
1068              xtype, size_t len, const unsigned char out[])
1069
1070       int nc_put_att_ushort(int ncid, int varid, const char  name[],  nc_type
1071              xtype, size_t len, const unsigned short out[])
1072
1073       int  nc_put_att_uint(int  ncid,  int  varid, const char name[], nc_type
1074              xtype, size_t len, const unsigned int out[])
1075
1076       int nc_put_att_int64(int ncid, int varid, const  char  name[],  nc_type
1077              xtype, size_t len, const long long out[])
1078
1079       int  nc_put_att_uint64(int  ncid, int varid, const char name[], nc_type
1080              xtype, size_t len, const unsigned long long out[])
1081
1082       int nc_put_att_string(int ncid, int varid, const char  name[],  nc_type
1083              xtype, size_t len, const char * out[])
1084
1085
1086
1087       int  nc_put_att(int  ncid, int varid, const char name[], nc_type xtype,
1088              size_t len, void * ip)
1089
1090       int nc_get_att(int ncid, int varid, const char name[], void ** ip)
1091
1092              Unlike variables, attributes do not have separate functions  for
1093              defining and writing values.  This family of functions defines a
1094              new attribute with a value or changes the value of  an  existing
1095              attribute.  If the attribute is new, or if the space required to
1096              store the attribute value is greater  than  before,  the  netCDF
1097              dataset must be in define mode.  The parameter len is the number
1098              of values from out to transfer.  It is often  one,  except  that
1099              for nc_put_att_text() it will usually be strlen(out).
1100
1101              For  these  functions,  the  type component of the function name
1102              refers to the in-memory type of the value, whereas the xtype ar‐
1103              gument  refers  to  the external type for storing the value.  An
1104              NC_ERANGE error results if a conversion between these  types  is
1105              not  possible.   In  this case the value is represented with the
1106              appropriate fill-value for the associated external type.
1107
1108       int nc_inq_attname(int ncid, int varid, int attnum, char name[])
1109
1110              Gets the name of an attribute, given its  variable  ID  and  at‐
1111              tribute number.  This function is useful in generic applications
1112              that need to get the names of all the attributes associated with
1113              a  variable,  since  attributes are accessed by name rather than
1114              number in all other attribute functions.  The number of  an  at‐
1115              tribute is more volatile than the name, since it can change when
1116              other attributes of the same  variable  are  deleted.   The  at‐
1117              tributes  for  each  variable are numbered from 0 (the first at‐
1118              tribute) to nvatts-1, where nvatts is the number  of  attributes
1119              for  the variable, as returned from a call to nc_inq_varnatts().
1120              If the name parameter is a NULL pointer, no  name  will  be  re‐
1121              turned and no space need be allocated.
1122
1123       int  nc_inq_att(int ncid, int varid, const char name[], nc_type* xtype,
1124              size_t* len)
1125
1126       int nc_inq_attid(int ncid, int varid, const char name[], int* attnum)
1127
1128       int nc_inq_atttype(int ncid, int varid,  const  char  name[],  nc_type*
1129              xtype)
1130
1131       int nc_inq_attlen(int ncid, int varid, const char name[], size_t* len)
1132
1133              These  functions  return  information  about a netCDF attribute,
1134              given its variable ID and name.  The information returned is the
1135              external  type  in  xtype  and the number of elements in the at‐
1136              tribute as len.  If any of the return arguments is a NULL point‐
1137              er, the specified information will not be returned.
1138
1139       int   nc_copy_att(int  ncid,  int  varid_in,  const  char  name[],  int
1140              ncid_out, int varid_out)
1141
1142              Copies an attribute from one netCDF dataset to another.  It  can
1143              also  be  used to copy an attribute from one variable to another
1144              within the same netCDF.  ncid_in is the netCDF ID  of  an  input
1145              netCDF   dataset  from  which  the  attribute  will  be  copied.
1146              varid_in is the ID of the variable in the input  netCDF  dataset
1147              from  which  the  attribute  will  be copied, or NC_GLOBAL for a
1148              global attribute.  name is the name of the attribute in the  in‐
1149              put  netCDF  dataset to be copied.  ncid_out is the netCDF ID of
1150              the output netCDF dataset to which the attribute will be copied.
1151              It is permissible for the input and output netCDF ID's to be the
1152              same.  The output netCDF dataset should be in define mode if the
1153              attribute  to  be  copied  does not already exist for the target
1154              variable, or if it would cause an existing target  attribute  to
1155              grow.   varid_out is the ID of the variable in the output netCDF
1156              dataset to which the attribute will be copied, or  NC_GLOBAL  to
1157              copy to a global attribute.
1158
1159       int  nc_rename_att(int  ncid,  int varid, const char name[], const char
1160              newname[])
1161
1162              Changes the name of an attribute.  If the  new  name  is  longer
1163              than  the original name, the netCDF must be in define mode.  You
1164              cannot rename an attribute to have the same name as another  at‐
1165              tribute  of  the  same variable.  name is the original attribute
1166              name.  newname is the new name to be assigned to  the  specified
1167              attribute.   If  the  new  name is longer than the old name, the
1168              netCDF dataset must be in define mode.
1169
1170       int nc_del_att(int ncid, int varid, const char name[])
1171
1172              Deletes an attribute from a netCDF dataset.  The dataset must be
1173              in define mode.
1174
1175       int nc_get_att_text(int ncid, int varid, const char name[], char in[])
1176
1177       int  nc_get_att_uchar(int  ncid, int varid, const char name[], unsigned
1178              char in[])
1179
1180       int nc_get_att_schar(int ncid, int varid,  const  char  name[],  signed
1181              char in[])
1182
1183       int  nc_get_att_short(int  ncid,  int  varid,  const char name[], short
1184              in[])
1185
1186       int nc_get_att_int(int ncid, int varid, const char name[], int in[])
1187
1188       int nc_get_att_long(int ncid, int varid, const char name[], long in[])
1189
1190       int nc_get_att_float(int ncid, int  varid,  const  char  name[],  float
1191              in[])
1192
1193       int  nc_get_att_double(int  ncid,  int varid, const char name[], double
1194              in[])
1195
1196       int nc_get_att_ubyte(int ncid, int varid, const char  name[],  unsigned
1197              char in[])
1198
1199       int  nc_get_att_ushort(int ncid, int varid, const char name[], unsigned
1200              short in[])
1201
1202       int nc_get_att_uint(int ncid, int varid, const  char  name[],  unsigned
1203              int in[])
1204
1205       int  nc_get_att_int64(int ncid, int varid, const char name[], long long
1206              in[])
1207
1208       int nc_get_att_uint64(int ncid, int varid, const char name[],  unsigned
1209              long long in[])
1210
1211       int  nc_get_att_string(int  ncid,  int varid, const char name[], char *
1212              in[])
1213
1214
1215
1216              Gets the value(s) of a netCDF attribute, given its  variable  ID
1217              and name.  Converts from the external type to the type specified
1218              in  the  function  name,  if  possible,  otherwise  returns   an
1219              NC_ERANGE error.  All elements of the vector of attribute values
1220              are returned, so you must allocate enough space  to  hold  them.
1221              If  you  don't  know  how much space to reserve, call nc_inq_at‐
1222              tlen() first to find out the length of the attribute.
1223

COMMON ARGUMENT DESCRIPTIONS

1225       In this section we define some common arguments which are used  in  the
1226       "FUNCTION DESCRIPTIONS" section.
1227
1228       int ncid
1229              is  the  netCDF  ID returned from a previous, successful call to
1230              nc_open() or nc_create()
1231
1232       char name[]
1233              is the name of a dimension, variable, or attribute. The names of
1234              dimensions,  variables  and  attributes consist of arbitrary se‐
1235              quences of alphanumeric characters (as well as  underscore  '_',
1236              period  '.'  and  hyphen '-'), beginning with a letter or under‐
1237              score. (However names commencing with  underscore  are  reserved
1238              for  system  use.)  Case is significant in netCDF names. A zero-
1239              length name is not allowed.  As an input argument, it shall be a
1240              pointer  to  a  0-terminated  string;  as an output argument, it
1241              shall be the address of a buffer in which to hold such a string.
1242              The maximum allowable number of characters (excluding the termi‐
1243              nating 0) is NC_MAX_NAME.
1244
1245       nc_type xtype
1246              specifies the external data type of a  netCDF  variable  or  at‐
1247              tribute and is one of the following: NC_BYTE, NC_CHAR, NC_SHORT,
1248              NC_INT, NC_FLOAT, or NC_DOUBLE.  These are used to specify 8-bit
1249              integers,  characters,  16-bit integers, 32-bit integers, 32-bit
1250              IEEE floating point numbers, and 64-bit IEEE floating-point num‐
1251              bers,  respectively.   (NC_INT corresponds to NC_LONG in version
1252              2, to specify a 32-bit integer).
1253
1254       int dimids[]
1255              is a vector of dimension ID's and defines the shape of a  netCDF
1256              variable.  The size of the vector shall be greater than or equal
1257              to the rank (i.e. the number  of  dimensions)  of  the  variable
1258              (ndims).   The vector shall be ordered by the speed with which a
1259              dimension varies: dimids[ndims-1] shall be the dimension  ID  of
1260              the  most  rapidly  varying dimension and dimids[0] shall be the
1261              dimension ID of the most slowly varying dimension.  The  maximum
1262              possible  number  of  dimensions  for a variable is given by the
1263              symbolic constant NC_MAX_VAR_DIMS.
1264
1265       int dimid
1266              is the ID of a netCDF dimension.  netCDF dimension ID's are  al‐
1267              located  sequentially  from  the non-negative integers beginning
1268              with 0.
1269
1270       int ndims
1271              is either the total number of dimensions in a netCDF dataset  or
1272              the  rank  (i.e. the number of dimensions) of a netCDF variable.
1273              The value shall not be negative or  greater  than  the  symbolic
1274              constant NC_MAX_VAR_DIMS.
1275
1276       int varid
1277              is  the  ID  of  a  netCDF variable or (for the attribute-access
1278              functions) the symbolic constant NC_GLOBAL,  which  is  used  to
1279              reference global attributes.  netCDF variable ID's are allocated
1280              sequentially from the non-negative integers beginning with 0.
1281
1282       int* natts
1283              is the number of global attributes in a netCDF dataset  for  the
1284              nc_inquire()  function  or  the  number of attributes associated
1285              with a netCDF variable for the nc_varinq() function.
1286
1287       const size_t index[]
1288              specifies the indicial coordinates of the netCDF data  value  to
1289              be  accessed.   The  indices  start at 0; thus, for example, the
1290              first data value of a two-dimensional variable  is  (0,0).   The
1291              size  of the vector shall be at least the rank of the associated
1292              netCDF variable and its elements shall correspond, in order,  to
1293              the variable's dimensions.
1294
1295       const size_t start[]
1296              specifies  the  starting point for accessing a netCDF variable's
1297              data values in terms of the indicial coordinates of  the  corner
1298              of  the  array section.  The indices start at 0; thus, the first
1299              data value of a variable is (0, 0, ..., 0).   The  size  of  the
1300              vector shall be at least the rank of the associated netCDF vari‐
1301              able and its elements shall correspond, in order, to  the  vari‐
1302              able's dimensions.
1303
1304       const size_t count[]
1305              specifies the number of indices selected along each dimension of
1306              the array section.  Thus, to access a single value, for example,
1307              specify  count  as  (1, 1, ..., 1).  Note that, for strided I/O,
1308              this argument must be adjusted to be compatible with the  stride
1309              and  start  arguments  so that the interaction of the three does
1310              not attempt to access an invalid data co-ordinate.  The elements
1311              of  the count vector correspond, in order, to the variable's di‐
1312              mensions.
1313
1314       const size_t stride[]
1315              specifies the sampling interval  along  each  dimension  of  the
1316              netCDF variable.   The elements of the stride vector correspond,
1317              in order, to the netCDF variable's dimensions (stride[0])  gives
1318              the sampling interval along the most slowly varying dimension of
1319              the netCDF variable).  Sampling intervals are specified in type-
1320              independent  units of elements (a value of 1 selects consecutive
1321              elements of the netCDF variable along the  corresponding  dimen‐
1322              sion,  a  value of 2 selects every other element, etc.).  A NULL
1323              stride argument is treated as (1, 1, ... , 1).
1324
1325       imap   specifies the mapping between the dimensions of a  netCDF  vari‐
1326              able  and  the  in-memory  structure of the internal data array.
1327              The elements of the index mapping vector correspond,  in  order,
1328              to  the netCDF variable's dimensions (imap[0] gives the distance
1329              between elements of the internal array corresponding to the most
1330              slowly varying dimension of the netCDF variable).  Distances be‐
1331              tween elements are specified in type-independent units  of  ele‐
1332              ments  (the distance between internal elements that occupy adja‐
1333              cent memory locations is 1 and not the element's byte-length  as
1334              in  netCDF  2).  A NULL pointer means the memory-resident values
1335              have the same structure as the associated netCDF variable.
1336

VARIABLE PREFILLING

1338       By default, the netCDF interface sets the values of  all  newly-defined
1339       variables  of  finite length (i.e. those that do not have an unlimited,
1340       dimension) to the type-dependent fill-value associated with each  vari‐
1341       able.   This  is done when nc_enddef() is called.  The fill-value for a
1342       variable may be changed from the default  value  by  defining  the  at‐
1343       tribute  `_FillValue'  for  the variable.  This attribute must have the
1344       same type as the variable and be of length one.
1345
1346       Variables with an unlimited dimension are also prefilled, but on an `as
1347       needed'  basis.   For example, if the first write of such a variable is
1348       to position 5, then positions 0 through 4 (and no others) would be  set
1349       to the fill-value at the same time.
1350
1351       This  default  prefilling  of data values may be disabled by or'ing the
1352       NC_NOFILL flag into the mode parameter of nc_open() or nc_create(), or,
1353       by calling the function nc_set_fill() with the argument NC_NOFILL.  For
1354       variables that do not use the unlimited dimension, this  call  must  be
1355       made  before  nc_enddef().  For variables that use the unlimited dimen‐
1356       sion, this call may be made at any time.
1357
1358       One can obtain increased performance of the netCDF interface  by  using
1359       this  feature,  but only at the expense of requiring the application to
1360       set every single data value.  The  performance  enhancing  behavior  of
1361       this function is dependent on the particulars of the implementation and
1362       dataset format.  The flag value  controlled  by  nc_set_fill()  is  per
1363       netCDF  ID, not per variable or per write.  Allowing this to change af‐
1364       fects the degree to which a program can  be  effectively  parallelized.
1365       Given  all  of  this,  we state that the use of this feature may not be
1366       available (or even needed) in future  releases.  Programmers  are  cau‐
1367       tioned against heavy reliance upon this feature.
1368
1369       int nc_setfill(int ncid, int fillmode, int* old_fillemode)
1370
1371              (Corresponds to ncsetfill() in version 2)
1372
1373              Determines  whether or not variable prefilling will be done (see
1374              above).  The netCDF dataset shall be writable.  fillmode is  ei‐
1375              ther  NC_FILL to enable prefilling (the default) or NC_NOFILL to
1376              disable prefilling.  This function returns the previous  setting
1377              in old_fillmode.
1378
1379
1380
1381

MPP FUNCTION DESCRIPTIONS

1383       Additional  functions  for  use  on  SGI/Cray  MPP machines (_CRAYMPP).
1384       These are used to set and inquire which PE is the base for  MPP  for  a
1385       particular  netCDF.  These  are  only  relevant when using the SGI/Cray
1386       ``global'' Flexible File I/O layer and desire to have only a subset  of
1387       PEs  to  open  the  specific netCDF file.  For technical reasons, these
1388       functions are available on all platforms.  On  a  platform  other  than
1389       SGI/Cray MPP, it is as if only processor available were processor 0.
1390
1391       To  use this feature, you need to specify a communicator group and call
1392       glio_group_mpi() or glio_group_shmem() prior to  the  netCDF  nc_open()
1393       and nc_create() calls.
1394
1395       int nc__create_mp(const char path[], int cmode, size_t initialsize, int
1396              pe, size_t* chunksize, int* ncid)
1397
1398              Like nc__create() but allows the base PE to be set.
1399
1400              The argument pe sets the base PE at creation time.  In  the  MPP
1401              environment,  nc__create()  and  nc_create()  set the base PE to
1402              processor zero by default.
1403
1404       int nc__open_mp(const char path[], int mode, int pe, size_t* chunksize,
1405              int* ncid)
1406
1407              Like  nc__open() but allows the base PE to be set.  The argument
1408              pe sets the base PE at creation time. In  the  MPP  environment,
1409              nc__open()  and  nc_open()  set the base PE to processor zero by
1410              default.
1411
1412       int nc_inq_base_pe(int ncid, int* pe)
1413
1414              Inquires of the netCDF dataset which PE is  being  used  as  the
1415              base for MPP use.  This is safe to use at any time.
1416
1417       int nc_set_base_pe(int ncid, int pe)
1418
1419              Resets  the  base  PE for the netCDF dataset.  Only perform this
1420              operation when the affected communicator group synchronizes  be‐
1421              fore  and  after  the  call.   This  operation is very risky and
1422              should only be contemplated under only the most extreme cases.
1423

ENVIRONMENT VARIABLES

1425       NETCDF_FFIOSPEC
1426           Specifies the Flexible File I/O buffers for netCDF I/O when execut‐
1427           ing  under  the UNICOS operating system (the variable is ignored on
1428           other operating systems).  An appropriate specification can greatly
1429           increase  the efficiency of netCDF I/O -- to the extent that it can
1430           actually surpass FORTRAN binary I/O.  This environment variable has
1431           been  made  a  little more generalized, such that other FFIO option
1432           specifications can now be added.  The default specification is  bu‐
1433           fa:336:2,  unless  a  current  FFIO  specification is in operation,
1434           which will be honored.  See UNICOS Flexible File I/O for  more  in‐
1435           formation.
1436

MAILING-LISTS

1438       Both  a  mailing  list and a digest are available for discussion of the
1439       netCDF interface and announcements about netCDF bugs,  fixes,  and  en‐
1440       hancements.   To  begin or change your subscription to either the mail‐
1441       ing-list or the digest, send one of the following in the body (not  the
1442       subject line) of an email message to "majordomo@unidata.ucar.edu".  Use
1443       your email address in place of jdoe@host.inst.domain.
1444
1445       To subscribe to the netCDF mailing list:
1446              subscribe netcdfgroup jdoe@host.inst.domain
1447       To unsubscribe from the netCDF mailing list:
1448              unsubscribe netcdfgroup jdoe@host.inst.domain
1449       To subscribe to the netCDF digest:
1450              subscribe netcdfdigest jdoe@host.inst.domain
1451       To unsubscribe from the netCDF digest:
1452              unsubscribe netcdfdigest jdoe@host.inst.domain
1453       To retrieve the general introductory information for the mailing list:
1454              info netcdfgroup
1455       To get a synopsis of other majordomo commands:
1456              help
1457

SEE ALSO

1459       ncdump(1), ncgen(1), netcdf(3).
1460
1461       netCDF User's Guide, published by the Unidata Program Center, Universi‐
1462       ty Corporation for Atmospheric Research, located in Boulder, Colorado.
1463
1464       NetCDF home page at http:/www.unidata.ucar.edu/netcdf.
1465
1466
1467
1468Printed: 2019-06-22               1997-04-18                         NETCDF(3)
Impressum