---
name: "sem_init"
section: "3thr"
platform: "linux"
package: "glibc-doc"
version: "2.1.3-20"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/sem_init/3thr"
---

# sem\_init(3thr)

operations on semaphores

## NAME

sem\_init, sem\_wait, sem\_trywait, sem\_post, sem\_getvalue, sem\_destroy - operations on semaphores

## SYNOPSIS

**#include \<semaphore.h\>**

**int sem\_init(sem\_t \****sem***, int** *pshared***, unsigned int** *value***);**

**int sem\_wait(sem\_t \*** *sem***);**

**int sem\_trywait(sem\_t \*** *sem***);**

**int sem\_post(sem\_t \*** *sem***);**

**int sem\_getvalue(sem\_t \*** *sem***, int \*** *sval***);**

**int sem\_destroy(sem\_t \*** *sem***);**

## DESCRIPTION

This manual page documents POSIX 1003.1b semaphores, not to be confused with SystemV semaphores as described in  [**ipc**(5)](/ipc/5.md), [**semctl**(2)](/semctl/2.md) and  [**semop**(2)](/semop/2.md).

Semaphores are counters for resources shared between threads. The basic operations on semaphores are: increment the counter atomically, and wait until the counter is non-null and decrement it atomically.

**sem\_init** initializes the semaphore object pointed to by  *sem*. The count associated with the semaphore is set initially to  *value*. The *pshared* argument indicates whether the semaphore is local to the current process ( *pshared* is zero) or is to be shared between several processes ( *pshared* is not zero). LinuxThreads currently does not support process-shared semaphores, thus  **sem\_init** always returns with error  **ENOSYS** if  *pshared* is not zero.

**sem\_wait** suspends the calling thread until the semaphore pointed to by  *sem* has non-zero count. It then atomically decreases the semaphore count.

**sem\_trywait** is a non-blocking variant of  **sem\_wait**. If the semaphore pointed to by  *sem* has non-zero count, the count is atomically decreased and  **sem\_trywait** immediately returns 0. If the semaphore count is zero,  **sem\_trywait** immediately returns with error  **EAGAIN**.

**sem\_post** atomically increases the count of the semaphore pointed to by  *sem*. This function never blocks and can safely be used in asynchronous signal handlers.

**sem\_getvalue** stores in the location pointed to by  *sval* the current count of the semaphore  *sem*.

**sem\_destroy** destroys a semaphore object, freeing the resources it might hold. No threads should be waiting on the semaphore at the time **sem\_destroy** is called. In the LinuxThreads implementation, no resources are associated with semaphore objects, thus  **sem\_destroy** actually does nothing except checking that no thread is waiting on the semaphore.

## CANCELLATION

**sem\_wait** is a cancellation point.

## ASYNC-SIGNAL SAFETY

On processors supporting atomic compare-and-swap (Intel 486, Pentium and later, Alpha, PowerPC, MIPS II, Motorola 68k), the  **sem\_post** function is async-signal safe and can therefore be called from signal handlers. This is the only thread synchronization function provided by POSIX threads that is async-signal safe.

On the Intel 386 and the Sparc, the current LinuxThreads implementation of  **sem\_post** is not async-signal safe by lack of the required atomic operations.

## RETURN VALUE

The  **sem\_wait** and  **sem\_getvalue** functions always return 0. All other semaphore functions return 0 on success and -1 on error, in addition to writing an error code in  **errno**.

## ERRORS

The  **sem\_init** function sets  **errno** to the following codes on error:

- **EINVAL**

  *value* exceeds the maximal counter value  **SEM\_VALUE\_MAX**

- **ENOSYS**

  *pshared* is not zero

The  **sem\_trywait** function sets  **errno** to the following error code on error:

- **EAGAIN**

  the semaphore count is currently 0

The  **sem\_post** function sets  **errno** to the following error code on error:

- **ERANGE**

  after incrementation, the semaphore value would exceed  **SEM\_VALUE\_MAX** (the semaphore count is left unchanged in this case)

The  **sem\_destroy** function sets  **errno** to the following error code on error:

- **EBUSY**

  some threads are currently blocked waiting on the semaphore.

## AUTHOR

Xavier Leroy \<Xavier.Leroy@inria.fr\>

## SEE ALSO

[**pthread\_mutex\_init**(3)](/pthread_mutex_init/3.md), [**pthread\_cond\_init**(3)](/pthread_cond_init/3.md), [**pthread\_cancel**(3)](/pthread_cancel/3.md), [**ipc**(5)](/ipc/5.md).