qnx_adj_time()

gradually adjust the system clock

Synopsis:

#include <time.h>

int qnx_adj_time(long usec, 
                 long rate, 
                 long *onsec,
                 long *ocount);

The qnx_adj_time() function gradually adjusts the system clock until it has been increased or decreased by the number of microseconds specified by the usec argument. A positive usec value increases the clock, while a negative one decreases the clock.

The clock is partially adjusted every system tick until it has been adjusted by the entire usec amount. The system tick size is set by the qnx_ticksize() function.

The rate argument controls the amount by which the clock is adjusted every tick. This adjustment value is a fraction of the tick size, calculated as (1/rate). You should keep your rates below 10% (that is, rate of 10 = 1/10).

For example, a rate of 100 is (1/100) or 1% of the tick size, while a rate of 2000 is (1/2000) or 0.05% of the tick size. The smaller the fraction of the ticksize, the longer it takes to achieve the desired clock adjustment.

When qnx_adj_time() is called with a rate of zero, its a read-only call that extracts the current time adjustment values. The tick size adjustment value is placed in the onsec argument, while ocount contains the number of remaining clock ticks before the time adjustment is complete. Thus, the total remaining adjustment time can be calculated as (onsec * ocount). Note that you must have previously called qnx_adj_time() with usec and a nonzero rate to set the adjustment values.

The qnx_adj_time() function can be used when you need to speed up or slow down the system clock to synchronize it with another time source without causing any major discontinuities in the time flow.

If the current clock is ahead, it is generally better to pass a negative usec value to qnx_adj_time() to slow the clock down, rather than simply setting the time backwards with the qnx_setclock() function, since some programs may malfunction if time goes backwards.

Possible external clock sources can be the realtime clock on the PC, the system clock on another node, or any other external clock source.

Returns:

0: Success
-1: An error occurred. errno is set to indicate the error.

Errors:

EPERM: Operation not permitted. You must be root.
ENOSYS: The qnx_adj_time() function is not supported.

Examples:

main(int argc, char *argv[])
{
   long rate, usec, c, d;
   int rc;

   usec = atol(argv[1]);
   rate = atol(argv[2]);

   rc = qnx_adj_time(usec, rate, &c, &d);
   printf("rc=%d nsec=%ld count=%ld\n", rc, c, d);

   if(rc == 0)
   do {
       rc = qnx_adj_time(0, 0, &c, &d);
       printf("rc=%d nsec=%ld count=%ld\n", rc, c, d);
   } while(rc == 0  &&  c != 0) ;
}

Classification:

QNX

Safety:
Interrupt handler	No
Signal handler	Yes
Thread	Yes

Caveats:

Your application must run as root to call this function.