From: Arnd Bergmann <arnd@xxxxxxxx>
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@xxxxxxxx>
Signed-off-by: Richard Cochran <richardcochran@xxxxxxxxx>
---
man2/adjtimex.2 | 63 +++++++++++++++++++++++++++++++++++++++++++++++++---
man2/clock_adjtime.2 | 1 +
2 files changed, 61 insertions(+), 3 deletions(-)
create mode 100644 man2/clock_adjtime.2
diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index fc6892d7e..71b5c4a5a 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -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),
diff --git a/man2/clock_adjtime.2 b/man2/clock_adjtime.2
new file mode 100644
index 000000000..b08b9c801
--- /dev/null
+++ b/man2/clock_adjtime.2
@@ -0,0 +1 @@
+.so man2/adjtimex.2
--
2.11.0
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
