/** \ingroup v2_api

Put file in define mode.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_redef().

\param ncid file ID

\returns 0 for success, -1 for failure.
*/


/** \ingroup v2_api

End define mode for file.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_enddef().

\param ncid file ID

\returns 0 for success, -1 for failure.
*/


/** \ingroup v2_api

Close a file.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_close().

\param ncid file ID

\returns 0 for success, -1 for failure.
*/


/** \ingroup v2_api

Learn about a file.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_inq().

\param ncid file ID
\param ndims pointer that will get number of dimensions.
\param nvars pointer that will get number of variables.
\param natts pointer that will get number of global attributes.
\param recdim pointer that will get dimension ID of record dimension,
or -1 if there is no record dimension.

\returns 0 for success, -1 for failure.
*/


/** \ingroup v2_api

Sync a file.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_sync().

\param ncid file ID

\returns 0 for success, -1 for failure.
*/


/** \ingroup v2_api

Abort defining a file.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_abort().

\param ncid file ID
\returns 0 for success, -1 for failure.
*/


/** \ingroup v2_api

Define a dimension.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_def_dim().

\param ncid file ID
\param name name of dimension.
\param length length of the dimension, NC_UNLIMITED for a record
dimension.

\returns dimid or -1 for failure.
*/


/** \ingroup v2_api

Find dimension ID from name.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_inq_dimid().

\param ncid file ID
\param name name of dimension.

\returns dimid or -1 for failure.
*/


/** \ingroup v2_api

Learn about a dimension.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_inq_dim().

\param ncid file ID
\param dimid the dimension ID to learn about
\param name pointer that will get name of dimension.
\param length pointer that will get length of dimension.

\returns dimid or -1 for failure.
*/


/** \ingroup v2_api

Rename a dimension.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_rename_dim().

\param ncid file ID
\param dimid the dimension ID.
\param name the new name.

\returns dimid or -1 for failure.
*/


/** \ingroup v2_api

Define a variable.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_def_var().

\param ncid file ID
\param name the name of the variable.
\param datatype the data type of the variable.
\param ndims the number of dimensions.
\param dim array of dimension IDs.

\returns varid or -1 for failure.
*/


/** \ingroup v2_api

Learn a variable ID from the name.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_inq_varid().

\param ncid file ID
\param name the name of the variable.

\returns varid or -1 for failure.
*/


/** \ingroup v2_api

Learn about a variable.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_inq_var().

\param ncid file ID
\param varid the variable ID.
\param name pointer to array of char that will get name of variable.
\param datatype pointer that will get variable data type.
\param ndims pointer that will get number of dimensions.
\param dim pointer to array that will get dimension IDs.
\param natts pointer that will get number of variable attributes.

\returns varid or -1 for failure.
*/


/** \ingroup v2_api

Read 1 data value.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_var1().

\param ncid file ID
\param varid the variable ID.
\param index pointer to array of index values.
\param value pointer that will get data.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Write some data.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_put_vara().

\param ncid file ID
\param varid the variable ID.
\param start pointer to array of start values.
\param count pointer to array of count values.
\param value pointer to data.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Read some data.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_vara().

\param ncid file ID
\param varid the variable ID.
\param start pointer to array of start values.
\param count pointer to array of count values.
\param value pointer to data.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Write strided data.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_put_vars().

\param ncid file ID
\param varid the variable ID.
\param start pointer to array of start values.
\param count pointer to array of count values.
\param stride pointer to array of stride values.
\param value pointer to data.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Read strided data.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_vars().

\param ncid file ID
\param varid the variable ID.
\param start pointer to array of start values.
\param count pointer to array of count values.
\param stride pointer to array of stride values.
\param value pointer to data.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Write mapped data.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_varm().

\param ncid file ID
\param varid the variable ID.
\param start pointer to array of start values.
\param count pointer to array of count values.
\param stride pointer to array of stride values.
\param map pointer to array of map values.
\param value pointer to data.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Read mapped data.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_varm().

\param ncid file ID
\param varid the variable ID.
\param start pointer to array of start values.
\param count pointer to array of count values.
\param stride pointer to array of stride values.
\param map pointer to array of map values.
\param value pointer to data.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Rename a variable.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_rename_var().

\param ncid file ID
\param varid the variable ID.
\param name the new name.

\returns varid or -1 for failure.
*/


/** \ingroup v2_api

Write an attribute.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_put_att_int(), etc.

\param ncid file ID
\param varid the variable ID or NC_GLOBAL.
\param name the name of the attribute.
\param datatype the type of the attribute.
\param len the length of the attribute.
\param value the attribute value.

\returns dimid or -1 for failure.
*/


/** \ingroup v2_api

Learn about an attribute.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_inq_att().

\param ncid file ID
\param varid the variable ID.
\param name the name of the attribute.
\param datatype pointer that will get data type.
\param len pointer that will get length.

\returns 1 for success or -1 for failure. (That's a delightful
artifact of a by-gone era of C programming, isn't it?)
*/


/** \ingroup v2_api

Read an attribute.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_att_int(), etc.

\param ncid file ID.
\param varid the variable ID or NC_GLOBAL.
\param name the name of the attribute.
\param value pointer that will get the attribute data.

\returns 1 for success or -1 for failure.
*/


/** \ingroup v2_api

Copy an attribute.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_att_int(), etc.

\param ncid_in file ID to copy from.
\param varid_in the variable ID or NC_GLOBAL to copy from.
\param name the name of the attribute.
\param ncid_out file ID to copy to.
\param varid_out the variable ID or NC_GLOBAL to copy to.

\returns 0 for success or -1 for failure.
*/


/** \ingroup v2_api

Learn attribute name from its number.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_inq_attname().

\param ncid file ID
\param varid the variable ID.
\param attnum the number of the attribute.
\param name the name of the attribute.

\returns attnum for success or -1 for failure.
*/


/** \ingroup v2_api

Rename an attribute.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_rename_att().

\param ncid file ID
\param varid the variable ID.
\param name the attribute name.
\param newname the new name.

\returns 1 for success or -1 for failure.
*/


/** \ingroup v2_api

Delete an attribute.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_delete_att().

\param ncid file ID
\param varid the variable ID.
\param name the attribute name.

\returns 1 for success or -1 for failure.
*/


/** \ingroup v2_api

Set the fill mode.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_set_fill().

\param ncid file ID
\param fillmode NC_FILL or NC_NOFILL.

\returns oldmode for success or -1 for failure.
*/


/** \ingroup v2_api

Learn record variables and the lengths of the record dimension.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 functions nc_inq_var()/nc_inq_dim().

\param ncid file ID
\param nrecvars pointer that will get number of record variables.
\param recvarids pointer that will get array of record variable IDs.
\param recsizes pointer that will get array of record dimension length.

\returns oldmode for success or -1 for failure.
*/


/** \ingroup v2_api

Read one record's worth of data, except don't read from variables for which
the address of the data to be read is null.  Return -1 on error. This is
the same as the nc_get_rec(), with poorer error handling.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_get_vara().

\param ncid file ID
\param recnum the record number to read.
\param datap pointer memory to hold one record's worth of data for all
variables.

\returns 0 for success, -1 for error.
*/


/** \ingroup v2_api

Write one record's worth of data, except don't write to variables for which
the address of the data to be written is NULL.  Return -1 on error.  This is
the same as the nc_put_rec(), but with poorer error handling.

This is part of the legacy V2 API of netCDF. New code should be
written with the V3 API. See V3 function nc_put_vara().

\param ncid file ID
\param recnum the record number to write.
\param datap pointer to one record's worth of data for all variables.

\returns 0 for success, -1 for error.
*/


/*
Added to support open by name
*/


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 * @param varid Ignored.
 * @param name Ignored.
 * @param newname Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 * @param varid Ignored.
 * @param name Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 * @param varid Ignored.
 * @param name Ignored.
 * @param file_type Ignored.
 * @param len Ignored.
 * @param data Ignored.
 * @param memtype Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 * @param name Ignored.
 * @param len Ignored.
 * @param idp Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 * @param dimid Ignored.
 * @param name Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 * @param name Ignored.
 * @param xtype Ignored.
 * @param ndims Ignored.
 * @param dimidsp Ignored.
 * @param varidp Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for classic model access.
 *
 * @param ncid Ignored.
 * @param varid Ignored.
 * @param no_fill Ignored.
 * @param fill_value Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid File ID.
 * @param varid Variable ID
 * @param name New name of the variable.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid File ID.
 * @param varid Variable ID.
 * @param startp Array of start indices.
 * @param countp Array of counts.
 * @param op pointer that gets the data.
 * @param memtype The type of these data in memory.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid File and group ID.
 * @param fillmode File mode.
 * @param old_modep Pointer that gets old mode. Ignored if NULL.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param ncid Ignored.
 * @param h_minfree Ignored.
 * @param v_align Ignored.
 * @param v_minfree Ignored.
 * @param r_align Ignored.
 *
 * @return ::NC_EPERM Not allowed.
 * @author Ed Hartnett
 */


/**
 * @internal Not allowed for read-only access.
 *
 * @param path Ignored.
 * @param cmode Ignored.
 * @param initialsz Ignored.
 * @param basepe Ignored.
 * @param chunksizehintp Ignored.
 * @param use_parallel Ignored.
 * @param parameters Ignored.
 * @param dispatch Ignored.
 * @param nc_file Ignored.
 *
 * @return ::NC_EPERM Cannot create files.
 * @author Ed Hartnett
 */


