1explain_snprintf(3) Library Functions Manual explain_snprintf(3)
2
6 explain_snprintf - explain snprintf(3) errors
7
9 #include <libexplain/snprintf.h>
10 const char *explain_snprintf(char *data, size_t data_size, const char
11 *format);
12 const char *explain_errno_snprintf(int errnum, char *data, size_t
13 data_size, const char *format);
14 void explain_message_snprintf(char *message, int message_size, char
15 *data, size_t data_size, const char *format);
16 void explain_message_errno_snprintf(char *message, int message_size,
17 int errnum, char *data, size_t data_size, const char *format);
18
20 These functions may be used to obtain explanations for errors returned
21 by the snprintf(3) system call.
22 explain_snprintf
24 const char *explain_snprintf(char *data, size_t data_size, const char
25 *format);
26 The explain_snprintf function is used to obtain an explanation of an
28 error returned by the snprintf(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 snprintf(3) system
36 call.
37 data_size
39 The original data_size, exactly as passed to the snprintf(3)
40 system call.
41 format The original format, exactly as passed to the snprintf(3) sys‐
43 tem call.
44 Returns:
46 The message explaining the error. This message buffer is shared
47 by all libexplain functions which do not supply a buffer in
48 their argument list. This will be overwritten by the next call
49 to any libexplain function which shares this buffer, including
50 other threads.
51 Note: This function is not thread safe, because it shares a return buf‐
53 fer across all threads, and many other functions in this library.
54 Example: This function is intended to be used in a fashion similar to
56 the following example:
57 errno = 0;
58 int result = snprintf(data, data_size, format);
59 if (result < 0 && errno != 0)
60 {
61 fprintf(stderr, "%s\n", explain_snprintf(data, data_size,
62 format));
63 exit(EXIT_FAILURE);
64 }
65 The above code example is available pre‐packaged as the
67 explain_snprintf_or_die(3) function.
68 explain_errno_snprintf
70 const char *explain_errno_snprintf(int errnum, char *data, size_t
71 data_size, const char *format);
72 The explain_errno_snprintf function is used to obtain an explanation of
74 an error returned by the snprintf(3) system call. The least the mes‐
75 sage will contain is the value of strerror(errno), but usually it will
76 do much better, and indicate the underlying cause in more detail.
77 errnum The error value to be decoded, usually obtained from the errno
79 global variable just before this function is called. This is
80 necessary if you need to call any code between the system call
81 to be explained and this function, because many libc functions
82 will alter the value of errno.
83 data The original data, exactly as passed to the snprintf(3) system
85 call.
86 data_size
88 The original data_size, exactly as passed to the snprintf(3)
89 system call.
90 format The original format, exactly as passed to the snprintf(3) sys‐
92 tem call.
93 Returns:
95 The message explaining the error. This message buffer is shared
96 by all libexplain functions which do not supply a buffer in
97 their argument list. This will be overwritten by the next call
98 to any libexplain function which shares this buffer, including
99 other threads.
100 Note: This function is not thread safe, because it shares a return buf‐
102 fer across all threads, and many other functions in this library.
103 Example: This function is intended to be used in a fashion similar to
105 the following example:
106 errno = 0;
107 int result = snprintf(data, data_size, format);
108 if (result < 0 && errno != 0)
109 {
110 int err = errno;
111 fprintf(stderr, "%s\n", explain_errno_snprintf(err, data,
112 data_size, format));
113 exit(EXIT_FAILURE);
114 }
115 The above code example is available pre‐packaged as the
117 explain_snprintf_or_die(3) function.
118 explain_message_snprintf
120 void explain_message_snprintf(char *message, int message_size, char
121 *data, size_t data_size, const char *format);
122 The explain_message_snprintf function is used to obtain an explanation
124 of an error returned by the snprintf(3) system call. The least the
125 message will contain is the value of strerror(errno), but usually it
126 will do much better, and indicate the underlying cause in more detail.
127 The errno global variable will be used to obtain the error value to be
129 decoded.
130 message The location in which to store the returned message. If a suit‐
132 able message return buffer is supplied, this function is thread
133 safe.
134 message_size
136 The size in bytes of the location in which to store the
137 returned message.
138 data The original data, exactly as passed to the snprintf(3) system
140 call.
141 data_size
143 The original data_size, exactly as passed to the snprintf(3)
144 system call.
145 format The original format, exactly as passed to the snprintf(3) sys‐
147 tem call.
148 Example: This function is intended to be used in a fashion similar to
150 the following example:
151 errno = 0;
152 int result = snprintf(data, data_size, format);
153 if (result < 0 && errno != 0)
154 {
155 char message[3000];
156 explain_message_snprintf(message, sizeof(message), data,
157 data_size, format);
158 fprintf(stderr, "%s\n", message);
159 exit(EXIT_FAILURE);
160 }
161 The above code example is available pre‐packaged as the
163 explain_snprintf_or_die(3) function.
164 explain_message_errno_snprintf
166 void explain_message_errno_snprintf(char *message, int message_size,
167 int errnum, char *data, size_t data_size, const char *format);
168 The explain_message_errno_snprintf function is used to obtain an expla‐
170 nation of an error returned by the snprintf(3) system call. The least
171 the message will contain is the value of strerror(errno), but usually
172 it will do much better, and indicate the underlying cause in more
173 detail.
174 message The location in which to store the returned message. If a suit‐
176 able message return buffer is supplied, this function is thread
177 safe.
178 message_size
180 The size in bytes of the location in which to store the
181 returned message.
182 errnum The error value to be decoded, usually obtained from the errno
184 global variable just before this function is called. This is
185 necessary if you need to call any code between the system call
186 to be explained and this function, because many libc functions
187 will alter the value of errno.
188 data The original data, exactly as passed to the snprintf(3) system
190 call.
191 data_size
193 The original data_size, exactly as passed to the snprintf(3)
194 system call.
195 format The original format, exactly as passed to the snprintf(3) sys‐
197 tem call.
198 Example: This function is intended to be used in a fashion similar to
200 the following example:
201 errno = 0;
202 int result = snprintf(data, data_size, format);
203 if (result < 0 && errno != 0)
204 {
205 int err = errno;
206 char message[3000];
207 explain_message_errno_snprintf(message, sizeof(message),
208 err, data, data_size, format);
209 fprintf(stderr, "%s\n", message);
210 exit(EXIT_FAILURE);
211 }
212 The above code example is available pre‐packaged as the
214 explain_snprintf_or_die(3) function.
215
217 snprintf(3)
218 formatted output conversion
219 explain_snprintf_or_die(3)
221 formatted output conversion and report errors
222
224 libexplain version 0.40
225 Copyright (C) 2010 Peter Miller
226 explain_snprintf(3)