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

NAME

6       explain_pwrite - explain pwrite(2) errors
7

SYNOPSIS

9       #include <libexplain/pwrite.h>
10       const char *explain_pwrite(int fildes, const void *data, size_t
11       data_size, off_t offset);
12       const char *explain_errno_pwrite(int errnum, int fildes, const void
13       *data, size_t data_size, off_t offset);
14       void explain_message_pwrite(char *message, int message_size, int
15       fildes, const void *data, size_t data_size, off_t offset);
16       void explain_message_errno_pwrite(char *message, int message_size, int
17       errnum, int fildes, const 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 pwrite(2) system call.
22
23   explain_pwrite
24       const char *explain_pwrite(int fildes, const void *data, size_t
25       data_size, off_t offset);
26
27       The  explain_pwrite  function  is  used  to obtain an explanation of an
28       error returned by the pwrite(2) system call. The least the message will
29       contain  is  the  value of strerror(errno), but usually it will do much
30       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       fildes  The  original fildes, exactly as passed to the pwrite(2) system
36               call.
37
38       data    The original data, exactly as passed to  the  pwrite(2)  system
39               call.
40
41       data_size
42               The original data_size, exactly as passed to the pwrite(2) sys‐
43               tem call.
44
45       offset  The original offset, exactly as passed to the pwrite(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 = pwrite(fildes, data, data_size, offset);
61              if (result < 0)
62              {
63                  fprintf(stderr, "%s\n", explain_pwrite(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_pwrite_or_die(3) function.
70
71   explain_errno_pwrite
72       const char *explain_errno_pwrite(int errnum, int fildes, const void
73       *data, size_t data_size, off_t offset);
74
75       The explain_errno_pwrite function is used to obtain an  explanation  of
76       an  error  returned by the pwrite(2) system call. The least the message
77       will contain is the value of strerror(errno), but usually  it  will  do
78       much 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 pwrite(2) system
87               call.
88
89       data    The original data, exactly as passed to  the  pwrite(2)  system
90               call.
91
92       data_size
93               The original data_size, exactly as passed to the pwrite(2) sys‐
94               tem call.
95
96       offset  The original offset, exactly as passed to the pwrite(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 = pwrite(fildes, data, data_size, offset);
112              if (result < 0)
113              {
114                  int err = errno;
115                  fprintf(stderr, "%s\n", explain_errno_pwrite(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_pwrite_or_die(3) function.
122
123   explain_message_pwrite
124       void explain_message_pwrite(char *message, int message_size, int
125       fildes, const void *data, size_t data_size, off_t offset);
126
127       The explain_message_pwrite function is used to obtain an explanation of
128       an  error  returned by the pwrite(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 pwrite(2) system
144               call.
145
146       data    The original data, exactly as passed to  the  pwrite(2)  system
147               call.
148
149       data_size
150               The original data_size, exactly as passed to the pwrite(2) sys‐
151               tem call.
152
153       offset  The original offset, exactly as passed to the pwrite(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 = pwrite(fildes, data, data_size, offset);
159              if (result < 0)
160              {
161                  char message[3000];
162                  explain_message_pwrite(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_pwrite_or_die(3) function.
170
171   explain_message_errno_pwrite
172       void explain_message_errno_pwrite(char *message, int message_size, int
173       errnum, int fildes, const void *data, size_t data_size, off_t offset);
174
175       The explain_message_errno_pwrite function is used to obtain an explana‐
176       tion of an error returned by the pwrite(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 pwrite(2) system
195               call.
196
197       data    The original data, exactly as passed to  the  pwrite(2)  system
198               call.
199
200       data_size
201               The original data_size, exactly as passed to the pwrite(2) sys‐
202               tem call.
203
204       offset  The original offset, exactly as passed to the pwrite(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 = pwrite(fildes, data, data_size, offset);
210              if (result < 0)
211              {
212                  int err = errno;
213                  char message[3000];
214                  explain_message_errno_pwrite(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_pwrite_or_die(3) function.
222

SEE ALSO

224       pwrite(2)
225               read from or write to a file descriptor at a given offset
226
227       explain_pwrite_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_pwrite(3)
Impressum