From: Karel Zak <kzak@redhat.com>
Date: Fri, 28 Apr 2017 11:25:41 +0000 (+0200)
Subject: lib/timer: add comment
X-Git-Tag: v2.30-rc1~78
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dc9a23fe66356ece744e27d14bb5fc3368a1a829;p=thirdparty%2Futil-linux.git

lib/timer: add comment

Signed-off-by: Karel Zak <kzak@redhat.com>
---

diff --git a/lib/timer.c b/lib/timer.c
index 813eade948..210c726cbe 100644
--- a/lib/timer.c
+++ b/lib/timer.c
@@ -10,6 +10,23 @@
 #include "c.h"
 #include "timer.h"
 
+/*
+ * Note the timeout is used for the first signal, then the signal is send
+ * repeatedly in interval ~1% of the original timeout to avoid race in signal
+ * handling -- for example you want to use timer to define timeout for a
+ * syscall:
+ *
+ *	 setup_timer()
+ *	 syscall()
+ *	 cancel_timer()
+ *
+ * if the timeout is too short than it's possible that the signal is delivered
+ * before application enter the syscall function. For this reason timer send
+ * the signal repeatedly.
+ *
+ * The applications need to ensure that they can tolerate multiple signal
+ * deliveries.
+ */
 int setup_timer(timer_t * t_id, struct itimerval *timeout,
 		void (*timeout_handler)(int, siginfo_t *, void *))
 {