LOADER.LUA(8)

💖 LOADER.LUA(8) — the bootloader Lua binding module, bestie 💖

okay so real talk, this is a System Manager's Manual page for loader.lua, and it's genuinely one of the most useful little pages in the whole FreeBSD boot situation. buckle up 🎀

---

✨ NAME ✨

loader.lua — the bootloader Lua binding module 🦋

---

🌸 DESCRIPTION 🌸

The built-in Lua bindings for the FreeBSD boot loaders (the ones using the Lua interpreter, obvi) are available via the loader table.

The loader table is always available in Lua scripts. Like, no need to require it like you have to do with other loader-specific modules — it's just there. main character energy fr fr 👑

💅 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. iykyk but some boot loaders are 32-bit applications that then load a 64-bit kernel. In those cases, machine_arch represents the 32-bit architecture, not the 64-bit architecture. don't get it twisted 🙈
• 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. nap time bestie 😴
• 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. bye bye 👋
• 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(). she's versatile 💁‍♀️
• 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 command 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. so don't come for her about that 💀
• 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. slay ✅
  • 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. 😭 like. it literally does not come back.
• printc(str) — outputs the string using the loader's putchar() function. This function is also available globally as printc(). two names, one icon 🫶
• 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. ngl time is lowkey a vibe check in itself ⭐
• 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). so if you're looking for them, they're over there now — she moved out but still left a forwarding address 💅

🍓 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. iconic behavior honestly 🌈

---

🔥 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 <imp@FreeBSD.org>. thank you warner, we love you 🫶

---

💀 BUGS 💀

command() and perform() should return a tuple when there's CMD_ERROR or worse. yeah. that's the whole bug. it's giving "known issue, we're aware" 🙈

---

✨ and that's the page, bestie ✨

this one came out of the Debian side of things, dated March 29, 2025 — so go forth, boot responsibly, and remember: the loader table was always there for you 💖🎀🦋