sync code with last fixes and improvements from OpenBSD

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
-.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
-.Fa interval
-argument is non-zero, the
+function schedules the
 .Dv SIGALRM
-signal will be sent
-to the process every
+signal for delivery to the calling process after at least the given number of
+.Fa microseconds
+have elapsed.
+If
 .Fa interval
-microseconds after the timer expires (e.g., after
-.Fa microseconds
-number of microseconds have passed).
-.Sh RETURN VALUES
-When the signal has successfully been caught,
+is non-zero,
+the
+.Dv SIGALRM
+signal is scheduled for redelivery to the calling process every
+.Fa interval
+microseconds thereafter.
+.Pp
+If an alarm is already pending,
+an additional call to
 .Fn ualarm
-returns the amount of time left on the clock.
-The maximum value for
+supersedes the prior call.
+.Pp
+If
 .Fa microseconds
-allowed
-is 2147483647.
+is zero,
+any pending alarm is cancelled and the value of
+.Fa interval
+is ignored.
+.Sh RETURN VALUES
+The
+.Fn ualarm
+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.