1explain_readlink(3) Library Functions Manual explain_readlink(3)
2
6 explain_readlink - explain readlink(2) errors
7
9 #include <libexplain/readlink.h>
10 const char *explain_readlink(const char *pathname, char *data, size_t
11 data_size);
12 const char *explain_errno_readlink(int errnum, const char *pathname,
13 char *data, size_t data_size);
14 void explain_message_readlink(char *message, int message_size, const
15 char *pathname, char *data, size_t data_size);
16 void explain_message_errno_readlink(char *message, int message_size,
17 int errnum, const char *pathname, char *data, size_t data_size);
18
20 These functions may be used to obtain explanations for errors returned
21 by the readlink(2) system call.
22 explain_readlink
24 const char *explain_readlink(const char *pathname, char *data, size_t
25 data_size);
26 The explain_readlink function is used to obtain an explanation of an
28 error returned by the readlink(2) system call. The least the message
29 will contain is the value of strerror(errno), but usually it will do
30 much 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 This function is intended to be used in a fashion similar to the fol‐
36 lowing example:
37 if (readlink(pathname, data, data_size) < 0)
38 {
39 fprintf(stderr, "%s\n", explain_readlink(pathname, data, data_size));
40 exit(EXIT_FAILURE);
41 }
42 pathname
44 The original pathname, exactly as passed to the readlink(2)
45 system call.
46 data The original data, exactly as passed to the readlink(2) system
48 call.
49 data_size
51 The original data_size, exactly as passed to the readlink(2)
52 system 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_readlink
65 const char *explain_errno_readlink(int errnum, const char *pathname,
66 char *data, size_t data_size);
67 The explain_errno_readlink function is used to obtain an explanation of
69 an error returned by the readlink(2) system call. The least the mes‐
70 sage will contain is the value of strerror(errnum), but usually it will
71 do much better, and indicate the underlying cause in more detail.
72 This function is intended to be used in a fashion similar to the fol‐
74 lowing example:
75 if (readlink(pathname, data, data_size) < 0)
76 {
77 int err = errno;
78 fprintf(stderr, "%s\n", explain_errno_readlink(err, pathname, data,
79 data_size));
80 exit(EXIT_FAILURE);
81 }
82 errnum The error value to be decoded, usually obtained from the errno
84 global variable just before this function is called. This is
85 necessary if you need to call any code between the system call
86 to be explained and this function, because many libc functions
87 will alter the value of errno.
88 pathname
90 The original pathname, exactly as passed to the readlink(2)
91 system call.
92 data The original data, exactly as passed to the readlink(2) system
94 call.
95 data_size
97 The original data_size, exactly as passed to the readlink(2)
98 system call.
99 Returns:
101 The message explaining the error. This message buffer is
102 shared by all libexplain functions which do not supply a buffer
103 in their argument list. This will be overwritten by the next
104 call to any libexplain function which shares this buffer,
105 including other threads.
106 Note: This function is not thread safe, because it shares a return buf‐
108 fer across all threads, and many other functions in this library.
109 explain_message_readlink
111 void explain_message_readlink(char *message, int message_size, const
112 char *pathname, char *data, size_t data_size);
113 The explain_message_readlink function may be used to obtain an expla‐
115 nation of an error returned by the readlink(2) system call. The least
116 the message will contain is the value of strerror(errno), but usually
117 it will do much better, and indicate the underlying cause in more
118 detail.
119 The errno global variable will be used to obtain the error value to be
121 decoded.
122 This function is intended to be used in a fashion similar to the fol‐
124 lowing example:
125 if (readlink(pathname, data, data_size) < 0)
126 {
127 char message[3000];
128 explain_message_readlink(message, sizeof(message), pathname, data,
129 data_size);
130 fprintf(stderr, "%s\n", message);
131 exit(EXIT_FAILURE);
132 }
133 message The location in which to store the returned message. If a
135 suitable message return buffer is supplied, this function is
136 thread safe.
137 message_size
139 The size in bytes of the location in which to store the
140 returned message.
141 pathname
143 The original pathname, exactly as passed to the readlink(2)
144 system call.
145 data The original data, exactly as passed to the readlink(2) system
147 call.
148 data_size
150 The original data_size, exactly as passed to the readlink(2)
151 system call.
152 explain_message_errno_readlink
154 void explain_message_errno_readlink(char *message, int message_size,
155 int errnum, const char *pathname, char *data, size_t data_size);
156 The explain_message_errno_readlink function may be used to obtain an
158 explanation of an error returned by the readlink(2) system call. The
159 least the message will contain is the value of strerror(errnum), but
160 usually it will do much better, and indicate the underlying cause in
161 more detail.
162 This function is intended to be used in a fashion similar to the fol‐
164 lowing example:
165 if (readlink(pathname, data, data_size) < 0)
166 {
167 int err = errno;
168 char message[3000];
169 explain_message_errno_readlink(message, sizeof(message), err, pathname,
170 data, data_size);
171 fprintf(stderr, "%s\n", message);
172 exit(EXIT_FAILURE);
173 }
174 message The location in which to store the returned message. If a
176 suitable message return buffer is supplied, this function is
177 thread safe.
178 message_size
180 The size in bytes of the location in which to store the
181 returned message.
182 errnum The error value to be decoded, usually obtained from the errno
184 global variable just before this function is called. This is
185 necessary if you need to call any code between the system call
186 to be explained and this function, because many libc functions
187 will alter the value of errno.
188 pathname
190 The original pathname, exactly as passed to the readlink(2)
191 system call.
192 data The original data, exactly as passed to the readlink(2) system
194 call.
195 data_size
197 The original data_size, exactly as passed to the readlink(2)
198 system call.
199
201 readlink(2)
202 blah blah blah
203 explain_readlink_or_die(3)
205 blah blah blah and report errors
206
208 libexplain version 1.4
209 Copyright (C) 2008 Peter Miller
210 explain_readlink(3)