On Fri, Jun 18, 2021 at 12:46:38PM -0600, Theo de Raadt wrote: > Todd C. Miller <[email protected]> wrote: > > > On Fri, 18 Jun 2021 12:02:18 -0600, "Theo de Raadt" wrote: > > > > > 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.) > > > > This is an implementation detail that is not reflected by the > > standard. Historically alarm() was a system call and there are > > still OSes where that is the case. > > > > On the other hand, it is good to document that on OpenBSD trying > > to use both alarm() and ITIMER_REAL would interact in surprising > > ways. > > > > To me, this seems like information that belongs in a CAVEAT section. > > Ok, fine. > > But I still feel the proposed "asyncronous delivery of signal" chunk > is crazy, if people don't understand signals this is the wrong time > to introduce them to the concepts (it makes the sentence describing > alarm, suddenly describe something else tangential)
I guess I see what you mean. I'm not sure what else to say about alarm(3), though. Maybe this? The .Fn alarm function schedules the .Dv SIGALRM signal for delivery to the calling process after the given number of .Fa seconds have elapsed. I've also added a CAVEATS section. I've also tweaked the .Nd summary: .Nd schedule SIGALRM delivery Thoughts? 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, +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.