/** \ingroup user_types
Create an enum type. Provide an ncid, a name, and a base integer type.

After calling this function, fill out the type with repeated calls to
nc_insert_enum(). Call nc_insert_enum() once for each value you wish
to make part of the enumeration.

\param ncid \ref ncid

\param base_typeid The base integer type for this enum. Must be one
of: ::NC_BYTE, ::NC_UBYTE, ::NC_SHORT, ::NC_USHORT, ::NC_INT,
::NC_UINT, ::NC_INT64, ::NC_UINT64.

\param name \ref object_name of new type.

\param typeidp A pointer to an nc_type. The typeid of the new type
will be placed there.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\returns ::NC_ENAMEINUSE That name is in use.
\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
\returns ::NC_EBADNAME Name contains illegal characters.
\returns ::NC_EPERM Attempt to write to a read-only file.
\returns ::NC_ENOTINDEFINE Not in define mode.
 */


/** \ingroup user_types
Insert a named member into a enum type.

\param ncid \ref ncid
\param xtype
\param name The identifier (\ref object_name) of the new member.
\param value The value that is to be associated with this member.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\returns ::NC_ENAMEINUSE That name is in use.
\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
\returns ::NC_EBADNAME Name contains illegal characters.
\returns ::NC_EPERM Attempt to write to a read-only file.
\returns ::NC_ENOTINDEFINE Not in define mode.
 */


/** \ingroup user_types
Learn about a user-define enumeration type.

\param ncid \ref ncid

\param xtype Typeid to inquire about.

\param name \ref object_name of type will be copied here. \ref
ignored_if_null.

\param base_nc_typep Typeid if the base type of the enum.\ref
ignored_if_null.

\param base_sizep Pointer that will get the size in bytes of the base
type. \ref ignored_if_null.

\param num_membersp Pointer that will get the number of members
defined for this enum type. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/** \ingroup user_types
Learn about a about a member of an enum type.

\param ncid \ref ncid

\param xtype Typeid of the enum type.

\param idx Index to the member to inquire about.

\param name The identifier (\ref object_name) of this member will be
copied here. \ref ignored_if_null.

\param value The value of this member will be copied here. \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/** \ingroup user_types
Get the name which is associated with an enum member value.

\param ncid \ref ncid

\param xtype Typeid of the enum type.

\param value Value of interest.

\param identifier The identifier (\ref object_name) of this value will
be copied here. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/*
 * Check validity of a UTF8 encoded null-terminated byte string.
 * Return codes:
 * NC_NOERR -- string is valid utf8
 * NC_ENOMEM -- out of memory
 * NC_EINVAL -- invalid argument or internal error
 * NC_EBADNAME-- not valid utf8
 */


/*
 * Returns a pointer to newly allocated memory of a
 * normalized version of the null-terminated string 'str'.
 * Normalized string is returned in normalp argument;
 * caller must free.
 * Return codes:
 * NC_NOERR -- success
 * NC_ENOMEM -- out of memory
 * NC_EINVAL -- illegal argument or internal error
 * NC_EBADNAME -- other failure
 */


/*
 * Convert a normalized utf8 string to utf16. This is approximate
 * because it just does the truncation version of conversion for
 * each 32-bit codepoint to get the corresponding utf16.
 * Return codes:
 * NC_NOERR -- success
 * NC_ENOMEM -- out of memory
 * NC_EINVAL -- invalid argument or internal error
 * NC_EBADNAME-- not valid utf16
 */


/* Argument is a netcdf type class, except compound|ENUM  */


/*!
Enable/Disable logging.

\param[in] tf If 1, then turn on logging, if 0, then turn off logging.

\return The previous value of the logging flag.
*/


/*!
Specify a file into which to place logging output.

\param[in] file The name of the file into which to place logging output.
If the file has the value NULL, then send logging output to
stderr.

\return zero if the open failed, one otherwise.
*/


/*!
Send logging messages. This uses a variable
number of arguments and operates like the stdio
printf function.

\param[in] tag Indicate the kind of this log message.
\param[in] format Format specification as with printf.
*/


/*!
Send arbitrarily long text as a logging message.
Each line will be sent using nclog with the specified tag.
\param[in] tag Indicate the kind of this log message.
\param[in] text Arbitrary text to send as a logging message.
*/


/* The tagset is null terminated */


/* locate, read and compile the rc file, if any */


/**
 * Locate a triple by property key and host+port (may be null|"")
 * If duplicate keys, first takes precedence.
 */


/*!
Set the absolute path to use for the rc file.
WARNING: this MUST be called before any other
call in order for this to take effect.

\param[in] rcfile The path to use. If NULL, or "",
                  then do not use any rcfile.

\retval OC_NOERR if the request succeeded.
\retval OC_ERCFILE if the file failed to load
*/


/**************************************************/
/* RC processing functions */


/* Trim TRIMCHARS from both ends of text; */


/* Order the triples: those with urls must be first,
   but otherwise relative order does not matter.
*/


/* Create a triple store from a file */


/**
 * (Internal) Locate a triple by property key and host+port (may be null or "").
 * If duplicate keys, first takes precedence.
 */


/**
 * Locate rc file by searching in directory prefix.
 * Prefix must end in '/'
 */


/* Obtain the count of number of triples */


/* Obtain the ith triple; return NULL if out of range */


