1explain_futimesat(3) Library Functions Manual explain_futimesat(3)
2
6 explain_futimesat - explain futimesat(2) errors
7
9 #include <libexplain/futimesat.h>
10 const char *explain_futimesat(int fildes, const char *pathname, const
11 struct timeval *data);
12 const char *explain_errno_futimesat(int errnum, int fildes, const char
13 *pathname, const struct timeval *data);
14 void explain_message_futimesat(char *message, int message_size, int
15 fildes, const char *pathname, const struct timeval *data);
16 void explain_message_errno_futimesat(char *message, int message_size,
17 int errnum, int fildes, const char *pathname, const struct timeval
18 *data);
19
21 These functions may be used to obtain explanations for errors returned
22 by the futimesat(2) system call.
23 explain_futimesat
25 const char *explain_futimesat(int fildes, const char *pathname, const
26 struct timeval *data);
27 The explain_futimesat function is used to obtain an explanation of an
29 error returned by the futimesat(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 futimesat(2) sys‐
37 tem call.
38 pathname
40 The original pathname, exactly as passed to the futimesat(2)
41 system call.
42 data The original data, exactly as passed to the futimesat(2) system
44 call.
45 Returns:
47 The message explaining the error. This message buffer is shared
48 by all libexplain functions which do not supply a buffer in
49 their argument list. This will be overwritten by the next call
50 to any libexplain function which shares this buffer, including
51 other threads.
52 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 Example: This function is intended to be used in a fashion similar to
57 the following example:
58 if (futimesat(fildes, pathname, data) < 0)
59 {
60 fprintf(stderr, "%s\n", explain_futimesat(fildes, pathname,
61 data));
62 exit(EXIT_FAILURE);
63 }
64 The above code example is available pre-packaged as the explain_futime‐
66 sat_or_die(3) function.
67 explain_errno_futimesat
69 const char *explain_errno_futimesat(int errnum, int fildes, const char
70 *pathname, const struct timeval *data);
71 The explain_errno_futimesat function is used to obtain an explanation
73 of an error returned by the futimesat(2) system call. The least the
74 message will contain is the value of strerror(errno), but usually it
75 will do much better, and indicate the underlying cause in more detail.
76 errnum The error value to be decoded, usually obtained from the errno
78 global variable just before this function is called. This is
79 necessary if you need to call any code between the system call
80 to be explained and this function, because many libc functions
81 will alter the value of errno.
82 fildes The original fildes, exactly as passed to the futimesat(2) sys‐
84 tem call.
85 pathname
87 The original pathname, exactly as passed to the futimesat(2)
88 system call.
89 data The original data, exactly as passed to the futimesat(2) system
91 call.
92 Returns:
94 The message explaining the error. This message buffer is shared
95 by all libexplain functions which do not supply a buffer in
96 their argument list. This will be overwritten by the next call
97 to any libexplain function which shares this buffer, including
98 other threads.
99 Note: This function is not thread safe, because it shares a return buf‐
101 fer across all threads, and many other functions in this library.
102 Example: This function is intended to be used in a fashion similar to
104 the following example:
105 if (futimesat(fildes, pathname, data) < 0)
106 {
107 int err = errno;
108 fprintf(stderr, "%s\n", explain_errno_futimesat(err, fildes,
109 pathname, data));
110 exit(EXIT_FAILURE);
111 }
112 The above code example is available pre-packaged as the explain_futime‐
114 sat_or_die(3) function.
115 explain_message_futimesat
117 void explain_message_futimesat(char *message, int message_size, int
118 fildes, const char *pathname, const struct timeval *data);
119 The explain_message_futimesat function is used to obtain an explanation
121 of an error returned by the futimesat(2) system call. The least the
122 message will contain is the value of strerror(errno), but usually it
123 will do much better, and indicate the underlying cause in more detail.
124 The errno global variable will be used to obtain the error value to be
126 decoded.
127 message The location in which to store the returned message. If a suit‐
129 able message return buffer is supplied, this function is thread
130 safe.
131 message_size
133 The size in bytes of the location in which to store the
134 returned message.
135 fildes The original fildes, exactly as passed to the futimesat(2) sys‐
137 tem call.
138 pathname
140 The original pathname, exactly as passed to the futimesat(2)
141 system call.
142 data The original data, exactly as passed to the futimesat(2) system
144 call.
145 Example: This function is intended to be used in a fashion similar to
147 the following example:
148 if (futimesat(fildes, pathname, data) < 0)
149 {
150 char message[3000];
151 explain_message_futimesat(message, sizeof(message), fildes,
152 pathname, data);
153 fprintf(stderr, "%s\n", message);
154 exit(EXIT_FAILURE);
155 }
156 The above code example is available pre-packaged as the explain_futime‐
158 sat_or_die(3) function.
159 explain_message_errno_futimesat
161 void explain_message_errno_futimesat(char *message, int message_size,
162 int errnum, int fildes, const char *pathname, const struct timeval
163 *data);
164 The explain_message_errno_futimesat function is used to obtain an
166 explanation of an error returned by the futimesat(2) system call. The
167 least the message will contain is the value of strerror(errno), but
168 usually it will do much better, and indicate the underlying cause in
169 more detail.
170 message The location in which to store the returned message. If a suit‐
172 able message return buffer is supplied, this function is thread
173 safe.
174 message_size
176 The size in bytes of the location in which to store the
177 returned message.
178 errnum The error value to be decoded, usually obtained from the errno
180 global variable just before this function is called. This is
181 necessary if you need to call any code between the system call
182 to be explained and this function, because many libc functions
183 will alter the value of errno.
184 fildes The original fildes, exactly as passed to the futimesat(2) sys‐
186 tem call.
187 pathname
189 The original pathname, exactly as passed to the futimesat(2)
190 system call.
191 data The original data, exactly as passed to the futimesat(2) system
193 call.
194 Example: This function is intended to be used in a fashion similar to
196 the following example:
197 if (futimesat(fildes, pathname, data) < 0)
198 {
199 int err = errno;
200 char message[3000];
201 explain_message_errno_futimesat(message, sizeof(message),
202 err, fildes, pathname, data);
203 fprintf(stderr, "%s\n", message);
204 exit(EXIT_FAILURE);
205 }
206 The above code example is available pre-packaged as the explain_futime‐
208 sat_or_die(3) function.
209
211 futimesat(2)
212 change timestamps of a file relative to a directory
213 explain_futimesat_or_die(3)
215 change timestamps of a file relative to a directory and report
216 errors
217
219 libexplain version 1.4
220 Copyright (C) 2013 Peter Miller
221 explain_futimesat(3)