1explain_fstatat(3) Library Functions Manual explain_fstatat(3)
2
6 explain_fstatat - explain fstatat(2) errors
7
9 #include <libexplain/fstatat.h>
10 const char *explain_fstatat(int fildes, const char *pathname, struct
11 stat *data, int flags);
12 const char *explain_errno_fstatat(int errnum, int fildes, const char
13 *pathname, struct stat *data, int flags);
14 void explain_message_fstatat(char *message, int message_size, int
15 fildes, const char *pathname, struct stat *data, int flags);
16 void explain_message_errno_fstatat(char *message, int message_size, int
17 errnum, int fildes, const char *pathname, struct stat *data, int
18 flags);
19
21 These functions may be used to obtain explanations for errors returned
22 by the fstatat(2) system call.
23 explain_fstatat
25 const char *explain_fstatat(int fildes, const char *pathname, struct
26 stat *data, int flags);
27 The explain_fstatat function is used to obtain an explanation of an
29 error returned by the fstatat(2) system call. The least the message
30 will contain is the value of strerror(errno), but usually it will do
31 much better, and indicate the underlying cause in more detail.
32 The errno global variable will be used to obtain the error value to be
34 decoded.
35 fildes The original fildes, exactly as passed to the fstatat(2) system
37 call.
38 pathname
40 The original pathname, exactly as passed to the fstatat(2) sys‐
41 tem call.
42 data The original data, exactly as passed to the fstatat(2) system
44 call.
45 flags The original flags, exactly as passed to the fstatat(2) system
47 call.
48 Returns:
50 The message explaining the error. This message buffer is shared
51 by all libexplain functions which do not supply a buffer in
52 their argument list. This will be overwritten by the next call
53 to any libexplain function which shares this buffer, including
54 other threads.
55 Note: This function is not thread safe, because it shares a return buf‐
57 fer across all threads, and many other functions in this library.
58 Example: This function is intended to be used in a fashion similar to
60 the following example:
61 if (fstatat(fildes, pathname, data, flags) < 0)
62 {
63 fprintf(stderr, "%s\n", explain_fstatat(fildes, pathname,
64 data, flags));
65 exit(EXIT_FAILURE);
66 }
67 The above code example is available pre-packaged as the
69 explain_fstatat_or_die(3) function.
70 explain_errno_fstatat
72 const char *explain_errno_fstatat(int errnum, int fildes, const char
73 *pathname, struct stat *data, int flags);
74 The explain_errno_fstatat function is used to obtain an explanation of
76 an error returned by the fstatat(2) system call. The least the message
77 will contain is the value of strerror(errno), but usually it will do
78 much better, and indicate the underlying cause in more detail.
79 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 fildes The original fildes, exactly as passed to the fstatat(2) system
87 call.
88 pathname
90 The original pathname, exactly as passed to the fstatat(2) sys‐
91 tem call.
92 data The original data, exactly as passed to the fstatat(2) system
94 call.
95 flags The original flags, exactly as passed to the fstatat(2) system
97 call.
98 Returns:
100 The message explaining the error. This message buffer is shared
101 by all libexplain functions which do not supply a buffer in
102 their argument list. This will be overwritten by the next call
103 to any libexplain function which shares this buffer, including
104 other threads.
105 Note: This function is not thread safe, because it shares a return buf‐
107 fer across all threads, and many other functions in this library.
108 Example: This function is intended to be used in a fashion similar to
110 the following example:
111 if (fstatat(fildes, pathname, data, flags) < 0)
112 {
113 int err = errno;
114 fprintf(stderr, "%s\n", explain_errno_fstatat(err, fildes,
115 pathname, data, flags));
116 exit(EXIT_FAILURE);
117 }
118 The above code example is available pre-packaged as the
120 explain_fstatat_or_die(3) function.
121 explain_message_fstatat
123 void explain_message_fstatat(char *message, int message_size, int
124 fildes, const char *pathname, struct stat *data, int flags);
125 The explain_message_fstatat function is used to obtain an explanation
127 of an error returned by the fstatat(2) system call. The least the mes‐
128 sage will contain is the value of strerror(errno), but usually it will
129 do much better, and indicate the underlying cause in more detail.
130 The errno global variable will be used to obtain the error value to be
132 decoded.
133 message The location in which to store the returned message. If a suit‐
135 able message return buffer is supplied, this function is thread
136 safe.
137 message_size
139 The size in bytes of the location in which to store the
140 returned message.
141 fildes The original fildes, exactly as passed to the fstatat(2) system
143 call.
144 pathname
146 The original pathname, exactly as passed to the fstatat(2) sys‐
147 tem call.
148 data The original data, exactly as passed to the fstatat(2) system
150 call.
151 flags The original flags, exactly as passed to the fstatat(2) system
153 call.
154 Example: This function is intended to be used in a fashion similar to
156 the following example:
157 if (fstatat(fildes, pathname, data, flags) < 0)
158 {
159 char message[3000];
160 explain_message_fstatat(message, sizeof(message), fildes,
161 pathname, data, flags);
162 fprintf(stderr, "%s\n", message);
163 exit(EXIT_FAILURE);
164 }
165 The above code example is available pre-packaged as the
167 explain_fstatat_or_die(3) function.
168 explain_message_errno_fstatat
170 void explain_message_errno_fstatat(char *message, int message_size, int
171 errnum, int fildes, const char *pathname, struct stat *data, int
172 flags);
173 The explain_message_errno_fstatat function is used to obtain an expla‐
175 nation of an error returned by the fstatat(2) system call. The least
176 the message will contain is the value of strerror(errno), but usually
177 it will do much better, and indicate the underlying cause in more
178 detail.
179 message The location in which to store the returned message. If a suit‐
181 able message return buffer is supplied, this function is thread
182 safe.
183 message_size
185 The size in bytes of the location in which to store the
186 returned message.
187 errnum The error value to be decoded, usually obtained from the errno
189 global variable just before this function is called. This is
190 necessary if you need to call any code between the system call
191 to be explained and this function, because many libc functions
192 will alter the value of errno.
193 fildes The original fildes, exactly as passed to the fstatat(2) system
195 call.
196 pathname
198 The original pathname, exactly as passed to the fstatat(2) sys‐
199 tem call.
200 data The original data, exactly as passed to the fstatat(2) system
202 call.
203 flags The original flags, exactly as passed to the fstatat(2) system
205 call.
206 Example: This function is intended to be used in a fashion similar to
208 the following example:
209 if (fstatat(fildes, pathname, data, flags) < 0)
210 {
211 int err = errno;
212 char message[3000];
213 explain_message_errno_fstatat(message, sizeof(message), err,
214 fildes, pathname, data, flags);
215 fprintf(stderr, "%s\n", message);
216 exit(EXIT_FAILURE);
217 }
218 The above code example is available pre-packaged as the
220 explain_fstatat_or_die(3) function.
221
223 fstatat(2)
224 get file status relative to a directory file descriptor
225 explain_fstatat_or_die(3)
227 get file status relative to a directory file descriptor and
228 report errors
229
231 libexplain version 1.4
232 Copyright (C) 2013 Peter Miller
233 explain_fstatat(3)