From 231f59920aeae8e07e7d5619df14063e128bfc38 Mon Sep 17 00:00:00 2001
From: Kyle Evans <kevans@FreeBSD.org>
Date: Tue, 17 Nov 2020 03:26:56 +0000
Subject: [PATCH] _umtx_op: document UMTX_OP_SEM2_WAIT copyout behavior

This clever technique to get a time remaining back was added to support sem_clockwait_np.

Reviewed by:	kib, vangyzen
MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D27160
---
 lib/libc/sys/_umtx_op.2 | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/lib/libc/sys/_umtx_op.2 b/lib/libc/sys/_umtx_op.2
index 20d75eec74b..547ed313e4a 100644
--- a/lib/libc/sys/_umtx_op.2
+++ b/lib/libc/sys/_umtx_op.2
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 13, 2017
+.Dd November 16, 2020
 .Dt _UMTX_OP 2
 .Os
 .Sh NAME
@@ -1101,6 +1101,15 @@ The arguments to the request are:
 .It Fa obj
 Pointer to the semaphore (of type
 .Vt struct _usem2 ) .
+.It Fa uaddr
+Size of the memory passed in via the
+.Fa uaddr2
+argument.
+.It Fa uaddr2
+Optional pointer to a structure of type
+.Vt struct _umtx_time ,
+which may be followed by a structure of type
+.Vt struct timespec .
 .El
 .Pp
 Put the requesting thread onto a sleep queue if the semaphore counter
@@ -1124,6 +1133,18 @@ An unblocked signal delivered during such wait results in sleep
 interruption and
 .Er EINTR
 error.
+.Pp
+If
+.Dv UMTX_ABSTIME
+was not set, and the operation was interrupted and the caller passed in a
+.Fa uaddr2
+large enough to hold a
+.Vt struct timespec
+following the initial
+.Vt struct _umtx_time ,
+then the
+.Vt struct timespec
+is updated to contain the unslept amount.
 .It Dv UMTX_OP_SEM2_WAKE
 Wake up waiters on semaphore lock.
 The arguments to the request are:
-- 
2.45.0