pthread_rwlock_init(3pthread)
pthread_rwlock_init, pthread_rwlock_destroy --
initialize, destroy, a read-write lock
Synopsis
cc [options] -Kthread file
#include <pthread.h>
int pthread_rwlock_init(pthread_rwlock_t *rwlock,
const pthread_rwlockattr_t *attr);
int pthread_rwlock_destroy(pthread_rwlock_t *rwlock);
pthread_rwlock_t *rwlock=PTHREAD_RWLOCK_INITIALIZER
Description
pthread_rwlock_init initializes the read-write lock
pointed to by rwlock
with the attributes referenced
by attr
and in the unlocked state.
Once initialized, the lock can be used any number of
times without being re-initialized.
The
rwlock parameter points to the
reader-writer lock to be initialized or destroyed.
The attr parameter points to a read-write lock
attributes object that will be used to initialize rwlock.
If attr is NULL, the default read-write lock attributes
are used; the effect is the same as passing the address
of a default read-write attributes object.
If the pthread_rwlock_init
function fails, rwlock is not initialized and
its contents are undefined.
pthread_rwlock_destroy destroys the read-write
object pointed to by rwlock and
releases any resources used by the lock.
This includes invalidating the lock and freeing any
associated dynamically allocated resources.
The effect of subsequent use of the lock is undefined
until the lock is re-initialized by another call
to pthread_rwlock_init.
An implementation may cause pthread_rwlock_destroy
to set the object referenced by rwlock to an
invalid value.
Results are undefined if pthread_rwlock_destroy
is called when any thread holds rwlock.
Attempting to destroy an uninitialized read-write lock
results in undefined behavior.
A destroyed read-write lock object can be re-initialized using
pthread_rwlock_init;
the results of otherwise referencing the read-write lock
object after it has been destroyed are undefined.
Static reader-Writer initialization
In cases where default read-write lock attributes
are appropriate, the macro PTHREAD_RWLOCK_INITIALIZER
can be used to initialize read-write locks that are
statically allocated.
The effect is equivalent to dynamic initialization
by a call to pthread_rwlock_init with attr
specified as NULL,
except that no error checks are performed.
Return values
pthread_rwlock_init and pthread_rwlock_destroy
return zero on success.
Otherwise, an error number is returned.
Diagnostics
The EBUSY and EINVAL error checks,
if implemented, will act as if they were performed
immediately at the beginning of processing for the
function and caused an error return prior to modifying
the state of the read-write lock specified by rwlock.
pthread_rwlock_init
returns
the following value
and does not change
the contents of rwlock
if the corresponding condition is detected:
EINVAL-
Invalid attr argument specified.
EINVAL-
Invalid rwlock argument specified.
pthread_rwlock_destroy
returns
the following values
if the corresponding conditions are detected:
EBUSY-
rwlock is locked or another thread is waiting to
acquire rwlock.
EINVAL-
The value specified by rwlock is invalid.
Warnings
pthread_rwlock_init does not examine
the rwlock argument before initializing it.
If pthread_rwlock_init is called more than
once for the same reader-writer lock,
it will overwrite its state.
It is the user's responsibility to ensure that
pthread_rwlock_init
is only called once for each reader-writer lock.
Most operations on read-write locks
are not recursive--a thread can deadlock if
it attempts to reacquire a read-write lock
that it already has acquired.
Results are undefined if a read-write lock
is used without first being initialized.
Standards Compliance
The Single UNIX Specification, Version 2; The Open Group.
References
Intro(3pthread),
pthread(4),
pthread_rwlockattr_init(3pthread),
pthread_rwlock_rdlock(3pthread),
pthread_rwlock_unlock(3pthread),
pthread_rwlock_wrlock(3pthread)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004