Provided by: libgetdata-doc_0.9.0-2.2_all bug

NAME
       gd_strings — retrieve a list of string values from a dirfile


SYNOPSIS
       #include <getdata.h>

       const char **gd_strings(DIRFILE *dirfile);


DESCRIPTION
       The gd_strings() function queries a dirfile(5) database specified by dirfile and returns a
       read-only list of values of the all STRING type fields 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 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() 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_field_list_by_type(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.  The array
       is terminated by a NULL pointer.  If no strings are defined  in  the  database,  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_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_field_list_by_type(3),
       gd_mstrings(3), gd_nfields_by_type(3), gd_string(3)