unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 adjtime(2)							  adjtime(2)




 NAME
      adjtime() - correct the time to synchronize the system clock

 SYNOPSIS
      #include <&lt&lt&lt;sys/time.h>&gt&gt&gt;

      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:

	   struct timeval {
	      unsigned long tv_sec;	    /* seconds */
	      long	    tv_usec;	    /* and microseconds */
	   };

      When adjtime() is called, if the delta.tv_sec field is greater than
      31536000 (approx. 365 days), or less than -31536000, then adjtime()



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 adjtime(2)							  adjtime(2)




      fails with an errno of EINVAL. The tv_usec field is not used in the
      calculations to determine the limits, and so the actual limit on
      adjustments are [-31536000-LONG_MIN, 31536000+LONG_MAX].

      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().

 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 (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
      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(&&amp&amp&amp;forward, (struct timeval *)NULL) == -1)
	      perror("adjtime() failure");

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



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 adjtime(2)							  adjtime(2)




	   */

      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, &&amp&amp&amp;report) == -1)
	   perror("adjtime() failure");

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

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

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

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




























 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000