Xenomai  3.0.5
Functions
Semaphores
Cobalt » POSIX interface

Cobalt/POSIX semaphore services. More...

Collaboration diagram for Semaphores:

Functions

int sem_init (sem_t *sem, int pshared, unsigned int value)
 Initialize an unnamed semaphore. More...
 
int sem_destroy (sem_t *sem)
 Destroy an unnamed semaphore. More...
 
int sem_post (sem_t *sem)
 Post a semaphore. More...
 
int sem_trywait (sem_t *sem)
 Attempt to decrement a semaphore. More...
 
int sem_wait (sem_t *sem)
 Decrement a semaphore. More...
 
int sem_timedwait (sem_t *sem, const struct timespec *abs_timeout)
 Attempt to decrement a semaphore with a time limit. More...
 
int sem_close (sem_t *sem)
 Close a named semaphore. More...
 
int sem_unlink (const char *name)
 Unlink a named semaphore. More...
 

Detailed Description

Cobalt/POSIX semaphore services.

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.

Semaphores have a maximum value past which they cannot be incremented. The macro SEM_VALUE_MAX is defined to be this maximum value.

Function Documentation

◆ sem_close()

int sem_close ( sem_t *  sem)

Close a named semaphore.

This service closes the semaphore sem. The semaphore is destroyed only when unlinked with a call to the sem_unlink() service and when each call to sem_open() matches a call to this service.

When a semaphore is destroyed, the memory it used is returned to the system heap, so that further references to this semaphore are not guaranteed to fail, as is the case for unnamed semaphores.

This service fails if sem is an unnamed semaphore.

Parameters
semthe semaphore to be closed.
Return values
0on success;
-1with errno set if:
  • EINVAL, the semaphore sem is invalid or is an unnamed semaphore.
See also
Specification.
Tags
thread-unrestricted, switch-secondary

◆ sem_destroy()

int sem_destroy ( sem_t *  sem)

Destroy an unnamed semaphore.

This service destroys the semaphore sem. Threads currently blocked on sem are unblocked and the service they called return -1 with errno set to EINVAL. The semaphore is then considered invalid by all semaphore services (they all fail with errno set to EINVAL) except sem_init().

This service fails if sem is a named semaphore.

Parameters
semthe semaphore to be destroyed.
Return values
always0 on success. If SEM_WARNDEL was mentioned in sem_init_np(), the semaphore is deleted as requested and a strictly positive value is returned to warn the caller if threads were pending on it, otherwise zero is returned. If SEM_NOBUSYDEL was mentioned in sem_init_np(), sem_destroy() may succeed only if no thread is waiting on the semaphore to delete, otherwise -EBUSY is returned.
-1with errno set if:
  • EINVAL, the semaphore sem is invalid or a named semaphore;
  • EPERM, the semaphore sem is not process-shared and does not belong to the current process.
  • EBUSY, a thread is currently waiting on the semaphore sem with SEM_NOBUSYDEL set.
See also
Specification.
Tags
thread-unrestricted

◆ sem_init()

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

Initialize an unnamed semaphore.

This service initializes the semaphore sm, with the value value.

This service fails if sm is already initialized or is a named semaphore.

Parameters
semthe semaphore to be initialized;
psharedif zero, means that the new semaphore may only be used by threads in the same process as the thread calling sem_init(); if non zero, means that the new semaphore may be used by any thread that has access to the memory where the semaphore is allocated.
valuethe semaphore initial value.
Return values
0on success,
-1with errno set if:
  • EBUSY, the semaphore sm was already initialized;
  • EAGAIN, insufficient memory available to initialize the semaphore, increase CONFIG_XENO_OPT_SHARED_HEAPSZ for a process-shared semaphore, or CONFIG_XENO_OPT_PRIVATE_HEAPSZ for a process-private semaphore.
  • EAGAIN, no registry slot available, check/raise CONFIG_XENO_OPT_REGISTRY_NRSLOTS.
  • EINVAL, the value argument exceeds SEM_VALUE_MAX.
See also
Specification.
Tags
thread-unrestricted

◆ sem_post()

