xref: /freebsd/share/man/man3/pthread_rwlock_timedwrlock.3 (revision ef13db44d1278eaa50be8ba6303f06a5a6011c4d)
1104ff764SMike Makonnen.\" Copyright (c) 2004 Michael Telahun Makonnen
2104ff764SMike Makonnen.\" All rights reserved.
3104ff764SMike Makonnen.\"
4104ff764SMike Makonnen.\" Redistribution and use in source and binary forms, with or without
5104ff764SMike Makonnen.\" modification, are permitted provided that the following conditions
6104ff764SMike Makonnen.\" are met:
7104ff764SMike Makonnen.\" 1. Redistributions of source code must retain the above copyright
8104ff764SMike Makonnen.\"    notice, this list of conditions and the following disclaimer.
9104ff764SMike Makonnen.\" 2. Redistributions in binary form must reproduce the above copyright
10104ff764SMike Makonnen.\"    notice, this list of conditions and the following disclaimer in the
11104ff764SMike Makonnen.\"    documentation and/or other materials provided with the distribution.
12104ff764SMike Makonnen.\"
13104ff764SMike Makonnen.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14104ff764SMike Makonnen.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15104ff764SMike Makonnen.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16104ff764SMike Makonnen.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17104ff764SMike Makonnen.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18104ff764SMike Makonnen.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19104ff764SMike Makonnen.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20104ff764SMike Makonnen.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21104ff764SMike Makonnen.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22104ff764SMike Makonnen.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23104ff764SMike Makonnen.\" SUCH DAMAGE.
24104ff764SMike Makonnen.\"
25104ff764SMike Makonnen.\" $FreeBSD$
26104ff764SMike Makonnen.\"
27104ff764SMike Makonnen.Dd January 16, 2004
28104ff764SMike Makonnen.Dt PTHREAD_RWLOCK_TIMEDWRLOCK 3
29104ff764SMike Makonnen.Os
30104ff764SMike Makonnen.Sh NAME
31ef13db44SRuslan Ermilov.Nm pthread_rwlock_timedwrlock
32ef13db44SRuslan Ermilov.Nd "acquire a read-write lock for writing or give up after a specified period"
33104ff764SMike Makonnen.Sh LIBRARY
34104ff764SMike Makonnen.Lb libpthread
35104ff764SMike Makonnen.Lb libthr
36104ff764SMike Makonnen.Sh SYNOPSIS
37104ff764SMike Makonnen.In pthread.h
38104ff764SMike Makonnen.Ft int
39104ff764SMike Makonnen.Fn pthread_rwlock_timedwrlock "pthread_rwlock_t *rwlock" "const struct timespec *abs_timeout"
40104ff764SMike Makonnen.Sh DESCRIPTION
41104ff764SMike MakonnenThis function acquires a write lock on the read-write lock
42104ff764SMike Makonnen.Fa rwlock .
43104ff764SMike MakonnenHowever, if the lock cannot be
44104ff764SMike Makonnenacquired without waiting for another thread to
45104ff764SMike Makonnenunlock the lock,
46104ff764SMike Makonnenthis wait shall be terminated when
47104ff764SMike Makonnen.Fa abs_timeout
48104ff764SMike Makonnenexpires.
49104ff764SMike Makonnen.Pp
50104ff764SMike MakonnenIf the thread should be interrupted by a signal,
51104ff764SMike Makonnenthe
52ef13db44SRuslan Ermilov.Fn pthread_rwlock_timedwrlock
53104ff764SMike Makonnenfunction will be automatically restarted after the thread returns from
54104ff764SMike Makonnenthe signal handler.
55104ff764SMike Makonnen.Pp
56104ff764SMike MakonnenThe calling thread may deadlock if
57104ff764SMike Makonnenat the time the call is made it holds
58104ff764SMike Makonnen.Fa rwlock .
59104ff764SMike MakonnenThe results are undefined if this function is called with
60104ff764SMike Makonnenan uninitialized read-write lock.
61104ff764SMike Makonnen.Sh IMPLEMENTATION NOTES
62104ff764SMike MakonnenTo prevent writer starvation, writers are favored over readers.
63104ff764SMike Makonnen.Sh RETURN VALUES
64104ff764SMike MakonnenIf successful, the
65104ff764SMike Makonnen.Fn pthread_rwlock_timedwrlock
66ef13db44SRuslan Ermilovfunction will return zero.
67ef13db44SRuslan ErmilovOtherwise, an error number will be returned to indicate the error.
68104ff764SMike Makonnen.Pp
69ef13db44SRuslan ErmilovThis function shall not return an error code of
70ef13db44SRuslan Ermilov.Er EINTR .
71104ff764SMike Makonnen.Sh ERRORS
72104ff764SMike MakonnenThe
73104ff764SMike Makonnen.Fn pthread_rwlock_timedwrlock
74104ff764SMike Makonnenfunction shall fail if:
75104ff764SMike Makonnen.Bl -tag -width Er
76104ff764SMike Makonnen.It Bq Er ETIMEDOUT
77ef13db44SRuslan ErmilovThe lock could not be acquired before the specified timeout expired.
78104ff764SMike Makonnen.El
79104ff764SMike Makonnen.Pp
80104ff764SMike MakonnenThe
81104ff764SMike Makonnen.Fn pthread_rwlock_timedrwlock
82104ff764SMike Makonnenfunction may fail if:
83104ff764SMike Makonnen.Bl -tag -width Er
84104ff764SMike Makonnen.It Bq Er EDEADLK
85104ff764SMike MakonnenThe calling thread already holds
86104ff764SMike Makonnen.Fa rwlock .
87104ff764SMike Makonnen.It Bq Er EINVAL
88104ff764SMike MakonnenThe value specified by
89104ff764SMike Makonnen.Fa rwlock
90104ff764SMike Makonnendoes not refer to an initialized read-write lock object,
91104ff764SMike Makonnenor the
92ef13db44SRuslan Ermilov.Fa abs_timeout
93ef13db44SRuslan Ermilovnanosecond value is less than zero or
94104ff764SMike Makonnengreater than or equal to 1 billion.
95104ff764SMike Makonnen.El
96104ff764SMike Makonnen.Sh SEE ALSO
97104ff764SMike Makonnen.Xr pthread_rwlock_init 3 ,
98ef13db44SRuslan Ermilov.Xr pthread_rwlock_timedrdlock 3 ,
99ef13db44SRuslan Ermilov.Xr pthread_rwlock_unlock 3
100104ff764SMike Makonnen.Sh STANDARDS
101104ff764SMike MakonnenThe
102104ff764SMike Makonnen.Fn pthread_rwlock_timedwrlock
103104ff764SMike Makonnenfunction is expected to conform to
104104ff764SMike Makonnen.St -p1003.1-96 .
105104ff764SMike Makonnen.Sh HISTORY
106104ff764SMike MakonnenThe
107104ff764SMike Makonnen.Fn pthread_rwlock_timedwrlock
108104ff764SMike Makonnenfunction first appeared in
109104ff764SMike Makonnen.Fx 5.2 .
110