1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. 44.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. 45.\" Copyright 2024 Oxide Computer Company 46.\" 47.Dd June 23, 2024 48.Dt PTHREAD_RWLOCK_TIMEDWRLOCK 3C 49.Os 50.Sh NAME 51.Nm pthread_rwlock_clockwdlock , 52.Nm pthread_rwlock_timedwdlock , 53.Nm pthread_rwlock_relclockwdlock_np , 54.Nm pthread_rwlock_reltimedwdlock_np 55.Nd lock a read-write lock for writing 56.Sh LIBRARY 57.Lb libc 58.Sh SYNOPSIS 59.In pthread.h 60.In time.h 61.Ft int 62.Fo pthread_rwlock_clockwdlock 63.Fa "pthread_rwlock_t *restrict rwlock" 64.Fa "clockid_t clock" 65.Fa "const struct timespec *restrict abstime" 66.Fc 67.Ft int 68.Fo pthread_rwlock_timedwdlock 69.Fa "pthread_rwlock_t *restrict rwlock" 70.Fa "const struct timespec *restrict abstime" 71.Fc 72.Ft int 73.Fo pthread_rwlock_relclockwdlock_np 74.Fa "pthread_rwlock_t *restrict rwlock" 75.Fa "clockid_t clock" 76.Fa "const struct timespec *restrict reltime" 77.Fc 78.Ft int 79.Fo pthread_rwlock_reltimedwdlock_np 80.Fa "pthread_rwlock_t *restrict rwlock" 81.Fa "const struct timespec *restrict reltime" 82.Fc 83.Sh DESCRIPTION 84The 85.Fn pthread_rwlock_clockwdlock , 86.Fn pthread_rwlock_timerwdlock , 87.Fn pthread_rwlock_relclockwdlock_np , 88and 89.Fn pthread_rwlock_reltimewrdlock_np 90functions apply a read lock to the read-write lock referenced by 91.Fa rwlock . 92The calling thread will acquire a write lock if there are no readers or 93writers holding the lock, or pending writers. 94However, if the read-write lock 95.Fa rwlock 96is not available, the calling thread will be suspended and wait for the 97lock to become avaialble. 98If the lock does not become available within a specified timeout, then 99the function call will terminate without acquiring the lock and return 100the 101.Er ETIMEDOUT 102error. 103These functions all differ in terms of how the timeout is specified and 104the clock that is used to determine when the timeout has elapsed. 105.Pp 106In general, the system provides the ability to program timeouts against 107either the realtime clock, 108.Dv CLOCK_REALTIME , 109which measure, the wall clock and is subject to changes due to time 110synchronization daemons such as NTP and PTP, or the high-resolution clock, 111.Dv CLOCK_HIGHRES , 112which is a non-adjustable high-resolution clock that is provided by 113system hardware. 114The specified timeout may either be specified as an absolute time in the 115future or as a relative amount of time that should elapse. 116Each clock has its own resolution, which can be determined by 117.Xr clock_getres 3C . 118Timeouts may be rounded up to a given clock's resolution. 119Due to scheduling effects, it is possible that more time may elapse than 120was specified in the timeout when the caller does not successfully 121acquire the lock. 122The 123.Fn pthread_rwlock_clockwrlock 124and 125.Fn pthread_rwlock_relclockwrlock_np 126functions allow the clock source to be used to be specified by the 127.Fa clock 128argument. 129While there are additional clocks in the system, only 130.Dv CLOCK_REALTIME 131or 132.Dv CLOCK_HIGHRES 133may be specified. 134The thread and process-specific CPU time clocks cannot be used. 135Conversely, the 136.Fn pthread_rwlock_timedwrlock 137and 138.Fn pthread_rwlock_reltimedwrlock_np 139functions will always utilize the realtime clock, 140.Dv CLOCK_REALTIME . 141.Pp 142The 143.Fn pthread_rwlock_clockwrlock 144and 145.Fn pthread_rwlock_timedwrlock 146functions treat the timeout value, 147.Fa abstime , 148as the absolute time in the future when the timeout should expire. 149Conversely, the 150.Fn pthread_rwlock_relclockwrlock_np 151and 152.Fn pthread_rwlock_reltimedwrlock_np 153functions operate in terms of a relative time. 154The timer will expire when a specified amount of time passes on the 155clock specified as indicated by 156.Fa reltime . 157If the read-write lock, 158.Fa rwlock , 159can be immediately write-locked, then the timeout value is ignored 160entirely, Even if the timeout had already expired or represented a 161value that didn't make sense. 162Both are only checked if the thread would block on the read-write lock 163itself. 164.Pp 165Similarly, if a signal that causes a signal handler to be executed is 166delivered to a thread blocked on a read-write lock, then upon return 167from the signal handler, the thread resumes waiting for the lock as 168though it was not interrupted. 169.Pp 170It is illegal for a thread to acquire a write lock on the same read-write 171lock that it already holds either a read or write lock on. 172.Sh RETURN VALUES 173Upon successful completion, the 174.Fn pthread_rwlock_clockwrlock , 175.Fn pthread_rwlock_timerwrlock , 176.Fn pthread_rwlock_relclockwrlock_np , 177and 178.Fn pthread_rwlock_reltimerwrlock_np 179return 180.Sy 0 181and have successfully acquired a write lock on 182.Fa rwlock . 183Otherwise, an error number is returned to indicate the error. 184.Sh ERRORS 185The 186.Fn pthread_rwlock_clockwrlock , 187.Fn pthread_rwlock_timerwrlock , 188.Fn pthread_rwlock_relclockwrlock_np , 189and 190.Fn pthread_rwlock_reltimerwrlock_np 191will fail if: 192.Bl -tag -width Er 193.It Er EDEADLK 194The calling thread already has a read or write lock on 195.Fa rwlock 196.It Er EINVAL 197The value specified by 198.Fa rwlock 199does not refer to an initialized read-write 200lock object. 201The timeout nanosecond value is less than zero or greater than 202or equal to 1,000 million. 203.Pp 204For 205.Fn pthread_rwlock_clockwrlock 206and 207.Fn pthread_rwlock_relclockwrlock_np 208the value of 209.Fa clock 210is either unsupported for locking or unknown to the system. 211.It Er ETIMEDOUT 212The lock could not be acquired before the specified timeout expired. 213.El 214.Sh INTERFACE STABILITY 215.Sy Committed 216.Sh MT-LEVEL 217.Sy MT-Safe 218.Sh SEE ALSO 219.Xr clock_getres 3C , 220.Xr pthread_rwlock_destroy 3C , 221.Xr pthread_rwlock_rdlock 3C , 222.Xr pthread_rwlock_timedrdlock 3C , 223.Xr pthread_rwlock_tryrdlock 3C , 224.Xr pthread_rwlock_trywrlock 3C , 225.Xr pthread_rwlock_unlock 3C , 226.Xr pthread_rwlock_wrlock 3C , 227.Xr attributes 7 , 228.Xr standards 7 229