/share/man/man3/pthread_rwlock_rdlock.3

  1.\" Copyright (c) 1998 Alex Nash
  2.\" All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  7.\" 1. Redistributions of source code must retain the above copyright
  8.\"    notice, this list of conditions and the following disclaimer.
  9.\" 2. Redistributions in binary form must reproduce the above copyright
 10.\"    notice, this list of conditions and the following disclaimer in the
 11.\"    documentation and/or other materials provided with the distribution.
 12.\"
 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 23.\" SUCH DAMAGE.
 24.\"
 25.\" $FreeBSD$
 26.\"
 27.Dd August 4, 1998
 28.Dt PTHREAD_RWLOCK_RDLOCK 3
 29.Os
 30.Sh NAME
 31.Nm pthread_rwlock_rdlock ,
 32.Nm pthread_rwlock_tryrdlock
 33.Nd acquire a read/write lock for reading
 34.Sh LIBRARY
 35.Lb libpthread
 36.Sh SYNOPSIS
 37.In pthread.h
 38.Ft int
 39.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
 40.Ft int
 41.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
 42.Sh DESCRIPTION
 43The
 44.Fn pthread_rwlock_rdlock
 45function acquires a read lock on
 46.Fa lock
 47provided that
 48.Fa lock
 49is not presently held for writing and no writer threads are
 50presently blocked on the lock.
 51If the read lock cannot be
 52immediately acquired, the calling thread blocks until it can
 53acquire the lock.
 54.Pp
 55The
 56.Fn pthread_rwlock_tryrdlock
 57function performs the same action, but does not block if the lock
 58cannot be immediately obtained (i.e., the lock is held for writing
 59or there are waiting writers).
 60.Pp
 61A thread may hold multiple concurrent read locks.
 62If so,
 63.Fn pthread_rwlock_unlock
 64must be called once for each lock obtained.
 65.Pp
 66The results of acquiring a read lock while the calling thread holds
 67a write lock are undefined.
 68.Sh IMPLEMENTATION NOTES
 69To prevent writer starvation, writers are favored over readers.
 70.Sh RETURN VALUES
 71If successful, the
 72.Fn pthread_rwlock_rdlock
 73and
 74.Fn pthread_rwlock_tryrdlock
 75functions will return zero.
 76Otherwise an error number will be returned
 77to indicate the error.
 78.Sh ERRORS
 79The
 80.Fn pthread_rwlock_tryrdlock
 81function will fail if:
 82.Bl -tag -width Er
 83.It Bq Er EBUSY
 84The lock could not be acquired because a writer holds the lock or
 85was blocked on it.
 86.El
 87.Pp
 88The
 89.Fn pthread_rwlock_rdlock
 90and
 91.Fn pthread_rwlock_tryrdlock
 92functions may fail if:
 93.Bl -tag -width Er
 94.It Bq Er EAGAIN
 95The lock could not be acquired because the maximum number of read locks
 96against
 97.Fa lock
 98has been exceeded.
 99.It Bq Er EDEADLK
100The current thread already owns
101.Fa lock
102for writing.
103.It Bq Er EINVAL
104The value specified by
105.Fa lock
106is invalid.
107.It Bq Er ENOMEM
108Insufficient memory exists to initialize the lock (applies to
109statically initialized locks only).
110.El
111.Sh SEE ALSO
112.Xr pthread_rwlock_init 3 ,
113.Xr pthread_rwlock_trywrlock 3 ,
114.Xr pthread_rwlock_unlock 3 ,
115.Xr pthread_rwlock_wrlock 3
116.Sh STANDARDS
117The
118.Fn pthread_rwlock_rdlock
119and
120.Fn pthread_rwlock_tryrdlock
121functions are expected to conform to
122.St -susv2 .
123.Sh HISTORY
124The
125.Fn pthread_rwlock_rdlock
126function first appeared in
127.Fx 3.0 .