Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751213AbeAAG3K (ORCPT + 1 other); Mon, 1 Jan 2018 01:29:10 -0500 Received: from mail-pf0-f193.google.com ([209.85.192.193]:41415 "EHLO mail-pf0-f193.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750788AbeAAG25 (ORCPT ); Mon, 1 Jan 2018 01:28:57 -0500 X-Google-Smtp-Source: ACJfBouVUBu756bORNfPggeICNHSNime2Vm19kpTFGCqCwGFY1OcADY2PCF/larR4+bf8ZvZ14V0/Q== From: Richard Cochran To: Michael Kerrisk Cc: Arnd Bergmann , John Stultz , Stephen Boyd , Thomas Gleixner , linux-api@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime Date: Sun, 31 Dec 2017 22:28:52 -0800 Message-Id: <88e5c54201bcfc335e484e83ab66f31f48e9f504.1514787752.git.richardcochran@gmail.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20171219165811.6ahuquuf5hq74zg3@localhost> References: <20171219165811.6ahuquuf5hq74zg3@localhost> In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: From: Arnd Bergmann 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 Signed-off-by: Richard Cochran --- 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