NAME

       gd_mfield_list_by_type — retrieve a list of fields in a dirfile

SYNOPSIS

       #include <getdata.h>

       const char **gd_mfield_list_by_type(DIRFILE *dirfile, const char *parent, gd_entype_t
              type);

DESCRIPTION

       The gd_mfield_list_by_type() function queries a dirfile(5) database specified  by  dirfile
       and  returns a read-only list of names of the all metafields of the indicated type for the
       supplied parent field.

       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_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_nmfields_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_mfield_list_by_type()  is  called  again with the same arguments, 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_mconstants(3) or gd_mstrings(3).

RETURN VALUE

       Upon  successful  completion,  gd_mfield_list_by_type()  returns  a pointer to an array of
       strings containing the names of all the metafields of the  specific  type  for  the  given
       parent.   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_CODE
               The supplied parent field code was not found, or referred to a metafield itself.

       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_error(3),  gd_error_string(3), gd_field_list_by_type(3), gd_mconstants(3),
       gd_mfield_list(3), gd_mstrings(3), gd_nmfields_by_type(3), gd_open(3)