adjtime(2)

NAME

adjtime() — correct the time to synchronize the system clock

SYNOPSIS

#include <sys/time.h> 

int adjtime( 
    const struct timeval *delta, 
    struct timeval *olddelta 
); 

DESCRIPTION

The function adjtime() adjusts the current time of the system. The time is either advanced or retarded by the amount of time specified in the struct timeval pointed to by delta.

The adjustment is made by applying small correctional adjustments to the value of current time that the system keeps. The time is always increasing monotonically, but at a rate slightly slower or faster than normal.

A time correction for an earlier call to adjtime() may not be complete when adjtime() is called. The second call to adjtime() stops the first call to adjtime() if delta is non-NULL, but does not undo the effects of the previous call. If delta is NULL, then no time correction will be done.

If olddelta is not a NULL pointer, then the structure it points to will contain, upon return, the number of seconds and/or microseconds still to be corrected from the earlier call. If olddelta is a NULL pointer, the corresponding information will not be returned.

The call to adjtime() returns immediately, though its effect will continue until the whole correction is made or until modified by another call to either adjtime() with a non-NULL delta or to change the system time (see Interaction with Other System Calls).

Only a user with appropriate privileges can call adjtime() successfully with a non-NULL delta. Any user can call adjtime() with a NULL delta to report the correction left from the previous call.

Limits

struct timeval is defined in <time.h> as having at least 2 members, tv_sec (seconds) and tv_usec (microseconds).

When adjtime() is called, if the delta.tv_sec field is greater than 31536000 (approximately 365 days), or less than -31536000, then adjtime() fails with an errno of EINVAL. The tv_usec field is not used in the calculations to determine the limits, and so the actual limits on adjustments are [-31536000 + (LONG_MIN/1000000), 31536000 + (LONG_MAX/1000000)] seconds.

Note that the desired seconds may be negative. Since the type of the tv_sec field is (unsigned long), any negative values for tv_sec need to be cast.

Any olddelta value returned by the adjtime() function will be returned such that the signs of non-zero members are the same.

Interaction with Other System Calls

A call to change the system time terminates the adjtime() correction currently in effect. A subsequent call to adjtime() will return {0, 0} for the olddelta parameter. This includes system calls such as stime() and clock_settime().

Security Restrictions

This system call requires the SYSATTR privilege in order to successfully usa a non-NULL delta. Processes owned by the superuser have this privilege. Processes owned by other users may have this privilege, depending on system configuration. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

Upon successful completion, adjtime() returns a value of 0; otherwise, it returns a value -1 and sets errno to indicate the error.

ERRORS

adjtime() fails if one or more of the following is true:

EPERM: if the process does not have the appropriate privilege.
EFAULT: The address specified for delta (or olddelta) is invalid.
EINVAL: If delta.tv_sec is greater than 31536000 (approximately 365 days) or less than -31536000. The delta.tv_usec field is not used in calculation of these limits. If the user wants to adjust time greater than these limits, an appropriate alternative interface should be used.

EXAMPLES

The following code snippet will take the time forward 20 minutes.

    struct timeval forward; 

    forward.tv_sec = 20 * 60;   /* 20 minutes */ 
    forward.tv_usec = 0; 

    if (adjtime(&forward, (struct timeval *)NULL) == -1) 
        perror("adjtime() failure"); 

    /* 
     *  If adjtime() succeeds, the system time will move forward 
     *  20 minutes over a period of time. 
     */ 

The following code fragment will repeatedly call a user-defined function adjustment_still_in_progress() until the adjustment requested in a previous call to adjtime() (called from either the same process or another process) is completed.

struct timeval report; 

if (adjtime((struct timeval *)NULL, &report) == -1) 
     perror("adjtime() failure"); 

while (report.tv_sec || report.tv_usec) { 
     adjustment_still_in_progress(); 

     if (adjtime((struct timeval *)NULL, &report) == -1) 
          perror("adjtime() failure"); 
} 

AUTHOR

adjtime() was developed by the University of California, Berkeley and AT&T.