1explain_fread(3) Library Functions Manual explain_fread(3)
2
6 explain_fread - explain fread(3) errors
7
9 #include <libexplain/fread.h>
10 const char *explain_fread(void *ptr, size_t size, size_t nmemb, FILE
11 *fp);
12 const char *explain_errno_fread(int errnum, void *ptr, size_t size,
13 size_t nmemb, FILE *fp);
14 void explain_message_fread(char *message, int message_size, void *ptr,
15 size_t size, size_t nmemb, FILE *fp);
16 void explain_message_errno_fread(char *message, int message_size, int
17 errnum, 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 fread(3) system call.
22 explain_fread
24 const char *explain_fread(void *ptr, size_t size, size_t nmemb, FILE
25 *fp);
26 The explain_fread function is used to obtain an explanation of an error
28 returned by the fread(3) system call. The least the message will con‐
29 tain is the value of strerror(errno), but usually it will do much bet‐
30 ter, 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 size_t how_many = fread(ptr, size, nmemb, fp);
38 if (how_many == 0 && ferror(fp))
39 {
40 fprintf(stderr, "%s\n", explain_fread(ptr, size, nmemb, fp));
41 exit(EXIT_FAILURE);
42 }
43 ptr The original ptr, exactly as passed to the fread(3) system
45 call.
46 size The original size, exactly as passed to the fread(3) system
48 call.
49 nmemb The original nmemb, exactly as passed to the fread(3) system
51 call.
52 fp The original fp, exactly as passed to the fread(3) system 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_fread
66 const char *explain_errno_fread(int errnum, void *ptr, size_t size,
67 size_t nmemb, FILE *fp);
68 The explain_errno_fread function is used to obtain an explanation of an
70 error returned by the fread(3) system call. The least the message will
71 contain is the value of strerror(errnum), but usually it will do much
72 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 size_t how_many = fread(ptr, size, nmemb, fp);
77 if (how_many == 0 && ferror(fp))
78 {
79 int err = errno;
80 fprintf(stderr, "%s\n", explain_errno_fread(err, 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 fread(3) system
91 call.
92 size The original size, exactly as passed to the fread(3) system
94 call.
95 nmemb The original nmemb, exactly as passed to the fread(3) system
97 call.
98 fp The original fp, exactly as passed to the fread(3) system call.
100 Returns:
102 The message explaining the error. This message buffer is
103 shared by all libexplain functions which do not supply a buffer
104 in their argument list. This will be overwritten by the next
105 call to any libexplain function which shares this buffer,
106 including other threads.
107 Note: This function is not thread safe, because it shares a return buf‐
109 fer across all threads, and many other functions in this library.
110 explain_message_fread
112 void explain_message_fread(char *message, int message_size, void *ptr,
113 size_t size, size_t nmemb, FILE *fp);
114 The explain_message_fread function may be used to obtain an explana‐
116 tion of an error returned by the fread(3) system call. The least the
117 message will contain is the value of strerror(errno), but usually it
118 will do much better, and indicate the underlying cause in more detail.
119 The errno global variable will be used to obtain the error value to be
121 decoded.
122 This function is intended to be used in a fashion similar to the fol‐
124 lowing example:
125 size_t how_many = fread(ptr, size, nmemb, fp);
126 if (how_many == 0 && ferror(fp))
127 {
128 char message[3000];
129 explain_message_fread(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 fread(3) system
143 call.
144 size The original size, exactly as passed to the fread(3) system
146 call.
147 nmemb The original nmemb, exactly as passed to the fread(3) system
149 call.
150 fp The original fp, exactly as passed to the fread(3) system call.
152 explain_message_errno_fread
154 void explain_message_errno_fread(char *message, int message_size, int
155 errnum, void *ptr, size_t size, size_t nmemb, FILE *fp);
156 The explain_message_errno_fread function may be used to obtain an
158 explanation of an error returned by the fread(3) system call. The
159 least the message will contain is the value of strerror(errnum), but
160 usually it will do much better, and indicate the underlying cause in
161 more detail.
162 This function is intended to be used in a fashion similar to the fol‐
164 lowing example:
165 size_t how_many = fread(ptr, size, nmemb, fp);
166 if (how_many == 0 && ferror(fp))
167 {
168 int err = errno;
169 char message[3000];
170 explain_message_errno_fread(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 fread(3) system
191 call.
192 size The original size, exactly as passed to the fread(3) system
194 call.
195 nmemb The original nmemb, exactly as passed to the fread(3) system
197 call.
198 fp The original fp, exactly as passed to the fread(3) system call.
200
202 fread(3)
203 binary stream input
204 explain_fread_or_die(3)
206 binary stream input and report errors
207
209 libexplain version 1.4
210 Copyright (C) 2008 Peter Miller
211 explain_fread(3)