NAME
sem_wait, sem_trywait — lock a POSIX semaphore
SYNOPSIS
#include <sys/semaphore.h>
int sem_wait(sem_t *sem);
int sem_trywait(sem_t *sem);
DESCRIPTION
sem_wait()
is used to lock a semaphore. The calling thread will not return from its call
to
sem_wait()
until one of the following events occur:
it successfully obtains a lock on the semaphore;
it is interrupted by a signal or an
error condition occurs.
sem_trywait()
is used to lock a semaphore, if it is available.
The value of the semaphore
sem
is checked at some unspecified time during the call.
If the semaphore is available at the time its value is checked,
the calling thread will atomically, with respect
to the checking of the value, lock the semaphore.
The thread will now own a lock on the
semaphore; the call will return successfully.
If the semaphore is unavailable at the time its value is checked, then the call returns -1 with errno set to
EAGAIN.
If the specified semaphore referred to by
sem
is a named semaphore, then this semaphore must have been opened by the
calling process with
sem_open().
The calling process must have both
read and write permissions on the semaphore to perform these operations.
The semaphore will be locked upon successful return and will stay locked
until it is explicitly released by a call to
sem_post().
To use this function, link in the realtime library by specifying
-lrt
on the compiler or linker command line.
EXAMPLES
The following call to
sem_wait()
will lock the semaphore
sem.
The following call to
sem_trywait()
will lock the semaphore
sem,
if it is available.
RETURN VALUE
A successful call to
sem_wait()
will return 0 and the calling thread will
then own a lock on the semaphore. Otherwise, the call to
sem_wait()
will
return -1 with errno set to the appropriate value of the error condition.
A successful call to
sem_trywait()
will return 0, if the semaphore was available
and the calling thread was able to
lock the semaphore. Otherwise, the call to
sem_trywait()
will
return -1 with errno set to the appropriate value of the error condition.
ERRORS
sem_wait()
and
sem_trywait()
fail and do not perform the requested operation
if any of the following conditions are encountered:
- [EPERM]
The calling process does not have the privileges necessary to lock the
semaphore.
- [EAGAIN]
The semaphore was not available and hence could not be locked by
sem_trywait().
This error condition only occurs in
sem_trywait().
- [EINVAL]
The argument
sem
does not refer to a valid semaphore.
- [EINTR]
The function was interrupted by a signal
STANDARDS CONFORMANCE
sem_wait(),sem_trywait(): POSIX
Printable version
