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)