| Previous | Contents | Index |
Obtains the value of the process-shared attribute of a read-write lock attributes object.This routine is for Tru64 UNIX systems only.
pthread_rwlockattr_getpshared(C Binding #include <pthread.h>
attr ,
pshared );
Argument Data Type Access attr opaque pthread_rwlockattr_t read pshared int write
int
pthread_rwlockattr_getpshared (
const pthread_rwlockattr_t *attr,
int *pshared);
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.
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. |
pthread_rwlock_init()
pthread_rwlock_rdlock()
pthread_rwlock_unlock()
pthread_rwlock_wrlock()
pthread_rwlockattr_init()
pthread_rwlockattr_setpshared()
Initializes a read-write lock attributes object.
pthread_rwlockattr_init(C Binding #include <pthread.h>
attr );
Argument Data Type Access attr opaque pthread_rwlockattr_t write
int
pthread_rwlockattr_init (
pthread_rwlockattr_t *attr);
attr
Address of the read-write lock attributes object to be initialized.
This routine initializes the read-write lock attributes object referenced by attr and sets its attributes with default values.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | Description |
|---|---|
| 0 | Successful completion |
| [ENOMEM] | Insufficient memory to initialize the read-write lock attributes object |
pthread_rwlockattr_destroy()
pthread_rwlock_init()
Sets the value of the process-shared attribute of a read-write lock attributes object.This routine is for Tru64 UNIX systems only.
pthread_rwlockattr_setpshared(C Binding #include <pthread.h>
attr ,
pshared );
Argument Data Type Access attr opaque pthread_rwlockattr_t write pshared int read
int
pthread_rwlockattr_setpshared (
pthread_rwlockattr_t *attr,
int pshared);
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.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | 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. |
pthread_rwlock_init()
pthread_rwlock_rdlock()
pthread_rwlock_unlock()
pthread_rwlock_wrlock()
pthread_rwlockattr_init()
pthread_rwlockattr_getpshared()
Destroys a read-write lock object.
pthread_rwlock_destroy(C Binding #include <pthread.h>
rwlock );
Argument Data Type Access rwlock opaque pthread_rwlock_t write
int
pthread_rwlock_destroy (
pthread_rwlock_t *rwlock);
rwlock
Address of the read-write lock object to be destroyed.
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() .Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | Description |
|---|---|
| 0 | Successful completion. |
| [EBUSY] | An attempt was made to destroy the object referenced by rwlock while it is locked or referenced. |
pthread_rwlock_init()
Obtains the object name from a read-write lock object.
pthread_rwlock_getname_np(C Binding #include <pthread.h>
rwlock ,
name ,
len );
Argument Data Type Access rwlock opaque pthread_rwlock_t read name char write len size_t read
int
pthread_rwlock_getname_np (
pthread_rwlock_t *rwlock,
char *name,
size_t len);
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.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by rwlock is not a valid read-write lock. |
pthread_rwlock_setname_np()
Initializes a read-write lock object.
C Binding #include <pthread.h>
pthread_rwlock_init(
rwlock ,
attr );
Argument Data Type Access rwlock opaque pthread_rwlock_t write attr opaque pthread_rwlockattr_t read
int
pthread_rwlock_init (
pthread_rwlock_t *rwlock,
const pthread_rwlockattr_t *attr);
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.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | 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. |
pthread_rwlock_destroy()
Acquires a read-write lock object for read access.
pthread_rwlock_rdlock(C Binding #include <pthread.h>
rwlock );
Argument Data Type Access rwlock opaque pthread_rwlock_t write
int
pthread_rwlock_rdlock (
pthread_rwlock_t *rwlock);
rwlock
Address of the read-write lock object to acquire for read access.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | 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. |
pthread_rwlock_init()
pthread_rwlockattr_init()
pthread_rwlock_tryrdlock()
pthread_rwlock_wrlock()
pthread_rwlock_unlock()
Changes the object name in a read-write lock object.
pthread_rwlock_setname_np(C Binding #include <pthread.h>
rwlock ,
name ,
mbz );
Argument Data Type Access rwlock opaque pthread_rwlock_t write name char read mbz void read
int
pthread_rwlock_setname_np (
pthread_rwlock_t *rwlock,
const char *name,
void *mbz);
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).
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | 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. |
pthread_rwlock_getname_np()
pthread_rwlock_init()
| Previous | Next | Contents | Index |