NAME

       gd_get_sarray,  gd_get_sarray_slice  —  retrieve  STRING  or  SARRAY  data  from a dirfile
       database

SYNOPSIS

       #include <getdata.h>

       int gd_get_sarray_slice(DIRFILE *dirfile, const char *field_code, unsigned int start,
              size_t len, const char **data_out);

       int gd_get_sarray(DIRFILE *dirfile, const char *field_code, const char **data_out);

DESCRIPTION

       The  gd_get_sarray_slice() function queries a dirfile(5) database specified by dirfile for
       the STRING or SARRAY scalar field_code.  Pointers to  read-only  string  elements  of  the
       specified  field  are  stored  in  the  user-supplied data_out buffer, which must be large
       enough to hold len pointers.  The first element of the field stored is given by start, and
       the number of elements stored is given by len.

       The  gd_get_sarray() function behaves similarly, except it returns the entire field, as if
       gd_get_sarray_slice() were called with start equal to zero and  len  equal  to  the  value
       returned by gd_array_len(3).

       The  dirfile argument must point to a valid DIRFILE object previously created by a call to
       gd_open(3).  The number of elements returned by gd_get_sarray() may be obtained by calling
       gd_array_len(3).   Unlike  gd_getdata(3), calling gd_get_sarray_slice() never results in a
       short read; attempting to read past the end of the field will result in an error,  and  no
       data will be returned.

       If  field_code  refers  to a STRING field, it is treated as if it were a SARRAY field with
       only one element.  See the gd_get_string(3) manual page for an example of how  to  replace
       gd_get_string(3) calls with gd_get_sarray().

RETURN VALUE

       On  success,  gd_get_sarray()  and  gd_get_sarray_slice(),  return  zero.  Storage for the
       strings returned by this function are managed by GetData and should not be deallocated  by
       the  caller.   On  error,  these  functions return a negative-valued error code.  Possible
       error codes are:

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The field specified by field_code was not found in the database.

       GD_E_BAD_DIRFILE
               An invalid dirfile was supplied.

       GD_E_BAD_FIELD_TYPE
               The supplied field_code was not a STRING nor SARRAY.

       GD_E_BOUNDS
               A request for data beyond the end of the field was made.

       GD_E_INTERNAL_ERROR
               An internal error occurred in the library while trying to perform the task.   This
               indicates a bug in the library.  Please report the incident to the maintainer.

       The  error  code  is  also  stored  in  the DIRFILE object and may be retrieved after this
       function returns by calling gd_error(3).  A descriptive error string for the error may  be
       obtained by calling gd_error_string(3).

HISTORY

       The gd_get_sarray() and gd_get_sarray_slice() functions appeared in GetData-0.10.0.

SEE ALSO

       gd_array_len(3),    gd_get_string(3),    gd_error(3),    gd_error_string(3),   gd_open(3),
       gd_put_sarray_slice(3), gd_sarrays(3), dirfile(5)