NAME

       gd_mstrings — retrieve a list of string values from a dirfile

SYNOPSIS

       #include <getdata.h>

       const char **gd_mstrings(DIRFILE *dirfile, const char *parent);

DESCRIPTION

       The  gd_mstrings() function queries a dirfile(5) database specified by dirfile and returns
       a read-only list of values of the all STRING  type  metafields  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 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, although it is guaranteed to be in the same order as  the  list  of  STRING  fields
       returned  by  gd_mfield_list_by_type(3).   The array is terminated by a NULL pointer.  The
       number of strings 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_mstrings() is called again with the same arguments, or until the array is  de-allocated
       by a call to gd_close(3).

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

RETURN VALUE

       Upon successful completion, gd_mstrings()  returns  a  pointer  to  an  array  of  strings
       containing  the  values  of all the STRING metafields for the specified parent field.  The
       array is terminated by a NULL pointer.  If no strings are defined in the database for  the
       specified  parent,  an array consisting of only the NULL pointer is returned.  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_open(3),   gd_error(3),   gd_error_string(3),   gd_mfield_list_by_type(3),
       gd_nmfields_by_type(3), gd_strings(3)