NetBSD/sbin/luactl/luactl.8

.\" $NetBSD: luactl.8,v 1.2 2013/10/17 08:21:03 wiz Exp $
.\"
.\" Copyright (c) 2011 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 October 17, 2013
.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 require
.Ar name module
.Nm
.Op Fl cq
.Cm load
.Ar name path
.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 required .
If a kernel subsystem is to use a Lua state, a state has to be
.Dq assigned
to it.
Once a module has been
.Dq 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 require, assign, and, 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 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.
.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 / .
.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 lua 9
.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 .