On Sun, Jul 30, 2023 at 08:20:31PM -0500, Scott Cheloha wrote: > 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? >
hi. fine by me. i would stick with "high resolution", purely because we seem to have no other instances of "high-resolution". jmc > 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.
