lib/libc/sys/_umtx_op.2

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