git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	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
	37	.Fo pthread_rwlock_rdlock
	38	.Fa "pthread_rwlock_t *rwlock"
	39	.Fc
	40	.Ft int
	41	.Fo pthread_rwlock_tryrdlock
	42	.Fa "pthread_rwlock_t *rwlock"
	43	.Fc
	44	.Sh DESCRIPTION
	45	The
	46	.Fn pthread_rwlock_rdlock
	47	function acquires a read lock on
	48	.Fa rwlock ,
	49	provided that
	50	.Fa rwlock
	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
	59	cannot be immediately obtained (i.e., the lock is held for writing
	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
	75	functions will return zero.
	76	Otherwise, an error number will be returned to indicate the error.
	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
	95	The lock could not be acquired, because a writer holds the lock or
	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
	106	The lock could not be acquired, because the maximum number of read locks
	107	against
	108	.Fa lock
	109	has been exceeded.
	110	.It Bq Er EDEADLK
	111	The current thread already owns
	112	.Fa rwlock
	113	for writing.
	114	.It Bq Er EINVAL
	115	The value specified by
	116	.Fa rwlock
	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 .