~ubuntu-branches/ubuntu/precise/manpages-posix/precise

.\" 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 .