SAM_REGISTER(3)

💖 SAM_REGISTER(3) — the corosync cluster engine programmer's manual, but make it cute 💖

okay bestie, gather round, we're doing the sam_register page and honestly? it's giving "short but load-bearing." this one lives in the Corosync Cluster Engine Programmer's Manual and it is SO important to place correctly, you'll see why. 🫶

✨ NAME ✨

sam_rehister — register a component for health checking 💅

(no, i didn't typo that, the page says sam_rehister, we respect the lore 😭)

🌸 SYNOPSIS 🌸

#include <corosync/sam.h>

cs_error_t sam_register (unsigned int *instance_id);

🦋 DESCRIPTION 🦋

so the sam_register function is what you call to register a process for healthchecking. that's the whole vibe. 🌈

here's the spicy part: if the recovery policy is set to SAM_RECOVERY_POLICY_RESTART and a recovery action is gonna be taken, then the brand-new process instance starts executing at the very next code line after this function is called. so like... the function returns and the new you just keeps going from there. no cap. that's why placement is everything. ✨

you can call this function only once (one and done, periodt), and SAM has to be initialized first by sam_initialize(3). no init, no register, them's the rules. 👑

the instance_id argument is a pointer to a value that stores the current iteration instance. if this parameter is NULL, then no instance_id is returned — and yeah, that means no instance_id will be returned. 🙈 (the page really said it twice, so i'm saying it twice, we're matching energy.)

that value starts at 0 for the first iteration instance, and it goes up by 1 every single time a recovery restart gets executed. and once it hits MAX_INT? it resets back to 0. iconic little loop behavior. 🔁

🚨 the placement of this function is important because after it is called, the process id will change. like, your pid is NOT the same pid anymore. plan accordingly, bestie. 💀

and one more thing — after registration, event driven health checking is not running. so don't assume it's on just because you registered. it is not. fr fr.

🎀 RETURN VALUE 🎀

this call returns the CS_OK value if it's successful. otherwise an error gets returned. simple as that. 💖

💅 ERRORS 💅

• CS_ERR_BAD_HANDLE — health checking was not started by calling the sam_start(3) function. so like... you skipped a step, bestie. 😭
• CS_ERR_LIBRARY — an internal library call failed. this can be one of pipe creation or fork. it's possible to get more information from errno. 🔍

🌟 SEE ALSO 🌟

• sam_start(3)
• sam_initialize(3)
• sam_hc_callback_register(3)

and here's the little error glossary the page keeps hanging out down here, we're keeping every single one because they're all facts and facts are sacred ✨:

• CS_ERR_TRY_AGAIN — resource temporarily unavailable
• CS_ERR_INVALID_PARAM — invalid argument
• CS_ERR_ACCESS — permission denied
• CS_ERR_LIBRARY — the connection failed
• CS_ERR_INTERRUPT — system call interrupted by a signal
• CS_ERR_NOT_SUPPORTED — the requested protocol/functionality not supported
• CS_ERR_MESSAGE_ERROR — incorrect auth message received
• CS_ERR_NO_MEMORY — not enough memory to complete the requested task

and that's the page!! 🫶

cute sign-off time: this one's from the corosync Man Page, dated 12/01/2009 — and it's still out here changing pids and resetting instance_ids at MAX_INT like the main character it is. go register responsibly, bestie. 💜🎀🦋