lib/stat-time.h

   1 /* stat-related time functions.
   2
   3    Copyright (C) 2005, 2007, 2009-2024 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 /* Return *ST's access time.  */
 121 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
 122 get_stat_atime (struct stat const *st)
 123 {
 124 #ifdef STAT_TIMESPEC
 125   return STAT_TIMESPEC (st, st_atim);
 126 #else
 127   return (struct timespec) { .tv_sec = st->st_atime,
 128                              .tv_nsec = get_stat_atime_ns (st) };
 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   return (struct timespec) { .tv_sec = st->st_ctime,
 140                              .tv_nsec = get_stat_ctime_ns (st) };
 141 #endif
 142 }
 143
 144 /* Return *ST's data modification time.  */
 145 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
 146 get_stat_mtime (struct stat const *st)
 147 {
 148 #ifdef STAT_TIMESPEC
 149   return STAT_TIMESPEC (st, st_mtim);
 150 #else
 151   return (struct timespec) { .tv_sec = st->st_mtime,
 152                              .tv_nsec = get_stat_mtime_ns (st) };
 153 #endif
 154 }
 155
 156 /* Return *ST's birth time, if available; otherwise return a value
 157    with tv_sec and tv_nsec both equal to -1.  */
 158 _GL_STAT_TIME_INLINE struct timespec _GL_ATTRIBUTE_PURE
 159 get_stat_birthtime (_GL_UNUSED struct stat const *st)
 160 {
 161   struct timespec t;
 162
 163 #if (defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC \
 164      || defined HAVE_STRUCT_STAT_ST_BIRTHTIM_TV_NSEC)
 165   t = STAT_TIMESPEC (st, st_birthtim);
 166 #elif defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC
 167   t = (struct timespec) { .tv_sec = st->st_birthtime,
 168                           .tv_nsec = st->st_birthtimensec };
 169 #elif defined _WIN32 && ! defined __CYGWIN__
 170   /* Native Windows platforms (but not Cygwin) put the "file creation
 171      time" in st_ctime (!).  See
 172      <https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/stat-functions>.  */
 173 # if _GL_WINDOWS_STAT_TIMESPEC
 174   t = st->st_ctim;
 175 # else
 176   t = (struct timespec) { .tv_sec = st->st_ctime };
 177 # endif
 178 #else
 179   /* Birth time is not supported.  */
 180   t = (struct timespec) { .tv_sec = -1, .tv_nsec = -1 };
 181 #endif
 182
 183 #if (defined HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC_TV_NSEC \
 184      || defined HAVE_STRUCT_STAT_ST_BIRTHTIM_TV_NSEC \
 185      || defined HAVE_STRUCT_STAT_ST_BIRTHTIMENSEC)
 186   /* FreeBSD and NetBSD sometimes signal the absence of knowledge by
 187      using zero.  Attempt to work around this problem.  Alas, this can
 188      report failure even for valid timestamps.  Also, NetBSD
 189      sometimes returns junk in the birth time fields; work around this
 190      bug if it is detected.  */
 191   if (! (t.tv_sec && 0 <= t.tv_nsec && t.tv_nsec < 1000000000))
 192     t = (struct timespec) { .tv_sec = -1, .tv_nsec = -1 };
 193 #endif
 194
 195   return t;
 196 }
 197
 198 /* If a stat-like function returned RESULT, normalize the timestamps
 199    in *ST, if this platform suffers from a macOS and Solaris bug where
 200    tv_nsec might be negative.  Return the adjusted RESULT, setting
 201    errno to EOVERFLOW if normalization overflowed.  This function
 202    is intended to be private to this .h file.  */
 203 _GL_STAT_TIME_INLINE int
 204 stat_time_normalize (int result, _GL_UNUSED struct stat *st)
 205 {
 206 #if (((defined __APPLE__ && defined __MACH__) || defined __sun) \
 207      && defined STAT_TIMESPEC_OFFSETOF)
 208   if (result == 0)
 209     {
 210       long int timespec_hz = 1000000000;
 211       short int const ts_off[] = { STAT_TIMESPEC_OFFSETOF (st_atim),
 212                                    STAT_TIMESPEC_OFFSETOF (st_mtim),
 213                                    STAT_TIMESPEC_OFFSETOF (st_ctim) };
 214       int i;
 215       for (i = 0; i < sizeof ts_off / sizeof *ts_off; i++)
 216         {
 217           struct timespec *ts = (struct timespec *) ((char *) st + ts_off[i]);
 218           long int q = ts->tv_nsec / timespec_hz;
 219           long int r = ts->tv_nsec % timespec_hz;
 220           if (r < 0)
 221             {
 222               r += timespec_hz;
 223               q--;
 224             }
 225           ts->tv_nsec = r;
 226           /* Overflow is possible, as Solaris 11 stat can yield
 227              tv_sec == TYPE_MINIMUM (time_t) && tv_nsec == -1000000000.  */
 228           if (ckd_add (&ts->tv_sec, q, ts->tv_sec))
 229             {
 230               errno = EOVERFLOW;
 231               return -1;
 232             }
 233         }
 234     }
 235 #endif
 236   return result;
 237 }
 238
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243 _GL_INLINE_HEADER_END
 244
 245 #endif