Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_rwlockattr_getpshared

> Obtains the value of the process-shared attribute of a read-write lock attributes object.

> This routine is for Tru64 UNIX systems only.

### Syntax

> pthread_rwlockattr_getpshared(
> attr ,
> pshared );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_rwlockattr_t | read
> pshared | int | write

C Binding #include <pthread.h>

int
pthread_rwlockattr_getpshared (
const pthread_rwlockattr_t *attr,
int *pshared);

### Arguments

> #### attr

> Address of the read-write lock attributes object whose process-shared attribute is to be obtained.

> #### pshared

> Receives the value of the process-shared attribute of the read-write lock attributes object specified by attr.

### Description

> This routine obtains the value of the process-shared attribute from the read-write lock attributes object specified by the attr argument and stores it in the location specified by the pshared argument. This attributes object must already be initialized at the time this routine is called.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by attr is not a valid attributes object.

#### Associated Routines

> `pthread_rwlock_init()`
> `pthread_rwlock_rdlock()`
> `pthread_rwlock_unlock()`
> `pthread_rwlock_wrlock()`
> `pthread_rwlockattr_init()`
> `pthread_rwlockattr_setpshared()`

## pthread_rwlockattr_init

> Initializes a read-write lock attributes object.

### Syntax

> pthread_rwlockattr_init(
> attr );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_rwlockattr_t | write

C Binding #include <pthread.h>

int
pthread_rwlockattr_init (
pthread_rwlockattr_t *attr);

### Arguments

> #### attr

> Address of the read-write lock attributes object to be initialized.

### Description

> This routine initializes the read-write lock attributes object referenced by attr and sets its attributes with default values.

> The results of calling this routine are undefined if attr references an already initialized read-write lock attributes object.

> After an initialized read-write lock attributes object has been used to initialize one or more read-write lock objects, any operation on that attributes object (including destruction) has no effect on those read-write lock objects.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion
[ENOMEM] | Insufficient memory to initialize the read-write lock attributes object

#### Associated Routines

> `pthread_rwlockattr_destroy()`
> `pthread_rwlock_init()`

## pthread_rwlockattr_setpshared

> Sets the value of the process-shared attribute of a read-write lock attributes object.

> This routine is for Tru64 UNIX systems only.

### Syntax

> pthread_rwlockattr_setpshared(
> attr ,
> pshared );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_rwlockattr_t | write
> pshared | int | read

C Binding #include <pthread.h>

int
pthread_rwlockattr_setpshared (
pthread_rwlockattr_t *attr,
int pshared);

### Arguments

> #### attr

> Address of the read-write lock attributes object whose process-shared attribute is to be modified.

> #### pshared

> New value for the process-shared attribute of the read-write lock attributes object specified by attr.

### Description

> This routine uses the value specified in the pshared argument to set the process-shared attribute of the read-write lock attributes object specified by the attr argument. This attributes object must already be initialized at the time this routine is called.

> If the process-shared attribute is set to `PTHREAD_PROCESS_PRIVATE` , the read-write lock object can only be operated upon by threads created within the same process as the thread that initialized the read-write lock object. If threads of differing processes attempt to operate on such a read-write lock object, the behavior is undefined.

> The default value of the process-shared attribute of a read-write lock attributes object is `PTHREAD_PROCESS_PRIVATE` .

> If the process-shared attribute of a read-write lock attributes object is set to `PTHREAD_PROCESS_SHARED` , the read-write lock object can be operated upon by any thread that has access to the memory where that object is allocated, even if that object is allocated in memory that is shared by multiple processes.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by attr is not a valid attributes object, or the value pshared is outside the range of legal values for that attribute.

#### Associated Routines

> `pthread_rwlock_init()`
> `pthread_rwlock_rdlock()`
> `pthread_rwlock_unlock()`
> `pthread_rwlock_wrlock()`
> `pthread_rwlockattr_init()`
> `pthread_rwlockattr_getpshared()`

## pthread_rwlock_destroy

> Destroys a read-write lock object.

### Syntax

> pthread_rwlock_destroy(
> rwlock );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write

C Binding #include <pthread.h>

int
pthread_rwlock_destroy (
pthread_rwlock_t *rwlock);

### Arguments

> #### rwlock

> Address of the read-write lock object to be destroyed.

### Description

> This routine destroys the specified read-write lock object by uninitializing it, and should be called when the object is no longer referenced in your program. After this routine is called, the Threads Library may reclaim internal storage used by the specified read-write lock object. The effect of subsequent use of the lock is undefined until the lock is reinitialized by another call to `pthread_rwlock_init()` .

> It is illegal to destroy a locked read-write lock.

> The results of this routine are unpredictable if the specified read-write lock object does not currently exist or is not initialized. This routine destroys the read-write lock object specified by the rwlock argument and releases any resources that the object used.

> A destroyed read-write lock object can be reinitialized using the
> `pthread_rwlock_init()` routine. The results of otherwise referencing a destroyed read-write lock object are undefined.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EBUSY] | An attempt was made to destroy the object referenced by rwlock while it is locked or referenced.

#### Associated Routines

> `pthread_rwlock_init()`

## pthread_rwlock_getname_np

> Obtains the object name from a read-write lock object.

### Syntax

> pthread_rwlock_getname_np(
> rwlock ,
> name ,
> len );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | read
> name | char | write
> len | size_t | read

C Binding #include <pthread.h>

int
pthread_rwlock_getname_np (
pthread_rwlock_t *rwlock,
char *name,
size_t len);

### Arguments

> #### rwlock

> Address of the read-write lock object whose object name is to be obtained.

> #### name

> Location to store the obtained object name.

> #### len

> Length in bytes of buffer at the location specified by name.

### Description

