1explain_read(3) Library Functions Manual explain_read(3)
2
6 explain_read - explain read(2) errors
7
9 #include <libexplain/read.h>
10 const char *explain_read(int fildes, const void *data, long data_size);
11 const char *explain_errno_read(int errnum, int fildes, const void
12 *data, long data_size);
13 void explain_message_read(char *message, int message_size, int fildes,
14 const void *data, long data_size);
15 void explain_message_errno_read(char *message, int message_size, int
16 errnum, int fildes, const void *data, long data_size);
17
19 These functions may be used to obtain an explanation for read(2)
20 errors.
21 explain_read
23 const char *explain_read(int fildes, const void *data, long data_size);
24 The explain_read function may be used to obtain a human readable expla‐
26 nation of what went wrong in a read(2) system call. The least the mes‐
27 sage will contain is the value of strerror(errno), but usually it will
28 do much better, and indicate the underlying cause in more detail.
29 The error number will be picked up from the errno global variable.
31 This function is intended to be used in a fashion similar to the fol‐
33 lowing example:
34 ssize_t n = read(fd, data, data_size);
35 if (n < 0)
36 {
37 fprintf(stderr, "%s\n", explain_read(fd, data, data_size));
38 exit(EXIT_FAILURE);
39 }
40 fildes The original fildes, exactly as passed to the read(2) system
42 call.
43 data The original data, exactly as passed to the read(2) system
45 call.
46 data_size
48 The original data_size, exactly as passed to the read(2) system
49 call.
50 Returns:
52 The message explaining the error. This message buffer is
53 shared by all libexplain functions which do not supply a buffer
54 in their argument list. This will be overwritten by the next
55 call to any libexplain function which shares this buffer,
56 including other threads.
57 Note: This function is not thread safe, because it shares a return buf‐
59 fer across all threads, and many other functions in this library.
60 explain_errno_read
62 const char *explain_errno_read(int errnum, int fildes, const void
63 *data, long data_size);
64 The explain_errno_read function may be used to obtain a human readable
66 explanation of what went wrong in a read(2) system call. The least the
67 message will contain is the value of strerror(errnum), but usually it
68 will do much better, and indicate the underlying cause in more detail.
69 This function is intended to be used in a fashion similar to the fol‐
71 lowing example:
72 ssize_t n = read(fd, data, data_size);
73 if (n < 0)
74 {
75 int err = errno;
76 fprintf(stderr, "%s\n", explain_errno_read(err, fd, data, data_size));
77 exit(EXIT_FAILURE);
78 }
79 errnum The error value to be decoded, usually obtain 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 fildes The original fildes, exactly as passed to the read(2) system
87 call.
88 data The original data, exactly as passed to the read(2) system
90 call.
91 data_size
93 The original data_size, exactly as passed to the read(2) system
94 call.
95 Returns:
97 The message explaining the error. This message buffer is
98 shared by all libexplain functions which do not supply a buffer
99 in their argument list. This will be overwritten by the next
100 call to any libexplain function which shares this buffer,
101 including other threads.
102 Note: This function is not thread safe, because it shares a return buf‐
104 fer across all threads, and many other functions in this library.
105 explain_message_read
107 void explain_message_read(char *message, int message_size, int fildes,
108 const void *data, long data_size);
109 The explain_message_read function may be used to obtain a human read‐
111 able explanation of what went wrong in a read(2) system call. The
112 least the message will contain is the value of strerror(errno), but
113 usually it will do much better, and indicate the underlying cause in
114 more detail.
115 The error number will be picked up from the errno global variable.
117 This function is intended to be used in a fashion similar to the fol‐
119 lowing example:
120 ssize_t n = read(fd, data, data_size);
121 if (n < 0)
122 {
123 char message[3000];
124 explain_message_read(message, sizeof(message), fd, data, data_size));
125 fprintf(stderr, "%s\n", message);
126 exit(EXIT_FAILURE);
127 }
128 message The location in which to store the returned message. Because a
130 message return buffer has been supplied, this function is
131 thread 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 read(2) system
138 call.
139 data The original data, exactly as passed to the read(2) system
141 call.
142 data_size
144 The original data_size, exactly as passed to the read(2) system
145 call.
146 Note: Given a suitably thread safe buffer, this function is thread
148 safe.
149 explain_message_errno_read
151 void explain_message_errno_read(char *message, int message_size, int
152 errnum, int fildes, const void *data, long data_size);
153 The explain_message_errno_read function may be used to obtain a human
155 readable explanation of what went wrong in a read(2) system call. The
156 least the message will contain is the value of strerror(errnum), but
157 usually it will do much better, and indicate the underlying cause in
158 more detail.
159 This function is intended to be used in a fashion similar to the fol‐
161 lowing example:
162 ssize_t n = read(fd, data, data_size);
163 if (n < 0)
164 {
165 int err = errno;
166 char message[3000];
167 explain_message_errno_read(message, sizeof(message), err,
168 fd, data, data_size);
169 fprintf(stderr, "%s\n", message);
170 exit(EXIT_FAILURE);
171 }
172 message The location in which to store the returned message. Because a
174 message return buffer has been supplied, this function is
175 thread safe.
176 message_size
178 The size in bytes of the location in which to store the
179 returned message.
180 errnum The error value to be decoded, usually obtain from the errno
182 global variable just before this function is called. This is
183 necessary if you need to call any code between the system call
184 to be explained and this function, because many libc functions
185 will alter the value of errno.
186 fildes The original fildes, exactly as passed to the read(2) system
188 call.
189 data The original data, exactly as passed to the read(2) system
191 call.
192 data_size
194 The original data_size, exactly as passed to the read(2) system
195 call.
196 Note: Given a suitably thread safe buffer, this function is thread
198 safe.
199
201 libexplain version 1.4
202 Copyright (C) 2008 Peter Miller
203
205 Written by Peter Miller <pmiller@opensource.org.au>
206 explain_read(3)