1explain_fchown(3) Library Functions Manual explain_fchown(3)
2
6 explain_fchown - explain fchown(2) errors
7
9 #include <libexplain/fchown.h>
10 const char *explain_fchown(int fildes, int owner, int group);
11 const char *explain_errno_fchown(int errnum, int fildes, int owner, int
12 group);
13 void explain_message_fchown(char *message, int message_size, int
14 fildes, int owner, int group);
15 void explain_message_errno_fchown(char *message, int message_size, int
16 errnum, int fildes, int owner, int group);
17
19 These functions may be used to obtain explanations for errors returned
20 by the fchown(2) system call.
21 explain_fchown
23 const char *explain_fchown(int fildes, int owner, int group);
24 The explain_fchown function is used to obtain an explanation of an
26 error returned by the fchown(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 (fchown(fildes, owner, group) < 0)
36 {
37 fprintf(stderr, "%s\n", explain_fchown(fildes, owner, group));
38 exit(EXIT_FAILURE);
39 }
40 The above code example is available pre‐packaged as the
42 explain_fchown_or_die(3) function.
43 fildes The original fildes, exactly as passed to the fchown(2) system
45 call.
46 owner The original owner, exactly as passed to the fchown(2) system
48 call.
49 group The original group, exactly as passed to the fchown(2) system
51 call.
52 Returns:
54 The message explaining the error. This message buffer is
55 shared by all libexplain functions which do not supply a buffer
56 in their argument list. This will be overwritten by the next
57 call to any libexplain function which shares this buffer,
58 including other threads.
59 Note: This function is not thread safe, because it shares a return buf‐
61 fer across all threads, and many other functions in this library.
62 explain_errno_fchown
64 const char *explain_errno_fchown(int errnum, int fildes, int owner, int
65 group);
66 The explain_errno_fchown function is used to obtain an explanation of
68 an error returned by the fchown(2) system call. The least the message
69 will contain is the value of strerror(errnum), but usually it will do
70 much better, and indicate the underlying cause in more detail.
71 This function is intended to be used in a fashion similar to the fol‐
73 lowing example:
74 if (fchown(fildes, owner, group) < 0)
75 {
76 int err = errno;
77 fprintf(stderr, "%s\n",
78 explain_errno_fchown(err, fildes, owner, group));
79 exit(EXIT_FAILURE);
80 }
81 The above code example is available pre‐packaged as the
83 explain_fchown_or_die(3) function.
84 errnum The error value to be decoded, usually obtained from the errno
86 global variable just before this function is called. This is
87 necessary if you need to call any code between the system call
88 to be explained and this function, because many libc functions
89 will alter the value of errno.
90 fildes The original fildes, exactly as passed to the fchown(2) system
92 call.
93 owner The original owner, exactly as passed to the fchown(2) system
95 call.
96 group The original group, exactly as passed to the fchown(2) system
98 call.
99 Returns:
101 The message explaining the error. This message buffer is
102 shared by all libexplain functions which do not supply a buffer
103 in their argument list. This will be overwritten by the next
104 call to any libexplain function which shares this buffer,
105 including other threads.
106 Note: This function is not thread safe, because it shares a return buf‐
108 fer across all threads, and many other functions in this library.
109 explain_message_fchown
111 void explain_message_fchown(char *message, int message_size, int
112 fildes, int owner, int group);
113 The explain_message_fchown function may be used to obtain an explana‐
115 tion of an error returned by the fchown(2) system call. The least the
116 message will contain is the value of strerror(errno), but usually it
117 will do much better, and indicate the underlying cause in more detail.
118 The errno global variable will be used to obtain the error value to be
120 decoded.
121 This function is intended to be used in a fashion similar to the fol‐
123 lowing example:
124 if (fchown(fildes, owner, group) < 0)
125 {
126 char message[3000];
127 explain_message_fchown(message, sizeof(message), fildes, owner, group);
128 fprintf(stderr, "%s\n", message);
129 exit(EXIT_FAILURE);
130 }
131 The above code example is available pre‐packaged as the
133 explain_fchown_or_die(3) function.
134 message The location in which to store the returned message. If a
136 suitable message return buffer is supplied, this function is
137 thread safe.
138 message_size
140 The size in bytes of the location in which to store the
141 returned message.
142 fildes The original fildes, exactly as passed to the fchown(2) system
144 call.
145 owner The original owner, exactly as passed to the fchown(2) system
147 call.
148 group The original group, exactly as passed to the fchown(2) system
150 call.
151 explain_message_errno_fchown
153 void explain_message_errno_fchown(char *message, int message_size, int
154 errnum, int fildes, int owner, int group);
155 The explain_message_errno_fchown function may be used to obtain an
157 explanation of an error returned by the fchown(2) system call. The
158 least the message will contain is the value of strerror(errnum), but
159 usually it will do much better, and indicate the underlying cause in
160 more detail.
161 This function is intended to be used in a fashion similar to the fol‐
163 lowing example:
164 if (fchown(fildes, owner, group) < 0)
165 {
166 int err = errno;
167 char message[3000];
168 explain_message_errno_fchown(message, sizeof(message),
169 err, fildes, owner, group);
170 fprintf(stderr, "%s\n", message);
171 exit(EXIT_FAILURE);
172 }
173 The above code example is available pre‐packaged as the
175 explain_fchown_or_die(3) function.
176 message The location in which to store the returned message. If a
178 suitable message return buffer is supplied, this function is
179 thread safe.
180 message_size
182 The size in bytes of the location in which to store the
183 returned message.
184 errnum The error value to be decoded, usually obtained from the errno
186 global variable just before this function is called. This is
187 necessary if you need to call any code between the system call
188 to be explained and this function, because many libc functions
189 will alter the value of errno.
190 fildes The original fildes, exactly as passed to the fchown(2) system
192 call.
193 owner The original owner, exactly as passed to the fchown(2) system
195 call.
196 group The original group, exactly as passed to the fchown(2) system
198 call.
199
201 fchown(2)
202 change ownership of a file
203 explain_fchown_or_die(3)
205 change ownership of a file and report errors
206
208 libexplain version 0.40
209 Copyright (C) 2008 Peter Miller
210 explain_fchown(3)