ClockAdjust(), ClockAdjust_r()

Adjust the time of a clock

Synopsis:

#include <sys/neutrino.h>

int ClockAdjust( clockid_t id,
                 const struct _clockadjust * new,
                 struct _clockadjust * old );

int ClockAdjust_r( clockid_t id,
                   const struct _clockadjust * new,
                   struct _clockadjust * old );

Description:

The ClockAdjust() and ClockAdjust_r() functions are identical except in the way they indicate errors. See the Returns section for details.

These kernel calls allow you to gradually adjust the time of the clock specified by id. The clock ID, CLOCK_REALTIME, maintains the system time. The ClockAdjust() function can be used to speed up or slow down the system clock to synchronize it with another time source -- without causing major discontinuities in the time flow.

If new isn't NULL then it contains an adjustment to be applied to the clock. Any previous adjustment is replaced. The argument new contains at least the following members:

Member	Meaning
`long` tick_nsec_inc	The adjustment to be made on each clock tick, in nanoseconds.
`unsigned long` tick_count	The number of clock ticks over which the adjustment should be applied.

The total time adjustment in nanoseconds is:

(new->tick_count * new->tick_nsec_inc)

If the current clock is ahead of the desired time, a negative tick_nsec_inc can be passed to slow the clock down. This is preferable to setting the time backwards with the ClockTime() kernel call, since some programs may malfunction if time goes backwards.

Picking small values for tick_nsec_inc and large values for tick_count adjusts the time slowly, while the opposite approach adjusts it rapidly. As a rule of thumb, don't try to set a tick_nsec_inc that exceeds the basic clock tick as set by the ClockPeriod() kernel call. This would change the clock rate by more than 100% and if the adjustment was negative, it could result in the clock going backwards.

You can cancel any adjustment in progress by setting tick_count and tick_nsec_inc to 0.

Superuser privileges are required to adjust the clock.

If old isn't NULL, then the current adjustment (before being changed by a non-NULL new) is returned in it.

Blocking states:

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

ClockAdjust(): If an error occurs, -1 is returned and errno is set. Any other value returned indicates success.
ClockAdjust_r(): EOK is returned on success. This function does NOT set errno. If an error occurs, any value in the Errors section may be returned.

Errors:

EFAULT: A fault occurred when the kernel tried to access the buffers provided.
EINVAL: The clock id isn't valid.
EPERM: The process tried to adjust the time without having superuser capabilities.

Classification:

QNX 6

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	No