Scroll to navigation

gd_put_string(3) GETDATA gd_put_string(3)


gd_put_string — write a STRING or SARRAY element to a Dirfile database


#include <getdata.h>

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


The gd_put_string() function queries a dirfile(5) database specified by dirfile and stores the character string data_in in the STRING or SARRAY scalar field, specified by field_code. If field_code specifies a SARRAY field, the supplied string is stored as the first element.

The dirfile argument must point to a valid DIRFILE object previously created by a call to gd_open(3).

Because string values are stored in the dirfile metadata, the new value of field_code won't be written to disk until the dirfile metadata is flushed with gd_metaflush(3), or until the dirfile is closed with gd_close(3).

The gd_put_sarray(3) function provides another way of storing STRING and SARRAY data to a Dirfile.


On success, gd_put_string() returns zero. On error, this a negative-valued error code. Possible error codes are:

The specified dirfile was opened read-only.
The field specified by field_code was not found in the database.
An invalid dirfile was supplied.
The supplied field_code referred to a field of type other than SARRAY or STRING.
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 string 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 put_string() function apepared in GetData-0.4.0. It returned a size_t cotnaining length of the string written, or zero on error.

In GetData-0.7.0, this function was renamed to gd_put_strint().

In GetData-0.10.0, this function's return value changed to zero on success, or or else a negative-valued error code.


dirfile(5), gd_close(3), gd_get_string(3), gd_error(3), gd_error_string(3), gd_metaflush(3), gd_open(3), gd_put_sarray(3).

25 December 2016 Version 0.10.0