PTHREAD_RWLOCK(3) NetBSD Library Functions Manual PTHREAD_RWLOCK(3)
NAME
pthread_rwlock -- read/write lock interface
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
int
pthread_rwlock_init(pthread_rwlock_t * restrict lock,
const pthread_rwlockattr_t * restrict attr);
pthread_rwlock_t lock = PTHREAD_RWLOCK_INITIALIZER;
int
pthread_rwlock_destroy(pthread_rwlock_t *lock);
int
pthread_rwlock_rdlock(pthread_rwlock_t *lock);
int
pthread_rwlock_timedrdlock(pthread_rwlock_t * restrict lock,
const struct timespec * restrict abstime);
int
pthread_rwlock_tryrdlock(pthread_rwlock_t *lock);
int
pthread_rwlock_wrlock(pthread_rwlock_t *lock);
int
pthread_rwlock_timedwrlock(pthread_rwlock_t * restrict lock,
const struct timespec * restrict abstime);
int
pthread_rwlock_trywrlock(pthread_rwlock_t *lock);
int
pthread_rwlock_unlock(pthread_rwlock_t *lock);
DESCRIPTION
The pthread_rwlock_init() function is used to initialize a read/write
lock, with attributes specified by attr. If attr is NULL, the default
read/write lock attributes are used.
The results of calling pthread_rwlock_init() with an already initialized
lock are undefined.
The macro PTHREAD_RWLOCK_INITIALIZER can be used to initialize a
read/write lock when the allocation can be done statically, no error
checking is required, and the default attributes are appropriate. The
behavior is similar to calling pthread_rwlock_init() with attr specified
as NULL.
The pthread_rwlock_destroy() function is used to destroy a read/write
lock previously created with pthread_rwlock_init().
The pthread_rwlock_rdlock() function acquires a read lock on lock pro-
vided that lock is not presently held for writing and no writer threads
are presently blocked on the lock. If the read lock cannot be immedi-
ately acquired, the calling thread blocks until it can acquire the lock.
The pthread_rwlock_timedrdlock() performs the same action, but will not
wait beyond abstime to obtain the lock before returning.
The pthread_rwlock_tryrdlock() function performs the same action as
pthread_rwlock_rdlock(), but does not block if the lock cannot be immedi-
ately obtained (i.e., the lock is held for writing or there are waiting
writers).
A thread may hold multiple concurrent read locks. If so,
pthread_rwlock_unlock() must be called once for each lock obtained.
The results of acquiring a read lock while the calling thread holds a
write lock are undefined.
The pthread_rwlock_wrlock() function blocks until a write lock can be
acquired against lock.
The pthread_rwlock_timedwrlock() performs the same action, but will not
wait beyond abstime to obtain the lock before returning.
The pthread_rwlock_trywrlock() function performs the same action as
pthread_rwlock_wrlock(), but does not block if the lock cannot be immedi-
ately obtained.
The results are undefined if the calling thread already holds the lock at
the time the call is made.
The pthread_rwlock_unlock() function is used to release the read/write
lock previously obtained by pthread_rwlock_rdlock(),
pthread_rwlock_wrlock(), pthread_rwlock_tryrdlock(), or
pthread_rwlock_trywrlock().
RETURN VALUES
If successful, the pthread_rwlock_init() function will return zero. Oth-
erwise an error number will be returned to indicate the error.
If successful, the pthread_rwlock_destroy(), pthread_rwlock_rdlock(),
pthread_rwlock_timedrdlock(), pthread_rwlock_tryrdlock(),
pthread_rwlock_wrlock(), pthread_rwlock_timedwrlock(),
pthread_rwlock_trywrlock(), and pthread_rwlock_unlock() will return zero.
Otherwise an error number will be returned to indicate the error.
The results are undefined if lock is not held by the calling thread.
ERRORS
The pthread_rwlock_init() function may fail if:
[EAGAIN] The system lacks the resources to initialize another
read-write lock.
[EBUSY] The system has detected an attempt to re-initialize
the object referenced by lock, a previously initial-
ized but not yet destroyed read/write lock.
[EINVAL] The value specified by attr is invalid.
[ENOMEM] Insufficient memory exists to initialize the read-
write lock.
The pthread_rwlock_destroy() function may fail if:
[EBUSY] The system has detected an attempt to destroy the
object referenced by lock while it is locked.
[EINVAL] The value specified by lock is invalid.
The pthread_rwlock_tryrdlock() function shall fail if:
[EBUSY] The lock could not be acquired because a writer holds
the lock or was blocked on it.
The pthread_rwlock_timedrdlock() function shall fail if:
[ETIMEDOUT] The time specified by abstime was reached before the
lock could be obtained.
The pthread_rwlock_rdlock(), pthread_rwlock_timedrdlock(), and
pthread_rwlock_tryrdlock() functions may fail if:
[EAGAIN] The lock could not be acquired because the maximum
number of read locks against lock has been exceeded.
[EDEADLK] The current thread already owns lock for writing.
[EINVAL] The value specified by lock is invalid.
The pthread_rwlock_trywrlock() function shall fail if:
[EBUSY] The calling thread is not able to acquire the lock
without blocking.
The pthread_rwlock_timedrdlock() function shall fail if:
[ETIMEDOUT] The time specified by abstime was reached before the
lock could be obtained.
The pthread_rwlock_wrlock(), pthread_rwlock_timedwrlock(), and
pthread_rwlock_trywrlock() functions may fail if:
[EDEADLK] The calling thread already owns the read/write lock
(for reading or writing).
[EINVAL] The value specified by lock is invalid.
The pthread_rwlock_unlock() function may fail if:
[EINVAL] The value specified by lock is invalid.
[EPERM] The current thread does not own the read/write lock.
SEE ALSO
pthread(3), pthread_barrier(3), pthread_cond(3), pthread_mutex(3),
pthread_rwlockattr(3), pthread_spin(3)
STANDARDS
These functions conform to IEEE Std 1003.1-2001 (``POSIX.1'').
BUGS
The PTHREAD_PROCESS_SHARED attribute is not supported.
NetBSD 5.0 July 8, 2010 NetBSD 5.0
