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)