.\"
.\" 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) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd June 23, 2024
.Dt SEM_TIMEDWAIT 3C
.Os
.Sh NAME
.Nm sem_clockwait ,
.Nm sem_timedwait ,
.Nm sem_relclockwait_np ,
.Nm sem_reltimedwait_np
.Nd lock a semaphore with timeout
.Sh SYNOPSIS
.In sempahore.h
.In time.h
.Ft int
.Fo sem_clockwait
.Fa "sem_t *restrict sem"
.Fa "clockid_t clock"
.Fa "const struct timespec *abstime"
.Fc
.Ft int
.Fo sem_timedwait
.Fa "sem_t *restrict sem"
.Fa "const struct timespec *abstime"
.Fc
.Ft int
.Fo sem_relclockwait_np
.Fa "sem_t *restrict sem"
.Fa "clockid_t clock"
.Fa "const struct timespec *reltime"
.Fc
.Ft int
.Fo sem_reltimedwait_np
.Fa "sem_t *restrict sem"
.Fa "const struct timespec *reltime"
.Fc
.Sh DESCRIPTION
The
.Fn sem_clockwait ,
.Fn sem_timedwait ,
.Fn sem_relclockwait_np ,
and
.Fn sem_reltimewait_np
functions lock the sempahore referenced by
.Fa sem
as in the
.Xr sem_wait 3C
function.
If the semaphore is locked, the calling thread will block until it
becomes available by another process or thread unlocking the semaphore
by calling
.Xr sem_post 3C .
However, if the semaphore does not become available within a specified
timeout, then the function call will terminate without acquiring the
semaphore 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.
.Pp
The
.Fn sem_clockwait
and
.Fn sem_relclocklock_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 sem_timedwait
and
.Fn sem_reltimedwait_np
functions will always utilize the realtime clock,
.Dv CLOCK_REALTIME .
.Pp
The
.Fn sem_clockwait
and
.Fn sem_timedwait
functions treat the timeout value,
.Fa abstime ,
as the absolute time in the future when the timeout should expire.
Conversely, the
and
.Fn sem_reltimedwait_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 .
.Pp
If the semaphore,
.Fa sem ,
can be immediately 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 semaphore itself.
.Sh RETURN VALUES
Upon successful completion, the
.Fn sem_clockwait ,
.Fn sem_timedwait ,
.Fn sem_relclockwait_np ,
and
.Fn sem_reltimewait_np
functions return
.Sy 0
and the thread will have successfully locked the semaphore.
Otherwise
.Sy -1
is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn sem_clockwait ,
.Fn sem_timedwait ,
.Fn sem_relclockwait_np ,
and
.Fn sem_reltimewait_np
functions will fail if:
.Bl -tag -width Er
.It Er EINVAL
The
.Fa sem
argument does not refer to a valid semaphore or the process or thread
would have blocked, and the timeout parameter specified a nanoseconds
field value less than zero or greater than or equal to 1,000 million.
.Pp
For
.Fn sem_clockwait
or
.Fn sem_relclockwait_np
the value of
.Fa clock
is either unsupported for locking or unknown to the system.
.It Er EDEADLK
A deadlock condition was detected.
.It Er EINTR
A signal interrupted this function.
.It Er ETIMEDOUT
The semaphore could not be locked before the specified timeout expired.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr semctl 2 ,
.Xr semget 2 ,
.Xr semop 2 ,
.Xr time 2 ,
.Xr clock_getres 3C ,
.Xr sem_post 3C ,
.Xr sem_trywait 3C ,
.Xr sem_wait 3C ,
.Xr attributes 7 ,
.Xr standards 7