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

NAME

6       explain_fread - explain fread(3) errors
7

SYNOPSIS

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

DESCRIPTION

20       These  functions may be used to obtain explanations for errors returned
21       by the fread(3) system call.
22
23   explain_fread
24       const char *explain_fread(void *ptr, size_t size,  size_t  nmemb,  FILE
25       *fp);
26
27       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
32       The errno global variable will be used to obtain the error value to  be
33       decoded.
34
35       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
44       ptr     The original ptr, exactly as  passed  to  the  fread(3)  system
45               call.
46
47       size    The  original  size,  exactly  as passed to the fread(3) system
48               call.
49
50       nmemb   The original nmemb, exactly as passed to  the  fread(3)  system
51               call.
52
53       fp      The original fp, exactly as passed to the fread(3) system call.
54
55       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
62       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
65   explain_errno_fread
66       const char *explain_errno_fread(int errnum,  void  *ptr,  size_t  size,
67       size_t nmemb, FILE *fp);
68
69       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
74       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
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       ptr     The  original  ptr,  exactly  as  passed to the fread(3) system
91               call.
92
93       size    The original size, exactly as passed  to  the  fread(3)  system
94               call.
95
96       nmemb   The  original  nmemb,  exactly as passed to the fread(3) system
97               call.
98
99       fp      The original fp, exactly as passed to the fread(3) system call.
100
101       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
108       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
111   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
115       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
120       The  errno global variable will be used to obtain the error value to be
121       decoded.
122
123       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
134       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
138       message_size
139               The  size  in  bytes  of  the  location  in  which to store the
140               returned message.
141
142       ptr     The original ptr, exactly as  passed  to  the  fread(3)  system
143               call.
144
145       size    The  original  size,  exactly  as passed to the fread(3) system
146               call.
147
148       nmemb   The original nmemb, exactly as passed to  the  fread(3)  system
149               call.
150
151       fp      The original fp, exactly as passed to the fread(3) system call.
152
153   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
157       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
163       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
176       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
180       message_size
181               The  size  in  bytes  of  the  location  in  which to store the
182               returned message.
183
184       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
190       ptr     The original ptr, exactly as  passed  to  the  fread(3)  system
191               call.
192
193       size    The  original  size,  exactly  as passed to the fread(3) system
194               call.
195
196       nmemb   The original nmemb, exactly as passed to  the  fread(3)  system
197               call.
198
199       fp      The original fp, exactly as passed to the fread(3) system call.
200

SEE ALSO

202       fread(3)
203               binary stream input
204
205       explain_fread_or_die(3)
206               binary stream input and report errors
207
209       libexplain version 0.40
210       Copyright (C) 2008 Peter Miller
211
212
213
214                                                              explain_fread(3)
Impressum