Programming with POSIX® Threads

If a signal in set is pending, atomically clear it from the set of pending signals and return the signal number in the si_signo member of info. The cause of the signal shall be stored in the si_code member. If any value is queued to the selected signal, return the first queued value in the si_value member. If no signal in set is pending, suspend the calling thread until one or more become pending. This function returns the signal number—on error, it returns -1 and sets errno to the appropriate error code.

References: 6.6.4 Headers: 

Errors: [EINVAL] set contains an invalid signal number.

[ENOSYS] realtime signals are not supported. Hint: Use only for asynchronous signal delivery. All signals in set must

be masked in the calling thread, and should usually be masked in

all threads.

9.3.13 Semaphores

Semaphores come from POSIX.1b (POSIX 1003.1b-1993) rather than from Pthreads. They follow the older UNIX convention for reporting errors. That is, on failure they return a value of -1 and store the appropriate error number into errno. All of the semaphore functions require the header file .

sem_destroy....................................................................................................[_POSIX_SEMAPHORES]

int sem_destroy (

sem_t *sem);

Destroy an unnamed semaphore.

References: 6.6.6 Headers: 

Errors: [EINVAL] value exceeds SEM_VALUE_MAX.

[ENOSYS] semaphores are not supported.

[ EBUSY ] threads (or processes) are currently blocked on sem.

sem_init............................................................................................................[_POSIX_SEMAPHORES]

int sem_init (

sem_t *sem,

int pshared,

unsigned int value);

Initialize an unnamed semaphore. The initial value of the semaphore counter is value. If the pshared argument has a nonzero value, the semaphore can be shared between processes. With a zero value, it can be shared only between threads in the same process.

References: 6.6.6 Headers: 

Errors: [EINVAL] sem is not a valid semaphore.

[ENOSPC] a required resource has been exhausted.

[ENOSYS] semaphores are not supported.

[EPERM] the process lacks appropriate privilege. Hint: Use a value of 1 for a lock, a value of 0 for waiting.

sem_trywait.....................................................................................................[_POSIX_SEMAPHORES ]

int sem_trywait (

sem_t *sem);

Try to wait on a semaphore (or "try to lock" the semaphore). If the semaphore value is greater than zero, decrease the value by one. If the semaphore value is 0, then return immediately with the error EAGAIN.

References: 6.6.6 Headers:

Errors: [EAGAIN] the semaphore was already locked.

[EINVAL] sem is not a valid semaphore.

[EINTR] the function was interrupted by a signal.

[ENOSYS] semaphores are not supported.

[EDEADLK] a deadlock condition was detected. Hint: When the semaphore's initial value was 1, this is a lock operation;

when the initial value was 0, this is a wait operation.

sem_post..........................................................................................................[_POSIX_SEMAPHORES ]

int sem_post (

sem_t *sem);

Post a wakeup to a semaphore. If there are waiting threads (or processes), one is awakened. Otherwise the semaphore value is incremented by one.

References: 6.6.6 Headers: 

Errors: [EINVAL] sem is not a valid semaphore.

[ENOSYS] semaphores are not supported. Hint: May be used from within a signal-handling function.

sem_wait..........................................................................................................[_POSIX_SEMAPHORES ]

int sem_wait (

sem_t *sem);

Wait on a semaphore (or lock the semaphore). If the semaphore value is greater than zero, decrease the value by one. If the semaphore value is 0, then the calling thread (or process) is blocked until it can successfully decrease the value or until interrupted by a signal.

References: 6.6.6 Headers: 

Errors: [EINVAL] sem is not a valid semaphore.

[EINTR] the function was interrupted by a signal.

[ENOSYS] semaphores are not supported.

[EDEADLK] a deadlock condition was detected. Hint: When the semaphore's initial value was 1, this is a lock operation;

when the initial value was 0, this is a wait operation.

10 Future standardization