pthread_rwlock

NAME

pthread_rwlock_init(), pthread_rwlock_destroy() — initialize or destroy a read-write lock

SYNOPSIS

#include <pthread.h>

int pthread_rwlock_init( 
   pthread_rwlock_t *__restrict rwlock, 
   const pthread_rwlockattr_t *__restrict attr 
); 

pthread_rwlock_t rwlock = PTHREAD_RWLOCK_INITIALIZER;

int pthread_rwlock_destroy( 
   pthread_rwlock_t *rwlock 
); 

PARAMETERS

rwlock: Pointer to the read-write lock to be initialized or destroyed.
attr: Pointer to the attributes object that defines the characteristics of the read-write lock to be initialized. If the pointer is NULL, default attributes are used.

DESCRIPTION

pthread_rwlock_init() initializes the read-write lock referenced by rwlock with the attributes attr. If attr is NULL, the default read-write lock attributes are used. Upon successful initialization, the state of the read-write lock becomes initialized and unlocked. Attempting to initialize an already initialized read-write lock object results in undefined behavior.

The macro PTHREAD_RWLOCK_INITIALIZER can be used to initialize read-write locks which are statically allocated. The effect is equivalent to dynamic initialization by a call to pthread_rwlock_init() with the attr parameter specified as NULL, except that no error checks are performed. The read-write lock will be initialized with default attributes.

If the process-shared attribute in the read-write lock attributes object referenced by attr is defined as PTHREAD_PROCESS_SHARED, the read-write lock must be allocated such that the processes sharing the read-write lock has access to it. This may be done through the memory-mapping functions (see mmap(2)) or shared memory functions (see shmget(2)).

pthread_rwlock_destroy() destroys the read-write referenced by rwlock. This function may set rwlock to an invalid value. The destroyed read-write lock can be reinitialized using the function pthread_rwlock_init(). If the read-write lock is referenced after destruction in any read-write lock call, the resulting behavior is undefined.

A read-write lock should be destroyed only when no threads are currently using it. Destroying a read-write lock which is currently in use results in undefined behavior.

RETURN VALUE

Upon successful completion, pthread_rwlock_init() and pthread_rwlock_destroy() returns zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_rwlock_init() function returns the corresponding error number:

EAGAIN: The necessary resources (other than memory) to initialize rwlock are not available.
EBUSY: rwlock is an already initialized read-write lock. However, getting EBUSY for reinitializing the rwlock cannot be expected all the time since the behavior of reinitializing the rwlock is undefined.
EINVAL: The value specified by rwlock or attr is invalid.
ENOMEM: There is insufficient memory available in which to initialize the read-write lock rwlock.
EPERM: The caller does not have the privilege to perform the operation.

If any of the following occur, the pthread_rwlock_destroy() function returns the corresponding error number:

EBUSY: rwlock is currently locked or being used by other threads.
EINVAL: The value specified by rwlock is invalid.

WARNINGS

The space for the read-write lock must to be allocated before calling pthread_rwlock_init(). Undefined behavior may result if the process-shared attribute of attr is PTHREAD_PROCESS_SHARED and the space allocated for the read-write lock is not accessible to cooperating threads.

AUTHOR

pthread_rwlock_init() and pthread_rwlock_destroy() were developed by X/Open.

STANDARDS CONFORMANCE

pthread_rwlock_init(): X/Open.
pthread_rwlock_destroy(): X/Open.

pthread_rwlock_init(3T)

Technical documentation

» Table of Contents

» Index