SYSCALL_HELPER_REGISTER(9freebsd)

💖 SYSCALL_HELPER_REGISTER 💖 — kernel syscall registration routines

okay bestie, welcome to the SYSCALL_HELPER_REGISTER(9) page, straight out of the Kernel Developer's Manual. this is the one where you learn how to slide a whole new system call into the kernel's little black book, and how to take it back out again. sit down, hydrate, let's go ✨

---

📖 NAME 📖

syscall_helper_register, syscall_helper_unregister — kernel syscall registration routines 🫶

---

✨ SYNOPSIS ✨

#include <sys/sysent.h>

int
syscall_helper_register(struct syscall_helper_data *sd, int flags);

int
syscall_helper_unregister(struct syscall_helper_data *sd);

🌸 INITIALIZER MACROS 🌸

struct syscall_helper_data
SYSCALL_INIT_HELPER(syscallname);

struct syscall_helper_data
SYSCALL_INIT_HELPER_F(syscallname, int flags);

🦋 COMPATIBILITY INITIALIZER MACROS 🦋

struct syscall_helper_data
SYSCALL_INIT_HELPER_COMPAT(syscallname);

struct syscall_helper_data
SYSCALL_INIT_HELPER_COMPAT_F(syscallname, int flags);

---

💅 DESCRIPTION 💅

so, syscall_helper_register() registers a system call. periodt. it takes that struct syscall_helper_data sd and that struct is literally the blueprint — it tells the kernel everything it needs to know about your syscall registration:

struct syscall_helper_data {
        struct sysent   new_sysent;
        struct sysent   old_sysent;
        int             syscall_no;
        int             registered;
};

the only valid flag you can pass in the flags argument of syscall_helper_register() is SY_THR_STATIC. and bestie, listen — that flag prevents the syscall from being unregistered. it's giving permanent marker, not pencil 😭

before you even use the struct, you have to initialize it with one of the SYSCALL_INIT_HELPER*() macros. no skipping steps, no shortcuts. in new code, syscall implementation functions shall be named sys_syscallname() and you use the regular macros. that's the vibe. that's the standard. ✨

but if you're dealing with legacy syscall functions whose names don't have that "sys_" prefix, the "COMPAT" versions of the macros are there for you. iconic of them honestly.

and for the "F" variants of the initializer macros, the only valid flag in the flags argument is SYF_CAPENABLED. that flag means the syscall is allowed in capability mode. like, it gets a hall pass 🎀

now for the other one: syscall_helper_unregister() unregisters a system call. it takes the same struct syscall_helper_data sd that you initialized the way described above and that was used in a successful invocation of syscall_helper_register(). same struct, no imposters 🙈

---

🫶 RETURN VALUES 🫶

if everything goes right, syscall_helper_register() and syscall_helper_unregister() return 0. otherwise, they return an error. that's it, that's the whole thing 💜

---

💀 ERRORS 💀

the syscall_helper_register() call will fail and the syscall will not be registered if:

• [EINVAL] — the flags argument contained a value other than SY_THR_STATIC. wrong flag, no entry, sorry babe 🚫
• [EINVAL] — the specified syscall number, sd.syscall_no (SYS_syscallname), was outside of the valid range of system call numbers (zero through SYS_MAXSYSCALL). out of bounds = out of luck.
• [ENFILE] — the system call table does not have any available slots. the club is full, the bouncer said no 😭
• [EEXIST] — the specified syscall number, sd.syscall_no (SYS_syscallname), was already in use. bestie that seat is taken 💀

---

👑 SEE ALSO 👑

SYSCALL_MODULE(9) — go read that one next, iykyk 🌈

---

okay that's the whole page!! this beauty came to you from the Debian build, dated February 10, 2018, and it lives in section 9 as SYSCALL_HELPER_REGISTER(9). register responsibly, unregister even more responsibly, and don't you dare try to unregister something you flagged with SY_THR_STATIC 🎀💖✨