Similar Synchronization Functions: Semaphores

Semaphore operations are the same in both the Oracle Solaris Operating Environment and the POSIX environment. The function name changed from sema_ in the Oracle Solaris Operating Environment to sem_ in pthreads. This section discusses the following topics:

• Initializing a semaphore

• Incrementing a semaphore

• Blocking on a semaphore count

• Decrementing a semaphore count

• Destroying the semaphore state

Initialize a Semaphore

Use sema_init(3C) to initialize the semaphore variable pointed to by sp by count amount.

sema_init Syntax

#include <thread.h>

int sema_init(sema_t *sp, unsigned int count, int type,
    void *arg);

type can be one of the following values:

• USYNC_PROCESS. The semaphore can be used to synchronize threads in this process and other processes. Only one process should initialize the semaphore. arg is ignored.

• USYNC_THREAD. The semaphore can be used to synchronize threads in this process, only. arg is ignored.

Multiple threads must not initialize the same semaphore simultaneously. A semaphore must not be reinitialized while other threads might be using the semaphore.

Semaphores With Intraprocess Scope

#include <thread.h>

sema_t sp;
int ret;
int count;
count = 4;

/* to be used within this process only */
ret = sema_init(&sp, count, USYNC_THREAD, 0); 

Semaphores With Interprocess Scope

#include <thread.h>

sema_t sp;
int ret;
int count;
count = 4;

/* to be used among all the processes */
ret = sema_init (&sp, count, USYNC_PROCESS, 0); 

sema_init Return Values

sema_init() returns 0 if successful. When any of the following conditions is detected, sema_init() fails and returns the corresponding value.

EINVAL

Description: sp refers to an invalid semaphore.

EFAULT

Description: Either sp or arg point to an illegal address.

Increment a Semaphore

Use sema_post(3C) to atomically increment the semaphore pointed to by sp. When any threads are blocked on the semaphore, one thread is unblocked.

sema_post Syntax

#include <thread.h>

int sema_post(sema_t *sp);

sema_post Return Values

sema_post() returns 0 if successful. When any of the following conditions is detected, sema_post() fails and returns the corresponding value.

EINVAL

Description: sp refers to an invalid semaphore.

EFAULT

Description: sp points to an illegal address.

EOVERFLOW

Description: The semaphore value pointed to by sp exceeds SEM_VALUE_MAX.

Block on a Semaphore Count

Use sema_wait(3C) to block the calling thread until the count in the semaphore pointed to by sp becomes greater than zero. When the count becomes greater than zero, atomically decrement the count.

sema_wait Syntax

#include <thread.h>

int sema_wait(sema_t *sp);

sema_wait Return Values

sema_wait() returns 0 if successful. When any of the following conditions is detected, sema_wait() fails and returns the corresponding value.

EINVAL

Description: sp refers to an invalid semaphore.

EINTR

Description: The wait was interrupted by a signal.

Decrement a Semaphore Count

Use sema_trywait(3C) to atomically decrement the count in the semaphore pointed to by sp when the count is greater than zero. This function is a nonblocking version of sema_wait().

sema_trywait Syntax

#include <thread.h>

int sema_trywait(sema_t *sp);

sema_trywait Return Values

sema_trywait() returns 0 if successful. When any of the following conditions is detected, sema_trywait() fails and returns the corresponding value.

EINVAL

Description: sp refers to an invalid semaphore.

EBUSY

Description: The semaphore pointed to by sp has a zero count.

Destroy the Semaphore State

Use sema_destroy(3C) to destroy any state that is associated with the semaphore pointed to by sp. The space for storing the semaphore is not freed.

sema_destroy(3C) Syntax

#include <thread.h>

int sema_destroy(sema_t *sp);

sema_destroy(3C) Return Values

sema_destroy() returns 0 if successful. When the following condition is detected, sema_destroy() fails and returns the corresponding value.

EINVAL

Description: sp refers to an invalid semaphore.