VirtualBox

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

Last change on this file since 103224 was 99739, checked in by vboxsync, 17 months ago

*: doxygen corrections (mostly about removing @returns from functions returning void).

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