NAME

       rtapi - Introduction to the RTAPI API

DESCRIPTION

       RTAPI is a library providing a uniform API for several real time operating systems.  As of
       LinuxCNC 2.7, POSIX threads and RTAI are supported.

HEADER FILES

   rtapi.h
       The file rtapi.h defines the RTAPI for both realtime and non-realtime  code.   This  is  a
       change from Rev 2, where the non-realtime (user space) API was defined in ulapi.h and used
       different function names.  The symbols RTAPI and ULAPI are used to determine which mode is
       being compiled, RTAPI for realtime and ULAPI for non-realtime.

   rtapi_math.h
       The  file  rtapi_math.h defines floating-point functions and constants.  It should be used
       instead of <math.h> in rtapi real-time components.

   rtapi_string.h
       The file rtapi_string.h defines string-related functions.  It should be  used  instead  of
       <string.h> in rtapi real-time components.

   rtapi_byteorder.h
       This  file  defines  the  preprocessor  macros  RTAPI_BIG_ENDIAN, RTAPI_LITTLE_ENDIAN, and
       RTAPI_FLOAT_BIG_ENDIAN as true or false depending on the  characteristics  of  the  target
       system.   It  should  be  used  instead  of  <endian.h> (userspace) or <linux/byteorder.h>
       (kernel space).

   rtapi_limits.h
       This file defines the minimum and maximum value of some fundamental integral  types,  such
       as  INT_MIN  and  INT_MAX.   This should be used instead of <limits.h> because that header
       file is not available to kernel modules.

REALTIME CONSIDERATIONS

   Userspace code
       Certain functions are not available in  userspace  code.   This  includes  functions  that
       perform direct device access such as rtapi_inb(3).

   Init/cleanup code
       Certain  functions  may  only  be  called  from realtime init/cleanup code.  This includes
       functions that perform memory allocation, such as rtapi_shmem_new(3).

   Realtime code
       Only a few functions may be called from  realtime  code.   This  includes  functions  that
       perform  direct  device  access  such as rtapi_inb(3).  It excludes most Linux kernel APIs
       such as do_gettimeofday(3) and many rtapi APIs such as rtapi_shmem_new(3).

   Simulator
       For an RTAPI module to be buildable in the "sim" environment (fake realtime system without
       special  privileges),  it  must  not use any linux kernel APIs, and must not use the RTAPI
       APIs for direct device access such  as  rtapi_inb(3).   This  automatically  includes  any
       hardware  device  drivers,  and also devices which use Linux kernel APIs to do things like
       create special devices or entries in the /proc filesystem.

RTAPI STATUS CODES

       Except as noted in specific manual pages, RTAPI returns negative errno values for  errors,
       and nonnegative values for success.