     [file version.texi not included]
     [file defines.texi not included]

libcf-man
*********

This guide describes libcf, the netCDF CF Library. This document applies to libcf version VERSION, and was last updated on UPDATED.

Summary
*******

The CF conventions for climate and forecast metadata are designed to promote the processing and sharing of files created with the netCDF API.

This library, libcf, makes it easier to create and work with data files which conform to the CF conventions.

The functions of the CF library are intended to be interspersed with netCDF library calls. That is, the programmer will open or create a netCDF file with the netCDF API, and then add or read metadata with libcf library functions, then continue to working with the netCDF API to read and write data.

By using libcf, a data producer can produce files that conform to the CF standards, without having to write netCDF code to create and decode all the attributes that the CF convention uses to store meta-data. A data consumer can use libcf to read any file which conforms to the CF conventions; the file does not need to be created with libcf to be read by libcf.

Fortran-77 wrapper functions provide a Fortran 77 API, just as is done with netCDF itself. A Fortran 90 API is planned, but not yet begun.

For more information about the CF Conventions, see the CF Metadata web site at cf-url.

Downloading and Installing libcf
********************************

Currently, and for some time to come, libcf is in alpha release. The code is tested, but not extensively. The API may be extended, and possibly changed, in each release.

You must have either netCDF-3 (or netCDF-4) installed. And reasonably recent version of netCDF should work. libcf is tested with netCDF 3.6.2-beta4.

Get the latest version of the libcf tarball at the libcf ftp site: ftp-site

Unpack the tarball, and run:

     ./configure --with-netcdf=/my/netcdf --prefix=/my/libcf && make check install > output.txt

Where /my/netcdf is the root install directory of the netCDF library you want to use, and /my/libcf is the root directory where you want libcf installed. (They may be the same directory.)

If you wish to use netCDF-4, you must also have HDF5 and libz, the compression library, installed. In this case, configure libcf like this:

     ./configure --with-netcdf=/s/n4_new1/install --enable-netcdf-4 --with-hdf5=/home/ed/local/s && make check install > output.txt

If the build does not work for you, please email libcf support: libcf-support-email. Please send the *complete* output of the configure and build output, in ASCII (the output.txt file produced by the above build commands), and the file config.log, which is generated by the configure script.

The cfcheck Utility
*******************

The cfchck utility will chck a file to see if it contains valid CF metadata. Messages about the file are printed to stdout.

Files
*****

Mark a File as Conforming to CF Conventions
===========================================

Mark the file as following CF-1.0 conventions.

This functions is called automatically by nccf_def_file, so need not be called by the user if nccf_def_file is being called.

Usage
=====

        int nccf_def_convention(int ncid);

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Determine if a File Claims to Conform to CF Conventions
=======================================================

Determine if the file claims to follow CF-1.0 conventions. This function only checks the global ``Conventions'' attribute. It does not look at file metadata to ensure that this is a well-formed CF file. It only tells whether the file claims to be a CF file.

Usage
=====

        int nccf_inq_convention(int ncid, int *cf_convention);

ncid
     The ncid of the file.

cf_conventions
     If this pointer to an int is provided, a 1 is written there if this file claims to follow CF 1.0 conventions, a 0 otherwise.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Add description to the data with nccf_def_file
==============================================

Add some or all of the CF recommended text attributes to a file. Any parameters which are set to NULL will be ignored.

Usage
=====

     int nccf_def_file(int ncid, char *title, char *history, char *institution,
                       char *source, char *comment, char *references);

ncid
     The ncid of the file.

title
     If non-NULL, this text string will be written as the CF-recommended ``title'' attribute.

history
     If non-NULL, this text string will be written as the CF-recommended ``history'' attribute.

institution
     If non-NULL, this text string will be written as the CF-recommended ``institution'' attribute.

source
     If non-NULL, this text string will be written as the CF-recommended ``source'' attribute.

comment
     If non-NULL, this text string will be written as the CF-recommended ``comment'' attribute.

references
     If non-NULL, this text string will be written as the CF-recommended ``references'' attribute.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Read the description of the data with nccf_inq_file
===================================================

Read any existing CF recommended text attributes from the file.

Recall that in C, strlens do not include the null terminator. To get the lengths before the strings (in order to allocated) pass NULL for any or all strings and the lengths will be returned. Then call the function again after allocating memory.

The CF version is guaranteed to be less than NC_MAX_NAME.

