Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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

NetBSD 10.99                    April 15, 2017                    NetBSD 10.99