1explain_vsnprintf(3) Library Functions Manual explain_vsnprintf(3)
2
6 explain_vsnprintf - explain vsnprintf(3) errors
7
9 #include <libexplain/vsnprintf.h>
10 const char *explain_vsnprintf(char *data, size_t data_size, const char
11 *format, va_list ap);
12 const char *explain_errno_vsnprintf(int errnum, char *data, size_t
13 data_size, const char *format, va_list ap);
14 void explain_message_vsnprintf(char *message, int message_size, char
15 *data, size_t data_size, const char *format, va_list ap);
16 void explain_message_errno_vsnprintf(char *message, int message_size,
17 int errnum, char *data, size_t data_size, const char *format, va_list
18 ap);
19
21 These functions may be used to obtain explanations for errors returned
22 by the vsnprintf(3) system call.
23 explain_vsnprintf
25 const char *explain_vsnprintf(char *data, size_t data_size, const char
26 *format, va_list ap);
27 The explain_vsnprintf function is used to obtain an explanation of an
29 error returned by the vsnprintf(3) system call. The least the message
30 will contain is the value of strerror(errno), but usually it will do
31 much better, and indicate the underlying cause in more detail.
32 The errno global variable will be used to obtain the error value to be
34 decoded.
35 data The original data, exactly as passed to the vsnprintf(3) system
37 call.
38 data_size
40 The original data_size, exactly as passed to the vsnprintf(3)
41 system call.
42 format The original format, exactly as passed to the vsnprintf(3) sys‐
44 tem call.
45 ap The original ap, exactly as passed to the vsnprintf(3) system
47 call.
48 Returns:
50 The message explaining the error. This message buffer is shared
51 by all libexplain functions which do not supply a buffer in
52 their argument list. This will be overwritten by the next call
53 to any libexplain function which shares this buffer, including
54 other threads.
55 Note: This function is not thread safe, because it shares a return buf‐
57 fer across all threads, and many other functions in this library.
58 Example: This function is intended to be used in a fashion similar to
60 the following example:
61 errno = 0;
62 int result = vsnprintf(data, data_size, format, ap);
63 if (result < 0 && errno != 0)
64 {
65 fprintf(stderr, "%s\n", explain_vsnprintf(data, data_size,
66 format, ap));
67 exit(EXIT_FAILURE);
68 }
69 The above code example is available pre‐packaged as the
71 explain_vsnprintf_or_die(3) function.
72 explain_errno_vsnprintf
74 const char *explain_errno_vsnprintf(int errnum, char *data, size_t
75 data_size, const char *format, va_list ap);
76 The explain_errno_vsnprintf function is used to obtain an explanation
78 of an error returned by the vsnprintf(3) system call. The least the
79 message will contain is the value of strerror(errno), but usually it
80 will do much better, and indicate the underlying cause in more detail.
81 errnum The error value to be decoded, usually obtained from the errno
83 global variable just before this function is called. This is
84 necessary if you need to call any code between the system call
85 to be explained and this function, because many libc functions
86 will alter the value of errno.
87 data The original data, exactly as passed to the vsnprintf(3) system
89 call.
90 data_size
92 The original data_size, exactly as passed to the vsnprintf(3)
93 system call.
94 format The original format, exactly as passed to the vsnprintf(3) sys‐
96 tem call.
97 ap The original ap, exactly as passed to the vsnprintf(3) system
99 call.
100 Returns:
102 The message explaining the error. This message buffer is shared
103 by all libexplain functions which do not supply a buffer in
104 their argument list. This will be overwritten by the next call
105 to any libexplain function which shares this buffer, including
106 other threads.
107 Note: This function is not thread safe, because it shares a return buf‐
109 fer across all threads, and many other functions in this library.
110 Example: This function is intended to be used in a fashion similar to
112 the following example:
113 errno = 0;
114 int result = vsnprintf(data, data_size, format, ap);
115 if (result < 0 && errno != 0)
116 {
117 int err = errno;
118 fprintf(stderr, "%s\n", explain_errno_vsnprintf(err, data,
119 data_size, format, ap));
120 exit(EXIT_FAILURE);
121 }
122 The above code example is available pre‐packaged as the
124 explain_vsnprintf_or_die(3) function.
125 explain_message_vsnprintf
127 void explain_message_vsnprintf(char *message, int message_size, char
128 *data, size_t data_size, const char *format, va_list ap);
129 The explain_message_vsnprintf function is used to obtain an explanation
131 of an error returned by the vsnprintf(3) system call. The least the
132 message will contain is the value of strerror(errno), but usually it
133 will do much better, and indicate the underlying cause in more detail.
134 The errno global variable will be used to obtain the error value to be
136 decoded.
137 message The location in which to store the returned message. If a suit‐
139 able message return buffer is supplied, this function is thread
140 safe.
141 message_size
143 The size in bytes of the location in which to store the
144 returned message.
145 data The original data, exactly as passed to the vsnprintf(3) system
147 call.
148 data_size
150 The original data_size, exactly as passed to the vsnprintf(3)
151 system call.
152 format The original format, exactly as passed to the vsnprintf(3) sys‐
154 tem call.
155 ap The original ap, exactly as passed to the vsnprintf(3) system
157 call.
158 Example: This function is intended to be used in a fashion similar to
160 the following example:
161 errno = 0;
162 int result = vsnprintf(data, data_size, format, ap);
163 if (result < 0 && errno != 0)
164 {
165 char message[3000];
166 explain_message_vsnprintf(message, sizeof(message), data,
167 data_size, format, ap);
168 fprintf(stderr, "%s\n", message);
169 exit(EXIT_FAILURE);
170 }
171 The above code example is available pre‐packaged as the
173 explain_vsnprintf_or_die(3) function.
174 explain_message_errno_vsnprintf
176 void explain_message_errno_vsnprintf(char *message, int message_size,
177 int errnum, char *data, size_t data_size, const char *format, va_list
178 ap);
179 The explain_message_errno_vsnprintf function is used to obtain an
181 explanation of an error returned by the vsnprintf(3) system call. The
182 least the message will contain is the value of strerror(errno), but
183 usually it will do much better, and indicate the underlying cause in
184 more detail.
185 message The location in which to store the returned message. If a suit‐
187 able message return buffer is supplied, this function is thread
188 safe.
189 message_size
191 The size in bytes of the location in which to store the
192 returned message.
193 errnum The error value to be decoded, usually obtained from the errno
195 global variable just before this function is called. This is
196 necessary if you need to call any code between the system call
197 to be explained and this function, because many libc functions
198 will alter the value of errno.
199 data The original data, exactly as passed to the vsnprintf(3) system
201 call.
202 data_size
204 The original data_size, exactly as passed to the vsnprintf(3)
205 system call.
206 format The original format, exactly as passed to the vsnprintf(3) sys‐
208 tem call.
209 ap The original ap, exactly as passed to the vsnprintf(3) system
211 call.
212 Example: This function is intended to be used in a fashion similar to
214 the following example:
215 errno = 0;
216 int result = vsnprintf(data, data_size, format, ap);
217 if (result < 0 && errno != 0)
218 {
219 int err = errno;
220 char message[3000];
221 explain_message_errno_vsnprintf(message, sizeof(message),
222 err, data, data_size, format, ap);
223 fprintf(stderr, "%s\n", message);
224 exit(EXIT_FAILURE);
225 }
226 The above code example is available pre‐packaged as the
228 explain_vsnprintf_or_die(3) function.
229
231 vsnprintf(3)
232 formatted output conversion
233 explain_vsnprintf_or_die(3)
235 formatted output conversion and report errors
236
238 libexplain version 1.4
239 Copyright (C) 2010 Peter Miller
240 explain_vsnprintf(3)