SYSTEMTIME structure (minwinbase.h)
Specifies a date and time, using individual members for the month, day, year, weekday, hour, minute, second, and millisecond. The time is either in coordinated universal time (UTC) or local time, depending on the function that is being called.
Syntax
Members
The year. The valid values for this member are 1601 through 30827.
The month. This member can be one of the following values.
| Value | Meaning |
|---|---|
| 1 | January |
| 2 | February |
| 3 | March |
| 4 | April |
| 5 | May |
| 6 | June |
| 7 | July |
| 8 | August |
| 9 | September |
| 10 | October |
| 11 | November |
| 12 | December |
The day of the week. This member can be one of the following values.
| Value | Meaning |
|---|---|
| 0 | Sunday |
| 1 | Monday |
| 2 | Tuesday |
| 3 | Wednesday |
| 4 | Thursday |
| 5 | Friday |
| 6 | Saturday |
The day of the month. The valid values for this member are 1 through 31.
The hour. The valid values for this member are 0 through 23.
The minute. The valid values for this member are 0 through 59.
The second. The valid values for this member are 0 through 59.
The millisecond. The valid values for this member are 0 through 999.
Remarks
The SYSTEMTIME does not check to see if the date represented is a real and valid date. When working with this API, you should ensure its validity, especially in leap year scenarios. See leap day readiness for more information.
It is not recommended that you add and subtract values from the SYSTEMTIME structure to obtain relative times. Instead, you should
- Convert the SYSTEMTIME structure to a FILETIME structure.
- Copy the resulting FILETIME structure to a ULARGE_INTEGER structure.
- Use normal 64-bit arithmetic on the ULARGE_INTEGER value.
The system can periodically refresh the time by synchronizing with a time source. Because the system time can be adjusted either forward or backward, do not compare system time readings to determine elapsed time. Instead, use one of the methods described in Windows Time.
Examples
The following example demonstrates the difference between the time values retrieved by the GetSystemTime and GetLocalTime functions.
Time Functions
The following functions are used with system time.
| Function | Description |
|---|---|
| GetSystemTime | Retrieves the current system date and time in UTC format. |
| GetSystemTimeAdjustment | Determines whether the system is applying periodic time adjustments to its time-of-day clock. |
| GetTimeFormat | Formats a system time as a time string for a specified locale. |
| NtQuerySystemTime | Returns the system time. |
| RtlLocalTimeToSystemTime | Converts the specified local time to system time. |
| RtlTimeToSecondsSince1970 | Converts the specified system time to the number of seconds since the first second of January 1, 1970. |
| SetSystemTime | Sets the current system time and date. |
| SetSystemTimeAdjustment | Enables or disables periodic time adjustments to the system’s time-of-day clock. |
| SystemTimeToFileTime | Converts a system time to a file time. |
| SystemTimeToTzSpecificLocalTime | Converts a UTC time to a specified time zone’s corresponding local time. |
| TzSpecificLocalTimeToSystemTime | Converts a local time to a UTC time. |
The following functions are used with local time.
| Function | Description |
|---|---|
| EnumDynamicTimeZoneInformation | Enumerates dynamic daylight saving time information entries stored in the registry. |
| FileTimeToLocalFileTime | Converts a UTC file time to a local file time. |
| GetDynamicTimeZoneInformation | Retrieves the current time zone and dynamic daylight saving time settings. |
| GetDynamicTimeZoneInformationEffectiveYears | Retrieves a range, expressed in years, for which a DYNAMIC_TIME_ZONE_INFORMATION has valid entries. |
| GetLocalTime | Retrieves the current local date and time. |
| GetTimeZoneInformation | Retrieves the current time zone settings. |
| GetTimeZoneInformationForYear | Retrieves the time zone settings for the specified year and time zone. |
| RtlLocalTimeToSystemTime | Converts the specified local time to system time. |
| SetDynamicTimeZoneInformation | Sets the current time zone and dynamic daylight saving time settings. |
| SetLocalTime | Sets the current local time and date. |
| SetTimeZoneInformation | Sets the current time zone settings. |
| SystemTimeToTzSpecificLocalTime | Converts a UTC time to a specified time zone’s corresponding local time. |
| SystemTimeToTzSpecificLocalTimeEx | Converts a UTC time with dynamic daylight saving time settings to a specified time zone’s corresponding local time. |
| TzSpecificLocalTimeToSystemTime | Converts a local time to a UTC time. |
| TzSpecificLocalTimeToSystemTimeEx | Converts a local time with dynamic daylight saving time settings to UTC time. |
The following functions are used with file time.
| Function | Description |
|---|---|
| CompareFileTime | Compares two file times. |
| FileTimeToLocalFileTime | Converts a UTC file time to a local file time. |
| FileTimeToSystemTime | Converts a file time to system time format. |
| GetFileTime | Retrieves the date and time that the specified file or directory was created, last accessed, and last modified. |
| GetSystemTimeAsFileTime | Retrieves the current system date and time in UTC format. |
| LocalFileTimeToFileTime | Converts a local file time to a file time based on UTC. |
| SetFileTime | Sets the date and time that the specified file or directory was created, last accessed, or last modified. |
| SystemTimeToFileTime | Converts a system time to a file time. |
The following functions are used with MS-DOS date and time.
| Function | Description |
|---|---|
| DosDateTimeToFileTime | Converts MS-DOS date and time values to a file time. |
| FileTimeToDosDateTime | Converts a file time to MS-DOS date and time values. |
The following functions are used with Windows time.
| Function | Description |
|---|---|
| GetSystemTimes | Retrieves system timing information. |
| GetTickCount | Retrieves the number of milliseconds that have elapsed since the system was started, up to 49.7 days. |
| GetTickCount64 | Retrieves the number of milliseconds that have elapsed since the system was started. |
The following functions are used with high-resolution performance counters.
| Function | Description |
|---|---|
| QueryPerformanceCounter | Retrieves the current value of the high-resolution performance counter. |
| QueryPerformanceFrequency | Retrieves the frequency of the high-resolution performance counter. |
The following functions are used with the auxiliary performance counter.
| Function | Description |
|---|---|
| QueryAuxiliaryCounterFrequency | Queries the auxiliary counter frequency. |
| ConvertAuxiliaryCounterToPerformanceCounter | Converts the specified auxiliary counter value to the corresponding performance counter value; optionally provides the estimated conversion error in nanoseconds due to latencies and maximum possible drift. |
| ConvertPerformanceCounterToAuxiliaryCounter | Converts the specified performance counter value to the corresponding auxiliary counter value; optionally provides the estimated conversion error in nanoseconds due to latencies and maximum possible drift. |
The following function is used with interrupt time.
Getting the current time (in milliseconds) from the system clock in Windows?
How can you obtain the system clock’s current time of day (in milliseconds) in C++? This is a windows specific app.
6 Answers 6
To get the time expressed as UTC, use GetSystemTime in the Win32 API.
SYSTEMTIME is documented as having these relevant members:
As shf301 helpfully points out below, GetLocalTime (with the same prototype) will yield a time corrected to the user’s current timezone.
You have a few good answers here, depending on what you’re after. If you’re looking for just time of day, my answer is the best approach — if you need solid dates for arithmetic, consider Alex’s. There’s a lot of ways to skin the time cat on Windows, and some of them are more accurate than others (and nobody has mentioned QueryPerformanceCounter yet).
The easiest (and most direct) way is to call GetSystemTimeAsFileTime() , which returns a FILETIME , a struct which stores the 64-bit number of 100-nanosecond intervals since midnight Jan 1, 1601.
At least at the time of Windows NT 3.1, 3.51, and 4.01, the GetSystemTimeAsFileTime() API was the fastest user-mode API able to retrieve the current time. It also offers the advantage (compared with GetSystemTime() -> SystemTimeToFileTime()) of being a single API call, that under normal circumstances cannot fail.
To convert a FILETIME ft_now; to a 64-bit integer named ll_now , use the following:
ll_now = (LONGLONG)ft_now.dwLowDateTime + ((LONGLONG)(ft_now.dwHighDateTime)
You can then divide by the number of 100-nanosecond intervals in a millisecond (10,000 of those) and you have milliseconds since the Win32 epoch.
To convert to the Unix epoch, subtract 116444736000000000LL to reach Jan 1, 1970.
You mentioned a desire to find the number of milliseconds into the current day. Because the Win32 epoch begins at a midnight, the number of milliseconds passed so far today can be calculated from the filetime with a modulus operation. Specifically, because there are 24 hours/day * 60 minutes/hour * 60 seconds/minute * 1000 milliseconds/second = 86,400,000 milliseconds/day , you could user the modulus of the system time in milliseconds modulus 86400000LL .
For a different application, one might not want to use the modulus. Especially if one is calculating elapsed times, one might have difficulties due to wrap-around at midnight. These difficulties are solvable, the best example I am aware is Linus Torvald’s line in the Linux kernel which handles counter wrap around.
Keep in mind that the system time is returned as a UTC time (both in the case of GetSystemTimeAsFileTime() and simply GetSystemTime() ). If you require the local time as configured by the Administrator, then you could use GetLocalTime() .
How can I get the Windows system time with millisecond resolution?
How can I get the Windows system time with millisecond resolution?
If the above is not possible, then how can I get the operating system start time? I would like to use this value together with timeGetTime() in order to compute a system time with millisecond resolution.
Thank you in advance.
10 Answers 10
GetTickCount will not get it done for you.
Look into QueryPerformanceFrequency / QueryPerformanceCounter . The only gotcha here is CPU scaling though, so do your research.
Try this article from MSDN Magazine. It’s actually quite complicated.
This is an elaboration of the above comments to explain the some of the whys.
First, the GetSystemTime* calls are the only Win32 APIs providing the system’s time. This time has a fairly coarse granularity, as most applications do not need the overhead required to maintain a higher resolution. Time is (likely) stored internally as a 64-bit count of milliseconds. Calling timeGetTime gets the low order 32 bits. Calling GetSystemTime, etc requests Windows to return this millisecond time, after converting into days, etc and including the system start time.
There are two time sources in a machine: the CPU’s clock and an on-board clock (e.g., real-time clock (RTC), Programmable Interval Timers (PIT), and High Precision Event Timer (HPET)). The first has a resolution of around
0.5ns (2GHz) and the second is generally programmable down to a period of 1ms (though newer chips (HPET) have higher resolution). Windows uses these periodic ticks to perform certain operations, including updating the system time.
Applications can change this period via timerBeginPeriod; however, this affects the entire system. The OS will check / update regular events at the requested frequency. Under low CPU loads / frequencies, there are idle periods for power savings. At high frequencies, there isn’t time to put the processor into low power states. See Timer Resolution for further details. Finally, each tick has some overhead and increasing the frequency consumes more CPU cycles.
