1.\" Copyright (c) 2004 Michael Telahun Makonnen 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$ 26.\" 27.Dd August 17, 2018 28.Dt PTHREAD_RWLOCK_TIMEDWRLOCK 3 29.Os 30.Sh NAME 31.Nm pthread_rwlock_timedwrlock 32.Nd "acquire a read-write lock for writing or give up after a specified period" 33.Sh LIBRARY 34.Lb libpthread 35.Sh SYNOPSIS 36.In pthread.h 37.Ft int 38.Fn pthread_rwlock_timedwrlock "pthread_rwlock_t *restrict rwlock" "const struct timespec *restrict abs_timeout" 39.Sh DESCRIPTION 40This function acquires a write lock on the read-write lock 41.Fa rwlock . 42However, if the lock cannot be 43acquired without waiting for another thread to 44unlock the lock, 45this wait shall be terminated when 46.Fa abs_timeout 47expires. 48.Pp 49If the thread should be interrupted by a signal, 50the 51.Fn pthread_rwlock_timedwrlock 52function will be automatically restarted after the thread returns from 53the signal handler. 54.Pp 55The calling thread may deadlock if 56at the time the call is made it holds 57.Fa rwlock . 58The results are undefined if this function is called with 59an uninitialized read-write lock. 60.Sh IMPLEMENTATION NOTES 61To prevent writer starvation, writers are favored over readers. 62.Sh RETURN VALUES 63If successful, the 64.Fn pthread_rwlock_timedwrlock 65function will return zero. 66Otherwise, an error number will be returned to indicate the error. 67.Pp 68This function shall not return an error code of 69.Er EINTR . 70.Sh ERRORS 71The 72.Fn pthread_rwlock_timedwrlock 73function shall fail if: 74.Bl -tag -width Er 75.It Bq Er ETIMEDOUT 76The lock could not be acquired before the specified timeout expired. 77.El 78.Pp 79The 80.Fn pthread_rwlock_timedwrlock 81function may fail if: 82.Bl -tag -width Er 83.It Bq Er EDEADLK 84The calling thread already holds 85.Fa rwlock . 86.It Bq Er EINVAL 87The value specified by 88.Fa rwlock 89does not refer to an initialized read-write lock object, 90or the 91.Fa abs_timeout 92nanosecond value is less than zero or 93greater than or equal to 1 billion. 94.El 95.Sh SEE ALSO 96.Xr pthread_rwlock_init 3 , 97.Xr pthread_rwlock_timedrdlock 3 , 98.Xr pthread_rwlock_unlock 3 99.Sh STANDARDS 100The 101.Fn pthread_rwlock_timedwrlock 102function is expected to conform to 103.St -p1003.1-96 . 104.Sh HISTORY 105The 106.Fn pthread_rwlock_timedwrlock 107function first appeared in 108.Fx 5.2 . 109