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

NAME

6       explain_vfprintf - explain vfprintf(3) errors
7

SYNOPSIS

9       #include <libexplain/vfprintf.h>
10       const char *explain_vfprintf(FILE *fp, const char *format, va_list ap);
11       const char *explain_errno_vfprintf(int errnum, FILE *fp, const char
12       *format, va_list ap);
13       void explain_message_vfprintf(char *message, int message_size, FILE
14       *fp, const char *format, va_list ap);
15       void explain_message_errno_vfprintf(char *message, int message_size,
16       int errnum, FILE *fp, const char *format, va_list ap);
17

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the vfprintf(3) system call.
21
22   explain_vfprintf
23       const char *explain_vfprintf(FILE *fp, const char *format, va_list ap);
24
25       The  explain_vfprintf  function  is used to obtain an explanation of an
26       error returned by the vfprintf(3) system call. The  least  the  message
27       will  contain  is  the value of strerror(errno), but usually it will do
28       much better, and indicate the underlying cause in more detail.
29
30       The errno global variable will be used to obtain the error value to  be
31       decoded.
32
33       fp      The  original  fp,  exactly as passed to the vfprintf(3) system
34               call.
35
36       format  The original format, exactly as passed to the vfprintf(3)  sys‐
37               tem call.
38
39       ap      The  original  ap,  exactly as passed to the vfprintf(3) system
40               call.
41
42       Returns:
43               The message explaining the error. This message buffer is shared
44               by  all  libexplain  functions  which do not supply a buffer in
45               their argument list.  This will be overwritten by the next call
46               to  any libexplain function which shares this buffer, including
47               other threads.
48
49       Note: This function is not thread safe, because it shares a return buf‐
50       fer across all threads, and many other functions in this library.
51
52       Example:  This  function is intended to be used in a fashion similar to
53       the following example:
54              errno = EINVAL; if (vfprintf(fp, format, ap) < 0)
55              {
56                  fprintf(stderr, "%s\n", explain_vfprintf(fp, format, ap));
57                  exit(EXIT_FAILURE);
58              }
59
60       The   above   code   example   is   available   pre‐packaged   as   the
61       explain_vfprintf_or_die(3) function.
62
63   explain_errno_vfprintf
64       const char *explain_errno_vfprintf(int errnum, FILE *fp, const char
65       *format, va_list ap);
66
67       The explain_errno_vfprintf function is used to obtain an explanation of
68       an  error  returned by the vfprintf(3) system call.  The least the mes‐
69       sage will contain is the value of strerror(errno), but usually it  will
70       do much better, and indicate the underlying cause in more detail.
71
72       errnum  The  error value to be decoded, usually obtained from the errno
73               global variable just before this function is  called.  This  is
74               necessary  if you need to call any code between the system call
75               to be explained and this function, because many libc  functions
76               will alter the value of errno.
77
78       fp      The  original  fp,  exactly as passed to the vfprintf(3) system
79               call.
80
81       format  The original format, exactly as passed to the vfprintf(3)  sys‐
82               tem call.
83
84       ap      The  original  ap,  exactly as passed to the vfprintf(3) system
85               call.
86
87       Returns:
88               The message explaining the error. This message buffer is shared
89               by  all  libexplain  functions  which do not supply a buffer in
90               their argument list.  This will be overwritten by the next call
91               to  any libexplain function which shares this buffer, including
92               other threads.
93
94       Note: This function is not thread safe, because it shares a return buf‐
95       fer across all threads, and many other functions in this library.
96
97       Example:  This  function is intended to be used in a fashion similar to
98       the following example:
99              errno = EINVAL; if (vfprintf(fp, format, ap) < 0)
100              {
101                  int err = errno;
102                  fprintf(stderr, "%s\n", explain_errno_vfprintf(err, fp, for‐
103                  mat, ap));
104                  exit(EXIT_FAILURE);
105              }
106
107       The   above   code   example   is   available   pre‐packaged   as   the
108       explain_vfprintf_or_die(3) function.
109
110   explain_message_vfprintf
111       void explain_message_vfprintf(char *message, int message_size, FILE
112       *fp, const char *format, va_list ap);
113
114       The  explain_message_vfprintf function is used to obtain an explanation
115       of an error returned by the vfprintf(3) system  call.   The  least  the
116       message  will  contain  is the value of strerror(errno), but usually it
117       will do much better, and indicate the underlying cause in more detail.
118
119       The errno global variable will be used to obtain the error value to  be
120       decoded.
121
122       message The location in which to store the returned message. If a suit‐
123               able message return buffer is supplied, this function is thread
124               safe.
125
126       message_size
127               The  size  in  bytes  of  the  location  in  which to store the
128               returned message.
129
130       fp      The original fp, exactly as passed to  the  vfprintf(3)  system
131               call.
132
133       format  The  original format, exactly as passed to the vfprintf(3) sys‐
134               tem call.
135
136       ap      The original ap, exactly as passed to  the  vfprintf(3)  system
137               call.
138
139       Example:  This  function is intended to be used in a fashion similar to
140       the following example:
141              errno = EINVAL; if (vfprintf(fp, format, ap) < 0)
142              {
143                  char message[3000];
144                  explain_message_vfprintf(message, sizeof(message), fp, for‐
145                  mat, ap);
146                  fprintf(stderr, "%s\n", message);
147                  exit(EXIT_FAILURE);
148              }
149
150       The   above   code   example   is   available   pre‐packaged   as   the
151       explain_vfprintf_or_die(3) function.
152
153   explain_message_errno_vfprintf
154       void explain_message_errno_vfprintf(char *message, int message_size,
155       int errnum, FILE *fp, const char *format, va_list ap);
156
157       The explain_message_errno_vfprintf function is used to obtain an expla‐
158       nation of an error returned by the vfprintf(3) system call.  The  least
159       the  message  will contain is the value of strerror(errno), but usually
160       it will do much better, and  indicate  the  underlying  cause  in  more
161       detail.
162
163       message The location in which to store the returned message. If a suit‐
164               able message return buffer is supplied, this function is thread
165               safe.
166
167       message_size
168               The  size  in  bytes  of  the  location  in  which to store the
169               returned message.
170
171       errnum  The error value to be decoded, usually obtained from the  errno
172               global  variable  just  before this function is called. This is
173               necessary if you need to call any code between the system  call
174               to  be explained and this function, because many libc functions
175               will alter the value of errno.
176
177       fp      The original fp, exactly as passed to  the  vfprintf(3)  system
178               call.
179
180       format  The  original format, exactly as passed to the vfprintf(3) sys‐
181               tem call.
182
183       ap      The original ap, exactly as passed to  the  vfprintf(3)  system
184               call.
185
186       Example:  This  function is intended to be used in a fashion similar to
187       the following example:
188              errno = EINVAL; if (vfprintf(fp, format, ap) < 0)
189              {
190                  int err = errno;
191                  char message[3000];
192                  explain_message_errno_vfprintf(message, sizeof(message),
193                  err, fp, format, ap);
194                  fprintf(stderr, "%s\n", message);
195                  exit(EXIT_FAILURE);
196              }
197
198       The   above   code   example   is   available   pre‐packaged   as   the
199       explain_vfprintf_or_die(3) function.
200

SEE ALSO

202       vfprintf(3)
203               formatted output conversion
204
205       explain_vfprintf_or_die(3)
206               formatted output conversion and report errors
207
209       libexplain version 0.40
210       Copyright (C) 2010 Peter Miller
211
212
213
214                                                           explain_vfprintf(3)
Impressum