1explain_futimens(3) Library Functions Manual explain_futimens(3)
2
6 explain_futimens - explain futimens(3) errors
7
9 #include <libexplain/futimens.h>
10 const char *explain_futimens(int fildes, const struct time_spec *data);
11 const char *explain_errno_futimens(int errnum, int fildes, const struct
12 time_spec *data);
13 void explain_message_futimens(char *message, int message_size, int
14 fildes, const struct time_spec *data);
15 void explain_message_errno_futimens(char *message, int message_size,
16 int errnum, int fildes, const struct time_spec *data);
17
19 These functions may be used to obtain explanations for errors returned
20 by the futimens(3) system call.
21 explain_futimens
23 const char *explain_futimens(int fildes, const struct time_spec *data);
24 The explain_futimens function is used to obtain an explanation of an
26 error returned by the futimens(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 fildes The original fildes, exactly as passed to the futimens(3) sys‐
34 tem call.
35 data The original data, exactly as passed to the futimens(3) system
37 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 if (futimens(fildes, data) < 0)
52 {
53 fprintf(stderr, "%s\n", explain_futimens(fildes, data));
54 exit(EXIT_FAILURE);
55 }
56 The above code example is available pre-packaged as the explain_futi‐
58 mens_or_die(3) function.
59 explain_errno_futimens
61 const char *explain_errno_futimens(int errnum, int fildes, const struct
62 time_spec *data);
63 The explain_errno_futimens function is used to obtain an explanation of
65 an error returned by the futimens(3) system call. The least the mes‐
66 sage will contain is the value of strerror(errno), but usually it will
67 do much better, and indicate the underlying cause in more detail.
68 errnum The error value to be decoded, usually obtained from the errno
70 global variable just before this function is called. This is
71 necessary if you need to call any code between the system call
72 to be explained and this function, because many libc functions
73 will alter the value of errno.
74 fildes The original fildes, exactly as passed to the futimens(3) sys‐
76 tem call.
77 data The original data, exactly as passed to the futimens(3) system
79 call.
80 Returns:
82 The message explaining the error. This message buffer is shared
83 by all libexplain functions which do not supply a buffer in
84 their argument list. This will be overwritten by the next call
85 to any libexplain function which shares this buffer, including
86 other threads.
87 Note: This function is not thread safe, because it shares a return buf‐
89 fer across all threads, and many other functions in this library.
90 Example: This function is intended to be used in a fashion similar to
92 the following example:
93 if (futimens(fildes, data) < 0)
94 {
95 int err = errno;
96 fprintf(stderr, "%s\n", explain_errno_futimens(err, fildes,
97 data));
98 exit(EXIT_FAILURE);
99 }
100 The above code example is available pre-packaged as the explain_futi‐
102 mens_or_die(3) function.
103 explain_message_futimens
105 void explain_message_futimens(char *message, int message_size, int
106 fildes, const struct time_spec *data);
107 The explain_message_futimens function is used to obtain an explanation
109 of an error returned by the futimens(3) system call. The least the
110 message will contain is the value of strerror(errno), but usually it
111 will do much better, and indicate the underlying cause in more detail.
112 The errno global variable will be used to obtain the error value to be
114 decoded.
115 message The location in which to store the returned message. If a suit‐
117 able message return buffer is supplied, this function is thread
118 safe.
119 message_size
121 The size in bytes of the location in which to store the
122 returned message.
123 fildes The original fildes, exactly as passed to the futimens(3) sys‐
125 tem call.
126 data The original data, exactly as passed to the futimens(3) system
128 call.
129 Example: This function is intended to be used in a fashion similar to
131 the following example:
132 if (futimens(fildes, data) < 0)
133 {
134 char message[3000];
135 explain_message_futimens(message, sizeof(message), fildes,
136 data);
137 fprintf(stderr, "%s\n", message);
138 exit(EXIT_FAILURE);
139 }
140 The above code example is available pre-packaged as the explain_futi‐
142 mens_or_die(3) function.
143 explain_message_errno_futimens
145 void explain_message_errno_futimens(char *message, int message_size,
146 int errnum, int fildes, const struct time_spec *data);
147 The explain_message_errno_futimens function is used to obtain an expla‐
149 nation of an error returned by the futimens(3) system call. The least
150 the message will contain is the value of strerror(errno), but usually
151 it will do much better, and indicate the underlying cause in more
152 detail.
153 message The location in which to store the returned message. If a suit‐
155 able message return buffer is supplied, this function is thread
156 safe.
157 message_size
159 The size in bytes of the location in which to store the
160 returned message.
161 errnum The error value to be decoded, usually obtained from the errno
163 global variable just before this function is called. This is
164 necessary if you need to call any code between the system call
165 to be explained and this function, because many libc functions
166 will alter the value of errno.
167 fildes The original fildes, exactly as passed to the futimens(3) sys‐
169 tem call.
170 data The original data, exactly as passed to the futimens(3) system
172 call.
173 Example: This function is intended to be used in a fashion similar to
175 the following example:
176 if (futimens(fildes, data) < 0)
177 {
178 int err = errno;
179 char message[3000];
180 explain_message_errno_futimens(message, sizeof(message),
181 err, fildes, data);
182 fprintf(stderr, "%s\n", message);
183 exit(EXIT_FAILURE);
184 }
185 The above code example is available pre-packaged as the explain_futi‐
187 mens_or_die(3) function.
188
190 futimens(3)
191 change file timestamps with nanosecond precision
192 explain_futimens_or_die(3)
194 change file timestamps with nanosecond precision and report
195 errors
196
198 libexplain version 1.4
199 Copyright (C) 2013 Peter Miller
200 explain_futimens(3)