.\" gd_get_string.3.  The gd_get_string man page.
.\"
.\" Copyright (C) 2008, 2009, 2010 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_get_string 3 "25 May 2010" "Version 0.7.0" "GETDATA"
.SH NAME
gd_get_string \(em retrieve a string from a dirfile database
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "size_t gd_get_string(DIRFILE *" dirfile ", const char *" field_code ,
.BI "size_t " len ", char *" data_out );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_get_string ()
function queries a dirfile(5) database specified by
.I dirfile
for the string scalar
.IR field_code ,
which should not contain a representation suffix.  The first
.I len
characters of the string scalar are stored in the user-supplied buffer
.IR data_out .

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

If
.I len
equals zero, or if
.I data_out
equals NULL, no data will be copied to
.IR data_out ,
but the length of the string scalar will still be returned by
.BR gd_get_string ().
Otherwise, the argument
.I data_out
must point to a valid memory location of sufficient size to hold at least
.I len
characters.  If the length of the string scalar is greater than
.IR len ", " data_out
will not be NULL-terminated.
.SH RETURN VALUE
On success,
.BR gd_get_string ()
returns the actual length of the specified string scalar, including the trailing
NULL character.  A return value greater than
.I len
indicates that the output string is not null terminated.

On error, it returns 0 and sets the dirfile error to a non-zero
value.  Possible error values are:
.TP 8
.B GD_E_BAD_CODE
The field specified by
.I field_code
was not found in the database.
.TP
.B GD_E_BAD_DIRFILE
An invalid
.I dirfile
was supplied.
.TP
.B GD_E_BAD_FIELD_TYPE
The supplied
.I field_code
referred to a field of type other than
.BR STRING .
The caller should use
.BR gd_getdata (3),
or
.BR gd_get_constant (3)
instead.
.TP
.B GD_E_BAD_TYPE
An invalid
.I return_type
was specified.
.TP
.B 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.
.PP
The dirfile error may be retrieved by calling
.BR gd_error (3).
A descriptive error string for the last error encountered may be obtained from
a call to
.BR gd_error_string (3).
.SH SEE ALSO
.BR dirfile (5),
.BR gd_open (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR gd_put_string (3)