1explain_lchownat(3) Library Functions Manual explain_lchownat(3)
2
6 explain_lchownat - explain lchownat(2) errors
7
9 #include <libexplain/lchownat.h>
10 const char *explain_lchownat(int fildes, const char *pathname, int uid,
11 int gid);
12 const char *explain_errno_lchownat(int errnum, int fildes, const char
13 *pathname, int uid, int gid);
14 void explain_message_lchownat(char *message, int message_size, int
15 fildes, const char *pathname, int uid, int gid);
16 void explain_message_errno_lchownat(char *message, int message_size,
17 int errnum, int fildes, const char *pathname, int uid, int gid);
18
20 These functions may be used to obtain explanations for errors returned
21 by the lchownat(2) system call.
22 explain_lchownat
24 const char *explain_lchownat(int fildes, const char *pathname, int uid,
25 int gid);
26 The explain_lchownat function is used to obtain an explanation of an
28 error returned by the lchownat(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 fildes The original fildes, exactly as passed to the lchownat(2) sys‐
36 tem call.
37 pathname
39 The original pathname, exactly as passed to the lchownat(2)
40 system call.
41 uid The original uid, exactly as passed to the lchownat(2) system
43 call.
44 gid The original gid, exactly as passed to the lchownat(2) system
46 call.
47 Returns:
49 The message explaining the error. This message buffer is shared
50 by all libexplain functions which do not supply a buffer in
51 their argument list. This will be overwritten by the next call
52 to any libexplain function which shares this buffer, including
53 other threads.
54 Note: This function is not thread safe, because it shares a return buf‐
56 fer across all threads, and many other functions in this library.
57 Example: This function is intended to be used in a fashion similar to
59 the following example:
60 if (lchownat(fildes, pathname, uid, gid) < 0)
61 {
62 fprintf(stderr, "%s\n", explain_lchownat(fildes, pathname,
63 uid, gid));
64 exit(EXIT_FAILURE);
65 }
66 The above code example is available pre-packaged as the explain_lchow‐
68 nat_or_die(3) function.
69 explain_errno_lchownat
71 const char *explain_errno_lchownat(int errnum, int fildes, const char
72 *pathname, int uid, int gid);
73 The explain_errno_lchownat function is used to obtain an explanation of
75 an error returned by the lchownat(2) system call. The least the mes‐
76 sage will contain is the value of strerror(errno), but usually it will
77 do much better, and indicate the underlying cause in more detail.
78 errnum The error value to be decoded, usually obtained from the errno
80 global variable just before this function is called. This is
81 necessary if you need to call any code between the system call
82 to be explained and this function, because many libc functions
83 will alter the value of errno.
84 fildes The original fildes, exactly as passed to the lchownat(2) sys‐
86 tem call.
87 pathname
89 The original pathname, exactly as passed to the lchownat(2)
90 system call.
91 uid The original uid, exactly as passed to the lchownat(2) system
93 call.
94 gid The original gid, exactly as passed to the lchownat(2) system
96 call.
97 Returns:
99 The message explaining the error. This message buffer is shared
100 by all libexplain functions which do not supply a buffer in
101 their argument list. This will be overwritten by the next call
102 to any libexplain function which shares this buffer, including
103 other threads.
104 Note: This function is not thread safe, because it shares a return buf‐
106 fer across all threads, and many other functions in this library.
107 Example: This function is intended to be used in a fashion similar to
109 the following example:
110 if (lchownat(fildes, pathname, uid, gid) < 0)
111 {
112 int err = errno;
113 fprintf(stderr, "%s\n", explain_errno_lchownat(err, fildes,
114 pathname, uid, gid));
115 exit(EXIT_FAILURE);
116 }
117 The above code example is available pre-packaged as the explain_lchow‐
119 nat_or_die(3) function.
120 explain_message_lchownat
122 void explain_message_lchownat(char *message, int message_size, int
123 fildes, const char *pathname, int uid, int gid);
124 The explain_message_lchownat function is used to obtain an explanation
126 of an error returned by the lchownat(2) system call. The least the
127 message will contain is the value of strerror(errno), but usually it
128 will do much better, and indicate the underlying cause in more detail.
129 The errno global variable will be used to obtain the error value to be
131 decoded.
132 message The location in which to store the returned message. If a suit‐
134 able message return buffer is supplied, this function is thread
135 safe.
136 message_size
138 The size in bytes of the location in which to store the
139 returned message.
140 fildes The original fildes, exactly as passed to the lchownat(2) sys‐
142 tem call.
143 pathname
145 The original pathname, exactly as passed to the lchownat(2)
146 system call.
147 uid The original uid, exactly as passed to the lchownat(2) system
149 call.
150 gid The original gid, exactly as passed to the lchownat(2) system
152 call.
153 Example: This function is intended to be used in a fashion similar to
155 the following example:
156 if (lchownat(fildes, pathname, uid, gid) < 0)
157 {
158 char message[3000];
159 explain_message_lchownat(message, sizeof(message), fildes,
160 pathname, uid, gid);
161 fprintf(stderr, "%s\n", message);
162 exit(EXIT_FAILURE);
163 }
164 The above code example is available pre-packaged as the explain_lchow‐
166 nat_or_die(3) function.
167 explain_message_errno_lchownat
169 void explain_message_errno_lchownat(char *message, int message_size,
170 int errnum, int fildes, const char *pathname, int uid, int gid);
171 The explain_message_errno_lchownat function is used to obtain an expla‐
173 nation of an error returned by the lchownat(2) system call. The least
174 the message will contain is the value of strerror(errno), but usually
175 it will do much better, and indicate the underlying cause in more
176 detail.
177 message The location in which to store the returned message. If a suit‐
179 able message return buffer is supplied, this function is thread
180 safe.
181 message_size
183 The size in bytes of the location in which to store the
184 returned message.
185 errnum The error value to be decoded, usually obtained from the errno
187 global variable just before this function is called. This is
188 necessary if you need to call any code between the system call
189 to be explained and this function, because many libc functions
190 will alter the value of errno.
191 fildes The original fildes, exactly as passed to the lchownat(2) sys‐
193 tem call.
194 pathname
196 The original pathname, exactly as passed to the lchownat(2)
197 system call.
198 uid The original uid, exactly as passed to the lchownat(2) system
200 call.
201 gid The original gid, exactly as passed to the lchownat(2) system
203 call.
204 Example: This function is intended to be used in a fashion similar to
206 the following example:
207 if (lchownat(fildes, pathname, uid, gid) < 0)
208 {
209 int err = errno;
210 char message[3000];
211 explain_message_errno_lchownat(message, sizeof(message),
212 err, fildes, pathname, uid, gid);
213 fprintf(stderr, "%s\n", message);
214 exit(EXIT_FAILURE);
215 }
216 The above code example is available pre-packaged as the explain_lchow‐
218 nat_or_die(3) function.
219
221 lchownat(2)
222 Execute lchownat(2)
223 explain_lchownat_or_die(3)
225 Execute lchownat(2) and report errors
226
228 libexplain version 1.4
229 Copyright (C) 2013 Peter Miller
230 explain_lchownat(3)