gd_put_sarray_slice(3)

NAME

gd_put_sarray, gd_put_sarray_slice—write STRING or SARRAY data to a Dirfile database

SYNOPSIS

#include <getdata.h>

int gd_put_sarray_slice(DIRFILE *dirfile, const char *field_code, unsigned int start, size_t len, const char **data_in);

int gd_put_sarray(DIRFILE *dirfile, const char *field_code, const char **data_in);

DESCRIPTION

The gd_put_sarray_slice() function writes string data to a dirfile(5) database specified by dirfile into the STRING or SARRAY scalar array field_code. The location of the first element of the field into which data is stored is given by start, and the number of elements stored is given by len.

If field_code specifies a STRING field, it is treated as if it were a SARRAY field of length one.

The gd_put_sarray() function behaves similarly, except the whole scalar array is written, as if gd_put_sarray_slice() were called with start equal zero and len equal to the value returned by gd_array_len(3).

The argument data_in must point to an array of pointers to character strings, which are the values to store. The number of elements which will be stored by gd_put_sarray() may be obtained by calling gd_array_len(3). Unlike gd_putdata(3), writing data past the end of the field is not permitted. To add data to a SARRAY, first increase its length by calling gd_alter_sarray(3), or another equivalent function.

The gd_put_string(3) function provides another way of writing data to a STRING field.

RETURN VALUE

On success, gd_put_sarray() and gd_put_sarray_slice() return zero. On error, they return a negative-valued error code. Possible error codes are:

GD_E_ACCMODE: The specified dirfile was opened read-only.
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 a 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.
GD_E_PROTECTED: The fragment containing the constant was protected from change.

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