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

NAME

6       explain_pread - explain pread(2) errors
7

SYNOPSIS

9       #include <libexplain/pread.h>
10       const char *explain_pread(int fildes, void *data, size_t data_size,
11       off_t offset);
12       const char *explain_errno_pread(int errnum, int fildes, void *data,
13       size_t data_size, off_t offset);
14       void explain_message_pread(char *message, int message_size, int fildes,
15       void *data, size_t data_size, off_t offset);
16       void explain_message_errno_pread(char *message, int message_size, int
17       errnum, int fildes, void *data, size_t data_size, off_t offset);
18

DESCRIPTION

20       These  functions may be used to obtain explanations for errors returned
21       by the pread(2) system call.
22
23   explain_pread
24       const char *explain_pread(int fildes, void *data, size_t data_size,
25       off_t offset);
26
27       The explain_pread function is used to obtain an explanation of an error
28       returned by the pread(2) 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       fildes  The  original  fildes, exactly as passed to the pread(2) system
36               call.
37
38       data    The original data, exactly as passed  to  the  pread(2)  system
39               call.
40
41       data_size
42               The  original data_size, exactly as passed to the pread(2) sys‐
43               tem call.
44
45       offset  The original offset, exactly as passed to the  pread(2)  system
46               call.
47
48       Returns:
49               The message explaining the error. This message buffer is shared
50               by all libexplain functions which do not  supply  a  buffer  in
51               their argument list.  This will be overwritten by the next call
52               to any libexplain function which shares this buffer,  including
53               other threads.
54
55       Note: This function is not thread safe, because it shares a return buf‐
56       fer across all threads, and many other functions in this library.
57
58       Example: This function is intended to be used in a fashion  similar  to
59       the following example:
60              ssize_t result = pread(fildes, data, data_size, offset);
61              if (result < 0)
62              {
63                  fprintf(stderr, "%s\n", explain_pread(fildes, data,
64                  data_size, offset));
65                  exit(EXIT_FAILURE);
66              }
67
68       The   above   code   example   is   available   pre‐packaged   as   the
69       explain_pread_or_die(3) function.
70
71   explain_errno_pread
72       const char *explain_errno_pread(int errnum, int fildes, void *data,
73       size_t data_size, off_t offset);
74
75       The explain_errno_pread function is used to obtain an explanation of an
76       error  returned by the pread(2) system call. The least the message will
77       contain is the value of strerror(errno), but usually it  will  do  much
78       better, and indicate the underlying cause in more detail.
79
80       errnum  The  error value to be decoded, usually obtained from the errno
81               global variable just before this function is  called.  This  is
82               necessary  if you need to call any code between the system call
83               to be explained and this function, because many libc  functions
84               will alter the value of errno.
85
86       fildes  The  original  fildes, exactly as passed to the pread(2) system
87               call.
88
89       data    The original data, exactly as passed  to  the  pread(2)  system
90               call.
91
92       data_size
93               The  original data_size, exactly as passed to the pread(2) sys‐
94               tem call.
95
96       offset  The original offset, exactly as passed to the  pread(2)  system
97               call.
98
99       Returns:
100               The message explaining the error. This message buffer is shared
101               by all libexplain functions which do not  supply  a  buffer  in
102               their argument list.  This will be overwritten by the next call
103               to any libexplain function which shares this buffer,  including
104               other threads.
105
106       Note: This function is not thread safe, because it shares a return buf‐
107       fer across all threads, and many other functions in this library.
108
109       Example: This function is intended to be used in a fashion  similar  to
110       the following example:
111              ssize_t result = pread(fildes, data, data_size, offset);
112              if (result < 0)
113              {
114                  int err = errno;
115                  fprintf(stderr, "%s\n", explain_errno_pread(err, fildes,
116                  data, data_size, offset));
117                  exit(EXIT_FAILURE);
118              }
119
120       The   above   code   example   is   available   pre‐packaged   as   the
121       explain_pread_or_die(3) function.
122
123   explain_message_pread
124       void explain_message_pread(char *message, int message_size, int fildes,
125       void *data, size_t data_size, off_t offset);
126
127       The explain_message_pread function is used to obtain an explanation  of
128       an  error  returned  by the pread(2) system call. The least the message
129       will contain is the value of strerror(errno), but usually  it  will  do
130       much better, and indicate the underlying cause in more detail.
131
132       The  errno global variable will be used to obtain the error value to be
133       decoded.
134
135       message The location in which to store the returned message. If a suit‐
136               able message return buffer is supplied, this function is thread
137               safe.
138
139       message_size
140               The size in bytes  of  the  location  in  which  to  store  the
141               returned message.
142
143       fildes  The  original  fildes, exactly as passed to the pread(2) system
144               call.
145
146       data    The original data, exactly as passed  to  the  pread(2)  system
147               call.
148
149       data_size
150               The  original data_size, exactly as passed to the pread(2) sys‐
151               tem call.
152
153       offset  The original offset, exactly as passed to the  pread(2)  system
154               call.
155
156       Example:  This  function is intended to be used in a fashion similar to
157       the following example:
158              ssize_t result = pread(fildes, data, data_size, offset);
159              if (result < 0)
160              {
161                  char message[3000];
162                  explain_message_pread(message, sizeof(message), fildes,
163                  data, data_size, offset);
164                  fprintf(stderr, "%s\n", message);
165                  exit(EXIT_FAILURE);
166              }
167
168       The   above   code   example   is   available   pre‐packaged   as   the
169       explain_pread_or_die(3) function.
170
171   explain_message_errno_pread
172       void explain_message_errno_pread(char *message, int message_size, int
173       errnum, int fildes, void *data, size_t data_size, off_t offset);
174
175       The  explain_message_errno_pread function is used to obtain an explana‐
176       tion of an error returned by the pread(2) system call.  The  least  the
177       message  will  contain  is the value of strerror(errno), but usually it
178       will do much better, and indicate the underlying cause in more detail.
179
180       message The location in which to store the returned message. If a suit‐
181               able message return buffer is supplied, this function is thread
182               safe.
183
184       message_size
185               The size in bytes  of  the  location  in  which  to  store  the
186               returned message.
187
188       errnum  The  error value to be decoded, usually obtained from the errno
189               global variable just before this function is  called.  This  is
190               necessary  if you need to call any code between the system call
191               to be explained and this function, because many libc  functions
192               will alter the value of errno.
193
194       fildes  The  original  fildes, exactly as passed to the pread(2) system
195               call.
196
197       data    The original data, exactly as passed  to  the  pread(2)  system
198               call.
199
200       data_size
201               The  original data_size, exactly as passed to the pread(2) sys‐
202               tem call.
203
204       offset  The original offset, exactly as passed to the  pread(2)  system
205               call.
206
207       Example:  This  function is intended to be used in a fashion similar to
208       the following example:
209              ssize_t result = pread(fildes, data, data_size, offset);
210              if (result < 0)
211              {
212                  int err = errno;
213                  char message[3000];
214                  explain_message_errno_pread(message, sizeof(message), err,
215                  fildes, data, data_size, offset);
216                  fprintf(stderr, "%s\n", message);
217                  exit(EXIT_FAILURE);
218              }
219
220       The   above   code   example   is   available   pre‐packaged   as   the
221       explain_pread_or_die(3) function.
222

SEE ALSO

224       pread(2)
225               read from or write to a file descriptor at a given offset
226
227       explain_pread_or_die(3)
228               read from or write to a file descriptor at a given  offset  and
229               report errors
230
232       libexplain version 0.40
233       Copyright (C) 2009 Peter Miller
234
235
236
237                                                              explain_pread(3)
Impressum