'\" t
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
-.TH SEM_WAIT 3 2007-07-26 "Linux" "Linux Programmer's Manual"
+.TH SEM_WAIT 3 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
sem_wait, sem_timedwait, sem_trywait \- lock a semaphore
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.sp
+.PP
.BI "int sem_wait(sem_t *" sem );
-.sp
+.PP
.BI "int sem_trywait(sem_t *" sem );
-.sp
+.PP
.BI "int sem_timedwait(sem_t *" sem ", const struct timespec *" abs_timeout );
.fi
-.sp
-Link with \fI\-lrt\fP or \fI\-pthread\fP.
-.sp
+.PP
+Link with \fI\-pthread\fP.
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.BR sem_timedwait ():
-_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
+_POSIX_C_SOURCE\ >=\ 200112L
.SH DESCRIPTION
.BR sem_wait ()
decrements (locks) the semaphore pointed to by
then the call blocks until either it becomes possible to perform
the decrement (i.e., the semaphore value rises above zero),
or a signal handler interrupts the call.
-
+.PP
.BR sem_trywait ()
is the same as
.BR sem_wait (),
set to
.BR EAGAIN )
instead of blocking.
-
+.PP
.BR sem_timedwait ()
is the same as
.BR sem_wait (),
The
.I abs_timeout
argument points to a structure that specifies an absolute timeout
-in seconds and nanoseconds since the Epoch (00:00:00, 1 January 1970).
+in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
This structure is defined as follows:
-
-.nf
+.PP
.in +4n
+.EX
struct timespec {
time_t tv_sec; /* Seconds */
long tv_nsec; /* Nanoseconds [0 .. 999999999] */
};
+.EE
.in
-.fi
.PP
If the timeout has already expired by the time of the call,
and the semaphore could not be locked immediately,
.RI ( errno
set to
.BR ETIMEDOUT ).
-
+.PP
If the operation can be performed immediately, then
.BR sem_timedwait ()
never fails with a timeout error, regardless of the value of
.SH ERRORS
.TP
.B EINTR
-The call was interrupted by a signal handler.
+The call was interrupted by a signal handler; see
+.BR signal (7).
.TP
.B EINVAL
.I sem
The call timed out before the semaphore could be locked.
.\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition
.\" was detected", but this does not occur on Linux(?).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw26 lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR sem_wait (),
+.BR sem_trywait (),
+.BR sem_timedwait ()
+T} Thread safety MT-Safe
+.TE
.SH CONFORMING TO
-POSIX.1-2001.
-.SH NOTES
-A signal handler always interrupts a blocked call to
-one of these functions, regardless of the use of the
-.BR sigaction (2)
-.B SA_RESTART
-flag.
-.\" sem_wait() is always interrupted on most other implementations,
-.\" but on FreeBSD 5.4 SA_RESTART does cause restarting.
+POSIX.1-2001, POSIX.1-2008.
.SH EXAMPLE
.PP
The (somewhat trivial) program shown below operates on an
of the timeout, in seconds, for
.BR sem_timedwait ().
The following shows what happens on two different runs of the program:
-
+.PP
.in +4n
-.nf
-$ ./a.out 2 3
+.EX
+.RB "$" " ./a.out 2 3"
About to call sem_timedwait()
sem_post() from handler
-sem_getvalue() from handler; value = 1
sem_timedwait() succeeded
-$ ./a.out 2 1
+.RB "$" " ./a.out 2 1"
About to call sem_timedwait()
sem_timedwait() timed out
-.fi
+.EE
.in
-.PP
-The source code of the program is as follows:
-.nf
-
+.SS Program source
+\&
+.EX
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
}
-.fi
-.SH "SEE ALSO"
-.\" FIXME . when this page has been added to the man-pages set:
-.\" .BR clock_gettime (3),
+.EE
+.SH SEE ALSO
+.BR clock_gettime (2),
.BR sem_getvalue (3),
.BR sem_post (3),
-.BR sem_overview (7)
+.BR sem_overview (7),
+.BR time (7)