1.\" Copyright (c) 2011-2013 Devin Teske 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd July 20, 2018 26.Dt MENU.4TH 7 27.Os 28.Sh NAME 29.Nm menu.4th 30.Nd loader dynamic menu boot module 31.Sh DESCRIPTION 32The file that goes by the name of 33.Nm 34is a set of commands designed to display a dynamic menu system managed through 35a system of carefully named environment variables. 36The commands of 37.Nm 38by themselves are not enough for most uses. 39Please refer to the 40examples below for the most common situations, and to 41.Xr loader 7 42for additional commands. 43.Pp 44Before using any of the commands provided in 45.Nm , 46it must be included 47through the command: 48.Pp 49.Dl include menu.4th 50.Pp 51This line is present in the default 52.Pa /boot/forth/menu.rc 53file, so it is not needed (and should not be re-issued) in a normal setup. 54.Pp 55The commands provided by it are: 56.Pp 57.Bl -tag -width disable-module_module -compact -offset indent 58.It Ic menu-init 59Draws the menu bounding box and initializes some internal state variables. 60This should be called before any other menu-related functions. 61.It Ic menu-display 62Displays the menu (configured via the below documented environment variables) 63and blocks on keyboard input, awaiting user action. 64.It Ic menu-erase 65Clears the screen area within the menu bounding box. 66.It Ic menu-redraw 67Calls 68.Ic menu-erase 69and then redraws the menu. 70.It Ic menu-unset 71Unsets the environment variables associated with individual menu items, 72clearing the way for a new menu. 73.It Ic menu-clear 74Calls 75.Ic menu-unset 76and then 77.Ic menu-erase . 78.El 79.Pp 80The environment variables that effect its behavior are: 81.Bl -tag -width bootfile -offset indent 82.It Va loader_color 83If set to 84.Dq Li NO 85(case-insensitive) or 86.Dq Li 0 , 87causes the menu to be displayed without color. 88The default is to use ANSI coloring whenever possible. 89If serial boot is enabled, color is disabled by default. 90Color features include the use of ANSI bold for numbers appearing to the left 91of menuitems and the use of special 92.Dq Li ansi 93variables described below. 94.It Va autoboot_delay 95Number of seconds 96.Ic menu-display 97will wait before executing 98.Va menu_timeout_command 99.Ic ( boot 100by default) unless a key is pressed. 101If set to 102.Dq Li NO 103(case-insensitive) 104.Ic menu-display 105will wait for user input and never execute 106.Ic menu_timeout_command . 107If set to 108.Dq Li -1 , 109.Ic menu-display 110will boot immediately, preventing both interruption of the 111.Ic autoboot 112process and escaping to the loader prompt. 113Default is 114.Dq Li 10 . 115See 116.Xr loader 7 117for additional information. 118.It Va menu_timeout_command 119The command to be executed after 120.Va autoboot_delay 121seconds if a key is not pressed. 122The default is 123.Ic boot . 124.It Va loader_menu_frame 125Sets the desired box style to draw around the boot menu. 126Possible values are: 127.Dq Li single 128.Pq the default , 129.Dq Li double , 130and 131.Dq Li none . 132.It Va loader_menu_timeout_x 133Sets the desired column position of the timeout countdown text. 134Default is 4. 135.It Va loader_menu_timeout_y 136Sets the desired row position of the timeout countdown text. 137Default is 23. 138.It Va loader_menu_title 139The text to display above the menu. 140Default is 141.Dq Li "Welcome to FreeBSD" . 142.It Va loader_menu_title_align 143Default is to align 144.Ic loader_menu_title 145centered above the menu. 146This can be set to 147.Dq Li left 148or 149.Dq Li right 150to instead display the title left-or-right justified 151.Pq respectively . 152.It Va loader_menu_x 153Sets the desired column position of the boot menu. 154Default is 5. 155.It Va loader_menu_y 156Sets the desired row position of the boot menu. 157Default is 10. 158.It Va menu_caption[x] 159The text to be displayed for the numbered menuitem 160.Dq Li x . 161.It Va menu_command[x] 162The command to be executed when the number associated with menuitem 163.Dq Li x 164is pressed. 165See the list of included FICL words below for some ideas. 166.It Va menu_keycode[x] 167An optional decimal ASCII keycode to be associated with menuitem 168.Dq Li x . 169When pressed, will cause the execution of 170.Va menu_command[x] . 171.It Va ansi_caption[x] 172If 173.Va loader_color 174is set 175.Pq enabled by default , 176use this caption for menuitem 177.Dq Li x 178instead of 179.Va menu_caption[x] . 180.It Va toggled_text[x] 181For menuitems where 182.Va menu_command[x] 183is set to 184.Dq Li toggle_menuitem 185(or a derivative thereof), the text displayed 186will toggle between this and 187.Va menu_caption[x] . 188.It Va toggled_ansi[x] 189Like 190.Va toggled_text[x] 191except used when 192.Va loader_color 193is enabled 194.Pq default . 195.It Va menu_caption[x][y] 196For menuitems where 197.Va menu_command[x] 198is set to 199.Dq Li cycle_menuitem 200(or a derivative thereof), the text displayed will cycle between this and other 201.Va menu_caption[x][y] 202entries. 203.It Va ansi_caption[x][y] 204Like 205.Va menu_caption[x][y] 206except used when 207.Va loader_color 208is enabled 209.Pq default . 210.It Va menu_acpi 211When set to a number 212.Dq Li x 213associated with a given menuitem, that menuitem will allow to select 214acpi-user-options 215.Pq see Xr eeprom 8 . 216.It Va menu_options 217When set to a number 218.Dq Li x , 219a single blank-line and an 220.Dq Li Options 221header are inserted between 222.Va menu_caption[x-1] 223and 224.Va menu_caption[x] 225(if configured). 226.It Va menu_reboot 227If set, adds a built-in 228.Dq Li Reboot 229menuitem to the end of the last configured menuitem. 230If 231.Va menu_options 232is configured, the 233.Dq Li Reboot 234menuitem will be inserted before the 235.Dq Options 236separator. 237.El 238.Pp 239In addition, it provides the following FICL words: 240.Pp 241.Bl -tag -width disable-module_module -compact -offset indent 242.It Ic arch-i386? ( -- BOOL ) 243Returns true (-1) on i386 and false (0) otherwise. 244.It Ic acpipresent? ( -- BOOL ) 245Returns true (-1) if ACPI is present and false (0) otherwise. 246.It Ic acpienabled? ( -- BOOL ) 247Returns true (-1) if ACPI is enabled and false (0) otherwise. 248.It Ic toggle_menuitem ( N -- N ) 249Toggles menuitem 250.Dq Li N 251between 252.Va menu_caption[x] 253and 254.Va toggled_text[x] 255(where 256.Dq Li N 257represents the ASCII decimal value for 258.Dq Li x ) . 259.It Ic cycle_menuitem ( N -- N ) 260Cycles menuitem 261.Dq Li N 262between 263.Va menu_caption[x][y] 264entries (where 265.Va N 266represents the ASCII decimal value for 267.Va x ) . 268.El 269.Pp 270For all values of 271.Dq Li x 272above, use any number between 1 through 9. 273Sorry, double-digits are not currently supported. 274.Sh FILES 275.Bl -tag -width /boot/forth/loader.4th -compact 276.It Pa /boot/loader 277The 278.Xr loader 7 . 279.It Pa /boot/forth/menu.4th 280.Nm 281itself. 282.It Pa /boot/loader.rc 283.Xr loader 7 284bootstrapping script. 285.El 286.Sh EXAMPLES 287A simple boot menu: 288.Pp 289.Bd -literal -offset indent -compact 290include /boot/forth/menu.4th 291menu-init 292set menu_caption[1]="Boot" 293set menu_command[1]="boot" 294set menu_options=2 295set menu_caption[2]="Option: NO" 296set toggled_text[2]="Option: YES" 297set menu_command[2]="toggle_menuitem" 298set menu_timeout_command="boot" 299set menu_reboot 300menu-display 301.Ed 302.Sh SEE ALSO 303.Xr loader.conf 5 , 304.Xr beastie.4th 7 , 305.Xr loader 7 , 306.Xr loader.4th 7 , 307.Xr eeprom 8 308