NAME

       gd_error_string — report a GetData library error

SYNOPSIS

       #include <getdata.h>

       char *gd_error_string(const DIRFILE *dirfile, char *buffer, size_t buflen);

DESCRIPTION

       The  gd_error_string()  function  returns  a  string  describing  the  last  dirfile error
       encountered while operating on dirfile.

       If buffer is not NULL, the string is written to this  memory  location.   At  most  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
       gd_error(3).

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

RETURN VALUE

       If buffer is non-NULL, the gd_error_string() function returns buffer, or NULL if buflen is
       less than one.  If 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 dirfile is unchanged.

SEE ALSO

       gd_error(3), gd_error_count(3)