.\" gd_error_string.3.  The gd_error_string man page.
.\"
.\" Copyright (C) 2008, 2009, 2010, 2011, 2014 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_error_string 3 "16 October 2014" "Version 0.9.0" "GETDATA"
.SH NAME
gd_error_string \(em report a GetData library error
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "char *gd_error_string(const DIRFILE *" dirfile ", char *" buffer ", size_t
.IB buflen );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_error_string ()
function returns a string describing the last dirfile error encountered while
operating on 
.IR dirfile .

If 
.I buffer
is not NULL, the string is written to this memory location.  At most
.I buflen
characters will be written. This always includes a terminating null byte, even
if the error string was truncated.
The numeric dirfile error itself may be obtained by calling
.BR gd_error (3).

If
.I buffer
is NULL,
.BR gd_error_string ()
will allocate a string of sufficient length using
.BR malloc (3),
and
.I buflen
is ignored.  In this case, the caller should deallocate the returned string
using
.BR free (3)
when it is no longer needed.

.SH RETURN VALUE
If
.I buffer
is non-NULL, the
.BR gd_error_string ()
function returns 
.IR buffer ,
or NULL if buflen is less than one.  If
.I buffer
is NULL, this function returns a newly malloc'd
string of sufficient length which should be deallocated by the caller, or
NULL, if memory allocation failed.  In all cases, the error state of
.I dirfile
is unchanged.
.SH SEE ALSO
.BR gd_error (3),
.BR gd_error_count (3)