1explain_chown(3) Library Functions Manual explain_chown(3)
2
6 explain_chown - explain chown(2) errors
7
9 #include <libexplain/chown.h>
10 const char *explain_chown(const char *pathname, int owner, int group);
11 const char *explain_errno_chown(int errnum, const char *pathname, int
12 owner, int group);
13 void explain_message_chown(char *message, int message_size, const char
14 *pathname, int owner, int group);
15 void explain_message_errno_chown(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 chown(2) system call.
21 explain_chown
23 const char *explain_chown(const char *pathname, int owner, int group);
24 The explain_chown function is used to obtain an explanation of an error
26 returned by the chown(2) system call. The least the message will con‐
27 tain is the value of strerror(errno), but usually it will do much bet‐
28 ter, 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 (chown(pathname, owner, group) < 0)
36 {
37 fprintf(stderr, "%s\n", explain_chown(pathname, owner, group));
38 exit(EXIT_FAILURE);
39 }
40 pathname
42 The original pathname, exactly as passed to the chown(2) system
43 call.
44 owner The original owner, exactly as passed to the chown(2) system
46 call.
47 group The original group, exactly as passed to the chown(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_chown
62 const char *explain_errno_chown(int errnum, const char *pathname, int
63 owner, int group);
64 The explain_errno_chown function is used to obtain an explanation of an
66 error returned by the chown(2) system call. The least the message will
67 contain is the value of strerror(errnum), but usually it will do much
68 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 (chown(pathname, owner, group) < 0)
73 {
74 int err = errno;
75 fprintf(stderr, "%s\n", explain_errno_chown(err, pathname, owner,
76 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 chown(2) system
88 call.
89 owner The original owner, exactly as passed to the chown(2) system
91 call.
92 group The original group, exactly as passed to the chown(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_chown
107 void explain_message_chown(char *message, int message_size, const char
108 *pathname, int owner, int group);
109 The explain_message_chown function may be used to obtain an explana‐
111 tion of an error returned by the chown(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 (chown(pathname, owner, group) < 0)
121 {
122 char message[3000];
123 explain_message_chown(message, sizeof(message), pathname, owner, group);
124 fprintf(stderr, "%s\n", message);
125 exit(EXIT_FAILURE);
126 }
127 message The location in which to store the returned message. If a
129 suitable message return buffer is supplied, this function is
130 thread safe.
131 message_size
133 The size in bytes of the location in which to store the
134 returned message.
135 pathname
137 The original pathname, exactly as passed to the chown(2) system
138 call.
139 owner The original owner, exactly as passed to the chown(2) system
141 call.
142 group The original group, exactly as passed to the chown(2) system
144 call.
145 explain_message_errno_chown
147 void explain_message_errno_chown(char *message, int message_size, int
148 errnum, const char *pathname, int owner, int group);
149 The explain_message_errno_chown function may be used to obtain an
151 explanation of an error returned by the chown(2) system call. The
152 least the message will contain is the value of strerror(errnum), but
153 usually it will do much better, and indicate the underlying cause in
154 more detail.
155 This function is intended to be used in a fashion similar to the fol‐
157 lowing example:
158 if (chown(pathname, owner, group) < 0)
159 {
160 int err = errno;
161 char message[3000];
162 explain_message_errno_chown(message, sizeof(message), err,
163 pathname, owner, group);
164 fprintf(stderr, "%s\n", message);
165 exit(EXIT_FAILURE);
166 }
167 message The location in which to store the returned message. If a
169 suitable message return buffer is supplied, this function is
170 thread safe.
171 message_size
173 The size in bytes of the location in which to store the
174 returned message.
175 errnum The error value to be decoded, usually obtained from the errno
177 global variable just before this function is called. This is
178 necessary if you need to call any code between the system call
179 to be explained and this function, because many libc functions
180 will alter the value of errno.
181 pathname
183 The original pathname, exactly as passed to the chown(2) system
184 call.
185 owner The original owner, exactly as passed to the chown(2) system
187 call.
188 group The original group, exactly as passed to the chown(2) system
190 call.
191
193 chown(2)
194 change ownership of a file
195 explain_chown_or_die(3)
197 change ownership of a file and report errors
198
200 libexplain version 1.4
201 Copyright (C) 2008 Peter Miller
202 explain_chown(3)