1explain_linkat(3) Library Functions Manual explain_linkat(3)
2
6 explain_linkat - explain linkat(2) errors
7
9 #include <libexplain/linkat.h>
10 const char *explain_linkat(int old_fildes, const char *old_path, int
11 new_fildes, const char *new_path, int flags);
12 const char *explain_errno_linkat(int errnum, int old_fildes, const char
13 *old_path, int new_fildes, const char *new_path, int flags);
14 void explain_message_linkat(char *message, int message_size, int
15 old_fildes, const char *old_path, int new_fildes, const char *new_path,
16 int flags);
17 void explain_message_errno_linkat(char *message, int message_size, int
18 errnum, int old_fildes, const char *old_path, int new_fildes, const
19 char *new_path, int flags);
20
22 These functions may be used to obtain explanations for errors returned
23 by the linkat(2) system call.
24 explain_linkat
26 const char *explain_linkat(int old_fildes, const char *old_path, int
27 new_fildes, const char *new_path, int flags);
28 The explain_linkat function is used to obtain an explanation of an
30 error returned by the linkat(2) system call. The least the message will
31 contain is the value of strerror(errno), but usually it will do much
32 better, and indicate the underlying cause in more detail.
33 The errno global variable will be used to obtain the error value to be
35 decoded.
36 old_fildes
38 The original old_fildes, exactly as passed to the linkat(2)
39 system call.
40 old_path
42 The original old_path, exactly as passed to the linkat(2) sys‐
43 tem call.
44 new_fildes
46 The original new_fildes, exactly as passed to the linkat(2)
47 system call.
48 new_path
50 The original new_path, exactly as passed to the linkat(2) sys‐
51 tem call.
52 flags The original flags, exactly as passed to the linkat(2) system
54 call.
55 Returns:
57 The message explaining the error. This message buffer is shared
58 by all libexplain functions which do not supply a buffer in
59 their argument list. This will be overwritten by the next call
60 to any libexplain function which shares this buffer, including
61 other threads.
62 Note: This function is not thread safe, because it shares a return buf‐
64 fer across all threads, and many other functions in this library.
65 Example: This function is intended to be used in a fashion similar to
67 the following example:
68 if (linkat(old_fildes, old_path, new_fildes, new_path, flags) <
69 0)
70 {
71 fprintf(stderr, "%s\n", explain_linkat(old_fildes, old_path,
72 new_fildes, new_path, flags));
73 exit(EXIT_FAILURE);
74 }
75 The above code example is available pre-packaged as the
77 explain_linkat_or_die(3) function.
78 explain_errno_linkat
80 const char *explain_errno_linkat(int errnum, int old_fildes, const char
81 *old_path, int new_fildes, const char *new_path, int flags);
82 The explain_errno_linkat function is used to obtain an explanation of
84 an error returned by the linkat(2) system call. The least the message
85 will contain is the value of strerror(errno), but usually it will do
86 much better, and indicate the underlying cause in more detail.
87 errnum The error value to be decoded, usually obtained from the errno
89 global variable just before this function is called. This is
90 necessary if you need to call any code between the system call
91 to be explained and this function, because many libc functions
92 will alter the value of errno.
93 old_fildes
95 The original old_fildes, exactly as passed to the linkat(2)
96 system call.
97 old_path
99 The original old_path, exactly as passed to the linkat(2) sys‐
100 tem call.
101 new_fildes
103 The original new_fildes, exactly as passed to the linkat(2)
104 system call.
105 new_path
107 The original new_path, exactly as passed to the linkat(2) sys‐
108 tem call.
109 flags The original flags, exactly as passed to the linkat(2) system
111 call.
112 Returns:
114 The message explaining the error. This message buffer is shared
115 by all libexplain functions which do not supply a buffer in
116 their argument list. This will be overwritten by the next call
117 to any libexplain function which shares this buffer, including
118 other threads.
119 Note: This function is not thread safe, because it shares a return buf‐
121 fer across all threads, and many other functions in this library.
122 Example: This function is intended to be used in a fashion similar to
124 the following example:
125 if (linkat(old_fildes, old_path, new_fildes, new_path, flags) <
126 0)
127 {
128 int err = errno;
129 fprintf(stderr, "%s\n", explain_errno_linkat(err,
130 old_fildes, old_path, new_fildes, new_path, flags));
131 exit(EXIT_FAILURE);
132 }
133 The above code example is available pre-packaged as the
135 explain_linkat_or_die(3) function.
136 explain_message_linkat
138 void explain_message_linkat(char *message, int message_size, int
139 old_fildes, const char *old_path, int new_fildes, const char *new_path,
140 int flags);
141 The explain_message_linkat function is used to obtain an explanation of
143 an error returned by the linkat(2) system call. The least the message
144 will contain is the value of strerror(errno), but usually it will do
145 much better, and indicate the underlying cause in more detail.
146 The errno global variable will be used to obtain the error value to be
148 decoded.
149 message The location in which to store the returned message. If a suit‐
151 able message return buffer is supplied, this function is thread
152 safe.
153 message_size
155 The size in bytes of the location in which to store the
156 returned message.
157 old_fildes
159 The original old_fildes, exactly as passed to the linkat(2)
160 system call.
161 old_path
163 The original old_path, exactly as passed to the linkat(2) sys‐
164 tem call.
165 new_fildes
167 The original new_fildes, exactly as passed to the linkat(2)
168 system call.
169 new_path
171 The original new_path, exactly as passed to the linkat(2) sys‐
172 tem call.
173 flags The original flags, exactly as passed to the linkat(2) system
175 call.
176 Example: This function is intended to be used in a fashion similar to
178 the following example:
179 if (linkat(old_fildes, old_path, new_fildes, new_path, flags) <
180 0)
181 {
182 char message[3000];
183 explain_message_linkat(message, sizeof(message), old_fildes,
184 old_path, new_fildes, new_path, flags);
185 fprintf(stderr, "%s\n", message);
186 exit(EXIT_FAILURE);
187 }
188 The above code example is available pre-packaged as the
190 explain_linkat_or_die(3) function.
191 explain_message_errno_linkat
193 void explain_message_errno_linkat(char *message, int message_size, int
194 errnum, int old_fildes, const char *old_path, int new_fildes, const
195 char *new_path, int flags);
196 The explain_message_errno_linkat function is used to obtain an explana‐
198 tion of an error returned by the linkat(2) system call. The least the
199 message will contain is the value of strerror(errno), but usually it
200 will do much better, and indicate the underlying cause in more detail.
201 message The location in which to store the returned message. If a suit‐
203 able message return buffer is supplied, this function is thread
204 safe.
205 message_size
207 The size in bytes of the location in which to store the
208 returned message.
209 errnum The error value to be decoded, usually obtained from the errno
211 global variable just before this function is called. This is
212 necessary if you need to call any code between the system call
213 to be explained and this function, because many libc functions
214 will alter the value of errno.
215 old_fildes
217 The original old_fildes, exactly as passed to the linkat(2)
218 system call.
219 old_path
221 The original old_path, exactly as passed to the linkat(2) sys‐
222 tem call.
223 new_fildes
225 The original new_fildes, exactly as passed to the linkat(2)
226 system call.
227 new_path
229 The original new_path, exactly as passed to the linkat(2) sys‐
230 tem call.
231 flags The original flags, exactly as passed to the linkat(2) system
233 call.
234 Example: This function is intended to be used in a fashion similar to
236 the following example:
237 if (linkat(old_fildes, old_path, new_fildes, new_path, flags) <
238 0)
239 {
240 int err = errno;
241 char message[3000];
242 explain_message_errno_linkat(message, sizeof(message), err,
243 old_fildes, old_path, new_fildes, new_path, flags);
244 fprintf(stderr, "%s\n", message);
245 exit(EXIT_FAILURE);
246 }
247 The above code example is available pre-packaged as the
249 explain_linkat_or_die(3) function.
250
252 linkat(2)
253 create a file link relative to directory file descriptors
254 explain_linkat_or_die(3)
256 create a file link relative to directory file descriptors and
257 report errors
258
260 libexplain version 1.4
261 Copyright (C) 2013 Peter Miller
262 explain_linkat(3)