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

NAME

6       explain_ferror - explain ferror(3) errors
7

SYNOPSIS

9       #include <libexplain/ferror.h>
10       const char *explain_ferror(FILE *fp);
11       const char *explain_errno_ferror(int errnum, FILE *fp);
12       void explain_message_ferror(char *message, int message_size, FILE *fp);
13       void  explain_message_errno_ferror(char *message, int message_size, int
14       errnum, FILE *fp);
15

DESCRIPTION

17       These functions may be used to obtain explanations for errors  returned
18       by the ferror(3) system call.
19
20   explain_ferror
21       const char *explain_ferror(FILE *fp);
22
23       The  explain_ferror  function  is  used  to obtain an explanation of an
24       error returned by the ferror(3) system call.   The  least  the  message
25       will  contain  is  the value of strerror(errno), but usually it will do
26       much better, and indicate the underlying cause in more detail.
27
28       The errno global variable will be used to obtain the error value to  be
29       decoded.
30
31       This  function  is intended to be used in a fashion similar to the fol‐
32       lowing example:
33              if (ferror(fp) < 0)
34              {
35                  fprintf(stderr, "%s\n", explain_ferror(fp));
36                  exit(EXIT_FAILURE);
37              }
38
39       It is essential that this function cal be placed as close  as  possible
40       to the I/O code that has caused the problem, otherwise intervening code
41       could have altered the errno global variable.
42
43       fp      The original fp, exactly as  passed  to  the  ferror(3)  system
44               call.
45
46       Returns:
47               The  message  explaining  the  error.   This  message buffer is
48               shared by all libexplain functions which do not supply a buffer
49               in  their  argument list.  This will be overwritten by the next
50               call to any  libexplain  function  which  shares  this  buffer,
51               including other threads.
52
53       Note: This function is not thread safe, because it shares a return buf‐
54       fer across all threads, and many other functions in this library.
55
56   explain_errno_ferror
57       const char *explain_errno_ferror(int errnum, FILE *fp);
58
59       The explain_errno_ferror function is used to obtain an  explanation  of
60       an  error returned by the ferror(3) system call.  The least the message
61       will contain is the value of strerror(errnum), but usually it  will  do
62       much better, and indicate the underlying cause in more detail.
63
64       This  function  is intended to be used in a fashion similar to the fol‐
65       lowing example:
66              if (ferror(fp) < 0)
67              {
68                  int err = errno;
69                  fprintf(stderr, "%s\n", explain_errno_ferror(err, fp));
70                  exit(EXIT_FAILURE);
71              }
72
73       It is essential that this function cal be placed as close  as  possible
74       to the I/O code that has caused the problem, otherwise intervening code
75       could have altered the errno global variable.
76
77       errnum  The error value to be decoded, usually obtained from the  errno
78               global  variable  just before this function is called.  This is
79               necessary if you need to call any code between the system  call
80               to  be explained and this function, because many libc functions
81               will alter the value of errno.
82
83       fp      The original fp, exactly as  passed  to  the  ferror(3)  system
84               call.
85
86       Returns:
87               The  message  explaining  the  error.   This  message buffer is
88               shared by all libexplain functions which do not supply a buffer
89               in  their  argument list.  This will be overwritten by the next
90               call to any  libexplain  function  which  shares  this  buffer,
91               including other threads.
92
93       Note: This function is not thread safe, because it shares a return buf‐
94       fer across all threads, and many other functions in this library.
95
96   explain_message_ferror
97       void explain_message_ferror(char *message, int message_size, FILE *fp);
98
99       The explain_message_ferror function may be used to  obtain an  explana‐
100       tion  of an error returned by the ferror(3) system call.  The least the
101       message will contain is the value of strerror(errno),  but  usually  it
102       will do much better, and indicate the underlying cause in more detail.
103
104       The  errno global variable will be used to obtain the error value to be
105       decoded.
106
107       This function is intended to be used in a fashion similar to  the  fol‐
108       lowing example:
109              if (ferror(fp) < 0)
110              {
111                  char message[3000];
112                  explain_message_ferror(message, sizeof(message), fp);
113                  fprintf(stderr, "%s\n", message);
114                  exit(EXIT_FAILURE);
115              }
116
117       It  is  essential that this function cal be placed as close as possible
118       to the I/O code that has caused the problem, otherwise intervening code
119       could have altered the errno global variable.
120
121       message The  location  in  which  to  store the returned message.  If a
122               suitable message return buffer is supplied,  this  function  is
123               thread safe.
124
125       message_size
126               The  size  in  bytes  of  the  location  in  which to store the
127               returned message.
128
129       fp      The original fp, exactly as  passed  to  the  ferror(3)  system
130               call.
131
132   explain_message_errno_ferror
133       void  explain_message_errno_ferror(char *message, int message_size, int
134       errnum, FILE *fp);
135
136       The explain_message_errno_ferror function may  be  used  to  obtain  an
137       explanation  of  an  error  returned by the ferror(3) system call.  The
138       least the message will contain is the value  of  strerror(errnum),  but
139       usually  it  will  do much better, and indicate the underlying cause in
140       more detail.
141
142       This function is intended to be used in a fashion similar to  the  fol‐
143       lowing example:
144              if (ferror(fp) < 0)
145              {
146                  int err = errno;
147                  char message[3000];
148                  explain_message_errno_ferror(message, sizeof(message), err, fp);
149                  fprintf(stderr, "%s\n", message);
150                  exit(EXIT_FAILURE);
151              }
152
153       It  is  essential that this function cal be placed as close as possible
154       to the I/O code that has caused the problem, otherwise intervening code
155       could have altered the errno global variable.
156
157       message The  location  in  which  to  store the returned message.  If a
158               suitable message return buffer is supplied,  this  function  is
159               thread safe.
160
161       message_size
162               The  size  in  bytes  of  the  location  in  which to store the
163               returned message.
164
165       errnum  The error value to be decoded, usually obtained from the  errno
166               global  variable  just before this function is called.  This is
167               necessary if you need to call any code between the system  call
168               to  be explained and this function, because many libc functions
169               will alter the value of errno.
170
171       fp      The original fp, exactly as  passed  to  the  ferror(3)  system
172               call.
173

SEE ALSO

175       ferror(3)
176               check stream status
177
178       explain_ferror_or_die(3)
179               check stream status and report errors
180
182       libexplain version 0.40
183       Copyright (C) 2008 Peter Miller
184
185
186
187                                                             explain_ferror(3)
Impressum