gd_put_string(3)

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