NAME

       gd_strings — retrieve a list of string values from a Dirfile

SYNOPSIS

       #include <getdata.h>

       const char **gd_strings(DIRFILE *dirfile);

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

DESCRIPTION

       The  gd_strings() function queries a dirfile(5) database specified by dirfile and compiles
       a read-only list of values of  the  all  STRING  type  fields  defined  in  the  database,
       excluding /META subfields.

       The  gd_mstrings()  function  produces the same list, but for STRING meta subfields of the
       indicated parent field.

       The dirfile argument must point to a valid DIRFILE object previously created by a call  to
       gd_open(3).

RETURN VALUE

       Upon  successful  completion,  gd_strings()  returns  a  pointer  to  an  array of strings
       containing the  values  of  all  the  STRING  fields  defined  in  the  dirfile  database.
       Similarly, gd_mstrings() returns a pointer to an array of strings containing the values of
       all the STRING metafields under parent.

       The returned array is terminated by a NULL pointer.  A valid pointer is always returned if
       this  function  does  not  encounter an error.  If there are no string values to return, a
       pointer to an array consisting of only the NULL pointer is returned.

       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_field_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_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_strings() or gd_mstrings() is called again with the same arguments, or until the  array
       is de-allocated by a call to gd_close(3) or gd_discard(3).

       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
               (gd_mstrings()  only) The supplied parent field code was not found, or referred to
               a metafield itself.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

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

HISTORY

       The get_strings() function appeared in GetData-0.3.0.

       The get_mstrings() function appeared in GetData-0.4.0.

       In GetData-0.7.0, these functions were renamed to gd_strings() and gd_mstrings().

SEE ALSO

       gd_error(3),      gd_error_string(3),      gd_field_list_by_type(3),       gd_mstrings(3),
       gd_nfields_by_type(3), gd_open(3), gd_string(3), dirfile(5)