svn commit: r325905 - stable/11/lib/libc/sys
Eric van Gyzen
vangyzen at FreeBSD.org
Thu Nov 16 21:47:43 UTC 2017
Author: vangyzen
Date: Thu Nov 16 21:47:41 2017
New Revision: 325905
URL: https://svnweb.freebsd.org/changeset/base/325905
Log:
MFC r325766
Fix formatting of _umtx_op(2)
Do not use macros in the -width of a .Bl, since mandoc does not support them.
Fix issues reported by igor and mandoc -Tlint.
Use a .Bl for list of clock IDs instead of a comma list.
Sponsored by: Dell EMC
Modified:
stable/11/lib/libc/sys/_umtx_op.2
Directory Properties:
stable/11/ (props changed)
Modified: stable/11/lib/libc/sys/_umtx_op.2
==============================================================================
--- stable/11/lib/libc/sys/_umtx_op.2 Thu Nov 16 21:45:10 2017 (r325904)
+++ stable/11/lib/libc/sys/_umtx_op.2 Thu Nov 16 21:47:41 2017 (r325905)
@@ -28,7 +28,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd May 23, 2017
+.Dd November 13, 2017
.Dt _UMTX_OP 2
.Os
.Sh NAME
@@ -61,7 +61,7 @@ All objects require ABI-mandated alignment, but this i
enforced consistently on all architectures.
.Pp
The following flags are defined for flag fields of all structures:
-.Bl -tag -width "Dv USYNC_PROCESS_SHARED"
+.Bl -tag -width indent
.It Dv USYNC_PROCESS_SHARED
Allow selection of the process-shared sleep queue for the thread sleep
container, when the lock ownership cannot be granted immediately,
@@ -77,7 +77,6 @@ See the
.Sx SLEEP QUEUES
subsection below for more details on sleep queues.
.El
-.Pp
.Bl -hang -offset indent
.It Sy Mutex
.Bd -literal
@@ -96,7 +95,7 @@ It contains either the thread identifier of the lock o
locked state, or zero when the lock is unowned.
The highest bit set indicates that there is contention on the lock.
The constants are defined for special values:
-.Bl -tag -width "Dv UMUTEX_RB_OWNERDEAD"
+.Bl -tag -width indent
.It Dv UMUTEX_UNOWNED
Zero, the value stored in the unowned lock.
.It Dv UMUTEX_CONTESTED
@@ -113,7 +112,7 @@ The
.Dv m_flags
field may contain the following umutex-specific flags, in addition to
the common flags:
-.Bl -tag -width "Dv UMUTEX_NONCONSISTENT"
+.Bl -tag -width indent
.It Dv UMUTEX_PRIO_INHERIT
Mutex implements
.Em Priority Inheritance
@@ -136,8 +135,9 @@ In the manual page, mutexes not having
and
.Dv UMUTEX_PRIO_PROTECT
flags set, are called normal mutexes.
-Each type of mutex, i.e. normal mutexes, priority-inherited mutexes,
-and priority-protected mutexes, have a separate sleep queue associated
+Each type of mutex
+.Pq normal, priority-inherited, and priority-protected
+has a separate sleep queue associated
with the given key.
.Pp
For priority protected mutexes, the
@@ -182,8 +182,8 @@ request.
The
.Dv c_flags
field contains flags.
-Only the common flags, i.e.
-.Dv USYNC_PROCESS_SHARED ,
+Only the common flags
+.Pq Dv USYNC_PROCESS_SHARED
are defined for ucond.
.Pp
The
@@ -193,23 +193,34 @@ member provides the clock identifier to use for timeou
request has both the
.Dv CVWAIT_CLOCKID
flag and the timeout specified.
-Valid clock identifiers are subset of the valid clock ids for the
-.Xr clock_gettime 2
-syscall, namely,
-.Dv CLOCK_REALTIME ,
-.Dv CLOCK_VIRTUAL ,
-.Dv CLOCK_PROF ,
-.Dv CLOCK_MONOTONIC ,
-.Dv CLOCK_UPTIME ,
-.Dv CLOCK_UPTIME_PRECISE ,
-.Dv CLOCK_UPTIME_FAST ,
-.Dv CLOCK_REALTIME_PRECISE ,
-.Dv CLOCK_REALTIME_FAST ,
-.Dv CLOCK_MONOTONIC_PRECISE ,
-.Dv CLOCK_MONOTONIC_FAST ,
-and
+Valid clock identifiers are a subset of those for
+.Xr clock_gettime 2 :
+.Bl -bullet -compact
+.It
+.Dv CLOCK_MONOTONIC
+.It
+.Dv CLOCK_MONOTONIC_FAST
+.It
+.Dv CLOCK_MONOTONIC_PRECISE
+.It
+.Dv CLOCK_PROF
+.It
+.Dv CLOCK_REALTIME
+.It
+.Dv CLOCK_REALTIME_FAST
+.It
+.Dv CLOCK_REALTIME_PRECISE
+.It
.Dv CLOCK_SECOND
-are allowed.
+.It
+.Dv CLOCK_UPTIME
+.It
+.Dv CLOCK_UPTIME_FAST
+.It
+.Dv CLOCK_UPTIME_PRECISE
+.It
+.Dv CLOCK_VIRTUAL
+.El
.It Sy Reader/writer lock
.Bd -literal
struct urwlock {
@@ -228,7 +239,7 @@ granted.
Names of the
.Dv rw_state
bits are following:
-.Bl -tag -width "Dv URWLOCK_WRITE_WAITERS"
+.Bl -tag -width indent
.It Dv URWLOCK_WRITE_OWNER
Write lock was granted.
.It Dv URWLOCK_WRITE_WAITERS
@@ -253,7 +264,7 @@ The following flags for the
member of
.Vt struct urwlock
are defined, in addition to the common flags:
-.Bl -tag -width "Dv URWLOCK_PREFER_READER"
+.Bl -tag -width indent
.It Dv URWLOCK_PREFER_READER
If specified, immediately grant read lock requests when
.Dv urwlock
@@ -302,7 +313,7 @@ The
.Dv USEM_COUNT()
macro, applied to the
.Dv _count
-word, returns the current semaphore counter, i.e. the number of posts
+word, returns the current semaphore counter, which is the number of posts
issued on the semaphore.
.Pp
The following bits for the
@@ -310,7 +321,7 @@ The following bits for the
member of
.Vt struct _usem2
are defined, in addition to the common flags:
-.Bl -tag -width "Dv USEM_NAMED"
+.Bl -tag -width indent
.It Dv USEM_NAMED
Flag is ignored by kernel.
.El
@@ -359,7 +370,7 @@ Interval counting is always performed by the monotonic
The
.Dv _flags
argument allows the following flags to further define the timeout behaviour:
-.Bl -tag -width "It Dv UMTX_ABSTIME"
+.Bl -tag -width indent
.It Dv UMTX_ABSTIME
The
.Dv _timeout
@@ -374,7 +385,6 @@ start.
.El
.El
.Ss SLEEP QUEUES
-.Pp
When a locking request cannot be immediately satisfied, the thread is
typically put to
.Em sleep ,
@@ -416,7 +426,7 @@ regardless of the kind of backing memory.
.Pp
Only the address of the start byte of the variable specified as key is
important for determining corresponding sleep queue.
-The size of the variable does not matter, so e.g. sleep on the same
+The size of the variable does not matter, so, for example, sleep on the same
address interpeted as
.Vt uint32_t
and
@@ -505,11 +515,11 @@ error for lock attempts, without granting the lock.
The following operations, requested by the
.Fa op
argument to the function, are implemented:
-.Bl -tag -width "It Dv UMTX_OP_WAIT_UINT_PRIVATE"
+.Bl -tag -width indent
.It Dv UMTX_OP_WAIT
Wait.
The arguments for the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to a variable of type
.Vt long .
@@ -558,7 +568,7 @@ Optionally, a timeout for the request may be specified
Wake the threads possibly sleeping due to
.Dv UMTX_OP_WAIT .
The arguments for the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to a variable, used as a key to find sleeping threads.
.It Fa val
@@ -572,7 +582,7 @@ to wake up all waiters.
.It Dv UMTX_OP_MUTEX_TRYLOCK
Try to lock umutex.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@@ -585,7 +595,7 @@ instead of sleeping if the lock cannot be obtained imm
.It Dv UMTX_OP_MUTEX_LOCK
Lock umutex.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@@ -624,7 +634,7 @@ from a signal handler.
.It Dv UMTX_OP_MUTEX_UNLOCK
Unlock umutex.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@@ -661,7 +671,7 @@ priority protected protocol mutex.
.It Dv UMTX_OP_SET_CEILING
Set ceiling for the priority protected umutex.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "uaddr"
.It Fa obj
Pointer to the umutex.
.It Fa val
@@ -696,7 +706,7 @@ interface.
.It Dv UMTX_OP_CV_WAIT
Wait for a condition.
The arguments to the request are:
-.Bl -tag -width "It Fa uaddr2"
+.Bl -tag -width "uaddr2"
.It Fa obj
Pointer to the
.Vt struct ucond .
@@ -743,7 +753,7 @@ After wakeup, the
umutex is not relocked.
.Pp
The following flags are defined:
-.Bl -tag -width "Dv CVWAIT_CLOCKID"
+.Bl -tag -width "CVWAIT_CLOCKID"
.It Dv CVWAIT_ABSTIME
Timeout is absolute.
.It Dv CVWAIT_CLOCKID
@@ -782,7 +792,7 @@ error.
.It Dv UMTX_OP_CV_SIGNAL
Wake up one condition waiter.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to
.Vt struct ucond .
@@ -800,7 +810,7 @@ is cleared.
.It Dv UMTX_OP_CV_BROADCAST
Wake up all condition waiters.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to
.Vt struct ucond .
@@ -820,14 +830,14 @@ Same as
but the type of the variable pointed to by
.Fa obj
is
-.Vt u_int ,
-i.e. 32-bit integer.
+.Vt u_int
+.Pq a 32-bit integer .
.It Dv UMTX_OP_RW_RDLOCK
Read-lock a
.Vt struct rwlock
lock.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the lock (of type
.Vt struct rwlock )
@@ -837,7 +847,7 @@ Additional flags to augment locking behaviour.
The valid flags in the
.Fa val
argument are:
-.Bl -tag -width "It Dv URWLOCK_PREFER_READER"
+.Bl -tag -width indent
.It Dv URWLOCK_PREFER_READER
.El
.El
@@ -889,7 +899,7 @@ Write-lock a
.Vt struct rwlock
lock.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the lock (of type
.Vt struct rwlock )
@@ -925,7 +935,7 @@ error.
.It Dv UMTX_OP_RW_UNLOCK
Unlock rwlock.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the lock (of type
.Vt struct rwlock )
@@ -967,7 +977,7 @@ but unconditionally select the process-private sleep q
.It Dv UMTX_OP_MUTEX_WAIT
Wait for mutex availability.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Address of the mutex.
.El
@@ -991,7 +1001,6 @@ priority inherited protocol mutexes.
.Pp
Optionally, a timeout for the request may be specified.
.Pp
-.Pp
A request with a timeout specified is not restartable.
An unblocked signal delivered during the wait always results in sleep
interruption and
@@ -1007,7 +1016,7 @@ member
.It Dv UMTX_OP_NWAKE_PRIVATE
Wake up a batch of sleeping threads.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the array of pointers.
.It Fa val
@@ -1024,7 +1033,7 @@ being the byte addressed by the array element.
.It Dv UMTX_OP_MUTEX_WAKE
Check if a normal umutex is unlocked and wake up a waiter.
The arguments for the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.El
@@ -1058,7 +1067,7 @@ bit may then modify freed memory.
.It Dv UMTX_OP_MUTEX_WAKE2
Check if a umutex is unlocked and wake up a waiter.
The arguments for the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the umutex.
.It Fa val
@@ -1088,11 +1097,12 @@ word of the
.It Dv UMTX_OP_SEM2_WAIT
Wait until semaphore is available.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the semaphore (of type
.Vt struct _usem2 ) .
.El
+.Pp
Put the requesting thread onto a sleep queue if the semaphore counter
is zero.
If the thread is put to sleep, the
@@ -1117,7 +1127,7 @@ error.
.It Dv UMTX_OP_SEM2_WAKE
Wake up waiters on semaphore lock.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "obj"
.It Fa obj
Pointer to the semaphore (of type
.Vt struct _usem2 ) .
@@ -1145,7 +1155,7 @@ The
argument specifies the sub-request of the
.Dv UMTX_OP_SHM
request:
-.Bl -tag -width "Dv UMTX_SHM_DESTROY"
+.Bl -tag -width indent
.It Dv UMTX_SHM_CREAT
Creates the anonymous shared memory object, which can be looked up
with the specified key
@@ -1191,7 +1201,7 @@ creation or lookup.
.It Dv UMTX_OP_ROBUST_LISTS
Register the list heads for the current thread's robust mutex lists.
The arguments to the request are:
-.Bl -tag -width "It Fa obj"
+.Bl -tag -width "uaddr"
.It Fa val
Size of the structure passed in the
.Fa uaddr
@@ -1261,8 +1271,8 @@ variable is set to indicate the error.
.Sh ERRORS
The
.Fn _umtx_op
-operations will return the following errors:
-.Bl -tag -width "Bq Er ENOTRECOVERABLE"
+operations can fail with the following errors:
+.Bl -tag -width "[ETIMEDOUT]"
.It Bq Er EFAULT
One of the arguments point to invalid memory.
.It Bq Er EINVAL
More information about the svn-src-stable-11
mailing list