int sem_post ( sem_t *  sem)

Post a semaphore.

This service posts the semaphore sem.

If no thread is currently blocked on this semaphore, its count is incremented unless "pulse" mode is enabled for it (see sem_init_np(), SEM_PULSE). If a thread is blocked on the semaphore, the thread heading the wait queue is unblocked.

Parameters
semthe semaphore to be signaled.
Return values
0on success;
-1with errno set if:
  • EINVAL, the specified semaphore is invalid or uninitialized;
  • EPERM, the semaphore sm is not process-shared and does not belong to the current process;
  • EAGAIN, the semaphore count is SEM_VALUE_MAX.
See also
Specification.
Tags
unrestricted

◆ sem_timedwait()

int sem_timedwait ( sem_t *  sem,
const struct timespec *  abs_timeout 
)

Attempt to decrement a semaphore with a time limit.

This service is equivalent to sem_wait(), except that the caller is only blocked until the timeout abs_timeout expires.

Parameters
semthe semaphore to be decremented;
abs_timeoutthe timeout, expressed as an absolute value of the relevant clock for the semaphore, either CLOCK_MONOTONIC if SEM_RAWCLOCK was mentioned via sem_init_np(), or CLOCK_REALTIME otherwise.
Return values
0on success;
-1with errno set if:
  • EPERM, the caller context is invalid;
  • EINVAL, the semaphore is invalid or uninitialized;
  • EINVAL, the specified timeout is invalid;
  • EPERM, the semaphore sm is not process-shared and does not belong to the current process;
  • EINTR, the caller was interrupted by a signal while blocked in this service;
  • ETIMEDOUT, the semaphore could not be decremented and the specified timeout expired.
See also
Specification.
Tags
xthread-only, switch-primary

References sem_trywait().

◆ sem_trywait()

int sem_trywait ( sem_t *  sem)

Attempt to decrement a semaphore.

This service is equivalent to sem_wait(), except that it returns immediately if the semaphore sem is currently depleted, and that it is not a cancellation point.

Parameters
semthe semaphore to be decremented.
Return values
0on success;
-1with errno set if:
  • EINVAL, the specified semaphore is invalid or uninitialized;
  • EPERM, the semaphore sem is not process-shared and does not belong to the current process;
  • EAGAIN, the specified semaphore is currently fully depleted.
See also
Specification.
Tags
xthread-only

Referenced by sem_timedwait(), and sem_wait().

◆ sem_unlink()

int sem_unlink ( const char *  name)

Unlink a named semaphore.

This service unlinks the semaphore named name. This semaphore is not destroyed until all references obtained with sem_open() are closed by calling sem_close(). However, the unlinked semaphore may no longer be reached with the sem_open() service.

When a semaphore is destroyed, the memory it used is returned to the system heap, so that further references to this semaphore are not guaranteed to fail, as is the case for unnamed semaphores.

Parameters
namethe name of the semaphore to be unlinked.
Return values
0on success;
-1with errno set if:
  • ENAMETOOLONG, the length of the name argument exceeds 64 characters;
  • ENOENT, the named semaphore does not exist.
See also
Specification.
Tags
thread-unrestricted, switch-secondary

◆ sem_wait()

int sem_wait ( sem_t *  sem)

Decrement a semaphore.

This service decrements the semaphore sem if it is currently if its value is greater than 0. If the semaphore's value is currently zero, the calling thread is suspended until the semaphore is posted, or a signal is delivered to the calling thread.

This service is a cancellation point for Cobalt threads (created with the pthread_create() service). When such a thread is cancelled while blocked in a call to this service, the semaphore state is left unchanged before the cancellation cleanup handlers are called.

Parameters
semthe semaphore to be decremented.
Return values
0on success;
-1with errno set if:
  • EPERM, the caller context is invalid;
  • EINVAL, the semaphore is invalid or uninitialized;
  • EPERM, the semaphore sem is not process-shared and does not belong to the current process;
  • EINTR, the caller was interrupted by a signal while blocked in this service.
See also
Specification.
Tags
xthread-only, switch-primary

References sem_trywait().