time.h revision 9aa6fbc4da65d57d07aadef838a1b032bd659c0f
/** @file
*
* InnoTek Portable Runtime - Time.
*/
/*
* Copyright (C) 2006 InnoTek Systemberatung GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License as published by the Free Software Foundation,
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
* distribution. VirtualBox OSE is distributed in the hope that it will
* be useful, but WITHOUT ANY WARRANTY of any kind.
*
* If you received this file as part of a commercial VirtualBox
* distribution, then only the terms of your commercial VirtualBox
* license agreement apply instead of the previous paragraph.
*/
#ifndef __iprt_time_h__
#define __iprt_time_h__
/** @defgroup grp_rt_time RTTime - Time
* @ingroup grp_rt
* @{
*/
/** Time Specification.
*
* Use the inline RTTimeSpecGet/Set to operate on structure this so we
* can easily change the representation if required later.
*
* The current representation is in nanoseconds relative to the unix epoch
* (1970-01-01 00:00:00 UTC). This gives us an approximate span from
* 1678 to 2262 without sacrifying the resolution offered by the various
* host OSes (BSD & LINUX 1ns, NT 100ns).
*/
typedef struct RTTIMESPEC
{
/** Nanoseconds since epoch.
* The name is intentially too long to be comfortable to use because you should be
* using inline helpers! */
} RTTIMESPEC;
/** Pointer to a time spec structure. */
typedef RTTIMESPEC *PRTTIMESPEC;
/** Pointer to a const time spec structure. */
typedef const RTTIMESPEC *PCRTTIMESPEC;
/** @name RTTIMESPEC methods
* @{ */
/**
* Gets the time as nanoseconds relative to the unix epoch.
*
* @returns Nanoseconds relative to unix epoch.
* @param pTime The time spec to interpret.
*/
{
return pTime->i64NanosecondsRelativeToUnixEpoch;
}
/**
* Sets the time give by nanoseconds relative to the unix epoch.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Nano The new time in nanoseconds.
*/
{
return pTime;
}
/**
* Gets the time as microseconds relative to the unix epoch.
*
* @returns microseconds relative to unix epoch.
* @param pTime The time spec to interpret.
*/
{
}
/**
* Sets the time given by microseconds relative to the unix epoch.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Micro The new time in microsecond.
*/
{
return pTime;
}
/**
* Gets the time as milliseconds relative to the unix epoch.
*
* @returns milliseconds relative to unix epoch.
* @param pTime The time spec to interpret.
*/
{
}
/**
* Sets the time given by milliseconds relative to the unix epoch.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Milli The new time in milliseconds.
*/
{
return pTime;
}
/**
* Gets the time as seconds relative to the unix epoch.
*
* @returns seconds relative to unix epoch.
* @param pTime The time spec to interpret.
*/
{
}
/**
* Sets the time given by seconds relative to the unix epoch.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Seconds The new time in seconds.
*/
{
return pTime;
}
/**
* Adds a time period to the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param pTimeAdd The time spec to add to pTime.
*/
{
return pTime;
}
/**
* Adds a time period give as nanoseconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Nano The time period in nanoseconds.
*/
{
return pTime;
}
/**
* Adds a time period give as microseconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Micro The time period in microseconds.
*/
{
return pTime;
}
/**
* Adds a time period give as milliseconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Milli The time period in milliseconds.
*/
{
return pTime;
}
/**
* Adds a time period give as seconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Seconds The time period in seconds.
*/
{
return pTime;
}
/**
* Subtracts a time period from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param pTimeSub The time spec to subtract from pTime.
*/
{
return pTime;
}
/**
* Subtracts a time period give as nanoseconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Nano The time period in nanoseconds.
*/
{
return pTime;
}
/**
* Subtracts a time period give as microseconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Micro The time period in microseconds.
*/
{
return pTime;
}
/**
* Subtracts a time period give as milliseconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Milli The time period in milliseconds.
*/
{
return pTime;
}
/**
* Subtracts a time period give as seconds from the time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Seconds The time period in seconds.
*/
{
return pTime;
}
/**
* Gets the time as POSIX timeval.
*
* @returns pTime.
* @param pTime The time spec to interpret.
* @param pTimeval Where to store the time as POSIX timeval.
*/
{
i64 /= 1000000;
if (i32Micro < 0)
{
i32Micro += 1000000;
i64++;
}
return pTimeval;
}
/**
* Sets the time as POSIX timeval.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param pTimeval Pointer to the POSIX timeval struct with the new time.
*/
{
}
#endif /* various ways of detecting struct timeval */
/**
* Gets the time as POSIX timespec.
*
* @returns pTime.
* @param pTime The time spec to interpret.
* @param pTimespec Where to store the time as POSIX timespec.
*/
{
i64 /= 1000000000;
if (i32Nano < 0)
{
i32Nano += 1000000000;
i64++;
}
return pTimespec;
}
/**
* Sets the time as POSIX timespec.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param pTimespec Pointer to the POSIX timespec struct with the new time.
*/
{
}
#endif /* various ways of detecting struct timespec */
/** The offset of the unix epoch and the base for NT time (in 100ns units).
* Nt time starts at 1601-01-01 00:00:00. */
#define RTTIME_NT_TIME_OFFSET_UNIX (116444736000000000LL)
/**
* Gets the time as NT time.
*
* @returns Nt time.
* @param pTime The time spec to interpret.
*/
{
}
/**
* Sets the time given by Nt time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param u64NtTime The new time in Nt time.
*/
{
return pTime;
}
#ifdef _FILETIME_
/**
* Gets the time as NT file time.
*
* @returns pFileTime.
* @param pTime The time spec to interpret.
* @param pFileTime Pointer to NT filetime structure.
*/
{
return pFileTime;
}
/**
* Sets the time as NT file time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param pFileTime Where to store the time as Nt file time.
*/
{
}
#endif
/** The offset to the start of DOS time.
* DOS time starts 1980-01-01 00:00:00. */
#define RTTIME_OFFSET_DOS_TIME (315532800000000000LL)
/**
* Gets the time as seconds relative to the start of dos time.
*
* @returns seconds relative to the start of dos time.
* @param pTime The time spec to interpret.
*/
{
/ 1000000000;
}
/**
* Sets the time given by seconds relative to the start of dos time.
*
* @returns pTime.
* @param pTime The time spec to modify.
* @param i64Seconds The new time in seconds relative to the start of dos time.
*/
{
return pTime;
}
/**
* Compare two time specs.
*
* @returns true they are equal.
* @returns false they are not equal.
* @param pTime1 The 1st time spec.
* @param pTime2 The 2nd time spec.
*/
{
}
/**
* Converts a time spec to a ISO date string.
*
* @returns psz on success.
* @returns NULL on buffer underflow.
* @param pTime The time spec.
* @param psz Where to store the string.
* @param cb The size of the buffer.
*/
/** @} */
/**
* Exploded time.
*/
#pragma pack(1)
typedef struct RTTIME
{
/** The year number. */
/** The month of the year (1-12). January is 1. */
/** The day of the week (0-6). Monday is 0. */
/** The day of the year (1-366). January the 1st is 1. */
/** The day of the month (1-31). */
/** Hour of the day (0-23). */
/** The minute of the hour (0-59). */
/** The second of the minute (0-60).
* (u32Nanosecond / 1000000) */
/** The nanoseconds of the second (0-999999999). */
/** Flags, of the RTTIME_FLAGS_* \#defines. */
/** @todo we need a UTC offset field. */
} RTTIME;
#pragma pack()
/** Pointer to a exploded time structure. */
/** Pointer to a const exploded time structure. */
/** @name RTTIME::fFlags values.
* @{ */
/** Set if the time is UTC. If clear the time local time. */
#define RTTIME_FLAGS_TYPE_MASK 3
/** the time is UTC time. */
#define RTTIME_FLAGS_TYPE_UTC 2
/** The time is local time. */
#define RTTIME_FLAGS_TYPE_LOCAL 3
/** Set if the time is local and daylight saving time is in effect.
* Not bit is not valid if RTTIME_FLAGS_NO_DST_DATA is set. */
/** Set if the time is local and there is no data available on daylight saving time. */
/** Set if the year is a leap year.
* This is mutual exclusiv with RTTIME_FLAGS_COMMON_YEAR. */
/** Set if the year is a common year.
* This is mutual exclusiv with RTTIME_FLAGS_LEAP_YEAR. */
/** @} */
/**
* Gets the current system time (UCT).
*
* @returns pTime.
* @param pTime Where to store the time.
*/
/**
* Explodes a time spec (UTC).
*
* @returns pTime.
* @param pTime Where to store the exploded time.
* @param pTimeSpec The time spec to exploded.
*/
/**
* Implodes exploded time to a time spec (UTC).
*
* @returns pTime on success.
* @returns NULL if the pTime data is invalid.
* @param pTimeSpec Where to store the imploded UTC time.
* If pTime specifies a time which outside the range, maximum or
* minimum values will be returned.
* @param pTime Pointer to the exploded time to implode.
* The fields u8Month, u8WeekDay and u8MonthDay are not used,
* and all the other fields are expected to be within their
* bounds. Use RTTimeNormalize() to calculate u16YearDay and
* normalize the ranges of the fields.
*/
/**
* Normalizes the fields of a timestructure.
*
* combinations. It's also possible to overflow other
* fields, and these overflows will be adjusted for.
*
* @returns pTime on success.
* @returns NULL if the data is invalid.
* @param pTime The time structure to normalize.
*/
/**
* Gets the current local system time.
*
* @returns pTime.
* @param pTime Where to store the local time.
*/
/**
* Gets the delta between UTC and local time.
*
* @code
* RTTIMESPEC LocalTime;
* RTTimeSpecAddNano(RTTimeNow(&LocalTime), RTTimeLocalDeltaNano());
* @endcode
*
* @returns Returns the nanosecond delta between UTC and local time.
*/
/**
* Explodes a time spec to the localized timezone.
*
* @returns pTime.
* @param pTime Where to store the exploded time.
* @param pTimeSpec The time spec to exploded (UCT).
*/
/**
* Converts a time spec to a ISO date string.
*
* @returns psz on success.
* @returns NULL on buffer underflow.
* @param pTime The time. Caller should've normalized this.
* @param psz Where to store the string.
* @param cb The size of the buffer.
*/
/**
* Gets the current nanosecond timestamp.
*
* @returns nanosecond timestamp.
*/
/**
* Gets the current millisecond timestamp.
*
* @returns millisecond timestamp.
*/
/**
* Debugging the time api.
*
* @returns the number of 1ns steps which has been applied by rtTimeNanoTSInternal().
*/
/**
* Gets the current nanosecond timestamp.
*
* This differs from RTTimeNanoTS in that it will use system APIs and not do any
* resolution or performance optimizations.
*
* @returns nanosecond timestamp.
*/
/**
* Gets the current millisecond timestamp.
*
* This differs from RTTimeNanoTS in that it will use system APIs and not do any
* resolution or performance optimizations.
*
* @returns millisecond timestamp.
*/
/**
* Get the nanosecond timestamp relative to program startup.
*
* @returns Timestamp relative to program startup.
*/
/**
* Get the millisecond timestamp relative to program startup.
*
* @returns Timestamp relative to program startup.
*/
/**
* Get the second timestamp relative to program startup.
*
* @returns Timestamp relative to program startup.
*/
/** @} */
#endif