1 /* stat-related time functions.
2
3 Copyright (C) 2005, 2007, 2009-2023 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 # else
56 # define STAT_TIMESPEC_NS(st, st_xtim) ((st)->st_xtim.tv_nsec)
57 # endif
58 #elif defined HAVE_STRUCT_STAT_ST_ATIMESPEC_TV_NSEC
59 # define STAT_TIMESPEC(st, st_xtim) ((st)->st_xtim##espec)
60 #elif defined HAVE_STRUCT_STAT_ST_ATIMENSEC
61 # define STAT_TIMESPEC_NS(st, st_xtim) ((st)->st_xtim##ensec)
62 #elif defined HAVE_STRUCT_STAT_ST_ATIM_ST__TIM_TV_NSEC
63 # define STAT_TIMESPEC_NS(st, st_xtim) ((st)->st_xtim.st__tim.tv_nsec)
64 #endif
65
66 /* Return the nanosecond component of *ST's access time. */
67 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
68 get_stat_atime_ns (struct stat const *st)
69 {
70 # if defined STAT_TIMESPEC
71 return STAT_TIMESPEC (st, st_atim).tv_nsec;
72 # elif defined STAT_TIMESPEC_NS
73 return STAT_TIMESPEC_NS (st, st_atim);
74 # else
75 return 0;
76 # endif
77 }
78
79 /* Return the nanosecond component of *ST's status change time. */
80 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
81 get_stat_ctime_ns (struct stat const *st)
82 {
83 # if defined STAT_TIMESPEC
84 return STAT_TIMESPEC (st, st_ctim).tv_nsec;
85 # elif defined STAT_TIMESPEC_NS
86 return STAT_TIMESPEC_NS (st, st_ctim);
87 # else
88 return 0;
89 # endif
90 }
91
92 /* Return the nanosecond component of *ST's data modification time. */
93 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
94 get_stat_mtime_ns (struct stat const *st)
95 {
96 # if defined STAT_TIMESPEC
97 return STAT_TIMESPEC (st, st_mtim).tv_nsec;
98 # elif defined STAT_TIMESPEC_NS
99 return STAT_TIMESPEC_NS (st, st_mtim);
100 # else
101 return 0;
102 # endif
103 }
104
105 /* Return the nanosecond component of *ST's birth time. */
106 _GL_STAT_TIME_INLINE long int _GL_ATTRIBUTE_PURE
107 get_stat_birthtime_ns (_GL_UNUSED struct stat const *st)
108 {
109 # if defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC
110 return STAT_TIMESPEC (st, st_birthtim).tv_nsec;
111 # elif defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC
112 return STAT_TIMESPEC_NS (st, st_birthtim);
113 # else
114 return 0;
115 # endif
116 }
117
118 /* Return *ST's access time. */
119 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
120 get_stat_atime (struct stat const *st)
121 {
122 #ifdef STAT_TIMESPEC
123 return STAT_TIMESPEC (st, st_atim);
124 #else
125 struct timespec t;
126 t.tv_sec = st->st_atime;
127 t.tv_nsec = get_stat_atime_ns (st);
128 return t;
129 #endif
130 }
131
132 /* Return *ST's status change time. */
133 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
134 get_stat_ctime (struct stat const *st)
135 {
136 #ifdef STAT_TIMESPEC
137 return STAT_TIMESPEC (st, st_ctim);
138 #else
139 struct timespec t;
140 t.tv_sec = st->st_ctime;
141 t.tv_nsec = get_stat_ctime_ns (st);
142 return t;
143 #endif
144 }
145
146 /* Return *ST's data modification time. */
147 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
148 get_stat_mtime (struct stat const *st)
149 {
150 #ifdef STAT_TIMESPEC
151 return STAT_TIMESPEC (st, st_mtim);
152 #else
153 struct timespec t;
154 t.tv_sec = st->st_mtime;
155 t.tv_nsec = get_stat_mtime_ns (st);
156 return t;
157 #endif
158 }
159
160 /* Return *ST's birth time, if available; otherwise return a value
161 with tv_sec and tv_nsec both equal to -1. */
162 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
163 get_stat_birthtime (_GL_UNUSED struct stat const *st)
164 {
165 struct timespec t;
166
167 #if (defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC \
168 || defined HAVE_STRUCT_STAT_ST_BIRTHTIM_TV_NSEC)
169 t = STAT_TIMESPEC (st, st_birthtim);
170 #elif defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC
171 t.tv_sec = st->st_birthtime;
172 t.tv_nsec = st->st_birthtimensec;
173 #elif defined _WIN32 && ! defined __CYGWIN__
174 /* Native Windows platforms (but not Cygwin) put the "file creation
175 time" in st_ctime (!). See
176 <https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/stat-functions>. */
177 # if _GL_WINDOWS_STAT_TIMESPEC
178 t = st->st_ctim;
179 # else
180 t.tv_sec = st->st_ctime;
181 t.tv_nsec = 0;
182 # endif
183 #else
184 /* Birth time is not supported. */
185 t.tv_sec = -1;
186 t.tv_nsec = -1;
187 #endif
188
189 #if (defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC \
190 || defined HAVE_STRUCT_STAT_ST_BIRTHTIM_TV_NSEC \
191 || defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC)
192 /* FreeBSD and NetBSD sometimes signal the absence of knowledge by
193 using zero. Attempt to work around this problem. Alas, this can
194 report failure even for valid timestamps. Also, NetBSD
195 sometimes returns junk in the birth time fields; work around this
196 bug if it is detected. */
197 if (! (t.tv_sec && 0 <= t.tv_nsec && t.tv_nsec < 1000000000))
198 {
199 t.tv_sec = -1;
200 t.tv_nsec = -1;
201 }
202 #endif
203
204 return t;
205 }
206
207 /* If a stat-like function returned RESULT, normalize the timestamps
208 in *ST, in case this platform suffers from the Solaris 11 bug where
209 tv_nsec might be negative. Return the adjusted RESULT, setting
210 errno to EOVERFLOW if normalization overflowed. This function
211 is intended to be private to this .h file. */
212 _GL_STAT_TIME_INLINE int
213 stat_time_normalize (int result, _GL_UNUSED struct stat *st)
214 {
215 #if defined __sun && defined STAT_TIMESPEC
216 if (result == 0)
217 {
218 long int timespec_hz = 1000000000;
219 short int const ts_off[] = { offsetof (struct stat, st_atim),
220 offsetof (struct stat, st_mtim),
221 offsetof (struct stat, st_ctim) };
222 int i;
223 for (i = 0; i < sizeof ts_off / sizeof *ts_off; i++)
224 {
225 struct timespec *ts = (struct timespec *) ((char *) st + ts_off[i]);
226 long int q = ts->tv_nsec / timespec_hz;
227 long int r = ts->tv_nsec % timespec_hz;
228 if (r < 0)
229 {
230 r += timespec_hz;
231 q--;
232 }
233 ts->tv_nsec = r;
234 /* Overflow is possible, as Solaris 11 stat can yield
235 tv_sec == TYPE_MINIMUM (time_t) && tv_nsec == -1000000000.
236 INT_ADD_WRAPV is OK, since time_t is signed on Solaris. */
237 if (ckd_add (&ts->tv_sec, q, ts->tv_sec))
238 {
239 errno = EOVERFLOW;
240 return -1;
241 }
242 }
243 }
244 #endif
245 return result;
246 }
247
248 #ifdef __cplusplus
249 }
250 #endif
251
252 _GL_INLINE_HEADER_END
253
254 #endif