sem_init()

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.
EBUSY: The given semaphore was previously initialized, and has not been destroyed.
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.