1explain_fwrite(3) Library Functions Manual explain_fwrite(3)
2
6 explain_fwrite - explain fwrite(3) errors
7
9 #include <libexplain/fwrite.h>
10 const char *explain_fwrite(const void *ptr, size_t size, size_t nmemb,
11 FILE *fp);
12 const char *explain_errno_fwrite(int errnum, const void *ptr, size_t
13 size, size_t nmemb, FILE *fp);
14 void explain_message_fwrite(char *message, int message_size, const void
15 *ptr, size_t size, size_t nmemb, FILE *fp);
16 void explain_message_errno_fwrite(char *message, int message_size, int
17 errnum, const void *ptr, size_t size, size_t nmemb, FILE *fp);
18
20 These functions may be used to obtain explanations for errors returned
21 by the fwrite(3) system call.
22 explain_fwrite
24 const char *explain_fwrite(const void *ptr, size_t size, size_t nmemb,
25 FILE *fp);
26 The explain_fwrite function is used to obtain an explanation of an
28 error returned by the fwrite(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 This function is intended to be used in a fashion similar to the fol‐
36 lowing example:
37 if (fwrite(ptr, size, nmemb, fp) < 0)
38 {
39 fprintf(stderr, "%s\n", explain_fwrite(ptr, size, nmemb, fp));
40 exit(EXIT_FAILURE);
41 }
42 ptr The original ptr, exactly as passed to the fwrite(3) system
44 call.
45 size The original size, exactly as passed to the fwrite(3) system
47 call.
48 nmemb The original nmemb, exactly as passed to the fwrite(3) system
50 call.
51 fp The original fp, exactly as passed to the fwrite(3) system
53 call.
54 Returns:
56 The message explaining the error. This message buffer is
57 shared by all libexplain functions which do not supply a buffer
58 in their argument list. This will be overwritten by the next
59 call to any libexplain function which shares this buffer,
60 including other threads.
61 Note: This function is not thread safe, because it shares a return buf‐
63 fer across all threads, and many other functions in this library.
64 explain_errno_fwrite
66 const char *explain_errno_fwrite(int errnum, const void *ptr, size_t
67 size, size_t nmemb, FILE *fp);
68 The explain_errno_fwrite function is used to obtain an explanation of
70 an error returned by the fwrite(3) system call. The least the message
71 will contain is the value of strerror(errnum), but usually it will do
72 much better, and indicate the underlying cause in more detail.
73 This function is intended to be used in a fashion similar to the fol‐
75 lowing example:
76 if (fwrite(ptr, size, nmemb, fp) < 0)
77 {
78 int err = errno;
79 fprintf(stderr, "%s\n", explain_errno_fwrite(err,
80 ptr, size, nmemb, fp));
81 exit(EXIT_FAILURE);
82 }
83 errnum The error value to be decoded, usually obtained from the errno
85 global variable just before this function is called. This is
86 necessary if you need to call any code between the system call
87 to be explained and this function, because many libc functions
88 will alter the value of errno.
89 ptr The original ptr, exactly as passed to the fwrite(3) system
91 call.
92 size The original size, exactly as passed to the fwrite(3) system
94 call.
95 nmemb The original nmemb, exactly as passed to the fwrite(3) system
97 call.
98 fp The original fp, exactly as passed to the fwrite(3) system
100 call.
101 Returns:
103 The message explaining the error. This message buffer is
104 shared by all libexplain functions which do not supply a buffer
105 in their argument list. This will be overwritten by the next
106 call to any libexplain function which shares this buffer,
107 including other threads.
108 Note: This function is not thread safe, because it shares a return buf‐
110 fer across all threads, and many other functions in this library.
111 explain_message_fwrite
113 void explain_message_fwrite(char *message, int message_size, const void
114 *ptr, size_t size, size_t nmemb, FILE *fp);
115 The explain_message_fwrite function may be used to obtain an explana‐
117 tion of an error returned by the fwrite(3) system call. The least the
118 message will contain is the value of strerror(errno), but usually it
119 will do much better, and indicate the underlying cause in more detail.
120 The errno global variable will be used to obtain the error value to be
122 decoded.
123 This function is intended to be used in a fashion similar to the fol‐
125 lowing example:
126 if (fwrite(ptr, size, nmemb, fp) < 0)
127 {
128 char message[3000];
129 explain_message_fwrite(message, sizeof(message), ptr, size, nmemb, fp);
130 fprintf(stderr, "%s\n", message);
131 exit(EXIT_FAILURE);
132 }
133 message The location in which to store the returned message. If a
135 suitable message return buffer is supplied, this function is
136 thread safe.
137 message_size
139 The size in bytes of the location in which to store the
140 returned message.
141 ptr The original ptr, exactly as passed to the fwrite(3) system
143 call.
144 size The original size, exactly as passed to the fwrite(3) system
146 call.
147 nmemb The original nmemb, exactly as passed to the fwrite(3) system
149 call.
150 fp The original fp, exactly as passed to the fwrite(3) system
152 call.
153 explain_message_errno_fwrite
155 void explain_message_errno_fwrite(char *message, int message_size, int
156 errnum, const void *ptr, size_t size, size_t nmemb, FILE *fp);
157 The explain_message_errno_fwrite function may be used to obtain an
159 explanation of an error returned by the fwrite(3) system call. The
160 least the message will contain is the value of strerror(errnum), but
161 usually it will do much better, and indicate the underlying cause in
162 more detail.
163 This function is intended to be used in a fashion similar to the fol‐
165 lowing example:
166 if (fwrite(ptr, size, nmemb, fp) < 0)
167 {
168 int err = errno;
169 char message[3000];
170 explain_message_errno_fwrite(message, sizeof(message), err,
171 ptr, size, nmemb, fp);
172 fprintf(stderr, "%s\n", message);
173 exit(EXIT_FAILURE);
174 }
175 message The location in which to store the returned message. If a
177 suitable message return buffer is supplied, this function is
178 thread safe.
179 message_size
181 The size in bytes of the location in which to store the
182 returned message.
183 errnum The error value to be decoded, usually obtained from the errno
185 global variable just before this function is called. This is
186 necessary if you need to call any code between the system call
187 to be explained and this function, because many libc functions
188 will alter the value of errno.
189 ptr The original ptr, exactly as passed to the fwrite(3) system
191 call.
192 size The original size, exactly as passed to the fwrite(3) system
194 call.
195 nmemb The original nmemb, exactly as passed to the fwrite(3) system
197 call.
198 fp The original fp, exactly as passed to the fwrite(3) system
200 call.
201
203 fwrite(3)
204 binary stream output
205 explain_fwrite_or_die(3)
207 binary stream output and report errors
208
210 libexplain version 0.40
211 Copyright (C) 2008 Peter Miller
212 explain_fwrite(3)