Document new clock IDs and describe semantics in a bit more detail.
PATCH 1/1 Document new clock IDs and describe semantics in a bit more detail.
Some time ago there was a request for more documentation of some of the newer POSIX clocks, and in particular of their characteristics with respect to NTP. I took a whack at adding this documentation against manpages release 3.24.
This patch adds description of the new clocks CLOCK_REALTIME_COARSE and CLOCK_MONOTONIC_COARSE, as well as CLOCK_MONOTONIC_RAW. I also added a bit of clarification in surrounding man pages (clock_getres, timer_create, clock_nanosleep).
I called the general clock description page posix_clocks.7 rather than linux_clocks.7, as these are clocks that fit into the POSIX framework (as opposed to other, non-POSIX clocks which are described elsewhere).
I welcome any thoughts or comments.
- bog
Quoted 1 line
From
8bfd08b81487b8a09f5e72a753ded50da41e3bd1Mon Sep 17 00:00:00 2001
From: Bill O. Gallmeister <[email protected]>
Date: Wed, 20 Jan 2010 21:58:07 -0800
Subject: [PATCH] Document new clock IDs and describe semantics in a bit more detail.
This patch introduces one new man page, posix_clocks.7, which describes all currently-supported CLOCK_IDs. The different behavior of each clock type is briefly described. A bit of additional clarification is added to some of the surrounding clock_ and timer_ man pages as well.
--- man2/clock_getres.2 | 28 ++++++++- man2/clock_nanosleep.2 | 6 +- man2/timer_create.2 | 9 +++ man7/posix_clocks.7 | 154 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 193 insertions(+), 4 deletions(-) create mode 100644 man7/posix_clocks.7
man2/clock_getres.2 +26 -2
@@ -118,12 +118,21 @@ Sufficiently recent versions of glibc and the Linux kernel support the following clocks: .TP .B CLOCK_REALTIME -System-wide real-time clock. +System-wide real-time clock, +potentially managed by NTP. Setting this clock requires appropriate privileges. +This clock may slew and it may jump, depending on adjustments propagated by +NTP. +.TP +.BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)" +Clock like CLOCK_REALTIME, but of coarser granularity +and faster to access. .TP .B CLOCK_MONOTONIC Clock that cannot be set and represents monotonic time since some unspecified starting point. +This clock may slew in response to NTP adjustments, but is guaranteed not to +jump backwards. .TP .BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)" .\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz
@@ -132,6 +141,10 @@ Similar to but provides access to a raw hardware-based time that is not subject to NTP adjustments. .TP +.BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)" +Monotonic clock like CLOCK_MONOTONIC, but of coarser granularity +and faster to access. +.TP .B CLOCK_PROCESS_CPUTIME_ID High-resolution per-process timer from the CPU. .TP
@@ -154,7 +167,15 @@ points outside the accessible address space. .B EINVAL The .I clk_id -specified is not supported on this system. +specified is not supported on this system for the desired operation +(for example, +.B CLOCK_MONOTONIC +cannot be set, so +.B EINVAL +will be returned if you pass it a +.I clk_id +equal to +.B CLOCK_MONOTONIC). .TP .B EPERM .BR clock_settime ()
@@ -168,10 +189,12 @@ is defined in \fI<unistd.h>\fP to a value greater than 0. The symbols .BR _POSIX_MONOTONIC_CLOCK , .BR _POSIX_CPUTIME , +and .B _POSIX_THREAD_CPUTIME indicate that .BR CLOCK_MONOTONIC , .BR CLOCK_PROCESS_CPUTIME_ID , +and .B CLOCK_THREAD_CPUTIME_ID are available. (See also
@@ -231,4 +254,5 @@ are not settable. .BR ftime (3), .BR pthread_getcpuclockid (3), .BR sysconf (3), +.BR posix_clocks (7), .BR time (7)
man2/clock_nanosleep.2 +4 -2
@@ -166,8 +166,10 @@ was negative. .B EINVAL .I clock_id was invalid. -.RB ( CLOCK_THREAD_CPUTIME_ID -is not a permitted value for +.RB ( CLOCK_THREAD_CPUTIME_ID , CLOCK_MONOTONIC_RAW , CLOCK_REALTIME_COARSE , +and +.B CLOCK_MONOTONIC_COARSE +are not permitted values for .IR clock_id .) .SH VERSIONS The
man2/timer_create.2 +9 -0
@@ -1,5 +1,6 @@ .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk .\" <[email protected]> +.\" Some additions by Bill O. Gallmeister <[email protected]> .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are
@@ -74,6 +75,8 @@ A clock that measures (user and system) CPU time consumed by the calling thread. .\" The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used .\" to create a timer -- mtk, Feb 2009 +.\" The CLOCK_MONOTONIC_COARSE and CLOCK_REALTIME_COARSE that were added in +.\" 2.6.32 can't be used to create a timer -- bog, Jan 2010 .PP As well as the above values, .I clockid
@@ -274,6 +277,12 @@ glibc provided an incomplete userspace implementation timers only) using POSIX threads, and current glibc falls back to this implementation on systems running pre-2.6 Linux kernels. +.PP +.BR CLOCK_REALTIME_COARSE , +.BR CLOCK_MONOTONIC_COARSE , +and +.B CLOCK_MONOTONIC_RAW +may not be used for creating timers. .SH EXAMPLE The program below takes two arguments: a sleep period in seconds, and a timer frequency in nanoseconds.
man7/posix_clocks.7 new file +154 -0
154 lines not on this page · raw message
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html