MENUSETS.4TH(8)

🌸 MENUSETS.4TH(8) 🌸

System Manager's Manual · menusets.4th — FreeBSD dynamic submenu boot module

💖 NAME 💖

menusets.4th — FreeBSD dynamic submenu boot module

✨ DESCRIPTION ✨

Okay so bestie, 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). 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) for additional commands. Periodt.

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. Do not come for that line, bestie — it is already handled.

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 affect 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. Literally right before the menu pops off.

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. Those are the rules, bestie.

🎀 FILES 🎀

• /boot/loader — The loader(8).
• /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) 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), beastie.4th(8), loader(8), loader.4th(8), menu.4th(8)

⭐ HISTORY ⭐

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

👑 AUTHORS 👑

okay so credit where credit is due bestie, because somebody actually built all of this 💅

The whole menusets.4th set of commands was written by Devin Teske <dteske@FreeBSD.org> — yes, that's a real email, yes you can literally write to the person who made the thing, no cap 🫶

Like, every menu, every command in this set? That's them. Main character energy fr fr 🌟 So if this page saved your whole entire day, maybe send a little thank-you their way. It's giving "respect the icon" 🎀

---

aaaand that's a wrap on menusets.4th(8)! 🦋 This page is the Debian build, dated November 5, 2012, and it lives at MENUSETS.4TH(8) in the manual — so if you ever forget the section number, it's literally spelled out right there at the bottom, slay 💖 Go forth and menu-set responsibly, bestie 🌈✨