Acquires a read-write lock object for read access.

1  –  C Binding

    #include <pthread.h>

    int
    pthread_rwlock_rdlock (
             pthread_rwlock_t   *rwlock);

2  –  Arguments

 rwlock

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

3  –  Description

    This routine acquires a read-write lock for read access. If no
    thread already holds the lock for write access and there are no
    writers waiting to acquire the lock, the lock for read access
    is granted to the calling thread and this routine returns. If
    a thread already holds the lock for read access, the lock is
    granted and this routine returns.

    A thread can hold multiple, concurrent locks for read access on
    the same read-write lock. In a given thread, for each call to
    this routine that successfully acquires the same read-write lock
    for read access, a corresponding call to pthread_rwlock_unlock
    must be issued.

    If some thread already holds the lock for write access, the
    calling thread will not acquire the read lock. If the read lock
    is not acquired, the calling thread blocks until it can acquire
    the lock for read access. Results are undefined if the calling
    thread has already acquired a lock for write access on rwlock
    when 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 read access, upon
    return from the interrupt routine the thread resumes waiting for
    the lock as if it had not been interrupted.

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 read access.
    [EINVAL]    The value specified by rwlock does not refer to an
                initialized read-write lock object.
    [EDEADLCK]  The calling thread already owns the specified read-
                write lock object for write access.
    [EAGAIN]    The lock for read access could not be acquired
                because the maximum number of read lock acquisitions
                for rwlock has been exceeded.

5  –  Associated Routines

       pthread_rwlock_init()
       pthread_rwlockattr_init()
       pthread_rwlock_tryrdlock()
       pthread_rwlock_wrlock()
       pthread_rwlock_unlock()