ualarm.3: cleanups, rewrites

Clean up the ualarm.3 page as we did with the alarm.3 page.

- Be more specific in the Name summary.
- Rewrite the Description.  In particular, ualarm(3) does not block,
  it schedules the signal for asynchronous delivery.
- The Return Values section is incoherent, rewrite it.  Remove the
  incorrect details about the upper bound.
- Add Caveats: discourage use of ualarm(3) and setitimer(2) in the
  same program.

Input on v1 from schwarze@, deraadt@, millert@, and jmc@.  Input on v2
from jmc@ and millert@.

v1: https://marc.info/?l=openbsd-tech&m=162508423008134&w=2
v2: https://marc.info/?l=openbsd-tech&m=169076642509763&w=2

ok jmc@ millert@

diff --git a/lib/libc/gen/ualarm.3 b/lib/libc/gen/ualarm.3
index e76514a..d25eda2 100644 (file)
--- a/lib/libc/gen/ualarm.3
+++ b/lib/libc/gen/ualarm.3
@@ -1,4 +1,4 @@
-.\"    $OpenBSD: ualarm.3,v 1.17 2019/07/26 12:08:18 millert Exp $
+.\"    $OpenBSD: ualarm.3,v 1.18 2023/08/01 01:17:25 cheloha Exp $
 .\"
 .\" Copyright (c) 1986, 1991, 1993
 .\"    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: July 26 2019 $
+.Dd $Mdocdate: August 1 2023 $
 .Dt UALARM 3
 .Os
 .Sh NAME
 .Nm ualarm
-.Nd schedule signal after specified time
+.Nd schedule high resolution SIGALRM delivery
 .Sh SYNOPSIS
 .In unistd.h
 .Ft useconds_t
@@ -45,31 +45,37 @@ This is a simplified interface to
 .Pp
 The
 .Fn ualarm
-function waits a count of
+function schedules the
+.Dv SIGALRM
+signal for delivery to the calling process after at least the given number of
 .Fa microseconds
-before asserting the terminating signal
-.Dv SIGALRM .
-System activity or time used in processing the call may cause a slight
-delay.
-.Pp
-If the
+have elapsed.
+If
 .Fa interval
-argument is non-zero, the
+is non-zero,
+the
 .Dv SIGALRM
-signal will be sent
-to the process every
+signal is scheduled for redelivery to the calling process every
 .Fa interval
-microseconds after the timer expires (e.g., after
+microseconds thereafter.
+.Pp
+If an alarm is already pending,
+an additional call to
+.Fn ualarm
+supersedes the prior call.
+.Pp
+If
 .Fa microseconds
-number of microseconds have passed).
+is zero,
+any pending alarm is cancelled and the value of
+.Fa interval
+is ignored.
 .Sh RETURN VALUES
-When the signal has successfully been caught,
+The
 .Fn ualarm
-returns the amount of time left on the clock.
-The maximum value for
-.Fa microseconds
-allowed
-is 2147483647.
+function returns the number of microseconds remaining until the next
+alarm is scheduled for delivery,
+or zero if no alarm is pending.
 .Sh SEE ALSO
 .Xr setitimer 2 ,
 .Xr sigaction 2 ,
@@ -86,5 +92,17 @@ function conforms to
 .Sh HISTORY
 The
 .Fn ualarm
-function appeared in
+function first appeared in
 .Bx 4.3 .
+.Sh CAVEATS
+The
+.Fn ualarm
+function is implemented with the per-process
+.Dv ITIMER_REAL
+timer described in
+.Xr setitimer 2 .
+Use of both
+.Fn ualarm
+and
+.Xr setitimer 2
+in the same program may yield confusing behavior.