1explain_utimensat(3) Library Functions Manual explain_utimensat(3)
2
6 explain_utimensat - explain utimensat(2) errors
7
9 #include <libexplain/utimensat.h>
10 const char *explain_utimensat(int fildes, const char *pathname, const
11 struct timespec *data, int flags);
12 const char *explain_errno_utimensat(int errnum, int fildes, const char
13 *pathname, const struct timespec *data, int flags);
14 void explain_message_utimensat(char *message, int message_size, int
15 fildes, const char *pathname, const struct timespec *data, int flags);
16 void explain_message_errno_utimensat(char *message, int message_size,
17 int errnum, int fildes, const char *pathname, const struct timespec
18 *data, int flags);
19
21 These functions may be used to obtain explanations for errors returned
22 by the utimensat(2) system call.
23 explain_utimensat
25 const char *explain_utimensat(int fildes, const char *pathname, const
26 struct timespec *data, int flags);
27 The explain_utimensat function is used to obtain an explanation of an
29 error returned by the utimensat(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 utimensat(2) sys‐
37 tem call.
38 pathname
40 The original pathname, exactly as passed to the utimensat(2)
41 system call.
42 data The original data, exactly as passed to the utimensat(2) system
44 call.
45 flags The original flags, exactly as passed to the utimensat(2) sys‐
47 tem 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 (utimensat(fildes, pathname, data, flags) < 0)
62 {
63 fprintf(stderr, "%s\n", explain_utimensat(fildes, pathname,
64 data, flags));
65 exit(EXIT_FAILURE);
66 }
67 The above code example is available pre-packaged as the explain_utimen‐
69 sat_or_die(3) function.
70 explain_errno_utimensat
72 const char *explain_errno_utimensat(int errnum, int fildes, const char
73 *pathname, const struct timespec *data, int flags);
74 The explain_errno_utimensat function is used to obtain an explanation
76 of an error returned by the utimensat(2) system call. The least the
77 message will contain is the value of strerror(errno), but usually it
78 will do 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 utimensat(2) sys‐
87 tem call.
88 pathname
90 The original pathname, exactly as passed to the utimensat(2)
91 system call.
92 data The original data, exactly as passed to the utimensat(2) system
94 call.
95 flags The original flags, exactly as passed to the utimensat(2) sys‐
97 tem 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 (utimensat(fildes, pathname, data, flags) < 0)
112 {
113 int err = errno;
114 fprintf(stderr, "%s\n", explain_errno_utimensat(err, fildes,
115 pathname, data, flags));
116 exit(EXIT_FAILURE);
117 }
118 The above code example is available pre-packaged as the explain_utimen‐
120 sat_or_die(3) function.
121 explain_message_utimensat
123 void explain_message_utimensat(char *message, int message_size, int
124 fildes, const char *pathname, const struct timespec *data, int flags);
125 The explain_message_utimensat function is used to obtain an explanation
127 of an error returned by the utimensat(2) system call. The least the
128 message will contain is the value of strerror(errno), but usually it
129 will 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 utimensat(2) sys‐
143 tem call.
144 pathname
146 The original pathname, exactly as passed to the utimensat(2)
147 system call.
148 data The original data, exactly as passed to the utimensat(2) system
150 call.
151 flags The original flags, exactly as passed to the utimensat(2) sys‐
153 tem call.
154 Example: This function is intended to be used in a fashion similar to
156 the following example:
157 if (utimensat(fildes, pathname, data, flags) < 0)
158 {
159 char message[3000];
160 explain_message_utimensat(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 explain_utimen‐
167 sat_or_die(3) function.
168 explain_message_errno_utimensat
170 void explain_message_errno_utimensat(char *message, int message_size,
171 int errnum, int fildes, const char *pathname, const struct timespec
172 *data, int flags);
173 The explain_message_errno_utimensat function is used to obtain an
175 explanation of an error returned by the utimensat(2) system call. The
176 least the message will contain is the value of strerror(errno), but
177 usually it will do much better, and indicate the underlying cause in
178 more 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 utimensat(2) sys‐
195 tem call.
196 pathname
198 The original pathname, exactly as passed to the utimensat(2)
199 system call.
200 data The original data, exactly as passed to the utimensat(2) system
202 call.
203 flags The original flags, exactly as passed to the utimensat(2) sys‐
205 tem call.
206 Example: This function is intended to be used in a fashion similar to
208 the following example:
209 if (utimensat(fildes, pathname, data, flags) < 0)
210 {
211 int err = errno;
212 char message[3000];
213 explain_message_errno_utimensat(message, sizeof(message),
214 err, 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 explain_utimen‐
220 sat_or_die(3) function.
221
223 utimensat(2)
224 change file timestamps with nanosecond precision
225 explain_utimensat_or_die(3)
227 change file timestamps with nanosecond precision and report
228 errors
229
231 libexplain version 1.4
232 Copyright (C) 2012 Peter Miller
233 explain_utimensat(3)