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