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

NAME

6       explain_fwrite - explain fwrite(3) errors
7

SYNOPSIS

9       #include <libexplain/fwrite.h>
10       const  char *explain_fwrite(const void *ptr, size_t size, size_t nmemb,
11       FILE *fp);
12       const char *explain_errno_fwrite(int errnum, const  void  *ptr,  size_t
13       size, size_t nmemb, FILE *fp);
14       void explain_message_fwrite(char *message, int message_size, const void
15       *ptr, size_t size, size_t nmemb, FILE *fp);
16       void explain_message_errno_fwrite(char *message, int message_size,  int
17       errnum, const 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 fwrite(3) system call.
22
23   explain_fwrite
24       const char *explain_fwrite(const void *ptr, size_t size, size_t  nmemb,
25       FILE *fp);
26
27       The  explain_fwrite  function  is  used  to obtain an explanation of an
28       error returned by the fwrite(3) system call.   The  least  the  message
29       will  contain  is  the value of strerror(errno), but usually it will do
30       much better, 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              if (fwrite(ptr, size, nmemb, fp) < 0)
38              {
39                  fprintf(stderr, "%s\n", explain_fwrite(ptr, size, nmemb, fp));
40                  exit(EXIT_FAILURE);
41              }
42
43       ptr     The original ptr, exactly as passed  to  the  fwrite(3)  system
44               call.
45
46       size    The  original  size,  exactly as passed to the fwrite(3) system
47               call.
48
49       nmemb   The original nmemb, exactly as passed to the  fwrite(3)  system
50               call.
51
52       fp      The  original  fp,  exactly  as  passed to the fwrite(3) system
53               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_fwrite
66       const  char  *explain_errno_fwrite(int  errnum, const void *ptr, size_t
67       size, size_t nmemb, FILE *fp);
68
69       The explain_errno_fwrite function is used to obtain an  explanation  of
70       an  error returned by the fwrite(3) system call.  The least the message
71       will contain is the value of strerror(errnum), but usually it  will  do
72       much 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              if (fwrite(ptr, size, nmemb, fp) < 0)
77              {
78                  int err = errno;
79                  fprintf(stderr, "%s\n", explain_errno_fwrite(err,
80                      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  fwrite(3)  system
91               call.
92
93       size    The  original  size,  exactly as passed to the fwrite(3) system
94               call.
95
96       nmemb   The original nmemb, exactly as passed to the  fwrite(3)  system
97               call.
98
99       fp      The  original  fp,  exactly  as  passed to the fwrite(3) system
100               call.
101
102       Returns:
103               The message explaining  the  error.   This  message  buffer  is
104               shared by all libexplain functions which do not supply a buffer
105               in their argument list.  This will be overwritten by  the  next
106               call  to  any  libexplain  function  which  shares this buffer,
107               including other threads.
108
109       Note: This function is not thread safe, because it shares a return buf‐
110       fer across all threads, and many other functions in this library.
111
112   explain_message_fwrite
113       void explain_message_fwrite(char *message, int message_size, const void
114       *ptr, size_t size, size_t nmemb, FILE *fp);
115
116       The explain_message_fwrite function may be used to  obtain an  explana‐
117       tion  of an error returned by the fwrite(3) system call.  The least the
118       message will contain is the value of strerror(errno),  but  usually  it
119       will do much better, and indicate the underlying cause in more detail.
120
121       The  errno global variable will be used to obtain the error value to be
122       decoded.
123
124       This function is intended to be used in a fashion similar to  the  fol‐
125       lowing example:
126              if (fwrite(ptr, size, nmemb, fp) < 0)
127              {
128                  char message[3000];
129                  explain_message_fwrite(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  fwrite(3)  system
143               call.
144
145       size    The  original  size,  exactly as passed to the fwrite(3) system
146               call.
147
148       nmemb   The original nmemb, exactly as passed to the  fwrite(3)  system
149               call.
150
151       fp      The  original  fp,  exactly  as  passed to the fwrite(3) system
152               call.
153
154   explain_message_errno_fwrite
155       void explain_message_errno_fwrite(char *message, int message_size,  int
156       errnum, const void *ptr, size_t size, size_t nmemb, FILE *fp);
157
158       The  explain_message_errno_fwrite  function  may  be  used to obtain an
159       explanation of an error returned by the  fwrite(3)  system  call.   The
160       least  the  message  will contain is the value of strerror(errnum), but
161       usually it will do much better, and indicate the  underlying  cause  in
162       more detail.
163
164       This  function  is intended to be used in a fashion similar to the fol‐
165       lowing example:
166              if (fwrite(ptr, size, nmemb, fp) < 0)
167              {
168                  int err = errno;
169                  char message[3000];
170                  explain_message_errno_fwrite(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 fwrite(3) system
191               call.
192
193       size    The original size, exactly as passed to  the  fwrite(3)  system
194               call.
195
196       nmemb   The  original  nmemb, exactly as passed to the fwrite(3) system
197               call.
198
199       fp      The original fp, exactly as  passed  to  the  fwrite(3)  system
200               call.
201

SEE ALSO

203       fwrite(3)
204               binary stream output
205
206       explain_fwrite_or_die(3)
207               binary stream output and report errors
208
210       libexplain version 1.4
211       Copyright (C) 2008 Peter Miller
212
213
214
215                                                             explain_fwrite(3)
Impressum