intro(3rtapi)

✨ intro(3rtapi) — the RTAPI lore drop ✨

okay bestie, sit down, grab a boba, because this is the rtapi intro page from section 3 of the manual, and it's literally the vibe check for the whole RTAPI API. 💖

---

🌸 NAME 🌸

rtapi — Introduction to the RTAPI API

---

🦋 DESCRIPTION 🦋

RTAPI is a library that gives you one uniform API across several real time operating systems. As of LinuxCNC 2.7, the supported ones are POSIX threads and RTAI. periodt. 💅

---

🎀 HEADER FILES 🎀

rtapi.h

The file rtapi.h defines the RTAPI for both realtime and non-realtime code. This is a glow-up from Rev 2, where the non-realtime API lived in ulapi.h and used different function names (not it). The symbols RTAPI and ULAPI are what decide which mode is being compiled — RTAPI for realtime, ULAPI for non-realtime. 🫶

rtapi_math.h

The file rtapi_math.h defines floating-point functions and constants. Use this one instead of <math.h> in rtapi real-time components. no cap. ✨

rtapi_string.h

The file rtapi_string.h defines string-related functions. Use it 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's the one you want 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, like INT_MIN and INT_MAX. Use this instead of <limits.h>, because that header file is simply not available to kernel modules. 😭

---

💜 REALTIME CONSIDERATIONS 💜

Non-realtime code

Some functions are just not available in non-realtime code. That includes functions that perform direct device access such as rtapi_inb(3). 🙈

Init/cleanup code

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

Realtime code

Only a few functions may be called from realtime code. That 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). read that again bestie, it matters. 🔥

Simulator

For an RTAPI module to be buildable in the "sim" environment (that's the 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). That 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. that's the whole system, slay. 🎀

---

💖 that's the page, bestie. go forth and write realtime code that actually builds.

and that's a wrap on intro(3rtapi) — brought to you by the LinuxCNC Documentation crew, dated 2006-10-02. iconic of them, fr fr. ✨👑💅