mirror of https://github.com/mkerrisk/man-pages
138 lines
5.1 KiB
Plaintext
138 lines
5.1 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "PTHREAD_RWLOCK_DESTROY" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" pthread_rwlock_destroy
|
||
|
.SH NAME
|
||
|
pthread_rwlock_destroy, pthread_rwlock_init \- destroy and initialize
|
||
|
a read\-write lock object
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <pthread.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int pthread_rwlock_destroy(pthread_rwlock_t *\fP\fIrwlock\fP\fB);
|
||
|
.br
|
||
|
int pthread_rwlock_init(pthread_rwlock_t *restrict\fP \fIrwlock\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ const pthread_rwlockattr_t *restrict\fP \fIattr\fP\fB);
|
||
|
\fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_destroy\fP() function shall destroy the read-write
|
||
|
lock object referenced by \fIrwlock\fP and release
|
||
|
any resources used by the lock. The effect of subsequent use of the
|
||
|
lock is undefined until the lock is reinitialized by another
|
||
|
call to \fIpthread_rwlock_init\fP(). An implementation may cause \fIpthread_rwlock_destroy\fP()
|
||
|
to set the object referenced by
|
||
|
\fIrwlock\fP to an invalid value. Results are undefined if \fIpthread_rwlock_destroy\fP()
|
||
|
is called when any thread holds
|
||
|
\fIrwlock\fP. Attempting to destroy an uninitialized read-write lock
|
||
|
results in undefined behavior.
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_init\fP() function shall allocate any resources
|
||
|
required to use the read-write lock referenced by
|
||
|
\fIrwlock\fP and initializes the lock to an unlocked state with attributes
|
||
|
referenced by \fIattr\fP. If \fIattr\fP is NULL, the
|
||
|
default read-write lock attributes shall be 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 are undefined if
|
||
|
\fIpthread_rwlock_init\fP() is called specifying an already initialized
|
||
|
read-write lock. Results are undefined if a read-write
|
||
|
lock is used without first being initialized.
|
||
|
.LP
|
||
|
If the \fIpthread_rwlock_init\fP() function fails, \fIrwlock\fP shall
|
||
|
not be initialized and the contents of \fIrwlock\fP are
|
||
|
undefined.
|
||
|
.LP
|
||
|
Only the object referenced by \fIrwlock\fP may be used for performing
|
||
|
synchronization. The result of referring to copies of
|
||
|
that object in calls to \fIpthread_rwlock_destroy\fP(), \fIpthread_rwlock_rdlock\fP(),
|
||
|
\fIpthread_rwlock_timedrdlock\fP(), \fIpthread_rwlock_timedwrlock\fP(),
|
||
|
\fIpthread_rwlock_tryrdlock\fP(), \fIpthread_rwlock_trywrlock\fP(),
|
||
|
\fIpthread_rwlock_unlock\fP(), or \fIpthread_rwlock_wrlock\fP() is
|
||
|
undefined.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
If successful, the \fIpthread_rwlock_destroy\fP() and \fIpthread_rwlock_init\fP()
|
||
|
functions shall return zero; otherwise, an
|
||
|
error number shall be returned to indicate the error.
|
||
|
.LP
|
||
|
The [EBUSY] and [EINVAL] error checks, if implemented, 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 \fIrwlock\fP.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_destroy\fP() function may fail if:
|
||
|
.TP 7
|
||
|
.B EBUSY
|
||
|
The implementation has detected an attempt to destroy the object referenced
|
||
|
by \fIrwlock\fP while it is locked.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The value specified by \fIrwlock\fP is invalid.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_init\fP() function shall fail if:
|
||
|
.TP 7
|
||
|
.B EAGAIN
|
||
|
The system lacked the necessary resources (other than memory) to initialize
|
||
|
another read-write lock.
|
||
|
.TP 7
|
||
|
.B ENOMEM
|
||
|
Insufficient memory exists to initialize the read-write lock.
|
||
|
.TP 7
|
||
|
.B EPERM
|
||
|
The caller does not have the privilege to perform the operation.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_init\fP() function may fail if:
|
||
|
.TP 7
|
||
|
.B EBUSY
|
||
|
The implementation has detected an attempt to reinitialize the object
|
||
|
referenced by \fIrwlock\fP, a previously initialized but
|
||
|
not yet destroyed read-write lock.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The value specified by \fIattr\fP is invalid.
|
||
|
.sp
|
||
|
.LP
|
||
|
These functions shall not return an error code of [EINTR].
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
Applications using these and related read-write lock functions may
|
||
|
be subject to priority inversion, as discussed in the Base
|
||
|
Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.285, Priority
|
||
|
Inversion.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIpthread_rwlock_rdlock\fP() , \fIpthread_rwlock_timedrdlock\fP()
|
||
|
, \fIpthread_rwlock_timedwrlock\fP() , \fIpthread_rwlock_tryrdlock\fP()
|
||
|
, \fIpthread_rwlock_trywrlock\fP() , \fIpthread_rwlock_unlock\fP()
|
||
|
, \fIpthread_rwlock_wrlock\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
||
|
\fI<pthread.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|