Tru64 UNIX
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