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

NAME

6       explain_writev - explain writev(2) errors
7

SYNOPSIS

9       #include <libexplain/writev.h>
10       const char *explain_writev(int fildes, const struct iovec *data, int
11       data_size);
12       const char *explain_errno_writev(int errnum, int fildes, const struct
13       iovec *data, int data_size);
14       void explain_message_writev(char *message, int message_size, int
15       fildes, const struct iovec *data, int data_size);
16       void explain_message_errno_writev(char *message, int message_size, int
17       errnum, int fildes, const struct iovec *data, int data_size);
18

DESCRIPTION

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

SEE ALSO

212       writev(2)
213               write data from multiple buffers
214
215       explain_writev_or_die(3)
216               write data from multiple buffers and report errors
217
219       libexplain version 0.40
220       Copyright (C) 2009 Peter Miller
221
222
223
224                                                             explain_writev(3)
Impressum