Tribblix: manual page: pthread_rwlock

PTHREAD_RWLOCK_RDLOCK(3C) Standard C Library Functions

NAME

pthread_rwlock_rdlock, pthread_rwlock_tryrdlock - lock or attempt to
lock read-write lock object for reading

SYNOPSIS

cc -mt [ flag... ] file... -lpthread [ library... ]
#include <pthread.h>

int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock);

int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock);

DESCRIPTION

The pthread_rwlock_rdlock() function applies a read lock to the read-
write lock referenced by rwlock. The calling thread acquires the
read lock if a writer does not hold the lock and there are no writers
blocked on the lock.

The calling thread does not acquire the lock if a writer holds the
lock or if writers of higher or equal priority are blocked on the
lock; otherwise, the calling thread acquires the lock. If the read
lock is not acquired, the calling thread blocks until it can acquire
the lock.

A thread can hold multiple concurrent read locks on rwlock (that is,
successfully call the pthread_rwlock_rdlock() function n times). If
so, the thread must perform matching unlocks (that is, it must call
the pthread_rwlock_unlock() function n times).

The maximum number of concurrent read locks that a thread can hold on
one read-write lock is currently set at 100,000, though this number
could change in a future release. There is no imposed limit on the
number of different threads that can apply a read lock to one read-
write lock.

The pthread_rwlock_tryrdlock() function applies a read lock like the
pthread_rwlock_rdlock() function, with the exception that the
function fails if the equivalent pthread_rwlock_rdlock() call would
have blocked the calling thread. In no case will the
pthread_rwlock_tryrdlock() function ever block. It always either
acquires the lock or fails and returns immediately.

Results are undefined if any of these functions are called with an
uninitialized read-write lock.

If a signal is delivered to a thread waiting for a read-write lock
for reading, upon return from the signal handler the thread resumes
waiting for the read-write lock for reading as if it was not
interrupted.

RETURN VALUES

If successful, the pthread_rwlock_rdlock() function returns 0.
Otherwise, an error number is returned to indicate the error.

The pthread_rwlock_tryrdlock() function returns 0 if the lock for
reading on the read-write lock object referenced by rwlock is
acquired. Otherwise an error number is returned to indicate the
error.

ERRORS

The pthread_rwlock_rdlock() and pthread_rwlock_tryrdlock() functions
will fail if:

EAGAIN
The read lock could not be acquired because the maximum
number of read locks by the current thread for rwlock has
been exceeded.

The pthread_rwlock_rdlock() function will fail if:

EDEADLK
The current thread already owns the read-write lock for
writing.

The pthread_rwlock_tryrdlock() function will fail if:

EBUSY
The read-write lock could not be acquired for reading
because a writer holds the lock or a writer with the
appropriate priority was blocked on it.