rw_rdlock(SYNCH)

rw_rdlock -- acquire a reader-writer lock in read mode.

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int rw_rdlock(rwlock_t *lock);

Description

rw_rdlock acquires the reader-writer lock pointed to by lock in read mode.

A reader-writer lock can be held by any number of readers at one time, but only one writer at a time can hold the lock. Once a writer has requested the lock with rw_wrlock, all subsequent requests for the lock in either read or write mode are queued.

If the lock is free, or is currently held by another reader and there are no writers waiting, rw_rdlock increments the reader count and the caller proceeds. If a writer holds the lock or if any writer is waiting for the lock, the caller blocks to wait for the lock.

lock must previously have been initialized (see rwlock_init(SYNCH)).

From the point of view of the caller, this function is atomic: even if interrupted by a signal or forkall (see fork(S)), rw_rdlock will not return until it holds the lock. As a consequence, if rw_rdlock is interrupted, an error indication, such as EINTR, is never returned to the user.

Parameters

lock: pointer to the reader-writer lock to be acquired

Usage

For consistency, locks acquired with rw_rdlock should be released with rw_unlock.

Return values

rw_rdlock returns zero for success and an error number for failure.

Errors

If any of the following conditions is detected, rw_rdlock returns the corresponding value:

EINVAL: invalid argument specified
ENOMEM: insufficient memory

Warnings

If a thread exits while holding a reader-writer lock, the lock will not be unlocked, and other threads waiting for the lock will wait forever. Similarly, if a process exits while holding a USYNC_PROCESS reader-writer lock, the lock will not be unlocked, and other processes waiting for the reader-writer lock will wait forever.

References

fork(S), Intro(SYNCH), rwlock(SYNCH), rwlock_destroy(SYNCH), rwlock_init(SYNCH), rw_tryrdlock(SYNCH), rw_trywrlock(SYNCH), rw_unlock(SYNCH), rw_wrlock(SYNCH)