1explain_fchownat(3)        Library Functions Manual        explain_fchownat(3)
2
3
4

NAME

6       explain_fchownat - explain fchownat(2) errors
7

SYNOPSIS

9       #include <libexplain/fchownat.h>
10       const char *explain_fchownat(int dirfd, const char *pathname, int
11       owner, int group, int flags);
12       const char *explain_errno_fchownat(int errnum, int dirfd, const char
13       *pathname, int owner, int group, int flags);
14       void explain_message_fchownat(char *message, int message_size, int
15       dirfd, const char *pathname, int owner, int group, int flags);
16       void explain_message_errno_fchownat(char *message, int message_size,
17       int errnum, int dirfd, const char *pathname, int owner, int group, int
18       flags);
19

DESCRIPTION

21       These functions may be used to obtain explanations for errors  returned
22       by the fchownat(2) system call.
23
24   explain_fchownat
25       const char *explain_fchownat(int dirfd, const char *pathname, int
26       owner, int group, int flags);
27
28       The explain_fchownat function is used to obtain an  explanation  of  an
29       error  returned  by  the fchownat(2) system call. The least the message
30       will contain is the value of strerror(errno), but usually  it  will  do
31       much better, and indicate the underlying cause in more detail.
32
33       The  errno global variable will be used to obtain the error value to be
34       decoded.
35
36       dirfd   The original dirfd, exactly as passed to the fchownat(2) system
37               call.
38
39       pathname
40               The  original  pathname,  exactly  as passed to the fchownat(2)
41               system call.
42
43       owner   The original owner, exactly as passed to the fchownat(2) system
44               call.
45
46       group   The original group, exactly as passed to the fchownat(2) system
47               call.
48
49       flags   The original flags, exactly as passed to the fchownat(2) system
50               call.
51
52       Returns:
53               The message explaining the error. This message buffer is shared
54               by all libexplain functions which do not  supply  a  buffer  in
55               their argument list.  This will be overwritten by the next call
56               to any libexplain function which shares this buffer,  including
57               other threads.
58
59       Note: This function is not thread safe, because it shares a return buf‐
60       fer across all threads, and many other functions in this library.
61
62       Example: This function is intended to be used in a fashion  similar  to
63       the following example:
64              if (fchownat(dirfd, pathname, owner, group, flags) < 0)
65              {
66                  fprintf(stderr, "%s\n", explain_fchownat(dirfd, pathname,
67                  owner, group, flags));
68                  exit(EXIT_FAILURE);
69              }
70
71       The above code example is available pre-packaged as the  explain_fchow‐
72       nat_or_die(3) function.
73
74   explain_errno_fchownat
75       const char *explain_errno_fchownat(int errnum, int dirfd, const char
76       *pathname, int owner, int group, int flags);
77
78       The explain_errno_fchownat function is used to obtain an explanation of
79       an  error  returned by the fchownat(2) system call.  The least the mes‐
80       sage will contain is the value of strerror(errno), but usually it  will
81       do much better, and indicate the underlying cause in more detail.
82
83       errnum  The  error value to be decoded, usually obtained from the errno
84               global variable just before this function is  called.  This  is
85               necessary  if you need to call any code between the system call
86               to be explained and this function, because many libc  functions
87               will alter the value of errno.
88
89       dirfd   The original dirfd, exactly as passed to the fchownat(2) system
90               call.
91
92       pathname
93               The original pathname, exactly as  passed  to  the  fchownat(2)
94               system call.
95
96       owner   The original owner, exactly as passed to the fchownat(2) system
97               call.
98
99       group   The original group, exactly as passed to the fchownat(2) system
100               call.
101
102       flags   The original flags, exactly as passed to the fchownat(2) system
103               call.
104
105       Returns:
106               The message explaining the error. This message buffer is shared
107               by  all  libexplain  functions  which do not supply a buffer in
108               their argument list.  This will be overwritten by the next call
109               to  any libexplain function which shares this buffer, including
110               other threads.
111
112       Note: This function is not thread safe, because it shares a return buf‐
113       fer across all threads, and many other functions in this library.
114
115       Example:  This  function is intended to be used in a fashion similar to
116       the following example:
117              if (fchownat(dirfd, pathname, owner, group, flags) < 0)
118              {
119                  int err = errno;
120                  fprintf(stderr, "%s\n", explain_errno_fchownat(err, dirfd,
121                  pathname, owner, group, flags));
122                  exit(EXIT_FAILURE);
123              }
124
125       The  above code example is available pre-packaged as the explain_fchow‐
126       nat_or_die(3) function.
127
128   explain_message_fchownat
129       void explain_message_fchownat(char *message, int message_size, int
130       dirfd, const char *pathname, int owner, int group, int flags);
131
132       The  explain_message_fchownat function is used to obtain an explanation
133       of an error returned by the fchownat(2) system  call.   The  least  the
134       message  will  contain  is the value of strerror(errno), but usually it
135       will do much better, and indicate the underlying cause in more detail.
136
137       The errno global variable will be used to obtain the error value to  be
138       decoded.
139
140       message The location in which to store the returned message. If a suit‐
141               able message return buffer is supplied, this function is thread
142               safe.
143
144       message_size
145               The  size  in  bytes  of  the  location  in  which to store the
146               returned message.
147
148       dirfd   The original dirfd, exactly as passed to the fchownat(2) system
149               call.
150
151       pathname
152               The  original  pathname,  exactly  as passed to the fchownat(2)
153               system call.
154
155       owner   The original owner, exactly as passed to the fchownat(2) system
156               call.
157
158       group   The original group, exactly as passed to the fchownat(2) system
159               call.
160
161       flags   The original flags, exactly as passed to the fchownat(2) system
162               call.
163
164       Example:  This  function is intended to be used in a fashion similar to
165       the following example:
166              if (fchownat(dirfd, pathname, owner, group, flags) < 0)
167              {
168                  char message[3000];
169                  explain_message_fchownat(message, sizeof(message), dirfd,
170                  pathname, owner, group, flags);
171                  fprintf(stderr, "%s\n", message);
172                  exit(EXIT_FAILURE);
173              }
174
175       The  above code example is available pre-packaged as the explain_fchow‐
176       nat_or_die(3) function.
177
178   explain_message_errno_fchownat
179       void explain_message_errno_fchownat(char *message, int message_size,
180       int errnum, int dirfd, const char *pathname, int owner, int group, int
181       flags);
182
183       The explain_message_errno_fchownat function is used to obtain an expla‐
184       nation  of an error returned by the fchownat(2) system call.  The least
185       the message will contain is the value of strerror(errno),  but  usually
186       it  will  do  much  better,  and  indicate the underlying cause in more
187       detail.
188
189       message The location in which to store the returned message. If a suit‐
190               able message return buffer is supplied, this function is thread
191               safe.
192
193       message_size
194               The size in bytes  of  the  location  in  which  to  store  the
195               returned message.
196
197       errnum  The  error value to be decoded, usually obtained from the errno
198               global variable just before this function is  called.  This  is
199               necessary  if you need to call any code between the system call
200               to be explained and this function, because many libc  functions
201               will alter the value of errno.
202
203       dirfd   The original dirfd, exactly as passed to the fchownat(2) system
204               call.
205
206       pathname
207               The original pathname, exactly as  passed  to  the  fchownat(2)
208               system call.
209
210       owner   The original owner, exactly as passed to the fchownat(2) system
211               call.
212
213       group   The original group, exactly as passed to the fchownat(2) system
214               call.
215
216       flags   The original flags, exactly as passed to the fchownat(2) system
217               call.
218
219       Example: This function is intended to be used in a fashion  similar  to
220       the following example:
221              if (fchownat(dirfd, pathname, owner, group, flags) < 0)
222              {
223                  int err = errno;
224                  char message[3000];
225                  explain_message_errno_fchownat(message, sizeof(message),
226                  err, dirfd, pathname, owner, group, flags);
227                  fprintf(stderr, "%s\n", message);
228                  exit(EXIT_FAILURE);
229              }
230
231       The above code example is available pre-packaged as the  explain_fchow‐
232       nat_or_die(3) function.
233

SEE ALSO

235       fchownat(2)
236               change ownership of a file relative to a directory
237
238       explain_fchownat_or_die(3)
239               change  ownership  of a file relative to a directory and report
240               errors
241
243       libexplain version 1.4
244       Copyright (C) 2013 Peter Miller
245
246
247
248                                                           explain_fchownat(3)
Impressum