Move pthread* manpages to lib/libpthread as they are not libc_r specific.
[dragonfly.git] / lib / libpthread / pthread_rwlock_wrlock.3
CommitLineData
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.\"
25.\" $FreeBSD: src/lib/libc_r/man/pthread_rwlock_wrlock.3,v 1.2.2.2 2001/12/17 10:08:26 ru Exp $
0b84df5c 26.\" $DragonFly: src/lib/libc_r/man/pthread_rwlock_wrlock.3,v 1.3 2006/02/17 19:35:07 swildner Exp $
984263bc
MD
27.\"
28.Dd August 4, 1998
29.Dt PTHREAD_RWLOCK_WRLOCK 3
30.Os
31.Sh NAME
32.Nm pthread_rwlock_wrlock ,
33.Nm pthread_rwlock_trywrlock
34.Nd acquire a read/write lock for writing
35.Sh LIBRARY
36.Lb libc_r
37.Sh SYNOPSIS
38.In pthread.h
39.Ft int
40.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
41.Ft int
42.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
43.Sh DESCRIPTION
44The
45.Fn pthread_rwlock_wrlock
46function blocks until a write lock can be acquired against
47.Fa lock .
48The
49.Fn pthread_rwlock_trywrlock
50function performs the same action, but does not block if the lock
51cannot be immediately obtained.
52.Pp
53The results are undefined if the calling thread already holds the
54lock at the time the call is made.
55.Sh IMPLEMENTATION NOTES
56To prevent writer starvation, writers are favored over readers.
57.Sh RETURN VALUES
58If successful, the
59.Fn pthread_rwlock_wrlock
60and
61.Fn pthread_rwlock_trywrlock
62functions will return zero. Otherwise an error number will be returned
63to indicate the error.
984263bc
MD
64.Sh ERRORS
65The
66.Fn pthread_rwlock_trywrlock
67function will fail if:
68.Bl -tag -width Er
69.It Bq Er EBUSY
70The calling thread is not able to acquire the lock without blocking.
71.El
72.Pp
73The
74.Fn pthread_rwlock_wrlock
75and
76.Fn pthread_rwlock_trywrlock
77functions may fail if:
78.Bl -tag -width Er
79.It Bq Er EDEADLK
80The calling thread already owns the read/write lock (for reading
81or writing).
82.It Bq Er EINVAL
83The value specified by
84.Fa lock
85is invalid.
86.It Bq Er ENOMEM
87Insufficient memory exists to initialize the lock (applies to
88statically initialized locks only).
89.El
0b84df5c
SW
90.Sh SEE ALSO
91.Xr pthread_rwlock_trywrlock 3 ,
92.Xr pthread_rwlock_unlock 3 ,
93.Xr pthread_rwlock_wrlock 3
94.Sh STANDARDS
95The
96.Fn pthread_rwlock_wrlock
97and
98.Fn pthread_rwlock_trywrlock
99functions are expected to conform to
100.St -susv2 .
984263bc
MD
101.Sh HISTORY
102The
103.Fn pthread_rwlock_wrlock
104function first appeared in
105.Fx 3.0 .