VirtualBox

source: vbox/trunk/include/iprt/time.h@ 75155

Last change on this file since 75155 was 74148, checked in by vboxsync, 6 years ago

IPRT/time: Added RTTimeFromRfc2822 and RTTimeToStringEx (both untested). Fixed faction parsing in RTTimeFromString. bugref:9167

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 36.5 KB
Line 
1/** @file
2 * IPRT - Time.
3 */
4
5/*
6 * Copyright (C) 2006-2017 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_time_h
27#define ___iprt_time_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/assertcompile.h>
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_time RTTime - Time
36 * @ingroup grp_rt
37 * @{
38 */
39
40/** Time Specification.
41 *
42 * Use the inline RTTimeSpecGet/Set to operate on structure this so we
43 * can easily change the representation if required later.
44 *
45 * The current representation is in nanoseconds relative to the unix epoch
46 * (1970-01-01 00:00:00 UTC). This gives us an approximate span from
47 * 1678 to 2262 without sacrificing the resolution offered by the various
48 * host OSes (BSD & LINUX 1ns, NT 100ns).
49 */
50typedef struct RTTIMESPEC
51{
52 /** Nanoseconds since epoch.
53 * The name is intentially too long to be comfortable to use because you should be
54 * using inline helpers! */
55 int64_t i64NanosecondsRelativeToUnixEpoch;
56} RTTIMESPEC;
57
58
59/** @name RTTIMESPEC methods
60 * @{ */
61
62/**
63 * Gets the time as nanoseconds relative to the unix epoch.
64 *
65 * @returns Nanoseconds relative to unix epoch.
66 * @param pTime The time spec to interpret.
67 */
68DECLINLINE(int64_t) RTTimeSpecGetNano(PCRTTIMESPEC pTime)
69{
70 return pTime->i64NanosecondsRelativeToUnixEpoch;
71}
72
73
74/**
75 * Sets the time give by nanoseconds relative to the unix epoch.
76 *
77 * @returns pTime.
78 * @param pTime The time spec to modify.
79 * @param i64Nano The new time in nanoseconds.
80 */
81DECLINLINE(PRTTIMESPEC) RTTimeSpecSetNano(PRTTIMESPEC pTime, int64_t i64Nano)
82{
83 pTime->i64NanosecondsRelativeToUnixEpoch = i64Nano;
84 return pTime;
85}
86
87
88/**
89 * Gets the time as microseconds relative to the unix epoch.
90 *
91 * @returns microseconds relative to unix epoch.
92 * @param pTime The time spec to interpret.
93 */
94DECLINLINE(int64_t) RTTimeSpecGetMicro(PCRTTIMESPEC pTime)
95{
96 return pTime->i64NanosecondsRelativeToUnixEpoch / RT_NS_1US;
97}
98
99
100/**
101 * Sets the time given by microseconds relative to the unix epoch.
102 *
103 * @returns pTime.
104 * @param pTime The time spec to modify.
105 * @param i64Micro The new time in microsecond.
106 */
107DECLINLINE(PRTTIMESPEC) RTTimeSpecSetMicro(PRTTIMESPEC pTime, int64_t i64Micro)
108{
109 pTime->i64NanosecondsRelativeToUnixEpoch = i64Micro * RT_NS_1US;
110 return pTime;
111}
112
113
114/**
115 * Gets the time as milliseconds relative to the unix epoch.
116 *
117 * @returns milliseconds relative to unix epoch.
118 * @param pTime The time spec to interpret.
119 */
120DECLINLINE(int64_t) RTTimeSpecGetMilli(PCRTTIMESPEC pTime)
121{
122 return pTime->i64NanosecondsRelativeToUnixEpoch / RT_NS_1MS;
123}
124
125
126/**
127 * Sets the time given by milliseconds relative to the unix epoch.
128 *
129 * @returns pTime.
130 * @param pTime The time spec to modify.
131 * @param i64Milli The new time in milliseconds.
132 */
133DECLINLINE(PRTTIMESPEC) RTTimeSpecSetMilli(PRTTIMESPEC pTime, int64_t i64Milli)
134{
135 pTime->i64NanosecondsRelativeToUnixEpoch = i64Milli * RT_NS_1MS;
136 return pTime;
137}
138
139
140/**
141 * Gets the time as seconds relative to the unix epoch.
142 *
143 * @returns seconds relative to unix epoch.
144 * @param pTime The time spec to interpret.
145 */
146DECLINLINE(int64_t) RTTimeSpecGetSeconds(PCRTTIMESPEC pTime)
147{
148 return pTime->i64NanosecondsRelativeToUnixEpoch / RT_NS_1SEC;
149}
150
151
152/**
153 * Sets the time given by seconds relative to the unix epoch.
154 *
155 * @returns pTime.
156 * @param pTime The time spec to modify.
157 * @param i64Seconds The new time in seconds.
158 */
159DECLINLINE(PRTTIMESPEC) RTTimeSpecSetSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
160{
161 pTime->i64NanosecondsRelativeToUnixEpoch = i64Seconds * RT_NS_1SEC;
162 return pTime;
163}
164
165
166/**
167 * Makes the time spec absolute like abs() does (i.e. a positive value).
168 *
169 * @returns pTime.
170 * @param pTime The time spec to modify.
171 */
172DECLINLINE(PRTTIMESPEC) RTTimeSpecAbsolute(PRTTIMESPEC pTime)
173{
174 if (pTime->i64NanosecondsRelativeToUnixEpoch < 0)
175 pTime->i64NanosecondsRelativeToUnixEpoch = -pTime->i64NanosecondsRelativeToUnixEpoch;
176 return pTime;
177}
178
179
180/**
181 * Negates the time.
182 *
183 * @returns pTime.
184 * @param pTime The time spec to modify.
185 */
186DECLINLINE(PRTTIMESPEC) RTTimeSpecNegate(PRTTIMESPEC pTime)
187{
188 pTime->i64NanosecondsRelativeToUnixEpoch = -pTime->i64NanosecondsRelativeToUnixEpoch;
189 return pTime;
190}
191
192
193/**
194 * Adds a time period to the time.
195 *
196 * @returns pTime.
197 * @param pTime The time spec to modify.
198 * @param pTimeAdd The time spec to add to pTime.
199 */
200DECLINLINE(PRTTIMESPEC) RTTimeSpecAdd(PRTTIMESPEC pTime, PCRTTIMESPEC pTimeAdd)
201{
202 pTime->i64NanosecondsRelativeToUnixEpoch += pTimeAdd->i64NanosecondsRelativeToUnixEpoch;
203 return pTime;
204}
205
206
207/**
208 * Adds a time period give as nanoseconds from the time.
209 *
210 * @returns pTime.
211 * @param pTime The time spec to modify.
212 * @param i64Nano The time period in nanoseconds.
213 */
214DECLINLINE(PRTTIMESPEC) RTTimeSpecAddNano(PRTTIMESPEC pTime, int64_t i64Nano)
215{
216 pTime->i64NanosecondsRelativeToUnixEpoch += i64Nano;
217 return pTime;
218}
219
220
221/**
222 * Adds a time period give as microseconds from the time.
223 *
224 * @returns pTime.
225 * @param pTime The time spec to modify.
226 * @param i64Micro The time period in microseconds.
227 */
228DECLINLINE(PRTTIMESPEC) RTTimeSpecAddMicro(PRTTIMESPEC pTime, int64_t i64Micro)
229{
230 pTime->i64NanosecondsRelativeToUnixEpoch += i64Micro * RT_NS_1US;
231 return pTime;
232}
233
234
235/**
236 * Adds a time period give as milliseconds from the time.
237 *
238 * @returns pTime.
239 * @param pTime The time spec to modify.
240 * @param i64Milli The time period in milliseconds.
241 */
242DECLINLINE(PRTTIMESPEC) RTTimeSpecAddMilli(PRTTIMESPEC pTime, int64_t i64Milli)
243{
244 pTime->i64NanosecondsRelativeToUnixEpoch += i64Milli * RT_NS_1MS;
245 return pTime;
246}
247
248
249/**
250 * Adds a time period give as seconds from the time.
251 *
252 * @returns pTime.
253 * @param pTime The time spec to modify.
254 * @param i64Seconds The time period in seconds.
255 */
256DECLINLINE(PRTTIMESPEC) RTTimeSpecAddSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
257{
258 pTime->i64NanosecondsRelativeToUnixEpoch += i64Seconds * RT_NS_1SEC;
259 return pTime;
260}
261
262
263/**
264 * Subtracts a time period from the time.
265 *
266 * @returns pTime.
267 * @param pTime The time spec to modify.
268 * @param pTimeSub The time spec to subtract from pTime.
269 */
270DECLINLINE(PRTTIMESPEC) RTTimeSpecSub(PRTTIMESPEC pTime, PCRTTIMESPEC pTimeSub)
271{
272 pTime->i64NanosecondsRelativeToUnixEpoch -= pTimeSub->i64NanosecondsRelativeToUnixEpoch;
273 return pTime;
274}
275
276
277/**
278 * Subtracts a time period give as nanoseconds from the time.
279 *
280 * @returns pTime.
281 * @param pTime The time spec to modify.
282 * @param i64Nano The time period in nanoseconds.
283 */
284DECLINLINE(PRTTIMESPEC) RTTimeSpecSubNano(PRTTIMESPEC pTime, int64_t i64Nano)
285{
286 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Nano;
287 return pTime;
288}
289
290
291/**
292 * Subtracts a time period give as microseconds from the time.
293 *
294 * @returns pTime.
295 * @param pTime The time spec to modify.
296 * @param i64Micro The time period in microseconds.
297 */
298DECLINLINE(PRTTIMESPEC) RTTimeSpecSubMicro(PRTTIMESPEC pTime, int64_t i64Micro)
299{
300 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Micro * RT_NS_1US;
301 return pTime;
302}
303
304
305/**
306 * Subtracts a time period give as milliseconds from the time.
307 *
308 * @returns pTime.
309 * @param pTime The time spec to modify.
310 * @param i64Milli The time period in milliseconds.
311 */
312DECLINLINE(PRTTIMESPEC) RTTimeSpecSubMilli(PRTTIMESPEC pTime, int64_t i64Milli)
313{
314 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Milli * RT_NS_1MS;
315 return pTime;
316}
317
318
319/**
320 * Subtracts a time period give as seconds from the time.
321 *
322 * @returns pTime.
323 * @param pTime The time spec to modify.
324 * @param i64Seconds The time period in seconds.
325 */
326DECLINLINE(PRTTIMESPEC) RTTimeSpecSubSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
327{
328 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Seconds * RT_NS_1SEC;
329 return pTime;
330}
331
332
333/**
334 * Gives the time in seconds and nanoseconds.
335 *
336 * @returns pTime.
337 * @param pTime The time spec to interpret.
338 * @param *pi32Seconds Where to store the time period in seconds.
339 * @param *pi32Nano Where to store the time period in nanoseconds.
340 */
341DECLINLINE(void) RTTimeSpecGetSecondsAndNano(PRTTIMESPEC pTime, int32_t *pi32Seconds, int32_t *pi32Nano)
342{
343 int64_t i64 = RTTimeSpecGetNano(pTime);
344 int32_t i32Nano = (int32_t)(i64 % RT_NS_1SEC);
345 i64 /= RT_NS_1SEC;
346 if (i32Nano < 0)
347 {
348 i32Nano += RT_NS_1SEC;
349 i64--;
350 }
351 *pi32Seconds = (int32_t)i64;
352 *pi32Nano = i32Nano;
353}
354
355
356/* PORTME: Add struct timeval guard macro here. */
357#if defined(RTTIME_INCL_TIMEVAL) || defined(_STRUCT_TIMEVAL) || defined(_SYS__TIMEVAL_H_) || defined(_SYS_TIME_H) || defined(_TIMEVAL) || defined(_LINUX_TIME_H) \
358 || (defined(RT_OS_NETBSD) && defined(_SYS_TIME_H_))
359/**
360 * Gets the time as POSIX timeval.
361 *
362 * @returns pTime.
363 * @param pTime The time spec to interpret.
364 * @param pTimeval Where to store the time as POSIX timeval.
365 */
366DECLINLINE(struct timeval *) RTTimeSpecGetTimeval(PCRTTIMESPEC pTime, struct timeval *pTimeval)
367{
368 int64_t i64 = RTTimeSpecGetMicro(pTime);
369 int32_t i32Micro = (int32_t)(i64 % RT_US_1SEC);
370 i64 /= RT_US_1SEC;
371 if (i32Micro < 0)
372 {
373 i32Micro += RT_US_1SEC;
374 i64--;
375 }
376 pTimeval->tv_sec = (time_t)i64;
377 pTimeval->tv_usec = i32Micro;
378 return pTimeval;
379}
380
381/**
382 * Sets the time as POSIX timeval.
383 *
384 * @returns pTime.
385 * @param pTime The time spec to modify.
386 * @param pTimeval Pointer to the POSIX timeval struct with the new time.
387 */
388DECLINLINE(PRTTIMESPEC) RTTimeSpecSetTimeval(PRTTIMESPEC pTime, const struct timeval *pTimeval)
389{
390 return RTTimeSpecAddMicro(RTTimeSpecSetSeconds(pTime, pTimeval->tv_sec), pTimeval->tv_usec);
391}
392#endif /* various ways of detecting struct timeval */
393
394
395/* PORTME: Add struct timespec guard macro here. */
396#if defined(RTTIME_INCL_TIMESPEC) || defined(_STRUCT_TIMESPEC) || defined(_SYS__TIMESPEC_H_) || defined(TIMEVAL_TO_TIMESPEC) || defined(_TIMESPEC) \
397 || (defined(RT_OS_NETBSD) && defined(_SYS_TIME_H_))
398/**
399 * Gets the time as POSIX timespec.
400 *
401 * @returns pTime.
402 * @param pTime The time spec to interpret.
403 * @param pTimespec Where to store the time as POSIX timespec.
404 */
405DECLINLINE(struct timespec *) RTTimeSpecGetTimespec(PCRTTIMESPEC pTime, struct timespec *pTimespec)
406{
407 int64_t i64 = RTTimeSpecGetNano(pTime);
408 int32_t i32Nano = (int32_t)(i64 % RT_NS_1SEC);
409 i64 /= RT_NS_1SEC;
410 if (i32Nano < 0)
411 {
412 i32Nano += RT_NS_1SEC;
413 i64--;
414 }
415 pTimespec->tv_sec = (time_t)i64;
416 pTimespec->tv_nsec = i32Nano;
417 return pTimespec;
418}
419
420/**
421 * Sets the time as POSIX timespec.
422 *
423 * @returns pTime.
424 * @param pTime The time spec to modify.
425 * @param pTimespec Pointer to the POSIX timespec struct with the new time.
426 */
427DECLINLINE(PRTTIMESPEC) RTTimeSpecSetTimespec(PRTTIMESPEC pTime, const struct timespec *pTimespec)
428{
429 return RTTimeSpecAddNano(RTTimeSpecSetSeconds(pTime, pTimespec->tv_sec), pTimespec->tv_nsec);
430}
431#endif /* various ways of detecting struct timespec */
432
433
434
435/** The offset of the unix epoch and the base for NT time (in 100ns units).
436 * Nt time starts at 1601-01-01 00:00:00. */
437#define RTTIME_NT_TIME_OFFSET_UNIX (116444736000000000LL)
438
439
440/**
441 * Gets the time as NT time.
442 *
443 * @returns Nt time.
444 * @param pTime The time spec to interpret.
445 */
446DECLINLINE(uint64_t) RTTimeSpecGetNtTime(PCRTTIMESPEC pTime)
447{
448 return pTime->i64NanosecondsRelativeToUnixEpoch / 100
449 + RTTIME_NT_TIME_OFFSET_UNIX;
450}
451
452
453/**
454 * Sets the time given by Nt time.
455 *
456 * @returns pTime.
457 * @param pTime The time spec to modify.
458 * @param u64NtTime The new time in Nt time.
459 */
460DECLINLINE(PRTTIMESPEC) RTTimeSpecSetNtTime(PRTTIMESPEC pTime, uint64_t u64NtTime)
461{
462 pTime->i64NanosecondsRelativeToUnixEpoch =
463 ((int64_t)u64NtTime - RTTIME_NT_TIME_OFFSET_UNIX) * 100;
464 return pTime;
465}
466
467
468#ifdef _FILETIME_
469/**
470 * Gets the time as NT file time.
471 *
472 * @returns pFileTime.
473 * @param pTime The time spec to interpret.
474 * @param pFileTime Pointer to NT filetime structure.
475 */
476DECLINLINE(PFILETIME) RTTimeSpecGetNtFileTime(PCRTTIMESPEC pTime, PFILETIME pFileTime)
477{
478 *((uint64_t *)pFileTime) = RTTimeSpecGetNtTime(pTime);
479 return pFileTime;
480}
481
482/**
483 * Sets the time as NT file time.
484 *
485 * @returns pTime.
486 * @param pTime The time spec to modify.
487 * @param pFileTime Where to store the time as Nt file time.
488 */
489DECLINLINE(PRTTIMESPEC) RTTimeSpecSetNtFileTime(PRTTIMESPEC pTime, const FILETIME *pFileTime)
490{
491 return RTTimeSpecSetNtTime(pTime, *(const uint64_t *)pFileTime);
492}
493#endif
494
495
496/** The offset to the start of DOS time.
497 * DOS time starts 1980-01-01 00:00:00. */
498#define RTTIME_OFFSET_DOS_TIME (315532800000000000LL)
499
500
501/**
502 * Gets the time as seconds relative to the start of dos time.
503 *
504 * @returns seconds relative to the start of dos time.
505 * @param pTime The time spec to interpret.
506 */
507DECLINLINE(int64_t) RTTimeSpecGetDosSeconds(PCRTTIMESPEC pTime)
508{
509 return (pTime->i64NanosecondsRelativeToUnixEpoch - RTTIME_OFFSET_DOS_TIME)
510 / RT_NS_1SEC;
511}
512
513
514/**
515 * Sets the time given by seconds relative to the start of dos time.
516 *
517 * @returns pTime.
518 * @param pTime The time spec to modify.
519 * @param i64Seconds The new time in seconds relative to the start of dos time.
520 */
521DECLINLINE(PRTTIMESPEC) RTTimeSpecSetDosSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
522{
523 pTime->i64NanosecondsRelativeToUnixEpoch = i64Seconds * RT_NS_1SEC
524 + RTTIME_OFFSET_DOS_TIME;
525 return pTime;
526}
527
528
529/**
530 * Compare two time specs.
531 *
532 * @returns true they are equal.
533 * @returns false they are not equal.
534 * @param pTime1 The 1st time spec.
535 * @param pTime2 The 2nd time spec.
536 */
537DECLINLINE(bool) RTTimeSpecIsEqual(PCRTTIMESPEC pTime1, PCRTTIMESPEC pTime2)
538{
539 return pTime1->i64NanosecondsRelativeToUnixEpoch == pTime2->i64NanosecondsRelativeToUnixEpoch;
540}
541
542
543/**
544 * Compare two time specs.
545 *
546 * @returns 0 if equal, -1 if @a pLeft is smaller, 1 if @a pLeft is larger.
547 * @returns false they are not equal.
548 * @param pLeft The 1st time spec.
549 * @param pRight The 2nd time spec.
550 */
551DECLINLINE(int) RTTimeSpecCompare(PCRTTIMESPEC pLeft, PCRTTIMESPEC pRight)
552{
553 if (pLeft->i64NanosecondsRelativeToUnixEpoch == pRight->i64NanosecondsRelativeToUnixEpoch)
554 return 0;
555 return pLeft->i64NanosecondsRelativeToUnixEpoch < pRight->i64NanosecondsRelativeToUnixEpoch ? -1 : 1;
556}
557
558
559/**
560 * Converts a time spec to a ISO date string.
561 *
562 * @returns psz on success.
563 * @returns NULL on buffer underflow.
564 * @param pTime The time spec.
565 * @param psz Where to store the string.
566 * @param cb The size of the buffer.
567 */
568RTDECL(char *) RTTimeSpecToString(PCRTTIMESPEC pTime, char *psz, size_t cb);
569
570/**
571 * Attempts to convert an ISO date string to a time structure.
572 *
573 * We're a little forgiving with zero padding, unspecified parts, and leading
574 * and trailing spaces.
575 *
576 * @retval pTime on success,
577 * @retval NULL on failure.
578 * @param pTime The time spec.
579 * @param pszString The ISO date string to convert.
580 */
581RTDECL(PRTTIMESPEC) RTTimeSpecFromString(PRTTIMESPEC pTime, const char *pszString);
582
583/** @} */
584
585
586/**
587 * Exploded time.
588 */
589typedef struct RTTIME
590{
591 /** The year number. */
592 int32_t i32Year;
593 /** The month of the year (1-12). January is 1. */
594 uint8_t u8Month;
595 /** The day of the week (0-6). Monday is 0. */
596 uint8_t u8WeekDay;
597 /** The day of the year (1-366). January the 1st is 1. */
598 uint16_t u16YearDay;
599 /** The day of the month (1-31). */
600 uint8_t u8MonthDay;
601 /** Hour of the day (0-23). */
602 uint8_t u8Hour;
603 /** The minute of the hour (0-59). */
604 uint8_t u8Minute;
605 /** The second of the minute (0-60).
606 * (u32Nanosecond / 1000000) */
607 uint8_t u8Second;
608 /** The nanoseconds of the second (0-999999999). */
609 uint32_t u32Nanosecond;
610 /** Flags, of the RTTIME_FLAGS_* \#defines. */
611 uint32_t fFlags;
612 /** UCT time offset in minutes (-840-840). Positive for timezones east of
613 * UTC, negative for zones to the west. Same as what RTTimeLocalDeltaNano
614 * & RTTimeLocalDeltaNanoFor returns, just different unit. */
615 int32_t offUTC;
616} RTTIME;
617AssertCompileSize(RTTIME, 24);
618/** Pointer to a exploded time structure. */
619typedef RTTIME *PRTTIME;
620/** Pointer to a const exploded time structure. */
621typedef const RTTIME *PCRTTIME;
622
623/** @name RTTIME::fFlags values.
624 * @{ */
625/** Set if the time is UTC. If clear the time local time. */
626#define RTTIME_FLAGS_TYPE_MASK 3
627/** the time is UTC time. */
628#define RTTIME_FLAGS_TYPE_UTC 2
629/** The time is local time. */
630#define RTTIME_FLAGS_TYPE_LOCAL 3
631
632/** Set if the time is local and daylight saving time is in effect.
633 * Not bit is not valid if RTTIME_FLAGS_NO_DST_DATA is set. */
634#define RTTIME_FLAGS_DST RT_BIT(4)
635/** Set if the time is local and there is no data available on daylight saving time. */
636#define RTTIME_FLAGS_NO_DST_DATA RT_BIT(5)
637/** Set if the year is a leap year.
638 * This is mutual exclusiv with RTTIME_FLAGS_COMMON_YEAR. */
639#define RTTIME_FLAGS_LEAP_YEAR RT_BIT(6)
640/** Set if the year is a common year.
641 * This is mutual exclusiv with RTTIME_FLAGS_LEAP_YEAR. */
642#define RTTIME_FLAGS_COMMON_YEAR RT_BIT(7)
643/** The mask of valid flags. */
644#define RTTIME_FLAGS_MASK UINT32_C(0xff)
645/** @} */
646
647
648/**
649 * Gets the current system time (UTC).
650 *
651 * @returns pTime.
652 * @param pTime Where to store the time.
653 */
654RTDECL(PRTTIMESPEC) RTTimeNow(PRTTIMESPEC pTime);
655
656/**
657 * Sets the system time.
658 *
659 * @returns IPRT status code
660 * @param pTime The new system time (UTC).
661 *
662 * @remarks This will usually fail because changing the wall time is usually
663 * requires extra privileges.
664 */
665RTDECL(int) RTTimeSet(PCRTTIMESPEC pTime);
666
667/**
668 * Explodes a time spec (UTC).
669 *
670 * @returns pTime.
671 * @param pTime Where to store the exploded time.
672 * @param pTimeSpec The time spec to exploded.
673 */
674RTDECL(PRTTIME) RTTimeExplode(PRTTIME pTime, PCRTTIMESPEC pTimeSpec);
675
676/**
677 * Implodes exploded time to a time spec (UTC).
678 *
679 * @returns pTime on success.
680 * @returns NULL if the pTime data is invalid.
681 * @param pTimeSpec Where to store the imploded UTC time.
682 * If pTime specifies a time which outside the range, maximum or
683 * minimum values will be returned.
684 * @param pTime Pointer to the exploded time to implode.
685 * The fields u8Month, u8WeekDay and u8MonthDay are not used,
686 * and all the other fields are expected to be within their
687 * bounds. Use RTTimeNormalize() to calculate u16YearDay and
688 * normalize the ranges of the fields.
689 */
690RTDECL(PRTTIMESPEC) RTTimeImplode(PRTTIMESPEC pTimeSpec, PCRTTIME pTime);
691
692/**
693 * Normalizes the fields of a time structure.
694 *
695 * It is possible to calculate year-day from month/day and vice
696 * versa. If you adjust any of of these, make sure to zero the
697 * other so you make it clear which of the fields to use. If
698 * it's ambiguous, the year-day field is used (and you get
699 * assertions in debug builds).
700 *
701 * All the time fields and the year-day or month/day fields will
702 * be adjusted for overflows. (Since all fields are unsigned, there
703 * is no underflows.) It is possible to exploit this for simple
704 * date math, though the recommended way of doing that to implode
705 * the time into a timespec and do the math on that.
706 *
707 * @returns pTime on success.
708 * @returns NULL if the data is invalid.
709 *
710 * @param pTime The time structure to normalize.
711 *
712 * @remarks This function doesn't work with local time, only with UTC time.
713 */
714RTDECL(PRTTIME) RTTimeNormalize(PRTTIME pTime);
715
716/**
717 * Gets the current local system time.
718 *
719 * @returns pTime.
720 * @param pTime Where to store the local time.
721 */
722RTDECL(PRTTIMESPEC) RTTimeLocalNow(PRTTIMESPEC pTime);
723
724/**
725 * Gets the current delta between UTC and local time.
726 *
727 * @code
728 * RTTIMESPEC LocalTime;
729 * RTTimeSpecAddNano(RTTimeNow(&LocalTime), RTTimeLocalDeltaNano());
730 * @endcode
731 *
732 * @returns Returns the nanosecond delta between UTC and local time.
733 */
734RTDECL(int64_t) RTTimeLocalDeltaNano(void);
735
736/**
737 * Gets the delta between UTC and local time at the given time.
738 *
739 * @code
740 * RTTIMESPEC LocalTime;
741 * RTTimeNow(&LocalTime);
742 * RTTimeSpecAddNano(&LocalTime, RTTimeLocalDeltaNanoFor(&LocalTime));
743 * @endcode
744 *
745 * @param pTimeSpec The time spec giving the time to get the delta for.
746 * @returns Returns the nanosecond delta between UTC and local time.
747 */
748RTDECL(int64_t) RTTimeLocalDeltaNanoFor(PCRTTIMESPEC pTimeSpec);
749
750/**
751 * Explodes a time spec to the localized timezone.
752 *
753 * @returns pTime.
754 * @param pTime Where to store the exploded time.
755 * @param pTimeSpec The time spec to exploded (UTC).
756 */
757RTDECL(PRTTIME) RTTimeLocalExplode(PRTTIME pTime, PCRTTIMESPEC pTimeSpec);
758
759/**
760 * Normalizes the fields of a time structure containing local time.
761 *
762 * See RTTimeNormalize for details.
763 *
764 * @returns pTime on success.
765 * @returns NULL if the data is invalid.
766 * @param pTime The time structure to normalize.
767 */
768RTDECL(PRTTIME) RTTimeLocalNormalize(PRTTIME pTime);
769
770/**
771 * Converts a time structure to UTC, relying on UTC offset information
772 * if it contains local time.
773 *
774 * @returns pTime on success.
775 * @returns NULL if the data is invalid.
776 * @param pTime The time structure to convert.
777 */
778RTDECL(PRTTIME) RTTimeConvertToZulu(PRTTIME pTime);
779
780/**
781 * Converts a time spec to a ISO date string.
782 *
783 * @returns psz on success.
784 * @returns NULL on buffer underflow.
785 * @param pTime The time. Caller should've normalized this.
786 * @param psz Where to store the string.
787 * @param cb The size of the buffer.
788 */
789RTDECL(char *) RTTimeToString(PCRTTIME pTime, char *psz, size_t cb);
790
791/**
792 * Converts a time spec to a ISO date string, extended version.
793 *
794 * @returns Output string length on success (positive), VERR_BUFFER_OVERFLOW
795 * (negative) or VERR_OUT_OF_RANGE (negative) on failure.
796 * @param pTime The time. Caller should've normalized this.
797 * @param psz Where to store the string.
798 * @param cb The size of the buffer.
799 * @param cFractionDigits Number of digits in the fraction. Max is 9.
800 */
801RTDECL(ssize_t) RTTimeToStringEx(PCRTTIME pTime, char *psz, size_t cb, unsigned cFractionDigits);
802
803/** Suggested buffer length for RTTimeToString and RTTimeToStringEx output, including terminator. */
804#define RTTIME_STR_LEN 40
805
806/**
807 * Attempts to convert an ISO date string to a time structure.
808 *
809 * We're a little forgiving with zero padding, unspecified parts, and leading
810 * and trailing spaces.
811 *
812 * @retval pTime on success,
813 * @retval NULL on failure.
814 * @param pTime Where to store the time on success.
815 * @param pszString The ISO date string to convert.
816 */
817RTDECL(PRTTIME) RTTimeFromString(PRTTIME pTime, const char *pszString);
818
819/**
820 * Formats the given time on a RTC-2822 compliant format.
821 *
822 * @returns Output string length on success (positive), VERR_BUFFER_OVERFLOW
823 * (negative) on failure.
824 * @param pTime The time. Caller should've normalized this.
825 * @param psz Where to store the string.
826 * @param cb The size of the buffer.
827 * @param fFlags RTTIME_RFC2822_F_XXX
828 * @sa RTTIME_RFC2822_LEN
829 */
830RTDECL(ssize_t) RTTimeToRfc2822(PRTTIME pTime, char *psz, size_t cb, uint32_t fFlags);
831
832/** Suggested buffer length for RTTimeToRfc2822 output, including terminator. */
833#define RTTIME_RFC2822_LEN 40
834/** @name RTTIME_RFC2822_F_XXX
835 * @{ */
836/** Use the deprecated GMT timezone instead of +/-0000.
837 * This is required by the HTTP RFC-7231 7.1.1.1. */
838#define RTTIME_RFC2822_F_GMT RT_BIT_32(0)
839/** @} */
840
841/**
842 * Attempts to convert an RFC-2822 date string to a time structure.
843 *
844 * We're a little forgiving with zero padding, unspecified parts, and leading
845 * and trailing spaces.
846 *
847 * @retval pTime on success,
848 * @retval NULL on failure.
849 * @param pTime Where to store the time on success.
850 * @param pszString The ISO date string to convert.
851 */
852RTDECL(PRTTIME) RTTimeFromRfc2822(PRTTIME pTime, const char *pszString);
853
854/**
855 * Checks if a year is a leap year or not.
856 *
857 * @returns true if it's a leap year.
858 * @returns false if it's a common year.
859 * @param i32Year The year in question.
860 */
861RTDECL(bool) RTTimeIsLeapYear(int32_t i32Year);
862
863/**
864 * Compares two normalized time structures.
865 *
866 * @retval 0 if equal.
867 * @retval -1 if @a pLeft is earlier than @a pRight.
868 * @retval 1 if @a pRight is earlier than @a pLeft.
869 *
870 * @param pLeft The left side time. NULL is accepted.
871 * @param pRight The right side time. NULL is accepted.
872 *
873 * @note A NULL time is considered smaller than anything else. If both are
874 * NULL, they are considered equal.
875 */
876RTDECL(int) RTTimeCompare(PCRTTIME pLeft, PCRTTIME pRight);
877
878/**
879 * Gets the current nanosecond timestamp.
880 *
881 * @returns nanosecond timestamp.
882 */
883RTDECL(uint64_t) RTTimeNanoTS(void);
884
885/**
886 * Gets the current millisecond timestamp.
887 *
888 * @returns millisecond timestamp.
889 */
890RTDECL(uint64_t) RTTimeMilliTS(void);
891
892/**
893 * Debugging the time api.
894 *
895 * @returns the number of 1ns steps which has been applied by RTTimeNanoTS().
896 */
897RTDECL(uint32_t) RTTimeDbgSteps(void);
898
899/**
900 * Debugging the time api.
901 *
902 * @returns the number of times the TSC interval expired RTTimeNanoTS().
903 */
904RTDECL(uint32_t) RTTimeDbgExpired(void);
905
906/**
907 * Debugging the time api.
908 *
909 * @returns the number of bad previous values encountered by RTTimeNanoTS().
910 */
911RTDECL(uint32_t) RTTimeDbgBad(void);
912
913/**
914 * Debugging the time api.
915 *
916 * @returns the number of update races in RTTimeNanoTS().
917 */
918RTDECL(uint32_t) RTTimeDbgRaces(void);
919
920/** @name RTTimeNanoTS GIP worker functions, for TM.
921 * @{ */
922/** Pointer to a RTTIMENANOTSDATA structure. */
923typedef struct RTTIMENANOTSDATA *PRTTIMENANOTSDATA;
924
925/**
926 * Nanosecond timestamp data.
927 *
928 * This is used to keep track of statistics and callback so IPRT
929 * and TM (VirtualBox) can share code.
930 *
931 * @remark Keep this in sync with the assembly version in timesupA.asm.
932 */
933typedef struct RTTIMENANOTSDATA
934{
935 /** Where the previous timestamp is stored.
936 * This is maintained to ensure that time doesn't go backwards or anything. */
937 uint64_t volatile *pu64Prev;
938
939 /**
940 * Helper function that's used by the assembly routines when something goes bust.
941 *
942 * @param pData Pointer to this structure.
943 * @param u64NanoTS The calculated nano ts.
944 * @param u64DeltaPrev The delta relative to the previously returned timestamp.
945 * @param u64PrevNanoTS The previously returned timestamp (as it was read it).
946 */
947 DECLCALLBACKMEMBER(void, pfnBad)(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS);
948
949 /**
950 * Callback for when rediscovery is required.
951 *
952 * @returns Nanosecond timestamp.
953 * @param pData Pointer to this structure.
954 */
955 DECLCALLBACKMEMBER(uint64_t, pfnRediscover)(PRTTIMENANOTSDATA pData);
956
957 /**
958 * Callback for when some CPU index related stuff goes wrong.
959 *
960 * @returns Nanosecond timestamp.
961 * @param pData Pointer to this structure.
962 * @param idApic The APIC ID if available, otherwise (UINT16_MAX-1).
963 * @param iCpuSet The CPU set index if available, otherwise
964 * (UINT16_MAX-1).
965 * @param iGipCpu The GIP CPU array index if available, otherwise
966 * (UINT16_MAX-1).
967 */
968 DECLCALLBACKMEMBER(uint64_t, pfnBadCpuIndex)(PRTTIMENANOTSDATA pData, uint16_t idApic, uint16_t iCpuSet, uint16_t iGipCpu);
969
970 /** Number of 1ns steps because of overshooting the period. */
971 uint32_t c1nsSteps;
972 /** The number of times the interval expired (overflow). */
973 uint32_t cExpired;
974 /** Number of "bad" previous values. */
975 uint32_t cBadPrev;
976 /** The number of update races. */
977 uint32_t cUpdateRaces;
978} RTTIMENANOTSDATA;
979
980#ifndef IN_RING3
981/**
982 * The Ring-3 layout of the RTTIMENANOTSDATA structure.
983 */
984typedef struct RTTIMENANOTSDATAR3
985{
986 R3PTRTYPE(uint64_t volatile *) pu64Prev;
987 DECLR3CALLBACKMEMBER(void, pfnBad,(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS));
988 DECLR3CALLBACKMEMBER(uint64_t, pfnRediscover,(PRTTIMENANOTSDATA pData));
989 DECLR3CALLBACKMEMBER(uint64_t, pfnBadCpuIndex,(PRTTIMENANOTSDATA pData, uint16_t idApic, uint16_t iCpuSet, uint16_t iGipCpu));
990 uint32_t c1nsSteps;
991 uint32_t cExpired;
992 uint32_t cBadPrev;
993 uint32_t cUpdateRaces;
994} RTTIMENANOTSDATAR3;
995#else
996typedef RTTIMENANOTSDATA RTTIMENANOTSDATAR3;
997#endif
998
999#ifndef IN_RING0
1000/**
1001 * The Ring-3 layout of the RTTIMENANOTSDATA structure.
1002 */
1003typedef struct RTTIMENANOTSDATAR0
1004{
1005 R0PTRTYPE(uint64_t volatile *) pu64Prev;
1006 DECLR0CALLBACKMEMBER(void, pfnBad,(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS));
1007 DECLR0CALLBACKMEMBER(uint64_t, pfnRediscover,(PRTTIMENANOTSDATA pData));
1008 DECLR0CALLBACKMEMBER(uint64_t, pfnBadCpuIndex,(PRTTIMENANOTSDATA pData, uint16_t idApic, uint16_t iCpuSet, uint16_t iGipCpu));
1009 uint32_t c1nsSteps;
1010 uint32_t cExpired;
1011 uint32_t cBadPrev;
1012 uint32_t cUpdateRaces;
1013} RTTIMENANOTSDATAR0;
1014#else
1015typedef RTTIMENANOTSDATA RTTIMENANOTSDATAR0;
1016#endif
1017
1018#ifndef IN_RC
1019/**
1020 * The RC layout of the RTTIMENANOTSDATA structure.
1021 */
1022typedef struct RTTIMENANOTSDATARC
1023{
1024 RCPTRTYPE(uint64_t volatile *) pu64Prev;
1025 DECLRCCALLBACKMEMBER(void, pfnBad,(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS));
1026 DECLRCCALLBACKMEMBER(uint64_t, pfnRediscover,(PRTTIMENANOTSDATA pData));
1027 DECLRCCALLBACKMEMBER(uint64_t, pfnBadCpuIndex,(PRTTIMENANOTSDATA pData, uint16_t idApic, uint16_t iCpuSet, uint16_t iGipCpu));
1028 uint32_t c1nsSteps;
1029 uint32_t cExpired;
1030 uint32_t cBadPrev;
1031 uint32_t cUpdateRaces;
1032} RTTIMENANOTSDATARC;
1033#else
1034typedef RTTIMENANOTSDATA RTTIMENANOTSDATARC;
1035#endif
1036
1037/** Internal RTTimeNanoTS worker (assembly). */
1038typedef DECLCALLBACK(uint64_t) FNTIMENANOTSINTERNAL(PRTTIMENANOTSDATA pData);
1039/** Pointer to an internal RTTimeNanoTS worker (assembly). */
1040typedef FNTIMENANOTSINTERNAL *PFNTIMENANOTSINTERNAL;
1041RTDECL(uint64_t) RTTimeNanoTSLegacySyncInvarNoDelta(PRTTIMENANOTSDATA pData);
1042RTDECL(uint64_t) RTTimeNanoTSLFenceSyncInvarNoDelta(PRTTIMENANOTSDATA pData);
1043#ifdef IN_RING3
1044RTDECL(uint64_t) RTTimeNanoTSLegacyAsyncUseApicId(PRTTIMENANOTSDATA pData);
1045RTDECL(uint64_t) RTTimeNanoTSLegacyAsyncUseRdtscp(PRTTIMENANOTSDATA pData);
1046RTDECL(uint64_t) RTTimeNanoTSLegacyAsyncUseRdtscpGroupChNumCl(PRTTIMENANOTSDATA pData);
1047RTDECL(uint64_t) RTTimeNanoTSLegacyAsyncUseIdtrLim(PRTTIMENANOTSDATA pData);
1048RTDECL(uint64_t) RTTimeNanoTSLegacySyncInvarWithDeltaUseApicId(PRTTIMENANOTSDATA pData);
1049RTDECL(uint64_t) RTTimeNanoTSLegacySyncInvarWithDeltaUseRdtscp(PRTTIMENANOTSDATA pData);
1050RTDECL(uint64_t) RTTimeNanoTSLegacySyncInvarWithDeltaUseIdtrLim(PRTTIMENANOTSDATA pData);
1051RTDECL(uint64_t) RTTimeNanoTSLFenceAsyncUseApicId(PRTTIMENANOTSDATA pData);
1052RTDECL(uint64_t) RTTimeNanoTSLFenceAsyncUseRdtscp(PRTTIMENANOTSDATA pData);
1053RTDECL(uint64_t) RTTimeNanoTSLFenceAsyncUseRdtscpGroupChNumCl(PRTTIMENANOTSDATA pData);
1054RTDECL(uint64_t) RTTimeNanoTSLFenceAsyncUseIdtrLim(PRTTIMENANOTSDATA pData);
1055RTDECL(uint64_t) RTTimeNanoTSLFenceSyncInvarWithDeltaUseApicId(PRTTIMENANOTSDATA pData);
1056RTDECL(uint64_t) RTTimeNanoTSLFenceSyncInvarWithDeltaUseRdtscp(PRTTIMENANOTSDATA pData);
1057RTDECL(uint64_t) RTTimeNanoTSLFenceSyncInvarWithDeltaUseIdtrLim(PRTTIMENANOTSDATA pData);
1058#else
1059RTDECL(uint64_t) RTTimeNanoTSLegacyAsync(PRTTIMENANOTSDATA pData);
1060RTDECL(uint64_t) RTTimeNanoTSLegacySyncInvarWithDelta(PRTTIMENANOTSDATA pData);
1061RTDECL(uint64_t) RTTimeNanoTSLFenceAsync(PRTTIMENANOTSDATA pData);
1062RTDECL(uint64_t) RTTimeNanoTSLFenceSyncInvarWithDelta(PRTTIMENANOTSDATA pData);
1063#endif
1064
1065/** @} */
1066
1067
1068/**
1069 * Gets the current nanosecond timestamp.
1070 *
1071 * This differs from RTTimeNanoTS in that it will use system APIs and not do any
1072 * resolution or performance optimizations.
1073 *
1074 * @returns nanosecond timestamp.
1075 */
1076RTDECL(uint64_t) RTTimeSystemNanoTS(void);
1077
1078/**
1079 * Gets the current millisecond timestamp.
1080 *
1081 * This differs from RTTimeNanoTS in that it will use system APIs and not do any
1082 * resolution or performance optimizations.
1083 *
1084 * @returns millisecond timestamp.
1085 */
1086RTDECL(uint64_t) RTTimeSystemMilliTS(void);
1087
1088/**
1089 * Get the nanosecond timestamp relative to program startup.
1090 *
1091 * @returns Timestamp relative to program startup.
1092 */
1093RTDECL(uint64_t) RTTimeProgramNanoTS(void);
1094
1095/**
1096 * Get the microsecond timestamp relative to program startup.
1097 *
1098 * @returns Timestamp relative to program startup.
1099 */
1100RTDECL(uint64_t) RTTimeProgramMicroTS(void);
1101
1102/**
1103 * Get the millisecond timestamp relative to program startup.
1104 *
1105 * @returns Timestamp relative to program startup.
1106 */
1107RTDECL(uint64_t) RTTimeProgramMilliTS(void);
1108
1109/**
1110 * Get the second timestamp relative to program startup.
1111 *
1112 * @returns Timestamp relative to program startup.
1113 */
1114RTDECL(uint32_t) RTTimeProgramSecTS(void);
1115
1116/**
1117 * Get the RTTimeNanoTS() of when the program started.
1118 *
1119 * @returns Program startup timestamp.
1120 */
1121RTDECL(uint64_t) RTTimeProgramStartNanoTS(void);
1122
1123
1124/**
1125 * Time zone information.
1126 */
1127typedef struct RTTIMEZONEINFO
1128{
1129 /** Unix time zone name (continent/country[/city]|). */
1130 const char *pszUnixName;
1131 /** Windows time zone name. */
1132 const char *pszWindowsName;
1133 /** The length of the unix time zone name. */
1134 uint8_t cchUnixName;
1135 /** The length of the windows time zone name. */
1136 uint8_t cchWindowsName;
1137 /** Two letter country/territory code if applicable, otherwise 'ZZ'. */
1138 char szCountry[3];
1139 /** Two letter windows country/territory code if applicable.
1140 * Empty string if no windows mapping. */
1141 char szWindowsCountry[3];
1142#if 0 /* Add when needed and it's been extracted. */
1143 /** The standard delta in minutes (add to UTC). */
1144 int16_t cMinStdDelta;
1145 /** The daylight saving time delta in minutes (add to UTC). */
1146 int16_t cMinDstDelta;
1147#endif
1148 /** closest matching windows time zone index. */
1149 uint32_t idxWindows;
1150 /** Flags, RTTIMEZONEINFO_F_XXX. */
1151 uint32_t fFlags;
1152} RTTIMEZONEINFO;
1153/** Pointer to time zone info. */
1154typedef RTTIMEZONEINFO const *PCRTTIMEZONEINFO;
1155
1156/** @name RTTIMEZONEINFO_F_XXX - time zone info flags.
1157 * @{ */
1158/** Indicates golden mapping entry for a windows time zone name. */
1159#define RTTIMEZONEINFO_F_GOLDEN RT_BIT_32(0)
1160/** @} */
1161
1162/**
1163 * Looks up static time zone information by unix name.
1164 *
1165 * @returns Pointer to info entry if found, NULL if not.
1166 * @param pszName The unix zone name (TZ).
1167 */
1168RTDECL(PCRTTIMEZONEINFO) RTTimeZoneGetInfoByUnixName(const char *pszName);
1169
1170/**
1171 * Looks up static time zone information by window name.
1172 *
1173 * @returns Pointer to info entry if found, NULL if not.
1174 * @param pszName The windows zone name (reg key).
1175 */
1176RTDECL(PCRTTIMEZONEINFO) RTTimeZoneGetInfoByWindowsName(const char *pszName);
1177
1178/**
1179 * Looks up static time zone information by windows index.
1180 *
1181 * @returns Pointer to info entry if found, NULL if not.
1182 * @param idxZone The windows timezone index.
1183 */
1184RTDECL(PCRTTIMEZONEINFO) RTTimeZoneGetInfoByWindowsIndex(uint32_t idxZone);
1185
1186/**
1187 * Get the current time zone (TZ).
1188 *
1189 * @returns IPRT status code.
1190 * @param pszName Where to return the time zone name.
1191 * @param cbName The size of the name buffer.
1192 */
1193RTDECL(int) RTTimeZoneGetCurrent(char *pszName, size_t cbName);
1194
1195/** @} */
1196
1197RT_C_DECLS_END
1198
1199#endif
1200
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette