1explain_writev(3) Library Functions Manual explain_writev(3)
2
6 explain_writev - explain writev(2) errors
7
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
20 These functions may be used to obtain explanations for errors returned
21 by the writev(2) system call.
22 explain_writev
24 const char *explain_writev(int fildes, const struct iovec *data, int
25 data_size);
26 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 The errno global variable will be used to obtain the error value to be
33 decoded.
34 fildes The original fildes, exactly as passed to the writev(2) system
36 call.
37 data The original data, exactly as passed to the writev(2) system
39 call.
40 data_size
42 The original data_size, exactly as passed to the writev(2) sys‐
43 tem call.
44 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 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 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 The above code example is available pre‐packaged as the
66 explain_writev_or_die(3) function.
67 explain_errno_writev
69 const char *explain_errno_writev(int errnum, int fildes, const struct
70 iovec *data, int data_size);
71 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 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 fildes The original fildes, exactly as passed to the writev(2) system
84 call.
85 data The original data, exactly as passed to the writev(2) system
87 call.
88 data_size
90 The original data_size, exactly as passed to the writev(2) sys‐
91 tem call.
92 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 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 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 The above code example is available pre‐packaged as the
115 explain_writev_or_die(3) function.
116 explain_message_writev
118 void explain_message_writev(char *message, int message_size, int
119 fildes, const struct iovec *data, int data_size);
120 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 The errno global variable will be used to obtain the error value to be
127 decoded.
128 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 message_size
134 The size in bytes of the location in which to store the
135 returned message.
136 fildes The original fildes, exactly as passed to the writev(2) system
138 call.
139 data The original data, exactly as passed to the writev(2) system
141 call.
142 data_size
144 The original data_size, exactly as passed to the writev(2) sys‐
145 tem call.
146 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 The above code example is available pre‐packaged as the
160 explain_writev_or_die(3) function.
161 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 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 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 message_size
176 The size in bytes of the location in which to store the
177 returned message.
178 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 fildes The original fildes, exactly as passed to the writev(2) system
186 call.
187 data The original data, exactly as passed to the writev(2) system
189 call.
190 data_size
192 The original data_size, exactly as passed to the writev(2) sys‐
193 tem call.
194 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 The above code example is available pre‐packaged as the
209 explain_writev_or_die(3) function.
210
212 writev(2)
213 write data from multiple buffers
214 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 explain_writev(3)