1explain_lchown(3) Library Functions Manual explain_lchown(3)
2
6 explain_lchown - explain lchown(2) errors
7
9 #include <libexplain/lchown.h>
10 const char *explain_lchown(const char *pathname, int owner, int group);
11 const char *explain_errno_lchown(int errnum, const char *pathname, int
12 owner, int group);
13 void explain_message_lchown(char *message, int message_size, const char
14 *pathname, int owner, int group);
15 void explain_message_errno_lchown(char *message, int message_size, int
16 errnum, const char *pathname, int owner, int group);
17
19 These functions may be used to obtain explanations for errors returned
20 by the lchown(2) system call.
21 explain_lchown
23 const char *explain_lchown(const char *pathname, int owner, int group);
24 The explain_lchown function is used to obtain an explanation of an
26 error returned by the lchown(2) system call. The least the message
27 will contain is the value of strerror(errno), but usually it will do
28 much better, and indicate the underlying cause in more detail.
29 The errno global variable will be used to obtain the error value to be
31 decoded.
32 This function is intended to be used in a fashion similar to the fol‐
34 lowing example:
35 if (lchown(pathname, owner, group) < 0)
36 {
37 fprintf(stderr, "%s\n", explain_lchown(pathname, owner, group));
38 exit(EXIT_FAILURE);
39 }
40 pathname
42 The original pathname, exactly as passed to the lchown(2) sys‐
43 tem call.
44 owner The original owner, exactly as passed to the lchown(2) system
46 call.
47 group The original group, exactly as passed to the lchown(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_lchown
62 const char *explain_errno_lchown(int errnum, const char *pathname, int
63 owner, int group);
64 The explain_errno_lchown function is used to obtain an explanation of
66 an error returned by the lchown(2) system call. The least the message
67 will contain is the value of strerror(errnum), but usually it will do
68 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 if (lchown(pathname, owner, group) < 0)
73 {
74 int err = errno;
75 fprintf(stderr, "%s\n", explain_errno_lchown(err,
76 pathname, owner, group));
77 exit(EXIT_FAILURE);
78 }
79 errnum The error value to be decoded, usually obtained 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 pathname
87 The original pathname, exactly as passed to the lchown(2) sys‐
88 tem call.
89 owner The original owner, exactly as passed to the lchown(2) system
91 call.
92 group The original group, exactly as passed to the lchown(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_lchown
107 void explain_message_lchown(char *message, int message_size, const char
108 *pathname, int owner, int group);
109 The explain_message_lchown function may be used to obtain an explana‐
111 tion of an error returned by the lchown(2) system call. The least the
112 message will contain is the value of strerror(errno), but usually it
113 will do much better, and indicate the underlying cause in more detail.
114 The errno global variable will be used to obtain the error value to be
116 decoded.
117 This function is intended to be used in a fashion similar to the fol‐
119 lowing example:
120 if (lchown(pathname, owner, group) < 0)
121 {
122 char message[3000];
123 explain_message_lchown(message, sizeof(message),
124 pathname, owner, group);
125 fprintf(stderr, "%s\n", message);
126 exit(EXIT_FAILURE);
127 }
128 message The location in which to store the returned message. If a
130 suitable message return buffer is 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 pathname
138 The original pathname, exactly as passed to the lchown(2) sys‐
139 tem call.
140 owner The original owner, exactly as passed to the lchown(2) system
142 call.
143 group The original group, exactly as passed to the lchown(2) system
145 call.
146 explain_message_errno_lchown
148 void explain_message_errno_lchown(char *message, int message_size, int
149 errnum, const char *pathname, int owner, int group);
150 The explain_message_errno_lchown function may be used to obtain an
152 explanation of an error returned by the lchown(2) system call. The
153 least the message will contain is the value of strerror(errnum), but
154 usually it will do much better, and indicate the underlying cause in
155 more detail.
156 This function is intended to be used in a fashion similar to the fol‐
158 lowing example:
159 if (lchown(pathname, owner, group) < 0)
160 {
161 int err = errno;
162 char message[3000];
163 explain_message_errno_lchown(message, sizeof(message), err,
164 pathname, owner, group);
165 fprintf(stderr, "%s\n", message);
166 exit(EXIT_FAILURE);
167 }
168 message The location in which to store the returned message. If a
170 suitable message return buffer is supplied, this function is
171 thread safe.
172 message_size
174 The size in bytes of the location in which to store the
175 returned message.
176 errnum The error value to be decoded, usually obtained from the errno
178 global variable just before this function is called. This is
179 necessary if you need to call any code between the system call
180 to be explained and this function, because many libc functions
181 will alter the value of errno.
182 pathname
184 The original pathname, exactly as passed to the lchown(2) sys‐
185 tem call.
186 owner The original owner, exactly as passed to the lchown(2) system
188 call.
189 group The original group, exactly as passed to the lchown(2) system
191 call.
192
194 lchown(2)
195 change ownership of a file
196 explain_lchown_or_die(3)
198 change ownership of a file and report errors
199
201 libexplain version 0.40
202 Copyright (C) 2008 Peter Miller
203 explain_lchown(3)