adjtime(2)                                                       adjtime(2)




 NAME    [Toc]    [Back]
      adjtime() - correct the time to synchronize the system clock

 SYNOPSIS    [Toc]    [Back]
      #include <sys/time.h>

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

 DESCRIPTION    [Toc]    [Back]
      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    [Toc]    [Back]
      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 (approx. 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.



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 adjtime(2)                                                       adjtime(2)




      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    [Toc]    [Back]
      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().

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

 ERRORS    [Toc]    [Back]
      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 (approx.
                          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    [Toc]    [Back]
      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



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 adjtime(2)                                                       adjtime(2)




      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    [Toc]    [Back]
      adjtime() was developed by the University of California, Berkeley and
      AT&T.

 SEE ALSO    [Toc]    [Back]
      date(1), gettimeofday(2), stime(2), clock_settime(2), clocks(2),
      getitimer(2), setitimer(2), alarm(2).


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003