mirror of
https://github.com/Unidata/netcdf-c.git
synced 2025-02-11 16:40:36 +08:00
more documentation cleanup
This commit is contained in:
parent
2f8f5baf0f
commit
c620d8c5c7
@ -9,7 +9,7 @@
|
|||||||
#include "netcdf_f.h"
|
#include "netcdf_f.h"
|
||||||
|
|
||||||
/**
|
/**
|
||||||
\defgroup variables Variables
|
@defgroup variables Variables
|
||||||
|
|
||||||
Variables hold multi-dimensional arrays of data.
|
Variables hold multi-dimensional arrays of data.
|
||||||
|
|
||||||
@ -55,7 +55,7 @@
|
|||||||
index mapping vector.
|
index mapping vector.
|
||||||
- Rename a variable.
|
- Rename a variable.
|
||||||
|
|
||||||
\section language_types Language Types Corresponding to netCDF
|
@section language_types Language Types Corresponding to netCDF
|
||||||
External Data Types
|
External Data Types
|
||||||
|
|
||||||
NetCDF supported six atomic data types through version 3.6.0 (char,
|
NetCDF supported six atomic data types through version 3.6.0 (char,
|
||||||
@ -68,7 +68,7 @@
|
|||||||
files. To create netCDF-4/HDF5 files, use the HDF5 flag in
|
files. To create netCDF-4/HDF5 files, use the HDF5 flag in
|
||||||
nc_create. (see nc_create).
|
nc_create. (see nc_create).
|
||||||
|
|
||||||
\section classic_types NetCDF-3 Classic and 64-Bit Offset Data Types
|
@section classic_types NetCDF-3 Classic and 64-Bit Offset Data Types
|
||||||
|
|
||||||
NetCDF-3 classic and 64-bit offset files support 6 atomic data types,
|
NetCDF-3 classic and 64-bit offset files support 6 atomic data types,
|
||||||
and none of the user defined datatype introduced in NetCDF-4.
|
and none of the user defined datatype introduced in NetCDF-4.
|
||||||
@ -94,7 +94,7 @@
|
|||||||
column gives the number of bits used in the external representation of
|
column gives the number of bits used in the external representation of
|
||||||
values of the corresponding type.
|
values of the corresponding type.
|
||||||
|
|
||||||
\section netcdf_4_atomic NetCDF-4 Atomic Types
|
@section netcdf_4_atomic NetCDF-4 Atomic Types
|
||||||
|
|
||||||
NetCDF-4 files support all of the atomic data types from netCDF-3,
|
NetCDF-4 files support all of the atomic data types from netCDF-3,
|
||||||
plus additional unsigned integer types, 64-bit integer types, and a
|
plus additional unsigned integer types, 64-bit integer types, and a
|
||||||
@ -127,7 +127,7 @@
|
|||||||
|
|
||||||
Use these functions to define variables.
|
Use these functions to define variables.
|
||||||
*/
|
*/
|
||||||
/*! \{ */
|
/*! @{ */
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@ingroup variables
|
@ingroup variables
|
||||||
@ -142,9 +142,9 @@
|
|||||||
nc_create(), nc_def_grp(), or associated inquiry functions such as
|
nc_create(), nc_def_grp(), or associated inquiry functions such as
|
||||||
nc_inq_ncid().
|
nc_inq_ncid().
|
||||||
|
|
||||||
@param name Variable \ref object_name.
|
@param name Variable @ref object_name.
|
||||||
|
|
||||||
@param xtype \ref data_type of the variable.
|
@param xtype @ref data_type of the variable.
|
||||||
|
|
||||||
@param ndims Number of dimensions for the variable. For example, 2
|
@param ndims Number of dimensions for the variable. For example, 2
|
||||||
specifies a matrix, 1 specifies a vector, and 0 means the variable is
|
specifies a matrix, 1 specifies a vector, and 0 means the variable is
|
||||||
@ -219,14 +219,14 @@ nc_def_var(int ncid, const char *name, nc_type xtype,
|
|||||||
return ncp->dispatch->def_var(ncid, name, xtype, ndims,
|
return ncp->dispatch->def_var(ncid, name, xtype, ndims,
|
||||||
dimidsp, varidp);
|
dimidsp, varidp);
|
||||||
}
|
}
|
||||||
/*! \} */
|
/*! @} */
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@name Rename a Variable
|
@name Rename a Variable
|
||||||
|
|
||||||
Rename a variable.
|
Rename a variable.
|
||||||
*/
|
*/
|
||||||
/*! \{ */
|
/*! @{ */
|
||||||
|
|
||||||
/**
|
/**
|
||||||
Rename a variable.
|
Rename a variable.
|
||||||
@ -295,7 +295,7 @@ nc_rename_var(int ncid, int varid, const char *name)
|
|||||||
TRACE(nc_rename_var);
|
TRACE(nc_rename_var);
|
||||||
return ncp->dispatch->rename_var(ncid, varid, name);
|
return ncp->dispatch->rename_var(ncid, varid, name);
|
||||||
}
|
}
|
||||||
/*! \} */
|
/*! @} */
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@ingroup variables
|
@ingroup variables
|
||||||
@ -470,8 +470,8 @@ nctypelen(nc_type type)
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \internal
|
/** @internal
|
||||||
\ingroup variables
|
@ingroup variables
|
||||||
Find the length of a type. Redundant over nctypelen() above. */
|
Find the length of a type. Redundant over nctypelen() above. */
|
||||||
size_t
|
size_t
|
||||||
NC_atomictypelen(nc_type xtype)
|
NC_atomictypelen(nc_type xtype)
|
||||||
@ -498,8 +498,8 @@ NC_atomictypelen(nc_type xtype)
|
|||||||
return sz;
|
return sz;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \internal
|
/** @internal
|
||||||
\ingroup variables
|
@ingroup variables
|
||||||
Get the type name. */
|
Get the type name. */
|
||||||
char *
|
char *
|
||||||
NC_atomictypename(nc_type xtype)
|
NC_atomictypename(nc_type xtype)
|
||||||
@ -526,8 +526,8 @@ NC_atomictypename(nc_type xtype)
|
|||||||
return nm;
|
return nm;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \internal
|
/** @internal
|
||||||
\ingroup variables
|
@ingroup variables
|
||||||
Get the shape of a variable.
|
Get the shape of a variable.
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
@ -708,7 +708,7 @@ NC_check_nulls(int ncid, int varid, const size_t *start, size_t **count,
|
|||||||
return NC_NOERR;
|
return NC_NOERR;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup variables
|
/** @ingroup variables
|
||||||
Free string space allocated by the library.
|
Free string space allocated by the library.
|
||||||
|
|
||||||
When you read string type the library will allocate the storage space
|
When you read string type the library will allocate the storage space
|
||||||
@ -716,10 +716,10 @@ NC_check_nulls(int ncid, int varid, const size_t *start, size_t **count,
|
|||||||
back to this function, when you're done with the data, and it will
|
back to this function, when you're done with the data, and it will
|
||||||
free the string memory.
|
free the string memory.
|
||||||
|
|
||||||
\param len The number of character arrays in the array.
|
@param len The number of character arrays in the array.
|
||||||
\param data The pointer to the data array.
|
@param data The pointer to the data array.
|
||||||
|
|
||||||
\returns ::NC_NOERR No error.
|
@returns ::NC_NOERR No error.
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
nc_free_string(size_t len, char **data)
|
nc_free_string(size_t len, char **data)
|
||||||
@ -731,7 +731,7 @@ nc_free_string(size_t len, char **data)
|
|||||||
}
|
}
|
||||||
|
|
||||||
#ifdef USE_NETCDF4
|
#ifdef USE_NETCDF4
|
||||||
/** \ingroup variables
|
/** @ingroup variables
|
||||||
|
|
||||||
Change the cache settings for a chunked variable. This function allows
|
Change the cache settings for a chunked variable. This function allows
|
||||||
users to control the amount of memory used in the per-variable chunk
|
users to control the amount of memory used in the per-variable chunk
|
||||||
@ -739,35 +739,35 @@ nc_free_string(size_t len, char **data)
|
|||||||
until the file is closed. Once re-opened, the variable chunk cache
|
until the file is closed. Once re-opened, the variable chunk cache
|
||||||
returns to its default value.
|
returns to its default value.
|
||||||
|
|
||||||
\param ncid NetCDF or group ID, from a previous call to nc_open(),
|
@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_create(), nc_def_grp(), or associated inquiry functions such as
|
||||||
nc_inq_ncid().
|
nc_inq_ncid().
|
||||||
|
|
||||||
\param varid Variable ID
|
@param varid Variable ID
|
||||||
|
|
||||||
\param size The total size of the raw data chunk cache, in bytes.
|
@param size The total size of the raw data chunk cache, in bytes.
|
||||||
|
|
||||||
\param nelems The number of chunk slots in the raw data chunk cache.
|
@param nelems The number of chunk slots in the raw data chunk cache.
|
||||||
|
|
||||||
\param preemption The preemption, a value between 0 and 1 inclusive
|
@param preemption The preemption, a value between 0 and 1 inclusive
|
||||||
that indicates how much chunks that have been fully read are favored
|
that indicates how much chunks that have been fully read are favored
|
||||||
for preemption. A value of zero means fully read chunks are treated no
|
for preemption. A value of zero means fully read chunks are treated no
|
||||||
differently than other chunks (the preemption is strictly LRU) while a
|
differently than other chunks (the preemption is strictly LRU) while a
|
||||||
value of one means fully read chunks are always preempted before other
|
value of one means fully read chunks are always preempted before other
|
||||||
chunks.
|
chunks.
|
||||||
|
|
||||||
\returns ::NC_NOERR No error.
|
@returns ::NC_NOERR No error.
|
||||||
\returns ::NC_EBADID Bad ncid.
|
@returns ::NC_EBADID Bad ncid.
|
||||||
\returns ::NC_ENOTVAR Invalid variable ID.
|
@returns ::NC_ENOTVAR Invalid variable ID.
|
||||||
\returns ::NC_ESTRICTNC3 Attempting netcdf-4 operation on strict nc3 netcdf-4 file.
|
@returns ::NC_ESTRICTNC3 Attempting netcdf-4 operation on strict nc3 netcdf-4 file.
|
||||||
\returns ::NC_EINVAL Invalid input
|
@returns ::NC_EINVAL Invalid input
|
||||||
|
|
||||||
\section nc_def_var_chunk_cache_example Example
|
@section nc_def_var_chunk_cache_example Example
|
||||||
|
|
||||||
In this example from nc_test4/tst_coords.c, a variable is defined, and
|
In this example from nc_test4/tst_coords.c, a variable is defined, and
|
||||||
the chunk cache settings are changed for that variable.
|
the chunk cache settings are changed for that variable.
|
||||||
|
|
||||||
\code
|
@code
|
||||||
printf("**** testing setting cache values for coordinate variables...");
|
printf("**** testing setting cache values for coordinate variables...");
|
||||||
{
|
{
|
||||||
#define RANK_1 1
|
#define RANK_1 1
|
||||||
@ -788,7 +788,7 @@ nc_free_string(size_t len, char **data)
|
|||||||
...
|
...
|
||||||
}
|
}
|
||||||
SUMMARIZE_ERR;
|
SUMMARIZE_ERR;
|
||||||
\endcode
|
@endcode
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
nc_set_var_chunk_cache(int ncid, int varid, size_t size, size_t nelems,
|
nc_set_var_chunk_cache(int ncid, int varid, size_t size, size_t nelems,
|
||||||
@ -801,35 +801,35 @@ nc_set_var_chunk_cache(int ncid, int varid, size_t size, size_t nelems,
|
|||||||
nelems, preemption);
|
nelems, preemption);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup variables
|
/** @ingroup variables
|
||||||
|
|
||||||
Get the per-variable chunk cache settings from the HDF5 layer.
|
Get the per-variable chunk cache settings from the HDF5 layer.
|
||||||
|
|
||||||
\param ncid NetCDF or group ID, from a previous call to nc_open(),
|
@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_create(), nc_def_grp(), or associated inquiry functions such as
|
||||||
nc_inq_ncid().
|
nc_inq_ncid().
|
||||||
|
|
||||||
\param varid Variable ID
|
@param varid Variable ID
|
||||||
|
|
||||||
\param sizep The total size of the raw data chunk cache, in bytes,
|
@param sizep The total size of the raw data chunk cache, in bytes,
|
||||||
will be put here. \ref ignored_if_null.
|
will be put here. @ref ignored_if_null.
|
||||||
|
|
||||||
\param nelemsp The number of chunk slots in the raw data chunk cache
|
@param nelemsp The number of chunk slots in the raw data chunk cache
|
||||||
hash table will be put here. \ref ignored_if_null.
|
hash table will be put here. @ref ignored_if_null.
|
||||||
|
|
||||||
\param preemptionp The preemption will be put here. The preemtion
|
@param preemptionp The preemption will be put here. The preemtion
|
||||||
value is between 0 and 1 inclusive and indicates how much chunks that
|
value is between 0 and 1 inclusive and indicates how much chunks that
|
||||||
have been fully read are favored for preemption. A value of zero means
|
have been fully read are favored for preemption. A value of zero means
|
||||||
fully read chunks are treated no differently than other chunks (the
|
fully read chunks are treated no differently than other chunks (the
|
||||||
preemption is strictly LRU) while a value of one means fully read
|
preemption is strictly LRU) while a value of one means fully read
|
||||||
chunks are always preempted before other chunks. \ref ignored_if_null.
|
chunks are always preempted before other chunks. @ref ignored_if_null.
|
||||||
|
|
||||||
\returns ::NC_NOERR No error.
|
@returns ::NC_NOERR No error.
|
||||||
\returns ::NC_EBADID Bad ncid.
|
@returns ::NC_EBADID Bad ncid.
|
||||||
\returns ::NC_ENOTVAR Invalid variable ID.
|
@returns ::NC_ENOTVAR Invalid variable ID.
|
||||||
\returns ::NC_ESTRICTNC3 Attempting netcdf-4 operation on strict nc3
|
@returns ::NC_ESTRICTNC3 Attempting netcdf-4 operation on strict nc3
|
||||||
netcdf-4 file.
|
netcdf-4 file.
|
||||||
\returns ::NC_EINVAL Invalid input
|
@returns ::NC_EINVAL Invalid input
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
nc_get_var_chunk_cache(int ncid, int varid, size_t *sizep, size_t *nelemsp,
|
nc_get_var_chunk_cache(int ncid, int varid, size_t *sizep, size_t *nelemsp,
|
||||||
@ -986,7 +986,7 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32)
|
|||||||
|
|
||||||
/*! Define chunking parameters for a variable
|
/*! Define chunking parameters for a variable
|
||||||
|
|
||||||
\ingroup variables
|
@ingroup variables
|
||||||
|
|
||||||
The function nc_def_var_chunking sets the chunking parameters for a
|
The function nc_def_var_chunking sets the chunking parameters for a
|
||||||
variable in a netCDF-4 file. It can set the chunk sizes to get chunked
|
variable in a netCDF-4 file. It can set the chunk sizes to get chunked
|
||||||
@ -1003,12 +1003,12 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32)
|
|||||||
Note that this does not work for scalar variables. Only non-scalar
|
Note that this does not work for scalar variables. Only non-scalar
|
||||||
variables can have chunking.
|
variables can have chunking.
|
||||||
|
|
||||||
\param[in] ncid NetCDF ID, from a previous call to nc_open or
|
@param[in] ncid NetCDF ID, from a previous call to nc_open or
|
||||||
nc_create.
|
nc_create.
|
||||||
|
|
||||||
\param[in] varid Variable ID.
|
@param[in] varid Variable ID.
|
||||||
|
|
||||||
\param[in] storage If ::NC_CONTIGUOUS, then contiguous storage is used
|
@param[in] storage If ::NC_CONTIGUOUS, then contiguous storage is used
|
||||||
for this variable. Variables with one or more unlimited dimensions
|
for this variable. Variables with one or more unlimited dimensions
|
||||||
cannot use contiguous storage. If contiguous storage is turned on, the
|
cannot use contiguous storage. If contiguous storage is turned on, the
|
||||||
chunksizes parameter is ignored. If ::NC_CHUNKED, then chunked storage
|
chunksizes parameter is ignored. If ::NC_CHUNKED, then chunked storage
|
||||||
@ -1016,7 +1016,7 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32)
|
|||||||
chunksizes parameter or default sizes will be used if that parameter
|
chunksizes parameter or default sizes will be used if that parameter
|
||||||
is NULL.
|
is NULL.
|
||||||
|
|
||||||
\param[in] chunksizesp A pointer to an array list of chunk sizes. The
|
@param[in] chunksizesp A pointer to an array list of chunk sizes. The
|
||||||
array must have one chunksize for each dimension of the variable. If
|
array must have one chunksize for each dimension of the variable. If
|
||||||
::NC_CONTIGUOUS storage is set, then the chunksizes parameter is
|
::NC_CONTIGUOUS storage is set, then the chunksizes parameter is
|
||||||
ignored.
|
ignored.
|
||||||
@ -1031,18 +1031,18 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32)
|
|||||||
set the chunking for that variable.
|
set the chunking for that variable.
|
||||||
* @returns ::NC_ENOTINDEFINE Not in define mode. This is returned for
|
* @returns ::NC_ENOTINDEFINE Not in define mode. This is returned for
|
||||||
netCDF classic or 64-bit offset files, or for netCDF-4 files, when
|
netCDF classic or 64-bit offset files, or for netCDF-4 files, when
|
||||||
they wwere created with NC_STRICT_NC3 flag. See \ref nc_create.
|
they wwere created with NC_STRICT_NC3 flag. See @ref nc_create.
|
||||||
* @returns ::NC_EPERM Attempt to create object in read-only file.
|
* @returns ::NC_EPERM Attempt to create object in read-only file.
|
||||||
* @returns ::NC_EBADCHUNK Retunrs if the chunk size specified for a
|
* @returns ::NC_EBADCHUNK Retunrs if the chunk size specified for a
|
||||||
variable is larger than the length of the dimensions associated with
|
variable is larger than the length of the dimensions associated with
|
||||||
variable.
|
variable.
|
||||||
|
|
||||||
\section nc_def_var_chunking_example Example
|
@section nc_def_var_chunking_example Example
|
||||||
|
|
||||||
In this example from libsrc4/tst_vars2.c, chunksizes are set with
|
In this example from libsrc4/tst_vars2.c, chunksizes are set with
|
||||||
nc_var_def_chunking, and checked with nc_var_inq_chunking.
|
nc_var_def_chunking, and checked with nc_var_inq_chunking.
|
||||||
|
|
||||||
\code
|
@code
|
||||||
printf("**** testing chunking...");
|
printf("**** testing chunking...");
|
||||||
{
|
{
|
||||||
#define NDIMS5 1
|
#define NDIMS5 1
|
||||||
@ -1074,7 +1074,7 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32)
|
|||||||
for (d = 0; d < NDIMS5; d++)
|
for (d = 0; d < NDIMS5; d++)
|
||||||
if (chunksize[d] != chunksize_in[d]) ERR;
|
if (chunksize[d] != chunksize_in[d]) ERR;
|
||||||
if (storage_in != NC_CHUNKED) ERR;
|
if (storage_in != NC_CHUNKED) ERR;
|
||||||
\endcode
|
@endcode
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
nc_def_var_chunking(int ncid, int varid, int storage,
|
nc_def_var_chunking(int ncid, int varid, int storage,
|
||||||
@ -1123,7 +1123,7 @@ nc_def_var_chunking(int ncid, int varid, int storage,
|
|||||||
set the chunking for that variable.
|
set the chunking for that variable.
|
||||||
@returns ::NC_ENOTINDEFINE Not in define mode. This is returned for
|
@returns ::NC_ENOTINDEFINE Not in define mode. This is returned for
|
||||||
netCDF classic or 64-bit offset files, or for netCDF-4 files, when
|
netCDF classic or 64-bit offset files, or for netCDF-4 files, when
|
||||||
they wwere created with NC_STRICT_NC3 flag. See \ref nc_create.
|
they wwere created with NC_STRICT_NC3 flag. See @ref nc_create.
|
||||||
@returns ::NC_EPERM Attempt to create object in read-only file.
|
@returns ::NC_EPERM Attempt to create object in read-only file.
|
||||||
|
|
||||||
@section nc_def_var_endian_example Example
|
@section nc_def_var_endian_example Example
|
||||||
|
Loading…
Reference in New Issue
Block a user