### NAME

  rt_sem_init - initialize a semaphore

### SYNOPSIS

  #include "rtai_sched.h"

  void rt_sem_init (SEM* sem, int value);

### DESCRIPTION

  rt_sem_init initializes a semaphore sem. A semaphore can be used for communication and synchronization among real-time tasks.

  sem must point to a statically allocated structure. value is the initial value of the semaphore (usually 1).

  Positive value of the semaphore variable shows how many tasks can do a 'P' operation without blocking. (Say how many tasks can enter the critical region.) Negative value of a semaphore shows that how many task is blocked on it. (Unless it is initialized to negative in advance but this would be totally senseless).

### RETURN VALUE

  None

### ERRORS

  None

### BUGS

  Negative initial values should not be allowed.

### NOTE

  Just for curiosity: the explanation of "P" and "V":

  > The name of P operation comes the Dutch "prolagen", a combination of "proberen" (to try) and "verlagen" (to reduce); Also from the word "passeren" (to pass).

  > The name of V operation coimes from the Dutch "verhogen" (to increase) or "vrygeven" (to release).

  (Source: Daniel Tabak - Multiprocessors, Prentice Hall, 1990.)

[return to index]

### NAME

  rt_sem_delete - delete a semaphore

### SYNOPSIS

  #include "rtai_sched.h"

  int rt_sem_delete (SEM* sem);

### DESCRIPTION

  rt_sem_delete deletes a semaphore previously created with rt_sem_create.

  sem points to the structure used in the corresponding call to rt_sem_create.

  Any tasks blocked on this semaphore is allowed to run when semaphore is destroyed.

### RETURN VALUE

  On success, 0 is returned. On failure, a nonzero value is returned, as described below.

### ERRORS

  `0xffff`
    sem does not refer to a valid semaphore.

### BUGS

  -EINVAL would be more a consistent error code.

[return to index]

### NAME

  rt_sem_signal - signalling a semaphore

### SYNOPSIS

  #include "rtai_sched.h"

  int rt_sem_signal (SEM* sem);

### DESCRIPTION

  rt_sem_signal is the semaphore post (sometimes known as 'give', 'signal', or 'V') operation. It is tipically called when the task leaves a critical region. The semaphore value is incremented and tested. If the value is not positive, the first task in semaphore's waiting queue is allowed to run. rt_sem_signal does not block the caller task.

  sem points to the structure used in the call to rt_sem_create.

### RETURN VALUE

  On success, 0 is returned. On failure, a nonzero value is returned as described below.

### ERRORS

  `0xffff`
    sem does not refer to a valid semaphore.

### BUGS

  -EINVAL would be more a consistent error code.

[return to index]

### NAME

  rt_sem_wait - wait a semaphore

### SYNOPSIS

  #include "rtai_sched.h"

  int rt_sem_wait (SEM* sem);

### DESCRIPTION

  rt_sem_wait is the semaphore wait (sometimes known as 'take' or 'P') operation. It is tipically called when a task enters a critical region. The semaphore value is decremented and tested. If it is still non-negative rt_sem_wait returns immediately. Otherwise the caller task is blocked and queued up. Queueing may happen in priority order or on FIFO base. This is determined by compile time option SEM_PRIORD. In this case rt_sem_wait returns if
  - The caller task is in the first place of the waiting queue and an other task issues a rt_sem_signal call;
  - An error occurs (e.g. the semaphore is destroyed);

  sem points to the structure used in the call to rt_sem_create.

### RETURN VALUE

  On success an undetermined number is returned. (Actually the return value somehow depends on the semaphore value.)
  On failure, a special value is returned as described below.

### ERRORS

  `0xffff`
    sem does not refer to a valid semaphore.

### BUGS

  The normal return value should not depend on the current value of the semaphore. In the current implementation number `0xffff` can be returned under normal circumstances too and it is undistinguishable from the error code.

[return to index]

### NAME

  rt_sem_wait_if - take a semaphore if possible

### SYNOPSIS

  #include "rtai_sched.h"

  int rt_sem_wait_if (SEM* sem);

### DESCRIPTION

  rt_sem_wait_if is a version of the semaphore wait (sometimes known as 'take' or 'P') operation. It is similar to rt_sem_wait but it is never blocks the caller. If the semaphore is not free, rt_sem_wait_if returns immediately and the semaphore value remains unchanged.

### RETURN VALUE

  On failure a special value is returned as described below. Otherwise the return value is undetermined. (Actually it is somehow derived from the current value of the semaphore.)

### ERRORS

  `0xffff`
    sem does not refer to a valid semaphore.

### BUGS

  The normal return value should not depend on the current value of the semaphore. In the current implementation number `0xffff` can be returned under normal circumstances too and it is undistinguishable from the error code. Moreover the caller cannot figure out, whether if taking the semaphore was successful or not.

[return to index]

### NAME

  rt_sem_wait_until, rt_sem_wait_timed - wait a semaphore with timeout

### SYNOPSIS

  #include "rtai_sched.h"

  int rt_sem_wait_until (SEM* sem, RTIME time);

  int rt_sem_wait_timed (SEM* sem, RTIME delay);

### DESCRIPTION

  rt_sem_wait_until and rt_sem_wait_timed are version of the semaphore wait (sometimes known as 'take' or 'P') operation. The semaphore value is decremented and tested. If it is still non-negative these functions return immediately. Otherwise the caller task is blocked and queued up. Queueing may happen in priority order or on FIFO base. This is determined by compile time option SEM_PRIORD. In this case these functions return if
  - The caller task is in the first place of the waiting queue and an other task issues a rt_sem_signal call;
  - Timeout occurs;
  - An error occurs (e.g. the semaphore is destroyed);
  In case of timeout the semaphore value is incremented before return.
  time is an absolute value. delay is relative to the current time.

### RETURN VALUE

  On failure a special value is returned as described below. Otherwise the return value is undetermined. (Actually it is somehow derived from the current value of the semaphore.)

### ERRORS

  `0xffff`
    sem does not refer to a valid semaphore.

### BUGS

  The normal return value should not depend on the current value of the semaphore. In the current implementation number `0xffff` can be returned under normal circumstances too and it is undistinguishable from the error code. Moreover the caller cannot figure out, whether if taking the semaphore was successful or not.

[return to index]