Acquires a read-write lock for write access.

1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_wrlock (
             pthread_rwlock_t   *rwlock);

2  –  Arguments

 rwlock

    Address of the read-write lock object to acquire for write
    access.

3  –  Description

    This routine attempts to acquire a read-write lock for write
    access. If any thread already has acquired the lock for write
    access or read access, the lock is not granted and the calling
    thread blocks until it can acquire the lock. A thread can hold
    only one lock for write access on a read-write lock.

    Results are undefined if the calling thread holds the read-write
    lock (whether for read or write access) at the time 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 write access, upon
    return from the interrupt routine the thread resumes waiting for
    the lock as if it had not been interrupted.

    Realtime applications can encounter priority inversion when using
    read-write locks. The problem occurs when a high-priority thread
    acquires a read-write lock that is about to be unlocked (that
    is, posted) by a low-priority thread, but the low-priority thread
    is preempted by a medium-priority thread. This scenario leads to
    priority inversion in that a high-priority thread is blocked by
    lower-priority threads for an unlimited period of time. During
    system design, realtime programmers must take into account the
    possibility of priority inversion and can deal with it in a
    number of ways, such as by having critical sections that are
    guarded by read-write locks execute at a high priority, so that
    a thread cannot be preempted while executing in its critical
    section.

4  –  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 write access.
    [EDEADLCK]  The calling thread already owns the read-write lock
                for write or read access.
    [EINVAL]    The value specified by rwlock does not refer to an
                initialized read-write lock object.

5  –  Associated Routines

       pthread_rwlockattr_init()
       pthread_rwlock_init()
       pthread_rwlock_rdlock()
       pthread_rwlock_trywrlock()
       pthread_rwlock_unlock()