sem_init()

Updated: April 19, 2023

Initialize an unnamed semaphore

Synopsis:

#include <semaphore.h>

int sem_init( sem_t * sem, 
              int pshared, 
              unsigned value );

Arguments:

sem
A pointer to the sem_t object for the semaphore that you want to initialize.
Note: It's always safe, and typically faster, to assure that sem is 32-bit aligned.
pshared
Nonzero if you want the semaphore to be shared between processes via a shared mapping.
value
The initial value of the semaphore. A positive value indicates the number of semaphore wait operations (e.g., sem_wait()) that will succeed without blocking, and a value of zero indicates that the next semaphore wait operation will block the calling thread. This value must not exceed SEM_VALUE_MAX.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The sem_init() function initializes the unnamed semaphore referred to by the sem argument. The initial counter value of this semaphore is specified by the value argument.

CAUTION:
You should allocate synchronization objects only in normal memory mappings. On certain processors, atomic operations such as calls to pthread_mutex_lock() will cause a fault if the control structure is allocated in uncached memory.

You can use the initialized semaphore in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_destroy(). An initialized semaphore is valid until it's destroyed by the sem_destroy() function, or until the memory where the semaphore resides is released.

If the pshared argument is nonzero, then the semaphore can be shared between processes via a shared mapping. Any process can then use sem with the sem_wait(), sem_trywait(), sem_post() and sem_destroy() functions.

Note: Don't mix named semaphore operations (sem_open() and sem_close()) with unnamed semaphore operations (sem_init() and sem_destroy()) on the same semaphore.

Returns:

0
Success. The semaphore referred to by sem is initialized.
-1
An error occurred (errno is set).

Errors:

EAGAIN
A resource required to initialize the semaphore has been exhausted.
EINVAL
The value argument exceeds SEM_VALUE_MAX.
EPERM
The process lacks the appropriate privileges to initialize the semaphore.
ENOSPC
A resource required to initialize the semaphore has been exhausted.
ENOSYS
The sem_init() function isn't supported.

Classification:

POSIX 1003.1

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes

Caveats:

Don't initialize the same semaphore from more than one thread. It's best to set up semaphores before starting any threads.