/**
   Define a new dimension. The function nc_def_dim() adds a new
   dimension to an open netCDF dataset in define mode. It returns (as an
   argument) a dimension ID, given the netCDF ID, the dimension name, and
   the dimension length. At most one unlimited length dimension, called
   the record dimension, may be defined for each classic or 64-bit offset
   netCDF dataset. NetCDF-4 datasets may have multiple unlimited
   dimensions.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param name Name of the dimension to be created.
   @param len Length of the dimension to be created. Use NC_UNLIMITED for
   unlimited dimensions.
   @param idp Pointer where dimension ID will be stored.

   @return ::NC_NOERR No error.
   @return ::NC_EBADID Not a valid ID.
   @return ::NC_EMAXNAME Name is too long.
   @return ::NC_EBADNAME Name breaks netCDF name rules.
   @return ::NC_EINVAL Invalid input.
   @return ::NC_ENOTINDEFINE Not in define mode.
   @return ::NC_EDIMSIZE Invalid dimension size.
   @return ::NC_EUNLIMIT NC_UNLIMITED size already in use
   @return ::NC_EMAXDIMS NC_MAX_DIMS exceeded [not enforced after 4.5.0]
   @return ::NC_ENAMEINUSE String match to name in use
   @return ::NC_ENOMEM Memory allocation (malloc) failure
   @return ::NC_EPERM Write to read only

   @section nc_def_dim_example Example

   Here is an example using nc_def_dim() to create a dimension named lat of
   length 18 and a unlimited dimension named rec in a new netCDF dataset
   named foo.nc:

   @code
   #include <netcdf.h>
   ...
   int status, ncid, latid, recid;
   ...
   status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
   if (status != NC_NOERR) handle_error(status);
   ...
   status = nc_def_dim(ncid, "lat", 18L, &latid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_def_dim(ncid, "rec", NC_UNLIMITED, &recid);
   if (status != NC_NOERR) handle_error(status);
   @endcode

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/**
   Find the ID of a dimension from the name.

   The function nc_inq_dimid returns (as an argument) the ID of a
   netCDF dimension, given the name of the dimension. If ndims is the
   number of dimensions defined for a netCDF dataset, each dimension
   has an ID between 0 and ndims-1.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param name Name of the dimension.
   @param idp Pointer where dimension ID will be stored.

   @return ::NC_NOERR No error.
   @return ::NC_EBADID Not a valid ID.
   @return ::NC_EBADDIM Invalid dimension ID.

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/**
   Find the name and length of a dimension.

   The length for the unlimited dimension, if any, is the number of
   records written so far.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param dimid Dimension ID, from a previous call to nc_inq_dimid() or
   nc_def_dim().
   @param name Returned dimension name. The caller must allocate space
   for the returned name. The maximum possible length, in characters, of
   a dimension name is given by the predefined constant
   ::NC_MAX_NAME. (This doesn't include the null terminator, so declare
   your array to be size NC_MAX_NAME+1). The returned character array
   will be null-terminated.
   @param lenp Pointer to location for returned length of dimension. For
   the unlimited dimension, this is the number of records written so far.

   @return ::NC_NOERR No error.
   @return ::NC_EBADID Not a valid ID.
   @return ::NC_EBADDIM Invalid dimension ID or name.

   @section nc_inq_dim_example Example

   Here is an example using nc_inq_dim() to determine the length of a
   dimension named lat, and the name and current maximum length of the
   unlimited dimension for an existing netCDF dataset named foo.nc:

   @code
   #include <netcdf.h>
   ...
   int status, ncid, latid, recid;
   size_t latlength, recs;
   char recname[NC_MAX_NAME+1];
   ...
   status = nc_open("foo.nc", NC_NOWRITE, &ncid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_inq_unlimdim(ncid, &recid);
   if (status != NC_NOERR) handle_error(status);
   ...
   status = nc_inq_dimid(ncid, "lat", &latid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_inq_dimlen(ncid, latid, &latlength);
   if (status != NC_NOERR) handle_error(status);

   status = nc_inq_dim(ncid, recid, recname, &recs);
   if (status != NC_NOERR) handle_error(status);
   @endcode

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/**
   Rename a dimension.

   This function renames an existing dimension in a netCDF dataset
   open for writing. You cannot rename a dimension to have the same
   name as another dimension.

   For netCDF classic and 64-bit offset files, if the new name is
   longer than the old name, which has been flushed to disk, the
   netCDF dataset must be in define mode.

   For netCDF-4 files the length of the name is not checked against
   the length of the old name, even for classic model files. This is
   due to the difficulty of exactly reproducing classic library
   behavior in this case.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param dimid Dimension ID, from a previous call to nc_inq_dimid()
   or nc_def_dim().
   @param name New name for dimension. Must be a null-terminated
   string with length less than ::NC_MAX_NAME.

   @return ::NC_NOERR No error.
   @return ::NC_EBADID Not a valid ID.
   @return ::NC_EBADDIM Invalid dimension ID or name.
   @return ::NC_ENAMEINUSE String match to name in use
   @return ::NC_ENOMEM Memory allocation (malloc) failure
   @return ::NC_EPERM Write to read only
   @return ::NC_ENOTINDEFINE Not in define mode and new name is longer
   than old.

   @section nc_rename_dim_example Example

   Here is an example using nc_rename_dim to rename the dimension lat
   to latitude in an existing netCDF dataset named foo.nc:

   @code
   #include <netcdf.h>
   ...
   int status, ncid, latid;
   ...
   status = nc_open("foo.nc", NC_WRITE, &ncid);
   if (status != NC_NOERR) handle_error(status);
   ...
   status = nc_redef(ncid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_inq_dimid(ncid, "lat", &latid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_rename_dim(ncid, latid, "latitude");
   if (status != NC_NOERR) handle_error(status);
   status = nc_enddef(ncid);
   if (status != NC_NOERR) handle_error(status);
   @endcode

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/**
   Find the number of dimensions.

   In a classic model netCDF file, this function returns the number of
   defined dimensions. In a netCDF-4/HDF5 file, this function returns
   the number of dimensions available in the group specified by ncid,
   which may be less than the total number of dimensions in a file. In
   a netCDF-4/HDF5 file, dimensions are in all sub-groups,
   sub-sub-groups, etc.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param ndimsp Pointer where number of dimensions will be
   written. Ignored if NULL.

   @return ::NC_NOERR  No error.
   @return ::NC_EBADID Not a valid ID.

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/**
   Find the ID of the unlimited dimension.

   This function finds the ID of the unlimited dimension. For
   netCDF-4/HDF5 files (which may have more than one unlimited
   dimension), the ID of the first unlimited dimesnion is
   returned. For these files, nc_inq_unlimdims() will return all the
   unlimited dimension IDs.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param unlimdimidp Pointer where unlimited dimension ID will be
   stored. If there is no unlimited dimension, -1 will be stored
   here. Ignored if NULL.

   @return ::NC_NOERR  No error.
   @return ::NC_EBADID Not a valid ID.

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/**
   Find out the name of a dimension.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param dimid Dimension ID, from a previous call to nc_inq_dimid()
   or nc_def_dim().
   @param name Returned dimension name. The caller must allocate space
   for the returned name. The maximum possible length, in characters,
   of a dimension name is given by the predefined constant
   ::NC_MAX_NAME. (This doesn't include the null terminator, so
   declare your array to be size NC_MAX_NAME+1). The returned
   character array will be null-terminated. Ignored if NULL.

   @return ::NC_NOERR   No error.
   @return ::NC_EBADID  Not a valid ID.
   @return ::NC_EBADDIM Invalid dimension ID or name.

   @section nc_inq_dim_example2 Example

   Here is an example using nc_inq_dim() to determine the length of a
   dimension named lat, and the name and current maximum length of the
   unlimited dimension for an existing netCDF dataset named foo.nc:

   @code
   #include <netcdf.h>
   ...
   int status, ncid, latid, recid;
   size_t latlength, recs;
   char recname[NC_MAX_NAME+1];
   ...
   status = nc_open("foo.nc", NC_NOWRITE, &ncid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_inq_unlimdim(ncid, &recid);
   if (status != NC_NOERR) handle_error(status);
   ...
   status = nc_inq_dimid(ncid, "lat", &latid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_inq_dimlen(ncid, latid, &latlength);
   if (status != NC_NOERR) handle_error(status);

   status = nc_inq_dim(ncid, recid, recname, &recs);
   if (status != NC_NOERR) handle_error(status);
   @endcode

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/**
   Find the length of a dimension.

   The length for the unlimited dimension, if any, is the number of
   records written so far.

   @param ncid NetCDF or group ID, from a previous call to nc_open(),
   nc_create(), nc_def_grp(), or associated inquiry functions such as
   nc_inq_ncid().
   @param dimid Dimension ID, from a previous call to nc_inq_dimid()
   or nc_def_dim().
   @param lenp Pointer where the length will be stored.

   @return ::NC_NOERR   No error.
   @return ::NC_EBADID  Not a valid ID.
   @return ::NC_EBADDIM Invalid dimension ID or name.

   @section nc_inq_dim_example3 Example

   Here is an example using nc_inq_dim() to determine the length of a
   dimension named lat, and the name and current maximum length of the
   unlimited dimension for an existing netCDF dataset named foo.nc:

   @code
   #include <netcdf.h>
   ...
   int status, ncid, latid, recid;
   size_t latlength, recs;
   char recname[NC_MAX_NAME+1];
   ...
   status = nc_open("foo.nc", NC_NOWRITE, &ncid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_inq_unlimdim(ncid, &recid);
   if (status != NC_NOERR) handle_error(status);
   ...
   status = nc_inq_dimid(ncid, "lat", &latid);
   if (status != NC_NOERR) handle_error(status);
   status = nc_inq_dimlen(ncid, latid, &latlength);
   if (status != NC_NOERR) handle_error(status);

   status = nc_inq_dim(ncid, recid, recname, &recs);
   if (status != NC_NOERR) handle_error(status);
   @endcode

   @author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
   Fisher
*/


/* Report a conflicting model field assignment;
   see the conflictset macro above */


/* Parse a mode string at the commas and convert to envv form */


/* Given a mode= argument, and the mode flags,
   infer the iosp part of the model */


/* Given a mode= argument, fill in the matching part of the model; except IOSP */


/* Search singleton list */


/* If we have a url, see if we can determine DAP */


/*
Infer from the mode
only call if iscreate or file is not easily readable.
*/


/* Infer the implementation/dispatcher from format*/


/**************************************************/
/*
   Infer model for this dataset using some
   combination of cmode, path, and reading the dataset.

   The precedence order is:
   1. file contents -- highest precedence
   2. path
   2. isurl -- check for DAP
   3. mode
   4. default format -- lowest precedence

@param path
@param omode
@param iscreate
@param useparallel
@param params
@param model
@param newpathp

*/


/**************************************************/
/**
 * @internal Given an existing file, figure out its format and return
 * that format value (NC_FORMATX_XXX) in model arg. Assume any path
 * conversion was already performed at a higher level.
 *
 * @param path File name.
 * @param flags
 * @param use_parallel
 * @param parameters
 * @param model Pointer that gets the model to use for the dispatch table.
 * @param version Pointer that gets version of the file.
 *
 * @return ::NC_NOERR No error.
 * @author Dennis Heimbigner
*/


/*!
  Interpret the magic number found in the header of a netCDF file.
  This function interprets the magic number/string contained in the header of a netCDF file and sets the appropriate NC_FORMATX flags.

  @param[in] magic Pointer to a character array with the magic number block.
  @param[out] model Pointer to an integer to hold the corresponding netCDF type.
  @param[out] version Pointer to an integer to hold the corresponding netCDF version.
  @returns NC_NOERR if a legitimate file type found
  @returns NC_ENOTNC otherwise

\internal
\ingroup datasets

*/


/**
Return the library version.

\returns short string that contains the version information for the
library.
 */


/*! Given an error number, return an error message.

This function returns a static reference to an error message string
corresponding to an integer netCDF error status or to a system error
number, presumably returned by a previous call to some other netCDF
function. The error codes are defined in netcdf.h.

\param ncerr1 error number

\returns short string containing error message.

Here is an example of a simple error handling function that uses
nc_strerror() to print the error message corresponding to the netCDF
error status returned from any netCDF function call and then exit:

\code
     #include <netcdf.h>
        ...
     void handle_error(int status) {
     if (status != NC_NOERR) {
        fprintf(stderr, "%s\n", nc_strerror(status));
        exit(-1);
        }
     }
\endcode
*/


/* Find first primitive field of a possibly nested sequence of compounds */


/**
\ingroup user_types
Free memory in a VLEN object.

When you read VLEN type the library will actually allocate the storage
space for the data. This storage space must be freed, so pass the
pointer back to this function, when you're done with the data, and it
will free the vlen memory.

The function nc_free_vlens() is more useful than this function,
because it can free an array of VLEN objects.

WARNING: this code is incorrect because it will only
work if the basetype of the vlen is
- atomic
- + enum
- + opaque
- excluding string basetype,

The reason is that to operate properly, it needs to recurse when
the basetype is a complex object such as another vlen or compound.

\param vl pointer to the vlen object.

\returns ::NC_NOERR No error.
*/


/**
\ingroup user_types
Free an array of vlens given the number of elements and an array.

When you read VLEN type the library will actually allocate the storage
space for the data. This storage space must be freed, so pass the
pointer back to this function, when you're done with the data, and it
will free the vlen memory.

WARNING: this code is incorrect because it will only
work if the basetype of the vlen is
- atomic
- + enum
- + opaque
- excluding string basetype,

The reason is that to operate properly, it needs to recurse when
the basetype is a complex object such as another vlen or compound.

\param len number of elements in the array.
\param vlens pointer to the vlen object.

\returns ::NC_NOERR No error.
*/


