lkml.org 
[lkml]   [2020]   [Apr]   [20]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime
From
Date
Hello Richard, Arnd,

On 1/1/18 7:28 AM, Richard Cochran wrote:
> From: Arnd Bergmann <arnd@arndb.de>
>
> 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@arndb.de>
> Signed-off-by: Richard Cochran <richardcochran@gmail.com>
> ---
> 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/

\
 
 \ /
  Last update: 2020-04-20 13:14    [W:0.046 / U:1.348 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site