In our exercises we use mainly the Alchemy API, but sometimes we need to also use the POSIX API. So the two API's used:
Although the API documentation of Xenomai is pretty good not all API functions are documented.
To really find out which functions are available for Xenomai one has the look at the xenomai header files at :
In Xenomai both the POSIX and the Alchemy API's use the standard errors defined in the headers :
In the both API's for each function is specified which specific errors are generated when an error happens.
However the more general errors like passing the wrong value to a function are not specified by the API .
Thus don't be surprised when you get an error code not specified in the API documentation.
IMPORTANT: always look up in the API what for possible errors a function returns, and write handler code for these errors!
The Alchemy API is very consistent in how it returns error codes. In general for the Alchemy API normal return values are 0 or positive, but a negative return value always means an error. Thus in case of a negative return value we have an error where the error code is minus the return value!
By looking at the error code one can already deal with the error. However sometimes one just want the program to stop, and print out the error in a human understable sentence.
With the strerror function one can easily do that. The following example demonstrates this :
#include <stdio.h>
#include <string.h>
#include <errno.h>
int retval,errcode;
/* send message */
retval = rt_task_send(&task_struct[1], &task_mcb , NULL, TM_INFINITE);
if (retval < 0 )
{
errcode=-retval;
printf("ERROR %d : %s\n",errcode,strerror(errcode));
} else {
printf("SUCCESS\n");
}
The POSIX API is not so consistent in how it returns error codes. For each function it can be different, so always look at the API documentation where is specified which and how specific errors are generated when an error happens.
The most common variations in POSIX:
#include <stdio.h>
#include <string.h>
#include <errno.h>
int retval,errcode;
retval = pthread_create(...);
if (retval != 0 )
{
errcode=retval;
printf("ERROR %d : %s\n",errcode,strerror(errcode));
} else {
printf("SUCCESS\n");
}
#include <stdio.h>
#include <string.h>
#include <errno.h>
int retval,errcode;
retval = ioctl(fd,...);
if (retval == -1 )
{
errcode=errno;
printf("ERROR %d : %s\n",errcode,strerror(errcode));
} else {
printf("SUCCESS\n");
}
symerror() is a small helper returning the error label
in compact ascii form, unlike the textual description strerror() provides.
To use symerror() you must the following include in your
code: #include <xenomai/init.h>
Since strerror() is influenced by the current locale, I would not expect
it to stay in primary mode unconditionally.
However symerror() is guaranteed to stay in primary mode and
never migrate to secondary mode. Note: primary mode is realtime in xenomai's cobalt kernel, secondary mode is none-realtime
in linux.
Thus if you want realtime behavior of your error handling code then use symerror() instead
of strerror() at the cost of having a small error label instead of a longer textual description.
However in most cases when something goes wrong the realtime behavior is not important anymore, wrong is just wrong. So in general it is adviced to use strerror(), because when an error happens you don't care you loose the realtime behavior, but you prefer to get a good message explaining the error.
Eg. for ERROR 9 the strerror() gives the error string "Bad file descriptor" and symerror only gives the error symbol "EBADF".