Provided by: libgetdata-doc_0.11.0-13_all bug

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 func‐
       tions 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)

Version 0.10.0                                  25 December 2016                          gd_get_sarray_slice(3)