Man

Command Section
MENU.4TH(8)             FreeBSD System Manager's Manual            MENU.4TH(8)

NAME
     menu.4th - FreeBSD 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(8) 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/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(8) 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 only appear when running on
                     i386-compatible hardware, hint.acpi.0.rsdp is set
                     (indicating the presence of hardware ACPI support as
                     detected by loader(8)), and hint.acpi.0.disabled is not
                     set.  On non-i386 hardware, menuitems configured after
                     the ``menu_acpi'' menuitem will use a lower number (to
                     compensate for the missing ACPI menuitem) but continue to
                     function as expected.  On i386-compatible hardware
                     lacking ACPI support (as detected by loader(8)),
                     subsequent menuitems will retain their associated
                     numbers.

           hint.acpi.0.rsdp
                     Set automatically by loader(8) on i386-compatible
                     hardware when ACPI support is detected at boot time.
                     Effects the display of the ``menu_acpi'' menuitem (if
                     configured).

           hint.acpi.0.disabled
                     Effects the display of the menu_acpi menuitem.  If set,
                     the menuitem will display toggled_text[x]
                     (toggled_ansi[x] if loader_color is set), otherwise
                     menu_caption[x] (ansi_caption[x] if loader_color is set).

           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(8).
     /boot/menu.4th    menu.4th itself.
     /boot/loader.rc   loader(8) bootstrapping script.

EXAMPLES
     A simple boot menu:

           include /boot/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(8), loader(8), loader.4th(8)

HISTORY
     The menu.4th set of commands first appeared in FreeBSD 9.0.

AUTHORS
     The menu.4th set of commands was written by Devin Teske
     <[email protected]>.

FreeBSD 11.1-RELEASE-p4         August 6, 2013         FreeBSD 11.1-RELEASE-p4
Command Section