rtapi_shmem(3rtapi)

💖 rtapi_shmem 💖

okay bestie, gather round, because this is rtapi_shmem(3rtapi) — the RTAPI page all about shared memory blocks, and it's genuinely so iconic. Three little functions, one big vibe: let different modules peek at the same chunk of memory. no cap. 🫶

---

✨ NAME ✨

rtapi_shmem — functions for managing shared memory blocks 🧠✨

---

🌸 SYNTAX 🌸

int rtapi_shmem_new(int key, int module_id, unsigned long int size)

int rtapi_shmem_delete(int shmem_id, int module_id)

int rtapi_shmem_getptr(int shmem_id, void ** ptr)

that's the whole lineup, bestie. three functions, all returning int, all living their main character era. 👑

---

🎀 ARGUMENTS 🎀

• key — this is the thing that identifies the memory block. it must be nonzero (like, non-negotiable, zero is not it 💅). and listen: every module that wants to use the same memory has to use the same key. same key = same block, periodt.
• module_id — the module identifier you got back from an earlier call to rtapi_init. yep, you gotta be initiated first, iykyk. 🦋
• size — how big you want your shared memory block, in bytes. 📏
• ptr — the pointer to the shared memory block. heads up though: the block may be mapped at a different address for different modules. so don't go assuming everyone sees it at the same spot, because they fr fr might not. 😭

---

🌈 DESCRIPTION 🌈

rtapi_shmem_new 🆕

rtapi_shmem_new allocates a block of shared memory. key identifies the memory block, and it must be non-zero. all modules wishing to access the same memory must use the same key. module_id is the ID of the module making the call (see rtapi_init).

the block will be at least size bytes, and may be rounded up. and lowkey this next bit matters: allocating many small blocks may be very wasteful. so don't be out here making a million tiny blocks, bestie, it's giving chaos. 💀

when a particular block is allocated for the first time, the contents are zeroed. subsequent allocations of the same block by other modules or processes will not touch the contents of the block. and that's actually a feature, not a bug — applications can use those bytes to see if they need to initialize the block, or if another module already did it for them. teamwork! 🤝✨

on success, it returns a positive integer ID, which is used for all subsequent calls dealing with the block. on failure it returns a negative error code. so if you get a negative number back, that's your sign, bestie. 🚩

rtapi_shmem_delete 🗑️

rtapi_shmem_delete frees the shared memory block associated with shmem_id. module_id is the ID of the calling module. returns a status code. bye bye block 👋

rtapi_shmem_getptr 📍

rtapi_shmem_getptr sets *ptr to point to the shared memory block associated with shmem_id. that's it, that's the whole job. simple, clean, slay. 💅

---

🔥 REALTIME CONSIDERATIONS 🔥

okay this part is the vibe check of the whole page, so pay attention:

• rtapi_shmem_getptr may be called from non-realtime code, init/cleanup code, or realtime tasks. flexible queen. 👑
• rtapi_shmem_new and rtapi_shmem_dete may not be called from realtime tasks. 🚫⏱️

not me pointing out that the page literally spells it rtapi_shmem_dete right there 🙈 — that's exactly how it's written, so that's exactly how i'm writing it. take it up with the source, bestie.

---

⭐ RETURN VALUE ⭐

so this section exists, but the page doesn't actually say anything under it — it just goes straight to the footer. 😭 the return value tea is all up in the DESCRIPTION section: rtapi_shmem_new gives you a positive integer ID on success and a negative error code on failure, and rtapi_shmem_delete returns a status code. that's the whole story, fr fr.

---

and that's the page, bestie!! 💖✨ this was rtapi_shmem(3rtapi) from the LinuxCNC Documentation, dated 2006-10-12 — vintage but still eating, no crumbs left. 🎀🦋 go forth and share that memory responsibly. mwah. 💅🌸