/**
\ingroup user_types
Use this function to define a variable length array type.

\param ncid \ref ncid
\param name \ref object_name of new type.

\param base_typeid The typeid of the base type of the VLEN. For
example, for a VLEN of shorts, the base type is ::NC_SHORT. This can be
a user defined type.

\param xtypep A pointer to an nc_type variable. The typeid of the new
VLEN type will be set here.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\returns ::NC_ENAMEINUSE That name is in use.
\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
\returns ::NC_EBADNAME Name contains illegal characters.
\returns ::NC_EPERM Attempt to write to a read-only file.
\returns ::NC_ENOTINDEFINE Not in define mode.
 */


/** \ingroup user_types
Learn about a VLEN type.

\param ncid \ref ncid
\param xtype The type of the VLEN to inquire about.
\param name \ref object_name of the type. \ref ignored_if_null.

\param datum_sizep A pointer to a size_t, this will get the size of
one element of this vlen. \ref ignored_if_null.

\param base_nc_typep Pointer to get the base type of the VLEN. \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/** \internal
\ingroup user_types

Put a VLEN element. This function writes an element of a VLEN for the
Fortran APIs.

\param ncid \ref ncid
\param typeid1 Typeid of the VLEN.
\param vlen_element Pointer to the element of the VLEN.
\param len Length of the VLEN element.
\param data VLEN data.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\returns ::NC_EPERM Attempt to write to a read-only file.
 */


/**
\internal
\ingroup user_types

Get a VLEN element. This function reads an element of a VLEN for the
Fortran APIs.

\param ncid \ref ncid
\param typeid1 Typeid of the VLEN.
\param vlen_element Pointer to the element of the VLEN.
\param len Length of the VLEN element.
\param data VLEN data.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**
 * @internal This function only does anything for netcdf-3 files.
 *
 * @param ncid Ignored.
 * @param pe Ignored.
 *
 * @return ::NC_ENOTNC3 Not a netCDF classic format file.
 * @author Ed Hartnett
 */


/* Allow dispatch to do general initialization and finalization */


/** \ingroup user_types

Create a compound type. Provide an ncid, a name, and a total size (in
bytes) of one element of the completed compound type.

After calling this function, fill out the type with repeated calls to
nc_insert_compound(). Call nc_insert_compound() once for each field
you wish to insert into the compound type.

\param ncid \ref ncid
\param size The size, in bytes, of the compound type.
\param name \ref object_name of the created type.
\param typeidp The type ID of the new type is copied here.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENAMEINUSE That name is in use.
\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
\returns ::NC_EBADNAME Name contains illegal characters.
\returns ::NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file.
\returns ::NC_ENOTNC4 This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see nc_open).
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\returns ::NC_EPERM Attempt to write to a read-only file.
\returns ::NC_ENOTINDEFINE Not in define mode.

\section nc_def_compound_example Example

\code
struct s1
{
int i1;
int i2;
};
struct s1 data[DIM_LEN], data_in[DIM_LEN];

if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
if (nc_def_compound(ncid, sizeof(struct s1), SVC_REC, &typeid)) ERR;
if (nc_insert_compound(ncid, typeid, BATTLES_WITH_KLINGONS,
HOFFSET(struct s1, i1), NC_INT)) ERR;
if (nc_insert_compound(ncid, typeid, DATES_WITH_ALIENS,
HOFFSET(struct s1, i2), NC_INT)) ERR;
if (nc_def_dim(ncid, STARDATE, DIM_LEN, &dimid)) ERR;
if (nc_def_var(ncid, SERVICE_RECORD, typeid, 1, dimids, &varid)) ERR;
if (nc_put_var(ncid, varid, data)) ERR;
if (nc_close(ncid)) ERR;
\endcode
*/


/** \ingroup user_types
Insert a named field into a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param name The \ref object_name of the new field.

\param offset Offset in byte from the beginning of the compound type
for this field.

\param field_typeid The type of the field to be inserted.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENAMEINUSE That name is in use.
\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
\returns ::NC_EBADNAME Name contains illegal characters.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\returns ::NC_EPERM Attempt to write to a read-only file.
\returns ::NC_ENOTINDEFINE Not in define mode.
*/


/** \ingroup user_types
Insert a named array field into a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param name The \ref object_name of the new field.

\param offset Offset in byte from the beginning of the compound type
for this field.

\param field_typeid The type of the field to be inserted.

 \param ndims Number of dimensions in array.

 \param dim_sizes Array of dimension sizes.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENAMEINUSE That name is in use.
\returns ::NC_EMAXNAME Name exceeds max length NC_MAX_NAME.
\returns ::NC_EBADNAME Name contains illegal characters.
\returns ::NC_ESTRICTNC3 Attempting a netCDF-4 operation on a netCDF-3 file.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\returns ::NC_EPERM Attempt to write to a read-only file.
\returns ::NC_ENOTINDEFINE Not in define mode.
*/


/**  \ingroup user_types
Learn about a compound type. Get the number of fields, len, and
name of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param name Returned \ref object_name of compound type. \ref
ignored_if_null.

\param sizep Returned size of compound type in bytes. \ref ignored_if_null.

\param nfieldsp The number of fields in the compound type will be
placed here. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Learn the name of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param name Returned \ref object_name of compound type. \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Learn the size of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param sizep Returned size of compound type in bytes. \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Learn the number of fields in a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param nfieldsp The number of fields in the compound type will be
placed here. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Get information about one of the fields of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param fieldid A zero-based index number specifying a field in the
compound type.

\param name Returned \ref object_name of the field. \ref
ignored_if_null.

\param offsetp A pointer which will get the offset of the field. \ref
ignored_if_null.

\param field_typeidp A pointer which will get the typeid of the
field. \ref ignored_if_null.

\param ndimsp A pointer which will get the number of dimensions of the
field. \ref ignored_if_null.

\param dim_sizesp A pointer which will get the dimension sizes of the
field. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Get information about one of the fields of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param fieldid A zero-based index number specifying a field in the
compound type.

\param name Returned \ref object_name of the field. \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Get information about one of the fields of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param fieldid A zero-based index number specifying a field in the
compound type.

\param offsetp A pointer which will get the offset of the field. \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Get information about one of the fields of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param fieldid A zero-based index number specifying a field in the
compound type.

\param field_typeidp A pointer which will get the typeid of the
field. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Get information about one of the fields of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param fieldid A zero-based index number specifying a field in the
compound type.

\param ndimsp A pointer which will get the number of dimensions of the
field. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Get information about one of the fields of a compound type.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param fieldid A zero-based index number specifying a field in the
compound type.

\param dim_sizesp A pointer which will get the dimension sizes of the
field. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/**  \ingroup user_types
Learn the Index of a Named Field in a Compound Type. Get the index
 * of a field in a compound type from the name.

\param ncid \ref ncid

\param xtype The typeid for this compound type, as returned by
nc_def_compound(), or nc_inq_var().

\param name \ref object_name of the field. \ref ignored_if_null.

\param fieldidp A pointer which will get the index of the named
field. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad \ref ncid.
\returns ::NC_EBADTYPE Bad type id.
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
 */


/*!
\ingroup attributes
Write a string attribute.

The function nc_put_att_string adds or changes a variable attribute or
global attribute of an open netCDF dataset. The string type is only
available in netCDF-4/HDF5 files, when ::NC_CLASSIC_MODEL has not been
used in nc_create().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID of the variable to which the attribute will
be assigned or ::NC_GLOBAL for a global or group attribute.

\param name Attribute \ref object_name. \ref attribute_conventions may
apply.

\param len Number of values provided for the attribute.

\param value Pointer to one or more values.

\returns ::NC_NOERR No error.
\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
\returns ::NC_ENOTVAR Couldn't find varid.
\returns ::NC_EBADTYPE Fill value and var must be same type.
\returns ::NC_ENOMEM Out of memory
\returns ::NC_ELATEFILL Fill values must be written while the file
is still in initial define mode.
*/


/*!
\ingroup attributes
Write a text attribute.

Add or change a text attribute. If this attribute is new, or if the
space required to store the attribute is greater than before, the
netCDF dataset must be in define mode for classic formats (or
netCDF-4/HDF5 with NC_CLASSIC_MODEL).

Although it's possible to create attributes of all types, text and
double attributes are adequate for most purposes.

Use the nc_put_att function to create attributes of any type,
including user-defined types. We recommend using the type safe
versions of this function whenever possible.

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID of the variable to which the attribute will
be assigned or ::NC_GLOBAL for a global attribute.

\param name Attribute \ref object_name. \ref attribute_conventions may
apply.

\param len Number of values provided for the attribute.

\param value Pointer to one or more values.

\returns ::NC_NOERR No error.
\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
\returns ::NC_ENOTVAR Couldn't find varid.
\returns ::NC_EBADTYPE Fill value and var must be same type.
\returns ::NC_ENOMEM Out of memory
\returns ::NC_ELATEFILL Fill values must be written while the file
is still in initial define mode.

\note With netCDF-4 files, nc_put_att will notice if you are writing a
_Fill_Value_ attribute, and will tell the HDF5 layer to use the
specified fill value for that variable.

\section nc_put_att_text_example Example

Here is an example using nc_put_att_double() to add a variable
attribute named valid_range for a netCDF variable named rh and
nc_put_att_text() to add a global attribute named title to an existing
netCDF dataset named foo.nc:

\code
     #include <netcdf.h>
        ...
     int  status;
     int  ncid;
     int  rh_id;
     static double rh_range[] = {0.0, 100.0};
     static char title[] = "example netCDF dataset";
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_redef(ncid);
     if (status != NC_NOERR) handle_error(status);
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_put_att_double (ncid, rh_id, "valid_range",
                                 NC_DOUBLE, 2, rh_range);
     if (status != NC_NOERR) handle_error(status);
     status = nc_put_att_text (ncid, NC_GLOBAL, "title",
                               strlen(title), title)
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_enddef(ncid);
     if (status != NC_NOERR) handle_error(status);
\endcode
*/


