1explain_vasprintf(3) Library Functions Manual explain_vasprintf(3)
2
6 explain_vasprintf - explain vasprintf(3) errors
7
9 #include <libexplain/vasprintf.h>
10 const char *explain_vasprintf(char **data, const char *format, va_list
11 ap);
12 const char *explain_errno_vasprintf(int errnum, char **data, const char
13 *format, va_list ap);
14 void explain_message_vasprintf(char *message, int message_size, char
15 **data, const char *format, va_list ap);
16 void explain_message_errno_vasprintf(char *message, int message_size,
17 int errnum, char **data, const char *format, va_list ap);
18
20 These functions may be used to obtain explanations for errors returned
21 by the vasprintf(3) system call.
22 explain_vasprintf
24 const char *explain_vasprintf(char **data, const char *format, va_list
25 ap);
26 The explain_vasprintf function is used to obtain an explanation of an
28 error returned by the vasprintf(3) system call. The least the message
29 will contain is the value of strerror(errno), but usually it will do
30 much better, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 data The original data, exactly as passed to the vasprintf(3) system
36 call.
37 format The original format, exactly as passed to the vasprintf(3) sys‐
39 tem call.
40 ap The original ap, exactly as passed to the vasprintf(3) system
42 call.
43 Returns:
45 The message explaining the error. This message buffer is shared
46 by all libexplain functions which do not supply a buffer in
47 their argument list. This will be overwritten by the next call
48 to any libexplain function which shares this buffer, including
49 other threads.
50 Note: This function is not thread safe, because it shares a return buf‐
52 fer across all threads, and many other functions in this library.
53 Example: This function is intended to be used in a fashion similar to
55 the following example:
56 errno = 0;
57 int result = vasprintf(data, format, ap);
58 if (result < 0 || errno != 0)
59 {
60 fprintf(stderr, "%s\n", explain_vasprintf(data, format,
61 ap));
62 exit(EXIT_FAILURE);
63 }
64 The above code example is available pre-packaged as the
66 explain_vasprintf_or_die(3) function.
67 explain_errno_vasprintf
69 const char *explain_errno_vasprintf(int errnum, char **data, const char
70 *format, va_list ap);
71 The explain_errno_vasprintf function is used to obtain an explanation
73 of an error returned by the vasprintf(3) system call. The least the
74 message will contain is the value of strerror(errno), but usually it
75 will do much better, and indicate the underlying cause in more detail.
76 errnum The error value to be decoded, usually obtained from the errno
78 global variable just before this function is called. This is
79 necessary if you need to call any code between the system call
80 to be explained and this function, because many libc functions
81 will alter the value of errno.
82 data The original data, exactly as passed to the vasprintf(3) system
84 call.
85 format The original format, exactly as passed to the vasprintf(3) sys‐
87 tem call.
88 ap The original ap, exactly as passed to the vasprintf(3) system
90 call.
91 Returns:
93 The message explaining the error. This message buffer is shared
94 by all libexplain functions which do not supply a buffer in
95 their argument list. This will be overwritten by the next call
96 to any libexplain function which shares this buffer, including
97 other threads.
98 Note: This function is not thread safe, because it shares a return buf‐
100 fer across all threads, and many other functions in this library.
101 Example: This function is intended to be used in a fashion similar to
103 the following example:
104 errno = 0;
105 int result = vasprintf(data, format, ap);
106 if (result < 0 || errno != 0)
107 {
108 int err = errno;
109 fprintf(stderr, "%s\n", explain_errno_vasprintf(err, data,
110 format, ap));
111 exit(EXIT_FAILURE);
112 }
113 The above code example is available pre-packaged as the
115 explain_vasprintf_or_die(3) function.
116 explain_message_vasprintf
118 void explain_message_vasprintf(char *message, int message_size, char
119 **data, const char *format, va_list ap);
120 The explain_message_vasprintf function is used to obtain an explanation
122 of an error returned by the vasprintf(3) system call. The least the
123 message will contain is the value of strerror(errno), but usually it
124 will do much better, and indicate the underlying cause in more detail.
125 The errno global variable will be used to obtain the error value to be
127 decoded.
128 message The location in which to store the returned message. If a suit‐
130 able message return buffer is supplied, this function is thread
131 safe.
132 message_size
134 The size in bytes of the location in which to store the
135 returned message.
136 data The original data, exactly as passed to the vasprintf(3) system
138 call.
139 format The original format, exactly as passed to the vasprintf(3) sys‐
141 tem call.
142 ap The original ap, exactly as passed to the vasprintf(3) system
144 call.
145 Example: This function is intended to be used in a fashion similar to
147 the following example:
148 errno = 0;
149 int result = vasprintf(data, format, ap);
150 if (result < 0 || errno != 0)
151 {
152 char message[3000];
153 explain_message_vasprintf(message, sizeof(message), data,
154 format, ap);
155 fprintf(stderr, "%s\n", message);
156 exit(EXIT_FAILURE);
157 }
158 The above code example is available pre-packaged as the
160 explain_vasprintf_or_die(3) function.
161 explain_message_errno_vasprintf
163 void explain_message_errno_vasprintf(char *message, int message_size,
164 int errnum, char **data, const char *format, va_list ap);
165 The explain_message_errno_vasprintf function is used to obtain an
167 explanation of an error returned by the vasprintf(3) system call. The
168 least the message will contain is the value of strerror(errno), but
169 usually it will do much better, and indicate the underlying cause in
170 more detail.
171 message The location in which to store the returned message. If a suit‐
173 able message return buffer is supplied, this function is thread
174 safe.
175 message_size
177 The size in bytes of the location in which to store the
178 returned message.
179 errnum The error value to be decoded, usually obtained from the errno
181 global variable just before this function is called. This is
182 necessary if you need to call any code between the system call
183 to be explained and this function, because many libc functions
184 will alter the value of errno.
185 data The original data, exactly as passed to the vasprintf(3) system
187 call.
188 format The original format, exactly as passed to the vasprintf(3) sys‐
190 tem call.
191 ap The original ap, exactly as passed to the vasprintf(3) system
193 call.
194 Example: This function is intended to be used in a fashion similar to
196 the following example:
197 errno = 0;
198 int result = vasprintf(data, format, ap);
199 if (result < 0 || errno != 0)
200 {
201 int err = errno;
202 char message[3000];
203 explain_message_errno_vasprintf(message, sizeof(message),
204 err, data, format, ap);
205 fprintf(stderr, "%s\n", message);
206 exit(EXIT_FAILURE);
207 }
208 The above code example is available pre-packaged as the
210 explain_vasprintf_or_die(3) function.
211
213 vasprintf(3)
214 print to allocated string
215 explain_vasprintf_or_die(3)
217 print to allocated string and report errors
218
220 libexplain version 1.4
221 Copyright (C) 2013 Peter Miller
222 explain_vasprintf(3)