oracular (3) gd_put_string.3.gz

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