/**
 * @internal Move odometer.
 *
 * @param odom Pointer to odometer.
 *
 * @return 0 or 1
 */


/** \internal
\ingroup variables

 */


/**
\internal
Get data for a variable.

\param ncid NetCDF or group ID.

\param varid Variable ID

\param value Pointer where the data will be copied. Memory must be
allocated by the user before this function is called.

\param memtype the NC type of the data after it is read into
memory. Data are converted from the variable's type to the memtype as
they are read.

\returns ::NC_NOERR No error.
\returns ::NC_ENOTVAR Variable not found.
\returns ::NC_EINVALCOORDS Index exceeds dimension bound.
\returns ::NC_EEDGE Start+count exceeds dimension bound.
\returns ::NC_ERANGE One or more of the values are out of range.
\returns ::NC_EINDEFINE Operation not allowed in define mode.
\returns ::NC_EBADID Bad ncid.

\ingroup variables
\author Dennis Heimbigner
 */


/** \internal
\ingroup variables
 Most dispatch tables will use the default procedures
*/


/** \internal
\ingroup variables
 */


/**
\internal
Called by externally visible nc_get_vars_xxx routines.

\param ncid NetCDF or group ID.

\param varid Variable ID

\param start start indices. Required for non-scalar vars.

\param edges count indices.

\param stride data strides.

\param value Pointer where the data will be copied. Memory must be
allocated by the user before this function is called.

\param memtype the NC type of the data after it is read into
memory. Data are converted from the variable's type to the memtype as
they are read.

\returns ::NC_NOERR No error.
\returns ::NC_ENOTVAR Variable not found.
\returns ::NC_EINVALCOORDS Index exceeds dimension bound.
\returns ::NC_EEDGE Start+count exceeds dimension bound.
\returns ::NC_ERANGE One or more of the values are out of range.
\returns ::NC_EINDEFINE Operation not allowed in define mode.
\returns ::NC_EBADID Bad ncid.

\ingroup variables
\author Dennis Heimbigner, Ed Hartnett
*/


/**
\internal
Called by externally visible nc_get_varm_xxx routines. Note that the
varm routines are deprecated. Use the vars routines instead for new
code.

\param ncid NetCDF or group ID.

\param varid Variable ID

\param start start indices.

\param edges count indices.

\param stride data strides.

\param map mapping of dimensions.

\param value Pointer where the data will be copied. Memory must be
allocated by the user before this function is called.

\param memtype the NC type of the data after it is read into
memory. Data are converted from the variable's type to the memtype as
they are read.

\returns ::NC_NOERR No error.
\returns ::NC_ENOTVAR Variable not found.
\returns ::NC_EINVALCOORDS Index exceeds dimension bound.
\returns ::NC_EEDGE Start+count exceeds dimension bound.
\returns ::NC_ERANGE One or more of the values are out of range.
\returns ::NC_EINDEFINE Operation not allowed in define mode.
\returns ::NC_EBADID Bad ncid.

\ingroup variables
\author Dennis Heimbigner, Ed Hartnett
 */


/**
\ingroup variables
Find the ID of a variable, from the name.

The function nc_inq_varid returns the ID of a netCDF variable, given
its name.

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param name Name of the variable.

\param varidp Pointer to location for returned variable ID.  \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.

\section nc_inq_varid_example4 Example

Here is an example using nc_inq_varid to find out the ID of a variable
named rh in an existing netCDF dataset named foo.nc:

\code
     #include <netcdf.h>
        ...
     int  status, ncid, rh_id;
        ...
     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
\endcode
 */


/**
\ingroup variables
Learn about a variable.

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param name Returned \ref object_name of variable. \ref
ignored_if_null.

\param xtypep Pointer where typeid will be stored. \ref ignored_if_null.

\param ndimsp Pointer where number of dimensions will be
stored. \ref ignored_if_null.

\param dimidsp Pointer where array of dimension IDs will be
stored. \ref ignored_if_null.

\param nattsp Pointer where number of attributes will be
stored. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.

\section nc_inq_var_example5 Example

Here is an example using nc_inq_var() to find out about a variable named
rh in an existing netCDF dataset named foo.nc:

\code
     #include <netcdf.h>
        ...
     int  status
     int  ncid;
     int  rh_id;
     nc_type rh_type;
     int rh_ndims;
     int  rh_dimids[NC_MAX_VAR_DIMS];
     int rh_natts
        ...
     status = nc_open ("foo.nc", NC_NOWRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
     status = nc_inq_var (ncid, rh_id, 0, &rh_type, &rh_ndims, rh_dimids,
                          &rh_natts);
     if (status != NC_NOERR) handle_error(status);
\endcode

 */


/**
\ingroup variables
Learn the name of a variable.

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param name Returned variable name. The caller must allocate space for
the returned name. The maximum length is ::NC_MAX_NAME. Ignored if
NULL.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
 */


/** Learn the type of a variable.
\ingroup variables

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param typep Pointer where typeid will be stored. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
 */


/**
Learn how many dimensions are associated with a variable.
\ingroup variables

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param ndimsp Pointer where number of dimensions will be
stored. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
 */


/**
Learn the dimension IDs associated with a variable.
\ingroup variables

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param dimidsp Pointer where array of dimension IDs will be
stored. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
 */


/**
Learn how many attributes are associated with a variable.
\ingroup variables

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param nattsp Pointer where number of attributes will be
stored. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
 */


/** \ingroup variables
Learn the storage and deflate settings for a variable.

This is a wrapper for nc_inq_var_all().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param shufflep A 1 will be written here if the shuffle filter is
turned on for this variable, and a 0 otherwise. \ref ignored_if_null.

\param deflatep If this pointer is non-NULL, the nc_inq_var_deflate
function will write a 1 if the deflate filter is turned on for this
variable, and a 0 otherwise. \ref ignored_if_null.

\param deflate_levelp If the deflate filter is in use for this
variable, the deflate_level will be written here. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_ENOTNC4 Not a netCDF-4 file.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
*/


/** \ingroup variables
Learn the checksum settings for a variable.

This is a wrapper for nc_inq_var_all().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param fletcher32p Will be set to ::NC_FLETCHER32 if the fletcher32
checksum filter is turned on for this variable, and ::NC_NOCHECKSUM if
it is not. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTNC4 Not a netCDF-4 file.
\returns ::NC_ENOTVAR Invalid variable ID.
*/


/** \ingroup variables

This is a wrapper for nc_inq_var_all().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param storagep Address of returned storage property, returned as
::NC_CONTIGUOUS if this variable uses contiguous storage, or
::NC_CHUNKED if it uses chunked storage. \ref ignored_if_null.

\param chunksizesp The chunksizes will be copied here. \ref
ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTNC4 Not a netCDF-4 file.
\returns ::NC_ENOTVAR Invalid variable ID.

\section nc_inq_var_chunking_example Example

\code
        printf("**** testing contiguous storage...");
        {
     #define NDIMS6 1
     #define DIM6_NAME "D5"
     #define VAR_NAME6 "V5"
     #define DIM6_LEN 100

           int dimids[NDIMS6], dimids_in[NDIMS6];
           int varid;
           int ndims, nvars, natts, unlimdimid;
           nc_type xtype_in;
           char name_in[NC_MAX_NAME + 1];
           int data[DIM6_LEN], data_in[DIM6_LEN];
           size_t chunksize_in[NDIMS6];
           int storage_in;
           int i, d;

           for (i = 0; i < DIM6_LEN; i++)
              data[i] = i;

           if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
           if (nc_def_dim(ncid, DIM6_NAME, DIM6_LEN, &dimids[0])) ERR;
           if (dimids[0] != 0) ERR;
           if (nc_def_var(ncid, VAR_NAME6, NC_INT, NDIMS6, dimids, &varid)) ERR;
           if (nc_def_var_chunking(ncid, varid, NC_CONTIGUOUS, NULL)) ERR;
           if (nc_put_var_int(ncid, varid, data)) ERR;

           if (nc_inq_var_chunking(ncid, 0, &storage_in, chunksize_in)) ERR;
           if (storage_in != NC_CONTIGUOUS) ERR;
\endcode

*/


/** \ingroup variables
Learn the fill mode of a variable.

The fill mode of a variable is set by nc_def_var_fill().

This is a wrapper for nc_inq_var_all().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param no_fill Pointer to an integer which will get a 1 if no_fill
mode is set for this variable. \ref ignored_if_null.

\param fill_valuep A pointer which will get the fill value for this
variable. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
*/


/** \ingroup variables
Find the endianness of a variable.

This is a wrapper for nc_inq_var_all().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param endianp Storage which will get ::NC_ENDIAN_LITTLE if this
variable is stored in little-endian format, ::NC_ENDIAN_BIG if it is
stored in big-endian format, and ::NC_ENDIAN_NATIVE if the endianness
is not set, and the variable is not created yet.

\returns ::NC_NOERR No error.
\returns ::NC_ENOTNC4 Not a netCDF-4 file.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
*/


