.\" $NetBSD: luactl.8,v 1.7 2017/04/10 19:49:39 sevan Exp $
.\"
.\" Copyright (c) 2011, 2013 Marc Balmer <marc@msys.ch>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd April 10, 2017
.Dt LUACTL 8
.Os
.Sh NAME
.Nm luactl
.Nd control kernel Lua states
.Sh SYNOPSIS
.Nm
.Op Fl cq
.Nm
.Op Fl cq
.Cm create
.Ar name
.Op desc
.Nm
.Op Fl cq
.Cm destroy
.Ar name
.Nm
.Op Fl cq
.Cm load
.Ar name path
.Nm
.Op Fl cq
.Cm require
.Ar name module
.Sh DESCRIPTION
The
.Nm
program allows the manipulation of Lua states in the kernel.
Lua states are created using the
.Dq Cm create
command (see below),
Lua bindings are provided as modules.
To make a Lua binding available to a state, it must be
.Dq Em required .
Once a module has been
.Dq Em required
by a state, it can not be unloaded from memory using the
.Xr modunload 8
command until the state using it has been destroyed.
.Pp
Lua code can be loaded from the file system into a state at anytime, please
note that code loaded into a state is immediately executed.
.Pp
When executed without a command,
.Nm
reads information about the
.Tn Lua
states and displays it.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl c
Create a Lua state before executing the command.
This flag is used for the
.Cm require
and
.Cm load
commands only, it
is ignored for all other commands.
.It Fl q
Operate quietly i.e. nothing is printed to stdout.
.El
.Sh COMMANDS
.Bl -tag -width Ds
.It Cm create Ar name Op Ar desc
Create a Lua state with name
.Ar name
and optional description
.Ar desc .
.It Cm destroy Ar name
Destroy the Lua state
.Ar name .
.It Cm load Ar name Pa path
Load Lua code in file
.Pa path
into the Lua state
.Ar name .
Note that the path name must contain at least one path separation character
.Pq Sq / .
.It Cm require Ar name module
Let the Lua state
.Ar name
use the bindings provided in module
.Ar module .
This is the equivalent of userland Lua code calling the
.Sq require
function.
.El
.Sh FILES
.Bl -tag -width "/dev/lua" -compact
.It /dev/lua
Lua device file.
.El
.Sh SEE ALSO
.Xr lua 4 ,
.Xr module 7 ,
.Xr modload 8 ,
.Xr modunload 8 ,
.Xr intro 9lua
.Sh HISTORY
The
.Nm
command first appeared in
.Nx 7.0 .
.Sh AUTHORS
The
.Nm
program was written by
.An Marc Balmer Aq Mt marc@msys.ch .