Debian Codegraph @

lib/stat-time.h

raw
1 /* stat-related time functions.
2
3 Copyright (C) 2005, 2007, 2009-2026 Free Software Foundation, Inc.
4
5 This file is free software: you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as
7 published by the Free Software Foundation; either version 2.1 of the
8 License, or (at your option) any later version.
9
10 This file is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public License
16 along with this program. If not, see <https://www.gnu.org/licenses/>. */
17
18 /* Written by Paul Eggert. */
19
20 #ifndef STAT_TIME_H
21 #define STAT_TIME_H 1
22
23 /* This file uses _GL_INLINE_HEADER_BEGIN, _GL_INLINE, _GL_UNUSED,
24 _GL_ATTRIBUTE_PURE, HAVE_STRUCT_STAT_*. */
25 #if !_GL_CONFIG_H_INCLUDED
26 #error "Please include config.h first."
27 #endif
28
29 #include <errno.h>
30 #include <stdckdint.h>
31 #include <stddef.h>
32 #include <sys/stat.h>
33 #include <time.h>
34
35 _GL_INLINE_HEADER_BEGIN
36 #ifndef _GL_STAT_TIME_INLINE
37 # define _GL_STAT_TIME_INLINE _GL_INLINE
38 #endif
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
44 /* STAT_TIMESPEC (ST, ST_XTIM) is the ST_XTIM member for *ST of type
45 struct timespec, if available. If not, then STAT_TIMESPEC_NS (ST,
46 ST_XTIM) is the nanosecond component of the ST_XTIM member for *ST,
47 if available. ST_XTIM can be st_atim, st_ctim, st_mtim, or st_birthtim
48 for access, status change, data modification, or birth (creation)
49 time respectively.
50
51 These macros are private to stat-time.h. */
52 #if _GL_WINDOWS_STAT_TIMESPEC || defined HAVE_STRUCT_STAT_ST_ATIM_TV_NSEC
53 # if _GL_WINDOWS_STAT_TIMESPEC || defined TYPEOF_STRUCT_STAT_ST_ATIM_IS_STRUCT_TIMESPEC
54 # define STAT_TIMESPEC(st, st_xtim) ((st)->st_xtim)
55 # define STAT_TIMESPEC_OFFSETOF(st_xtim) offsetof (struct stat, st_xtim)
56 # else
57 # define STAT_TIMESPEC_NS(st, st_xtim) ((st)->st_xtim.tv_nsec)
58 # endif
59 #elif defined HAVE_STRUCT_STAT_ST_ATIMESPEC_TV_NSEC
60 # define STAT_TIMESPEC(st, st_xtim) ((st)->st_xtim##espec)
61 # define STAT_TIMESPEC_OFFSETOF(st_xtim) offsetof (struct stat, st_xtim##espec)
62 #elif defined HAVE_STRUCT_STAT_ST_ATIMENSEC
63 # define STAT_TIMESPEC_NS(st, st_xtim) ((st)->st_xtim##ensec)
64 #elif defined HAVE_STRUCT_STAT_ST_ATIM_ST__TIM_TV_NSEC
65 # define STAT_TIMESPEC_NS(st, st_xtim) ((st)->st_xtim.st__tim.tv_nsec)
66 #endif
67
68 /* Return the nanosecond component of *ST's access time. */
69 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
70 get_stat_atime_ns (struct stat const *st)
71 {
72 # if defined STAT_TIMESPEC
73 return STAT_TIMESPEC (st, st_atim).tv_nsec;
74 # elif defined STAT_TIMESPEC_NS
75 return STAT_TIMESPEC_NS (st, st_atim);
76 # else
77 return 0;
78 # endif
79 }
80
81 /* Return the nanosecond component of *ST's status change time. */
82 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
83 get_stat_ctime_ns (struct stat const *st)
84 {
85 # if defined STAT_TIMESPEC
86 return STAT_TIMESPEC (st, st_ctim).tv_nsec;
87 # elif defined STAT_TIMESPEC_NS
88 return STAT_TIMESPEC_NS (st, st_ctim);
89 # else
90 return 0;
91 # endif
92 }
93
94 /* Return the nanosecond component of *ST's data modification time. */
95 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
96 get_stat_mtime_ns (struct stat const *st)
97 {
98 # if defined STAT_TIMESPEC
99 return STAT_TIMESPEC (st, st_mtim).tv_nsec;
100 # elif defined STAT_TIMESPEC_NS
101 return STAT_TIMESPEC_NS (st, st_mtim);
102 # else
103 return 0;
104 # endif
105 }
106
107 /* Return the nanosecond component of *ST's birth time. */
108 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
109 get_stat_birthtime_ns (_GL_UNUSED struct stat const *st)
110 {
111 # if defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC
112 return STAT_TIMESPEC (st, st_birthtim).tv_nsec;
113 # elif defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC
114 return STAT_TIMESPEC_NS (st, st_birthtim);
115 # else
116 return 0;
117 # endif
118 }
119
120 /* Constructs a 'struct timespec' with the given contents.
121 This macro / function is private to stat-time.h. */
122 #if !defined __cplusplus
123 /* Use a C99 compound literal.
124 This is guaranteed to initialize also the padding bits, for example on
125 platforms where tv_sec is 64 bits and tv_nsec is 32 bits, thus avoiding
126 gcc -Wuse-of-uninitialized-value warnings. */
127 # define _gl_make_timespec(sec,nsec) \
128 (struct timespec) { .tv_sec = (sec), .tv_nsec = (nsec) }
129 #else
130 /* C++ does not have C99 compound literals.
131 A constructor invocation
132 timespec { (sec), (nsec) }
133 would make assumptions about the order of the fields of 'struct timespec',
134 which are not guaranteed by POSIX. So, use an inline function. */
135 static inline struct timespec
136 _gl_make_timespec (time_t sec, long nsec)
137 {
138 struct timespec ts;
139 ts.tv_sec = sec;
140 ts.tv_nsec = nsec;
141 return ts;
142 }
143 #endif
144
145 /* Return *ST's access time. */
146 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
147 get_stat_atime (struct stat const *st)
148 {
149 #ifdef STAT_TIMESPEC
150 return STAT_TIMESPEC (st, st_atim);
151 #else
152 return _gl_make_timespec (st->st_atime, get_stat_atime_ns (st));
153 #endif
154 }
155
156 /* Return *ST's status change time. */
157 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
158 get_stat_ctime (struct stat const *st)
159 {
160 #ifdef STAT_TIMESPEC
161 return STAT_TIMESPEC (st, st_ctim);
162 #else
163 return _gl_make_timespec (st->st_ctime, get_stat_ctime_ns (st));
164 #endif
165 }
166
167 /* Return *ST's data modification time. */
168 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
169 get_stat_mtime (struct stat const *st)
170 {
171 #ifdef STAT_TIMESPEC
172 return STAT_TIMESPEC (st, st_mtim);
173 #else
174 return _gl_make_timespec (st->st_mtime, get_stat_mtime_ns (st));
175 #endif
176 }
177
178 /* Return *ST's birth time, if available; otherwise return a value
179 with tv_sec and tv_nsec both equal to -1. */
180 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
181 get_stat_birthtime (_GL_UNUSED struct stat const *st)
182 {
183 struct timespec t;
184
185 #if (defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC \
186 || defined HAVE_STRUCT_STAT_ST_BIRTHTIM_TV_NSEC)
187 t = STAT_TIMESPEC (st, st_birthtim);
188 #elif defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC
189 t = _gl_make_timespec (st->st_birthtime, st->st_birthtimensec);
190 #elif defined _WIN32 && ! defined __CYGWIN__
191 /* Native Windows platforms (but not Cygwin) put the "file creation
192 time" in st_ctime (!). See
193 <https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/stat-functions>. */
194 # if _GL_WINDOWS_STAT_TIMESPEC
195 t = st->st_ctim;
196 # else
197 t = _gl_make_timespec (st->st_ctime, 0);
198 # endif
199 #else
200 /* Birth time is not supported. */
201 t = _gl_make_timespec (-1, -1);
202 #endif
203
204 #if (defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC \
205 || defined HAVE_STRUCT_STAT_ST_BIRTHTIM_TV_NSEC \
206 || defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC)
207 /* FreeBSD and NetBSD sometimes signal the absence of knowledge by
208 using zero. Attempt to work around this problem. Alas, this can
209 report failure even for valid timestamps. Also, NetBSD
210 sometimes returns junk in the birth time fields; work around this
211 bug if it is detected. */
212 if (! (t.tv_sec && 0 <= t.tv_nsec && t.tv_nsec < 1000000000))
213 t = _gl_make_timespec (-1, -1);
214 #endif
215
216 return t;
217 }
218
219 /* If a stat-like function returned RESULT, normalize the timestamps
220 in *ST, if this platform suffers from a macOS and Solaris bug where
221 tv_nsec might be negative. Return the adjusted RESULT, setting
222 errno to EOVERFLOW if normalization overflowed. This function
223 is intended to be private to this .h file. */
224 _GL_STAT_TIME_INLINE int
225 stat_time_normalize (int result, _GL_UNUSED struct stat *st)
226 {
227 #if (((defined __APPLE__ && defined __MACH__) || defined __sun) \
228 && defined STAT_TIMESPEC_OFFSETOF)
229 if (result == 0)
230 {
231 long int timespec_hz = 1000000000;
232 short int const ts_off[] = { STAT_TIMESPEC_OFFSETOF (st_atim),
233 STAT_TIMESPEC_OFFSETOF (st_mtim),
234 STAT_TIMESPEC_OFFSETOF (st_ctim) };
235 for (int i = 0; i < sizeof ts_off / sizeof *ts_off; i++)
236 {
237 struct timespec *ts = (struct timespec *) ((char *) st + ts_off[i]);
238 long int q = ts->tv_nsec / timespec_hz;
239 long int r = ts->tv_nsec % timespec_hz;
240 if (r < 0)
241 {
242 r += timespec_hz;
243 q--;
244 }
245 ts->tv_nsec = r;
246 /* Overflow is possible, as Solaris 11 stat can yield
247 tv_sec == TYPE_MINIMUM (time_t) && tv_nsec == -1000000000. */
248 if (ckd_add (&ts->tv_sec, q, ts->tv_sec))
249 {
250 errno = EOVERFLOW;
251 return -1;
252 }
253 }
254 }
255 #endif
256 return result;
257 }
258
259 #ifdef __cplusplus
260 }
261 #endif
262
263 _GL_INLINE_HEADER_END
264
265 #endif