From patchwork Mon Jan 1 06:28:52 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Richard Cochran X-Patchwork-Id: 123029 Delivered-To: patch@linaro.org Received: by 10.140.22.227 with SMTP id 90csp7563236qgn; Sun, 31 Dec 2017 22:29:16 -0800 (PST) X-Google-Smtp-Source: ACJfBovCufUw3UEaWlDjR0f8/NIXKvWyjhWlDNfXJTWg3Jgj+O1R4mM3VdifHStHyxXWwyBrQNgZ X-Received: by 10.98.222.197 with SMTP id h188mr42194593pfg.132.1514788156107; Sun, 31 Dec 2017 22:29:16 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1514788156; cv=none; d=google.com; s=arc-20160816; b=uIvTtJ02FMJMYMj/3zRQZJHuOGQIo9xAXcVyC1xdYm4pRWc9yPRui19kXsmrmkvVNj 8jF6+z0XDsV0wSvuC0DgdL31vtEmVaeEmKPd+Bt8D3d0Aci4LZ4YC3Um/S6JykC5stdK aZOj26q8mBeQ0fV8RNrqIgJZxg0TMHX31C61Gy868FuO/5oDFgzOoi3t+X1mJl4Bj+dA YfX+C3mfKw91aEAmKdmi/5fLX7EZ0+9f1/gqAa/fMpn2A05O9C1bKXnlIVzh1hd3iPEa 1a4CQ8LfodDInSQpqucM0k+W1RQHNEtyl9K/9EScZ3ihsdaDaK0t69Z5Abbw1MFLgZYo hjhw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:references :in-reply-to:message-id:date:subject:cc:to:from:dkim-signature :arc-authentication-results; bh=9WeY/xDZNdlxR5JR+b371fJ7sm49ICgQbmOjE5XPxEg=; b=Aint+n1D2C1smyQgZBTyrsq63XNXE5MgACFadVHJi9AhNDpieIbOwgc7hc5tePxvRD 8T4iOQgyUU0gixrcjXEC1pr9UZ4V6Q9bMT2sF37Q8umXVhKzlmx5HDcSaFYh+f9mhOhU tGw2gEMr6OfrH6PjxEu723eM+mOnQRZJNoGbqrFa3m4qiF3ZJ9QmCePqV0IOjKDljt3n tqg2aBnQNekx73MnvdyFNSKzkZ83AWAbxXQqTry34ZZdoOaG0X69g+/iWJt2ebKfRJsb U5BIAjIEFG/ESLehEmNV3gM4izMs6gMVP8tYfisUxuGbVrHzD8sDh1Ndbmbutq6nfwCU FcWA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmail.com header.s=20161025 header.b=QkKC+Svy; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmail.com Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id y7si32383233plh.9.2017.12.31.22.29.15; Sun, 31 Dec 2017 22:29:16 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20161025 header.b=QkKC+Svy; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751213AbeAAG3K (ORCPT + 28 others); 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 Received: by mail-pf0-f193.google.com with SMTP id j28so24411993pfk.8; Sun, 31 Dec 2017 22:28:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :in-reply-to:references; bh=9WeY/xDZNdlxR5JR+b371fJ7sm49ICgQbmOjE5XPxEg=; b=QkKC+Svyla2aEiY93x/J3mwlS9Q2qlnJWjzPpFprlcHZP4GZdmZ7hE4FJPYYrY8R9N 7QPPRfvxY3nayJ+1kpkz8/04TqErAMTm8u8Dr09DyZsSOF1EwlQrKkO8wPAz4b7ifPkw XhXdf08AhgPEgSckxQVruUd+UldfqvsQUUKYLKInUWDLfb5TnMMBYnEMZ3WbecOszT10 88Y5SZ0dCOjW3BYAXxLwtfCkXZzvXv93TZ+Nl7tAdp/GjPCtQEOA7dVzMHwEcGYJHiwF rGlVmqdaJpLILUNxE6AmCFjCcKIxRxem8GUE2RH/bFfBMTjmOSnmBEIzVjfl1y1gzJnl LnMA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:in-reply-to:references; bh=9WeY/xDZNdlxR5JR+b371fJ7sm49ICgQbmOjE5XPxEg=; b=iXs1rzRqxFBD1KmCBkXLr6oYiFeQ2YbaRjb5h+yKwej6PSGfZGwVsvaEhJ/TTFCOdk mZRCdJxgnMNygG+LrWQFYVA1/WNxcPprVFeOQynBuQoXbanCxIq4jYaQ84tVuBddUi5f aQDUIfwWwwM0UuS06hfBc1hibargFDIrsq5dLB+gNtsR5DnZ6k3gnEvNmr5K8+bLX8Um Egc1D03/ofSIuYDGyEeFYua37tN9QImNsanCii67HuDwSWQxttBOB02/ITn97WtKNSRT /xaEQh7bNMtfAG44Qm+RWUzFOlhe9OR0nTFlGkchUpIiWzd9YYg6YG+EtlaHnCWZ8h2r se+Q== X-Gm-Message-State: AKGB3mLG2ma9Jt+RcYe3mGpjjjiKFpyAbJiOSwfJAJgLbmju/idUtxty Mu2DBxAufCNQ8Jmw3jtZQSK74w== X-Received: by 10.99.105.132 with SMTP id e126mr35455099pgc.414.1514788136854; Sun, 31 Dec 2017 22:28:56 -0800 (PST) Received: from netboy.linutronix.net (c-24-4-235-119.hsd1.ca.comcast.net. [24.4.235.119]) by smtp.gmail.com with ESMTPSA id k2sm75582402pff.150.2017.12.31.22.28.55 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 31 Dec 2017 22:28:56 -0800 (PST) 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 Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 -- 2.11.0 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