1explain_printf(3) Library Functions Manual explain_printf(3)
2
6 explain_printf - explain printf(3) errors
7
9 #include <libexplain/printf.h>
10 const char *explain_printf(const char *format);
11 const char *explain_errno_printf(int errnum, const char *format);
12 void explain_message_printf(char *message, int message_size, const char
13 *format);
14 void explain_message_errno_printf(char *message, int message_size, int
15 errnum, const char *format);
16
18 These functions may be used to obtain explanations for errors returned
19 by the printf(3) system call.
20 explain_printf
22 const char *explain_printf(const char *format);
23 The explain_printf function is used to obtain an explanation of an
25 error returned by the printf(3) system call. The least the message will
26 contain is the value of strerror(errno), but usually it will do much
27 better, and indicate the underlying cause in more detail.
28 The errno global variable will be used to obtain the error value to be
30 decoded.
31 format The original format, exactly as passed to the printf(3) system
33 call.
34 Returns:
36 The message explaining the error. This message buffer is shared
37 by all libexplain functions which do not supply a buffer in
38 their argument list. This will be overwritten by the next call
39 to any libexplain function which shares this buffer, including
40 other threads.
41 Note: This function is not thread safe, because it shares a return buf‐
43 fer across all threads, and many other functions in this library.
44 Example: This function is intended to be used in a fashion similar to
46 the following example:
47 errno = 0;
48 int result = printf(format);
49 if (result < 0 && errno != 0)
50 {
51 fprintf(stderr, "%s\n", explain_printf(format));
52 exit(EXIT_FAILURE);
53 }
54 The above code example is available pre‐packaged as the
56 explain_printf_or_die(3) function.
57 explain_errno_printf
59 const char *explain_errno_printf(int errnum, const char *format);
60 The explain_errno_printf function is used to obtain an explanation of
62 an error returned by the printf(3) system call. The least the message
63 will contain is the value of strerror(errno), but usually it will do
64 much better, and indicate the underlying cause in more detail.
65 errnum The error value to be decoded, usually obtained from the errno
67 global variable just before this function is called. This is
68 necessary if you need to call any code between the system call
69 to be explained and this function, because many libc functions
70 will alter the value of errno.
71 format The original format, exactly as passed to the printf(3) system
73 call.
74 Returns:
76 The message explaining the error. This message buffer is shared
77 by all libexplain functions which do not supply a buffer in
78 their argument list. This will be overwritten by the next call
79 to any libexplain function which shares this buffer, including
80 other threads.
81 Note: This function is not thread safe, because it shares a return buf‐
83 fer across all threads, and many other functions in this library.
84 Example: This function is intended to be used in a fashion similar to
86 the following example:
87 errno = 0;
88 int result = printf(format);
89 if (result < 0 && errno != 0)
90 {
91 int err = errno;
92 fprintf(stderr, "%s\n", explain_errno_printf(err, format));
93 exit(EXIT_FAILURE);
94 }
95 The above code example is available pre‐packaged as the
97 explain_printf_or_die(3) function.
98 explain_message_printf
100 void explain_message_printf(char *message, int message_size, const char
101 *format);
102 The explain_message_printf function is used to obtain an explanation of
104 an error returned by the printf(3) system call. The least the message
105 will contain is the value of strerror(errno), but usually it will do
106 much better, and indicate the underlying cause in more detail.
107 The errno global variable will be used to obtain the error value to be
109 decoded.
110 message The location in which to store the returned message. If a suit‐
112 able message return buffer is supplied, this function is thread
113 safe.
114 message_size
116 The size in bytes of the location in which to store the
117 returned message.
118 format The original format, exactly as passed to the printf(3) system
120 call.
121 Example: This function is intended to be used in a fashion similar to
123 the following example:
124 errno = 0;
125 int result = printf(format);
126 if (result < 0 && errno != 0)
127 {
128 char message[3000];
129 explain_message_printf(message, sizeof(message), format);
130 fprintf(stderr, "%s\n", message);
131 exit(EXIT_FAILURE);
132 }
133 The above code example is available pre‐packaged as the
135 explain_printf_or_die(3) function.
136 explain_message_errno_printf
138 void explain_message_errno_printf(char *message, int message_size, int
139 errnum, const char *format);
140 The explain_message_errno_printf function is used to obtain an explana‐
142 tion of an error returned by the printf(3) system call. The least the
143 message will contain is the value of strerror(errno), but usually it
144 will do much better, and indicate the underlying cause in more detail.
145 message The location in which to store the returned message. If a suit‐
147 able message return buffer is supplied, this function is thread
148 safe.
149 message_size
151 The size in bytes of the location in which to store the
152 returned message.
153 errnum The error value to be decoded, usually obtained from the errno
155 global variable just before this function is called. This is
156 necessary if you need to call any code between the system call
157 to be explained and this function, because many libc functions
158 will alter the value of errno.
159 format The original format, exactly as passed to the printf(3) system
161 call.
162 Example: This function is intended to be used in a fashion similar to
164 the following example:
165 errno = 0;
166 int result = printf(format);
167 if (result < 0 && errno != 0)
168 {
169 int err = errno;
170 char message[3000];
171 explain_message_errno_printf(message, sizeof(message), err,
172 format);
173 fprintf(stderr, "%s\n", message);
174 exit(EXIT_FAILURE);
175 }
176 The above code example is available pre‐packaged as the
178 explain_printf_or_die(3) function.
179
181 printf(3)
182 formatted output conversion
183 explain_printf_or_die(3)
185 formatted output conversion and report errors
186
188 libexplain version 1.4
189 Copyright (C) 2010 Peter Miller
190 explain_printf(3)