Hi, As it would turn out, there are not one, but *two* simplified interfaces to setitimer(2). We just cleaned up the alarm(3) manpage, but did you know there is also a ualarm(3) interface?
Luckily it's basically the same interface as alarm(3). So, I have taken the rewritten manpage from alarm.3 and transposed it into ualarm.3. The only details that change are the units (microseconds instead of seconds) and the additional input, "interval", which I have noted in the DESCRIPTION. All the changes over there apply here re describing what the interface actually does. It basically does the same thing so I see no reason not to reuse what I wrote for that page. Given that alarm(3), ualarm(3), and setitimer(2) all poke at the same underlying per-process timer I think it makes sense to mention all three interfaces in the CAVEATS section of both alarm.3 and ualarm.3. (A getitimer.2 cleanup is coming, don't fret.) The only thing I'm unsure about is how to talk about the input limits. useconds_t is uint32_t on all platforms. Is there a more graceful way to tell people the limit than the literal number as we do now? Maybe UINT32_MAX? POSIX defines the type but does not define a USECONDS_MAX constant. Thoughts? Index: alarm.3 =================================================================== RCS file: /cvs/src/lib/libc/gen/alarm.3,v retrieving revision 1.16 diff -u -p -r1.16 alarm.3 --- alarm.3 18 Jun 2021 22:21:29 -0000 1.16 +++ alarm.3 30 Jun 2021 20:00:14 -0000 @@ -95,12 +95,17 @@ system call. .Sh CAVEATS The .Fn alarm -function is implemented with the per-process +function, +like +.Xr ualarm 3 , +is implemented with the per-process .Dv ITIMER_REAL timer described in .Xr setitimer 2 . -Use of both +Use of .Fn alarm -and +along with +.Xr ualarm 3 +or .Xr setitimer 2 in the same program may yield confusing behavior. Index: ualarm.3 =================================================================== RCS file: /cvs/src/lib/libc/gen/ualarm.3,v retrieving revision 1.17 diff -u -p -r1.17 ualarm.3 --- ualarm.3 26 Jul 2019 12:08:18 -0000 1.17 +++ ualarm.3 30 Jun 2021 20:00:14 -0000 @@ -32,7 +32,7 @@ .Os .Sh NAME .Nm ualarm -.Nd schedule signal after specified time +.Nd schedule periodic SIGALRM delivery .Sh SYNOPSIS .In unistd.h .Ft useconds_t @@ -45,31 +45,41 @@ This is a simplified interface to .Pp The .Fn ualarm -function waits a count of +function schedules the +.Dv SIGALRM +signal for delivery to the calling process after the given number of .Fa microseconds -before asserting the terminating signal -.Dv SIGALRM . -System activity or time used in processing the call may cause a slight -delay. -.Pp -If the +have elapsed. +If .Fa interval -argument is non-zero, the +is non-zero, +an additional .Dv SIGALRM -signal will be sent -to the process every +signal will be delivered to the calling process every .Fa interval -microseconds after the timer expires (e.g., after +microseconds thereafter until cancellation. +.Pp +If an alarm is already pending, +another call to +.Fn ualarm +will supersede the prior call. +.Pp +If .Fa microseconds -number of microseconds have passed). +is zero, +any pending alarm is cancelled. +No new alarm is scheduled, +regardless of the value of +.Fa interval . .Sh RETURN VALUES -When the signal has successfully been caught, .Fn ualarm -returns the amount of time left on the clock. -The maximum value for -.Fa microseconds -allowed -is 2147483647. +returns the number of microseconds remaining until the pending alarm would have +expired. +If the alarm has already expired, +the alarm was already cancelled, +or no alarm was ever scheduled, +.Fn ualarm +returns zero. .Sh SEE ALSO .Xr setitimer 2 , .Xr sigaction 2 , @@ -88,3 +98,20 @@ The .Fn ualarm function appeared in .Bx 4.3 . +.Sh CAVEATS +The +.Fn ualarm +function, +like +.Xr alarm 3 , +is implemented with the per-process +.Dv ITIMER_REAL +timer described in +.Xr setitimer 2 . +Use of +.Fn ualarm +along with +.Xr alarm 3 +or +.Xr setitimer 2 +in the same program may yield confusing behavior.
