lib/libc/sys/_umtx_op.2

   1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This documentation was written by
   5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   6 .\" from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd November 23, 2020
  32 .Dt _UMTX_OP 2
  33 .Os
  34 .Sh NAME
  35 .Nm _umtx_op
  36 .Nd interface for implementation of userspace threading synchronization primitives
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In sys/umtx.h
  42 .Ft int
  43 .Fn _umtx_op "void *obj" "int op" "u_long val" "void *uaddr" "void *uaddr2"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn _umtx_op
  47 system call provides kernel support for userspace implementation of
  48 the threading synchronization primitives.
  49 The
  50 .Lb libthr
  51 uses the syscall to implement
  52 .St -p1003.1-2001
  53 pthread locks, like mutexes, condition variables and so on.
  54 .Ss STRUCTURES
  55 The operations, performed by the
  56 .Fn _umtx_op
  57 syscall, operate on userspace objects which are described
  58 by the following structures.
  59 Reserved fields and paddings are omitted.
  60 All objects require ABI-mandated alignment, but this is not currently
  61 enforced consistently on all architectures.
  62 .Pp
  63 The following flags are defined for flag fields of all structures:
  64 .Bl -tag -width indent
  65 .It Dv USYNC_PROCESS_SHARED
  66 Allow selection of the process-shared sleep queue for the thread sleep
  67 container, when the lock ownership cannot be granted immediately,
  68 and the operation must sleep.
  69 The process-shared or process-private sleep queue is selected based on
  70 the attributes of the memory mapping which contains the first byte of
  71 the structure, see
  72 .Xr mmap 2 .
  73 Otherwise, if the flag is not specified, the process-private sleep queue
  74 is selected regardless of the memory mapping attributes, as an optimization.
  75 .Pp
  76 See the
  77 .Sx SLEEP QUEUES
  78 subsection below for more details on sleep queues.
  79 .El
  80 .Bl -hang -offset indent
  81 .It Sy Mutex
  82 .Bd -literal
  83 struct umutex {
  84         volatile lwpid_t m_owner;
  85         uint32_t         m_flags;
  86         uint32_t         m_ceilings[2];
  87         uintptr_t        m_rb_lnk;
  88 };
  89 .Ed
  90 .Pp
  91 The
  92 .Dv m_owner
  93 field is the actual lock.
  94 It contains either the thread identifier of the lock owner in the
  95 locked state, or zero when the lock is unowned.
  96 The highest bit set indicates that there is contention on the lock.
  97 The constants are defined for special values:
  98 .Bl -tag -width indent
  99 .It Dv UMUTEX_UNOWNED
 100 Zero, the value stored in the unowned lock.
 101 .It Dv UMUTEX_CONTESTED
 102 The contention indicator.
 103 .It Dv UMUTEX_RB_OWNERDEAD
 104 A thread owning the robust mutex terminated.
 105 The mutex is in unlocked state.
 106 .It Dv UMUTEX_RB_NOTRECOV
 107 The robust mutex is in a non-recoverable state.
 108 It cannot be locked until reinitialized.
 109 .El
 110 .Pp
 111 The
 112 .Dv m_flags
 113 field may contain the following umutex-specific flags, in addition to
 114 the common flags:
 115 .Bl -tag -width indent
 116 .It Dv UMUTEX_PRIO_INHERIT
 117 Mutex implements
 118 .Em Priority Inheritance
 119 protocol.
 120 .It Dv UMUTEX_PRIO_PROTECT
 121 Mutex implements
 122 .Em Priority Protection
 123 protocol.
 124 .It Dv UMUTEX_ROBUST
 125 Mutex is robust, as described in the
 126 .Sx ROBUST UMUTEXES
 127 section below.
 128 .It Dv UMUTEX_NONCONSISTENT
 129 Robust mutex is in a transient non-consistent state.
 130 Not used by kernel.
 131 .El
 132 .Pp
 133 In the manual page, mutexes not having
 134 .Dv UMUTEX_PRIO_INHERIT
 135 and
 136 .Dv UMUTEX_PRIO_PROTECT
 137 flags set, are called normal mutexes.
 138 Each type of mutex
 139 .Pq normal, priority-inherited, and priority-protected
 140 has a separate sleep queue associated
 141 with the given key.
 142 .Pp
 143 For priority protected mutexes, the
 144 .Dv m_ceilings
 145 array contains priority ceiling values.
 146 The
 147 .Dv m_ceilings[0]
 148 is the ceiling value for the mutex, as specified by
 149 .St -p1003.1-2008
 150 for the
 151 .Em Priority Protected
 152 mutex protocol.
 153 The
 154 .Dv m_ceilings[1]
 155 is used only for the unlock of a priority protected mutex, when
 156 unlock is done in an order other than the reversed lock order.
 157 In this case,
 158 .Dv m_ceilings[1]
 159 must contain the ceiling value for the last locked priority protected
 160 mutex, for proper priority reassignment.
 161 If, instead, the unlocking mutex was the last priority propagated
 162 mutex locked by the thread,
 163 .Dv m_ceilings[1]
 164 should contain \-1.
 165 This is required because kernel does not maintain the ordered lock list.
 166 .It Sy Condition variable
 167 .Bd -literal
 168 struct ucond {
 169         volatile uint32_t c_has_waiters;
 170         uint32_t          c_flags;
 171         uint32_t          c_clockid;
 172 };
 173 .Ed
 174 .Pp
 175 A non-zero
 176 .Dv c_has_waiters
 177 value indicates that there are in-kernel waiters for the condition,
 178 executing the
 179 .Dv UMTX_OP_CV_WAIT
 180 request.
 181 .Pp
 182 The
 183 .Dv c_flags
 184 field contains flags.
 185 Only the common flags
 186 .Pq Dv USYNC_PROCESS_SHARED
 187 are defined for ucond.
 188 .Pp
 189 The
 190 .Dv c_clockid
 191 member provides the clock identifier to use for timeout, when the
 192 .Dv UMTX_OP_CV_WAIT
 193 request has both the
 194 .Dv CVWAIT_CLOCKID
 195 flag and the timeout specified.
 196 Valid clock identifiers are a subset of those for
 197 .Xr clock_gettime 2 :
 198 .Bl -bullet -compact
 199 .It
 200 .Dv CLOCK_MONOTONIC
 201 .It
 202 .Dv CLOCK_MONOTONIC_FAST
 203 .It
 204 .Dv CLOCK_MONOTONIC_PRECISE
 205 .It
 206 .Dv CLOCK_PROF
 207 .It
 208 .Dv CLOCK_REALTIME
 209 .It
 210 .Dv CLOCK_REALTIME_FAST
 211 .It
 212 .Dv CLOCK_REALTIME_PRECISE
 213 .It
 214 .Dv CLOCK_SECOND
 215 .It
 216 .Dv CLOCK_UPTIME
 217 .It
 218 .Dv CLOCK_UPTIME_FAST
 219 .It
 220 .Dv CLOCK_UPTIME_PRECISE
 221 .It
 222 .Dv CLOCK_VIRTUAL
 223 .El
 224 .It Sy Reader/writer lock
 225 .Bd -literal
 226 struct urwlock {
 227         volatile int32_t rw_state;
 228         uint32_t         rw_flags;
 229         uint32_t         rw_blocked_readers;
 230         uint32_t         rw_blocked_writers;
 231 };
 232 .Ed
 233 .Pp
 234 The
 235 .Dv rw_state
 236 field is the actual lock.
 237 It contains both the flags and counter of the read locks which were
 238 granted.
 239 Names of the
 240 .Dv rw_state
 241 bits are following:
 242 .Bl -tag -width indent
 243 .It Dv URWLOCK_WRITE_OWNER
 244 Write lock was granted.
 245 .It Dv URWLOCK_WRITE_WAITERS
 246 There are write lock waiters.
 247 .It Dv URWLOCK_READ_WAITERS
 248 There are read lock waiters.
 249 .It Dv URWLOCK_READER_COUNT(c)
 250 Returns the count of currently granted read locks.
 251 .El
 252 .Pp
 253 At any given time there may be only one thread to which the writer lock
 254 is granted on the
 255 .Vt struct rwlock ,
 256 and no threads are granted read lock.
 257 Or, at the given time, up to
 258 .Dv URWLOCK_MAX_READERS
 259 threads may be granted the read lock simultaneously, but write lock is
 260 not granted to any thread.
 261 .Pp
 262 The following flags for the
 263 .Dv rw_flags
 264 member of
 265 .Vt struct urwlock
 266 are defined, in addition to the common flags:
 267 .Bl -tag -width indent
 268 .It Dv URWLOCK_PREFER_READER
 269 If specified, immediately grant read lock requests when
 270 .Dv urwlock
 271 is already read-locked, even in presence of unsatisfied write
 272 lock requests.
 273 By default, if there is a write lock waiter, further read requests are
 274 not granted, to prevent unfair write lock waiter starvation.
 275 .El
 276 .Pp
 277 The
 278 .Dv rw_blocked_readers
 279 and
 280 .Dv rw_blocked_writers
 281 members contain the count of threads which are sleeping in kernel,
 282 waiting for the associated request type to be granted.
 283 The fields are used by kernel to update the
 284 .Dv URWLOCK_READ_WAITERS
 285 and
 286 .Dv URWLOCK_WRITE_WAITERS
 287 flags of the
 288 .Dv rw_state
 289 lock after requesting thread was woken up.
 290 .It Sy Semaphore
 291 .Bd -literal
 292 struct _usem2 {
 293         volatile uint32_t _count;
 294         uint32_t          _flags;
 295 };
 296 .Ed
 297 .Pp
 298 The
 299 .Dv _count
 300 word represents a counting semaphore.
 301 A non-zero value indicates an unlocked (posted) semaphore, while zero
 302 represents the locked state.
 303 The maximal supported semaphore count is
 304 .Dv USEM_MAX_COUNT .
 305 .Pp
 306 The
 307 .Dv _count
 308 word, besides the counter of posts (unlocks), also contains the
 309 .Dv USEM_HAS_WAITERS
 310 bit, which indicates that locked semaphore has waiting threads.
 311 .Pp
 312 The
 313 .Dv USEM_COUNT()
 314 macro, applied to the
 315 .Dv _count
 316 word, returns the current semaphore counter, which is the number of posts
 317 issued on the semaphore.
 318 .Pp
 319 The following bits for the
 320 .Dv _flags
 321 member of
 322 .Vt struct _usem2
 323 are defined, in addition to the common flags:
 324 .Bl -tag -width indent
 325 .It Dv USEM_NAMED
 326 Flag is ignored by kernel.
 327 .El
 328 .It Sy Timeout parameter
 329 .Bd -literal
 330 struct _umtx_time {
 331         struct timespec _timeout;
 332         uint32_t        _flags;
 333         uint32_t        _clockid;
 334 };
 335 .Ed
 336 .Pp
 337 Several
 338 .Fn _umtx_op
 339 operations allow the blocking time to be limited, failing the request
 340 if it cannot be satisfied in the specified time period.
 341 The timeout is specified by passing either the address of
 342 .Vt struct timespec ,
 343 or its extended variant,
 344 .Vt struct _umtx_time ,
 345 as the
 346 .Fa uaddr2
 347 argument of
 348 .Fn _umtx_op .
 349 They are distinguished by the
 350 .Fa uaddr
 351 value, which must be equal to the size of the structure pointed to by
 352 .Fa uaddr2 ,
 353 casted to
 354 .Vt uintptr_t .
 355 .Pp
 356 The
 357 .Dv _timeout
 358 member specifies the time when the timeout should occur.
 359 Legal values for clock identifier
 360 .Dv _clockid
 361 are shared with the
 362 .Fa clock_id
 363 argument to the
 364 .Xr clock_gettime 2
 365 function,
 366 and use the same underlying clocks.
 367 The specified clock is used to obtain the current time value.
 368 Interval counting is always performed by the monotonic wall clock.
 369 .Pp
 370 The
 371 .Dv _flags
 372 argument allows the following flags to further define the timeout behaviour:
 373 .Bl -tag -width indent
 374 .It Dv UMTX_ABSTIME
 375 The
 376 .Dv _timeout
 377 value is the absolute time.
 378 The thread will be unblocked and the request failed when specified
 379 clock value is equal or exceeds the
 380 .Dv _timeout.
 381 .Pp
 382 If the flag is absent, the timeout value is relative, that is the amount
 383 of time, measured by the monotonic wall clock from the moment of the request
 384 start.
 385 .El
 386 .El
 387 .Ss SLEEP QUEUES
 388 When a locking request cannot be immediately satisfied, the thread is
 389 typically put to
 390 .Em sleep ,
 391 which is a non-runnable state terminated by the
 392 .Em wake
 393 operation.
 394 Lock operations include a
 395 .Em try
 396 variant which returns an error rather than sleeping if the lock cannot
 397 be obtained.
 398 Also,
 399 .Fn _umtx_op
 400 provides requests which explicitly put the thread to sleep.
 401 .Pp
 402 Wakes need to know which threads to make runnable, so sleeping threads
 403 are grouped into containers called
 404 .Em sleep queues .
 405 A sleep queue is identified by a key, which for
 406 .Fn _umtx_op
 407 is defined as the physical address of some variable.
 408 Note that the
 409 .Em physical
 410 address is used, which means that same variable mapped multiple
 411 times will give one key value.
 412 This mechanism enables the construction of
 413 .Em process-shared
 414 locks.
 415 .Pp
 416 A related attribute of the key is shareability.
 417 Some requests always interpret keys as private for the current process,
 418 creating sleep queues with the scope of the current process even if
 419 the memory is shared.
 420 Others either select the shareability automatically from the
 421 mapping attributes, or take additional input as the
 422 .Dv USYNC_PROCESS_SHARED
 423 common flag.
 424 This is done as optimization, allowing the lock scope to be limited
 425 regardless of the kind of backing memory.
 426 .Pp
 427 Only the address of the start byte of the variable specified as key is
 428 important for determining corresponding sleep queue.
 429 The size of the variable does not matter, so, for example, sleep on the same
 430 address interpeted as
 431 .Vt uint32_t
 432 and
 433 .Vt long
 434 on a little-endian 64-bit platform would collide.
 435 .Pp
 436 The last attribute of the key is the object type.
 437 The sleep queue to which a sleeping thread is assigned is an individual
 438 one for simple wait requests, mutexes, rwlocks, condvars and other
 439 primitives, even when the physical address of the key is same.
 440 .Pp
 441 When waking up a limited number of threads from a given sleep queue,
 442 the highest priority threads that have been blocked for the longest on
 443 the queue are selected.
 444 .Ss ROBUST UMUTEXES
 445 The
 446 .Em robust umutexes
 447 are provided as a substrate for a userspace library to implement
 448 .Tn POSIX
 449 robust mutexes.
 450 A robust umutex must have the
 451 .Dv UMUTEX_ROBUST
 452 flag set.
 453 .Pp
 454 On thread termination, the kernel walks two lists of mutexes.
 455 The two lists head addresses must be provided by a prior call to
 456 .Dv UMTX_OP_ROBUST_LISTS
 457 request.
 458 The lists are singly-linked.
 459 The link to next element is provided by the
 460 .Dv m_rb_lnk
 461 member of the
 462 .Vt struct umutex .
 463 .Pp
 464 Robust list processing is aborted if the kernel finds a mutex
 465 with any of the following conditions:
 466 .Bl -dash -offset indent -compact
 467 .It
 468 the
 469 .Dv UMUTEX_ROBUST
 470 flag is not set
 471 .It
 472 not owned by the current thread, except when the mutex is pointed to
 473 by the
 474 .Dv robust_inactive
 475 member of the
 476 .Vt struct umtx_robust_lists_params ,
 477 registered for the current thread
 478 .It
 479 the combination of mutex flags is invalid
 480 .It
 481 read of the umutex memory faults
 482 .It
 483 the list length limit described in
 484 .Xr libthr 3
 485 is reached.
 486 .El
 487 .Pp
 488 Every mutex in both lists is unlocked as if the
 489 .Dv UMTX_OP_MUTEX_UNLOCK
 490 request is performed on it, but instead of the
 491 .Dv UMUTEX_UNOWNED
 492 value, the
 493 .Dv m_owner
 494 field is written with the
 495 .Dv UMUTEX_RB_OWNERDEAD
 496 value.
 497 When a mutex in the
 498 .Dv UMUTEX_RB_OWNERDEAD
 499 state is locked by kernel due to the
 500 .Dv UMTX_OP_MUTEX_TRYLOCK
 501 and
 502 .Dv UMTX_OP_MUTEX_LOCK
 503 requests, the lock is granted and
 504 .Er EOWNERDEAD
 505 error is returned.
 506 .Pp
 507 Also, the kernel handles the
 508 .Dv UMUTEX_RB_NOTRECOV
 509 value of
 510 .Dv the m_owner
 511 field specially, always returning the
 512 .Er ENOTRECOVERABLE
 513 error for lock attempts, without granting the lock.
 514 .Ss OPERATIONS
 515 The following operations, requested by the
 516 .Fa op
 517 argument to the function, are implemented:
 518 .Bl -tag -width indent
 519 .It Dv UMTX_OP_WAIT
 520 Wait.
 521 The arguments for the request are:
 522 .Bl -tag -width "obj"
 523 .It Fa obj
 524 Pointer to a variable of type
 525 .Vt long .
 526 .It Fa val
 527 Current value of the
 528 .Dv *obj .
 529 .El
 530 .Pp
 531 The current value of the variable pointed to by the
 532 .Fa obj
 533 argument is compared with the
 534 .Fa val .
 535 If they are equal, the requesting thread is put to interruptible sleep
 536 until woken up or the optionally specified timeout expires.
 537 .Pp
 538 The comparison and sleep are atomic.
 539 In other words, if another thread writes a new value to
 540 .Dv *obj
 541 and then issues
 542 .Dv UMTX_OP_WAKE ,
 543 the request is guaranteed to not miss the wakeup,
 544 which might otherwise happen between comparison and blocking.
 545 .Pp
 546 The physical address of memory where the
 547 .Fa *obj
 548 variable is located, is used as a key to index sleeping threads.
 549 .Pp
 550 The read of the current value of the
 551 .Dv *obj
 552 variable is not guarded by barriers.
 553 In particular, it is the user's duty to ensure the lock acquire
 554 and release memory semantics, if the
 555 .Dv UMTX_OP_WAIT
 556 and
 557 .Dv UMTX_OP_WAKE
 558 requests are used as a substrate for implementing a simple lock.
 559 .Pp
 560 The request is not restartable.
 561 An unblocked signal delivered during the wait always results in sleep
 562 interruption and
 563 .Er EINTR
 564 error.
 565 .Pp
 566 Optionally, a timeout for the request may be specified.
 567 .It Dv UMTX_OP_WAKE
 568 Wake the threads possibly sleeping due to
 569 .Dv UMTX_OP_WAIT .
 570 The arguments for the request are:
 571 .Bl -tag -width "obj"
 572 .It Fa obj
 573 Pointer to a variable, used as a key to find sleeping threads.
 574 .It Fa val
 575 Up to
 576 .Fa val
 577 threads are woken up by this request.
 578 Specify
 579 .Dv INT_MAX
 580 to wake up all waiters.
 581 .El
 582 .It Dv UMTX_OP_MUTEX_TRYLOCK
 583 Try to lock umutex.
 584 The arguments to the request are:
 585 .Bl -tag -width "obj"
 586 .It Fa obj
 587 Pointer to the umutex.
 588 .El
 589 .Pp
 590 Operates same as the
 591 .Dv UMTX_OP_MUTEX_LOCK
 592 request, but returns
 593 .Er EBUSY
 594 instead of sleeping if the lock cannot be obtained immediately.
 595 .It Dv UMTX_OP_MUTEX_LOCK
 596 Lock umutex.
 597 The arguments to the request are:
 598 .Bl -tag -width "obj"
 599 .It Fa obj
 600 Pointer to the umutex.
 601 .El
 602 .Pp
 603 Locking is performed by writing the current thread id into the
 604 .Dv m_owner
 605 word of the
 606 .Vt struct umutex .
 607 The write is atomic, preserves the
 608 .Dv UMUTEX_CONTESTED
 609 contention indicator, and provides the acquire barrier for
 610 lock entrance semantic.
 611 .Pp
 612 If the lock cannot be obtained immediately because another thread owns
 613 the lock, the current thread is put to sleep, with
 614 .Dv UMUTEX_CONTESTED
 615 bit set before.
 616 Upon wake up, the lock conditions are re-tested.
 617 .Pp
 618 The request adheres to the priority protection or inheritance protocol
 619 of the mutex, specified by the
 620 .Dv UMUTEX_PRIO_PROTECT
 621 or
 622 .Dv UMUTEX_PRIO_INHERIT
 623 flag, respectively.
 624 .Pp
 625 Optionally, a timeout for the request may be specified.
 626 .Pp
 627 A request with a timeout specified is not restartable.
 628 An unblocked signal delivered during the wait always results in sleep
 629 interruption and
 630 .Er EINTR
 631 error.
 632 A request without timeout specified is always restarted after return
 633 from a signal handler.
 634 .It Dv UMTX_OP_MUTEX_UNLOCK
 635 Unlock umutex.
 636 The arguments to the request are:
 637 .Bl -tag -width "obj"
 638 .It Fa obj
 639 Pointer to the umutex.
 640 .El
 641 .Pp
 642 Unlocks the mutex, by writing
 643 .Dv UMUTEX_UNOWNED
 644 (zero) value into
 645 .Dv m_owner
 646 word of the
 647 .Vt struct umutex .
 648 The write is done with a release barrier, to provide lock leave semantic.
 649 .Pp
 650 If there are threads sleeping in the sleep queue associated with the
 651 umutex, one thread is woken up.
 652 If more than one thread sleeps in the sleep queue, the
 653 .Dv UMUTEX_CONTESTED
 654 bit is set together with the write of the
 655 .Dv UMUTEX_UNOWNED
 656 value into
 657 .Dv m_owner .
 658 .Pp
 659 The request adheres to the priority protection or inheritance protocol
 660 of the mutex, specified by the
 661 .Dv UMUTEX_PRIO_PROTECT
 662 or
 663 .Dv UMUTEX_PRIO_INHERIT
 664 flag, respectively.
 665 See description of the
 666 .Dv m_ceilings
 667 member of the
 668 .Vt struct umutex
 669 structure for additional details of the request operation on the
 670 priority protected protocol mutex.
 671 .It Dv UMTX_OP_SET_CEILING
 672 Set ceiling for the priority protected umutex.
 673 The arguments to the request are:
 674 .Bl -tag -width "uaddr"
 675 .It Fa obj
 676 Pointer to the umutex.
 677 .It Fa val
 678 New ceiling value.
 679 .It Fa uaddr
 680 Address of a variable of type
 681 .Vt uint32_t .
 682 If not
 683 .Dv NULL
 684 and the update was successful, the previous ceiling value is
 685 written to the location pointed to by
 686 .Fa uaddr .
 687 .El
 688 .Pp
 689 The request locks the umutex pointed to by the
 690 .Fa obj
 691 parameter, waiting for the lock if not immediately available.
 692 After the lock is obtained, the new ceiling value
 693 .Fa val
 694 is written to the
 695 .Dv m_ceilings[0]
 696 member of the
 697 .Vt struct umutex,
 698 after which the umutex is unlocked.
 699 .Pp
 700 The locking does not adhere to the priority protect protocol,
 701 to conform to the
 702 .Tn POSIX
 703 requirements for the
 704 .Xr pthread_mutex_setprioceiling 3
 705 interface.
 706 .It Dv UMTX_OP_CV_WAIT
 707 Wait for a condition.
 708 The arguments to the request are:
 709 .Bl -tag -width "uaddr2"
 710 .It Fa obj
 711 Pointer to the
 712 .Vt struct ucond .
 713 .It Fa val
 714 Request flags, see below.
 715 .It Fa uaddr
 716 Pointer to the umutex.
 717 .It Fa uaddr2
 718 Optional pointer to a
 719 .Vt struct timespec
 720 for timeout specification.
 721 .El
 722 .Pp
 723 The request must be issued by the thread owning the mutex pointed to
 724 by the
 725 .Fa uaddr
 726 argument.
 727 The
 728 .Dv c_hash_waiters
 729 member of the
 730 .Vt struct ucond ,
 731 pointed to by the
 732 .Fa obj
 733 argument, is set to an arbitrary non-zero value, after which the
 734 .Fa uaddr
 735 mutex is unlocked (following the appropriate protocol), and
 736 the current thread is put to sleep on the sleep queue keyed by
 737 the
 738 .Fa obj
 739 argument.
 740 The operations are performed atomically.
 741 It is guaranteed to not miss a wakeup from
 742 .Dv UMTX_OP_CV_SIGNAL
 743 or
 744 .Dv UMTX_OP_CV_BROADCAST
 745 sent between mutex unlock and putting the current thread on the sleep queue.
 746 .Pp
 747 Upon wakeup, if the timeout expired and no other threads are sleeping in
 748 the same sleep queue, the
 749 .Dv c_hash_waiters
 750 member is cleared.
 751 After wakeup, the
 752 .Fa uaddr
 753 umutex is not relocked.
 754 .Pp
 755 The following flags are defined:
 756 .Bl -tag -width "CVWAIT_CLOCKID"
 757 .It Dv CVWAIT_ABSTIME
 758 Timeout is absolute.
 759 .It Dv CVWAIT_CLOCKID
 760 Clockid is provided.
 761 .El
 762 .Pp
 763 Optionally, a timeout for the request may be specified.
 764 Unlike other requests, the timeout value is specified directly by a
 765 .Vt struct timespec ,
 766 pointed to by the
 767 .Fa uaddr2
 768 argument.
 769 If the
 770 .Dv CVWAIT_CLOCKID
 771 flag is provided, the timeout uses the clock from the
 772 .Dv c_clockid
 773 member of the
 774 .Vt struct ucond ,
 775 pointed to by
 776 .Fa obj
 777 argument.
 778 Otherwise,
 779 .Dv CLOCK_REALTIME
 780 is used, regardless of the clock identifier possibly specified in the
 781 .Vt struct _umtx_time .
 782 If the
 783 .Dv CVWAIT_ABSTIME
 784 flag is supplied, the timeout specifies absolute time value, otherwise
 785 it denotes a relative time interval.
 786 .Pp
 787 The request is not restartable.
 788 An unblocked signal delivered during
 789 the wait always results in sleep interruption and
 790 .Er EINTR
 791 error.
 792 .It Dv UMTX_OP_CV_SIGNAL
 793 Wake up one condition waiter.
 794 The arguments to the request are:
 795 .Bl -tag -width "obj"
 796 .It Fa obj
 797 Pointer to
 798 .Vt struct ucond .
 799 .El
 800 .Pp
 801 The request wakes up at most one thread sleeping on the sleep queue keyed
 802 by the
 803 .Fa obj
 804 argument.
 805 If the woken up thread was the last on the sleep queue, the
 806 .Dv c_has_waiters
 807 member of the
 808 .Vt struct ucond
 809 is cleared.
 810 .It Dv UMTX_OP_CV_BROADCAST
 811 Wake up all condition waiters.
 812 The arguments to the request are:
 813 .Bl -tag -width "obj"
 814 .It Fa obj
 815 Pointer to
 816 .Vt struct ucond .
 817 .El
 818 .Pp
 819 The request wakes up all threads sleeping on the sleep queue keyed by the
 820 .Fa obj
 821 argument.
 822 The
 823 .Dv c_has_waiters
 824 member of the
 825 .Vt struct ucond
 826 is cleared.
 827 .It Dv UMTX_OP_WAIT_UINT
 828 Same as
 829 .Dv UMTX_OP_WAIT ,
 830 but the type of the variable pointed to by
 831 .Fa obj
 832 is
 833 .Vt u_int
 834 .Pq a 32-bit integer .
 835 .It Dv UMTX_OP_RW_RDLOCK
 836 Read-lock a
 837 .Vt struct rwlock
 838 lock.
 839 The arguments to the request are:
 840 .Bl -tag -width "obj"
 841 .It Fa obj
 842 Pointer to the lock (of type
 843 .Vt struct rwlock )
 844 to be read-locked.
 845 .It Fa val
 846 Additional flags to augment locking behaviour.
 847 The valid flags in the
 848 .Fa val
 849 argument are:
 850 .Bl -tag -width indent
 851 .It Dv URWLOCK_PREFER_READER
 852 .El
 853 .El
 854 .Pp
 855 The request obtains the read lock on the specified
 856 .Vt struct rwlock
 857 by incrementing the count of readers in the
 858 .Dv rw_state
 859 word of the structure.
 860 If the
 861 .Dv URWLOCK_WRITE_OWNER
 862 bit is set in the word
 863 .Dv rw_state ,
 864 the lock was granted to a writer which has not yet relinquished
 865 its ownership.
 866 In this case the current thread is put to sleep until it makes sense to
 867 retry.
 868 .Pp
 869 If the
 870 .Dv URWLOCK_PREFER_READER
 871 flag is set either in the
 872 .Dv rw_flags
 873 word of the structure, or in the
 874 .Fa val
 875 argument of the request, the presence of the threads trying to obtain
 876 the write lock on the same structure does not prevent the current thread
 877 from trying to obtain the read lock.
 878 Otherwise, if the flag is not set, and the
 879 .Dv URWLOCK_WRITE_WAITERS
 880 flag is set in
 881 .Dv rw_state ,
 882 the current thread does not attempt to obtain read-lock.
 883 Instead it sets the
 884 .Dv URWLOCK_READ_WAITERS
 885 in the
 886 .Dv rw_state
 887 word and puts itself to sleep on corresponding sleep queue.
 888 Upon wakeup, the locking conditions are re-evaluated.
 889 .Pp
 890 Optionally, a timeout for the request may be specified.
 891 .Pp
 892 The request is not restartable.
 893 An unblocked signal delivered during the wait always results in sleep
 894 interruption and
 895 .Er EINTR
 896 error.
 897 .It Dv UMTX_OP_RW_WRLOCK
 898 Write-lock a
 899 .Vt struct rwlock
 900 lock.
 901 The arguments to the request are:
 902 .Bl -tag -width "obj"
 903 .It Fa obj
 904 Pointer to the lock (of type
 905 .Vt struct rwlock )
 906 to be write-locked.
 907 .El
 908 .Pp
 909 The request obtains a write lock on the specified
 910 .Vt struct rwlock ,
 911 by setting the
 912 .Dv URWLOCK_WRITE_OWNER
 913 bit in the
 914 .Dv rw_state
 915 word of the structure.
 916 If there is already a write lock owner, as indicated by the
 917 .Dv URWLOCK_WRITE_OWNER
 918 bit being set, or there are read lock owners, as indicated
 919 by the read-lock counter, the current thread does not attempt to
 920 obtain the write-lock.
 921 Instead it sets the
 922 .Dv URWLOCK_WRITE_WAITERS
 923 in the
 924 .Dv rw_state
 925 word and puts itself to sleep on corresponding sleep queue.
 926 Upon wakeup, the locking conditions are re-evaluated.
 927 .Pp
 928 Optionally, a timeout for the request may be specified.
 929 .Pp
 930 The request is not restartable.
 931 An unblocked signal delivered during the wait always results in sleep
 932 interruption and
 933 .Er EINTR
 934 error.
 935 .It Dv UMTX_OP_RW_UNLOCK
 936 Unlock rwlock.
 937 The arguments to the request are:
 938 .Bl -tag -width "obj"
 939 .It Fa obj
 940 Pointer to the lock (of type
 941 .Vt struct rwlock )
 942 to be unlocked.
 943 .El
 944 .Pp
 945 The unlock type (read or write) is determined by the
 946 current lock state.
 947 Note that the
 948 .Vt struct rwlock
 949 does not save information about the identity of the thread which
 950 acquired the lock.
 951 .Pp
 952 If there are pending writers after the unlock, and the
 953 .Dv URWLOCK_PREFER_READER
 954 flag is not set in the
 955 .Dv rw_flags
 956 member of the
 957 .Fa *obj
 958 structure, one writer is woken up, selected as described in the
 959 .Sx SLEEP QUEUES
 960 subsection.
 961 If the
 962 .Dv URWLOCK_PREFER_READER
 963 flag is set, a pending writer is woken up only if there is
 964 no pending readers.
 965 .Pp
 966 If there are no pending writers, or, in the case that the
 967 .Dv URWLOCK_PREFER_READER
 968 flag is set, then all pending readers are woken up by unlock.
 969 .It Dv UMTX_OP_WAIT_UINT_PRIVATE
 970 Same as
 971 .Dv UMTX_OP_WAIT_UINT ,
 972 but unconditionally select the process-private sleep queue.
 973 .It Dv UMTX_OP_WAKE_PRIVATE
 974 Same as
 975 .Dv UMTX_OP_WAKE ,
 976 but unconditionally select the process-private sleep queue.
 977 .It Dv UMTX_OP_MUTEX_WAIT
 978 Wait for mutex availability.
 979 The arguments to the request are:
 980 .Bl -tag -width "obj"
 981 .It Fa obj
 982 Address of the mutex.
 983 .El
 984 .Pp
 985 Similarly to the
 986 .Dv UMTX_OP_MUTEX_LOCK ,
 987 put the requesting thread to sleep if the mutex lock cannot be obtained
 988 immediately.
 989 The
 990 .Dv UMUTEX_CONTESTED
 991 bit is set in the
 992 .Dv m_owner
 993 word of the mutex to indicate that there is a waiter, before the thread
 994 is added to the sleep queue.
 995 Unlike the
 996 .Dv UMTX_OP_MUTEX_LOCK
 997 request, the lock is not obtained.
 998 .Pp
 999 The operation is not implemented for priority protected and
