1explain_fclose(3) Library Functions Manual explain_fclose(3)
2
6 explain_fclose - explain fclose(3) errors
7
9 #include <libexplain/fclose.h>
10 const char *explain_fclose(FILE *fp);
11 const char *explain_errno_fclose(int errnum, FILE *fp);
12 void explain_message_fclose(char *message, int message_size, FILE *fp);
13 void explain_message_errno_fclose(char *message, int message_size, int
14 errnum, FILE *fp);
15
17 These functions may be used to obtain explanations of fclose(3) errors.
18 explain_fclose
20 const char *explain_fclose(FILE * fp);
21 The explain_fclose function is used to obtain an explanation of an
23 error returned by the fclose(3) function. The least the message will
24 contain is the value of strerror(errno), but usually it will do much
25 better, and indicate the underlying cause in more detail.
26 The errno global variable will be used to obtain the error value to be
28 decoded.
29 This function is intended to be used in a fashion similar to the fol‐
31 lowing example:
32 if (fclose(fp))
33 {
34 fprintf(stderr, "%s\n", explain_fclose(fp));
35 exit(EXIT_FAILURE);
36 }
37 fp The original fp, exactly as passed to the fclose(3) system
39 call.
40 Returns:
42 The message explaining the error. This message buffer is
43 shared by all libexplain functions which do not supply a buffer
44 in their argument list. This will be overwritten by the next
45 call to any libexplain function which shares this buffer,
46 including other threads.
47 Note: This function is not thread safe, because it shares a return buf‐
49 fer across all threads, and many other functions in this library.
50 Note: This function may be of little diagnostic value, because libc may
52 have destroyed any useful context, leaving nothing for libexplain to
53 work with (this is true of glibc in particular). For files that are
54 open for writing, you will obtain more useful information by first
55 calling fflush(3), as in the following example
56 if (fflush(fp))
57 {
58 fprintf(stderr, "%s\n", explain_fflush(fp));
59 exit(EXIT_FAILURE);
60 }
61 if (fclose(fp))
62 {
63 fprintf(stderr, "%s\n", explain_fclose(fp));
64 exit(EXIT_FAILURE);
65 }
66 explain_errno_fclose
68 const char *explain_errno_fclose(int errnum, FILE * fp);
69 The explain_errno_fclose function is used to obtain an explanation of
71 an error returned by the fclose(3) function. The least the message
72 will contain is the value of strerror(errnum), but usually it will do
73 much better, and indicate the underlying cause in more detail.
74 This function is intended to be used in a fashion similar to the fol‐
76 lowing example:
77 if (fclose(fp))
78 {
79 int err = errno;
80 fprintf(stderr, "%s\n", explain_errno_fclose(err, 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 fp The original fp, exactly as passed to the fclose(3) system
91 call.
92 Returns:
94 The message explaining the error. This message buffer is
95 shared by all libexplain functions which do not supply a buffer
96 in their argument list. This will be overwritten by the next
97 call to any libexplain function which shares this buffer,
98 including other threads.
99 Note: This function is not thread safe, because it shares a return buf‐
101 fer across all threads, and many other functions in this library.
102 Note: This function may be of little diagnostic value, because libc may
104 have destroyed any useful context, leaving nothing for libexplain to
105 work with (this is true of glibc in particular). For files that are
106 open for writing, you will obtain more useful information by first
107 calling fflush(3), as in the following example
108 if (fflush(fp))
109 {
110 int err = errno;
111 fprintf(stderr, "%s\n", explain_errno_fflush(err, fp));
112 exit(EXIT_FAILURE);
113 }
114 if (fclose(fp))
115 {
116 int err = errno;
117 fprintf(stderr, "%s\n", explain_errno_fclose(err, fp));
118 exit(EXIT_FAILURE);
119 }
120 explain_message_fclose
122 void explain_message_fclose(char *message, int message_size, FILE *fp);
123 The explain_message_fclose function is used to obtain an explanation of
125 an error returned by the fclose(3) function. The least the message
126 will contain is the value of strerror(errno), but usually it will do
127 much better, and indicate the underlying cause in more detail.
128 The errno global variable will be used to obtain the error value to be
130 decoded.
131 This function is intended to be used in a fashion similar to the fol‐
133 lowing example:
134 if (fclose(fp))
135 {
136 char message[3000];
137 explain_message_fclose(message, sizeof(message), fp);
138 fprintf(stderr, "%s\n", message);
139 exit(EXIT_FAILURE);
140 }
141 message The location in which to store the returned message. Because a
143 message return buffer has been supplied, this function is
144 thread safe.
145 message_size
147 The size in bytes of the location in which to store the
148 returned message.
149 fp The original fp, exactly as passed to the fclose(3) system
151 call.
152 Note: This function may be of little diagnostic value, because libc may
154 have destroyed any useful context, leaving nothing for libexplain to
155 work with (this is true of glibc in particular). For files that are
156 open for writing, you will obtain more useful information by first
157 calling fflush(3), as in the following example
158 if (fflush(fp))
159 {
160 char message[3000];
161 explain_message_fflush(message, sizeof(message), fp);
162 fprintf(stderr, "%s\n", message);
163 exit(EXIT_FAILURE);
164 }
165 if (fclose(fp))
166 {
167 char message[3000];
168 explain_message_fclose(message, sizeof(message), fp);
169 fprintf(stderr, "%s\n", message);
170 exit(EXIT_FAILURE);
171 }
172 explain_message_errno_fclose
174 void explain_message_errno_fclose(char *message, int message_size, int
175 errnum, FILE *fp);
176 The explain_message_errno_fclose function is used to obtain an explana‐
178 tion of an error returned by the fclose(3) function. The least the
179 message will contain is the value of strerror(errnum), but usually it
180 will do much better, and indicate the underlying cause in more detail.
181 This function is intended to be used in a fashion similar to the fol‐
183 lowing exameple:
184 if (fclose(fp))
185 {
186 int err = errno;
187 char message[3000];
188 explain_message_errno_fclose(message, sizeof(message),
189 err, fp);
190 fprintf(stderr, "%s\n", message);
191 exit(EXIT_FAILURE);
192 }
193 message The location in which to store the returned message. Because a
195 message return buffer has been supplied, this function is
196 thread safe.
197 message_size
199 The size in bytes of the location in which to store the
200 returned message.
201 errnum The error value to be decoded, usually obtained from the errno
203 global variable just before this function is called. This is
204 necessary if you need to call any code between the system call
205 to be explained and this function, because many libc functions
206 will alter the value of errno.
207 fp The original fp, exactly as passed to the fclose(3) system
209 call.
210 Note: This function may be of little diagnostic value, because libc may
212 have destroyed any useful context, leaving nothing for libexplain to
213 work with (this is true of glibc in particular). For files that are
214 open for writing, you will obtain more useful information by first
215 calling fflush(3), as in the following example
216 if (fflush(fp))
217 {
218 int err = errno;
219 char message[3000];
220 explain_message_errno_fflush(message, sizeof(message),
221 err, fp);
222 fprintf(stderr, "%s\n", message);
223 exit(EXIT_FAILURE);
224 }
225 if (fclose(fp))
226 {
227 int err = errno;
228 char message[3000];
229 explain_message_errno_fclose(message, sizeof(message),
230 err, fp);
231 fprintf(stderr, "%s\n", message);
232 exit(EXIT_FAILURE);
233 }
234
236 libexplain version 1.4
237 Copyright (C) 2008 Peter Miller
238
240 Written by Peter Miller <pmiller@opensource.org.au>
241 explain_fclose(3)