Any of these pointer arguments may be NULL, in which case it will be ignored.

Usage
=====

     int nccf_inq_file(int ncid, size_t *title_lenp, char *title,
                       size_t *history_lenp, char *history,
                       size_t *institution_lenp, char *institution,
                       size_t *source_lenp, char *source,
                       size_t *comment_lenp, char *comment,
                       size_t *references_lenp, char *references);

ncid
     The ncid of the file.

title_lenp
     Pointer to size_t which, if not NULL, will get the length of the title attribute.

title
     Pointer to char array which, if not NULL, will get the title string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

history_lenp
     Pointer to size_t which, if not NULL, will get the length of the history attribute.

history
     Pointer to char array which, if not NULL, will get the history string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

institution_lenp
     Pointer to size_t which, if not NULL, will get the length of the institution attribute.

institution
     Pointer to char array which, if not NULL, will get the institution string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

source_lenp
     Pointer to size_t which, if not NULL, will get the length of the source attribute.

source
     Pointer to char array which, if not NULL, will get the source string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

comment_lenp
     Pointer to size_t which, if not NULL, will get the length of the comment attribute.

comment
     Pointer to char array which, if not NULL, will get the comment string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

references_lenp
     Pointer to size_t which, if not NULL, will get the length of the references attribute.

references
     Pointer to char array which, if not NULL, will get the references string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Append to a History Attribute
=============================

This function appends a time-stamped history string to the history attribute, creating the attribute if it doesn't already exist.

Usage
=====

     int nccf_add_history(int ncid, const char *history);

ncid
     The ncid of the file.

history
     The string to append to the history attribute.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Variables
*********

Add description to a variable with nccf_def_var
===============================================

Usage
=====

     int nccf_def_var(int ncid, int varid, const char *units,
                         const char *long_name, const char *standard_name,
                         int ncoord_vars, int *coord_varids);

ncid
     The ncid of the file.

varid
     The varid of the netCDF variable being described.

units
     If non-NULL, this text string will be written as the CF-recommended ``units'' attribute.

long_name
     If non-NULL, this text string will be written as the CF-recommended ``long_name'' attribute.

standard_name
     If non-NULL, this text string will be written as the CF-recommended ``standard_name'' attribute.

ncoord_vars
     Number of coordinate variables for this variable.

coord_varids
     The variable IDs of the coordinate variables for this variable.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Read variable description with nccf_inq_var
===========================================

Read any existing CF recommended text attributes from a variable.

Usage
=====

     int nccf_inq_var(int ncid, int varid, size_t *units_lenp, char *units,
                      size_t *long_name_lenp, char *long_name,
                      size_t *standard_name_lenp, char *standard_name,
                      int *ncoord_vars, int *coord_varids);

ncid
     The ncid of the file.

varid
     The varid of the netCDF variable.

units_lenp
     Pointer to size_t which, if not NULL, will get the length of the units attribute.

units
     Pointer to char array which, if not NULL, will get the long_name string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

long_name_lenp
     Pointer to size_t which, if not NULL, will get the length of the long_name attribute.

long_name
     Pointer to char array which, if not NULL, will get the long_name string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

standard_name_lenp
     Pointer to size_t which, if not NULL, will get the length of the standard_name attribute.

standard_name
     Pointer to char array which, if not NULL, will get the standard_name string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

ncoord_vars
     Pointer to an integer, which, if non-NULL, will get the number of coordinate variables identified in the ``coordinates'' attribute.

coord_varids
     Pointer to an array of integer, which, if non-NULL, will be filled with the variable IDs of the variables listed int he ``coordinates'' attribute.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Define missing data values for a variable with nccf_def_var_missing
===================================================================

nccf_def_notes

This function sets the ``fill_value'', ``valid_min'', and ``valid_max'' attributes.

Usage
=====

     int nccf_def_var_missing(int ncid, int varid, const void *fill_valuep,
                                 const void *valid_minp, const void *valid_maxp);

ncid
     The ncid of the file.

varid
     The varid of the netCDF variable being described.

fill_valuep
     If non-NULL, this will point to a value of the same type as this varid, which will be used as the fill_value for the data.

valid_minp
     If non-NULL, this will point to a value of the same type as this varid, which will be written as the ``valid_min'' attribute. If this parameter is non-NULL, valid_max must also be provided.

valid_maxp
     If non-NULL, this will point to a value of the same type as this varid, which will be written as the ``valid_max'' attribute. If this parameter is non-NULL, valid_min must also be provided.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Learn about missing data settings with nccf_inq_var_missing
