RTAI api ---Semaphore function

rt_sem_init 
rt_sem_delete 
rt_sem_signal 
rt_sem_wait 
rt_sem_wait_if 
rt_sem_wait_until 

rt_sem_wait_timed

please refer to: https://www.rtai.org/userfiles/documentation/magma/html/api

**************************************************************************************************************************************************************

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).
*********************************************************************************************************
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.

********************************************************************************************************************
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.
****************************************************************************************************************
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.

***************************************************************************************************************
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.
*****************************************************************************************************************
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.