Scott Cheloha <[email protected]> wrote: > I want to improve the alarm(3) manpage. Here's a first attempt: > > - Correct the initial behavior description. alarm(3) does not "wait". > It schedules signal delivery at a point in the future.
you are right about this. > The > .Fn alarm > +function causes the asynchronous delivery of the > +.Dv SIGALRM > +signal to the calling process after the given number of > +.Fa seconds > +have elapsed. But I dislike this text since it doesn't speak to the underlying mechanism. The .Fn alarm function configures the process .Va ITIMER_REAL interval timer with .Xr setitimer 2 to deliver a .Va SIGALRM signal in the future. (This also hints that parallel use of the underlying mechanism, ITIMER_REAL, could break expectations.) I do not like your wording about 'asynchronous delivery of a signal', I don't see the need to explain the the nature of signal delivery. The rest of your changes seem reasonable, better detailing of edges. > .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, > +or no alarm was ever scheduled, > +.Fn alarm > +returns zero. > .Sh SEE ALSO > .Xr setitimer 2 , > .Xr sigaction 2 , >
