1 PTHREAD_RWLOCK_RDLOCK(3C)                         Standard C Library Functions
   2 
   3 
   4 
   5 NAME
   6        pthread_rwlock_rdlock, pthread_rwlock_tryrdlock - lock or attempt to
   7        lock read-write lock object for reading
   8 
   9 SYNOPSIS
  10        cc -mt [ flag... ] file... -lpthread [ library... ]
  11        #include <pthread.h>
  12 
  13        int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock);
  14 
  15 
  16        int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock);
  17 
  18 
  19 DESCRIPTION
  20        The pthread_rwlock_rdlock() function applies a read lock to the read-
  21        write lock referenced by rwlock.  The calling thread acquires the read
  22        lock if a writer does not hold the lock and there are no writers
  23        blocked on the lock.
  24 
  25 
  26        The calling thread does not acquire the lock if a writer holds the lock
  27        or if writers of higher or equal priority are blocked on the lock;
  28        otherwise, the calling thread acquires the lock. If the read lock is
  29        not acquired, the calling thread blocks until it can acquire the lock.
  30 
  31 
  32        A thread can hold multiple concurrent read locks on rwlock (that is,
  33        successfully call the pthread_rwlock_rdlock() function n times). If so,
  34        the thread must perform matching unlocks (that is, it must call the
  35        pthread_rwlock_unlock() function n times).
  36 
  37 
  38        The maximum number of concurrent read locks that a thread can hold on
  39        one read-write lock is currently set at 100,000, though this number
  40        could change in a future release. There is no imposed limit on the
  41        number of different threads that can apply a read lock to one read-
  42        write lock.
  43 
  44 
  45        The pthread_rwlock_tryrdlock() function applies a read lock like the
  46        pthread_rwlock_rdlock() function, with the exception that the function
  47        fails if the equivalent pthread_rwlock_rdlock() call would have blocked
  48        the calling thread.  In no case will the pthread_rwlock_tryrdlock()
  49        function ever block. It always either acquires the lock or fails and
  50        returns immediately.
  51 
  52 
  53        Results are undefined if any of these functions are called with an
  54        uninitialized read-write lock.
  55 
  56 
  57        If a signal is delivered to a thread waiting for a read-write lock for
  58        reading, upon return from the signal handler the thread resumes waiting
  59        for the read-write lock for reading as if it was not interrupted.
  60 
  61 RETURN VALUES
  62        If successful, the pthread_rwlock_rdlock() function returns 0.
  63        Otherwise, an error number is returned to indicate the error.
  64 
  65 
  66        The pthread_rwlock_tryrdlock() function returns 0 if the lock for
  67        reading on the read-write lock object referenced by rwlock is acquired.
  68        Otherwise an error number  is returned to indicate the error.
  69 
  70 ERRORS
  71        The pthread_rwlock_rdlock() and pthread_rwlock_tryrdlock() functions
  72        will fail if:
  73 
  74        EAGAIN
  75                  The read lock could not be acquired because the maximum
  76                  number of read locks by the current thread for rwlock has
  77                  been exceeded.
  78 
  79 
  80 
  81        The pthread_rwlock_rdlock() function will fail if:
  82 
  83        EDEADLK
  84                   The current thread already owns the read-write lock for
  85                   writing.
  86 
  87 
  88 
  89        The pthread_rwlock_tryrdlock() function will fail if:
  90 
  91        EBUSY
  92                 The read-write lock could not be acquired for reading because
  93                 a writer holds the lock or a writer with the appropriate
  94                 priority was blocked on it.
  95 
  96 
  97 ATTRIBUTES
  98        See  attributes(5) for descriptions of the following attributes:
  99 
 100 
 101 
 102 
 103        +--------------------+-----------------+
 104        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 105        +--------------------+-----------------+
 106        |Interface Stability | Standard        |
 107        +--------------------+-----------------+
 108        |MT-Level            | MT-Safe         |
 109        +--------------------+-----------------+
 110 
 111 SEE ALSO
 112        pthread_rwlock_init(3C), pthread_rwlock_wrlock(3C),
 113        pthread_rwlockattr_init(3C), pthread_rwlock_unlock(3C), attributes(5),
 114        standards(5)
 115 
 116 
 117 
 118                                 March 23, 2005       PTHREAD_RWLOCK_RDLOCK(3C)