On Fri, Jun 18, 2021 at 04:27:36PM -0500, Scott Cheloha wrote: > > I've also added a CAVEATS section. > > I've also tweaked the .Nd summary: > > .Nd schedule SIGALRM delivery > > Thoughts? >
reads ok to me. one possible tweak inline: > Index: alarm.3 > =================================================================== > RCS file: /cvs/src/lib/libc/gen/alarm.3,v > retrieving revision 1.15 > diff -u -p -r1.15 alarm.3 > --- alarm.3 28 Jan 2016 22:11:39 -0000 1.15 > +++ alarm.3 18 Jun 2021 21:26:23 -0000 > @@ -32,7 +32,7 @@ > .Os > .Sh NAME > .Nm alarm > -.Nd set signal timer alarm > +.Nd schedule SIGALRM delivery > .Sh SYNOPSIS > .In unistd.h > .Ft unsigned int > @@ -45,32 +45,30 @@ This is a simplified interface to > .Pp > The > .Fn alarm > -function waits a count of > -.Ar seconds > -before asserting the terminating signal > -.Dv SIGALRM . > -When the signal has successfully been caught, > -.Fn alarm > -returns the amount of time left on the clock. > -The maximum number of > -.Ar seconds > -allowed > -is 100000000. > +function schedules the > +.Dv SIGALRM > +signal for delivery to the calling process after the given number of > +.Fa seconds > +have elapsed. > .Pp > -If an alarm has been set with > -.Fn alarm , > +If an alarm is already pending, > another call to > .Fn alarm > will supersede the prior call. > -The request > -.Fn alarm "0" > -voids the current > -alarm. > +.Pp > +If > +.Fa seconds > +is zero, > +any pending alarm is cancelled. > .Sh RETURN VALUES > -If the call succeeds, any time left remaining from a previous call is > returned. > -If an error occurs, the value \-1 is returned, and a more precise > -error code is placed in the global variable > -.Va errno . > +.Fn alarm > +returns the number of seconds remaining until the pending alarm would have > +expired. > +If the alarm has already expired, > +or the alarm was cancelled, i would remove "or" from the sentence above. jmc > +or no alarm was ever scheduled, > +.Fn alarm > +returns zero. > .Sh SEE ALSO > .Xr setitimer 2 , > .Xr sigaction 2 , > @@ -94,3 +92,15 @@ For > it was reimplemented as a wrapper around the > .Xr setitimer 2 > system call. > +.Sh CAVEATS > +The > +.Fn alarm > +function is implemented with the per-process > +.Dv ITIMER_REAL > +timer described in > +.Xr setitimer 2 . > +Use of both > +.Fn alarm > +and > +.Xr setitimer 2 > +in the same program may yield confusing behavior.
