---
name: "loader.lua"
section: "8"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/loader.lua"
---

# loader.lua(8)

bootloader Lua binding module

## 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)](/sysctl/8.md) value.

- **machine\_arch**

  The target's *hw.machine\_arch* [sysctl(8)](/sysctl/8.md) 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)](/cli.lua/8.md) 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 *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.

- **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)](/gfx.lua/8.md).

### 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)](/loader.conf/5.md), [core.lua(8)](/core.lua/8.md), [gfx.lua(8)](/gfx.lua/8.md), [loader(8)](/loader/8.md), [sysctl(8)](/sysctl/8.md)

## AUTHORS

The **loader.lua** man page was written by Warner Losh ⟨*imp@FreeBSD.org*⟩.

## BUGS

**command**() and **perform**() should return a tuple when there's *CMD\_ERROR* or worse.