/**
Return number and list of unlimited dimensions.

In netCDF-4 files, it's possible to have multiple unlimited
dimensions. This function returns a list of the unlimited dimension
ids visible in a group.

Dimensions are visible in a group if they have been defined in that
group, or any ancestor group.

\param ncid NetCDF file and group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), etc.

\param nunlimdimsp A pointer to an int which will get the number of
visible unlimited dimensions. Ignored if NULL.

\param unlimdimidsp A pointer to an already allocated array of int
which will get the ids of all visible unlimited dimensions. Ignored if
NULL. To allocate the correct length for this array, call
nc_inq_unlimdims with a NULL for this parameter and use the
nunlimdimsp parameter to get the number of visible unlimited
dimensions.

\section nc_inq_unlimdims_example Example

Here is an example from nc_test4/tst_dims.c. In this example we create
a file with two unlimited dimensions, and then call nc_inq_unlimdims()
to check that there are 2 unlimited dimensions, and that they have
dimids 0 and 1.

\code
     #include <netcdf.h>
        ...
#define ROMULUS "Romulus"
#define REMUS "Remus"
#define DIMS2 2
   printf("*** Testing file with two unlimited dimensions...");
   {
      int ncid, dimid[DIMS2];
      int unlimdimid_in[DIMS2];
      int nunlimdims_in;

      if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
      if (nc_def_dim(ncid, REMUS, NC_UNLIMITED, &dimid[0])) ERR;
      if (nc_def_dim(ncid, ROMULUS, NC_UNLIMITED, &dimid[1])) ERR;

      ...
      if (nc_inq_unlimdims(ncid, &nunlimdims_in, unlimdimid_in)) ERR;
      if (nunlimdims_in != 2 || unlimdimid_in[0] != 0 || unlimdimid_in[1] != 1) ERR;
\endcode

This function will return one of the following values.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad group id.
\returns ::NC_ENOTNC4 Attempting a netCDF-4 operation on a netCDF-3
file. NetCDF-4 operations can only be performed on files defined with
a create mode which includes flag HDF5. (see nc_open).
\returns ::NC_ESTRICTNC3 This file was created with the strict
netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see
nc_open).
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
\author Ed Hartnett, Dennis Heimbigner
 */


/**
Find the filter (if any) associated with a variable.

This is a wrapper for nc_inq_var_all().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param idp Storage which will get the filter id.

\param nparamsp Storage which will get the number of parameters to the
filter

\param params Storage which will get associated parameters. Note
the caller must allocate and free.

\returns ::NC_NOERR No error.
\returns ::NC_ENOTNC4 Not a netCDF-4 file.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Invalid variable ID.
\returns ::NC_EFILTER No filter defined.
\ingroup variables
\author Dennis Heimbigner
*/


/** \ingroup variables
Learn the szip settings of a variable.
Similar to nc_inq_var_deflate.

This function returns the szip settings for a variable.
With the introduction of general filter support,
szip inquiry is converted to use the filter interface.

This is a wrapper for nc_inq_var_filter().

\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().

\param varid Variable ID

\param options_maskp The szip options mask will be copied to this
pointer. \ref ignored_if_null.

\param pixels_per_blockp The szip pixels per block will be copied
here. \ref ignored_if_null.

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTNC4 Not a netCDF-4 file.
\returns ::NC_ENOTVAR Invalid variable ID.
\returns ::NC_EFILTER Variable is not szip encoded
*/


/*!
Learn all about a variable.

@param[in] ncid ncid for file.
@param[in] varid varid for variable in question.
@param[out] name Pointer to memory to contain the name of the
variable.
@param[out] xtypep Pointer to memory to contain the type of the
variable.
@param[out] ndimsp Pointer to memory to store the number of associated
dimensions for the variable.
@param[out] dimidsp Pointer to memory to store the dimids associated
with the variable.
@param[out] nattsp Pointer to memory to store the number of attributes
associated with the variable.
@param[out] shufflep Pointer to memory to store shuffle information
associated with the variable.
@param[out] deflatep Pointer to memory to store compression type
associated with the variable.
@param[out] deflate_levelp Pointer to memory to store compression
level associated with the variable.
@param[out] fletcher32p Pointer to memory to store compression
information associated with the variable.
@param[out] contiguousp Pointer to memory to store contiguous-data
information associated with the variable.
@param[out] chunksizesp Pointer to memory to store chunksize
information associated with the variable.
@param[out] no_fill Pointer to memory to store whether or not there is
a fill value associated with the variable.
@param[out] fill_valuep Pointer to memory to store the fill value (if
one exists) for the variable.
@param[out] endiannessp Pointer to memory to store endianness
value. One of ::NC_ENDIAN_BIG ::NC_ENDIAN_LITTLE ::NC_ENDIAN_NATIVE
@param[out] idp Pointer to memory to store filter id.
@param[out] nparamsp Pointer to memory to store filter parameter count.
@param[out] params Pointer to vector of unsigned integers into which
to store filter parameters.
\note Expose access to nc_inq_var_all().

\returns ::NC_NOERR No error.
\returns ::NC_EBADID Bad ncid.
\returns ::NC_ENOTVAR Bad varid.
\returns ::NC_ENOMEM Out of memory.
\returns ::NC_EINVAL Invalid input.
\author Ed Hartnett, Dennis Heimbigner
\internal
\ingroup variables
*/


/**
@param objecturl url we propose to access
@param curlp curl handle stored here if non-NULL
@param filelenp store length of the file here if non-NULL
*/


/**
Assume URL etc has already been set.
@param curl curl handle
@param start starting offset
@param count number of bytes to read
@param buf store read data here -- caller must allocate and free
*/


/**
 * Add handling of user-defined format.
 *
 * @param mode_flag NC_UDF0 or NC_UDF1
 * @param dispatch_table Pointer to dispatch table to use for this user format.
 * @param magic_number Magic number used to identify file. Ignored if
 * NULL.
 *
 * @return ::NC_NOERR No error.
 * @return ::NC_EINVAL Invalid input.
 * @author Ed Hartnett
 * @ingroup datasets
 */


/**
 * Inquire about user-defined format.
 *
 * @param mode_flag NC_UDF0 or NC_UDF1
 * @param dispatch_table Pointer that gets pointer to dispatch table
 * to use for this user format, or NULL if this user-defined format is
 * not defined. Ignored if NULL.
 * @param magic_number Pointer that gets magic number used to identify
 * file, if one has been set. Magic number will be of max size
 * NC_MAX_MAGIC_NUMBER_LEN. Ignored if NULL.
 *
 * @return ::NC_NOERR No error.
 * @return ::NC_EINVAL Invalid input.
 * @author Ed Hartnett
 * @ingroup datasets
 */


/**  \ingroup datasets
Create a new netCDF file.

This function creates a new netCDF dataset, returning a netCDF ID that
can subsequently be used to refer to the netCDF dataset in other
netCDF function calls. The new netCDF dataset opened for write access
and placed in define mode, ready for you to add dimensions, variables,
and attributes.

\param path The file name of the new netCDF dataset.

\param cmode The creation mode flag. The following flags are available:
  NC_CLOBBER (overwrite existing file),
  NC_NOCLOBBER (do not overwrite existing file),
  NC_SHARE (limit write caching - netcdf classic files only),
  NC_64BIT_OFFSET (create 64-bit offset file),
  NC_64BIT_DATA (alias NC_CDF5) (create CDF-5 file),
  NC_NETCDF4 (create netCDF-4/HDF5 file),
  NC_CLASSIC_MODEL (enforce netCDF classic mode on netCDF-4/HDF5 files),
  NC_DISKLESS (store data in memory), and
  NC_PERSIST (force the NC_DISKLESS data from memory to a file),
  NC_MMAP (use MMAP for NC_DISKLESS instead of NC_INMEMORY -- deprecated).
  See discussion below.

\param ncidp Pointer to location where returned netCDF ID is to be
stored.

The cmode Flag

The cmode flag is used to control the type of file created, and some
aspects of how it may be used.

Setting NC_NOCLOBBER means you do not want to clobber (overwrite) an
existing dataset; an error (NC_EEXIST) is returned if the specified
dataset already exists.

The NC_SHARE flag is appropriate when one process may be writing the
dataset and one or more other processes reading the dataset
concurrently; it means that dataset accesses are not buffered and
caching is limited. Since the buffering scheme is optimized for
sequential access, programs that do not access data sequentially may
see some performance improvement by setting the NC_SHARE flag. This
flag is ignored for netCDF-4 files.

Setting NC_64BIT_OFFSET causes netCDF to create a 64-bit offset format
file, instead of a netCDF classic format file. The 64-bit offset
format imposes far fewer restrictions on very large (i.e. over 2 GB)
data files. See Large File Support.

Setting NC_64BIT_DATA (alias NC_CDF5) causes netCDF to create a CDF-5
file format that supports large files (i.e. over 2GB) and large
variables (over 2B array elements.). See Large File Support.

A zero value (defined for convenience as NC_CLOBBER) specifies the
default behavior: overwrite any existing dataset with the same file
name and buffer and cache accesses for efficiency. The dataset will be
in netCDF classic format. See NetCDF Classic Format Limitations.

Setting NC_NETCDF4 causes netCDF to create a HDF5/NetCDF-4 file.

Setting NC_CLASSIC_MODEL causes netCDF to enforce the classic data
model in this file. (This only has effect for netCDF-4/HDF5 files, as
CDF-1, 2 and 5 files always use the classic model.) When
used with NC_NETCDF4, this flag ensures that the resulting
netCDF-4/HDF5 file may never contain any new constructs from the
enhanced data model. That is, it cannot contain groups, user defined
types, multiple unlimited dimensions, or new atomic types. The
advantage of this restriction is that such files are guaranteed to
work with existing netCDF software.

Setting NC_DISKLESS causes netCDF to create the file only in
memory and to optionally write the final contents to the
correspondingly named disk file. This allows for the use of
files that have no long term purpose. Operating on an existing file
in memory may also be faster. The decision on whether
or not to "persist" the memory contents to a disk file is
described in detail in the file docs/inmemory.md, which is
definitive.  By default, closing a diskless fill will cause it's
contents to be lost.

If NC_DISKLESS is going to be used for creating a large classic
file, it behooves one to use nc__create and specify an
appropriately large value of the initialsz parameter to avoid to
many extensions to the in-memory space for the file.  This flag
applies to files in classic format and to file in extended
format (netcdf-4).

Note that nc_create(path,cmode,ncidp) is equivalent to the invocation of
nc__create(path,cmode,NC_SIZEHINT_DEFAULT,NULL,ncidp).

\returns ::NC_NOERR No error.
\returns ::NC_EEXIST Specifying a file name of a file that exists and also specifying NC_NOCLOBBER.
\returns ::NC_EPERM Attempting to create a netCDF file in a directory where you do not have permission to create files.
\returns ::NC_ENOMEM System out of memory.
\returns ::NC_ENFILE Too many files open.
\returns ::NC_EHDFERR HDF5 error (netCDF-4 files only).
\returns ::NC_EFILEMETA Error writing netCDF-4 file-level metadata in
HDF5 file. (netCDF-4 files only).
\returns ::NC_EDISKLESS if there was an error in creating the
in-memory file.

\note When creating a netCDF-4 file HDF5 error reporting is turned
off, if it is on. This doesn't stop the HDF5 error stack from
recording the errors, it simply stops their display to the user
through stderr.

Examples

In this example we create a netCDF dataset named foo.nc; we want the
dataset to be created in the current directory only if a dataset with
that name does not already exist:

@code
     #include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
        ...
     status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode

In this example we create a netCDF dataset named foo_large.nc. It will
be in the 64-bit offset format.

@code
     #include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
        ...
     status = nc_create("foo_large.nc", NC_NOCLOBBER|NC_64BIT_OFFSET, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode

In this example we create a netCDF dataset named foo_HDF5.nc. It will
be in the HDF5 format.

@code
     #include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
        ...
     status = nc_create("foo_HDF5.nc", NC_NOCLOBBER|NC_NETCDF4, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode

In this example we create a netCDF dataset named
foo_HDF5_classic.nc. It will be in the HDF5 format, but will not allow
the use of any netCDF-4 advanced features. That is, it will conform to
the classic netCDF-3 data model.

@code
     #include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
        ...
     status = nc_create("foo_HDF5_classic.nc", NC_NOCLOBBER|NC_NETCDF4|NC_CLASSIC_MODEL, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode

In this example we create an in-memory netCDF classic dataset named
diskless.nc whose content will be lost when nc_close() is called.

@code
     #include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
        ...
     status = nc_create("diskless.nc", NC_DISKLESS, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode

In this example we create a in-memory netCDF classic dataset named
diskless.nc and specify that it should be made persistent
in a file named diskless.nc when nc_close() is called.

@code
     #include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
        ...
     status = nc_create("diskless.nc", NC_DISKLESS|NC_PERSIST, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode

A variant of nc_create(), nc__create() (note the double underscore) allows
users to specify two tuning parameters for the file that it is
creating.  */


