From 5cb84ec742fd33f78c8022863fadaa8d0d93e176 Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sat, 25 Apr 2026 15:32:58 -0400 Subject: feat: Added NetBSD man pages --- static/netbsd/man9/klua_lock.9 | 181 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 static/netbsd/man9/klua_lock.9 (limited to 'static/netbsd/man9/klua_lock.9') diff --git a/static/netbsd/man9/klua_lock.9 b/static/netbsd/man9/klua_lock.9 new file mode 100644 index 00000000..4b3a391c --- /dev/null +++ b/static/netbsd/man9/klua_lock.9 @@ -0,0 +1,181 @@ +.\" $NetBSD: klua_lock.9,v 1.5 2017/04/16 06:36:03 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_LOCK 9 +.Os +.Sh NAME +.Nm klua_lock , +.Nm klua_unlock , +.Nm klua_close , +.Nm klua_newstate , +.Nm kluaL_newstate +.Nd Lua kernel bindings +.Sh SYNOPSIS +.In sys/lua.h +.Ft void +.Fn klua_lock "klua_State *K" +.Ft void +.Fn klua_unlock "klua_State *K" +.Ft void +.Fn klua_close "klua_State *K" +.Ft "klua_State *" +.Fo klua_newstate +.Fa "lua_Alloc f" +.Fa "void *ud" +.Fa "const char *name" +.Fa "const char *desc" +.Fa "int ipl" +.Fc +.Ft "klua_State *" +.Fn kluaL_newstate "void *ud" "const char *name" "const char *desc" "int ipl" +.Sh DESCRIPTION +The Lua kernel bindings are designed to provide functionality to reuse Lua +scripts maintained by the +.Xr lua 9 +driver. +A +.Xr driver 9 +can be extended with dynamically managed Lua code with optional functionality +injected from userland with the +.Xr luactl 8 +utility. +.Pp +The kernel structure +.Ft klua_State +is defined as follows: +.Bd -literal +typedef struct _klua_State { + lua_State *L; + kmutex_t ks_lock; + bool ks_user; /* state created by user (ioctl) */ +} klua_State; +.Ed +.Pp +The first element +.Ft L +of the structure points to a standard Lua state structure. +The second element +.Ft ks_lock +is used to protect integrity during cross-thread access to the Lua state. +The third element +.Ft ks_user +indicates whether the structure was created from the kernel space or userland. +This parameter is used in the logic of +.Xr luactl 8 , +to prohibit the destruction of state from an opposing side. +Destroying kernel state from userland for example. +.Pp +The kernel Lua API is designed after the userland Lua API. +.Ss List of Functions +.Bl -column "kluaL_newstateX" "luaL_newstateX" "create a Lua state with custom allocatorX" +.It Sy kernel API Ta Sy userland API Ta Sy Description +.It Xr klua_lock 3 Ta lua_lock Ta lock a Lua state +.It Xr klua_unlock 3 Ta lua_unlock Ta unlock a Lua state +.It Xr klua_close 3 Ta lua_close Ta destroy a Lua state +.It Xr klua_newstate 3 Ta lua_newstate Ta create a Lua state with custom allocator +.It Xr kluaL_newstate 3 Ta luaL_newstate Ta create a Lua state +.El +.Pp +The +.Fn klua_lock +and +.Fn klua_unlock +functions must be used before and after the use of the +.Ft 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 +.Xr luactl 8 +utility when accessing +.Fa K . +.Pp +The +.Fn klua_close +function destroys the kernel Lua state. +.Pp +The +.Fn klua_newstate +and +.Fn kluaL_newstate +functions are used to create and register a new kernel Lua state. +.Fn klua_newstate +takes an additional standard parameter of type +.Fa f , +defined by the proper Lua release and an opaque pointer +.Fa ud +that Lua passes to the allocator in every call. +The +.Ft name +parameter identifies the kernel Lua state with a text literal. +It must not begin with the +.Dq _ +character and must be unique for the +.Xr lua 9 +device. +The +.Ft desc +parameter describes the Lua state in plain text. +The +.Ft ipl +argument is used to define the type of +.Xr mutex 9 +by the system interrupt priority level. +.Sh RETURN VALUES +The +.Fn klua_lock , +.Fn klua_unlock , +and +.Fn klua_close +functions do not return anything upon completion. +.Pp +The +.Fn klua_newstate +and +.Fn kluaL_newstate +functions return a pointer to newly created to the +.Ft klua_State +structure or otherwise in case of failure the +.Dv NULL +value. +.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_mod_register 9 , +.Xr klua_mod_unregister 9 , +.Xr intro 9lua +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org . -- cgit v1.2.3