Re: alarm.3: misc. cleanup, rewriting
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 - 1.15 > +++ alarm.3 18 Jun 2021 21:26:23 - > @@ -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 1. > +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.
Re: alarm.3: misc. cleanup, rewriting
On Fri, 18 Jun 2021 16:27:36 -0500, Scott Cheloha wrote: > 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 That looks good to me. - todd
Re: alarm.3: misc. cleanup, rewriting
On Fri, Jun 18, 2021 at 12:46:38PM -0600, Theo de Raadt wrote: > Todd C. Miller 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 - 1.15 +++ alarm.3 18 Jun 2021 21:26:23 - @@ -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 1. +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.
Re: alarm.3: misc. cleanup, rewriting
Todd C. Miller 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)
Re: alarm.3: misc. cleanup, rewriting
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. - todd
Re: alarm.3: misc. cleanup, rewriting
Scott Cheloha 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 , >
alarm.3: misc. cleanup, rewriting
Hi,
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.
- If alarm(3) is not itself "asserting" the signal we need to specify
who the signal is delivered to ("the calling process").
- Use "pending" to refer to an alarm scheduled earlier that hasn't
expired.
- The 100 million second upper bound has been removed from
setitimer(2), no need to mention it anymore.
- Remind the reader in RETURN VALUES that the pending alarm is no
longer scheduled if you call alarm(3) again ("would have expired").
- Be more specific in RETURN VALUES about when it returns zero.
- Outside of a couple edge cases, alarm(3) cannot fail. There isn't
any practical reason for an application to check for them because they
aren't expected unless the process is seriously screwed up.
Thoughts?
I think the .Nd one-line summary is clunky but I'm not sure what to
replace it with.
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 - 1.15
+++ alarm.3 18 Jun 2021 17:46:08 -
@@ -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 1.
+function causes the asynchronous delivery of the
+.Dv SIGALRM
+signal 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 ,
