---
name: "menusets.4th"
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/menusets.4th"
---

# menusets.4th(8)

FreeBSD dynamic submenu boot module

## NAME

**menusets.4th** – FreeBSD dynamic submenu boot module

## DESCRIPTION

The file that goes by the name of **menusets.4th** is a set of commands designed to add submenu functionality to the dynamic menu system provided by [menu.4th(8)](/menu.4th/8.md). Submenus are managed through a system of carefully named environment variables. The commands of **menusets.4th** by themselves are not enough for most uses. Please refer to the examples below for the most common situations, and to [menu.4th(8)](/menu.4th/8.md) for additional commands.

Before using any of the commands provided in **menusets.4th**, it must be included through the command:

```
include menusets.4th
```

This line is present in the default */boot/menu-commands.4th* file, so it is not needed (and should not be re-issued) in a normal setup.

The commands provided by it are:

- **menuset-loadsetnum**

  Takes a single integer on the stack to identify the menuset environment variables to be activated (see environment variables below).

- **menuset-loadinitial**

  If $menuset\_initial is set, passes the value to menuset-loadsetnum. The value must be a number.

- **menusets-unset**

  Unsets the environment variables associated with all menusets. Increments starting at 1 and stops at the first unconfigured menuset. A menuset is considered configured if the caption for item 1 is set.

The environment variables that effect its behavior are:

- *menuset\_initial*

  Number to pass to menuset-loadsetnum when menuset-loadinitial is called.

- *menuset\_nameN*

  Used to give a name to a menuset.

When a menuset is NOT given a name (the default), menuset N is comprised of the following environment variables:

- *ansisetN\_caption\[x\]*

  \-\> ansi\_caption\[x\]

- *ansisetN\_caption\[x\]\[y\]*

  \-\> ansi\_caption\[x\]\[y\]

- *menusetN\_acpi*

  \-\> menu\_acpi

- *menusetN\_caption\[x\]*

  \-\> menu\_caption\[x\]

- *menusetN\_caption\[x\]\[y\]*

  \-\> menu\_caption\[x\]\[y\]

- *menusetN\_command\[x\]*

  \-\> menu\_command\[x\]

- *menusetN\_init*

  \-\> “evaluated”

- *menusetN\_init\[x\]*

  \-\> menu\_init\[x\]

- *menusetN\_keycode\[x\]*

  \-\> menu\_keycode\[x\]

- *menusetN\_options*

  \-\> menu\_options

- *menusetN\_optionstext*

  \-\> menu\_optionstext

- *menusetN\_reboot*

  \-\> menu\_reboot

- *toggledsetN\_ansi\[x\]*

  \-\> toggled\_ansi\[x\]

- *toggledsetN\_text\[x\]*

  \-\> toggled\_text\[x\]

When you choose to give a menuset a name (by setting $menuset\_nameN), menuset N is instead comprised of the following environment variables:

- *NAMEansi\_caption\[x\]*

  \-\> ansi\_caption\[x\]

- *NAMEansi\_caption\[x\]\[y\]*

  \-\> ansi\_caption\[x\]\[y\]

- *NAMEmenu\_acpi*

  \-\> menu\_acpi

- *NAMEmenu\_caption\[x\]*

  \-\> menu\_caption\[x\]

- *NAMEmenu\_caption\[x\]\[y\]*

  \-\> menu\_caption\[x\]\[y\]

- *NAMEmenu\_command\[x\]*

  \-\> menu\_command\[x\]

- *NAMEmenu\_init*

  \-\> “evaluated”

- *NAMEmenu\_init\[x\]*

  \-\> menu\_init\[x\]

- *NAMEmenu\_keycode\[x\]*

  \-\> menu\_keycode\[x\]

- *NAMEmenu\_options*

  \-\> menu\_options

- *NAMEmenu\_optionstext*

  \-\> menu\_optionstext

- *NAMEmenu\_reboot*

  \-\> menu\_reboot

- *NAMEtoggled\_ansi\[x\]*

  \-\> toggled\_ansi\[x\]

- *NAMEtoggled\_text\[x\]*

  \-\> toggled\_text\[x\]

where “NAME” is the value of $menuset\_nameN. In the case of $NAMEmenu\_init ($menusetN\_init when $menuset\_nameN is unset), the value is evaluated as an FICL statement. This can be used to dynamically adjust the menuset variables right before the menu is activated.

In addition, **menusets.4th** provides the following FICL words:

- **menuset-checksetnum** (**N** **--**)

  Given a single integer on the stack, sets a global variable *menuset\_use\_name* to a boolean based on whether $menuset\_nameN is set (true) or not (false). Also sets $affix temporary variable (prefix or infix depending on menuset\_use\_name). Automatically called by menuset-loadsetnum and menusets-unset.

- **menuset-loadvar** (**--**)

  Used indirectly to shorten syntax and mitigate dictionary size. Requires the following temporary environment variables:

  - *type*

    should be set to one of: menu toggled ansi

  - *var*

    should be set to one of: caption command keycode text ...

  - *affix*

    either a prefix (menuset\_use\_name is true) or infix (menuset\_use\_name is false)

    If the global *menuset\_use\_name* is true, the variable ${type}\_${var} is made to equal the value of the variable ${affix}${type}\_${var} (note: in this case menuset-checksetnum has set $affix to $menuset\_nameN). Otherwise (when *menuset\_use\_name* is false), the variable ${type}\_${var} is made to equal the value of the variable ${type}set${affix}\_${var} (note: in this case menuset-checksetnum has set $affix to N).

    Both the global variable *menuset\_use\_name* and the environment variable $affix are automatically handled by menuset-checksetnum above (which is automatically called by menuset-loadsetnum).

