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)