===========================================================

Get attributes which define missing data information. If the attributes are not there, then provide the valid data anyway, based on netCDF defaults.

Usage
=====

     int nccf_inq_var_missing(int ncid, int varid, void *fill_valuep,
                                 void *valid_minp, void *valid_maxp);

ncid
     The ncid of the file.

varid
     The varid of the netCDF variable.

fill_valuep
     If this is not NULL, the fill value of the variable will be written at this address by nccf_inq_var_missing. If the fill value was not defined for the variable, the netCDF default value will be used.

valid_minp
     If this is not NULL, the valid_min value of the variable will be written at this address by nccf_inq_var_missing. If the valid_min was not defined for the variable, the netCDF default value will be used.

valid_maxp
     If this is not NULL, the valid_max value of the variable will be written at this address by nccf_inq_var_missing. If the valid_max value was not defined for the variable, the netCDF default value will be used.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Add CF-Recommended Metadata to a File or Variable with
======================================================

nccf_def_notes

This functions writes up to four text attributes for either a variable, or an entire file. These text attributes, ``institution,'' ``source,'' ``comment,'' and ``references'' are recommended by the CF Metadata Convention.

Usage
=====

     int nccf_def_notes(int ncid, int varid, char *units, char *long_name,
                        char *standard_name, char *institution,
                        char *source, char *comment, char *references);

ncid
     The ncid of the file.

varid
     The varid of the netCDF variable being described. Use NC_GLOBAL if you wish these attributes to apply to the entire file.

institution
     If non-NULL, this text string will be written as the CF-recommended ``institution'' attribute.

source
     If non-NULL, this text string will be written as the CF-recommended ``source'' attribute.

comment
     If non-NULL, this text string will be written as the CF-recommended ``comment'' attribute.

references
     If non-NULL, this text string will be written as the CF-recommended ``references'' attribute.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Read variable description with nccf_inq_notes
=============================================

Read any existing CF recommended text attributes from a variable.

Usage
=====

     int nccf_inq_notes(int ncid, int varid,
                        size_t *institution_lenp, char *institution,
                        size_t *source_lenp, char *source,
                        size_t *comment_lenp, char *comment,
                        size_t *references_lenp, char *references);

ncid
     The ncid of the file.

varid
     The varid of the netCDF variable.

institution_lenp
     Pointer to size_t which, if not NULL, will get the length of the institution attribute.

institution
     Pointer to char array which, if not NULL, will get the institution string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

source_lenp
     Pointer to size_t which, if not NULL, will get the length of the source attribute.

source
     Pointer to char array which, if not NULL, will get the source string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

comment_lenp
     Pointer to size_t which, if not NULL, will get the length of the comment attribute.

comment
     Pointer to char array which, if not NULL, will get the comment string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

references_lenp
     Pointer to size_t which, if not NULL, will get the length of the references attribute.

references
     Pointer to char array which, if not NULL, will get the references string. Memory must be allocated before this function is called. Call this function with a NULL for this parameter to get the size first.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Define a coordinate variable and dimension for latitude with nccf_def_latitude
==============================================================================

Define a coordinate variable and dimension with all the CF recommended attribute accessories for latitude.

Usage
=====

     int nccf_def_latitude(int ncid, size_t len, nc_type xtype,
                              const char *formula_terms, int *lat_dimidp,
                              int *lat_varidp);

ncid
     The ncid of the file.

len
     The length of this coordinate dimension.

xtype
     The type of this coordinate variable.

formula_terms
     If non-NULL, a string which will be written as the ``formula_terms'' attribute on the coordinate variable.

lat_dimidp
     If non-NULL, nccf_def_latitude will write the dimension ID of the netCDF dimension for the latitude here.

lat_varidp
     If non-NULL, nccf_def_latitude will write the variable ID of the netCDF coordinate variable for the latitude here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Learn about a latitude coordinate variable and dimension with
=============================================================

nccf_inq_latitude

Inquire about a latitude dimension and coordinate variable.

Usage
=====

     int nccf_inq_latitude(int ncid, size_t *lenp, nc_type *xtypep,
                              size_t *ft_lenp, char *formula_terms,
                              int *lat_dimidp, int *lat_varidp);

ncid
     The ncid of the file.

lenp
     If non-NULL, the length of the latitude dimension will be written here by nccf_inq_latitude.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

