1explain_printf(3)          Library Functions Manual          explain_printf(3)
2
3
4

NAME

6       explain_printf - explain printf(3) errors
7

SYNOPSIS

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

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the printf(3) system call.
20
21   explain_printf
22       const char *explain_printf(const char *format);
23
24       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
29       The  errno global variable will be used to obtain the error value to be
30       decoded.
31
32       format  The original format, exactly as passed to the printf(3)  system
33               call.
34
35       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
42       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
45       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
55       The   above   code   example   is   available   pre‐packaged   as   the
56       explain_printf_or_die(3) function.
57
58   explain_errno_printf
59       const char *explain_errno_printf(int errnum, const char *format);
60
61       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
66       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
72       format  The  original format, exactly as passed to the printf(3) system
73               call.
74
75       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
82       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
85       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
96       The   above   code   example   is   available   pre‐packaged   as   the
97       explain_printf_or_die(3) function.
98
99   explain_message_printf
100       void explain_message_printf(char *message, int message_size, const char
101       *format);
102
103       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
108       The  errno global variable will be used to obtain the error value to be
109       decoded.
110
111       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
115       message_size
116               The size in bytes  of  the  location  in  which  to  store  the
117               returned message.
118
119       format  The  original format, exactly as passed to the printf(3) system
120               call.
121
122       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
134       The   above   code   example   is   available   pre‐packaged   as   the
135       explain_printf_or_die(3) function.
136
137   explain_message_errno_printf
138       void explain_message_errno_printf(char *message, int message_size, int
139       errnum, const char *format);
140
141       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
146       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
150       message_size
151               The size in bytes  of  the  location  in  which  to  store  the
152               returned message.
153
154       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
160       format  The  original format, exactly as passed to the printf(3) system
161               call.
162
163       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
177       The   above   code   example   is   available   pre‐packaged   as   the
178       explain_printf_or_die(3) function.
179

SEE ALSO

181       printf(3)
182               formatted output conversion
183
184       explain_printf_or_die(3)
185               formatted output conversion and report errors
186
188       libexplain version 0.40
189       Copyright (C) 2010 Peter Miller
190
191
192
193                                                             explain_printf(3)
Impressum