alarm.3: miscellaneous improvements to alarm(3) documentation

Improve the alarm(3) manpage:

- Better one-line description of the interface.

- Carefully describe what alarm(3) actually does.  In particular, the
  first paragraph of the current DESCRIPTION is misleading in several
  ways.

- Remove mention of the 100 million second limit.  As of kern_time.c v1.154,
  setitimer(2) no longer has this limit on OpenBSD.

- An alarm is "pending" if it has been scheduled but has not yet
  "expired".

- Rewrite RETURN VALUES. Remind the reader that calling alarm(3)
  cancels any pending alarm.  Enumerate all the cases where alarm(3)
  could return zero.

- Remove all descriptions of errors and errno.  With the removal of
  the 100 million second limit, alarm(3) basically cannot fail on
  OpenBSD unless the stack is corrupted.

  Unfortunately, the standard does not prescribe a portable return
  value to report an error to the caller.

- Add a CAVEATS section.  Discourage use of alarm(3) and setitimer(2)'s
  ITIMER_REAL timer in the same program.

With input from millert@, deraadt@, and jmc@.

Thread: https://marc.info/?l=openbsd-tech&m=162403868814857&w=2

ok millert@, jmc@

1 files changed, 34 insertions, 24 deletions

diff --git a/lib/libc/gen/alarm.3 b/lib/libc/gen/alarm.3
index 5dcee7461ac..0b06b46d1f0 100644
--- a/lib/libc/gen/alarm.3
+++ b/lib/libc/gen/alarm.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: alarm.3,v 1.15 2016/01/28 22:11:39 jmc Exp $
+.\"	$OpenBSD: alarm.3,v 1.16 2021/06/18 22:21:29 cheloha Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993, 1994
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,12 +27,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: January 28 2016 $
+.Dd $Mdocdate: June 18 2021 $
 .Dt ALARM 3
 .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,
+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.