[apple/libc.git] / pthreads / pthread_rwlock_rdlock.3

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