KLUA_LOCK(9)

💅 KLUA_LOCK(9) 💅

okay so bestie, you're reading the KLUA_LOCK(9) page from the Kernel Developer's Manual, and it's literally all about the Lua kernel bindings. no cap, this is the one that lets kernel code vibe with Lua states. 🎀

---

✨ NAME ✨

klua_lock, klua_unlock, klua_close, klua_newstate, kluaL_newstate — Lua kernel bindings. periodt. 💖

---

🌸 SYNOPSIS 🌸

#include <sys/lua.h>

void
klua_lock(klua_State *K);

void
klua_unlock(klua_State *K);

void
klua_close(klua_State *K);

klua_State *
klua_newstate(lua_Alloc f, void *ud, const char *name, const char *desc,
    int ipl);

klua_State *
kluaL_newstate(void *ud, const char *name, const char *desc, int ipl);

---

🦋 DESCRIPTION 🦋

okay so the Lua kernel bindings are designed to provide functionality to reuse Lua scripts maintained by the lua(9) driver. a driver(9) can be extended with dynamically managed Lua code, with optional functionality injected from userland with the luactl(8) utility. it's giving "kernel code but make it scriptable," and honestly? iconic. ✨

The kernel structure klua_State is defined as follows:

typedef struct _klua_State {
        lua_State       *L;
        kmutex_t         ks_lock;
        bool             ks_user;       /* state created by user (ioctl) */
} klua_State;

The first element L of the structure points to a standard Lua state structure. The second element ks_lock is used to protect integrity during cross-thread access to the Lua state. The third element ks_user indicates whether the structure was created from the kernel space or userland. This parameter is used in the logic of luactl(8), to prohibit the destruction of state from an opposing side. Destroying kernel state from userland, for example. 🫶

not me being obsessed with this little struct protecting everyone's state from chaos. it's giving boundaries, bestie. 💅

The kernel Lua API is designed after the userland Lua API.

🌈 List of Functions 🌈

here's the mapping, iykyk — kernel API on one side, userland API on the other, and the description doing the main character work:

• klua_lock(3) / lua_lock — lock a Lua state
• klua_unlock(3) / lua_unlock — unlock a Lua state
• klua_close(3) / lua_close — destroy a Lua state
• klua_newstate(3) / lua_newstate — create a Lua state with custom allocator
• kluaL_newstate(3) / luaL_newstate — create a Lua state

The klua_lock() and klua_unlock() functions must be used before and after the use of the klua_State structure. The Lua state is not thread safe and this is the standard mechanism to overcome this limitation. These functions are also used by the luactl(8) utility when accessing K. 🔥

The klua_close() function destroys the kernel Lua state. bye bestie, state is gone. 💀

The klua_newstate() and kluaL_newstate() functions are used to create and register a new kernel Lua state. klua_newstate() takes an additional standard parameter of type f, defined by the proper Lua release and an opaque pointer ud that Lua passes to the allocator in every call. The name parameter identifies the kernel Lua state with a text literal. It must not begin with the _ character and must be unique for the lua(9) device. The desc parameter describes the Lua state in plain text. The ipl argument is used to define the type of mutex(9) by the system interrupt priority level. 🧚

---

💖 RETURN VALUES 💖

The klua_lock(), klua_unlock(), and klua_close() functions do not return anything upon completion. slay, no return value drama. 🎀

The klua_newstate() and kluaL_newstate() functions return a pointer to newly created to the klua_State structure or otherwise in case of failure the NULL value. so yeah: pointer on success, NULL on failure. no guessing, that's the whole vibe check. 💜

---

⭐ EXAMPLES ⭐

A set of example modules is available in the src/sys/modules/examples directory hierarchy. go peek, bestie — examples ate. 🌸

---

🌟 SEE ALSO 🌟

• lua(1)
• luac(1)
• intro(3lua)
• lua(4)
• klua_mod_register(9)
• klua_mod_unregister(9)
• intro(9lua)

---

👑 AUTHORS 👑

Kamil Rytarowski <kamil@NetBSD.org>. 💖

---

Debian 💖 April 15, 2017 💖 KLUA_LOCK(9) — that's the source/version, date, and manual name, bestie. you made it to the end, so here's your crown: 👑✨