timerfd_create.2: Document TFD_TIMER_CANCEL_ON_SET

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
index 698b160c983eb558deaab59d736243f9dfad3d61..dcfb63a81c4dbe38d41f2b61670ac3fbb90d34c7 100644 (file)
--- a/man2/timerfd_create.2
+++ b/man2/timerfd_create.2
@@ -209,6 +209,23 @@ as an absolute value on the timer's clock.
 The timer will expire when the value of the timer's
 clock reaches the value specified in
 .IR new_value.it_value .
+.TP
+.BR TFD_TIMER_CANCEL_ON_SET
+If this flag is specified along with
+.B TFD_TIMER_ABSTIME
+and the clock for this timer is
+.BR CLOCK_REALTIME
+or
+.BR CLOCK_REALTIME_ALARM ,
+then mark this timer as cancelable if the real-time clock
+undergoes a discontinuous change
+.RB ( settimeofday (2),
+.BR clock_settime (2),
+or similar).
+When such changes occur, a current or future
+.BR read (2)
+from the file descriptor will fail with the error
+.BR ECANCELED .
 .PP
 If the
 .I old_value
@@ -283,6 +300,24 @@ A
 will fail with the error
 .B EINVAL
 if the size of the supplied buffer is less than 8 bytes.
+
+If the associated clock is either
+.BR CLOCK_REALTIME
+or
+.BR CLOCK_REALTIME_ALARM ,
+the timer is absolute
+.RB ( TFD_TIMER_ABSTIME ),
+and the flag
+.BR TFD_TIMER_CANCEL_ON_SET
+was specified when calling
+.BR timerfd_settime (),
+then
+.BR read (2)
+will fail with the error
+.BR ECANCELED
+if the real-time clock undergoes a discontinuous change.
+(This allows the reading application to discover
+such discontinuous changes to the clock.)
 .TP
 .BR poll "(2), " select "(2) (and similar)"
 The file descriptor is readable