1explain_acl_to_text(3) Library Functions Manual explain_acl_to_text(3)
2
6 explain_acl_to_text - explain acl_to_text(3) errors
7
9 #include <libexplain/acl_to_text.h>
10 const char *explain_acl_to_text(acl_t acl, ssize_t *len_p);
11 const char *explain_errno_acl_to_text(int errnum, acl_t acl, ssize_t
12 *len_p);
13 void explain_message_acl_to_text(char *message, int message_size, acl_t
14 acl, ssize_t *len_p);
15 void explain_message_errno_acl_to_text(char *message, int message_size,
16 int errnum, acl_t acl, ssize_t *len_p);
17
19 These functions may be used to obtain explanations for errors returned
20 by the acl_to_text(3) system call.
21 explain_acl_to_text
23 const char *explain_acl_to_text(acl_t acl, ssize_t *len_p);
24 The explain_acl_to_text function is used to obtain an explanation of an
26 error returned by the acl_to_text(3) 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 The errno global variable will be used to obtain the error value to be
31 decoded.
32 acl The original acl, exactly as passed to the acl_to_text(3) sys‐
34 tem call.
35 len_p The original len_p, exactly as passed to the acl_to_text(3)
37 system call.
38 Returns:
40 The message explaining the error. This message buffer is shared
41 by all libexplain functions which do not supply a buffer in
42 their argument list. This will be overwritten by the next call
43 to any libexplain function which shares this buffer, including
44 other threads.
45 Note: This function is not thread safe, because it shares a return buf‐
47 fer across all threads, and many other functions in this library.
48 Example: This function is intended to be used in a fashion similar to
50 the following example:
51 char *result = acl_to_text(acl, len_p);
52 if (!result)
53 {
54 fprintf(stderr, "%s\n", explain_acl_to_text(acl, len_p));
55 exit(EXIT_FAILURE);
56 }
57 The above code example is available pre-packaged as the
59 explain_acl_to_text_or_die(3) function.
60 explain_errno_acl_to_text
62 const char *explain_errno_acl_to_text(int errnum, acl_t acl, ssize_t
63 *len_p);
64 The explain_errno_acl_to_text function is used to obtain an explanation
66 of an error returned by the acl_to_text(3) system call. The least the
67 message will contain is the value of strerror(errno), but usually it
68 will do much better, and indicate the underlying cause in more detail.
69 errnum The error value to be decoded, usually obtained from the errno
71 global variable just before this function is called. This is
72 necessary if you need to call any code between the system call
73 to be explained and this function, because many libc functions
74 will alter the value of errno.
75 acl The original acl, exactly as passed to the acl_to_text(3) sys‐
77 tem call.
78 len_p The original len_p, exactly as passed to the acl_to_text(3)
80 system call.
81 Returns:
83 The message explaining the error. This message buffer is shared
84 by all libexplain functions which do not supply a buffer in
85 their argument list. This will be overwritten by the next call
86 to any libexplain function which shares this buffer, including
87 other threads.
88 Note: This function is not thread safe, because it shares a return buf‐
90 fer across all threads, and many other functions in this library.
91 Example: This function is intended to be used in a fashion similar to
93 the following example:
94 char *result = acl_to_text(acl, len_p);
95 if (!result)
96 {
97 int err = errno;
98 fprintf(stderr, "%s\n", explain_errno_acl_to_text(err, acl,
99 len_p));
100 exit(EXIT_FAILURE);
101 }
102 The above code example is available pre-packaged as the
104 explain_acl_to_text_or_die(3) function.
105 explain_message_acl_to_text
107 void explain_message_acl_to_text(char *message, int message_size, acl_t
108 acl, ssize_t *len_p);
109 The explain_message_acl_to_text function is used to obtain an explana‐
111 tion of an error returned by the acl_to_text(3) system call. The least
112 the message will contain is the value of strerror(errno), but usually
113 it will do much better, and indicate the underlying cause in more
114 detail.
115 The errno global variable will be used to obtain the error value to be
117 decoded.
118 message The location in which to store the returned message. If a suit‐
120 able message return buffer is supplied, this function is thread
121 safe.
122 message_size
124 The size in bytes of the location in which to store the
125 returned message.
126 acl The original acl, exactly as passed to the acl_to_text(3) sys‐
128 tem call.
129 len_p The original len_p, exactly as passed to the acl_to_text(3)
131 system call.
132 Example: This function is intended to be used in a fashion similar to
134 the following example:
135 char *result = acl_to_text(acl, len_p);
136 if (!result)
137 {
138 char message[3000];
139 explain_message_acl_to_text(message, sizeof(message), acl,
140 len_p);
141 fprintf(stderr, "%s\n", message);
142 exit(EXIT_FAILURE);
143 }
144 The above code example is available pre-packaged as the
146 explain_acl_to_text_or_die(3) function.
147 explain_message_errno_acl_to_text
149 void explain_message_errno_acl_to_text(char *message, int message_size,
150 int errnum, acl_t acl, ssize_t *len_p);
151 The explain_message_errno_acl_to_text function is used to obtain an
153 explanation of an error returned by the acl_to_text(3) system call.
154 The least the message will contain is the value of strerror(errno), but
155 usually it will do much better, and indicate the underlying cause in
156 more detail.
157 message The location in which to store the returned message. If a suit‐
159 able message return buffer is supplied, this function is thread
160 safe.
161 message_size
163 The size in bytes of the location in which to store the
164 returned message.
165 errnum The error value to be decoded, usually obtained from the errno
167 global variable just before this function is called. This is
168 necessary if you need to call any code between the system call
169 to be explained and this function, because many libc functions
170 will alter the value of errno.
171 acl The original acl, exactly as passed to the acl_to_text(3) sys‐
173 tem call.
174 len_p The original len_p, exactly as passed to the acl_to_text(3)
176 system call.
177 Example: This function is intended to be used in a fashion similar to
179 the following example:
180 char *result = acl_to_text(acl, len_p);
181 if (!result)
182 {
183 int err = errno;
184 char message[3000];
185 explain_message_errno_acl_to_text(message, sizeof(message),
186 err, acl, len_p);
187 fprintf(stderr, "%s\n", message);
188 exit(EXIT_FAILURE);
189 }
190 The above code example is available pre-packaged as the
192 explain_acl_to_text_or_die(3) function.
193
195 acl_to_text(3)
196 convert an ACL to text
197 explain_acl_to_text_or_die(3)
199 convert an ACL to text and report errors
200
202 libexplain version 1.4
203 Copyright (C) 2013 Peter Miller
204 explain_acl_to_text(3)