PTHREAD_RWLOCK_DESTROY(3P)                          POSIX Programmer's Manual                         PTHREAD_RWLOCK_DESTROY(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       pthread_rwlock_destroy, pthread_rwlock_init - destroy and initialize a read-write lock object

SYNOPSIS
       #include <pthread.h>

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


DESCRIPTION
       The  pthread_rwlock_destroy()  function  shall  destroy  the  read-write lock object referenced by rwlock 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 pthread_rwlock_init(). An implementation may cause pthread_rwlock_destroy() to set the object referenced
       by rwlock to an invalid value. Results are undefined if pthread_rwlock_destroy() is called when any thread holds  rwlock.
       Attempting to destroy an uninitialized read-write lock results in undefined behavior.

       The  pthread_rwlock_init() function shall allocate any resources required to use the read-write lock referenced by rwlock
       and initializes the lock to an unlocked state with attributes referenced by attr. If attr 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
       pthread_rwlock_init()  is called specifying an already initialized read-write lock. Results are undefined if a read-write
       lock is used without first being initialized.

       If the pthread_rwlock_init() function fails, rwlock shall not be initialized and the contents of rwlock are undefined.

       Only the object referenced by rwlock may be used for performing synchronization. The result of  referring  to  copies  of
       that    object    in    calls   to   pthread_rwlock_destroy(),   pthread_rwlock_rdlock(),   pthread_rwlock_timedrdlock(),
       pthread_rwlock_timedwrlock(),   pthread_rwlock_tryrdlock(),   pthread_rwlock_trywrlock(),   pthread_rwlock_unlock(),   or
       pthread_rwlock_wrlock() is undefined.

RETURN VALUE
       If  successful,  the  pthread_rwlock_destroy() and pthread_rwlock_init() functions shall return zero; otherwise, an error
       number shall be returned to indicate the error.

       The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of pro-
       cessing  for  the  function  and  caused an error return prior to modifying the state of the read-write lock specified by
       rwlock.

ERRORS
       The pthread_rwlock_destroy() function may fail if:

       EBUSY  The implementation has detected an attempt to destroy the object referenced by rwlock while it is locked.

       EINVAL The value specified by rwlock is invalid.


       The pthread_rwlock_init() function shall fail if:

       EAGAIN The system lacked the necessary resources (other than memory) to initialize another read-write lock.

       ENOMEM Insufficient memory exists to initialize the read-write lock.

       EPERM  The caller does not have the privilege to perform the operation.


       The pthread_rwlock_init() function may fail if:

       EBUSY  The implementation has detected an attempt to reinitialize the object referenced by rwlock, a previously  initial-
              ized but not yet destroyed read-write lock.

       EINVAL The value specified by attr is invalid.


       These functions shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       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.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       pthread_rwlock_rdlock(),    pthread_rwlock_timedrdlock(),    pthread_rwlock_timedwrlock(),    pthread_rwlock_tryrdlock(),
       pthread_rwlock_trywrlock(),   pthread_rwlock_unlock(),   pthread_rwlock_wrlock(),   the   Base   Definitions   volume  of
       IEEE Std 1003.1-2001, <pthread.h>

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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                    PTHREAD_RWLOCK_DESTROY(3P)