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

NAME

6       explain_chown - explain chown(2) errors
7

SYNOPSIS

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

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the chown(2) system call.
21
22   explain_chown
23       const char *explain_chown(const char *pathname, int owner, int group);
24
25       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
30       The errno global variable will be used to obtain the error value to  be
31       decoded.
32
33       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
41       pathname
42               The original pathname, exactly as passed to the chown(2) system
43               call.
44
45       owner   The  original  owner,  exactly as passed to the chown(2) system
46               call.
47
48       group   The original group, exactly as passed to  the  chown(2)  system
49               call.
50
51       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
58       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
61   explain_errno_chown
62       const char *explain_errno_chown(int errnum, const char  *pathname,  int
63       owner, int group);
64
65       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
70       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
80       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
86       pathname
87               The original pathname, exactly as passed to the chown(2) system
88               call.
89
90       owner   The original owner, exactly as passed to  the  chown(2)  system
91               call.
92
93       group   The  original  group,  exactly as passed to the chown(2) system
94               call.
95
96       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
103       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
106   explain_message_chown
107       void  explain_message_chown(char *message, int message_size, const char
108       *pathname, int owner, int group);
109
110       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
115       The  errno global variable will be used to obtain the error value to be
116       decoded.
117
118       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
128       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
132       message_size
133               The  size  in  bytes  of  the  location  in  which to store the
134               returned message.
135
136       pathname
137               The original pathname, exactly as passed to the chown(2) system
138               call.
139
140       owner   The  original  owner,  exactly as passed to the chown(2) system
141               call.
142
143       group   The original group, exactly as passed to  the  chown(2)  system
144               call.
145
146   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
150       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
156       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
168       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
172       message_size
173               The  size  in  bytes  of  the  location  in  which to store the
174               returned message.
175
176       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
182       pathname
183               The original pathname, exactly as passed to the chown(2) system
184               call.
185
186       owner   The  original  owner,  exactly as passed to the chown(2) system
187               call.
188
189       group   The original group, exactly as passed to  the  chown(2)  system
190               call.
191

SEE ALSO

193       chown(2)
194               change ownership of a file
195
196       explain_chown_or_die(3)
197               change ownership of a file and report errors
198
200       libexplain version 0.40
201       Copyright (C) 2008 Peter Miller
202
203
204
205                                                              explain_chown(3)
Impressum