diff options
Diffstat (limited to 'static/freebsd/man8/cli.lua.8')
| -rw-r--r-- | static/freebsd/man8/cli.lua.8 | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/static/freebsd/man8/cli.lua.8 b/static/freebsd/man8/cli.lua.8 new file mode 100644 index 00000000..e47ecd3d --- /dev/null +++ b/static/freebsd/man8/cli.lua.8 @@ -0,0 +1,160 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org> +.\" +.\" 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 AUTHOR 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 AUTHOR 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 March 29, 2025 +.Dt CLI.LUA 8 +.Os +.Sh NAME +.Nm cli.lua +.Nd bootloader command line interpreter module +.Sh DESCRIPTION +.Nm +contains the main functionality required to add new CLI commands, which can be +executed at the loader prompt. +.Pp +Before hooking into the functionality provided by +.Nm , +it must be included with a statement such as the following: +.Pp +.Dl local cli = require("cli") +.Ss Adding new commands +New loader commands may be created by adding functions to the object returned by +requiring the +.Nm +module. +.Pp +For instance: +.Pp +.Bd -literal -offset indent -compact +local cli = require("cli") + +cli.foo = function(...) + -- Expand args to command name and the rest of argv. + -- These arguments are pushed directly to the stack by + -- loader, then handed off to cli_execute. cli_execute + -- then passes them on to the invoked function, where + -- they appear as varargs that must be peeled apart into + -- their respective components. + local _, argv = cli.arguments(...) + + print("This is the foo command!") + for k, v in ipairs(argv) do + print("arg #" .. tostring(k) .. ": '" .. v .. "'") + end + -- Perform a loader command directly. This will not get + -- dispatched back to Lua, so it is acceptable to have a + -- function of the exact same name in loader. Lua will + -- have the first chance to handle any commands executed + -- at the loader prompt. + loader.perform("foo") +end +.Ed +.Pp +This function may be invoked by a user at the loader prompt by simply typing +.Ic foo . +Arguments may be passed to it as usual, space-delimited. +.Ss Default Commands +The +.Nm +module provides the following default commands: +.Bl -bullet +.\"-width toggle-module -offset indent +.It +.Ic autoboot +.It +.Ic boot +.It +.Ic boot-conf +.It +.Ic reload-conf +.It +.Ic disable-device +.It +.Ic disable-module +.It +.Ic enable-module +.It +.Ic toggle-module +.It +.Ic show-module-options +.El +.Pp +For +.Ic autoboot , +.Ic boot , +and +.Ic boot-conf , +the +.Xr core.lua 8 +module will load all ELF modules as-needed before executing the equivalent +built-in loader commands. +All non-kernel arguments to these commands are passed in the same order to the +loader command. +.Pp +The +.Ic reload-conf +command will reload the configuration from disk. +This is useful if you have manually changed currdev and would like to easily +reload the configuration from the new device. +.Pp +The +.Ic enable-module , +.Ic disable-module , +and +.Ic toggle-module +commands manipulate the list of modules to be loaded along with the kernel. +Modules blacklisted are considered disabled by +.Ic toggle-module . +These commands will override any such restriction as needed. +The +.Ic show-module-options +command will dump the list of modules that loader has been made aware of and +any applicable options using paged output. +.Pp +The +.Ic disable-device +command sets the environment variable that disables the device argument. +.Ss Exported Functions +The following functions are exported from +.Nm : +.Bl -tag -width cli.arguments -offset indent +.It Fn cli.arguments ... +Takes varargs passed on the stack from +.Xr loader 8 +to +.Ic cli_execute , +splits them out into two return values: the command name, traditionally argv[0], +and the rest of argv. +.El +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr core.lua 8 , +.Xr loader 8 +.Sh AUTHORS +The +.Nm +file was originally written by +.An Kyle Evans Aq Mt kevans@FreeBSD.org . |