ft_lenp
     If non-NULL, the length of the value of the ``formula_terms'' attribute will be written here by ft_lenp. If there is no ``formula_terms'' attribute, zero will be written.

lat_dimidp
     If non-NULL, the dimid of the latitude dimension will be written here.

lat_varidp
     If non-NULL, the varid of the latitude coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define a coordinate variable and dimension for longitude with nccf_def_longitude
================================================================================

Define a coordinate variable and dimension with all the CF recommended attribute accessories for longitude.

Usage
=====

     int nccf_def_longitude(int ncid, size_t len, nc_type xtype,
                              const char *formula_terms, int *lon_dimidp,
                              int *lon_varidp);

ncid
     The ncid of the file.

len
     The length of this coordinate dimension.

xtype
     The type of this coordinate variable.

formula_terms
     If non-NULL, a string which will be written as the ``formula_terms'' attribute on the coordinate variable.

lon_dimidp
     If non-NULL, nccf_def_longitude will write the dimension ID of the netCDF dimension for the longitude here.

lon_varidp
     If non-NULL, nccf_def_longitude will write the variable ID of the netCDF coordinate variable for the longitude here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Learn about a longitude coordinate variable and dimension with
==============================================================

nccf_inq_longitude

Inquire about a longitude dimension and coordinate variable.

Usage
=====

     int nccf_inq_longitude(int ncid, size_t *lenp, nc_type *xtypep,
                              size_t *ft_lenp, char *formula_terms,
                              int *lon_dimidp, int *lon_varidp);

ncid
     The ncid of the file.

lenp
     If non-NULL, the length of the longitude dimension will be written here by nccf_inq_longitude.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

ft_lenp
     If non-NULL, the length of the value of the ``formula_terms'' attribute will be written here by ft_lenp. If there is no ``formula_terms'' attribute, zero will be written.

lon_dimidp
     If non-NULL, the dimid of the longitude dimension will be written here.

lon_varidp
     If non-NULL, the varid of the longitude coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define a coordinate variable and dimension for level with nccf_def_lvl
======================================================================

Define a coordinate variable and dimension with all the CF recommended attribute accessories for a vertical level.

