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

NAME

6       explain_readv - explain readv(2) errors
7

SYNOPSIS

9       #include <libexplain/readv.h>
10       const char *explain_readv(int fildes, const struct iovec *iov, int
11       iovcnt);
12       const char *explain_errno_readv(int errnum, int fildes, const struct
13       iovec *iov, int iovcnt);
14       void explain_message_readv(char *message, int message_size, int fildes,
15       const struct iovec *iov, int iovcnt);
16       void explain_message_errno_readv(char *message, int message_size, int
17       errnum, int fildes, const struct iovec *iov, int iovcnt);
18

DESCRIPTION

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

SEE ALSO

207       readv(2)
208               read data into multiple buffers
209
210       explain_readv_or_die(3)
211               read data into multiple buffers and report errors
212
214       libexplain version 0.40
215       Copyright (C) 2009 Peter Miller
216
217
218
219                                                              explain_readv(3)
Impressum