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

NAME

6       explain_access - explain access(2) errors
7

SYNOPSIS

9       #include <libexplain/access.h>
10       const char *explain_access(const char *pathname, int mode);
11       const  char *explain_errno_access(int errnum, const char *pathname, int
12       mode);
13       void explain_message_access(char *message, int message_size, const char
14       *pathname, int mode);
15       void  explain_message_errno_access(char *message, int message_size, int
16       errnum, const char *pathname, int mode);
17

DESCRIPTION

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

AUTHOR

186       Written by Peter Miller <pmiller@opensource.org.au>
187
188
189
190                                                             explain_access(3)
Impressum