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

NAME

6       explain_chmod - explain chmod(2) errors
7

SYNOPSIS

9       #include <libexplain/chmod.h>
10       const char *explain_chmod(const char *pathname, int mode);
11       const  char  *explain_errno_chmod(int errnum, const char *pathname, int
12       mode);
13       void explain_message_chmod(char *message, int message_size, const  char
14       *pathname, int mode);
15       void  explain_message_errno_chmod(char  *message, int message_size, int
16       errnum, const char *pathname, int mode);
17

DESCRIPTION

19       These functions may be used to otain explanations for chmod(2) errors.
20
21   explain_chmod
22       const char *explain_chmod(const char *pathname, int mode);
23
24       The explain_chmod function is used to obtain an explanation of an error
25       returned  by the chmod(2) system call.  The least the message will con‐
26       tain is the value of strerror(errno), but usually it will do much  bet‐
27       ter, and indicate the underlying cause in more detail.
28
29       The  errno global variable will be used to obtain the error value to be
30       decoded.
31
32       This function is intended to be used in a fashion similar to  the  fol‐
33       lowing example:
34              if (chmod(pathname, mode) < 0)
35              {
36                  fprintf(stderr, '%s0, explain_chmod(pathname, mode));
37                  exit(EXIT_FAILURE);
38              }
39
40       pathname
41               The original pathname, exactly as passed to the chmod(2) system
42               call.
43
44       mode    The original mode, exactly as passed  to  the  chmod(2)  system
45               call.
46
47       Returns:
48               The  message  explaining  the  error.   This  message buffer is
49               shared by all libexplain functions which do not supply a buffer
50               in  their  argument list.  This will be overwritten by the next
51               call to any  libexplain  function  which  shares  this  buffer,
52               including other threads.
53
54       Note: This function is not thread safe, because it shares a return buf‐
55       fer across all threads, and many other functions in this library.
56
57   explain_errno_chmod
58       const char *explain_errno_chmod(int errnum, const char  *pathname,  int
59       mode);
60
61       The explain_errno_chmod function is used to obtain an explanation of an
62       error returned by the chmod(2) system call.  The least the message will
63       contain  is  the value of strerror(errnum), but usually it will do much
64       better, and indicate the underlying cause in more detail.
65
66       This function is intended to be used in a fashion similar to  the  fol‐
67       lowing example:
68              if (chmod(pathname) < 0)
69              {
70                  int err = errno;
71                  fprintf(stderr, '%s0, explain_errno_chmod(err, pathname));
72                  exit(EXIT_FAILURE);
73              }
74
75       errnum  The  error value to be decoded, usually obtained from the errno
76               global variable just before this function is called.   This  is
77               necessary  if you need to call any code between the system call
78               to be explained and this function, because many libc  functions
79               will alter the value of errno.
80
81       pathname
82               The original pathname, exactly as passed to the chmod(2) system
83               call.
84
85       mode    The original mode, exactly as passed  to  the  chmod(2)  system
86               call.
87
88       Returns:
89               The  message  explaining  the  error.   This  message buffer is
90               shared by all libexplain functions which do not supply a buffer
91               in  their  argument list.  This will be overwritten by the next
92               call to any  libexplain  function  which  shares  this  buffer,
93               including other threads.
94
95       Note: This function is not thread safe, because it shares a return buf‐
96       fer across all threads, and many other functions in this library.
97
98   explain_message_chmod
99       void explain_message_chmod(char *message, int message_size, const  char
100       *pathname, int mode);
101
102       The  explain_message_chmod function is used to obtain an explanation of
103       an error returned by the chmod(2) system call.  The least  the  message
104       will  contain  is  the value of strerror(errno), but usually it will do
105       much better, and indicate the underlying cause in more detail.
106
107       The errno global variable will be used to obtain the error value to  be
108       decoded.
109
110       This  function  is intended to be used in a fashion similar to the fol‐
111       lowing example:
112              if (chmod(pathname, mode) < 0)
113              {
114                  char message[3000];
115                  explain_message_chmod(message, sizeof(message), pathname, mode);
116                  fprintf(stderr, '%s0, message);
117                  exit(EXIT_FAILURE);
118              }
119
120       message The location in which to store the returned message.  Because a
121               message  return  buffer  has  been  supplied,  this function is
122               thread safe.
123
124       message_size
125               The size in bytes  of  the  location  in  which  to  store  the
126               returned message.
127
128       pathname
129               The original pathname, exactly as passed to the chmod(2) system
130               call.
131
132       mode    The original mode, exactly as passed  to  the  chmod(2)  system
133               call.
134
135   explain_message_errno_chmod
136       void  explain_message_errno_chmod(char * message, int message_size, int
137       errnum, const char *pathname, int mode);
138
139       The explain_message_errno_chmod function is used to obtain an  explana‐
140       tion  of  an error returned by the chmod(2) system call.  The least the
141       message will contain is the value of strerror(errnum), but  usually  it
142       will do much better, and indicate the underlying cause in more detail.
143
144       This  function  is intended to be used in a fashion similar to the fol‐
145       lowing example:
146              if (chmod(pathname) < 0)
147              {
148                  int err = errno;
149                  char message[3000];
150                  explain_message_errno_chmod(message, sizeof(message), err,
151                      pathname);
152                  fprintf(stderr, '%s0, message);
153                  exit(EXIT_FAILURE);
154              }
155
156       message The location in which to store the returned message.  Because a
157               message  return  buffer  has  been  supplied,  this function is
158               thread safe.
159
160       message_size
161               The size in bytes  of  the  location  in  which  to  store  the
162               returned message.
163
164       errnum  The  error value to be decoded, usually obtained from the errno
165               global variable just before this function is called.   This  is
166               necessary  if you need to call any code between the system call
167               to be explained and this function, because many libc  functions
168               will alter the value of errno.
169
170       pathname
171               The original pathname, exactly as passed to the chmod(2) system
172               call.
173
174       mode    The original mode, exactly as passed  to  the  chmod(2)  system
175               call.
176
178       libexplain version 1.4
179       Copyright (C) 2008 Peter Miller
180

AUTHOR

182       Written by Peter Miller <pmiller@opensource.org.au>
183
184
185
186                                                              explain_chmod(3)
Impressum