RTEMS 4.0.0 On-Line Library

Semaphore Manager SEMAPHORE_OBTAIN - Acquire a semaphore

RTEMS C User's Guide

8.4.4: SEMAPHORE_OBTAIN - Acquire a semaphore

CALLING SEQUENCE:

rtems_status_code rtems_semaphore_obtain(
  rtems_id         id,
  rtems_unsigned32 option_set,
  rtems_interval   timeout
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - semaphore obtained successfully
RTEMS_UNSATISFIED - semaphore not available
RTEMS_TIMEOUT - timed out waiting for semaphore
RTEMS_OBJECT_WAS_DELETED - semaphore deleted while waiting
RTEMS_INVALID_ID - invalid semaphore id

DESCRIPTION:

This directive acquires the semaphore specified by id. The RTEMS_WAIT and RTEMS_NO_WAIT components of the options parameter indicate whether the calling task wants to wait for the semaphore to become available or return immediately if the semaphore is not currently available. With either RTEMS_WAIT or RTEMS_NO_WAIT, if the current semaphore count is positive, then it is decremented by one and the semaphore is successfully acquired by returning immediately with a successful return code.

If the calling task chooses to return immediately and the current semaphore count is zero or negative, then a status code is returned indicating that the semaphore is not available. If the calling task chooses to wait for a semaphore and the current semaphore count is zero or negative, then it is decremented by one and the calling task is placed on the semaphore's wait queue and blocked. If the semaphore was created with the RTEMS_PRIORITY attribute, then the calling task is inserted into the queue according to its priority. However, if the semaphore was created with the RTEMS_FIFO attribute, then the calling task is placed at the rear of the wait queue. If the binary semaphore was created with the RTEMS_INHERIT_PRIORITY attribute, then the priority of the task currently holding the binary semaphore is guaranteed to be greater than or equal to that of the blocking task. If the binary semaphore was created with the RTEMS_PRIORITY_CEILING attribute, a task successfully obtains the semaphore, and the priority of that task is greater than the ceiling priority for this semaphore, then the priority of the task obtaining the semaphore is elevated to that of the ceiling.

The timeout parameter specifies the maximum interval the calling task is willing to be blocked waiting for the semaphore. If it is set to RTEMS_NO_TIMEOUT, then the calling task will wait forever. If the semaphore is available or the RTEMS_NO_WAIT option component is set, then timeout is ignored.

NOTES:

The following semaphore acquisition option constants are defined by RTEMS:

RTEMS_WAIT - task will wait for semaphore (default)
RTEMS_NO_WAIT - task should not wait

Attempting to obtain a global semaphore which does not reside on the local node will generate a request to the remote node to access the semaphore. If the semaphore is not available and RTEMS_NO_WAIT was not specified, then the task must be blocked until the semaphore is released. A proxy is allocated on the remote node to represent the task until the semaphore is released.

A clock tick is required to support the timeout functionality of this directive.

RTEMS C User's Guide