NAME

       gd_field_list_by_type — retrieve a list of fields in a dirfile

SYNOPSIS

       #include <getdata.h>

       const char **gd_field_list_by_type(DIRFILE *dirfile, gd_entype_t type);

DESCRIPTION

       The  gd_field_list_by_type()  function  queries a dirfile(5) database specified by dirfile
       and returns a read-only list of names of the all fields of the indicated  type  which  are
       defined in the database.  Notably, this list does not include /META subfields.

       The  dirfile argument must point to a valid DIRFILE object previously created by a call to
       gd_open(3).  The type argument should be one  of  the  following  symbols  indicating  the
       desired field type:

              GD_BIT_ENTRY, GD_CARRAY_ENTRY, GD_CONST_ENTRY, GD_DIVIDE_ENTRY, GD_INDEX_ENTRY,
              GD_LINCOM_ENTRY, GD_LINTERP_ENTRY, GD_MULTIPLY_ENTRY, GD_PHASE_ENTRY,
              GD_POLYNOM_ENTRY, GD_RAW_ENTRY, GD_RECIP_ENTRY, GD_SBIT_ENTRY, GD_STRING_ENTRY.

       The  array  returned  will  be de-allocated by a call to gd_close(3) and should not be de-
       allocated by the caller.  The list returned should not be assumed to be in any  particular
       order.   The array is terminated by a NULL pointer.  The number of fields in the array can
       be obtained from a call to gd_nfields_by_type(3).

       The caller may not modify any strings in the array, or the array  itself.   Doing  so  may
       cause  database  corruption.   The  pointer  returned  is  guaranteed  to  be  valid until
       gd_field_list_by_type() is called again on the same DIRFILE  object  with  the  same  type
       argument, or until the array is de-allocated by a call to gd_close(3).

       For  CONST,  CARRAY,  and  STRING  field  types,  corresponding lists of values for may be
       obtained by calling gd_constants(3), gd_carrays(3), or gd_strings(3).

RETURN VALUE

       Upon successful completion, gd_field_list_by_type() returns  a  pointer  to  an  array  of
       strings  containing  the  names  of  all the fields defined in the dirfile database of the
       specific type.  On error it returns NULL and sets the dirfile error to  a  non-zero  error
       value.  Possible error values are:

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       The dirfile error may be retrieved by calling gd_error(3).  A descriptive error string for
       the last error encountered can be obtained from a call to gd_error_string(3).

SEE ALSO

       dirfile(5),     gd_open(3),     gd_constants(3),     gd_error(3),      gd_error_string(3),
       gd_field_list(3), gd_mfield_list_by_type(3), gd_nfields_by_type(3), gd_strings(3)