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

NAME

6       explain_lchown - explain lchown(2) errors
7

SYNOPSIS

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

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the lchown(2) system call.
21
22   explain_lchown
23       const char *explain_lchown(const char *pathname, int owner, int group);
24
25       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
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 (lchown(pathname, owner, group) < 0)
36              {
37                  fprintf(stderr, "%s\n", explain_lchown(pathname, owner, group));
38                  exit(EXIT_FAILURE);
39              }
40
41       pathname
42               The original pathname, exactly as passed to the lchown(2)  sys‐
43               tem call.
44
45       owner   The  original  owner, exactly as passed to the lchown(2) system
46               call.
47
48       group   The original group, exactly as passed to the  lchown(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_lchown
62       const char *explain_errno_lchown(int errnum, const char *pathname,  int
63       owner, int group);
64
65       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
70       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
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 lchown(2) sys‐
88               tem call.
89
90       owner   The original owner, exactly as passed to the  lchown(2)  system
91               call.
92
93       group   The  original  group, exactly as passed to the lchown(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_lchown
107       void explain_message_lchown(char *message, int message_size, const char
108       *pathname, int owner, int group);
109
110       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
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 (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
129       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
133       message_size
134               The  size  in  bytes  of  the  location  in  which to store the
135               returned message.
136
137       pathname
138               The original pathname, exactly as passed to the lchown(2)  sys‐
139               tem call.
140
141       owner   The  original  owner, exactly as passed to the lchown(2) system
142               call.
143
144       group   The original group, exactly as passed to the  lchown(2)  system
145               call.
146
147   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
151       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
157       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
169       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
173       message_size
174               The  size  in  bytes  of  the  location  in  which to store the
175               returned message.
176
177       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
183       pathname
184               The original pathname, exactly as passed to the lchown(2)  sys‐
185               tem call.
186
187       owner   The  original  owner, exactly as passed to the lchown(2) system
188               call.
189
190       group   The original group, exactly as passed to the  lchown(2)  system
191               call.
192

SEE ALSO

194       lchown(2)
195               change ownership of a file
196
197       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
204
205
206                                                             explain_lchown(3)
Impressum