lib/util/time.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3    time utility functions
   4
   5    Copyright (C) Andrew Tridgell                1992-2004
   6    Copyright (C) Stefan (metze) Metzmacher      2002
   7    Copyright (C) Jeremy Allison                 2007
   8    Copyright (C) Andrew Bartlett                2011
   9
  10    This program is free software; you can redistribute it and/or modify
  11    it under the terms of the GNU General Public License as published by
  12    the Free Software Foundation; either version 3 of the License, or
  13    (at your option) any later version.
  14
  15    This program is distributed in the hope that it will be useful,
  16    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18    GNU General Public License for more details.
  19
  20    You should have received a copy of the GNU General Public License
  21    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  22 */
  23
  24 #ifndef _SAMBA_TIME_H_
  25 #define _SAMBA_TIME_H_
  26
  27 #include <stdbool.h>
  28 #include <stdint.h>
  29 #include <talloc.h>
  30 #include <time.h>
  31
  32 #ifndef TIME_T_MIN
  33 /* we use 0 here, because (time_t)-1 means error */
  34 #define TIME_T_MIN 0
  35 #endif
  36
  37 /*
  38  * we use the INT32_MAX here as on 64 bit systems,
  39  * gmtime() fails with INT64_MAX
  40  */
  41 #ifndef TIME_T_MAX
  42 #define TIME_T_MAX MIN(INT32_MAX,_TYPE_MAXIMUM(time_t))
  43 #endif
  44
  45 /*
  46  * According to Windows API FileTimeToSystemTime() documentation the highest
  47  * allowed value " ... must be less than 0x8000000000000000.".
  48  */
  49 #define NTTIME_MAX INT64_MAX
  50
  51 /*
  52  * The lowest possible value when NTTIME=0 is used as sentinel value.
  53  */
  54 #define NTTIME_MIN 1
  55
  56 /*
  57  * NTTIME_OMIT in a setinfo tells us to not modify the corresponding on-disk
  58  * timestamp value.
  59  */
  60 #define NTTIME_OMIT 0
  61
  62 /*
  63  * Disable automatic timestamp updates, as described in MS-FSA. Samba doesn't
  64  * implement this yet.
  65  */
  66 #define NTTIME_FREEZE UINT64_MAX
  67 #define NTTIME_THAW (UINT64_MAX - 1)
  68
  69 #define SAMBA_UTIME_NOW UTIME_NOW
  70 #define SAMBA_UTIME_OMIT UTIME_OMIT
  71
  72 /* 64 bit time (100 nanosec) 1601 - cifs6.txt, section 3.5, page 30, 4 byte aligned */
  73 typedef uint64_t NTTIME;
  74
  75 #define NTTIME_USEC (10UL)
  76 #define NTTIME_MSEC (1000UL * NTTIME_USEC)
  77
  78 /**
  79  External access to time_t_min and time_t_max.
  80 **/
  81 time_t get_time_t_max(void);
  82
  83 /**
  84 a gettimeofday wrapper
  85 **/
  86 void GetTimeOfDay(struct timeval *tval);
  87
  88 /**
  89 a wrapper to preferably get the monotonic time
  90 **/
  91 void clock_gettime_mono(struct timespec *tp);
  92
  93 /**
  94 a wrapper to preferably get the monotonic time in s
  95 **/
  96 time_t time_mono(time_t *t);
  97
  98 /**
  99 interpret an 8 byte "filetime" structure to a time_t
 100 It's originally in "100ns units since jan 1st 1601"
 101 **/
 102 time_t nt_time_to_unix(NTTIME nt);
 103
 104 /**
 105 put a 8 byte filetime from a time_t
 106 This takes GMT as input
 107 **/
 108 void unix_to_nt_time(NTTIME *nt, time_t t);
 109
 110 /**
 111 check if it's a null unix time
 112 **/
 113 bool null_time(time_t t);
 114
 115 /**
 116 check if it's a null NTTIME
 117 **/
 118 bool null_nttime(NTTIME t);
 119
 120 /**
 121 put a dos date into a buffer (time/date format)
 122 This takes GMT time and puts local time in the buffer
 123 **/
 124 void push_dos_date(uint8_t *buf, int offset, time_t unixdate, int zone_offset);
 125
 126 /**
 127 put a dos date into a buffer (date/time format)
 128 This takes GMT time and puts local time in the buffer
 129 **/
 130 void push_dos_date2(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
 131
 132 /**
 133 put a dos 32 bit "unix like" date into a buffer. This routine takes
 134 GMT and converts it to LOCAL time before putting it (most SMBs assume
 135 localtime for this sort of date)
 136 **/
 137 void push_dos_date3(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
 138
 139 /**
 140   create a unix date (int GMT) from a dos date (which is actually in
 141   localtime)
 142 **/
 143 time_t pull_dos_date(const uint8_t *date_ptr, int zone_offset);
 144
 145 /**
 146 like make_unix_date() but the words are reversed
 147 **/
 148 time_t pull_dos_date2(const uint8_t *date_ptr, int zone_offset);
 149
 150 /**
 151   create a unix GMT date from a dos date in 32 bit "unix like" format
 152   these generally arrive as localtimes, with corresponding DST
 153 **/
 154 time_t pull_dos_date3(const uint8_t *date_ptr, int zone_offset);
 155
 156 /**
 157  Return a date and time as a string (optionally with microseconds)
 158
 159  format is %Y/%m/%d %H:%M:%S if strftime is available
 160 **/
 161
 162 char *timeval_string(TALLOC_CTX *ctx, const struct timeval *tp, bool hires);
 163
 164 struct timeval_buf;
 165 const char *timespec_string_buf(const struct timespec *tp,
 166                                 bool hires,
 167                                 struct timeval_buf *buf);
 168
 169 /**
 170  Return the current date and time as a string (optionally with microseconds)
 171
 172  format is %Y/%m/%d %H:%M:%S if strftime is available
 173 **/
 174 char *current_timestring(TALLOC_CTX *ctx, bool hires);
 175
 176 /**
 177  Return a date and time as a string (optionally with microseconds)
 178
 179  format is %Y%m%d_%H%M%S or %Y%m%d_%H%M%S_%us
 180 **/
 181
 182 char *minimal_timeval_string(TALLOC_CTX *ctx, const struct timeval *tp, bool hires);
 183
 184 /**
 185  Return the current date and time as a string (optionally with microseconds)
 186
 187  format is %Y%m%d_%H%M%S or %Y%m%d_%H%M%S_%us
 188 **/
 189 char *current_minimal_timestring(TALLOC_CTX *ctx, bool hires);
 190
 191 /**
 192 return a HTTP/1.0 time string
 193 **/
 194 char *http_timestring(TALLOC_CTX *mem_ctx, time_t t);
 195
 196 /**
 197  Return the date and time as a string
 198
 199  format is %a %b %e %X %Y %Z
 200 **/
 201 char *timestring(TALLOC_CTX *mem_ctx, time_t t);
 202
 203 /**
 204   return a talloced string representing a NTTIME for human consumption
 205 */
 206 const char *nt_time_string(TALLOC_CTX *mem_ctx, NTTIME nt);
 207
 208 /**
 209   put a NTTIME into a packet
 210 */
 211 void push_nttime(uint8_t *base, uint16_t offset, NTTIME t);
 212
 213 /**
 214   pull a NTTIME from a packet
 215 */
 216 NTTIME pull_nttime(uint8_t *base, uint16_t offset);
 217
 218 /**
 219   return (tv1 - tv2) in microseconds
 220 */
 221 int64_t usec_time_diff(const struct timeval *tv1, const struct timeval *tv2);
 222
 223 /**
 224   return (tp1 - tp2) in nanoseconds
 225 */
 226 int64_t nsec_time_diff(const struct timespec *tp1, const struct timespec *tp2);
 227
 228 /**
 229   return a zero timeval
 230 */
 231 struct timeval timeval_zero(void);
 232
 233 /**
 234   return true if a timeval is zero
 235 */
 236 bool timeval_is_zero(const struct timeval *tv);
 237
 238 /**
 239   return a timeval for the current time
 240 */
 241 struct timeval timeval_current(void);
 242
 243 /**
 244   return a timeval struct with the given elements
 245 */
 246 struct timeval timeval_set(uint32_t secs, uint32_t usecs);
 247
 248 /**
 249   return a timeval ofs microseconds after tv
 250 */
 251 struct timeval timeval_add(const struct timeval *tv,
 252                            uint32_t secs, uint32_t usecs);
 253
 254 /**
 255   return the sum of two timeval structures
 256 */
 257 struct timeval timeval_sum(const struct timeval *tv1,
 258                            const struct timeval *tv2);
 259
 260 /**
 261   return a timeval secs/usecs into the future
 262 */
 263 struct timeval timeval_current_ofs(uint32_t secs, uint32_t usecs);
 264
 265 /**
 266   return a timeval milliseconds into the future
 267 */
 268 struct timeval timeval_current_ofs_msec(uint32_t msecs);
 269
 270 /**
 271   return a timeval microseconds into the future
 272 */
 273 struct timeval timeval_current_ofs_usec(uint32_t usecs);
 274
 275 /**
 276   compare two timeval structures.
 277   Return -1 if tv1 < tv2
 278   Return 0 if tv1 == tv2
 279   Return 1 if tv1 > tv2
 280 */
 281 int timeval_compare(const struct timeval *tv1, const struct timeval *tv2);
 282
 283 /**
 284   return true if a timer is in the past
 285 */
 286 bool timeval_expired(const struct timeval *tv);
 287
 288 /**
 289   return the number of seconds elapsed between two times
 290 */
 291 double timeval_elapsed2(const struct timeval *tv1, const struct timeval *tv2);
 292
 293 /**
 294   return the number of seconds elapsed since a given time
 295 */
 296 double timeval_elapsed(const struct timeval *tv);
 297
 298 /**
 299   return the number of seconds elapsed between two times
 300 */
 301 double timespec_elapsed2(const struct timespec *ts1,
 302                          const struct timespec *ts2);
 303 /**
 304   return the number of seconds elapsed since a given time
 305 */
 306 double timespec_elapsed(const struct timespec *ts);
 307
 308 /**
 309   return the lesser of two timevals
 310 */
 311 struct timeval timeval_min(const struct timeval *tv1,
 312                            const struct timeval *tv2);
 313
 314 /**
 315   return the greater of two timevals
 316 */
 317 struct timeval timeval_max(const struct timeval *tv1,
 318                            const struct timeval *tv2);
 319
 320 /**
 321   return the difference between two timevals as a timeval
 322   if tv1 comes after tv2, then return a zero timeval
 323   (this is *tv2 - *tv1)
 324 */
 325 struct timeval timeval_until(const struct timeval *tv1,
 326                              const struct timeval *tv2);
 327
 328 /**
 329   convert a timeval to a NTTIME
 330 */
 331 NTTIME timeval_to_nttime(const struct timeval *tv);
 332
 333 /**
 334   convert a NTTIME to a timeval
 335 */
 336 void nttime_to_timeval(struct timeval *tv, NTTIME t);
 337
 338 /**
 339   return the UTC offset in seconds west of UTC, or 0 if it cannot be determined
 340  */
 341 int get_time_zone(time_t t);
 342
 343 /**
 344   check if 2 NTTIMEs are equal.
 345 */
 346 bool nt_time_equal(NTTIME *t1, NTTIME *t2);
 347
 348 void interpret_dos_date(uint32_t date,int *year,int *month,int *day,int *hour,int *minute,int *second);
 349
 350 struct timespec nt_time_to_unix_timespec_raw(NTTIME nt);
 351
 352 struct timespec nt_time_to_unix_timespec(NTTIME nt);
 353
 354 time_t convert_timespec_to_time_t(struct timespec ts);
 355
 356 struct timespec convert_time_t_to_timespec(time_t t);
 357
 358 bool null_timespec(struct timespec ts);
 359
 360 struct timespec convert_timeval_to_timespec(const struct timeval tv);
 361 struct timeval convert_timespec_to_timeval(const struct timespec ts);
 362 struct timespec timespec_current(void);
 363 struct timespec timespec_min(const struct timespec *ts1,
 364                              const struct timespec *ts2);
 365 int timespec_compare(const struct timespec *ts1, const struct timespec *ts2);
 366 void round_timespec_to_sec(struct timespec *ts);
 367 void round_timespec_to_usec(struct timespec *ts);
 368 void round_timespec_to_nttime(struct timespec *ts);
 369 NTTIME unix_timespec_to_nt_time(struct timespec ts);
 370 void normalize_timespec(struct timespec *ts);
 371
 372 /*
 373  * Functions supporting the full range of time_t and struct timespec values,
 374  * including 0, -1 and all other negative values. These functions don't use 0 or
 375  * -1 values as sentinel to denote "unset" variables, but use the POSIX 2008
 376  * define UTIME_OMIT from utimensat(2).
 377  */
 378 bool is_omit_timespec(const struct timespec *ts);
 379 struct timespec make_omit_timespec(void);
 380 NTTIME full_timespec_to_nt_time(const struct timespec *ts);
 381 struct timespec nt_time_to_full_timespec(NTTIME nt);
 382 time_t full_timespec_to_time_t(const struct timespec *ts);
 383 time_t nt_time_to_full_time_t(NTTIME nt);
 384 struct timespec time_t_to_full_timespec(time_t t);
 385
 386 /*
 387  * Functions to get and set the number of nanoseconds for times in a stat field.
 388  * If the stat has timestamp granularity less than nanosecond, then the set_*
 389  * operations will be lossy.
 390  */
 391 struct stat;
 392 time_t get_atimensec(const struct stat *);
 393 time_t get_mtimensec(const struct stat *);
 394 time_t get_ctimensec(const struct stat *);
 395 void set_atimensec(struct stat *, time_t);
 396 void set_mtimensec(struct stat *, time_t);
 397 void set_ctimensec(struct stat *, time_t);
 398
 399 /* These are convenience wrappers for the above getters. */
 400 struct timespec get_atimespec(const struct stat *);
 401 struct timespec get_mtimespec(const struct stat *);
 402 struct timespec get_ctimespec(const struct stat *);
 403
 404 #endif /* _SAMBA_TIME_H_ */