NAME

       gd_put_string — retrieve a string from 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 sets
       the STRING field_code , which should not contain a representation  suffix,  to  the  value
       specified in data_in.

       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.

RETURN VALUE

       On success, gd_put_string() returns  the  length  of  the  string  stored,  including  the
       trailing  NUL  character.  On error, it returns 0 and sets the dirfile error to a non-zero
       value.  Possible error values 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 STRING.  The caller
               should use gd_putdata(3), gd_put_carray(3), or gd_put_constant(3) instead.

       GD_E_BAD_TYPE
               An invalid data_type was specified.

       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 dirfile error may be retrieved by calling gd_error(3).  A descriptive error string for
       the last error encountered may be obtained from a call to gd_error_string(3).

SEE ALSO

       dirfile(5),      gd_metaflush(3),      gd_open(3),      gd_get_string(3),     gd_error(3),
       gd_error_string(3), gd_putdata(3)