> This routine copies the object name from the read-write lock object specified by rwlock to the buffer at the location name. Before calling this routine, your program must allocate the buffer indicated by name.

> The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

> If the specified read-write lock object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by rwlock is not a valid read-write lock.

#### Associated Routines

> `pthread_rwlock_setname_np()`

## pthread_rwlock_init

> Initializes a read-write lock object.

### Syntax

> pthread_rwlock_init(
> rwlock ,
> attr );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write
> attr | opaque pthread_rwlockattr_t | read

C Binding #include <pthread.h>

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

### Arguments

> #### rwlock

> Read-write lock object to be initialized.

> #### attr

> Read-write lock attributes object that defines the characteristics of the read-write lock to be initialized.

### Description

> This routine initializes a read-write lock object with the attributes specified by the read-write lock attributes object specified in attr. A read-write lock is a synchronization object that serializes access to shared information that needs to be read frequently and written only occasionally. A thread can acquire a read-write lock for shared read access or for exclusive write access.

> Upon successful completion of this routine, the read-write lock is initialized and set to the unlocked state. If attr is set to NULL, the default read-write lock attributes are used; the effect is the same as passing the address of a default read-write lock attributes object. Once initialized, the lock can be used any number of times without being reinitialized.

> Results of calling this routine are undefined if attr specifies an already initialized read-write lock or if rwlock is used without first being initialized.

> If this routine returns unsuccessfully, rwlock is not initialized and the contents of rwlock are undefined.

> A read-write lock is a resource of the process, not part of any particular thread. A read-write lock is neither destroyed not unlocked automatically when any thread exits. Because read-write locks are shared, they may be allocated in heap or static memory, but not on a stack.

> In cases where default read-write lock attributes are appropriate, you may use the `PTHREAD_RWLOCK_INITIALIZER` macro to statically initialize the lock object without calling this routine. 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. Statically initialized read-write locks need not be destroyed using `pthread_rwlock_destroy()` .

> Use the `PTHREAD_RWLOCK_INITIALIZER` macro as follows:

> `pthread_rwlock_t` rwlock `= PTHREAD_RWLOCK_INITIALIZER;`

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion.
[EAGAIN] | The system lacks the necessary resources to initialize the read-write lock.
[EBUSY] | The Threads Library has detected an attempt to reinitialize the read-write lock (a previously initialized, but not yet destroyed, read-write lock object).
[EINVAL] | The value specified by attr is not a valid attributes block.
[ENOMEM] | Insufficient memory exists to initialize the read-write lock.
[EPERM] | The caller does not have privileges to perform this operation.

#### Associated Routines

> `pthread_rwlock_destroy()`

## pthread_rwlock_rdlock

> Acquires a read-write lock object for read access.

### Syntax

> pthread_rwlock_rdlock(
> rwlock );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write

C Binding #include <pthread.h>

int
pthread_rwlock_rdlock (
pthread_rwlock_t *rwlock);

### Arguments

> #### rwlock

> Address of the read-write lock object to acquire for read access.

### Description

> This routine acquires a read-write lock for read access. If no thread already holds the lock for write access and there are no writers waiting to acquire the lock, the lock for read access is granted to the calling thread and this routine returns. If a thread already holds the lock for read access, the lock is granted and this routine returns.

> A thread can hold multiple, concurrent locks for read access on the same read-write lock. In a given thread, for each call to this routine that successfully acquires the same read-write lock for read access, a corresponding call to `pthread_rwlock_unlock` must be issued.

> If some thread already holds the lock for write access, the calling thread will not acquire the read lock. If the read lock is not acquired, the calling thread blocks until it can acquire the lock for read access. Results are undefined if the calling thread has already acquired a lock for write access on rwlock when this routine is called.

> If the read-write lock object referenced by rwlock is not initialized, the results of calling this routine are undefined.

> If a thread is interrupted (via a Tru64 UNIX signal or an OpenVMS AST) while waiting for a read-write lock for read access, upon return from the interrupt routine the thread resumes waiting for the lock as if it had not been interrupted.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion; the read-write lock object was acquired for read access.
[EINVAL] | The value specified by rwlock does not refer to an initialized read-write lock object.
[EDEADLCK] | The calling thread already owns the specified read-write lock object for write access.
[EAGAIN] | The lock for read access could not be acquired because the maximum number of read lock acquisitions for rwlock has been exceeded.

#### Associated Routines

> `pthread_rwlock_init()`
> `pthread_rwlockattr_init()`
> `pthread_rwlock_tryrdlock()`
> `pthread_rwlock_wrlock()`
> `pthread_rwlock_unlock()`

## pthread_rwlock_setname_np

> Changes the object name in a read-write lock object.

### Syntax

> pthread_rwlock_setname_np(
> rwlock ,
> name ,
> mbz );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write
> name | char | read
> mbz | void | read

C Binding #include <pthread.h>

int
pthread_rwlock_setname_np (
pthread_rwlock_t *rwlock,
const char *name,
void *mbz);

### Arguments

> #### rwlock

> Address of the read-write lock object whose object name is to be changed.

> #### name

> Object name value to copy into the read-write lock object.

> #### mbz

> Reserved for future use. The value must be zero (0).

### Description

> This routine changes the object name in the read-write lock object specified by rwlock to the value specified by name. To set a new read-write lock object's object name, call this routine immediately after initializing the read-write lock object.

> The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion, the read-write lock object was acquired for read access.
[EINVAL] | The value specified by rwlock is invalid, or the length in characters of name exceeds 31.
[ENOMEM] | Insufficient memory to create a copy of the object name string.

#### Associated Routines

> `pthread_rwlock_getname_np()`
> `pthread_rwlock_init()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_023.HTML