1
2
3
4
5
6
7
8
9gd_error(3)                         GETDATA                        gd_error(3)
10
11
12

NAME

14       gd_error, gd_error_string — report a GetData library error
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_error(const DIRFILE *dirfile);
21
22       char *gd_error_string(const DIRFILE *dirfile, char *buffer, size_t
23              buflen);
24
25

DESCRIPTION

27       The gd_error() function determines the success or failure of  the  most
28       recent  GetData library function call that operated on dirfile.  If the
29       last call succeeded, gd_error() will return GD_E_OK (which  equals  ze‐
30       ro).  If the last call failed, gd_error() returns a negative-valued er‐
31       ror code indicating the cause of the failure.  Possible codes vary from
32       function  to  function.   See corresponding manual page of the function
33       that failed for a list of possible codes.
34
35       The gd_error_string() function behaves similarly, but composes a string
36       describing  the error.  If buffer is not NULL, the string is written to
37       this memory location.  At most buflen characters will  be  written  in‐
38       cluding  the  terminating  NUL  byte.  If buffer is not large enough to
39       hold the entire string, the string will be truncated, but the truncated
40       string will still be NUL-terminated.
41
42       If  buffer  is NULL, gd_error_string() will allocate a string of suffi‐
43       cient length on the heap.  In this case, buflen  is  ignored.   By  de‐
44       fault, malloc(3) is used to allocate this buffer, but an alternate mem‐
45       ory manager may be specified by calling gd_alloc_funcs(3) before  call‐
46       ing  this  function.   The  caller is responsible for deallocating this
47       string when it is no longer needed.
48
49       The  functions   gd_alloc_funcs(3),   gd_error_count(3),   gd_flags(3),
50       gd_free_entry_strings(3),           gd_mplex_lookback(3),           and
51       gd_parser_callback(3) are ignored by these functions, since they always
52       succeed.   Previous gd_error() and gd_error_string() calls are also ig‐
53       nored.
54
55

RETURN VALUE

57       The gd_error() function always returns the integer error  code  of  the
58       last library call on the supplied DIRFILE object.
59
60       If  buffer is non-NULL, gd_error_string() returns buffer, unless buflen
61       is less than one, in which case it returns NULL.  If  buffer  is  NULL,
62       this  function  returns  a  newly allocated string of sufficient length
63       which should be deallocated by the caller, or NULL, if  memory  alloca‐
64       tion failed.
65
66

HISTORY

68       The get_error_string() function appeared in GetData-0.3.0.
69
70       The  get_error()  function appeared in GetData-0.4.0.  Before this, the
71       error code was directly accessible via the dirfile->error member in the
72       DIRFILE structure.
73
74       In  GetData-0.7.0,  these  functions  were  renamed  to  gd_error() and
75       gd_error_string().   This  is  also  the   first   release   in   which
76       gd_error_string()  would  allocate  a  buffer  for  the error string if
77       passed NULL.
78
79

SEE ALSO

81       gd_error_count(3)
82
83
84
85Version 0.10.0                 25 December 2016                    gd_error(3)
Impressum