1explain_write(3) Library Functions Manual explain_write(3)
2
6 explain_write - explain write(2) errors
7
9 #include <libexplain/write.h>
10 const char *explain_write(int fildes, const void *data, long
11 data_size);
12 const char *explain_errno_write(int errnum, int fildes, const void
13 *data, long data_size);
14 void explain_message_write(char *message, int message_size, int fildes,
15 const void *data, long data_size);
16 void explain_message_errno_write(char *message, int message_size, int
17 errnum, int fildes, const void *data, long data_size);
18
20 These functions may be used to obtain explanations for write(2) errors
21 .
22 explain_write
24 const char *explain_write(int fildes, const void *data, long
25 data_size);
26 The explain_write function may be used to obtain a human readable
28 explanation of what went wrong in a write(2) system call. The least
29 the message will contain is the value of strerror(errno), but usually
30 it will do much better, and indicate the underlying cause in more
31 detail.
32 The error number will be picked up from the errno global variable.
34 This function is intended to be used in a fashion similar to the fol‐
36 lowing example:
37 sszie_t n = write(fd, data, data_size);
38 if (n < 0)
39 {
40 fprintf(stderr, '%s0, explain_read(fd, data, data_size));
41 exit(EXIT_FAILURE);
42 }
43 fildes The original fildes, exactly as passed to the write(2) system
45 call.
46 data The original data, exactly as passed to the write(2) system
48 call.
49 data_size
51 The original data_size, exactly as passed to the write(2) sys‐
52 tem call.
53 Returns:
55 The message explaining the error. This message buffer is
56 shared by all libexplain functions which do not supply a buffer
57 in their argument list. This will be overwritten by the next
58 call to any libexplain function which shares this buffer,
59 including other threads.
60 Note: This function is not thread safe, because it shares a return buf‐
62 fer across all threads, and many other functions in this library.
63 explain_errno_write
65 const char *explain_errno_write(int errnum, int fildes, const void
66 *data, long data_size);
67 The explain_errno_write function may be used to obtain a human readable
69 explanation of what went wrong in a write(2) system call. The least
70 the message will contain is the value of strerror(errnum), but usually
71 it will do much better, and indicate the underlying cause in more
72 detail.
73 This function is intended to be used in a fashion similar to the fol‐
75 lowing example:
76 sszie_t n = write(fd, data, data_size);
77 if (n < 0)
78 {
79 int err = errno;
80 fprintf(stderr, '%s0, explain_errno_read(errnum, fd, data,
81 data_size));
82 exit(EXIT_FAILURE);
83 }
84 errnum The error value to be decoded, usually obtain from the errno
86 global variable just before this function is called. This is
87 necessary if you need to call any code between the system call
88 to be explained and this function, because many libc functions
89 will alter the value of errno.
90 fildes The orginal fildes, exactly as passed to the write(2) system
92 call.
93 data The original data, exactly as passed to the write(2) system
95 call.
96 data_size
98 The original data_size, exactly as passed to the write(2) sys‐
99 tem call.
100 Returns:
102 The message explaining the error. This message buffer is
103 shared by all libexplain functions which do not supply a buffer
104 in their argument list. This will be overwritten by the next
105 call to any libexplain function which shares this buffer,
106 including other threads.
107 Note: This function is not thread safe, because it shares a return buf‐
109 fer across all threads, and many other functions in this library.
110 explain_message_write
112 void explain_message_write(char *message, int message_size, int fildes,
113 const void *data, long data_size);
114 The explain_message_write function may be used to obtain a human read‐
116 able explanation of what went wrong in a write(2) system call. The
117 least the message will contain is the value of strerror(errno), but
118 usually it will do much better, and indicate the underlying cause in
119 more detail.
120 The error number will be picked up from the errno global variable.
122 This function is intended to be used in a fashion similar to the fol‐
124 lowing example:
125 sszie_t n = write(fd, data, data_size);
126 if (n < 0)
127 {
128 char message[3000];
129 explain_message_read(message, sizeof(message), fd, data,
130 data_size));
131 fprintf(stderr, '%s0, message);
132 exit(EXIT_FAILURE);
133 }
134 message The location in which to store the returned message. Because a
136 message return buffer has been supplied, this function is
137 thread safe.
138 message_size
140 The size in bytes of the location in which to store the
141 returned message.
142 fildes The original fildes, exactly as passed to the write(2) system
144 call.
145 data The original data, exactly as passed to the write(2) system
147 call.
148 data_size
150 The original data_size, exactly as passed to the write(2) sys‐
151 tem call.
152 Note: Given a suitably thread safe buffer, this function is thread
154 safe.
155 explain_message_errno_write
157 void explain_message_errno_write(char * message, int message_size, int
158 errnum, int fildes, const void *data, long data_size);
159 The explain_message_errno_write function may be used to obtain a human
161 readable explanation of what went wrong in a write(2) system call. The
162 least the message will contain is the value of strerror(errnum), but
163 usually it will do much better, and indicate the underlying cause in
164 more detail.
165 This function is intended to be used in a fashion similar to the fol‐
167 lowing example:
168 sszie_t n = write(fd, data, data_size);
169 if (n < 0)
170 {
171 int err = errno;
172 char message[3000];
173 explain_message_errno_read(message, sizeof(message), errno,
174 fd, data, data_size));
175 fprintf(stderr, '%s0, message);
176 exit(EXIT_FAILURE);
177 }
178 message The location in which to store the returned message. Because a
180 message return buffer has been supplied, this function is
181 thread safe.
182 message_size
184 The size in bytes of the location in which to store the
185 returned message.
186 errnum The error value to be decoded, usually obtain from the errno
188 global variable just before this function is called. This is
189 necessary if you need to call any code between the system call
190 to be explained and this function, because many libc functions
191 will alter the value of errno.
192 fildes The original fildes, exactly as passed to the write(2) system
194 call.
195 data The original data, exactly as passed to the write(2) system
197 call.
198 data_size
200 The original data_size, exactly as passed to the write(2) sys‐
201 tem call.
202 Note: Given a suitably thread safe buffer, this function is thread
204 safe.
205
207 libexplain version 1.4
208 Copyright (C) 2008 Peter Miller
209
211 Written by Peter Miller <pmiller@opensource.org.au>
212 explain_write(3)