LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

adjtimex.2: Document clock_adjtime(2) 

I was experimenting with some possible changes to adjtimex(2) and
clock_adjtime(2) and tried to look up the man page to see what the
documented behavior is when I noticed that clock_adjtime() appears
to be the only system call that is currently undocumented.

Before I do any changes to it, this tries to document what I
understand it currently does.

[ RC: Add better explanations of the usage and error codes
  and correct some typographical mistakes. ]

Signed-off-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Richard Cochran <richardcochran@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Arnd Bergmann 2017-12-31 22:28:52 -08:00 committed by Michael Kerrisk
parent bd72f280c9
commit 1ebc1dbaa1
1 changed files with 60 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
man2/adjtimex.2
View File

@ -35,6 +35,8 @@ adjtimex, ntp_adjtime \- tune kernel clock
.PP
.BI "int adjtimex(struct timex *" "buf" );
.PP
.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
.PP
.BI "int ntp_adjtime(struct timex *" buf );
.fi
.SH DESCRIPTION
@ -158,8 +160,26 @@ includes the
.B ADJ_NANO
flag, then
.I buf.time.tv_usec
is interpreted as a nanosecond value;
is interpreted as a nanosecond value,
otherwise it is interpreted as microseconds.
.IP
The value of
.I buf.time
is the sum of its two fields, but the
field
.I buf.time.tv_usec
must always be non-negative. The following example shows how to
normalize a timeval with nanosecond resolution.
.PP
.in +12n
.EX
while (buf.time.tv_usec < 0) {
buf.time.tv_sec -= 1;
buf.time.tv_usec += 1000000000;
}
.EE
.in
.PP
.TP
.BR ADJ_MICRO " (since Linux 2.6.26)"
.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
@ -344,6 +364,12 @@ Attempts to set read-only
.I status
bits are silently ignored.
.\"
.SS clock_adjtime ()
The
.BR clock_adjtime ()
system call (added in Linux 2.6.39) behaves like adjtimex() but takes an additional
.IR clk_id
argument to specify the particular clock on which to act.
.SS ntp_adjtime ()
The
.BR ntp_adjtime ()
@ -472,6 +498,19 @@ An attempt was made to set
to a value other than those listed above.
.TP
.B EINVAL
The
.I clk_id
given to
.BR clock_adjtime ()
is invalid for one of two reasons. Either the SYS-V style hard coded
positive value is out of range, or the dynamic
.I clk_id
does not refer to a valid instance of a clock object.
See
.BR clock_gettime (2)
for a discussion of dynamic clocks.
.TP
.B EINVAL
An attempt was made to set
.I buf.tick
to a value outside the range
@ -482,6 +521,20 @@ where
.B HZ
is the system timer interrupt frequency.
.TP
.B ENODEV
The hot-plugable device (like USB for example) represented by a
dynamic
.I clk_id
has disappeared after its character device was opened.
See
.BR clock_gettime (2)
for a discussion of dynamic clocks.
.TP
.B EOPNOTSUPP
The given
.I clk_id
does not support adjustment.
.TP
.B EPERM
.I buf.modes
is neither 0 nor
@ -503,10 +556,12 @@ T{
T} Thread safety MT-Safe
.TE
.SH CONFORMING TO
Neither of these interfaces is described in POSIX.1
None of these interfaces is described in POSIX.1
.PP
.BR adjtimex ()
is Linux-specific and should not be used in programs
and
.BR clock_adjtime ()
are Linux-specific and should not be used in programs
intended to be portable.
.PP
The preferred API for the NTP daemon is
@ -533,6 +588,8 @@ is done by the kernel in timer context.
Thus, it will take one tick into the second
for the leap second to be inserted or deleted.
.SH SEE ALSO
.BR clock_gettime (2)
.BR clock_settime (2)
.BR settimeofday (2),
.BR adjtime (3),
.BR ntp_gettime (3),