Hello Richard, Arnd, On 1/1/18 7:28 AM, Richard Cochran wrote: > 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. ] And this patch too is now applied. Thank you! Cheers, Michael > 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 > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/