/**
 * Create a netCDF file with some extra parameters controlling classic
 * file caching.
 *
 * Like nc_create(), this function creates a netCDF file.
 *
 * @param path The file name of the new netCDF dataset.
 * @param cmode The creation mode flag, the same as in nc_create().
 * @param initialsz On some systems, and with custom I/O layers, it
 * may be advantageous to set the size of the output file at creation
 * time. This parameter sets the initial size of the file at creation
 * time. This only applies to classic CDF-1, 2, and 5 files.  The
 * special value NC_SIZEHINT_DEFAULT (which is the value 0), lets the
 * netcdf library choose a suitable initial size.
 * @param chunksizehintp A pointer to the chunk size hint, which
 * controls a space versus time tradeoff, memory allocated in the
 * netcdf library versus number of system calls. Because of internal
 * requirements, the value may not be set to exactly the value
 * requested. The actual value chosen is returned by reference. Using
 * a NULL pointer or having the pointer point to the value
 * NC_SIZEHINT_DEFAULT causes the library to choose a default. How the
 * system chooses the default depends on the system. On many systems,
 * the "preferred I/O block size" is available from the stat() system
 * call, struct stat member st_blksize. If this is available it is
 * used. Lacking that, twice the system pagesize is used. Lacking a
 * call to discover the system pagesize, we just set default bufrsize
 * to 8192. The bufrsize is a property of a given open netcdf
 * descriptor ncid, it is not a persistent property of the netcdf
 * dataset. This only applies to classic files.
 * @param ncidp Pointer to location where returned netCDF ID is to be
 * stored.
 *
 * @note This function uses the same return codes as the nc_create()
 * function.
 *
 * @returns ::NC_NOERR No error.
 * @returns ::NC_ENOMEM System out of memory.
 * @returns ::NC_EHDFERR HDF5 error (netCDF-4 files only).
 * @returns ::NC_EFILEMETA Error writing netCDF-4 file-level metadata in
 * HDF5 file. (netCDF-4 files only).
 * @returns ::NC_EDISKLESS if there was an error in creating the
 * in-memory file.
 *
 *
Examples

 *
 * In this example we create a netCDF dataset named foo_large.nc; we
 * want the dataset to be created in the current directory only if a
 * dataset with that name does not already exist. We also specify that
 * bufrsize and initial size for the file.
 *
 * @code
#include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
     int intialsz = 2048;
     int *bufrsize;
        ...
     *bufrsize = 1024;
     status = nc__create("foo.nc", NC_NOCLOBBER, initialsz, bufrsize, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode
 *
 * @ingroup datasets
 * @author Glenn Davis
*/


/** \ingroup datasets
Create a netCDF file with the contents stored in memory.

\param path Must be non-null, but otherwise only used to set the dataset name.

\param mode the mode flags; Note that this procedure uses a limited set of flags because it forcibly sets NC_INMEMORY.

\param initialsize (advisory) size to allocate for the created file

\param ncidp Pointer to location where returned netCDF ID is to be
stored.

\returns ::NC_NOERR No error.

\returns ::NC_ENOMEM Out of memory.

\returns ::NC_EDISKLESS diskless io is not enabled for fails.

\returns ::NC_EINVAL, etc. other errors also returned by nc_open.

Examples

In this example we use nc_create_mem() to create a classic netCDF dataset
named foo.nc. The initial size is set to 4096.

@code
     #include <netcdf.h>
        ...
     int status = NC_NOERR;
     int ncid;
     int mode = 0;
     size_t initialsize = 4096;
        ...
     status = nc_create_mem("foo.nc", mode, initialsize, &ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode
*/


/**
 * @internal Create a file with special (deprecated) Cray settings.
 *
 * @deprecated This function was used in the old days with the Cray at
 * NCAR. The Cray is long gone, and this call is supported only for
 * backward compatibility. Use nc_create() instead.
 *
 * @param path File name.
 * @param cmode Create mode.
 * @param initialsz Initial size of metadata region for classic files,
 * ignored for other files.
 * @param basepe Deprecated parameter from the Cray days.
 * @param chunksizehintp A pointer to the chunk size hint. This only
 * applies to classic files.
 * @param ncidp Pointer that gets ncid.
 *
 * @return ::NC_NOERR No error.
 * @author Glenn Davis
 */


