gd_get_string(3)

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 function queries a dirfile(5) database specified by for the string scalar which should not contain a representation suffix. The first characters of the string scalar are stored in the user-supplied buffer If refers to a SARRAY field, the first element is returned.

The argument must point to a valid DIRFILE object previously created by a call to

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

The 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, returns the actual length of the specified string scalar, including space for the trailing NUL-character. A return value greater than 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 Possible error codes are: The field specified by was not found in the database. An invalid was supplied. The supplied referred to a field of type other than STRING or SARRAY. 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

HISTORY
The function appeared in GetData-0.4.0.

In GetData-0.7.0, this function was renamed to

SEE ALSO
dirfile(5)