MENU.4TH(7) Standards, Environments, and Macros MENU.4TH(7)

NAME


menu.4th - loader dynamic menu boot module

DESCRIPTION


The file that goes by the name of menu.4th is a set of commands designed to
display a dynamic menu system managed through a system of carefully named
environment variables. The commands of menu.4th by themselves are not
enough for most uses. Please refer to the examples below for the most
common situations, and to loader(7) for additional commands.

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

include menu.4th

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

The commands provided by it are:

menu-init Draws the menu bounding box and initializes
some internal state variables. This should be
called before any other menu-related
functions.
menu-display Displays the menu (configured via the below
documented environment variables) and blocks
on keyboard input, awaiting user action.
menu-erase Clears the screen area within the menu
bounding box.
menu-redraw Calls menu-erase and then redraws the menu.
menu-unset Unsets the environment variables associated
with individual menu items, clearing the way
for a new menu.
menu-clear Calls menu-unset and then menu-erase.

The environment variables that effect its behavior are:

loader_color
If set to "NO" (case-insensitive) or "0", causes the menu
to be displayed without color. The default is to use ANSI
coloring whenever possible. If serial boot is enabled,
color is disabled by default. Color features include the
use of ANSI bold for numbers appearing to the left of
menuitems and the use of special "ansi" variables described
below.

autoboot_delay
Number of seconds menu-display will wait before executing
menu_timeout_command (boot by default) unless a key is
pressed. If set to "NO" (case-insensitive) menu-display
will wait for user input and never execute
menu_timeout_command. If set to "-1", menu-display will
boot immediately, preventing both interruption of the
autoboot process and escaping to the loader prompt.
Default is "10". See loader(7) for additional information.

menu_timeout_command
The command to be executed after autoboot_delay seconds if
a key is not pressed. The default is boot.

loader_menu_frame
Sets the desired box style to draw around the boot menu.
Possible values are: "single" (the default), "double", and
"none".

loader_menu_timeout_x
Sets the desired column position of the timeout countdown
text. Default is 4.

loader_menu_timeout_y
Sets the desired row position of the timeout countdown
text. Default is 23.

loader_menu_title
The text to display above the menu. Default is "Welcome to
FreeBSD".

loader_menu_title_align
Default is to align loader_menu_title centered above the
menu. This can be set to "left" or "right" to instead
display the title left-or-right justified (respectively).

loader_menu_x
Sets the desired column position of the boot menu. Default
is 5.

loader_menu_y
Sets the desired row position of the boot menu. Default is
10.

menu_caption[x]
The text to be displayed for the numbered menuitem "x".

menu_command[x]
The command to be executed when the number associated with
menuitem "x" is pressed. See the list of included FICL
words below for some ideas.

menu_keycode[x]
An optional decimal ASCII keycode to be associated with
menuitem "x". When pressed, will cause the execution of
menu_command[x].

ansi_caption[x]
If loader_color is set (enabled by default), use this
caption for menuitem "x" instead of menu_caption[x].

toggled_text[x]
For menuitems where menu_command[x] is set to
"toggle_menuitem" (or a derivative thereof), the text
displayed will toggle between this and menu_caption[x].

toggled_ansi[x]
Like toggled_text[x] except used when loader_color is
enabled (default).

menu_caption[x][y]
For menuitems where menu_command[x] is set to
"cycle_menuitem" (or a derivative thereof), the text
displayed will cycle between this and other
menu_caption[x][y] entries.

ansi_caption[x][y]
Like menu_caption[x][y] except used when loader_color is
enabled (default).

menu_acpi
When set to a number "x" associated with a given menuitem,
that menuitem will allow to select acpi-user-options (see
eeprom(8)).

menu_options
When set to a number "x", a single blank-line and an
"Options" header are inserted between menu_caption[x-1] and
menu_caption[x] (if configured).

menu_reboot
If set, adds a built-in "Reboot" menuitem to the end of the
last configured menuitem. If menu_options is configured,
the "Reboot" menuitem will be inserted before the "Options"
separator.

In addition, it provides the following FICL words:

arch-i386? (-- BOOL) Returns true (-1) on i386 and false (0)
otherwise.
acpipresent? (-- BOOL)
Returns true (-1) if ACPI is present and false
(0) otherwise.
acpienabled? (-- BOOL)
Returns true (-1) if ACPI is enabled and false
(0) otherwise.
toggle_menuitem (N -- N)
Toggles menuitem "N" between menu_caption[x]
and toggled_text[x] (where "N" represents the
ASCII decimal value for "x").
cycle_menuitem (N -- N)
Cycles menuitem "N" between menu_caption[x][y]
entries (where N represents the ASCII decimal
value for x).

For all values of "x" above, use any number between 1 through 9. Sorry,
double-digits are not currently supported.

FILES


/boot/loader The loader(7).
/boot/forth/menu.4th menu.4th itself.
/boot/loader.rc loader(7) bootstrapping script.

EXAMPLES


A simple boot menu:

include /boot/forth/menu.4th
menu-init
set menu_caption[1]="Boot"
set menu_command[1]="boot"
set menu_options=2
set menu_caption[2]="Option: NO"
set toggled_text[2]="Option: YES"
set menu_command[2]="toggle_menuitem"
set menu_timeout_command="boot"
set menu_reboot
menu-display

SEE ALSO


loader.conf(5), beastie.4th(7), loader(7), loader.4th(7), eeprom(8)

illumos July 20, 2018 illumos