KLUA_LOCK(9) | Kernel Developer's Manual | KLUA_LOCK(9)

# NAME

`klua_lock`, `klua_unlock`, `klua_close`, `klua_newstate`, `kluaL_newstate` —
Lua kernel bindings

# 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

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.

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.

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

## List of Functions

kernel API | userland API | Description
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.

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.

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.

# EXAMPLES

A set of example modules is available in the src/sys/modules/examples directory hierarchy.

# 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>.

April 15, 2017 | NetBSD 9.2