adjtime.2 (2010 09)

a
adjtime(2) 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 (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.
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:
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1