NAME

       gd_constants, gd_mconstants — retrieve a list of constant values from a Dirfile

SYNOPSIS

       #include <getdata.h>

       const void *gd_constants(DIRFILE *dirfile, gd_type_t return_type);

       const void *gd_mconstants(DIRFILE *dirfile, const char *parent, gd_type_t return_type);

DESCRIPTION

       The  gd_constants()  function  queries  a  dirfile(5)  database  specified  by dirfile and
       compiles a list of values of the all CONST fields defined in the database, excluding  meta
       subfields.   The  values returned are converted to the data type specified by return_type.
       The return_type should be one of the following symbols:

              GD_UINT8, GD_INT8, GD_UINT16, GD_INT16, GD_UINT32, GD_INT32,
              GD_UINT64, GD_INT64, GD_FLOAT32, GD_FLOAT64, GD_COMPLEX64, GD_COMPLEX128.

       See  gd_get_constant(3) for the meaning of these symbols.  The dirfile argument must point
       to a valid DIRFILE object previously created by a call to gd_open(3).

       The gd_mconstants() function returns the same list for CONST meta subfields of the  parent
       field specified by parent.

       A   corresponding   list   of   names   for  these  fields  may  be  obtained  by  calling
       gd_field_list_by_type(3) or gd_mfield_list_by_type(3).

RETURN VALUE

       Upon successful completion, gd_constants() returns a pointer to an  array  containing  the
       values  of  all the constants defined in the dirfile database.  Similarly, gd_mconstants()
       returns a pointer to an array containing the values of the all the meta subfield constants
       of the specified parent field.

       The  list  returned  should  not  be assumed to be in any particular order, although it is
       guaranteed  to  be  in  the  same  order  as  the  list  of  CONST  fields   returned   by
       gd_field_list_by_type(3)  or  gd_mfield_list_by_type(3).   The array is unterminated.  The
       number of values in the array can be obtained from  a  call  to  gd_nfields_by_type(3)  or
       gd_nmfields_by_type(3), as appropriate.

       Memory  for the returned array is managed by GetData and should not be de-allocated by the
       caller.  The caller may not modify any values in the array.  Doing so may  cause  database
       corruption.   The  pointer  returned  is guaranteed to be valid only until the function is
       called again, with the exception that,  since  each  top-level  field  maintains  its  own
       arrays,  calling  gd_mconstants()  for  a one parent field does not invalidate the pointer
       returned for a any other parent.

       Modifying the dirfile's metadata invalidates any pointer returned by these functions.  And
       no  pointers  remain  valid  after the dirfile is de-allocated by a call to gd_close(3) or
       gd_discard(3).  Once a pointer is invalidated, the caller should not dereference it.

       If no constants of the appropriate class are defined in the database,  NULL  is  returned.
       This is not considered an error.

       On  error,  these  functions  return  NULL  and  store a negative-valued error code in the
       DIRFILE object which may be retrieved by a subsequent call to gd_error(3).  Possible error
       codes are:

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The  specified  parent  field  code  was  not  found,  or  referred to a metafield
               (gd_mconstants() only).

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_TYPE
               The return_type specified was not one of the symbols listed above.

       GD_E_INTERNAL_ERROR
               An internal error occurred in the library while trying to perform the task.   This
               indicates  a  bug  in  the  library.   Please  report  the incident to the GetData
               developers.

       A descriptive error string for the error may be obtained by calling gd_error_string(3).

HISTORY

       The functions get_constants() and get_mconstants() appeared in GetData-0.4.0.

       In GetData-0.7.0, these functions were renamed to gd_constants() and gd_mconstants().

SEE ALSO

       gd_error(3),     gd_error_string(3),     gd_field_list_by_type(3),     gd_get_constant(3),
       gd_mfield_list_by_type(3),   gd_nfields_by_type(3),   gd_nmfields_by_type(3),  gd_open(3),
       dirfile(5)