NAME

       gd_error, gd_error_string — report a GetData library error

SYNOPSIS

       #include <getdata.h>

       int gd_error(const DIRFILE *dirfile);

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

DESCRIPTION

       The  gd_error()  function  determines  the success or failure of the most recent GetData library function
       call that operated on dirfile.  If the last call succeeded, gd_error() will return GD_E_OK (which  equals
       zero).   If the last call failed, gd_error() returns a negative-valued error code indicating the cause of
       the failure.  Possible codes vary from function to  function.   See  corresponding  manual  page  of  the
       function that failed for a list of possible codes.

       The  gd_error_string() function behaves similarly, but composes a string describing the error.  If buffer
       is not NULL, the string is written to this memory location.  At most buflen characters  will  be  written
       including  the terminating NUL byte.  If buffer is not large enough to hold the entire string, the string
       will be truncated, but the truncated string will still be NUL-terminated.

       If buffer is NULL, gd_error_string() will allocate a string of sufficient length on the  heap.   In  this
       case,  buflen is ignored.  By default, malloc(3) is used to allocate this buffer, but an alternate memory
       manager may be specified by calling gd_alloc_funcs(3)  before  calling  this  function.   The  caller  is
       responsible for deallocating this string when it is no longer needed.

       The    functions    gd_alloc_funcs(3),    gd_error_count(3),    gd_flags(3),    gd_free_entry_strings(3),
       gd_mplex_lookback(3), and gd_parser_callback(3)  are  ignored  by  these  functions,  since  they  always
       succeed.  Previous gd_error() and gd_error_string() calls are also ignored.

RETURN VALUE

       The  gd_error()  function  always returns the integer error code of the last library call on the supplied
       DIRFILE object.

       If buffer is non-NULL, gd_error_string() returns buffer, unless buflen is less than one, in which case it
       returns  NULL.   If  buffer  is NULL, this function returns a newly allocated string of sufficient length
       which should be deallocated by the caller, or NULL, if memory allocation failed.

HISTORY

       The get_error_string() function appeared in GetData-0.3.0.

       The get_error() function appeared in GetData-0.4.0.  Before this, the error code was directly  accessible
       via the dirfile->error member in the DIRFILE structure.

       In  GetData-0.7.0,  these  functions  were renamed to gd_error() and gd_error_string().  This is also the
       first release in which gd_error_string() would allocate a buffer for the error string if passed NULL.

SEE ALSO

       gd_error_count(3)