gitweb.dragonflybsd.org Git - dragonfly.git/blame - lib/libpthread/pthread_rwlock

Commit	Line	Data
984263bc MD	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	.\"
15acf97d	25	.\" $FreeBSD: src/share/man/man3/pthread_rwlock_rdlock.3,v 1.10 2007/10/22 10:08:00 ru Exp $
984263bc	26	.\"
15acf97d	27	.Dd July 10, 2009
984263bc MD	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
9964d5ef	35	.Lb libpthread
984263bc MD	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
	43	The
	44	.Fn pthread_rwlock_rdlock
	45	function acquires a read lock on
	46	.Fa lock
	47	provided that
	48	.Fa lock
	49	is not presently held for writing and no writer threads are
15acf97d SW	50	presently blocked on the lock.
15acf97d SW	51	If the read lock cannot be
984263bc MD	52	immediately acquired, the calling thread blocks until it can
	53	acquire the lock.
	54	.Pp
	55	The
	56	.Fn pthread_rwlock_tryrdlock
	57	function performs the same action, but does not block if the lock
15acf97d	58	cannot be immediately obtained (i.e., the lock is held for writing
984263bc MD	59	or there are waiting writers).
984263bc MD	60	.Pp
15acf97d SW	61	A thread may hold multiple concurrent read locks.
15acf97d SW	62	If so,
984263bc MD	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
15acf97d SW	75	functions will return zero.
15acf97d SW	76	Otherwise an error number will be returned
984263bc	77	to indicate the error.
984263bc MD	78	.Sh ERRORS
	79	The
	80	.Fn pthread_rwlock_tryrdlock
	81	function will fail if:
	82	.Bl -tag -width Er
	83	.It Bq Er EBUSY
	84	The lock could not be acquired because a writer holds the lock or
	85	was blocked on it.
	86	.El
	87	.Pp
	88	The
	89	.Fn pthread_rwlock_rdlock
	90	and
	91	.Fn pthread_rwlock_tryrdlock
	92	functions may fail if:
	93	.Bl -tag -width Er
	94	.It Bq Er EAGAIN
	95	The lock could not be acquired because the maximum number of read locks
	96	against
	97	.Fa lock
	98	has been exceeded.
	99	.It Bq Er EDEADLK
	100	The current thread already owns
	101	.Fa lock
	102	for writing.
	103	.It Bq Er EINVAL
	104	The value specified by
	105	.Fa lock
	106	is invalid.
	107	.It Bq Er ENOMEM
	108	Insufficient memory exists to initialize the lock (applies to
	109	statically initialized locks only).
	110	.El
0b84df5c SW	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
	117	The
	118	.Fn pthread_rwlock_rdlock
	119	and
	120	.Fn pthread_rwlock_tryrdlock
	121	functions are expected to conform to
	122	.St -susv2 .
984263bc MD	123	.Sh HISTORY
	124	The
	125	.Fn pthread_rwlock_rdlock
	126	function first appeared in
	127	.Fx 3.0 .