Commit 65cade46 authored by Thomas Gleixner's avatar Thomas Gleixner
Browse files

posix-timers: Document sys_clock_getoverrun() 



Document the syscall in detail and with coherent sentences.

Signed-off-by: default avatarThomas Gleixner <tglx@linutronix.de>
Reviewed-by: default avatarFrederic Weisbecker <frederic@kernel.org>
Link: https://lore.kernel.org/r/20230425183313.462051641@linutronix.de
parent a86e9284

kernel/time/posix-timers.c

+17 −8
Original line number Diff line number Diff line
@@ -783,14 +783,23 @@ SYSCALL_DEFINE2(timer_gettime32, timer_t, timer_id, 


#endif



/*

 * Get the number of overruns of a POSIX.1b interval timer.  This is to

 * be the overrun of the timer last delivered.  At the same time we are

 * accumulating overruns on the next timer.  The overrun is frozen when

 * the signal is delivered, either at the notify time (if the info block

 * is not queued) or at the actual delivery time (as we are informed by

 * the call back to posixtimer_rearm().  So all we need to do is

 * to pick up the frozen overrun.

/**

 * sys_timer_getoverrun - Get the number of overruns of a POSIX.1b interval timer

 * @timer_id:	The timer ID which identifies the timer

 *

 * The "overrun count" of a timer is one plus the number of expiration

 * intervals which have elapsed between the first expiry, which queues the

 * signal and the actual signal delivery. On signal delivery the "overrun

 * count" is calculated and cached, so it can be returned directly here.

 *

 * As this is relative to the last queued signal the returned overrun count

 * is meaningless outside of the signal delivery path and even there it

 * does not accurately reflect the current state when user space evaluates

 * it.

 *

 * Returns:

 *	-EINVAL		@timer_id is invalid

 *	1..INT_MAX	The number of overruns related to the last delivered signal

 */

SYSCALL_DEFINE1(timer_getoverrun, timer_t, timer_id)

{