Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751127AbeAAG26 (ORCPT + 1 other); Mon, 1 Jan 2018 01:28:58 -0500 Received: from mail-pg0-f66.google.com ([74.125.83.66]:43032 "EHLO mail-pg0-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750749AbeAAG24 (ORCPT ); Mon, 1 Jan 2018 01:28:56 -0500 X-Google-Smtp-Source: ACJfBov3xz5yrLRKB49WPE8Va4dd9HNqbDpeEJhq0X5B5haSyHGi9A3KU1RFoTOUh0P2UblGR3g2Fg== 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 1/2] clock_getres.2: Explain dynamic clocks. Date: Sun, 31 Dec 2017 22:28:51 -0800 Message-Id: X-Mailer: git-send-email 2.11.0 In-Reply-To: <20171219165811.6ahuquuf5hq74zg3@localhost> References: <20171219165811.6ahuquuf5hq74zg3@localhost> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: Linux has allowed passing open file descriptors to clock_gettime() and friends since v2.6.39. This patch documents these "dynamic" clocks and adds a brief example of how to use them. Signed-off-by: Richard Cochran --- man2/clock_getres.2 | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 index 0812d159a..30cbfe46a 100644 --- a/man2/clock_getres.2 +++ b/man2/clock_getres.2 @@ -183,6 +183,35 @@ Per-process CPU-time clock .TP .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" Thread-specific CPU-time clock. +.PP +Linux also implements dynamic clock instances as described below. +.SH DYNAMIC CLOCKS " (since Linux 2.6.39)" +In addition to hard coded SYS-V style clock ids, Linux also supports +POSIX clock operations on certain character devices. Such devices are +called "dynamic" clocks. Using the appropriate macros, open file +descriptors may be converted into clock ids and passed to +.BR clock_gettime (), +.BR clock_settime (), +and +.BR clock_adj (2). +The follow example shows how to convert a file descriptor into a +dynamic clock id. +.PP +.in +4n +.EX +#define CLOCKFD 3 +#define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) +#define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3)) + +struct timeval tv; +clockid_t clkid; +int fd; + +fd = open("/dev/ptp0", O_RDWR); +clkid = FD_TO_CLOCKID(fd); +clock_gettime(clkid, &tv); +.EE +.in .SH RETURN VALUE .BR clock_gettime (), .BR clock_settime (), @@ -200,11 +229,19 @@ points outside the accessible address space. .B EINVAL The .I clk_id -specified is not supported on this system. +specified is invalid for one of two reasons. Either the SYS-V style +hard coded positive value is out of range, or the dynamic clock id +does not refer to a valid instance of a clock object. .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be .\" EPERM. .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. +.TP .B EPERM .BR clock_settime () does not have permission to set the clock indicated. -- 2.11.0