SetSystemTimeAdjustment function (sysinfoapi.h)

Article
07/27/2022

Enables or disables periodic time adjustments to the system's time-of-day clock. When enabled, such time adjustments can be used to synchronize the time of day with some other source of time information.

Syntax

BOOL SetSystemTimeAdjustment(
  [in] DWORD dwTimeAdjustment,
  [in] BOOL  bTimeAdjustmentDisabled
);

Parameters

[in] dwTimeAdjustment

This value represents the number of 100-nanosecond units added to the system time-of-day for each lpTimeIncrement period of time that actually passes. Call GetSystemTimeAdjustment to obtain the lpTimeIncrement value. See remarks.

Note

Currently, Windows Vista and Windows 7 machines will lose any time adjustments set less than 16.

[in] bTimeAdjustmentDisabled

The time adjustment mode that the system is to use. Periodic system time adjustments can be disabled or enabled.

A value of TRUE specifies that periodic time adjustment is to be disabled. When disabled, the value of dwTimeAdjustment is ignored, and the system may adjust the time of day using its own internal time synchronization mechanisms. These internal time synchronization mechanisms may cause the time-of-day clock to change during the normal course of the system operation, which can include noticeable jumps in time as deemed necessary by the system.

A value of FALSE specifies that periodic time adjustment is to be enabled, and will be used to adjust the time-of-day clock. The system will not interfere with the time adjustment scheme, and will not attempt to synchronize time of day on its own.

Return value

If the function succeeds, the return value is non-zero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. One way the function can fail is if the caller does not possess the SE_SYSTEMTIME_NAME privilege.

Remarks

The GetSystemTimeAdjustment and SetSystemTimeAdjustment functions support algorithms that synchronize the time-of-day clock, reported via GetSystemTime and GetLocalTime, with another time source using a periodic time adjustment.

The SetSystemTimeAdjustment function supports two modes of time synchronization:

Mode	Behavior
Time-Adjustment Disabled	For this mode, bTimeAdjustmentDisabled is set to TRUE. In this mode, the value of dwTimeAdjustment is ignored, and the system may adjust the time of day using its own internal time synchronization mechanisms. These internal time synchronization mechanisms may cause the time-of-day clock to change during the normal course of the system operation, which can include noticeable jumps in time as deemed necessary by the system.
Time-Adjustment Enabled	For this mode, bTimeAdjustmentDisabled is set to FALSE. For each lpTimeIncrement period of time that actually passes, dwTimeAdjustment will be added to the time of day. The period of time represented by lpTimeIncrement can be determined by calling GetSystemTimeAdjustment. The lpTimeIncrement value is fixed by the system upon start and does not change during system operation and is completely independent of the system’s internal clock interrupt resolution at any given time. Given this, the lpTimeIncrement value simply expresses a period of time for which dwTimeAdjustment will be applied to the system’s time-of-day clock. If the dwTimeAdjustment value is smaller than lpTimeIncrement, the time-of-day clock will advance at a rate slower than normal. If the dwTimeAdjustment value is larger than lpTimeIncrement, the time-of-day clock will advance at a rate faster than normal. The degree to which the time-of-day-clock will run faster or slower depends on how far the dwTimeAdjustment value is above or below the lpTimeIncrement value. If dwTimeAdjustment equals lpTimeIncrement, the time-of-day clock will advance at normal speed.

Mode

Behavior

Time-Adjustment Disabled

For this mode, bTimeAdjustmentDisabled is set to TRUE. In this mode, the value of dwTimeAdjustment is ignored, and the system may adjust the time of day using its own internal time synchronization mechanisms. These internal time synchronization mechanisms may cause the time-of-day clock to change during the normal course of the system operation, which can include noticeable jumps in time as deemed necessary by the system.

Time-Adjustment Enabled

For this mode, bTimeAdjustmentDisabled is set to FALSE. For each lpTimeIncrement period of time that actually passes, dwTimeAdjustment will be added to the time of day. The period of time represented by lpTimeIncrement can be determined by calling GetSystemTimeAdjustment. The lpTimeIncrement value is fixed by the system upon start and does not change during system operation and is completely independent of the system’s internal clock interrupt resolution at any given time. Given this, the lpTimeIncrement value simply expresses a period of time for which dwTimeAdjustment will be applied to the system’s time-of-day clock.

If the dwTimeAdjustment value is smaller than lpTimeIncrement, the time-of-day clock will advance at a rate slower than normal. If the dwTimeAdjustment value is larger than lpTimeIncrement, the time-of-day clock will advance at a rate faster than normal. The degree to which the time-of-day-clock will run faster or slower depends on how far the dwTimeAdjustment value is above or below the lpTimeIncrement value. If dwTimeAdjustment equals lpTimeIncrement, the time-of-day clock will advance at normal speed.

An application must have system-time privilege (the SE_SYSTEMTIME_NAME privilege) for this function to succeed. The SE_SYSTEMTIME_NAME privilege is disabled by default. Use the AdjustTokenPrivileges function to enable the privilege before calling SetSystemTimeAdjustment, and then to disable the privilege after the SetSystemTimeAdjustment call. For more information, see Running with Special Privileges.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	sysinfoapi.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll