1explain_asprintf(3)        Library Functions Manual        explain_asprintf(3)
2
3
4

NAME

6       explain_asprintf - explain asprintf(3) errors
7

SYNOPSIS

9       #include <libexplain/asprintf.h>
10       const char *explain_asprintf(, ...);
11       const char *explain_errno_asprintf(int errnum, , ...);
12       void explain_message_asprintf(char *message, int message_size, , ...);
13       void explain_message_errno_asprintf(char *message, int message_size,
14       int errnum, , ...);
15

DESCRIPTION

17       These functions may be used to obtain explanations for errors  returned
18       by the asprintf(3) system call.
19
20   explain_asprintf
21       const char *explain_asprintf(, ...);
22
23       The  explain_asprintf  function  is used to obtain an explanation of an
24       error returned by the asprintf(3) system call. The  least  the  message
25       will  contain  is  the value of strerror(errno), but usually it will do
26       much better, and indicate the underlying cause in more detail.
27
28       The errno global variable will be used to obtain the error value to  be
29       decoded.
30
31       Returns:
32               The message explaining the error. This message buffer is shared
33               by all libexplain functions which do not  supply  a  buffer  in
34               their argument list.  This will be overwritten by the next call
35               to any libexplain function which shares this buffer,  including
36               other threads.
37
38       Note: This function is not thread safe, because it shares a return buf‐
39       fer across all threads, and many other functions in this library.
40
41       Example: This function is intended to be used in a fashion  similar  to
42       the following example:
43              errno = 0;
44              int result = asprintf();
45              if (result < 0 || errno != 0)
46              {
47                  fprintf(stderr, "%s\n", explain_asprintf());
48                  exit(EXIT_FAILURE);
49              }
50
51       The   above   code   example   is   available   pre-packaged   as   the
52       explain_asprintf_or_die(3) function.
53
54   explain_errno_asprintf
55       const char *explain_errno_asprintf(int errnum, , ...);
56
57       The explain_errno_asprintf function is used to obtain an explanation of
58       an  error  returned by the asprintf(3) system call.  The least the mes‐
59       sage will contain is the value of strerror(errno), but usually it  will
60       do much better, and indicate the underlying cause in more detail.
61
62       errnum  The  error value to be decoded, usually obtained from the errno
63               global variable just before this function is  called.  This  is
64               necessary  if you need to call any code between the system call
65               to be explained and this function, because many libc  functions
66               will alter the value of errno.
67
68       Returns:
69               The message explaining the error. This message buffer is shared
70               by all libexplain functions which do not  supply  a  buffer  in
71               their argument list.  This will be overwritten by the next call
72               to any libexplain function which shares this buffer,  including
73               other threads.
74
75       Note: This function is not thread safe, because it shares a return buf‐
76       fer across all threads, and many other functions in this library.
77
78       Example: This function is intended to be used in a fashion  similar  to
79       the following example:
80              errno = 0;
81              int result = asprintf();
82              if (result < 0 || errno != 0)
83              {
84                  int err = errno;
85                  fprintf(stderr, "%s\n", explain_errno_asprintf(err, ));
86                  exit(EXIT_FAILURE);
87              }
88
89       The   above   code   example   is   available   pre-packaged   as   the
90       explain_asprintf_or_die(3) function.
91
92   explain_message_asprintf
93       void explain_message_asprintf(char *message, int message_size, , ...);
94
95       The explain_message_asprintf function is used to obtain an  explanation
96       of  an  error  returned  by the asprintf(3) system call.  The least the
97       message will contain is the value of strerror(errno),  but  usually  it
98       will do much better, and indicate the underlying cause in more detail.
99
100       The  errno global variable will be used to obtain the error value to be
101       decoded.
102
103       message The location in which to store the returned message. If a suit‐
104               able message return buffer is supplied, this function is thread
105               safe.
106
107       message_size
108               The size in bytes  of  the  location  in  which  to  store  the
109               returned message.
110
111       Example:  This  function is intended to be used in a fashion similar to
112       the following example:
113              errno = 0;
114              int result = asprintf();
115              if (result < 0 || errno != 0)
116              {
117                  char message[3000];
118                  explain_message_asprintf(message, sizeof(message), );
119                  fprintf(stderr, "%s\n", message);
120                  exit(EXIT_FAILURE);
121              }
122
123       The   above   code   example   is   available   pre-packaged   as   the
124       explain_asprintf_or_die(3) function.
125
126   explain_message_errno_asprintf
127       void explain_message_errno_asprintf(char *message, int message_size,
128       int errnum, , ...);
129
130       The explain_message_errno_asprintf function is used to obtain an expla‐
131       nation  of an error returned by the asprintf(3) system call.  The least
132       the message will contain is the value of strerror(errno),  but  usually
133       it  will  do  much  better,  and  indicate the underlying cause in more
134       detail.
135
136       message The location in which to store the returned message. If a suit‐
137               able message return buffer is supplied, this function is thread
138               safe.
139
140       message_size
141               The size in bytes  of  the  location  in  which  to  store  the
142               returned message.
143
144       errnum  The  error value to be decoded, usually obtained from the errno
145               global variable just before this function is  called.  This  is
146               necessary  if you need to call any code between the system call
147               to be explained and this function, because many libc  functions
148               will alter the value of errno.
149
150       Example:  This  function is intended to be used in a fashion similar to
151       the following example:
152              errno = 0;
153              int result = asprintf();
154              if (result < 0 || errno != 0)
155              {
156                  int err = errno;
157                  char message[3000];
158                  explain_message_errno_asprintf(message, sizeof(message),
159                  err, );
160                  fprintf(stderr, "%s\n", message);
161                  exit(EXIT_FAILURE);
162              }
163
164       The   above   code   example   is   available   pre-packaged   as   the
165       explain_asprintf_or_die(3) function.
166

SEE ALSO

168       asprintf(3)
169               print to allocated string
170
171       explain_asprintf_or_die(3)
172               print to allocated string and report errors
173
175       libexplain version 1.4
176       Copyright (C) 2013 Peter Miller
177
178
179
180                                                           explain_asprintf(3)
Impressum