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
  31 #ifndef TIME_T_MIN
  32 /* we use 0 here, because (time_t)-1 means error */
  33 #define TIME_T_MIN 0
  34 #endif
  35
  36 /*
  37  * we use the INT32_MAX here as on 64 bit systems,
  38  * gmtime() fails with INT64_MAX
  39  */
  40 #ifndef TIME_T_MAX
  41 #define TIME_T_MAX MIN(INT32_MAX,_TYPE_MAXIMUM(time_t))
  42 #endif
  43
  44
  45 /* 64 bit time (100 nanosec) 1601 - cifs6.txt, section 3.5, page 30, 4 byte aligned */
  46 typedef uint64_t NTTIME;
  47
  48 /**
  49  External access to time_t_min and time_t_max.
  50 **/
  51 time_t get_time_t_max(void);
  52
  53 /**
  54 a gettimeofday wrapper
  55 **/
  56 void GetTimeOfDay(struct timeval *tval);
  57
  58 /**
  59 a wrapper to preferably get the monotonic time
  60 **/
  61 void clock_gettime_mono(struct timespec *tp);
  62
  63 /**
  64 a wrapper to preferably get the monotonic time in s
  65 **/
  66 time_t time_mono(time_t *t);
  67
  68 /**
  69 interpret an 8 byte "filetime" structure to a time_t
  70 It's originally in "100ns units since jan 1st 1601"
  71 **/
  72 time_t nt_time_to_unix(NTTIME nt);
  73
  74 /**
  75 put a 8 byte filetime from a time_t
  76 This takes GMT as input
  77 **/
  78 void unix_to_nt_time(NTTIME *nt, time_t t);
  79
  80 /**
  81 check if it's a null unix time
  82 **/
  83 bool null_time(time_t t);
  84
  85 /**
  86 check if it's a null NTTIME
  87 **/
  88 bool null_nttime(NTTIME t);
  89
  90 /**
  91 put a dos date into a buffer (time/date format)
  92 This takes GMT time and puts local time in the buffer
  93 **/
  94 void push_dos_date(uint8_t *buf, int offset, time_t unixdate, int zone_offset);
  95
  96 /**
  97 put a dos date into a buffer (date/time format)
  98 This takes GMT time and puts local time in the buffer
  99 **/
 100 void push_dos_date2(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
 101
 102 /**
 103 put a dos 32 bit "unix like" date into a buffer. This routine takes
 104 GMT and converts it to LOCAL time before putting it (most SMBs assume
 105 localtime for this sort of date)
 106 **/
 107 void push_dos_date3(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
 108
 109 /**
 110   create a unix date (int GMT) from a dos date (which is actually in
 111   localtime)
 112 **/
 113 time_t pull_dos_date(const uint8_t *date_ptr, int zone_offset);
 114
 115 /**
 116 like make_unix_date() but the words are reversed
 117 **/
 118 time_t pull_dos_date2(const uint8_t *date_ptr, int zone_offset);
 119
 120 /**
 121   create a unix GMT date from a dos date in 32 bit "unix like" format
 122   these generally arrive as localtimes, with corresponding DST
 123 **/
 124 time_t pull_dos_date3(const uint8_t *date_ptr, int zone_offset);
 125
 126 /**
 127  Return a date and time as a string (optionally with microseconds)
 128
 129  format is %Y/%m/%d %H:%M:%S if strftime is available
 130 **/
 131
 132 char *timeval_string(TALLOC_CTX *ctx, const struct timeval *tp, bool hires);
 133
 134 /**
 135  Return the current date and time as a string (optionally with microseconds)
 136
 137  format is %Y/%m/%d %H:%M:%S if strftime is available
 138 **/
 139 char *current_timestring(TALLOC_CTX *ctx, bool hires);
 140
 141 /**
 142  Return a date and time as a string (optionally with microseconds)
 143
 144  format is %Y%m%d_%H%M%S or %Y%m%d_%H%M%S_%us
 145 **/
 146
 147 char *minimal_timeval_string(TALLOC_CTX *ctx, const struct timeval *tp, bool hires);
 148
 149 /**
 150  Return the current date and time as a string (optionally with microseconds)
 151
 152  format is %Y%m%d_%H%M%S or %Y%m%d_%H%M%S_%us
 153 **/
 154 char *current_minimal_timestring(TALLOC_CTX *ctx, bool hires);
 155
 156 /**
 157 return a HTTP/1.0 time string
 158 **/
 159 char *http_timestring(TALLOC_CTX *mem_ctx, time_t t);
 160
 161 /**
 162  Return the date and time as a string
 163
 164  format is %a %b %e %X %Y %Z
 165 **/
 166 char *timestring(TALLOC_CTX *mem_ctx, time_t t);
 167
 168 /**
 169   return a talloced string representing a NTTIME for human consumption
 170 */
 171 const char *nt_time_string(TALLOC_CTX *mem_ctx, NTTIME nt);
 172
 173 /**
 174   put a NTTIME into a packet
 175 */
 176 void push_nttime(uint8_t *base, uint16_t offset, NTTIME t);
 177
 178 /**
 179   pull a NTTIME from a packet
 180 */
 181 NTTIME pull_nttime(uint8_t *base, uint16_t offset);
 182
 183 /**
 184   parse a nttime as a large integer in a string and return a NTTIME
 185 */
 186 NTTIME nttime_from_string(const char *s);
 187
 188 /**
 189   return (tv1 - tv2) in microseconds
 190 */
 191 int64_t usec_time_diff(const struct timeval *tv1, const struct timeval *tv2);
 192
 193 /**
 194   return (tp1 - tp2) in nanoseconds
 195 */
 196 int64_t nsec_time_diff(const struct timespec *tp1, const struct timespec *tp2);
 197
 198 /**
 199   return a zero timeval
 200 */
 201 struct timeval timeval_zero(void);
 202
 203 /**
 204   return true if a timeval is zero
 205 */
 206 bool timeval_is_zero(const struct timeval *tv);
 207
 208 /**
 209   return a timeval for the current time
 210 */
 211 struct timeval timeval_current(void);
 212
 213 /**
 214   return a timeval struct with the given elements
 215 */
 216 struct timeval timeval_set(uint32_t secs, uint32_t usecs);
 217
 218 /**
 219   return a timeval ofs microseconds after tv
 220 */
 221 struct timeval timeval_add(const struct timeval *tv,
 222                            uint32_t secs, uint32_t usecs);
 223
 224 /**
 225   return the sum of two timeval structures
 226 */
 227 struct timeval timeval_sum(const struct timeval *tv1,
 228                            const struct timeval *tv2);
 229
 230 /**
 231   return a timeval secs/usecs into the future
 232 */
 233 struct timeval timeval_current_ofs(uint32_t secs, uint32_t usecs);
 234
 235 /**
 236   return a timeval milliseconds into the future
 237 */
 238 struct timeval timeval_current_ofs_msec(uint32_t msecs);
 239
 240 /**
 241   return a timeval microseconds into the future
 242 */
 243 struct timeval timeval_current_ofs_usec(uint32_t usecs);
 244
 245 /**
 246   compare two timeval structures.
 247   Return -1 if tv1 < tv2
 248   Return 0 if tv1 == tv2
 249   Return 1 if tv1 > tv2
 250 */
 251 int timeval_compare(const struct timeval *tv1, const struct timeval *tv2);
 252
 253 /**
 254   return true if a timer is in the past
 255 */
 256 bool timeval_expired(const struct timeval *tv);
 257
 258 /**
 259   return the number of seconds elapsed between two times
 260 */
 261 double timeval_elapsed2(const struct timeval *tv1, const struct timeval *tv2);
 262
 263 /**
 264   return the number of seconds elapsed since a given time
 265 */
 266 double timeval_elapsed(const struct timeval *tv);
 267
 268 /**
 269   return the number of seconds elapsed between two times
 270 */
 271 double timespec_elapsed2(const struct timespec *ts1,
 272                          const struct timespec *ts2);
 273 /**
 274   return the number of seconds elapsed since a given time
 275 */
 276 double timespec_elapsed(const struct timespec *ts);
 277
 278 /**
 279   return the lesser of two timevals
 280 */
 281 struct timeval timeval_min(const struct timeval *tv1,
 282                            const struct timeval *tv2);
 283
 284 /**
 285   return the greater of two timevals
 286 */
 287 struct timeval timeval_max(const struct timeval *tv1,
 288                            const struct timeval *tv2);
 289
 290 /**
 291   return the difference between two timevals as a timeval
 292   if tv1 comes after tv2, then return a zero timeval
 293   (this is *tv2 - *tv1)
 294 */
 295 struct timeval timeval_until(const struct timeval *tv1,
 296                              const struct timeval *tv2);
 297
 298 /**
 299   convert a timeval to a NTTIME
 300 */
 301 NTTIME timeval_to_nttime(const struct timeval *tv);
 302
 303 /**
 304   convert a NTTIME to a timeval
 305 */
 306 void nttime_to_timeval(struct timeval *tv, NTTIME t);
 307
 308 /**
 309   return the UTC offset in seconds west of UTC, or 0 if it cannot be determined
 310  */
 311 int get_time_zone(time_t t);
 312
 313 /**
 314   check if 2 NTTIMEs are equal.
 315 */
 316 bool nt_time_equal(NTTIME *t1, NTTIME *t2);
 317
 318 void interpret_dos_date(uint32_t date,int *year,int *month,int *day,int *hour,int *minute,int *second);
 319
 320 struct timespec nt_time_to_unix_timespec(NTTIME nt);
 321
 322 time_t convert_timespec_to_time_t(struct timespec ts);
 323
 324 struct timespec convert_time_t_to_timespec(time_t t);
 325
 326 bool null_timespec(struct timespec ts);
 327
 328 struct timespec convert_timeval_to_timespec(const struct timeval tv);
 329 struct timeval convert_timespec_to_timeval(const struct timespec ts);
 330 struct timespec timespec_current(void);
 331 struct timespec timespec_min(const struct timespec *ts1,
 332                              const struct timespec *ts2);
 333 int timespec_compare(const struct timespec *ts1, const struct timespec *ts2);
 334 void round_timespec_to_sec(struct timespec *ts);
 335 void round_timespec_to_usec(struct timespec *ts);
 336 NTTIME unix_timespec_to_nt_time(struct timespec ts);
 337
 338 #endif /* _SAMBA_TIME_H_ */