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.

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

RETURN VALUE

       If buffer is non-NULL, the gd_error_string() function returns buffer, or NULL if buflen is
       less  than  one.  Otherwise, it returns a newly malloc'd string of sufficient length which
       should be deallocated by the caller.  The error state of dirfile is unchanged.

SEE ALSO

       gd_open(3), gd_error(3)