/**
 * Open an existing netCDF file.
 *
 * This function opens an existing netCDF dataset for access. It
 * determines the underlying file format automatically. Use the same
 * call to open a netCDF classic or netCDF-4 file.
 *
 * @param path File name for netCDF dataset to be opened. When the dataset
 * is located on some remote server, then the path may be an OPeNDAP URL
 * rather than a file path.
 * @param omode The open mode flag may include NC_WRITE (for read/write
 * access) and NC_SHARE (see below) and NC_DISKLESS (see below).
 * @param ncidp Pointer to location where returned netCDF ID is to be
 * stored.
 *
 *
Open Mode

 *
 * A zero value (or ::NC_NOWRITE) specifies the default behavior: open
 * the dataset with read-only access, buffering and caching accesses
 * for efficiency.
 *
 * Otherwise, the open mode is ::NC_WRITE, ::NC_SHARE, or
 * ::NC_WRITE|::NC_SHARE. Setting the ::NC_WRITE flag opens the
 * dataset with read-write access. ("Writing" means any kind of change
 * to the dataset, including appending or changing data, adding or
 * renaming dimensions, variables, and attributes, or deleting
 * attributes.)
 *
 * The NC_SHARE flag is only used for netCDF classic
 * files. It is appropriate when one process may be writing the
 * dataset and one or more other processes reading the dataset
 * concurrently; it means that dataset accesses are not buffered and
 * caching is limited. Since the buffering scheme is optimized for
 * sequential access, programs that do not access data sequentially
 * may see some performance improvement by setting the NC_SHARE flag.
 *
 * This procedure may also be invoked with the NC_DISKLESS flag set in
 * the omode argument if the file to be opened is a classic format
 * file.  For nc_open(), this flag applies only to files in classic
 * format.  If the file is of type NC_NETCDF4, then the NC_DISKLESS
 * flag will be ignored.
 *
 * If NC_DISKLESS is specified, then the whole file is read completely
 * into memory. In effect this creates an in-memory cache of the file.
 * If the omode flag also specifies NC_PERSIST, then the in-memory cache
 * will be re-written to the disk file when nc_close() is called.  For
 * some kinds of manipulations, having the in-memory cache can speed
 * up file processing. But in simple cases, non-cached processing may
 * actually be faster than using cached processing.  You will need to
 * experiment to determine if the in-memory caching is worthwhile for
 * your application.
 *
 * Normally, NC_DISKLESS allocates space in the heap for storing the
 * in-memory file. If, however, the ./configure flags --enable-mmap is
 * used, and the additional omode flag NC_MMAP is specified, then the
 * file will be opened using the operating system MMAP facility.  This
 * flag only applies to files in classic format. Extended format
 * (netcdf-4) files will ignore the NC_MMAP flag.
 *
 * In most cases, using MMAP provides no advantage for just
 * NC_DISKLESS. The one case where using MMAP is an advantage is when
 * a file is to be opened and only a small portion of its data is to
 * be read and/or written.  In this scenario, MMAP will cause only the
 * accessed data to be retrieved from disk. Without MMAP, NC_DISKLESS
 * will read the whole file into memory on nc_open. Thus, MMAP will
 * provide some performance improvement in this case.
 *
 * It is not necessary to pass any information about the format of the
 * file being opened. The file type will be detected automatically by
 * the netCDF library.
 *
 * If a the path is a DAP URL, then the open mode is read-only.
 * Setting NC_WRITE will be ignored.
 *
 * As of version 4.3.1.2, multiple calls to nc_open with the same
 * path will return the same ncid value.
 *
 * @note When opening a netCDF-4 file HDF5 error reporting is turned
 * off, if it is on. This doesn't stop the HDF5 error stack from
 * recording the errors, it simply stops their display to the user
 * through stderr.
 *
 * nc_open()returns the value NC_NOERR if no errors
 * occurred. Otherwise, the returned status indicates an
 * error. Possible causes of errors include:
 *
 * Note that nc_open(path,omode,ncidp) is equivalent to the invocation
 * of nc__open(path,omode,NC_SIZEHINT_DEFAULT,NULL,ncidp).
 *
 * @returns ::NC_NOERR No error.
 * @returns ::NC_EPERM Attempting to create a netCDF file in a directory where you do not have permission to open files.
 * @returns ::NC_ENFILE Too many files open
 * @returns ::NC_ENOMEM Out of memory.
 * @returns ::NC_EHDFERR HDF5 error. (NetCDF-4 files only.)
 * @returns ::NC_EDIMMETA Error in netCDF-4 dimension metadata. (NetCDF-4 files only.)
 *
 *
Examples

 *
 * Here is an example using nc_open()to open an existing netCDF dataset
 * named foo.nc for read-only, non-shared access:
 *
 * @code
 * #include <netcdf.h>
 *   ...
 * int status = NC_NOERR;
 * int ncid;
 *   ...
 * status = nc_open("foo.nc", 0, &ncid);
 * if (status != NC_NOERR) handle_error(status);
 * @endcode
 * @ingroup datasets
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
*/


/** \ingroup datasets
Open a netCDF file with extra performance parameters for the classic
library.

\param path File name for netCDF dataset to be opened. When DAP
support is enabled, then the path may be an OPeNDAP URL rather than a
file path.

\param omode The open mode flag may include NC_WRITE (for read/write
access) and NC_SHARE as in nc_open().

\param chunksizehintp A size hint for the classic library. Only
applies to classic files. See below for more
information.

\param ncidp Pointer to location where returned netCDF ID is to be
stored.

The chunksizehintp Parameter

The argument referenced by bufrsizehintp controls a space versus time
tradeoff, memory allocated in the netcdf library versus number of
system calls.

Because of internal requirements, the value may not be set to exactly
the value requested. The actual value chosen is returned by reference.

Using a NULL pointer or having the pointer point to the value
NC_SIZEHINT_DEFAULT causes the library to choose a default.
How the system chooses the default depends on the system. On
many systems, the "preferred I/O block size" is available from the
stat() system call, struct stat member st_blksize. If this is
available it is used. Lacking that, twice the system pagesize is used.

Lacking a call to discover the system pagesize, we just set default
bufrsize to 8192.

The bufrsize is a property of a given open netcdf descriptor ncid, it
is not a persistent property of the netcdf dataset.

\returns ::NC_NOERR No error.

\returns ::NC_ENOMEM Out of memory.

\returns ::NC_EHDFERR HDF5 error. (NetCDF-4 files only.)

\returns ::NC_EDIMMETA Error in netCDF-4 dimension metadata. (NetCDF-4
files only.)

*/


/** \ingroup datasets
Open a netCDF file with the contents taken from a block of memory.

\param path Must be non-null, but otherwise only used to set the dataset name.

\param omode the open mode flags; Note that this procedure uses a limited set of flags because it forcibly sets NC_INMEMORY.

\param size The length of the block of memory being passed.

\param memory Pointer to the block of memory containing the contents
of a netcdf file.

\param ncidp Pointer to location where returned netCDF ID is to be
stored.

\returns ::NC_NOERR No error.

\returns ::NC_ENOMEM Out of memory.

\returns ::NC_EDISKLESS diskless io is not enabled for fails.

\returns ::NC_EINVAL, etc. other errors also returned by nc_open.

Examples

Here is an example using nc_open_mem() to open an existing netCDF dataset
named foo.nc for read-only, non-shared access. It differs from the nc_open()
example in that it assumes the contents of foo.nc have been read into memory.

@code
#include <netcdf.h>
#include <netcdf_mem.h>
   ...
int status = NC_NOERR;
int ncid;
size_t size;
void* memory;
   ...
size = <compute file size of foo.nc in bytes>;
memory = malloc(size);
   ...
status = nc_open_mem("foo.nc", 0, size, memory, &ncid);
if (status != NC_NOERR) handle_error(status);
@endcode
*/


/** \ingroup datasets
Open a netCDF file with the contents taken from a block of memory.
Similar to nc_open_mem, but with parameters. Warning: if you do
specify that the provided memory is locked, then never
pass in non-heap allocated memory. Additionally, if not locked,
then do not assume that the memory returned by nc_close_mem
is the same as passed to nc_open_memio. You must check
before attempting to free the original memory.

\param path Must be non-null, but otherwise only used to set the dataset name.

\param omode the open mode flags; Note that this procedure uses a limited set of flags because it forcibly sets NC_INMEMORY.

\param params controlling parameters

\param ncidp Pointer to location where returned netCDF ID is to be
stored.

\returns ::NC_NOERR No error.

\returns ::NC_ENOMEM Out of memory.

\returns ::NC_EDISKLESS diskless io is not enabled for fails.

\returns ::NC_EINVAL, etc. other errors also returned by nc_open.

Examples

Here is an example using nc_open_memio() to open an existing netCDF dataset
named foo.nc for read-only, non-shared access. It differs from the nc_open_mem()
example in that it uses a parameter block.

@code
#include <netcdf.h>
#include <netcdf_mem.h>
   ...
int status = NC_NOERR;
int ncid;
NC_memio params;
   ...
params.size = <compute file size of foo.nc in bytes>;
params.memory = malloc(size);
params.flags = <see netcdf_mem.h>
   ...
status = nc_open_memio("foo.nc", 0, &params, &ncid);
if (status != NC_NOERR) handle_error(status);
@endcode
*/


/**
 * @internal Open a netCDF file with extra parameters for Cray.
 *
 * @deprecated This function was used in the old days with the Cray at
 * NCAR. The Cray is long gone, and this call is supported only for
 * backward compatibility. Use nc_open() instead.
 *
 * @param path The file name of the new netCDF dataset.
 * @param omode Open mode.
 * @param basepe Deprecated parameter from the Cray days.
 * @param chunksizehintp A pointer to the chunk size hint. This only
 * applies to classic files.
 * @param ncidp Pointer to location where returned netCDF ID is to be
 * stored.
 *
 * @return ::NC_NOERR
 * @author Glenn Davis
 */


/** \ingroup datasets
Get the file pathname (or the opendap URL) which was used to
open/create the ncid's file.

\param ncid NetCDF ID, from a previous call to nc_open() or
nc_create().

\param pathlen Pointer where length of path will be returned. Ignored
if NULL.

\param path Pointer where path name will be copied. Space must already
be allocated. Ignored if NULL.

\returns ::NC_NOERR No error.

\returns ::NC_EBADID Invalid ncid passed.
*/


/** \ingroup datasets
Put open netcdf dataset into define mode

The function nc_redef puts an open netCDF dataset into define mode, so
dimensions, variables, and attributes can be added or renamed and
attributes can be deleted.

For netCDF-4 files (i.e. files created with NC_NETCDF4 in the cmode in
their call to nc_create()), it is not necessary to call nc_redef()
unless the file was also created with NC_STRICT_NC3. For straight-up
netCDF-4 files, nc_redef() is called automatically, as needed.

For all netCDF-4 files, the root ncid must be used. This is the ncid
returned by nc_open() and nc_create(), and points to the root of the
hierarchy tree for netCDF-4 files.

\param ncid NetCDF ID, from a previous call to nc_open() or
nc_create().

\returns ::NC_NOERR No error.

\returns ::NC_EBADID Bad ncid.

\returns ::NC_EBADGRPID The ncid must refer to the root group of the
file, that is, the group returned by nc_open() or nc_create().

\returns ::NC_EINDEFINE Already in define mode.

\returns ::NC_EPERM File is read-only.

Example

Here is an example using nc_redef to open an existing netCDF dataset
named foo.nc and put it into define mode:

\code
#include <netcdf.h>
   ...
int status = NC_NOERR;
int ncid;
   ...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
   ...
status = nc_redef(ncid);
if (status != NC_NOERR) handle_error(status);
\endcode
 */