This patch drags ualarm.3 over to where alarm.3 is. I think it reads better and the wording is truer to what the function actually does. In particular, ualarm(3) does not block or "wait": the alarm is scheduled for asynchronous delivery by the operating system.
I think I may have tried to clean this up two years ago. I don't remember where that got sidetracked, but fwiw this was written from scratch using alarm.3 as a guide. Two things I'm iffy on: - "high resolution" or "high-resolution"? - The current manual mentions an upper bound (2147483647). I'm not sure when, if ever, this was the real: useconds_t is unsigned, so an upper bound of INT32_MAX seems off. I am leaning toward just leaving the patch as-is instead of trying to guide the end-user through the minefield of matching bespoke "_t" types to real types and limits. Tweaks? ok? 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 31 Jul 2023 01:05:23 -0000 @@ -32,7 +32,7 @@ .Os .Sh NAME .Nm ualarm -.Nd schedule signal after specified time +.Nd schedule high resolution SIGALRM delivery .Sh SYNOPSIS .In unistd.h .Ft useconds_t @@ -45,31 +45,37 @@ 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 at least 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, +the .Dv SIGALRM -signal will be sent -to the process every +signal is scheduled for redelivery to the calling process every .Fa interval -microseconds after the timer expires (e.g., after +microseconds thereafter. +.Pp +If an alarm is already pending, +an additional call to +.Fn ualarm +supersedes the prior call. +.Pp +If .Fa microseconds -number of microseconds have passed). +is zero, +any pending alarm is cancelled and the value of +.Fa interval +is ignored. .Sh RETURN VALUES -When the signal has successfully been caught, +The .Fn ualarm -returns the amount of time left on the clock. -The maximum value for -.Fa microseconds -allowed -is 2147483647. +function returns the number of microseconds remaining until the next +alarm is scheduled for delivery, +or zero if no alarm is pending. .Sh SEE ALSO .Xr setitimer 2 , .Xr sigaction 2 , @@ -86,5 +92,17 @@ function conforms to .Sh HISTORY The .Fn ualarm -function appeared in +function first appeared in .Bx 4.3 . +.Sh CAVEATS +The +.Fn ualarm +function is implemented with the per-process +.Dv ITIMER_REAL +timer described in +.Xr setitimer 2 . +Use of both +.Fn ualarm +and +.Xr setitimer 2 +in the same program may yield confusing behavior.
