Initializes a read-write lock object.

1  –  C Binding

    #include <pthread.h>

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

2  –  Arguments

 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.

3  –  Description

    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.

    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;

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.
    [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.

5  –  Associated Routines

       pthread_rwlock_destroy()