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 -0000 1.15
+++ alarm.3 18 Jun 2021 17:46:08 -0000
@@ -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 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 ,
