sem_wait

Synopsis

#include <semaphore.h>

int sem_wait(sem_t *sem);

Status

Implemented

Conformance

IEEE Std 1003.1-2024

Description

The sem_wait() function shall lock the semaphore referenced by sem. If the semaphore value is greater than zero it is decremented and the call returns at once; otherwise the calling thread shall block until it can perform the decrement or the call is interrupted.

Both named and unnamed semaphores are accepted. Waiters on a named semaphore are released highest priority first, and in first-in-first-out order among equal priorities.

A call that blocks on a named semaphore is a message send to posixsrv and is not interruptible: it never fails with EINTR, and it is not a cancellation point. Both are permitted - IEEE Std 1003.1-2024 makes EINTR a “may fail” error and lists sem_wait() among the functions at which a cancellation point may occur rather than those where one shall (XSH 2.9.5.2). IEEE Std 1003.1-2017 required both, so this stopped being a deviation with the 2024 edition. See POSIX implementation for the behaviour, which still applies: a thread parked on a semaphore that is never posted cannot be cancelled or killed. Use sem_timedwait() where a thread has to regain control.

Return value

Upon successful completion, sem_wait() shall return 0 with the semaphore locked. Otherwise it shall return -1, the semaphore state shall be unchanged, and errno shall be set to indicate the error.

Errors

This function shall fail if:

• EINVAL - sem is a null pointer or does not refer to a valid semaphore,

• EBADF - the named semaphore has been closed or removed.

POSIX deviations

No POSIX deviations discovered.