1explain_vsprintf(3) Library Functions Manual explain_vsprintf(3)
2
6 explain_vsprintf - explain vsprintf(3) errors
7
9 #include <libexplain/vsprintf.h>
10 const char *explain_vsprintf(char *data, const char *format, va_list
11 ap);
12 const char *explain_errno_vsprintf(int errnum, char *data, const char
13 *format, va_list ap);
14 void explain_message_vsprintf(char *message, int message_size, char
15 *data, const char *format, va_list ap);
16 void explain_message_errno_vsprintf(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 vsprintf(3) system call.
22 explain_vsprintf
24 const char *explain_vsprintf(char *data, const char *format, va_list
25 ap);
26 The explain_vsprintf function is used to obtain an explanation of an
28 error returned by the vsprintf(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 vsprintf(3) system
36 call.
37 format The original format, exactly as passed to the vsprintf(3) sys‐
39 tem call.
40 ap The original ap, exactly as passed to the vsprintf(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 = vsprintf(data, format, ap);
58 if (result < 0 && errno != 0)
59 {
60 fprintf(stderr, "%s\n", explain_vsprintf(data, format, ap));
61 exit(EXIT_FAILURE);
62 }
63 The above code example is available pre‐packaged as the
65 explain_vsprintf_or_die(3) function.
66 explain_errno_vsprintf
68 const char *explain_errno_vsprintf(int errnum, char *data, const char
69 *format, va_list ap);
70 The explain_errno_vsprintf function is used to obtain an explanation of
72 an error returned by the vsprintf(3) system call. The least the mes‐
73 sage will contain is the value of strerror(errno), but usually it will
74 do much better, and indicate the underlying cause in more detail.
75 errnum The error value to be decoded, usually obtained from the errno
77 global variable just before this function is called. This is
78 necessary if you need to call any code between the system call
79 to be explained and this function, because many libc functions
80 will alter the value of errno.
81 data The original data, exactly as passed to the vsprintf(3) system
83 call.
84 format The original format, exactly as passed to the vsprintf(3) sys‐
86 tem call.
87 ap The original ap, exactly as passed to the vsprintf(3) system
89 call.
90 Returns:
92 The message explaining the error. This message buffer is shared
93 by all libexplain functions which do not supply a buffer in
94 their argument list. This will be overwritten by the next call
95 to any libexplain function which shares this buffer, including
96 other threads.
97 Note: This function is not thread safe, because it shares a return buf‐
99 fer across all threads, and many other functions in this library.
100 Example: This function is intended to be used in a fashion similar to
102 the following example:
103 errno = 0;
104 int result = vsprintf(data, format, ap);
105 if (result < 0 && errno != 0)
106 {
107 int err = errno;
108 fprintf(stderr, "%s\n", explain_errno_vsprintf(err, data,
109 format, ap));
110 exit(EXIT_FAILURE);
111 }
112 The above code example is available pre‐packaged as the
114 explain_vsprintf_or_die(3) function.
115 explain_message_vsprintf
117 void explain_message_vsprintf(char *message, int message_size, char
118 *data, const char *format, va_list ap);
119 The explain_message_vsprintf function is used to obtain an explanation
121 of an error returned by the vsprintf(3) system call. The least the
122 message will contain is the value of strerror(errno), but usually it
123 will do much better, and indicate the underlying cause in more detail.
124 The errno global variable will be used to obtain the error value to be
126 decoded.
127 message The location in which to store the returned message. If a suit‐
129 able message return buffer is supplied, this function is thread
130 safe.
131 message_size
133 The size in bytes of the location in which to store the
134 returned message.
135 data The original data, exactly as passed to the vsprintf(3) system
137 call.
138 format The original format, exactly as passed to the vsprintf(3) sys‐
140 tem call.
141 ap The original ap, exactly as passed to the vsprintf(3) system
143 call.
144 Example: This function is intended to be used in a fashion similar to
146 the following example:
147 errno = 0;
148 int result = vsprintf(data, format, ap);
149 if (result < 0 && errno != 0)
150 {
151 char message[3000];
152 explain_message_vsprintf(message, sizeof(message), data,
153 format, ap);
154 fprintf(stderr, "%s\n", message);
155 exit(EXIT_FAILURE);
156 }
157 The above code example is available pre‐packaged as the
159 explain_vsprintf_or_die(3) function.
160 explain_message_errno_vsprintf
162 void explain_message_errno_vsprintf(char *message, int message_size,
163 int errnum, char *data, const char *format, va_list ap);
164 The explain_message_errno_vsprintf function is used to obtain an expla‐
166 nation of an error returned by the vsprintf(3) system call. The least
167 the message will contain is the value of strerror(errno), but usually
168 it will do much better, and indicate the underlying cause in more
169 detail.
170 message The location in which to store the returned message. If a suit‐
172 able message return buffer is supplied, this function is thread
173 safe.
174 message_size
176 The size in bytes of the location in which to store the
177 returned message.
178 errnum The error value to be decoded, usually obtained from the errno
180 global variable just before this function is called. This is
181 necessary if you need to call any code between the system call
182 to be explained and this function, because many libc functions
183 will alter the value of errno.
184 data The original data, exactly as passed to the vsprintf(3) system
186 call.
187 format The original format, exactly as passed to the vsprintf(3) sys‐
189 tem call.
190 ap The original ap, exactly as passed to the vsprintf(3) system
192 call.
193 Example: This function is intended to be used in a fashion similar to
195 the following example:
196 errno = 0;
197 int result = vsprintf(data, format, ap);
198 if (result < 0 && errno != 0)
199 {
200 int err = errno;
201 char message[3000];
202 explain_message_errno_vsprintf(message, sizeof(message),
203 err, data, format, ap);
204 fprintf(stderr, "%s\n", message);
205 exit(EXIT_FAILURE);
206 }
207 The above code example is available pre‐packaged as the
209 explain_vsprintf_or_die(3) function.
210
212 vsprintf(3)
213 formatted output conversion
214 explain_vsprintf_or_die(3)
216 formatted output conversion and report errors
217
219 libexplain version 1.4
220 Copyright (C) 2010 Peter Miller
221 explain_vsprintf(3)