- **menuset-unloadvar** (**--**)

  Used indirectly to shorten syntax and mitigate dictionary size. Like menuset-loadvar except it unsets the menuset variable. If global *menuset\_use\_name* is true ($affix is $menuset\_nameN), variable ${affix}${type}\_${var} is unset. Otherwise, $affix is N and variable ${type}set${affix}\_${var} is unset.

- **menuset-loadmenuvar** (**--**)

  Sets $type to “menu” and calls menuset-loadvar.

- **menuset-unloadmenuvar** (**--**)

  Sets $type to “menu” and calls menuset-unloadvar.

- **menuset-loadxvar** (**--**)

  Like menuset-loadvar except it takes an additional temporary variable $x. If the global *menuset\_use\_name* is true (making $affix equal $menuset\_nameN), sets variable ${type}\_${var}\[${x}\] to variable ${affix}${type}\_${var}\[${x}\]. Otherwise ($affix being N), sets the same variable to instead ${type}set{affix}\_${var}\[${x}\].

- **menuset-unloadxvar** (**--**)

  Like menuset-loadxvar except it unsets the menuset variable. If global *menuset\_use\_name* is true, unsets ${affix}${type}\_${var}\[${x}\]. Otherwise, unsets ${type}set${affix}\_${var}\[${x}\].

- **menuset-loadansixvar** (**--**)

  Sets $type to “ansi” and calls menuset-loadxvar

- **menuset-unloadansixvar** (**--**)

  Sets $type to “ansi” and calls menuset-unloadxvar

- **menuset-loadmenuxvar** (**--**)

  Sets $type to “ansi” and calls menuset-loadxvar

- **menuset-unloadmenuxvar** (**--**)

  Sets $type to “ansi” and calls menuset-unloadxvar

- **menuset-loadtoggledxvar** (**--**)

  Sets $type to “toggled” and calls menuset-loadxvar

- **menuset-unloadtoggledxvar** (**--**)

  Sets $type to “toggled” and calls menuset-unloadxvar

- **menuset-loadxyvar** (**--**)

  Like menuset-loadxvar except it takes an additional temporary variable $y. If the global *menuset\_use\_name* is true ($affix is $menuset\_nameN), sets variable ${type}\_${var}\[${x}\]\[${y}\] to ${affix}${type}\_${var}\[${x}\]\[${y}\]. Otherwise ($affix is N) sets the same variable to instead ${type}set${affix}\_${var}\[${x}\]\[${y}\].

- **menuset-unloadxyvar** (**--**)

  Like menuset-loadxyvar except it unsets the menuset variable. If the global *menuset\_use\_name* is true, unsets ${affix}${type}\_${var}\[${x}\]\[${y}\]. Otherwise, unsets ${type}set${affix}\_${var}\[${x}\]\[${y}\].

- **menuset-loadansixyvar** (**--**)

  Sets $type to “ansi” and calls menuset-loadxyvar.

- **menuset-unloadansixyvar** (**--**)

  Sets $type to “ansi” and calls menuset-unloadxyvar.

- **menuset-loadmenuxyvar** (**--**)

  Sets $type to “menu” and calls menuset-loadxyvar.

- **menuset-unloadmenuxyvar** (**--**)

  Sets $type to “menu” and calls menuset-unloadxyvar.

- **menuset-setnum-namevar** (**N** **--** **C-Addr/U**)

  Takes a single integer on the stack and replaces it with a string (in c-addr/u format) whose value is “menuset\_nameN”. For example, if given 1 returns “menuset\_name1”.

- **menuset-cleanup** (**N** **--**)

  Unsets all the various temporary variables, currently *type*, *var*, *x*, *y*, and *affix*.

For all values of “x” above, use any number between 1 through 9. Sorry, double-digits are not currently supported. For all values of “N” above, use any number between 1 and 65535.

## FILES

- */boot/loader*

  The [loader(8)](/loader/8.md).

- */boot/menu.4th*

  Dynamic menu module.

- */boot/menu-commands.4th*

  Contains the goto\_menu command.

- */boot/menusets.4th*

  **menusets.4th** itself.

- */boot/loader.rc*

  [loader(8)](/loader/8.md) bootstrapping script.

## EXAMPLES

A simple boot menu with a submenu:

```
include /boot/menu.4th
include /boot/menu-commands.4th
menu-init
set menuset1_caption[1]="Boot"
set menuset1_command[1]="boot"
set menuset1_caption[2]="Submenu..."
set menuset1_command[2]="2 goto_menu"
set menuset2_caption[1]="Back"
set menuset2_command[1]="1 goto_menu"
set menuset_initial=2
menuset-loadinitial
menu-display
```

The same boot menu with named menusets:

```
include /boot/menu.4th
include /boot/menu-commands.4th
menu-init
set menuset_name1=main
set mainmenu_caption[1]="Boot"
set mainmenu_command[1]="boot"
set mainmenu_caption[2]="Submenu..."
set mainmenu_command[2]="2 goto_menu"
set menuset_name2=sub
set submenu_caption[1]="Back"
set submenu_command[1]="1 goto_menu"
```

## SEE ALSO

[loader.conf(5)](/loader.conf/5.md), [beastie.4th(8)](/beastie.4th/8.md), [loader(8)](/loader/8.md), [loader.4th(8)](/loader.4th/8.md), [menu.4th(8)](/menu.4th/8.md)

## HISTORY

The **menusets.4th** set of commands first appeared in FreeBSD 10.0.

## AUTHORS

The **menusets.4th** set of commands was written by Devin Teske ⟨*dteske@FreeBSD.org*⟩.