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

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@