NAME¶

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

SYNOPSIS¶

#include <getdata.h>

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

DESCRIPTION¶

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.

RETURN VALUE¶

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

GD_E_ACCMODE

The specified dirfile was opened read-only.

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 referred to a field of type other than SARRAY or STRING.

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 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).

HISTORY¶

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.

SEE ALSO¶

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).