LOADER.LUA(8) FreeBSD System Manager's Manual LOADER.LUA(8)
NAME
loader.lua - bootloader Lua binding module
DESCRIPTION
The built-in Lua bindings for the FreeBSD boot loaders using the Lua
interpreter are available via the loader table.
The loader table is always available in Lua scripts. There is no need to
require it like other loader-specific modules.
Exported Variables
The following variables are provided by the Lua interpreter in the loader
table:
machine The target's hw.machine sysctl(8) value.
machine_arch The target's hw.machine_arch sysctl(8) value. Some boot
loaders are 32-bit applications that then load a 64-bit
kernel. In these cases, machine_arch represents the 32-bit
architecture, not the 64-bit architecture.
lua_path The current lua loading path.
version The version of the boot program.
Exported Functions
The following functions are exported in the loader table.
delay(usec) Delay for usec microseconds.
command_error()
Returns the error string from the last command to fail.
command(argc, argv)
Like perform() but the arguments are already parsed onto
the stack.
exit(status) Exit the boot loader back to the firmware with a status of
status. The interpretation of this value is firmware
specific.
interpret(str)
Execute the loader builtin command str as if it were typed
by the user. This will first try to execute str as Lua.
If that fails, it will attempt to execute it as a cli
command, including those defined by the cli.lua(8)
mechanism. If that fails, it will attempt to execute it
as a builtin command and return the same values as
perform().
parse(str) Parses the command str into its words and return those
words on the stack.
getenv(name) Obtains the value of the environment variable name.
has_command(cmd)
returns true if commmand is present in the interpreter as
a builtin. Otherwise it returns nil and an error string.
It does not check the "cli" table to see if a user defined
command has been created.
has_feature(feature)
returns true if the feature is enabled. Otherwise it
returns nil and an error string.
perform(str) Execute the loader builtin command str. Returns the
result of the command, one of the following values:
loader.CMD_OK
The command completed successfully.
loader.CMD_WARN
The command was successful, but the user
stopped its output prematurely.
loader.CMD_ERROR
The command did not complete successfully.
Use command_error to retrieve the error.
loader.CMD_CRIT
The command returned a critical error that
was already printed.
loader.CMD_FATAL
The command determined continuation was not
possible and the loader panicked. In
practice, though, panic() does not return.
printc(str) Outputs the string using the loader's putchar() function.
This function is also available globally as printc().
setenv(name, value)
Insert or reset the environment variable name into the
loader's environment list. If no environment variable
with this name exists, one is created. If one exists, its
value is replaced.
time() Returns the loader's notion of time, in seconds since
1970. The value of loader's notion varies somewhat
between different loading environments.
unsetenv(name)
Removes the environment variable name from the loader's
environment list.
Compatibility
The functions fb_bezier(), fb_drawrect(), fb_line(), fb_putimage(),
fb_set_pixel(), term_drawrect(), and term_putimage() have moved to the
gfx table. They remain in the loader table for a transition period and
are documented in gfx.lua(8).
Default File
In addition, the Lua interpreters start with the file
/boot/lua/loader.lua when they start to boot the system. The default one
will fixup the screen, load the configuration files, check for a
password, and then load the menu or load the kernel file and then return.
If autoboot is enabled, the loaded files will boot.
SEE ALSO
loader.conf(5), core.lua(8), gfx.lua(8), loader(8), sysctl(8)
AUTHORS
The loader.lua man page was written by Warner Losh <
[email protected]>.
BUGS
command() and perform() should return a tuple when there's CMD_ERROR or
worse.
FreeBSD 14.1-RELEASE-p8 March 29, 2025 FreeBSD 14.1-RELEASE-p8