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


#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);


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.


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:

The specified dirfile was opened read-only.
The library was unable to allocate memory.
The field specified by field_code was not found in the database.
An invalid dirfile was supplied.
The supplied field_code was not a STRING nor a SARRAY.
A request for data beyond the end of the field was made.
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 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).


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


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)

Last updated on 25 December 2016 for GetData Version 0.10.0.