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¶

The gd_put_sarray() and gd_put_sarray_slice() functions appeared in GetData-0.10.0.

SEE ALSO¶

dirfile(5), gd_array_len(3), gd_sarrays(3), gd_error(3), gd_error_string(3), gd_get_sarray_slice(3), gd_open(3), gd_put_string(3)