1explain_realpath(3) Library Functions Manual explain_realpath(3)
2
6 explain_realpath - explain realpath(3) errors
7
9 #include <libexplain/realpath.h>
10 const char *explain_realpath(const char *pathname, char *resolved_path‐
11 name);
12 const char *explain_errno_realpath(int errnum, const char *pathname,
13 char *resolved_pathname);
14 void explain_message_realpath(char *message, int message_size, const
15 char *pathname, char *resolved_pathname);
16 void explain_message_errno_realpath(char *message, int message_size,
17 int errnum, const char *pathname, char *resolved_pathname);
18
20 These functions may be used to obtain explanations for errors returned
21 by the realpath(3) system call.
22 explain_realpath
24 const char *explain_realpath(const char *pathname, char *resolved_path‐
25 name);
26 The explain_realpath function is used to obtain an explanation of an
28 error returned by the realpath(3) 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 pathname
36 The original pathname, exactly as passed to the realpath(3)
37 system call.
38 resolved_pathname
40 The original resolved_pathname, exactly as passed to the real‐
41 path(3) system call.
42 Returns:
44 The message explaining the error. This message buffer is shared
45 by all libexplain functions which do not supply a buffer in
46 their argument list. This will be overwritten by the next call
47 to any libexplain function which shares this buffer, including
48 other threads.
49 Note: This function is not thread safe, because it shares a return buf‐
51 fer across all threads, and many other functions in this library.
52 Example: This function is intended to be used in a fashion similar to
54 the following example:
55 char *result = realpath(pathname, resolved_pathname);
56 if (!result)
57 {
58 fprintf(stderr, "%s\n", explain_realpath(pathname,
59 resolved_pathname));
60 exit(EXIT_FAILURE);
61 }
62 The above code example is available pre-packaged as the explain_real‐
64 path_or_die(3) function.
65 explain_errno_realpath
67 const char *explain_errno_realpath(int errnum, const char *pathname,
68 char *resolved_pathname);
69 The explain_errno_realpath function is used to obtain an explanation of
71 an error returned by the realpath(3) system call. The least the mes‐
72 sage will contain is the value of strerror(errno), but usually it will
73 do much better, and indicate the underlying cause in more detail.
74 errnum The error value to be decoded, usually obtained from the errno
76 global variable just before this function is called. This is
77 necessary if you need to call any code between the system call
78 to be explained and this function, because many libc functions
79 will alter the value of errno.
80 pathname
82 The original pathname, exactly as passed to the realpath(3)
83 system call.
84 resolved_pathname
86 The original resolved_pathname, exactly as passed to the real‐
87 path(3) system call.
88 Returns:
90 The message explaining the error. This message buffer is shared
91 by all libexplain functions which do not supply a buffer in
92 their argument list. This will be overwritten by the next call
93 to any libexplain function which shares this buffer, including
94 other threads.
95 Note: This function is not thread safe, because it shares a return buf‐
97 fer across all threads, and many other functions in this library.
98 Example: This function is intended to be used in a fashion similar to
100 the following example:
101 char *result = realpath(pathname, resolved_pathname);
102 if (!result)
103 {
104 int err = errno;
105 fprintf(stderr, "%s\n", explain_errno_realpath(err, path‐
106 name, resolved_pathname));
107 exit(EXIT_FAILURE);
108 }
109 The above code example is available pre-packaged as the explain_real‐
111 path_or_die(3) function.
112 explain_message_realpath
114 void explain_message_realpath(char *message, int message_size, const
115 char *pathname, char *resolved_pathname);
116 The explain_message_realpath function is used to obtain an explanation
118 of an error returned by the realpath(3) system call. The least the
119 message will contain is the value of strerror(errno), but usually it
120 will do much better, and indicate the underlying cause in more detail.
121 The errno global variable will be used to obtain the error value to be
123 decoded.
124 message The location in which to store the returned message. If a suit‐
126 able message return buffer is supplied, this function is thread
127 safe.
128 message_size
130 The size in bytes of the location in which to store the
131 returned message.
132 pathname
134 The original pathname, exactly as passed to the realpath(3)
135 system call.
136 resolved_pathname
138 The original resolved_pathname, exactly as passed to the real‐
139 path(3) system call.
140 Example: This function is intended to be used in a fashion similar to
142 the following example:
143 char *result = realpath(pathname, resolved_pathname);
144 if (!result)
145 {
146 char message[3000];
147 explain_message_realpath(message, sizeof(message), pathname,
148 resolved_pathname);
149 fprintf(stderr, "%s\n", message);
150 exit(EXIT_FAILURE);
151 }
152 The above code example is available pre-packaged as the explain_real‐
154 path_or_die(3) function.
155 explain_message_errno_realpath
157 void explain_message_errno_realpath(char *message, int message_size,
158 int errnum, const char *pathname, char *resolved_pathname);
159 The explain_message_errno_realpath function is used to obtain an expla‐
161 nation of an error returned by the realpath(3) system call. The least
162 the message will contain is the value of strerror(errno), but usually
163 it will do much better, and indicate the underlying cause in more
164 detail.
165 message The location in which to store the returned message. If a suit‐
167 able message return buffer is supplied, this function is thread
168 safe.
169 message_size
171 The size in bytes of the location in which to store the
172 returned message.
173 errnum The error value to be decoded, usually obtained from the errno
175 global variable just before this function is called. This is
176 necessary if you need to call any code between the system call
177 to be explained and this function, because many libc functions
178 will alter the value of errno.
179 pathname
181 The original pathname, exactly as passed to the realpath(3)
182 system call.
183 resolved_pathname
185 The original resolved_pathname, exactly as passed to the real‐
186 path(3) system call.
187 Example: This function is intended to be used in a fashion similar to
189 the following example:
190 char *result = realpath(pathname, resolved_pathname);
191 if (!result)
192 {
193 int err = errno;
194 char message[3000];
195 explain_message_errno_realpath(message, sizeof(message),
196 err, pathname, resolved_pathname);
197 fprintf(stderr, "%s\n", message);
198 exit(EXIT_FAILURE);
199 }
200 The above code example is available pre-packaged as the explain_real‐
202 path_or_die(3) function.
203
205 realpath(3)
206 return the canonicalized absolute pathname
207 explain_realpath_or_die(3)
209 return the canonicalized absolute pathname and report errors
210
212 libexplain version 1.4
213 Copyright (C) 2011 Peter Miller
214 explain_realpath(3)