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)