[PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks.

[Richard Cochran <richardcochran-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

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 <richardcochran-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 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