Usage
=====

     int nccf_def_lvl(int ncid, const char *name, size_t len, nc_type xtype,
                      const char *units, int positive_up, const char *standard_name,
                      const char *long_name, const char *formula_terms,
                      int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

name
     The name of the coordinate dimension and variable.

len
     The length of this coordinate dimension and variable.

xtype
     The type of this coordinate variable.

units
     If non-NULL, a string which will be written as the ``units'' attribute on the coordinate variable.

positive_up
     Set to 0 and the attribute ``positive'' to ``down''. Set to any other value to get ``up''.

standard_name
     If non-NULL, a string which will be written as the ``standard_name'' attribute on the coordinate variable.

long_name
     If non-NULL, a string which will be written as the ``long_name'' attribute on the coordinate variable.

lon_dimidp
     If non-NULL, nccf_def_lvl will write the dimension ID of the netCDF dimension for the level here.

lon_varidp
     If non-NULL, nccf_def_lvl will write the variable ID of the netCDF coordinate variable for the level here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Learn about a level coordinate variable and dimension with
==========================================================

nccf_inq_lvl

Inquire about a level dimension and coordinate variable.

Usage
=====

     int nccf_inq_lvl(int ncid, char *name, size_t *lenp, nc_type *xtypep,
                      size_t *ft_lenp, char *formula_terms, int *positive_upp,
                      int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, the name of this vertical level dimension (and variable) will be written here.

lenp
     If non-NULL, the length of the level dimension will be written here by nccf_inq_lvl.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

ft_lenp
     If non-NULL, the length of the value of the ``formula_terms'' attribute will be written here by ft_lenp. If there is no ``formula_terms'' attribute, zero will be written.

positive_upp
     If non-NULL, a one will be written here if the ``positive'' attribute of this coordinate variable is ``up'', a zero will be written if it is ``down''.

lvl_dimidp
     If non-NULL, the dimid of the level dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the level coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define a coordinate variable and dimension for level with nccf_def_lvl
======================================================================

Define a unitless vertical coordinate variable and dimension from Apendix D of the CF Convention, with all the CF recommended attribute accessories for a vertical level.

Usage
=====

     int nccf_def_lvl_vert(int ncid, int lvl_type, const char *name, nc_type xtype,
                           size_t len, int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

lvl_type
     One of: CF_VERT_ATM_LN, CF_VERT_SIGMA, CF_VERT_HYBRID_SIGMA, CF_VERT_HYBRID_HEIGHT, CF_VERT_SLEVE, CF_VERT_OCEAN_SIGMA, CF_VERT_OCEAN_S, CF_VERT_OCEAN_SIGMA_Z, CF_VERT_OCEAN_DBL_SIGMA.

name
     The name of the coordinate dimension and variable.

xtype
     The type of this coordinate variable.

len
     The length of this coordinate dimension and variable.

lvl_dimidp
     If non-NULL, the function will write the dimension ID of the netCDF dimension for the level here.

llvl_varidp
     If non-NULL, the function will write the variable ID of the netCDF coordinate variable for the level here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Learn about a level coordinate variable and dimension with
==========================================================

nccf_inq_lvl

Inquire about a level dimension and coordinate variable.

Usage
=====

     int nccf_inq_lvl_vert(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                           int *lvl_typep, int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, the name of this vertical level dimension (and variable) will be written here.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the level dimension will be written here.

lvl_typep
     If non-NULL, the type of vertical dimension will be written here, one of CF_VERT_ATM_LN, CF_VERT_SIGMA, CF_VERT_HYBRID_SIGMA, CF_VERT_HYBRID_HEIGHT, CF_VERT_SLEVE, CF_VERT_OCEAN_SIGMA, CF_VERT_OCEAN_S, CF_VERT_OCEAN_SIGMA_Z, CF_VERT_OCEAN_DBL_SIGMA.

lvl_dimidp
     If non-NULL, the dimid of the level dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the level coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define a coordinate variable and dimension for time with nccf_def_time
======================================================================

Define a coordinate variable and dimension with all the CF recommended attribute accessories for time.

Usage
=====

     int nccf_def_time(int ncid, const char *name, size_t len, nc_type xtype,
                          const char *units, const char *standard_name, const char *long_name,
                          const char *formula_terms, int *time_dimidp, int *time_varidp);

ncid
     The ncid of the file.

len
     The length of this coordinate dimension.

xtype
     The type of this coordinate variable.

formula_terms
     If non-NULL, a string which will be written as the ``formula_terms'' attribute on the coordinate variable.

lon_dimidp
     If non-NULL, nccf_def_time will write the dimension ID of the netCDF dimension for the time here.

lon_varidp
     If non-NULL, nccf_def_time will write the variable ID of the netCDF coordinate variable for the time here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Learn about a time coordinate variable and dimension with
=========================================================

nccf_inq_time

Inquire about a time dimension and coordinate variable.

Usage
=====

     int nccf_inq_time(int ncid, size_t *lenp, nc_type *xtypep, size_t *ft_lenp,
                          char *formula_terms, int *time_dimidp, int *time_varidp);

ncid
     The ncid of the file.

lenp
     If non-NULL, the length of the time dimension will be written here by nccf_inq_time.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

ft_lenp
     If non-NULL, the length of the value of the ``formula_terms'' attribute will be written here by ft_lenp. If there is no ``formula_terms'' attribute, zero will be written.

formula_terms
     If non-NULL the value of the ``formula_terms'' attribute, if any, will be copied here.

time_dimidp
     If non-NULL, the dimid of the time dimension will be written here.

time_varidp
     If non-NULL, the varid of the time coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define atmosphere sigma coordinate.
===================================

Define formula terms attribute for atmosphere sigma coordinate variable.

Usage
=====

     int nccf_def_ft_sigma(int ncid, int varid, int ps_varid, int ptop_varid);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

ps_varid
     The variable ID of the ps variable.

ptop_varid
     The variable ID of the ptop variable.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire about atmosphere sigma coordinate.
==========================================

nccf_inq_time

Inquire about atmosphere sigma coordinate.

Usage
=====

     int nccf_inq_lvl_sigma(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                            int *ps_varidp, int *ptop_varidp, int *lvl_dimidp,
                            int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

ps_varidp
     If non-NULL, the variable ID of the ps variable will be written here.

ptop_varidp
     If non-NULL, the variable ID of the ptop variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define atmosphere sigma coordinate.
===================================

Define formula terms attribute for atmosphere hybrid sigma coordinate variable.

Usage
=====

     int nccf_def_ft_hybrid_sigma(int ncid, int varid, int a_varid, int b_varid,
                                  int ps_varid, int p0_varid);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

a_varid
     The variable ID of the a variable.

b_varid
     The variable ID of the b variable.

ps_varid
     The variable ID of the ps variable.

ptop_varid
     The variable ID of the ptop variable.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire about atmosphere sigma coordinate.
==========================================

Inquire about atmosphere hybrid sigma coordinate.

Usage
=====

     int nccf_inq_lvl_hybrid_sigma(int ncid, char *name, nc_type *xtypep,
                                   size_t *lenp, int *a_varidp, int *b_varidp,
                                   int *ps_varidp, int *p0_varidp, int *lvl_dimidp,
                                   int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

a_varidp
     If non-NULL, the variable ID of the a variable will be written here.

b_varidp
     If non-NULL, the variable ID of the b variable will be written here.

ps_varidp
     If non-NULL, the variable ID of the ps variable will be written here.

ptop_varidp
     If non-NULL, the variable ID of the ptop variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

The formula_terms attribute for atmosphere hybrid height
========================================================

Define formula terms attribute for atmosphere hybrid height coordinate variable

Usage
=====

     int nccf_def_ft_hybrid_height(int ncid, int varid, int a_varid, int b_varid,
                                   int orog_varid);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

a_varid
     The variable ID of the a variable.

b_varid
     The variable ID of the b variable.

orog_varid
     The variable ID of the orog variable.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire about hybrid height coordinate.
=======================================

Inquire about the hybrid height coordinate.

Usage
=====

     int nccf_inq_lvl_hybrid_height(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                                    int *a_varidp, int *b_varidp, int *orog_varidp,
                                    int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

a_varidp
     If non-NULL, the variable ID of the a variable will be written here.

b_varidp
     If non-NULL, the variable ID of the b variable will be written here.

orog_varidp
     If non-NULL, the variable ID of the orog variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define atmosphere sleve coordinate.
===================================

Define formula terms attribute for the atmosphere sleve coordinate variable.

Usage
=====

     int nccf_def_ft_sleve(int ncid, int varid, int a_varid, int b1_varid,
                           int b2_varid, int ztop_varid, int zsurf1_varid,
                           int zsurf2_varid);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

a_varid
     The variable ID of the a variable.

b1_varid
     The variable ID of the b1 variable.

b2_varid
     The variable ID of the b2 variable.

ztop_varid
     The variable ID of the ztop variable.

zsurf1_varid
     The variable ID of the zsurf1 variable.

zsurf2_varid
     The variable ID of the zsurf2 variable.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire About Sleve Coordinate.
===============================

Inquire about the sleve coordinate.

Usage
=====

     int nccf_inq_lvl_sleve(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                            int *a_varidp, int *b1_varidp, int *b2_varidp, int *ztop_varidp,
                            int *zsurf1_varidp, int *zsurf2_varidp, int *lvl_dimidp,
                            int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

a_varidp
     If non-NULL, the variable ID of the a variable will be written here.

b1_varidp
     If non-NULL, the variable ID of the b1 variable will be written here.

b2_varidp
     If non-NULL, the variable ID of the b2 variable will be written here.

ztop_varidp
     If non-NULL, the variable ID of the ztop variable will be written here.

zsurf1_varidp
     If non-NULL, the variable ID of the zsurf1 variable will be written here.

zsurf2_varidp
     If non-NULL, the variable ID of the zsurf2 variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define Ocean Sigma Coordinate.
==============================

Define the formula terms attribute for the ocean sigma coordinate variable.

Usage
=====

     int nccf_def_ft_ocean_sigma(int ncid, int varid, int eta_varid, int depth_varid);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

eta_varid
     The variable ID of the eta variable.

depth_varid
     The variable ID of the depth variable.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire About Ocean Sigma Coordinate.
=====================================

Inquire about the ocean sigma coordinate.

Usage
=====

     int nccf_inq_lvl_ocean_sigma(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                                  int *eta_varidp, int *depth_varidp, int *lvl_dimidp,
                                  int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

eta_varidp
     If non-NULL, the variable ID of the eta variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define Ocean S Coordinate.
==========================

Define ocean s coordinate.

Usage
=====

     int nccf_def_ft_ocean_s(int ncid, const char *name, nc_type xtype, size_t len,
                              int eta_varid, int depth_varid, int a_varid, int b_varid,
                              int depth_c_varid, int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

xtype
     The type of this coordinate variable.

len
     The length of this coordinate dimension.

eta_varid
     The variable ID of the eta variable.

depth_varid
     The variable ID of the depth variable.

a_varid
     The variable ID of the a variable.

b_varid
     The variable ID of the b variable.

depth_c_varid
     The variable ID of the depth_c variable.

lvl_dimidp
     If non-NULL, the dimension ID of the netCDF coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the variable ID of the netCDF coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire About Ocean S Coordinate.
=================================

nccf_inq_time

Inquire about the ocean s coordinate.

Usage
=====

     int nccf_inq_lvl_ocean_s(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                              int *eta_varidp, int *depth_varidp, int *a_varidp, int *b_varidp,
                              int *depth_c_varidp, int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

eta_varidp
     If non-NULL, the variable ID of the eta variable will be written here.

depth_varidp
     If non-NULL, the variable ID of the depth variable will be written here.

a_varidp
     If non-NULL, the variable ID of the a variable will be written here.

b_varidp
     If non-NULL, the variable ID of the b variable will be written here.

depth_c_varidp
     If non-NULL, the variable ID of the depth_c variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define Ocean Sigma Z Coordinate.
================================

Define ocean sigma z coordinate.

Usage
=====

     int nccf_def_ft_ocean_sigma_z(int ncid, const char *name, nc_type xtype,
                                    size_t len, int eta_varid, int depth_varid,
                                    int depth_c_varid, int nsigma_varid,
                                    int zlev_varid, int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

xtype
     The type of this coordinate variable.

len
     The length of this coordinate dimension.

eta_varid
     The variable ID of the eta variable.

depth_varid
     The variable ID of the depth variable.

depth_c_varid
     The variable ID of the depth_c variable.

nsigma_varid
     The variable ID of the nsigma variable.

zlev_varid
     The variable ID of the zlev variable.

lvl_dimidp
     If non-NULL, the dimension ID of the netCDF coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the variable ID of the netCDF coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire About Ocean Sigma Z Coordinate.
=======================================

Inquire about the ocean sigma z coordinate.

Usage
=====

     int nccf_inq_lvl_ocean_sigma_z(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                                    int *eta_varidp, int *depth_varidp, int *depth_c_varidp,
                                    int *nsigma_varidp, int *zlev_varidp, int *lvl_dimidp,
                                    int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

eta_varidp
     If non-NULL, the variable ID of the eta variable will be written here.

depth_varidp
     If non-NULL, the variable ID of the depth variable will be written here.

depth_c_varidp
     If non-NULL, the variable ID of the depth_c variable will be written here.

nsigma_varidp
     If non-NULL, the variable ID of the nsigma variable will be written here.

zlev_varidp
     If non-NULL, the variable ID of the zlev variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Define Ocean Double Sigma Coordinate.
=====================================

Define ocean double sigma coordinate.

Usage
=====

     int nccf_def_ft_ocean_dbl_sigma(int ncid, const char *name, nc_type xtype, size_t len,
                                      int depth_varid, int z1_varid, int z2_varid, int a_varid,
                                      int href_varid, int k_c_varid, int *lvl_dimidp,
                                      int *lvl_varidp);

ncid
     The ncid of the file.

varid
     The varid of the vertical coordinate variable.

xtype
     The type of this coordinate variable.

len
     The length of this coordinate dimension.

depth_varid
     The variable ID of the depth variable.

z1_varid
     The variable ID of the z1 variable.

z2_varid
     The variable ID of the z2 variable.

a_varid
     The variable ID of the a variable.

href_varid
     The variable ID of the href variable.

k_c_varid
     The variable ID of the k_c variable.

lvl_dimidp
     If non-NULL, the dimension ID of the netCDF coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the variable ID of the netCDF coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Inquire About Ocean Double Sigma Coordinate.
============================================

Inquire about the ocean double sigma coordinate.

Usage
=====

     int nccf_inq_lvl_ocean_dbl_sigma(int ncid, char *name, nc_type *xtypep, size_t *lenp,
                                      int *depth_varidp, int *z1_varidp, int *z2_varidp,
                                      int *a_varidp, int *href_varidp, int *k_c_varidp,
                                      int *lvl_dimidp, int *lvl_varidp);

ncid
     The ncid of the file.

name
     If non-NULL, this pointer gets the name of the coordinate variable and dimension.

xtypep
     If non-NULL, the type of the coordinate variable will be written here.

lenp
     If non-NULL, the length of the coordinate dimension will be written here.

depth_varidp
     If non-NULL, the variable ID of the depth variable will be written here.

z1_varidp
     If non-NULL, the variable ID of the z1 variable will be written here.

z2_varidp
     If non-NULL, the variable ID of the z2 variable will be written here.

a_varidp
     If non-NULL, the variable ID of the a variable will be written here.

href_varidp
     If non-NULL, the variable ID of the href variable will be written here.

k_c_varidp
     If non-NULL, the variable ID of the k_c variable will be written here.

lvl_dimidp
     If non-NULL, the dimid of the coordinate dimension will be written here.

lvl_varidp
     If non-NULL, the varid of the coordinate variable will be written here.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Get a geographic subset of the data.
====================================

Get a geographic subset of the data.

Usage
=====

        int nccf_get_vara(int ncid, int varid, float *lat_bounds, int *nlat, float *lon_bounds,
     		     int *nlon, int *lvl_index, int *nlvl, int rec, void *data);

ncid
     The ncid of the file.

varid
     The varid of the data variable from which the subset will be taken.

lat_bounds
     A length two array, this holds the latitude start and stop values for the range of interest.

nlat
     A pointer to an integer which will get the number of latitude values which fall within the range.

lon_bounds
     A length two array, this holds the longitude start and stop values for the range of interest. (Wrapping around the dateline is not allowed!)

nlon
     A pointer to an integer which will get the number of longitude values which fall within the range.

lvl_index
     A zero-based index number for the verticle level of interest to the subsetter. (Ignored if data has no vertical axis).

timestep
     A zero-based index number for the timestep of interest to the subsetter. (Ignored if data has no time axis).

data
     A pointer to which the data subset will be written. Memory must be allocated (and deallocated) by the user.

Return Codes
============

This function returns zero for success, or an error code for failure.

Example
=======

Coordinate Systems
******************

Label the axis type of a coordinate var with nccf_def_axis_type
===============================================================

Usage
=====

     int
     nccf_def_axis_type(int ncid, int varid, int axis_type);

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Find out the axis type of a coordinate var with nccf_inq_axis_type
==================================================================

Usage
=====

     int
     nccf_inq_axis_type(int ncid, int varid, int *axis_type);

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Define a coordinate system with nccf_def_coord_system
=====================================================

Usage
=====

     int
     nccf_def_coord_system(int ncid, const char *name, int naxes, int *axis_varids,
                         int *system_varid);

Define a coordinate system consisting of naxes axes, each axis represented by a coordinate varid in the axis_varids array. This create a new (scalar, NC_CHAR) var, whose varid is returned in system_varid.

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Find out about a coordinate system with nccf_inq_coord_system
=============================================================

Usage
=====

     int
     nccf_inq_coord_system(int ncid, int system_varid, char *name,
                         int *naxes, int *axis_varids);

Find out about a coordinate system, it's name, number of axes, and the varid of each axis coordinate var.

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Assign a coordinate system to a var with nccf_assign_coord_system
=================================================================

Usage
=====

     int
     nccf_assign_coord_system(int ncid, int varid, int system_varid);

Assign a coordinate system to a var. This adds an attribute to the var.

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Define a coordinate transform with nccf_def_transform
=====================================================

Usage
=====

     int
     nccf_def_transform(int ncid, const char *name, const char *transform_type,
                      const char *transform_name, int *transform_varid);

Define a coordinate transform. This adds a (scalar, NC_CHAR) var, which contains some attributes. The varid of this new variable is returned in transform_varid.

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Find out about a coordinate transform with nccf_inq_transform
=============================================================

Usage
=====

     int
     nccf_inq_transform(int ncid, int transform_varid, char *name, size_t *type_len,
                      char *transform_type, size_t *name_len, char *transform_name);

Find out about a coordinate transform, it's name, and the contents of the transform_type and transform_name attributes. Pass NULL for any that you're not interested in. Pass NULL for transform_type and transform_name to get their lengths with type_len and name_len.

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======

Assign a coordinate transform to a coordinate system with nccf_assign_transform
===============================================================================

Usage
=====

     int
     nccf_assign_transform(int ncid, int system_varid, int transform_varid);

Assign a coordinate transform to a coordinate system. This adds an attribute to the variable that holds the coordinate system attributes.

ncid
     The ncid of the file.

Return Codes
============

This function returns zero for success, or a netCDF error code for failure.

Example
=======