1explain_ferror(3) Library Functions Manual explain_ferror(3)
2
6 explain_ferror - explain ferror(3) errors
7
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
17 These functions may be used to obtain explanations for errors returned
18 by the ferror(3) system call.
19 explain_ferror
21 const char *explain_ferror(FILE *fp);
22 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 The errno global variable will be used to obtain the error value to be
29 decoded.
30 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 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 fp The original fp, exactly as passed to the ferror(3) system
44 call.
45 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 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 explain_errno_ferror
57 const char *explain_errno_ferror(int errnum, FILE *fp);
58 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 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 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 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 fp The original fp, exactly as passed to the ferror(3) system
84 call.
85 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 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 explain_message_ferror
97 void explain_message_ferror(char *message, int message_size, FILE *fp);
98 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 The errno global variable will be used to obtain the error value to be
105 decoded.
106 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 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 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 message_size
126 The size in bytes of the location in which to store the
127 returned message.
128 fp The original fp, exactly as passed to the ferror(3) system
130 call.
131 explain_message_errno_ferror
133 void explain_message_errno_ferror(char *message, int message_size, int
134 errnum, FILE *fp);
135 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 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 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 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 message_size
162 The size in bytes of the location in which to store the
163 returned message.
164 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 fp The original fp, exactly as passed to the ferror(3) system
172 call.
173
175 ferror(3)
176 check stream status
177 explain_ferror_or_die(3)
179 check stream status and report errors
180
182 libexplain version 1.4
183 Copyright (C) 2008 Peter Miller
184 explain_ferror(3)