jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: sem_wait.3,v 1.11 2025/06/07 00:16:52 schwarze Exp $
2.\"
3.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice(s), this list of conditions and the following disclaimer as
11.\" the first lines of this file unmodified other than the possible
12.\" addition of one or more copyright notices.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice(s), this list of conditions and the following disclaimer in
15.\" the documentation and/or other materials provided with the
16.\" distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
19.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
25.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
27.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
28.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29.\"
30.\" $FreeBSD: src/lib/libc_r/man/sem_wait.3,v 1.8 2001/10/01 16:09:09 ru Exp $
31.Dd $Mdocdate: June 7 2025 $
32.Dt SEM_WAIT 3
33.Os
34.Sh NAME
35.Nm sem_wait ,
36.Nm sem_timedwait ,
37.Nm sem_trywait
38.Nd decrement (lock) a semaphore
39.Sh SYNOPSIS
40.Lb libpthread
41.In semaphore.h
42.Ft int
43.Fn sem_wait "sem_t *sem"
44.Ft int
45.Fn sem_timedwait "sem_t *sem" "const struct timespec *abstime"
46.Ft int
47.Fn sem_trywait "sem_t *sem"
48.Sh DESCRIPTION
49The
50.Fn sem_wait
51function decrements (locks) the semaphore pointed to by
52.Fa sem ,
53but blocks if the value of
54.Fa sem
55is zero, until the value is non-zero and the value can be decremented.
56.Pp
57The
58.Fn sem_timedwait
59function decrements (locks) the semaphore pointed to by
60.Fa sem ,
61but blocks if the value of
62.Fa sem
63is zero, until either the value is non-zero and can be decremented
64or the system time specified by
65.Fa abstime
66is reached.
67.Pp
68The
69.Fn sem_trywait
70function decrements (locks) the semaphore pointed to by
71.Fa sem
72only if the value is non-zero.
73Otherwise, the semaphore is not decremented and
74an error is returned.
75.Sh RETURN VALUES
76.Rv -std sem_wait sem_timedwait sem_trywait
77.Sh ERRORS
78.Fn sem_wait ,
79.Fn sem_timedwait ,
80and
81.Fn sem_trywait
82will fail if:
83.Bl -tag -width Er
84.It Bq Er EINVAL
85.Fa sem
86points to an invalid semaphore.
87.El
88.Pp
89Additionally,
90.Fn sem_wait
91and
92.Fn sem_timedwait
93will fail if:
94.Bl -tag -width Er
95.It Bq Er EINTR
96The call was interrupted by a signal.
97.El
98.Pp
99Additionally,
100.Fn sem_timedwait
101will fail if:
102.Bl -tag -width Er
103.It Bq Er EINVAL
104.Fa abstime
105was
106.Dv NULL
107or specified a nanosecond value less than zero or greater than 1000 million.
108.It Bq Er ETIMEDOUT
109The semaphore value was zero and could not be decremented before
110.Fa abstime
111was reached.
112.El
113.Pp
114Additionally,
115.Fn sem_trywait
116will fail if:
117.Bl -tag -width Er
118.It Bq Er EAGAIN
119The semaphore value was zero, and thus could not be decremented.
120.El
121.Sh SEE ALSO
122.Xr sem_destroy 3 ,
123.Xr sem_getvalue 3 ,
124.Xr sem_init 3 ,
125.Xr sem_open 3 ,
126.Xr sem_post 3
127.Sh STANDARDS
128.Fn sem_wait ,
129.Fn sem_timedwait ,
130and
131.Fn sem_trywait
132conform to
133.St -p1003.1-2008 .