RWLOCK(9) | Kernel Developer's Manual | RWLOCK(9)

# NAME

`rwlock`, `rw_init`, `rw_init_flags`, `rw_init_flags_trace`, `rw_enter`, `rw_exit`, `rw_enter_read`, `rw_enter_write`, `rw_exit_read`, `rw_exit_write`, `rw_assert_wrlock`, `rw_assert_rdlock`, `rw_assert_anylock`, `rw_assert_unlocked`, `rw_status`, `RWLOCK_INITIALIZER`, `RWLOCK_INITIALIZER_TRACE`, `rrw_init`, `rrw_init_flags`, `rrw_enter`, `rrw_exit`, `rrw_status` — interface to read/write locks

# SYNOPSIS

`#include <sys/rwlock.h>`

void
`rw_init`(struct rwlock *rwl, const char *name);

void
`rw_init_flags`(struct rwlock *rwl, const char *name, int flags);

void
`rw_init_flags_trace`(struct rwlock *rwl, const char *name, int flags, int trace);

int
`rw_enter`(struct rwlock *rwl, int flags);

void
`rw_exit`(struct rwlock *rwl);

void
`rw_enter_read`(struct rwlock *rwl);

void
`rw_enter_write`(struct rwlock *rwl);

void
`rw_exit_read`(struct rwlock *rwl);

void
`rw_exit_write`(struct rwlock *rwl);

void
`rw_assert_wrlock`(struct rwlock *rwl);

void
`rw_assert_rdlock`(struct rwlock *rwl);

void
`rw_assert_anylock`(struct rwlock *rwl);

void
`rw_assert_unlocked`(struct rwlock *rwl);

int
`rw_status`(struct rwlock *rwl);

`RWLOCK_INITIALIZER`(const char *name);

`RWLOCK_INITIALIZER_TRACE`(const char *name, int trace);

void
`rrw_init`(struct rrwlock *rrwl, const char *name);

void
`rrw_init_flags`(struct rrwlock *rrwl, const char *name, int flags);

int
`rrw_enter`(struct rrwlock *rrwl, int flags);

void
`rrw_exit`(struct rrwlock *rrwl);

int
`rrw_status`(struct rrwlock *rrwl);

# DESCRIPTION

The `rwlock` set of functions provides a multiple-reader, single-writer locking mechanism to ensure mutual exclusion between different threads.

Read locks can be acquired while the write lock is not held, and may coexist in distinct threads at any time. A write lock, however, can only be acquired when there are no read locks held, granting exclusive access to a single thread.

The `rw_init`() function is used to initiate the lock pointed to by rwl. The name argument specifies the name of the lock, which is used as the wait message if the thread needs to sleep.

The `rw_init_flags`() macro is similar to `rw_init`(), but it additionally accepts a bitwise OR of the following flags:

`RWL_DUPOK`
  Prevents witness(4) from logging when a thread acquires more than one lock of this lock type.
`RWL_IS_VNODE`
  Make witness(4) ignore lock order issues between this lock type and any other lock type tagged with the `RWL_IS_VNODE` flag.
`RWL_NOWITNESS`
  Instructs witness(4) to ignore this lock.

`rw_init_flags_trace`() additionally accepts a dt(4) static probe index.

The `rw_enter`() function acquires a lock. The flags argument specifies what kind of lock should be obtained and also modifies the operation. The possible flags are:

`RW_READ`
  Acquire a shared lock.
`RW_WRITE`
  Acquire an exclusive lock.
`RW_DOWNGRADE`
  Safely release an exclusive lock and acquire a shared lock without letting other exclusive locks in between.
`RW_UPGRADE`
  Upgrade a shared lock into an exclusive one. Must be combined with `RW_NOSLEEP`.
`RW_INTR`
  When waiting for a lock, allow signals to interrupt the sleep.
`RW_NOSLEEP`
  Do not wait for busy locks, fail with `EBUSY` instead.
`RW_DUPOK`
  Prevents witness(4), for just this `rw_enter`(), from logging when this thread already has a lock of this lock type.

The `rw_exit`() function is used to release a held lock.

The `rw_enter_read`() function acquires a read lock, sleeping if necessary.

The `rw_enter_write`() function acquires a write lock, sleeping if necessary.

The `rw_exit_read`() function releases a read lock.

The `rw_exit_write`() function releases a write lock.

The `rw_assert_wrlock`(), `rw_assert_rdlock`(), `rw_assert_anylock`(), and `rw_assert_unlocked`() functions check the status rwl, panicking if it is not write-, read-, any-, or unlocked, respectively.

`rw_status` returns the current state of the lock.

A lock declaration may be initialised with the `RWLOCK_INITIALIZER`() macro. The name argument specifies the name of the lock, which is used as the wait message if the thread needs to sleep. `RWLOCK_INITIALIZER_TRACE`() additionally accepts a dt(4) static probe index.

The `rrwlock` functions support recursive write locking by the same process. They otherwise behave the same as their rwlock counterparts.

# CONTEXT

`rw_init`(), `rw_init_flags`(), `rw_init_flags_trace`(), `rrw_init`() and `rrw_init_flags`() can be called during autoconf, from process context, or from interrupt context.

All other functions can be called during autoconf or from process context.

# RETURN VALUES

`rw_enter` and `rrw_enter` return 0 on success, or an errno(2) style value on failure.

`rw_status` and `rrw_status` return the state of the lock:

`RW_WRITE`
  Lock is write locked by the calling thread.
`RW_WRITE_OTHER`
  Lock is write locked by a different thread.
`RW_READ`
  Lock is read locked. The current thread may be one of the threads that has it locked.
0
  Lock is not locked.

# SEE ALSO

witness(4), mutex(9), rwsleep(9), spl(9)

# HISTORY

The `rwlock` functions first appeared in OpenBSD 3.5.

# AUTHORS

The `rwlock` functions were written by Artur Grabowski <art@openbsd.org>.

August 5, 2025 | Debian