NAME

       gd_get_string — retrieve STRING or SARRAY data from a Dirfile database

SYNOPSIS

       #include <getdata.h>

       size_t gd_get_string(DIRFILE *dirfile, const char *field_code, size_t len, char *data_out);

DESCRIPTION

       The  gd_get_string()  function  queries  a dirfile(5) database specified by dirfile for the string scalar
       field_code, which should not contain a representation suffix.  The first len  characters  of  the  string
       scalar  are  stored  in  the  user-supplied buffer data_out.  If field_code refers to a SARRAY field, the
       first element is returned.

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

       If len equals zero, or if data_out equals NULL, no data will be copied to data_out, but the length of the
       string scalar will still be returned by gd_get_string().  Otherwise, the argument data_out must point  to
       a  valid memory location of sufficient size to hold at least len characters.  If the length of the string
       scalar is greater than len, data_out will not be NUL-terminated.

       The gd_get_sarray(3) function provides another way of retrieving STRING data, but without having to  know
       the length of the returned string in advance.  The code:

              size_t len = gd_get_string(dirfile, field_code, 0, NULL);
              char *string = malloc(len);
              gd_get_string(dirfile, field_code, len, string);

       which ensures the whole string, including the terminating NUL, is returned, can be replaced with, simply:

              const char *string;
              gd_get_sarray(dirfile, field_code, &string);

       with the added benefit of not having manage the memory for the string.

RETURN VALUE

       On success, gd_get_string() returns the actual length of the specified string scalar, including space for
       the trailing NUL-character.  A return value greater than len indicates that the output string is not NUL-
       terminated.

       On error, this function returns 0 and stores a negative-valued error code in the DIRFILE object which may
       be retrieved by a subsequent call to gd_error(3).  Possible error codes are:

       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 or SARRAY.

       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.

       A descriptive error string for the error may be obtained by calling gd_error_string(3).

HISTORY

       The get_string() function appeared in GetData-0.4.0.

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

SEE ALSO

       gd_get_sarray(3), gd_error(3), gd_error_string(3), gd_open(3), gd_put_string(3), dirfile(5)

Version 0.10.0                                  25 December 2016                                gd_get_string(3)