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

NAME

6       explain_fclose - explain fclose(3) errors
7

SYNOPSIS

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

DESCRIPTION

17       These functions may be used to obtain explanations of fclose(3) errors.
18
19   explain_fclose
20       const char *explain_fclose(FILE * fp);
21
22       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
27       The  errno global variable will be used to obtain the error value to be
28       decoded.
29
30       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
38       fp      The  original  fp,  exactly  as  passed to the fclose(3) system
39               call.
40
41       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
48       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
51       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
67   explain_errno_fclose
68       const char *explain_errno_fclose(int errnum, FILE * fp);
69
70       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
75       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
84       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
90       fp      The  original  fp,  exactly  as  passed to the fclose(3) system
91               call.
92
93       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
100       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
103       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
121   explain_message_fclose
122       void explain_message_fclose(char *message, int message_size, FILE *fp);
123
124       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
129       The errno global variable will be used to obtain the error value to  be
130       decoded.
131
132       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
142       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
146       message_size
147               The size in bytes  of  the  location  in  which  to  store  the
148               returned message.
149
150       fp      The  original  fp,  exactly  as  passed to the fclose(3) system
151               call.
152
153       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
173   explain_message_errno_fclose
174       void explain_message_errno_fclose(char *message, int message_size,  int
175       errnum, FILE *fp);
176
177       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
182       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
194       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
198       message_size
199               The  size  in  bytes  of  the  location  in  which to store the
200               returned message.
201
202       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
208       fp      The original fp, exactly as  passed  to  the  fclose(3)  system
209               call.
210
211       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 0.40
237       Copyright (C) 2008 Peter Miller
238

AUTHOR

240       Written by Peter Miller <pmiller@opensource.org.au>
241
242
243
244                                                             explain_fclose(3)
Impressum