PTHREAD_RWLOCK(3) NetBSD Library Functions Manual PTHREAD_RWLOCK(3)
NAME
pthread_rwlock, pthread_rwlock_init, pthread_rwlock_destroy, pthread_rwlock_rdlock, pthread_rwlock_timedrdlock, pthread_rwlock_tryrdlock, pthread_rwlock_wrlock, pthread_rwlock_timedwrlock, pthread_rwlock_trywrlock, pthread_rwlock_unlock -- 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 9.0 July 8, 2010 NetBSD 9.0
Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.