166492cf0SYuri Pankov.\" 266492cf0SYuri Pankov.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 366492cf0SYuri Pankov.\" permission to reproduce portions of its copyrighted documentation. 466492cf0SYuri Pankov.\" Original documentation from The Open Group can be obtained online at 5c10c16deSRichard Lowe.\" http://www.opengroup.org/bookstore/. 666492cf0SYuri Pankov.\" 766492cf0SYuri Pankov.\" The Institute of Electrical and Electronics Engineers and The Open 866492cf0SYuri Pankov.\" Group, have given us permission to reprint portions of their 966492cf0SYuri Pankov.\" documentation. 1066492cf0SYuri Pankov.\" 1166492cf0SYuri Pankov.\" In the following statement, the phrase ``this text'' refers to portions 1266492cf0SYuri Pankov.\" of the system documentation. 1366492cf0SYuri Pankov.\" 1466492cf0SYuri Pankov.\" Portions of this text are reprinted and reproduced in electronic form 1566492cf0SYuri Pankov.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 1666492cf0SYuri Pankov.\" Standard for Information Technology -- Portable Operating System 1766492cf0SYuri Pankov.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 1866492cf0SYuri Pankov.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 1966492cf0SYuri Pankov.\" Engineers, Inc and The Open Group. In the event of any discrepancy 2066492cf0SYuri Pankov.\" between these versions and the original IEEE and The Open Group 2166492cf0SYuri Pankov.\" Standard, the original IEEE and The Open Group Standard is the referee 2266492cf0SYuri Pankov.\" document. The original Standard can be obtained online at 2366492cf0SYuri Pankov.\" http://www.opengroup.org/unix/online.html. 2466492cf0SYuri Pankov.\" 25c10c16deSRichard Lowe.\" This notice shall appear on any product containing this material. 2666492cf0SYuri Pankov.\" 2766492cf0SYuri Pankov.\" The contents of this file are subject to the terms of the 2866492cf0SYuri Pankov.\" Common Development and Distribution License (the "License"). 2966492cf0SYuri Pankov.\" You may not use this file except in compliance with the License. 3066492cf0SYuri Pankov.\" 3166492cf0SYuri Pankov.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 3266492cf0SYuri Pankov.\" or http://www.opensolaris.org/os/licensing. 3366492cf0SYuri Pankov.\" See the License for the specific language governing permissions 3466492cf0SYuri Pankov.\" and limitations under the License. 3566492cf0SYuri Pankov.\" 3666492cf0SYuri Pankov.\" When distributing Covered Code, include this CDDL HEADER in each 3766492cf0SYuri Pankov.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 3866492cf0SYuri Pankov.\" If applicable, add the following below this CDDL HEADER, with the 3966492cf0SYuri Pankov.\" fields enclosed by brackets "[]" replaced with your own identifying 4066492cf0SYuri Pankov.\" information: Portions Copyright [yyyy] [name of copyright owner] 4166492cf0SYuri Pankov.\" 4266492cf0SYuri Pankov.\" 4366492cf0SYuri Pankov.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. 4466492cf0SYuri Pankov.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. 45*8b6b46dcSRobert Mustacchi.\" Copyright 2024 Oxide Computer Company 4666492cf0SYuri Pankov.\" 47*8b6b46dcSRobert Mustacchi.Dd June 23, 2024 48*8b6b46dcSRobert Mustacchi.Dt PTHREAD_RWLOCK_TIMEDRDLOCK 3C 49*8b6b46dcSRobert Mustacchi.Os 50*8b6b46dcSRobert Mustacchi.Sh NAME 51*8b6b46dcSRobert Mustacchi.Nm pthread_rwlock_clockrdlock , 52*8b6b46dcSRobert Mustacchi.Nm pthread_rwlock_timedrdlock , 53*8b6b46dcSRobert Mustacchi.Nm pthread_rwlock_relclockrdlock_np , 54*8b6b46dcSRobert Mustacchi.Nm pthread_rwlock_reltimedrdlock_np 55*8b6b46dcSRobert Mustacchi.Nd lock a read-write lock for reading 56*8b6b46dcSRobert Mustacchi.Sh LIBRARY 57*8b6b46dcSRobert Mustacchi.Lb libc 58*8b6b46dcSRobert Mustacchi.Sh SYNOPSIS 59*8b6b46dcSRobert Mustacchi.In pthread.h 60*8b6b46dcSRobert Mustacchi.In time.h 61*8b6b46dcSRobert Mustacchi.Ft int 62*8b6b46dcSRobert Mustacchi.Fo pthread_rwlock_clockrdlock 63*8b6b46dcSRobert Mustacchi.Fa "pthread_rwlock_t *restrict rwlock" 64*8b6b46dcSRobert Mustacchi.Fa "clockid_t clock" 65*8b6b46dcSRobert Mustacchi.Fa "const struct timespec *restrict abstime" 66*8b6b46dcSRobert Mustacchi.Fc 67*8b6b46dcSRobert Mustacchi.Ft int 68*8b6b46dcSRobert Mustacchi.Fo pthread_rwlock_timedrdlock 69*8b6b46dcSRobert Mustacchi.Fa "pthread_rwlock_t *restrict rwlock" 70*8b6b46dcSRobert Mustacchi.Fa "const struct timespec *restrict abstime" 71*8b6b46dcSRobert Mustacchi.Fc 72*8b6b46dcSRobert Mustacchi.Ft int 73*8b6b46dcSRobert Mustacchi.Fo pthread_rwlock_relclockrdlock_np 74*8b6b46dcSRobert Mustacchi.Fa "pthread_rwlock_t *restrict rwlock" 75*8b6b46dcSRobert Mustacchi.Fa "clockid_t clock" 76*8b6b46dcSRobert Mustacchi.Fa "const struct timespec *restrict reltime" 77*8b6b46dcSRobert Mustacchi.Fc 78*8b6b46dcSRobert Mustacchi.Ft int 79*8b6b46dcSRobert Mustacchi.Fo pthread_rwlock_reltimedrdlock_np 80*8b6b46dcSRobert Mustacchi.Fa "pthread_rwlock_t *restrict rwlock" 81*8b6b46dcSRobert Mustacchi.Fa "const struct timespec *restrict reltime" 82*8b6b46dcSRobert Mustacchi.Fc 83*8b6b46dcSRobert Mustacchi.Sh DESCRIPTION 84*8b6b46dcSRobert MustacchiThe 85*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_clockrdlock , 86*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_timerrdlock , 87*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_relclockrdlock_np , 88*8b6b46dcSRobert Mustacchiand 89*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_reltimerrdlock_np 90*8b6b46dcSRobert Mustacchifunctions apply a read lock to the read-write lock referenced by 91*8b6b46dcSRobert Mustacchi.Fa rwlock . 92*8b6b46dcSRobert MustacchiThe calling thread will acquire a read lock if there are no writers 93*8b6b46dcSRobert Mustacchicurrently holding the lock and no writers that are blocking to acquire a 94*8b6b46dcSRobert Mustacchilock 95*8b6b46dcSRobert Mustacchi.Pq writers starve readers . 96*8b6b46dcSRobert MustacchiHowever, if the read-write lock 97*8b6b46dcSRobert Mustacchi.Fa rwlock 98*8b6b46dcSRobert Mustacchiis not available, the calling thread will be suspended and wait for the 99*8b6b46dcSRobert Mustacchilock to become avaialble. 100*8b6b46dcSRobert MustacchiIf the lock does not become available within a specified timeout, then 101*8b6b46dcSRobert Mustacchithe function call will terminate without acquiring the lock and return 102*8b6b46dcSRobert Mustacchithe 103*8b6b46dcSRobert Mustacchi.Er ETIMEDOUT 104*8b6b46dcSRobert Mustacchierror. 105*8b6b46dcSRobert MustacchiThese functions all differ in terms of how the timeout is specified and 106*8b6b46dcSRobert Mustacchithe clock that is used to determine when the timeout has elapsed. 107*8b6b46dcSRobert Mustacchi.Pp 108*8b6b46dcSRobert MustacchiIn general, the system provides the ability to program timeouts against 109*8b6b46dcSRobert Mustacchieither the realtime clock, 110*8b6b46dcSRobert Mustacchi.Dv CLOCK_REALTIME , 111*8b6b46dcSRobert Mustacchiwhich measures the wall clock and is subject to changes due to time 112*8b6b46dcSRobert Mustacchisynchronization daemons such as NTP and PTP, or the high-resolution clock, 113*8b6b46dcSRobert Mustacchi.Dv CLOCK_HIGHRES , 114*8b6b46dcSRobert Mustacchiwhich is a non-adjustable high-resolution clock that is provided by 115*8b6b46dcSRobert Mustacchisystem hardware. 116*8b6b46dcSRobert MustacchiThe specified timeout may either be specified as an absolute time in the 117*8b6b46dcSRobert Mustacchifuture or as a relative amount of time that should elapse. 118*8b6b46dcSRobert MustacchiEach clock has its own resolution, which can be determined by 119*8b6b46dcSRobert Mustacchi.Xr clock_getres 3C . 120*8b6b46dcSRobert MustacchiTimeouts may be rounded up to a given clock's resolution. 121*8b6b46dcSRobert MustacchiDue to scheduling effects, it is possible that more time may elapse than 122*8b6b46dcSRobert Mustacchiwas specified in the timeout when the caller does not successfully 123*8b6b46dcSRobert Mustacchiacquire the lock. 124*8b6b46dcSRobert MustacchiThe 125*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_clockrdlock 126*8b6b46dcSRobert Mustacchiand 127*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_relclockrdlock_np 128*8b6b46dcSRobert Mustacchifunctions allow the clock source to be used to be specified by the 129*8b6b46dcSRobert Mustacchi.Fa clock 130*8b6b46dcSRobert Mustacchiargument. 131*8b6b46dcSRobert MustacchiWhile there are additional clocks in the system, only 132*8b6b46dcSRobert Mustacchi.Dv CLOCK_REALTIME 133*8b6b46dcSRobert Mustacchior 134*8b6b46dcSRobert Mustacchi.Dv CLOCK_HIGHRES 135*8b6b46dcSRobert Mustacchimay be specified. 136*8b6b46dcSRobert MustacchiThe thread and process-specific CPU time clocks cannot be used. 137*8b6b46dcSRobert MustacchiConversely, the 138*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_timedrdlock 139*8b6b46dcSRobert Mustacchiand 140*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_reltimedrdlock_np 141*8b6b46dcSRobert Mustacchifunctions will always utilize the realtime clock, 142*8b6b46dcSRobert Mustacchi.Dv CLOCK_REALTIME . 143*8b6b46dcSRobert Mustacchi.Pp 144*8b6b46dcSRobert MustacchiThe 145*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_clockrdlock 146*8b6b46dcSRobert Mustacchiand 147*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_timedrdlock 148*8b6b46dcSRobert Mustacchifunctions treat the timeout value, 149*8b6b46dcSRobert Mustacchi.Fa abstime , 150*8b6b46dcSRobert Mustacchias the absolute time in the future when the timeout should expire. 151*8b6b46dcSRobert MustacchiConversely, the 152*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_relclockrdlock_np 153*8b6b46dcSRobert Mustacchiand 154*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_reltimedrdlock_np 155*8b6b46dcSRobert Mustacchifunctions operate in terms of a relative time. 156*8b6b46dcSRobert MustacchiThe timer will expire when a specified amount of time passes on the 157*8b6b46dcSRobert Mustacchiclock specified as indicated by 158*8b6b46dcSRobert Mustacchi.Fa reltime . 159*8b6b46dcSRobert MustacchiIf the read-write lock, 160*8b6b46dcSRobert Mustacchi.Fa rwlock , 161*8b6b46dcSRobert Mustacchican be immediately read-locked, then the timeout value is ignored 162*8b6b46dcSRobert Mustacchientirely, Even if the timeout had already expired or represented a 163*8b6b46dcSRobert Mustacchivalue that didn't make sense. 164*8b6b46dcSRobert MustacchiBoth are only checked if the thread would block on the read-write lock 165*8b6b46dcSRobert Mustacchiitself. 166*8b6b46dcSRobert Mustacchi.Pp 167*8b6b46dcSRobert MustacchiSimilarly, if a signal that causes a signal handler to be executed is 168*8b6b46dcSRobert Mustacchidelivered to a thread blocked on a read-write lock, then upon return 169*8b6b46dcSRobert Mustacchifrom the signal handler, the thread resumes waiting for the lock as 170*8b6b46dcSRobert Mustacchithough it was not interrupted. 171*8b6b46dcSRobert Mustacchi.Pp 172*8b6b46dcSRobert MustacchiIt is illegal for a thread to acquire a read lock on the same read-write 173*8b6b46dcSRobert Mustacchilock that it already holds a write lock on. 174*8b6b46dcSRobert Mustacchi.Sh RETURN VALUES 175*8b6b46dcSRobert MustacchiUpon successful completion, the 176*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_clockrdlock , 177*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_timerrdlock , 178*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_relclockrdlock_np , 179*8b6b46dcSRobert Mustacchiand 180*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_reltimerrdlock_np 181*8b6b46dcSRobert Mustacchireturn 182*8b6b46dcSRobert Mustacchi.Sy 0 183*8b6b46dcSRobert Mustacchiand have successfully acquired a read lock on 184*8b6b46dcSRobert Mustacchi.Fa rwlock . 185c10c16deSRichard LoweOtherwise, an error number is returned to indicate the error. 186*8b6b46dcSRobert Mustacchi.Sh ERRORS 187*8b6b46dcSRobert MustacchiThe 188*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_clockrdlock , 189*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_timerrdlock , 190*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_relclockrdlock_np , 191*8b6b46dcSRobert Mustacchiand 192*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_reltimerrdlock_np 193*8b6b46dcSRobert Mustacchiwill fail if: 194*8b6b46dcSRobert Mustacchi.Bl -tag -width Er 195*8b6b46dcSRobert Mustacchi.It Er EAGAIN 196c10c16deSRichard LoweThe read lock could not be acquired because the maximum number of read locks 197c10c16deSRichard Lowefor lock would be exceeded. 198*8b6b46dcSRobert Mustacchi.It Er EDEADLK 199*8b6b46dcSRobert MustacchiThe calling thread already holds a write lock on 200*8b6b46dcSRobert Mustacchi.Fa rwlock 201*8b6b46dcSRobert Mustacchi.It Er EINVAL 202*8b6b46dcSRobert MustacchiThe value specified by 203*8b6b46dcSRobert Mustacchi.Fa rwlock 204*8b6b46dcSRobert Mustacchidoes not refer to an initialized read-write 205*8b6b46dcSRobert Mustacchilock object. 206*8b6b46dcSRobert MustacchiThe timeout nanosecond value is less than zero or greater than 207*8b6b46dcSRobert Mustacchior equal to 1,000 million. 208*8b6b46dcSRobert Mustacchi.Pp 209*8b6b46dcSRobert MustacchiFor 210*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_clockrdlock 211*8b6b46dcSRobert Mustacchiand 212*8b6b46dcSRobert Mustacchi.Fn pthread_rwlock_relclockrdlock_np 213*8b6b46dcSRobert Mustacchithe value of 214*8b6b46dcSRobert Mustacchi.Fa clock 215*8b6b46dcSRobert Mustacchiis either unsupported for locking or unknown to the system. 216*8b6b46dcSRobert Mustacchi.It Er ETIMEDOUT 217*8b6b46dcSRobert MustacchiThe lock could not be acquired before the specified timeout expired. 218*8b6b46dcSRobert Mustacchi.El 219*8b6b46dcSRobert Mustacchi.Sh INTERFACE STABILITY 220*8b6b46dcSRobert Mustacchi.Sy Committed 221*8b6b46dcSRobert Mustacchi.Sh MT-LEVEL 222*8b6b46dcSRobert Mustacchi.Sy MT-Safe 223*8b6b46dcSRobert Mustacchi.Sh SEE ALSO 224*8b6b46dcSRobert Mustacchi.Xr clock_getres 3C , 225*8b6b46dcSRobert Mustacchi.Xr pthread_rwlock_destroy 3C , 226*8b6b46dcSRobert Mustacchi.Xr pthread_rwlock_rdlock 3C , 227*8b6b46dcSRobert Mustacchi.Xr pthread_rwlock_timedwrlock 3C , 228*8b6b46dcSRobert Mustacchi.Xr pthread_rwlock_tryrdlock 3C , 229*8b6b46dcSRobert Mustacchi.Xr pthread_rwlock_trywrlock 3C , 230*8b6b46dcSRobert Mustacchi.Xr pthread_rwlock_unlock 3C , 231*8b6b46dcSRobert Mustacchi.Xr pthread_rwlock_wrlock 3C , 232*8b6b46dcSRobert Mustacchi.Xr attributes 7 , 233*8b6b46dcSRobert Mustacchi.Xr standards 7 234