1000 priority inherited protocol mutexes.
1001 .Pp
1002 Optionally, a timeout for the request may be specified.
1003 .Pp
1004 A request with a timeout specified is not restartable.
1005 An unblocked signal delivered during the wait always results in sleep
1006 interruption and
1007 .Er EINTR
1008 error.
1009 A request without a timeout automatically restarts if the signal disposition
1010 requested restart via the
1011 .Dv SA_RESTART
1012 flag in
1013 .Vt struct sigaction
1014 member
1015 .Dv sa_flags .
1016 .It Dv UMTX_OP_NWAKE_PRIVATE
1017 Wake up a batch of sleeping threads.
1018 The arguments to the request are:
1019 .Bl -tag -width "obj"
1020 .It Fa obj
1021 Pointer to the array of pointers.
1022 .It Fa val
1023 Number of elements in the array pointed to by
1024 .Fa obj .
1025 .El
1026 .Pp
1027 For each element in the array pointed to by
1028 .Fa obj ,
1029 wakes up all threads waiting on the
1030 .Em private
1031 sleep queue with the key
1032 being the byte addressed by the array element.
1033 .It Dv UMTX_OP_MUTEX_WAKE
1034 Check if a normal umutex is unlocked and wake up a waiter.
1035 The arguments for the request are:
1036 .Bl -tag -width "obj"
1037 .It Fa obj
1038 Pointer to the umutex.
1039 .El
1040 .Pp
1041 If the
1042 .Dv m_owner
1043 word of the mutex pointed to by the
1044 .Fa obj
1045 argument indicates unowned mutex, which has its contention indicator bit
1046 .Dv UMUTEX_CONTESTED
1047 set, clear the bit and wake up one waiter in the sleep queue associated
1048 with the byte addressed by the
1049 .Fa obj ,
1050 if any.
1051 Only normal mutexes are supported by the request.
1052 The sleep queue is always one for a normal mutex type.
1053 .Pp
1054 This request is deprecated in favor of
1055 .Dv UMTX_OP_MUTEX_WAKE2
1056 since mutexes using it cannot synchronize their own destruction.
1057 That is, the
1058 .Dv m_owner
1059 word has already been set to
1060 .Dv UMUTEX_UNOWNED
1061 when this request is made,
1062 so that another thread can lock, unlock and destroy the mutex
1063 (if no other thread uses the mutex afterwards).
1064 Clearing the
1065 .Dv UMUTEX_CONTESTED
1066 bit may then modify freed memory.
1067 .It Dv UMTX_OP_MUTEX_WAKE2
1068 Check if a umutex is unlocked and wake up a waiter.
1069 The arguments for the request are:
1070 .Bl -tag -width "obj"
1071 .It Fa obj
1072 Pointer to the umutex.
1073 .It Fa val
1074 The umutex flags.
1075 .El
1076 .Pp
1077 The request does not read the
1078 .Dv m_flags
1079 member of the
1080 .Vt struct umutex ;
1081 instead, the
1082 .Fa val
1083 argument supplies flag information, in particular, to determine the
1084 sleep queue where the waiters are found for wake up.
1085 .Pp
1086 If the mutex is unowned, one waiter is woken up.
1087 .Pp
1088 If the mutex memory cannot be accessed, all waiters are woken up.
1089 .Pp
1090 If there is more than one waiter on the sleep queue, or there is only
1091 one waiter but the mutex is owned by a thread, the
1092 .Dv UMUTEX_CONTESTED
1093 bit is set in the
1094 .Dv m_owner
1095 word of the
1096 .Vt struct umutex .
1097 .It Dv UMTX_OP_SEM2_WAIT
1098 Wait until semaphore is available.
1099 The arguments to the request are:
1100 .Bl -tag -width "obj"
1101 .It Fa obj
1102 Pointer to the semaphore (of type
1103 .Vt struct _usem2 ) .
1104 .It Fa uaddr
1105 Size of the memory passed in via the
1106 .Fa uaddr2
1107 argument.
1108 .It Fa uaddr2
1109 Optional pointer to a structure of type
1110 .Vt struct _umtx_time ,
1111 which may be followed by a structure of type
1112 .Vt struct timespec .
1113 .El
1114 .Pp
1115 Put the requesting thread onto a sleep queue if the semaphore counter
1116 is zero.
1117 If the thread is put to sleep, the
1118 .Dv USEM_HAS_WAITERS
1119 bit is set in the
1120 .Dv _count
1121 word to indicate waiters.
1122 The function returns either due to
1123 .Dv _count
1124 indicating the semaphore is available (non-zero count due to post),
1125 or due to a wakeup.
1126 The return does not guarantee that the semaphore is available,
1127 nor does it consume the semaphore lock on successful return.
1128 .Pp
1129 Optionally, a timeout for the request may be specified.
1130 .Pp
1131 A request with non-absolute timeout value is not restartable.
1132 An unblocked signal delivered during such wait results in sleep
1133 interruption and
1134 .Er EINTR
1135 error.
1136 .Pp
1137 If
1138 .Dv UMTX_ABSTIME
1139 was not set, and the operation was interrupted and the caller passed in a
1140 .Fa uaddr2
1141 large enough to hold a
1142 .Vt struct timespec
1143 following the initial
1144 .Vt struct _umtx_time ,
1145 then the
1146 .Vt struct timespec
1147 is updated to contain the unslept amount.
1148 .It Dv UMTX_OP_SEM2_WAKE
1149 Wake up waiters on semaphore lock.
1150 The arguments to the request are:
1151 .Bl -tag -width "obj"
1152 .It Fa obj
1153 Pointer to the semaphore (of type
1154 .Vt struct _usem2 ) .
1155 .El
1156 .Pp
1157 The request wakes up one waiter for the semaphore lock.
1158 The function does not increment the semaphore lock count.
1159 If the
1160 .Dv USEM_HAS_WAITERS
1161 bit was set in the
1162 .Dv _count
1163 word, and the last sleeping thread was woken up, the bit is cleared.
1164 .It Dv UMTX_OP_SHM
1165 Manage anonymous
1166 .Tn POSIX
1167 shared memory objects (see
1168 .Xr shm_open 2 ) ,
1169 which can be attached to a byte of physical memory, mapped into the
1170 process address space.
1171 The objects are used to implement process-shared locks in
1172 .Dv libthr .
1173 .Pp
1174 The
1175 .Fa val
1176 argument specifies the sub-request of the
1177 .Dv UMTX_OP_SHM
1178 request:
1179 .Bl -tag -width indent
1180 .It Dv UMTX_SHM_CREAT
1181 Creates the anonymous shared memory object, which can be looked up
1182 with the specified key
1183 .Fa uaddr .
1184 If the object associated with the
1185 .Fa uaddr
1186 key already exists, it is returned instead of creating a new object.
1187 The object's size is one page.
1188 On success, the file descriptor referencing the object is returned.
1189 The descriptor can be used for mapping the object using
1190 .Xr mmap 2 ,
1191 or for other shared memory operations.
1192 .It Dv UMTX_SHM_LOOKUP
1193 Same as
1194 .Dv UMTX_SHM_CREATE
1195 request, but if there is no shared memory object associated with
1196 the specified key
1197 .Fa uaddr ,
1198 an error is returned, and no new object is created.
1199 .It Dv UMTX_SHM_DESTROY
1200 De-associate the shared object with the specified key
1201 .Fa uaddr .
1202 The object is destroyed after the last open file descriptor is closed
1203 and the last mapping for it is destroyed.
1204 .It Dv UMTX_SHM_ALIVE
1205 Checks whether there is a live shared object associated with the
1206 supplied key
1207 .Fa uaddr .
1208 Returns zero if there is, and an error otherwise.
1209 This request is an optimization of the
1210 .Dv UMTX_SHM_LOOKUP
1211 request.
1212 It is cheaper when only the liveness of the associated object is asked
1213 for, since no file descriptor is installed in the process fd table
1214 on success.
1215 .El
1216 .Pp
1217 The
1218 .Fa uaddr
1219 argument specifies the virtual address, which backing physical memory
1220 byte identity is used as a key for the anonymous shared object
1221 creation or lookup.
1222 .It Dv UMTX_OP_ROBUST_LISTS
1223 Register the list heads for the current thread's robust mutex lists.
1224 The arguments to the request are:
1225 .Bl -tag -width "uaddr"
1226 .It Fa val
1227 Size of the structure passed in the
1228 .Fa uaddr
1229 argument.
1230 .It Fa uaddr
1231 Pointer to the structure of type
1232 .Vt struct umtx_robust_lists_params .
1233 .El
1234 .Pp
1235 The structure is defined as
1236 .Bd -literal
1237 struct umtx_robust_lists_params {
1238         uintptr_t       robust_list_offset;
1239         uintptr_t       robust_priv_list_offset;
1240         uintptr_t       robust_inact_offset;
1241 };
1242 .Ed
1243 .Pp
1244 The
1245 .Dv robust_list_offset
1246 member contains address of the first element in the list of locked
1247 robust shared mutexes.
1248 The
1249 .Dv robust_priv_list_offset
1250 member contains address of the first element in the list of locked
1251 robust private mutexes.
1252 The private and shared robust locked lists are split to allow fast
1253 termination of the shared list on fork, in the child.
1254 .Pp
1255 The
1256 .Dv robust_inact_offset
1257 contains a pointer to the mutex which might be locked in nearby future,
1258 or might have been just unlocked.
1259 It is typically set by the lock or unlock mutex implementation code
1260 around the whole operation, since lists can be only changed race-free
1261 when the thread owns the mutex.
1262 The kernel inspects the
1263 .Dv robust_inact_offset
1264 in addition to walking the shared and private lists.
1265 Also, the mutex pointed to by
1266 .Dv robust_inact_offset
1267 is handled more loosely at the thread termination time,
1268 than other mutexes on the list.
1269 That mutex is allowed to be not owned by the current thread,
1270 in which case list processing is continued.
1271 See
1272 .Sx ROBUST UMUTEXES
1273 subsection for details.
1274 .El
1275 .Pp
1276 The
1277 .Fa op
1278 argument may be a bitwise OR of a single command from above with one or more of
1279 the following flags:
1280 .Bl -tag -width indent
1281 .It Dv UMTX_OP__I386
1282 Request i386 ABI compatibility from the native
1283 .Nm
1284 system call.
1285 Specifically, this implies that:
1286 .Bl -hang -offset indent
1287 .It
1288 .Fa obj
1289 arguments that point to a word, point to a 32-bit integer.
1290 .It
1291 The
1292 .Dv UMTX_OP_NWAKE_PRIVATE
1293 .Fa obj
1294 argument is a pointer to an array of 32-bit pointers.
1295 .It
1296 The
1297 .Dv m_rb_lnk
1298 member of
1299 .Vt struct umutex
1300 is a 32-bit pointer.
1301 .It
1302 .Vt struct timespec
1303 uses a 32-bit time_t.
1304 .El
1305 .Pp
1306 .Dv UMTX_OP__32BIT
1307 has no effect if this flag is set.
1308 This flag is valid for all architectures, but it is ignored on i386.
1309 .It Dv UMTX_OP__32BIT
1310 Request non-i386, 32-bit ABI compatibility from the native
1311 .Nm
1312 system call.
1313 Specifically, this implies that:
1314 .Bl -hang -offset indent
1315 .It
1316 .Fa obj
1317 arguments that point to a word, point to a 32-bit integer.
1318 .It
1319 The
1320 .Dv UMTX_OP_NWAKE_PRIVATE
1321 .Fa obj
1322 argument is a pointer to an array of 32-bit pointers.
1323 .It
1324 The
1325 .Dv m_rb_lnk
1326 member of
1327 .Vt struct umutex
1328 is a 32-bit pointer.
1329 .It
1330 .Vt struct timespec
1331 uses a 64-bit time_t.
1332 .El
1333 .Pp
1334 This flag has no effect if
1335 .Dv UMTX_OP__I386
1336 is set.
1337 This flag is valid for all architectures.
1338 .El
1339 .Pp
1340 Note that if any 32-bit ABI compatibility is being requested, then care must be
1341 taken with robust lists.
1342 A single thread may not mix 32-bit compatible robust lists with native
1343 robust lists.
1344 The first
1345 .Dv UMTX_OP_ROBUST_LISTS
1346 call in a given thread determines which ABI that thread will use for robust
1347 lists going forward.
1348 .Sh RETURN VALUES
1349 If successful,
1350 all requests, except
1351 .Dv UMTX_SHM_CREAT
1352 and
1353 .Dv UMTX_SHM_LOOKUP
1354 sub-requests of the
1355 .Dv UMTX_OP_SHM
1356 request, will return zero.
1357 The
1358 .Dv UMTX_SHM_CREAT
1359 and
1360 .Dv UMTX_SHM_LOOKUP
1361 return a shared memory file descriptor on success.
1362 On error \-1 is returned, and the
1363 .Va errno
1364 variable is set to indicate the error.
1365 .Sh ERRORS
1366 The
1367 .Fn _umtx_op
1368 operations can fail with the following errors:
1369 .Bl -tag -width "[ETIMEDOUT]"
1370 .It Bq Er EFAULT
1371 One of the arguments point to invalid memory.
1372 .It Bq Er EINVAL
1373 The clock identifier, specified for the
1374 .Vt struct _umtx_time
1375 timeout parameter, or in the
1376 .Dv c_clockid
1377 member of
1378 .Vt struct ucond,
1379 is invalid.
1380 .It Bq Er EINVAL
1381 The type of the mutex, encoded by the
1382 .Dv m_flags
1383 member of
1384 .Vt struct umutex ,
1385 is invalid.
1386 .It Bq Er EINVAL
1387 The
1388 .Dv m_owner
1389 member of the
1390 .Vt struct umutex
1391 has changed the lock owner thread identifier during unlock.
1392 .It Bq Er EINVAL
1393 The
1394 .Dv timeout.tv_sec
1395 or
1396 .Dv timeout.tv_nsec
1397 member of
1398 .Vt struct _umtx_time
1399 is less than zero, or
1400 .Dv timeout.tv_nsec
1401 is greater than 1000000000.
1402 .It Bq Er EINVAL
1403 The
1404 .Fa op
1405 argument specifies invalid operation.
1406 .It Bq Er EINVAL
1407 The
1408 .Fa uaddr
1409 argument for the
1410 .Dv UMTX_OP_SHM
1411 request specifies invalid operation.
1412 .It Bq Er EINVAL
1413 The
1414 .Dv UMTX_OP_SET_CEILING
1415 request specifies non priority protected mutex.
1416 .It Bq Er EINVAL
1417 The new ceiling value for the
1418 .Dv UMTX_OP_SET_CEILING
1419 request, or one or more of the values read from the
1420 .Dv m_ceilings
1421 array during lock or unlock operations, is greater than
1422 .Dv RTP_PRIO_MAX .
1423 .It Bq Er EPERM
1424 Unlock attempted on an object not owned by the current thread.
1425 .It Bq Er EOWNERDEAD
1426 The lock was requested on an umutex where the
1427 .Dv m_owner
1428 field was set to the
1429 .Dv UMUTEX_RB_OWNERDEAD
1430 value, indicating terminated robust mutex.
1431 The lock was granted to the caller, so this error in fact
1432 indicates success with additional conditions.
1433 .It Bq Er ENOTRECOVERABLE
1434 The lock was requested on an umutex which
1435 .Dv m_owner
1436 field is equal to the
1437 .Dv UMUTEX_RB_NOTRECOV
1438 value, indicating abandoned robust mutex after termination.
1439 The lock was not granted to the caller.
1440 .It Bq Er ENOTTY
1441 The shared memory object, associated with the address passed to the
1442 .Dv UMTX_SHM_ALIVE
1443 sub-request of
1444 .Dv UMTX_OP_SHM
1445 request, was destroyed.
1446 .It Bq Er ESRCH
1447 For the
1448 .Dv UMTX_SHM_LOOKUP ,
1449 .Dv UMTX_SHM_DESTROY ,
1450 and
1451 .Dv UMTX_SHM_ALIVE
1452 sub-requests of the
1453 .Dv UMTX_OP_SHM
1454 request, there is no shared memory object associated with the provided key.
1455 .It Bq Er ENOMEM
1456 The
1457 .Dv UMTX_SHM_CREAT
1458 sub-request of the
1459 .Dv UMTX_OP_SHM
1460 request cannot be satisfied, because allocation of the shared memory object
1461 would exceed the
1462 .Dv RLIMIT_UMTXP
1463 resource limit, see
1464 .Xr setrlimit 2 .
1465 .It Bq Er EAGAIN
1466 The maximum number of readers
1467 .Dv ( URWLOCK_MAX_READERS )
1468 were already granted ownership of the given
1469 .Vt struct rwlock
1470 for read.
1471 .It Bq Er EBUSY
1472 A try mutex lock operation was not able to obtain the lock.
1473 .It Bq Er ETIMEDOUT
1474 The request specified a timeout in the
1475 .Fa uaddr
1476 and
1477 .Fa uaddr2
1478 arguments, and timed out before obtaining the lock or being woken up.
1479 .It Bq Er EINTR
1480 A signal was delivered during wait, for a non-restartable operation.
1481 Operations with timeouts are typically non-restartable, but timeouts
1482 specified in absolute time may be restartable.
1483 .It Bq Er ERESTART
1484 A signal was delivered during wait, for a restartable operation.
1485 Mutex lock requests without timeout specified are restartable.
1486 The error is not returned to userspace code since restart
1487 is handled by usual adjustment of the instruction counter.
1488 .El
1489 .Sh SEE ALSO
1490 .Xr clock_gettime 2 ,
1491 .Xr mmap 2 ,
1492 .Xr setrlimit 2 ,
1493 .Xr shm_open 2 ,
1494 .Xr sigaction 2 ,
1495 .Xr thr_exit 2 ,
1496 .Xr thr_kill 2 ,
1497 .Xr thr_kill2 2 ,
1498 .Xr thr_new 2 ,
1499 .Xr thr_self 2 ,
1500 .Xr thr_set_name 2 ,
1501 .Xr signal 3
1502 .Sh STANDARDS
1503 The
1504 .Fn _umtx_op
1505 system call is non-standard and is used by the
1506 .Lb libthr
1507 to implement
1508 .St -p1003.1-2001
1509 .Xr pthread 3
1510 functionality.
1511 .Sh BUGS
1512 A window between a unlocking robust mutex and resetting the pointer in the
1513 .Dv robust_inact_offset
1514 member of the registered
1515 .Vt struct umtx_robust_lists_params
1516 allows another thread to destroy the mutex, thus making the kernel inspect
1517 freed or reused memory.
1518 The
1519 .Li libthr
1520 implementation is only vulnerable to this race when operating on
1521 a shared mutex.
1522 A possible fix for the current implementation is to strengthen the checks
1523 for shared mutexes before terminating them, in particular, verifying
1524 that the mutex memory is mapped from a shared memory object allocated
1525 by the
1526 .Dv UMTX_OP_SHM
1527 request.
1528 This is not done because it is believed that the race is adequately
1529 covered by other consistency checks, while adding the check would
1530 prevent alternative implementations of
1531 .Li libpthread .