.\"	$NetBSD: klua_mod_register.9,v 1.5 2017/04/16 06:34:05 wiz Exp $
.\"
.\" Copyright (c) 2015 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Kamil Rytarowski.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 15, 2017
.Dt KLUA_MOD_REGISTER 9
.Os
.Sh NAME
.Nm klua_mod_register ,
.Nm klua_mod_unregister
.Nd Lua kernel bindings
.Sh SYNOPSIS
.In sys/lua.h
.Ft void
.Fn klua_mod_register "const char *name" "lua_CFunction open"
.Ft void
.Fn klua_mod_unregister "const char *name"
.Sh DESCRIPTION
The Lua kernel bindings are designed to provide functionality to Lua scripts
normally not available in the language itself, e.g. to access core kernel functionality.
This is achieved by utilizing the lua_modules functionality.
.Pp
The lua_module structure is declared as follows:
.Bd -literal
struct lua_module {
        char                    mod_name[LUA_MAX_MODNAME];
        lua_CFunction           open;
        int                     refcount;
        LIST_ENTRY(lua_module)  mod_next;
};
.Ed
.Pp
The
.Ft mod_name
defines the unique name of a module.
A C function must use the standard Lua protocol in order to communicate with
Lua, this part is maintained with the
.Ft open
element in the standard Lua way.
.Ft refcount
protects the module from being unloaded whilst still in use.
The last parameter,
.Ft mod_next ,
is used for the standard container
.Xr LIST 3 .
.Pp
The
.Fn klua_mod_register
function registers a new function which is made available to the
.Xr lua 9
device and Lua code using the
.Dv require
directive.
The
.Dv require
directive can be called from
.Xr luactl 8
and the kernel Lua version.
The
.Fa name
parameter is a unique identifier of the kernel Lua module.
.Fa open
points to a function used in the C to Lua binding,
defined with the appropriate standard Lua API.
.Pp
Once registered, a C function can be unregistered with the
.Fn klua_mod_unregister
function.
This function takes as its parameter the unique literal identifier of the
extending module.
.Sh EXAMPLES
A set of example modules is available in the
.Pa src/sys/modules/examples
directory hierarchy.
.Sh SEE ALSO
.Xr lua 1 ,
.Xr luac 1 ,
.Xr intro 3lua ,
.Xr lua 4 ,
.Xr klua_close 9 ,
.Xr klua_lock 9 ,
.Xr klua_newstate 9 ,
.Xr klua_unlock 9 ,
.Xr kluaL_newstate 9 ,
.Xr intro 9lua
.Sh AUTHORS
.An Kamil Rytarowski Aq Mt kamil@NetBSD.org .