VirtualBox

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

Last change on this file since 43902 was 39890, checked in by vboxsync, 13 years ago

VMMDev,IGuest,IAdditionsFacility,VBoxGuest,iprt/types.h: VMMDev must track the guest facility reports so they can be saved and restored correctly. Also fixed a reset bug related to guestInfo2. Restrict who can report the status of which facilities. Recalc the runlevel based on which facilities are active. Restrict the number of facilities main tracks.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 26.6 KB
Line 
1/** @file
2 * IPRT - Time.
3 */
4
5/*
6 * Copyright (C) 2006-2007 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
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_time RTTime - Time
35 * @ingroup grp_rt
36 * @{
37 */
38
39/** Time Specification.
40 *
41 * Use the inline RTTimeSpecGet/Set to operate on structure this so we
42 * can easily change the representation if required later.
43 *
44 * The current representation is in nanoseconds relative to the unix epoch
45 * (1970-01-01 00:00:00 UTC). This gives us an approximate span from
46 * 1678 to 2262 without sacrificing the resolution offered by the various
47 * host OSes (BSD & LINUX 1ns, NT 100ns).
48 */
49typedef struct RTTIMESPEC
50{
51 /** Nanoseconds since epoch.
52 * The name is intentially too long to be comfortable to use because you should be
53 * using inline helpers! */
54 int64_t i64NanosecondsRelativeToUnixEpoch;
55} RTTIMESPEC;
56
57
58/** @name RTTIMESPEC methods
59 * @{ */
60
61/**
62 * Gets the time as nanoseconds relative to the unix epoch.
63 *
64 * @returns Nanoseconds relative to unix epoch.
65 * @param pTime The time spec to interpret.
66 */
67DECLINLINE(int64_t) RTTimeSpecGetNano(PCRTTIMESPEC pTime)
68{
69 return pTime->i64NanosecondsRelativeToUnixEpoch;
70}
71
72
73/**
74 * Sets the time give by nanoseconds relative to the unix epoch.
75 *
76 * @returns pTime.
77 * @param pTime The time spec to modify.
78 * @param i64Nano The new time in nanoseconds.
79 */
80DECLINLINE(PRTTIMESPEC) RTTimeSpecSetNano(PRTTIMESPEC pTime, int64_t i64Nano)
81{
82 pTime->i64NanosecondsRelativeToUnixEpoch = i64Nano;
83 return pTime;
84}
85
86
87/**
88 * Gets the time as microseconds relative to the unix epoch.
89 *
90 * @returns microseconds relative to unix epoch.
91 * @param pTime The time spec to interpret.
92 */
93DECLINLINE(int64_t) RTTimeSpecGetMicro(PCRTTIMESPEC pTime)
94{
95 return pTime->i64NanosecondsRelativeToUnixEpoch / 1000;
96}
97
98
99/**
100 * Sets the time given by microseconds relative to the unix epoch.
101 *
102 * @returns pTime.
103 * @param pTime The time spec to modify.
104 * @param i64Micro The new time in microsecond.
105 */
106DECLINLINE(PRTTIMESPEC) RTTimeSpecSetMicro(PRTTIMESPEC pTime, int64_t i64Micro)
107{
108 pTime->i64NanosecondsRelativeToUnixEpoch = i64Micro * 1000;
109 return pTime;
110}
111
112
113/**
114 * Gets the time as milliseconds relative to the unix epoch.
115 *
116 * @returns milliseconds relative to unix epoch.
117 * @param pTime The time spec to interpret.
118 */
119DECLINLINE(int64_t) RTTimeSpecGetMilli(PCRTTIMESPEC pTime)
120{
121 return pTime->i64NanosecondsRelativeToUnixEpoch / 1000000;
122}
123
124
125/**
126 * Sets the time given by milliseconds relative to the unix epoch.
127 *
128 * @returns pTime.
129 * @param pTime The time spec to modify.
130 * @param i64Milli The new time in milliseconds.
131 */
132DECLINLINE(PRTTIMESPEC) RTTimeSpecSetMilli(PRTTIMESPEC pTime, int64_t i64Milli)
133{
134 pTime->i64NanosecondsRelativeToUnixEpoch = i64Milli * 1000000;
135 return pTime;
136}
137
138
139/**
140 * Gets the time as seconds relative to the unix epoch.
141 *
142 * @returns seconds relative to unix epoch.
143 * @param pTime The time spec to interpret.
144 */
145DECLINLINE(int64_t) RTTimeSpecGetSeconds(PCRTTIMESPEC pTime)
146{
147 return pTime->i64NanosecondsRelativeToUnixEpoch / 1000000000;
148}
149
150
151/**
152 * Sets the time given by seconds relative to the unix epoch.
153 *
154 * @returns pTime.
155 * @param pTime The time spec to modify.
156 * @param i64Seconds The new time in seconds.
157 */
158DECLINLINE(PRTTIMESPEC) RTTimeSpecSetSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
159{
160 pTime->i64NanosecondsRelativeToUnixEpoch = i64Seconds * 1000000000;
161 return pTime;
162}
163
164
165/**
166 * Makes the time spec absolute like abs() does (i.e. a positive value).
167 *
168 * @returns pTime.
169 * @param pTime The time spec to modify.
170 */
171DECLINLINE(PRTTIMESPEC) RTTimeSpecAbsolute(PRTTIMESPEC pTime)
172{
173 if (pTime->i64NanosecondsRelativeToUnixEpoch < 0)
174 pTime->i64NanosecondsRelativeToUnixEpoch = -pTime->i64NanosecondsRelativeToUnixEpoch;
175 return pTime;
176}
177
178
179/**
180 * Negates the time.
181 *
182 * @returns pTime.
183 * @param pTime The time spec to modify.
184 */
185DECLINLINE(PRTTIMESPEC) RTTimeSpecNegate(PRTTIMESPEC pTime)
186{
187 pTime->i64NanosecondsRelativeToUnixEpoch = -pTime->i64NanosecondsRelativeToUnixEpoch;
188 return pTime;
189}
190
191
192/**
193 * Adds a time period to the time.
194 *
195 * @returns pTime.
196 * @param pTime The time spec to modify.
197 * @param pTimeAdd The time spec to add to pTime.
198 */
199DECLINLINE(PRTTIMESPEC) RTTimeSpecAdd(PRTTIMESPEC pTime, PCRTTIMESPEC pTimeAdd)
200{
201 pTime->i64NanosecondsRelativeToUnixEpoch += pTimeAdd->i64NanosecondsRelativeToUnixEpoch;
202 return pTime;
203}
204
205
206/**
207 * Adds a time period give as nanoseconds from the time.
208 *
209 * @returns pTime.
210 * @param pTime The time spec to modify.
211 * @param i64Nano The time period in nanoseconds.
212 */
213DECLINLINE(PRTTIMESPEC) RTTimeSpecAddNano(PRTTIMESPEC pTime, int64_t i64Nano)
214{
215 pTime->i64NanosecondsRelativeToUnixEpoch += i64Nano;
216 return pTime;
217}
218
219
220/**
221 * Adds a time period give as microseconds from the time.
222 *
223 * @returns pTime.
224 * @param pTime The time spec to modify.
225 * @param i64Micro The time period in microseconds.
226 */
227DECLINLINE(PRTTIMESPEC) RTTimeSpecAddMicro(PRTTIMESPEC pTime, int64_t i64Micro)
228{
229 pTime->i64NanosecondsRelativeToUnixEpoch += i64Micro * 1000;
230 return pTime;
231}
232
233
234/**
235 * Adds a time period give as milliseconds from the time.
236 *
237 * @returns pTime.
238 * @param pTime The time spec to modify.
239 * @param i64Milli The time period in milliseconds.
240 */
241DECLINLINE(PRTTIMESPEC) RTTimeSpecAddMilli(PRTTIMESPEC pTime, int64_t i64Milli)
242{
243 pTime->i64NanosecondsRelativeToUnixEpoch += i64Milli * 1000000;
244 return pTime;
245}
246
247
248/**
249 * Adds a time period give as seconds from the time.
250 *
251 * @returns pTime.
252 * @param pTime The time spec to modify.
253 * @param i64Seconds The time period in seconds.
254 */
255DECLINLINE(PRTTIMESPEC) RTTimeSpecAddSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
256{
257 pTime->i64NanosecondsRelativeToUnixEpoch += i64Seconds * 1000000000;
258 return pTime;
259}
260
261
262/**
263 * Subtracts a time period from the time.
264 *
265 * @returns pTime.
266 * @param pTime The time spec to modify.
267 * @param pTimeSub The time spec to subtract from pTime.
268 */
269DECLINLINE(PRTTIMESPEC) RTTimeSpecSub(PRTTIMESPEC pTime, PCRTTIMESPEC pTimeSub)
270{
271 pTime->i64NanosecondsRelativeToUnixEpoch -= pTimeSub->i64NanosecondsRelativeToUnixEpoch;
272 return pTime;
273}
274
275
276/**
277 * Subtracts a time period give as nanoseconds from the time.
278 *
279 * @returns pTime.
280 * @param pTime The time spec to modify.
281 * @param i64Nano The time period in nanoseconds.
282 */
283DECLINLINE(PRTTIMESPEC) RTTimeSpecSubNano(PRTTIMESPEC pTime, int64_t i64Nano)
284{
285 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Nano;
286 return pTime;
287}
288
289
290/**
291 * Subtracts a time period give as microseconds from the time.
292 *
293 * @returns pTime.
294 * @param pTime The time spec to modify.
295 * @param i64Micro The time period in microseconds.
296 */
297DECLINLINE(PRTTIMESPEC) RTTimeSpecSubMicro(PRTTIMESPEC pTime, int64_t i64Micro)
298{
299 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Micro * 1000;
300 return pTime;
301}
302
303
304/**
305 * Subtracts a time period give as milliseconds from the time.
306 *
307 * @returns pTime.
308 * @param pTime The time spec to modify.
309 * @param i64Milli The time period in milliseconds.
310 */
311DECLINLINE(PRTTIMESPEC) RTTimeSpecSubMilli(PRTTIMESPEC pTime, int64_t i64Milli)
312{
313 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Milli * 1000000;
314 return pTime;
315}
316
317
318/**
319 * Subtracts a time period give as seconds from the time.
320 *
321 * @returns pTime.
322 * @param pTime The time spec to modify.
323 * @param i64Seconds The time period in seconds.
324 */
325DECLINLINE(PRTTIMESPEC) RTTimeSpecSubSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
326{
327 pTime->i64NanosecondsRelativeToUnixEpoch -= i64Seconds * 100000000;
328 return pTime;
329}
330
331
332/* PORTME: Add struct timeval guard macro here. */
333#if defined(RTTIME_INCL_TIMEVAL) || defined(_STRUCT_TIMEVAL) || defined(_SYS__TIMEVAL_H_) || defined(_SYS_TIME_H) || defined(_TIMEVAL) || defined(_LINUX_TIME_H)
334/**
335 * Gets the time as POSIX timeval.
336 *
337 * @returns pTime.
338 * @param pTime The time spec to interpret.
339 * @param pTimeval Where to store the time as POSIX timeval.
340 */
341DECLINLINE(struct timeval *) RTTimeSpecGetTimeval(PCRTTIMESPEC pTime, struct timeval *pTimeval)
342{
343 int64_t i64 = RTTimeSpecGetMicro(pTime);
344 int32_t i32Micro = (int32_t)(i64 % 1000000);
345 i64 /= 1000000;
346 if (i32Micro < 0)
347 {
348 i32Micro += 1000000;
349 i64--;
350 }
351 pTimeval->tv_sec = (time_t)i64;
352 pTimeval->tv_usec = i32Micro;
353 return pTimeval;
354}
355
356/**
357 * Sets the time as POSIX timeval.
358 *
359 * @returns pTime.
360 * @param pTime The time spec to modify.
361 * @param pTimeval Pointer to the POSIX timeval struct with the new time.
362 */
363DECLINLINE(PRTTIMESPEC) RTTimeSpecSetTimeval(PRTTIMESPEC pTime, const struct timeval *pTimeval)
364{
365 return RTTimeSpecAddMicro(RTTimeSpecSetSeconds(pTime, pTimeval->tv_sec), pTimeval->tv_usec);
366}
367#endif /* various ways of detecting struct timeval */
368
369
370/* PORTME: Add struct timespec guard macro here. */
371#if defined(RTTIME_INCL_TIMESPEC) || defined(_STRUCT_TIMESPEC) || defined(_SYS__TIMESPEC_H_) || defined(TIMEVAL_TO_TIMESPEC) || defined(_TIMESPEC)
372/**
373 * Gets the time as POSIX timespec.
374 *
375 * @returns pTime.
376 * @param pTime The time spec to interpret.
377 * @param pTimespec Where to store the time as POSIX timespec.
378 */
379DECLINLINE(struct timespec *) RTTimeSpecGetTimespec(PCRTTIMESPEC pTime, struct timespec *pTimespec)
380{
381 int64_t i64 = RTTimeSpecGetNano(pTime);
382 int32_t i32Nano = (int32_t)(i64 % 1000000000);
383 i64 /= 1000000000;
384 if (i32Nano < 0)
385 {
386 i32Nano += 1000000000;
387 i64--;
388 }
389 pTimespec->tv_sec = (time_t)i64;
390 pTimespec->tv_nsec = i32Nano;
391 return pTimespec;
392}
393
394/**
395 * Sets the time as POSIX timespec.
396 *
397 * @returns pTime.
398 * @param pTime The time spec to modify.
399 * @param pTimespec Pointer to the POSIX timespec struct with the new time.
400 */
401DECLINLINE(PRTTIMESPEC) RTTimeSpecSetTimespec(PRTTIMESPEC pTime, const struct timespec *pTimespec)
402{
403 return RTTimeSpecAddNano(RTTimeSpecSetSeconds(pTime, pTimespec->tv_sec), pTimespec->tv_nsec);
404}
405#endif /* various ways of detecting struct timespec */
406
407
408
409/** The offset of the unix epoch and the base for NT time (in 100ns units).
410 * Nt time starts at 1601-01-01 00:00:00. */
411#define RTTIME_NT_TIME_OFFSET_UNIX (116444736000000000LL)
412
413
414/**
415 * Gets the time as NT time.
416 *
417 * @returns Nt time.
418 * @param pTime The time spec to interpret.
419 */
420DECLINLINE(uint64_t) RTTimeSpecGetNtTime(PCRTTIMESPEC pTime)
421{
422 return pTime->i64NanosecondsRelativeToUnixEpoch / 100
423 + RTTIME_NT_TIME_OFFSET_UNIX;
424}
425
426
427/**
428 * Sets the time given by Nt time.
429 *
430 * @returns pTime.
431 * @param pTime The time spec to modify.
432 * @param u64NtTime The new time in Nt time.
433 */
434DECLINLINE(PRTTIMESPEC) RTTimeSpecSetNtTime(PRTTIMESPEC pTime, uint64_t u64NtTime)
435{
436 pTime->i64NanosecondsRelativeToUnixEpoch =
437 ((int64_t)u64NtTime - RTTIME_NT_TIME_OFFSET_UNIX) * 100;
438 return pTime;
439}
440
441
442#ifdef _FILETIME_
443/**
444 * Gets the time as NT file time.
445 *
446 * @returns pFileTime.
447 * @param pTime The time spec to interpret.
448 * @param pFileTime Pointer to NT filetime structure.
449 */
450DECLINLINE(PFILETIME) RTTimeSpecGetNtFileTime(PCRTTIMESPEC pTime, PFILETIME pFileTime)
451{
452 *((uint64_t *)pFileTime) = RTTimeSpecGetNtTime(pTime);
453 return pFileTime;
454}
455
456/**
457 * Sets the time as NT file time.
458 *
459 * @returns pTime.
460 * @param pTime The time spec to modify.
461 * @param pFileTime Where to store the time as Nt file time.
462 */
463DECLINLINE(PRTTIMESPEC) RTTimeSpecSetNtFileTime(PRTTIMESPEC pTime, const FILETIME *pFileTime)
464{
465 return RTTimeSpecSetNtTime(pTime, *(const uint64_t *)pFileTime);
466}
467#endif
468
469
470/** The offset to the start of DOS time.
471 * DOS time starts 1980-01-01 00:00:00. */
472#define RTTIME_OFFSET_DOS_TIME (315532800000000000LL)
473
474
475/**
476 * Gets the time as seconds relative to the start of dos time.
477 *
478 * @returns seconds relative to the start of dos time.
479 * @param pTime The time spec to interpret.
480 */
481DECLINLINE(int64_t) RTTimeSpecGetDosSeconds(PCRTTIMESPEC pTime)
482{
483 return (pTime->i64NanosecondsRelativeToUnixEpoch - RTTIME_OFFSET_DOS_TIME)
484 / 1000000000;
485}
486
487
488/**
489 * Sets the time given by seconds relative to the start of dos time.
490 *
491 * @returns pTime.
492 * @param pTime The time spec to modify.
493 * @param i64Seconds The new time in seconds relative to the start of dos time.
494 */
495DECLINLINE(PRTTIMESPEC) RTTimeSpecSetDosSeconds(PRTTIMESPEC pTime, int64_t i64Seconds)
496{
497 pTime->i64NanosecondsRelativeToUnixEpoch = i64Seconds * 1000000000
498 + RTTIME_OFFSET_DOS_TIME;
499 return pTime;
500}
501
502
503/**
504 * Compare two time specs.
505 *
506 * @returns true they are equal.
507 * @returns false they are not equal.
508 * @param pTime1 The 1st time spec.
509 * @param pTime2 The 2nd time spec.
510 */
511DECLINLINE(bool) RTTimeSpecIsEqual(PCRTTIMESPEC pTime1, PCRTTIMESPEC pTime2)
512{
513 return pTime1->i64NanosecondsRelativeToUnixEpoch == pTime2->i64NanosecondsRelativeToUnixEpoch;
514}
515
516/**
517 * Converts a time spec to a ISO date string.
518 *
519 * @returns psz on success.
520 * @returns NULL on buffer underflow.
521 * @param pTime The time spec.
522 * @param psz Where to store the string.
523 * @param cb The size of the buffer.
524 */
525RTDECL(char *) RTTimeSpecToString(PCRTTIMESPEC pTime, char *psz, size_t cb);
526
527/** @} */
528
529
530/**
531 * Exploded time.
532 */
533#pragma pack(1)
534typedef struct RTTIME
535{
536 /** The year number. */
537 int32_t i32Year;
538 /** The month of the year (1-12). January is 1. */
539 uint8_t u8Month;
540 /** The day of the week (0-6). Monday is 0. */
541 uint8_t u8WeekDay;
542 /** The day of the year (1-366). January the 1st is 1. */
543 uint16_t u16YearDay;
544 /** The day of the month (1-31). */
545 uint8_t u8MonthDay;
546 /** Hour of the day (0-23). */
547 uint8_t u8Hour;
548 /** The minute of the hour (0-59). */
549 uint8_t u8Minute;
550 /** The second of the minute (0-60).
551 * (u32Nanosecond / 1000000) */
552 uint8_t u8Second;
553 /** The nanoseconds of the second (0-999999999). */
554 uint32_t u32Nanosecond;
555 /** Flags, of the RTTIME_FLAGS_* \#defines. */
556 uint32_t fFlags;
557 /** UCT time offset in minutes (-840-840).
558 * @remarks The implementation of RTTimeLocal* isn't quite there yet, so this might not be 100% correct. */
559 int32_t offUTC;
560} RTTIME;
561#pragma pack()
562/** Pointer to a exploded time structure. */
563typedef RTTIME *PRTTIME;
564/** Pointer to a const exploded time structure. */
565typedef const RTTIME *PCRTTIME;
566
567/** @name RTTIME::fFlags values.
568 * @{ */
569/** Set if the time is UTC. If clear the time local time. */
570#define RTTIME_FLAGS_TYPE_MASK 3
571/** the time is UTC time. */
572#define RTTIME_FLAGS_TYPE_UTC 2
573/** The time is local time. */
574#define RTTIME_FLAGS_TYPE_LOCAL 3
575
576/** Set if the time is local and daylight saving time is in effect.
577 * Not bit is not valid if RTTIME_FLAGS_NO_DST_DATA is set. */
578#define RTTIME_FLAGS_DST RT_BIT(4)
579/** Set if the time is local and there is no data available on daylight saving time. */
580#define RTTIME_FLAGS_NO_DST_DATA RT_BIT(5)
581/** Set if the year is a leap year.
582 * This is mutual exclusiv with RTTIME_FLAGS_COMMON_YEAR. */
583#define RTTIME_FLAGS_LEAP_YEAR RT_BIT(6)
584/** Set if the year is a common year.
585 * This is mutual exclusiv with RTTIME_FLAGS_LEAP_YEAR. */
586#define RTTIME_FLAGS_COMMON_YEAR RT_BIT(7)
587/** The mask of valid flags. */
588#define RTTIME_FLAGS_MASK UINT32_C(0xff)
589/** @} */
590
591
592/**
593 * Gets the current system time (UTC).
594 *
595 * @returns pTime.
596 * @param pTime Where to store the time.
597 */
598RTDECL(PRTTIMESPEC) RTTimeNow(PRTTIMESPEC pTime);
599
600/**
601 * Sets the system time.
602 *
603 * @returns IPRT status code
604 * @param pTime The new system time (UTC).
605 *
606 * @remarks This will usually fail because changing the wall time is usually
607 * requires extra privileges.
608 */
609RTDECL(int) RTTimeSet(PCRTTIMESPEC pTime);
610
611/**
612 * Explodes a time spec (UTC).
613 *
614 * @returns pTime.
615 * @param pTime Where to store the exploded time.
616 * @param pTimeSpec The time spec to exploded.
617 */
618RTDECL(PRTTIME) RTTimeExplode(PRTTIME pTime, PCRTTIMESPEC pTimeSpec);
619
620/**
621 * Implodes exploded time to a time spec (UTC).
622 *
623 * @returns pTime on success.
624 * @returns NULL if the pTime data is invalid.
625 * @param pTimeSpec Where to store the imploded UTC time.
626 * If pTime specifies a time which outside the range, maximum or
627 * minimum values will be returned.
628 * @param pTime Pointer to the exploded time to implode.
629 * The fields u8Month, u8WeekDay and u8MonthDay are not used,
630 * and all the other fields are expected to be within their
631 * bounds. Use RTTimeNormalize() to calculate u16YearDay and
632 * normalize the ranges of the fields.
633 */
634RTDECL(PRTTIMESPEC) RTTimeImplode(PRTTIMESPEC pTimeSpec, PCRTTIME pTime);
635
636/**
637 * Normalizes the fields of a time structure.
638 *
639 * It is possible to calculate year-day from month/day and vice
640 * versa. If you adjust any of of these, make sure to zero the
641 * other so you make it clear which of the fields to use. If
642 * it's ambiguous, the year-day field is used (and you get
643 * assertions in debug builds).
644 *
645 * All the time fields and the year-day or month/day fields will
646 * be adjusted for overflows. (Since all fields are unsigned, there
647 * is no underflows.) It is possible to exploit this for simple
648 * date math, though the recommended way of doing that to implode
649 * the time into a timespec and do the math on that.
650 *
651 * @returns pTime on success.
652 * @returns NULL if the data is invalid.
653 *
654 * @param pTime The time structure to normalize.
655 *
656 * @remarks This function doesn't work with local time, only with UTC time.
657 */
658RTDECL(PRTTIME) RTTimeNormalize(PRTTIME pTime);
659
660/**
661 * Gets the current local system time.
662 *
663 * @returns pTime.
664 * @param pTime Where to store the local time.
665 */
666RTDECL(PRTTIMESPEC) RTTimeLocalNow(PRTTIMESPEC pTime);
667
668/**
669 * Gets the delta between UTC and local time.
670 *
671 * @code
672 * RTTIMESPEC LocalTime;
673 * RTTimeSpecAddNano(RTTimeNow(&LocalTime), RTTimeLocalDeltaNano());
674 * @endcode
675 *
676 * @returns Returns the nanosecond delta between UTC and local time.
677 */
678RTDECL(int64_t) RTTimeLocalDeltaNano(void);
679
680/**
681 * Explodes a time spec to the localized timezone.
682 *
683 * @returns pTime.
684 * @param pTime Where to store the exploded time.
685 * @param pTimeSpec The time spec to exploded (UTC).
686 */
687RTDECL(PRTTIME) RTTimeLocalExplode(PRTTIME pTime, PCRTTIMESPEC pTimeSpec);
688
689/**
690 * Normalizes the fields of a time structure containing local time.
691 *
692 * See RTTimeNormalize for details.
693 *
694 * @returns pTime on success.
695 * @returns NULL if the data is invalid.
696 * @param pTime The time structure to normalize.
697 */
698RTDECL(PRTTIME) RTTimeLocalNormalize(PRTTIME pTime);
699
700/**
701 * Converts a time spec to a ISO date string.
702 *
703 * @returns psz on success.
704 * @returns NULL on buffer underflow.
705 * @param pTime The time. Caller should've normalized this.
706 * @param psz Where to store the string.
707 * @param cb The size of the buffer.
708 */
709RTDECL(char *) RTTimeToString(PCRTTIME pTime, char *psz, size_t cb);
710
711/**
712 * Checks if a year is a leap year or not.
713 *
714 * @returns true if it's a leap year.
715 * @returns false if it's a common year.
716 * @param i32Year The year in question.
717 */
718RTDECL(bool) RTTimeIsLeapYear(int32_t i32Year);
719
720/**
721 * Gets the current nanosecond timestamp.
722 *
723 * @returns nanosecond timestamp.
724 */
725RTDECL(uint64_t) RTTimeNanoTS(void);
726
727/**
728 * Gets the current millisecond timestamp.
729 *
730 * @returns millisecond timestamp.
731 */
732RTDECL(uint64_t) RTTimeMilliTS(void);
733
734/**
735 * Debugging the time api.
736 *
737 * @returns the number of 1ns steps which has been applied by RTTimeNanoTS().
738 */
739RTDECL(uint32_t) RTTimeDbgSteps(void);
740
741/**
742 * Debugging the time api.
743 *
744 * @returns the number of times the TSC interval expired RTTimeNanoTS().
745 */
746RTDECL(uint32_t) RTTimeDbgExpired(void);
747
748/**
749 * Debugging the time api.
750 *
751 * @returns the number of bad previous values encountered by RTTimeNanoTS().
752 */
753RTDECL(uint32_t) RTTimeDbgBad(void);
754
755/**
756 * Debugging the time api.
757 *
758 * @returns the number of update races in RTTimeNanoTS().
759 */
760RTDECL(uint32_t) RTTimeDbgRaces(void);
761
762/** @name RTTimeNanoTS GIP worker functions, for TM.
763 * @{ */
764/** Pointer to a RTTIMENANOTSDATA structure. */
765typedef struct RTTIMENANOTSDATA *PRTTIMENANOTSDATA;
766
767/**
768 * Nanosecond timestamp data.
769 *
770 * This is used to keep track of statistics and callback so IPRT
771 * and TM (VirtualBox) can share code.
772 *
773 * @remark Keep this in sync with the assembly version in timesupA.asm.
774 */
775typedef struct RTTIMENANOTSDATA
776{
777 /** Where the previous timestamp is stored.
778 * This is maintained to ensure that time doesn't go backwards or anything. */
779 uint64_t volatile *pu64Prev;
780
781 /**
782 * Helper function that's used by the assembly routines when something goes bust.
783 *
784 * @param pData Pointer to this structure.
785 * @param u64NanoTS The calculated nano ts.
786 * @param u64DeltaPrev The delta relative to the previously returned timestamp.
787 * @param u64PrevNanoTS The previously returned timestamp (as it was read it).
788 */
789 DECLCALLBACKMEMBER(void, pfnBad)(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS);
790
791 /**
792 * Callback for when rediscovery is required.
793 *
794 * @returns Nanosecond timestamp.
795 * @param pData Pointer to this structure.
796 */
797 DECLCALLBACKMEMBER(uint64_t, pfnRediscover)(PRTTIMENANOTSDATA pData);
798
799 /** Just a dummy alignment member. */
800 void *pvDummy;
801
802 /** Number of 1ns steps because of overshooting the period. */
803 uint32_t c1nsSteps;
804 /** The number of times the interval expired (overflow). */
805 uint32_t cExpired;
806 /** Number of "bad" previous values. */
807 uint32_t cBadPrev;
808 /** The number of update races. */
809 uint32_t cUpdateRaces;
810} RTTIMENANOTSDATA;
811
812#ifndef IN_RING3
813/**
814 * The Ring-3 layout of the RTTIMENANOTSDATA structure.
815 */
816typedef struct RTTIMENANOTSDATAR3
817{
818 R3PTRTYPE(uint64_t volatile *) pu64Prev;
819 DECLR3CALLBACKMEMBER(void, pfnBad,(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS));
820 DECLR3CALLBACKMEMBER(uint64_t, pfnRediscover,(PRTTIMENANOTSDATA pData));
821 RTR3PTR pvDummy;
822 uint32_t c1nsSteps;
823 uint32_t cExpired;
824 uint32_t cBadPrev;
825 uint32_t cUpdateRaces;
826} RTTIMENANOTSDATAR3;
827#else
828typedef RTTIMENANOTSDATA RTTIMENANOTSDATAR3;
829#endif
830
831#ifndef IN_RING0
832/**
833 * The Ring-3 layout of the RTTIMENANOTSDATA structure.
834 */
835typedef struct RTTIMENANOTSDATAR0
836{
837 R0PTRTYPE(uint64_t volatile *) pu64Prev;
838 DECLR0CALLBACKMEMBER(void, pfnBad,(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS));
839 DECLR0CALLBACKMEMBER(uint64_t, pfnRediscover,(PRTTIMENANOTSDATA pData));
840 RTR0PTR pvDummy;
841 uint32_t c1nsSteps;
842 uint32_t cExpired;
843 uint32_t cBadPrev;
844 uint32_t cUpdateRaces;
845} RTTIMENANOTSDATAR0;
846#else
847typedef RTTIMENANOTSDATA RTTIMENANOTSDATAR0;
848#endif
849
850#ifndef IN_RC
851/**
852 * The RC layout of the RTTIMENANOTSDATA structure.
853 */
854typedef struct RTTIMENANOTSDATARC
855{
856 RCPTRTYPE(uint64_t volatile *) pu64Prev;
857 DECLRCCALLBACKMEMBER(void, pfnBad,(PRTTIMENANOTSDATA pData, uint64_t u64NanoTS, uint64_t u64DeltaPrev, uint64_t u64PrevNanoTS));
858 DECLRCCALLBACKMEMBER(uint64_t, pfnRediscover,(PRTTIMENANOTSDATA pData));
859 RCPTRTYPE(void *) pvDummy;
860 uint32_t c1nsSteps;
861 uint32_t cExpired;
862 uint32_t cBadPrev;
863 uint32_t cUpdateRaces;
864} RTTIMENANOTSDATARC;
865#else
866typedef RTTIMENANOTSDATA RTTIMENANOTSDATARC;
867#endif
868
869/** Internal RTTimeNanoTS worker (assembly). */
870typedef DECLCALLBACK(uint64_t) FNTIMENANOTSINTERNAL(PRTTIMENANOTSDATA pData);
871/** Pointer to an internal RTTimeNanoTS worker (assembly). */
872typedef FNTIMENANOTSINTERNAL *PFNTIMENANOTSINTERNAL;
873
874RTDECL(uint64_t) RTTimeNanoTSLegacySync(PRTTIMENANOTSDATA pData);
875RTDECL(uint64_t) RTTimeNanoTSLegacyAsync(PRTTIMENANOTSDATA pData);
876RTDECL(uint64_t) RTTimeNanoTSLFenceSync(PRTTIMENANOTSDATA pData);
877RTDECL(uint64_t) RTTimeNanoTSLFenceAsync(PRTTIMENANOTSDATA pData);
878/** @} */
879
880
881/**
882 * Gets the current nanosecond timestamp.
883 *
884 * This differs from RTTimeNanoTS in that it will use system APIs and not do any
885 * resolution or performance optimizations.
886 *
887 * @returns nanosecond timestamp.
888 */
889RTDECL(uint64_t) RTTimeSystemNanoTS(void);
890
891/**
892 * Gets the current millisecond timestamp.
893 *
894 * This differs from RTTimeNanoTS in that it will use system APIs and not do any
895 * resolution or performance optimizations.
896 *
897 * @returns millisecond timestamp.
898 */
899RTDECL(uint64_t) RTTimeSystemMilliTS(void);
900
901/**
902 * Get the nanosecond timestamp relative to program startup.
903 *
904 * @returns Timestamp relative to program startup.
905 */
906RTDECL(uint64_t) RTTimeProgramNanoTS(void);
907
908/**
909 * Get the microsecond timestamp relative to program startup.
910 *
911 * @returns Timestamp relative to program startup.
912 */
913RTDECL(uint64_t) RTTimeProgramMicroTS(void);
914
915/**
916 * Get the millisecond timestamp relative to program startup.
917 *
918 * @returns Timestamp relative to program startup.
919 */
920RTDECL(uint64_t) RTTimeProgramMilliTS(void);
921
922/**
923 * Get the second timestamp relative to program startup.
924 *
925 * @returns Timestamp relative to program startup.
926 */
927RTDECL(uint32_t) RTTimeProgramSecTS(void);
928
929/**
930 * Get the RTTimeNanoTS() of when the program started.
931 *
932 * @returns Program startup timestamp.
933 */
934RTDECL(uint64_t) RTTimeProgramStartNanoTS(void);
935
936/** @} */
937
938RT_C_DECLS_END
939
940#endif
941
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