xref: /illumos-gate/usr/src/man/man3c/pthread_rwlock_timedrdlock.3c (revision 731e0c14235a850a605dedf273943e34f866a22f)

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd October 29, 2024
.Dt PTHREAD_RWLOCK_TIMEDRDLOCK 3C
.Os
.Sh NAME
.Nm pthread_rwlock_clockrdlock ,
.Nm pthread_rwlock_timedrdlock ,
.Nm pthread_rwlock_relclockrdlock_np ,
.Nm pthread_rwlock_reltimedrdlock_np
.Nd lock a read-write lock for reading
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In pthread.h
.In time.h
.Ft int
.Fo pthread_rwlock_clockrdlock
.Fa "pthread_rwlock_t *restrict rwlock"
.Fa "clockid_t clock"
.Fa "const struct timespec *restrict abstime"
.Fc
.Ft int
.Fo pthread_rwlock_timedrdlock
.Fa "pthread_rwlock_t *restrict rwlock"
.Fa "const struct timespec *restrict abstime"
.Fc
.Ft int
.Fo pthread_rwlock_relclockrdlock_np
.Fa "pthread_rwlock_t *restrict rwlock"
.Fa "clockid_t clock"
.Fa "const struct timespec *restrict reltime"
.Fc
.Ft int
.Fo pthread_rwlock_reltimedrdlock_np
.Fa "pthread_rwlock_t *restrict rwlock"
.Fa "const struct timespec *restrict reltime"
.Fc
.Sh DESCRIPTION
The
.Fn pthread_rwlock_clockrdlock ,
.Fn pthread_rwlock_timedrdlock ,
.Fn pthread_rwlock_relclockrdlock_np ,
and
.Fn pthread_rwlock_reltimedrdlock_np
functions apply a read lock to the read-write lock referenced by
.Fa rwlock .
The calling thread will acquire a read lock if there are no writers
currently holding the lock and no writers that are blocking to acquire a
lock
.Pq writers starve readers .
However, if the read-write lock
.Fa rwlock
is not available, the calling thread will be suspended and wait for the
lock to become avaialble.
If the lock does not become available within a specified timeout, then
the function call will terminate without acquiring the lock and return
the
.Er ETIMEDOUT
error.
These functions all differ in terms of how the timeout is specified and
the clock that is used to determine when the timeout has elapsed.
.Pp
In general, the system provides the ability to program timeouts against
either the realtime clock,
.Dv CLOCK_REALTIME ,
which measures the wall clock and is subject to changes due to time
synchronization daemons such as NTP and PTP, or the high-resolution clock,
.Dv CLOCK_HIGHRES ,
which is a non-adjustable high-resolution clock that is provided by
system hardware.
The specified timeout may either be specified as an absolute time in the
future or as a relative amount of time that should elapse.
Each clock has its own resolution, which can be determined by
.Xr clock_getres 3C .
Timeouts may be rounded up to a given clock's resolution.
Due to scheduling effects, it is possible that more time may elapse than
was specified in the timeout when the caller does not successfully
acquire the lock.
The
.Fn pthread_rwlock_clockrdlock
and
.Fn pthread_rwlock_relclockrdlock_np
functions allow the clock source to be used to be specified by the
.Fa clock
argument.
While there are additional clocks in the system, only
.Dv CLOCK_REALTIME
or
.Dv CLOCK_HIGHRES
may be specified.
The thread and process-specific CPU time clocks cannot be used.
Conversely, the
.Fn pthread_rwlock_timedrdlock
and
.Fn pthread_rwlock_reltimedrdlock_np
functions will always utilize the realtime clock,
.Dv CLOCK_REALTIME .
.Pp
The
.Fn pthread_rwlock_clockrdlock
and
.Fn pthread_rwlock_timedrdlock
functions treat the timeout value,
.Fa abstime ,
as the absolute time in the future when the timeout should expire.
Conversely, the
.Fn pthread_rwlock_relclockrdlock_np
and
.Fn pthread_rwlock_reltimedrdlock_np
functions operate in terms of a relative time.
The timer will expire when a specified amount of time passes on the
clock specified as indicated by
.Fa reltime .
If the read-write lock,
.Fa rwlock ,
can be immediately read-locked, then the timeout value is ignored
entirely, Even if the timeout had already expired or represented a
value that didn't make sense.
Both are only checked if the thread would block on the read-write lock
itself.
.Pp
Similarly, if a signal that causes a signal handler to be executed is
delivered to a thread blocked on a read-write lock, then upon return
from the signal handler, the thread resumes waiting for the lock as
though it was not interrupted.
.Pp
It is illegal for a thread to acquire a read lock on the same read-write
lock that it already holds a write lock on.
.Sh RETURN VALUES
Upon successful completion, the
.Fn pthread_rwlock_clockrdlock ,
.Fn pthread_rwlock_timedrdlock ,
.Fn pthread_rwlock_relclockrdlock_np ,
and
.Fn pthread_rwlock_reltimedrdlock_np
return
.Sy 0
and have successfully acquired a read lock on
.Fa rwlock .
Otherwise, an error number is returned to indicate the error.
.Sh ERRORS
The
.Fn pthread_rwlock_clockrdlock ,
.Fn pthread_rwlock_timedrdlock ,
.Fn pthread_rwlock_relclockrdlock_np ,
and
.Fn pthread_rwlock_reltimedrdlock_np
will fail if:
.Bl -tag -width Er
.It Er EAGAIN
The read lock could not be acquired because the maximum number of read locks
for lock would be exceeded.
.It Er EDEADLK
The calling thread already holds a write lock on
.Fa rwlock
.It Er EINVAL
The value specified by
.Fa rwlock
does not refer to an initialized read-write
lock object.
The timeout nanosecond value is less than zero or greater than
or equal to 1,000 million.
.Pp
For
.Fn pthread_rwlock_clockrdlock
and
.Fn pthread_rwlock_relclockrdlock_np
the value of
.Fa clock
is either unsupported for locking or unknown to the system.
.It Er ETIMEDOUT
The lock could not be acquired before the specified timeout expired.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr clock_getres 3C ,
.Xr pthread_rwlock_destroy 3C ,
.Xr pthread_rwlock_rdlock 3C ,
.Xr pthread_rwlock_timedwrlock 3C ,
.Xr pthread_rwlock_tryrdlock 3C ,
.Xr pthread_rwlock_trywrlock 3C ,
.Xr pthread_rwlock_unlock 3C ,
.Xr pthread_rwlock_wrlock 3C ,
.Xr attributes 7 ,
.Xr standards 7