1.\" $NetBSD: lua.4,v 1.5 2014/07/26 20:04:05 wiz Exp $ 2.\" 3.\" Copyright (c) 2013 Marc Balmer <marc@msys.ch> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd July 25, 2014 18.Dt LUA 4 19.Os 20.Sh NAME 21.Nm lua 22.Nd control in-kernel Lua states 23.Sh SYNOPSIS 24.Cd "lua*" 25.Pp 26.In sys/types.h 27.In sys/lua.h 28.Sh DESCRIPTION 29The 30.Nm 31device allows to create, control, and delete Lua states in the kernel 32through an 33.Xr ioctl 2 34interface. 35Moreover, 36.Nm 37can be used to load Lua scripts into a Lua state and to assign modules to an 38existing state, i.e. perform the equivalent of the Lua command 39.Em require . 40.Nm 41is also used to retrieve information about currently active Lua states. 42.Sh LUA MODULES 43Lua modules are used to provide functionality to Lua scripts not available 44in the language itself, e.g. to access core kernel functionality like 45printing text on the console. 46Unlike in user space Lua, where Lua modules are files in the filesystem, 47modules must be provided to 48.Nm 49in the form of loadable kernel modules that register their 50functionality with 51.Nm . 52Modules are loaded using the 53.Ic require 54Lua command; whether this command 55is available or not is controlled by a 56.Xr sysctl 8 57variable. 58.Nm 59by default tries to load a kernel module named 60.Em luafoo.kmod 61when it encounters the Lua command 62.Em require 'foo' . 63.Sh SYSCTL VARIABLES 64The operation of 65.Nm 66can be controlled by means of the following 67.Xr sysctl 8 68variables: 69.Bl -tag -width XXXX 70.It Dv kern.lua.autoload 71When set to 1, 72.Nm 73tries to autoload kernel modules. 74.Pp 75The default value is 1. 76.It Dv kern.lua.bytecode 77When set to 1, loading of Lua bytecode is allowed. 78.Pp 79The default value is 0. 80.It Dv kern.lua.maxcount 81When set to a value > 0, 82.Nm 83limits the number of instructions executed 84to this number. 85.Pp 86The default value is 0. 87.It Dv kern.lua.require 88When set to 1, enables the 89.Em require 90command in Lua. 91.Pp 92The default value is 1. 93.It Dv kern.lua.verbose 94When set to a value > 0, verbosity is increased. 95.Pp 96The default value is 0. 97.El 98.Sh IOCTL INTERFACE 99The following structures and constants are defined in the 100.In sys/lua.h 101header file: 102.Pp 103.Bl -tag -width XXXX -compact 104.It Dv LUAINFO(struct lua_info) 105Returns information about the 106.Nm 107states in the 108.Fa lua_info 109structure: 110.Bd -literal 111#define MAX_LUA_NAME 16 112#define MAX_LUA_DESC 64 113 114struct lua_state_info { 115 char name[MAX_LUA_NAME]; 116 char desc[MAX_LUA_DESC]; 117 bool user; 118}; 119 120struct lua_info { 121 int num_states; /* total number of Lua states */ 122 struct lua_state_info *states; 123}; 124.Ed 125.Pp 126.It Dv LUACREATE(struct lua_create) 127Create a new named Lua state with name and description in the 128.Fa lua_create 129structure: 130.Bd -literal 131struct lua_create { 132 char name[MAX_LUA_NAME]; 133 char desc[MAX_LUA_DESC]; 134}; 135.Ed 136.Pp 137.It Dv LUADESTROY(struct lua_create) 138Destroy a named Lua state. 139.Pp 140.It Dv LUAREQUIRE(struct lua_require) 141Perform the equivalent of the Lua command 142.Em require 143in a named state. 144The name of the state and of the module name is passed in the 145.Fa lua_require 146structure: 147.Bd -literal 148#define LUA_MAX_MODNAME 32 149 150struct lua_require { 151 char state[MAX_LUA_NAME]; 152 char module[LUA_MAX_MODNAME]; 153}; 154.Ed 155.Pp 156.It Dv LUALOAD(struct lua_load) 157Load Lua code from the filesystem into a named Lua state. 158The name of the state and the path to the Lua code are passed in the 159.Fa lua_load 160structure: 161.Bd -literal 162struct lua_load { 163 char state[MAX_LUA_NAME]; 164 char path[MAXPATHLEN]; 165}; 166.Ed 167.Pp 168The path element of the 169.Fa lua_load 170structure must contain at least one 171.Sq / 172character. 173.Pp 174.El 175.Sh FILES 176.Bl -tag -width "/dev/lua" -compact 177.It /dev/lua 178Lua device file. 179.El 180.Sh SEE ALSO 181.Xr ioctl 2 , 182.Xr luactl 8 183.Sh HISTORY 184The 185.Nm 186device first appeared in 187.Nx 7.0 . 188.Sh AUTHORS 189.An -nosplit 190The 191.Nm 192driver was written by 193.An Marc Balmer Aq Mt mbalmer@NetBSD.org . 194.Sh CAVEATS 195The 196.Nm 197device is experimental. 198Incompatible changes might be made in the future. 199