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 Apr 22, 2017 26.Dt MENU.4TH 5 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 5 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 8 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. This can be set to 146.Dq Li left 147or 148.Dq Li right 149to instead display the title left-or-right justified 150.Pq respectively . 151.It Va loader_menu_x 152Sets the desired column position of the boot menu. 153Default is 5. 154.It Va loader_menu_y 155Sets the desired row position of the boot menu. 156Default is 10. 157.It Va menu_caption[x] 158The text to be displayed for the numbered menuitem 159.Dq Li x . 160.It Va menu_command[x] 161The command to be executed when the number associated with menuitem 162.Dq Li x 163is pressed. 164See the list of included FICL words below for some ideas. 165.It Va menu_keycode[x] 166An optional decimal ASCII keycode to be associated with menuitem 167.Dq Li x . 168When pressed, will cause the execution of 169.Va menu_command[x] . 170.It Va ansi_caption[x] 171If 172.Va loader_color 173is set 174.Pq enabled by default , 175use this caption for menuitem 176.Dq Li x 177instead of 178.Va menu_caption[x] . 179.It Va toggled_text[x] 180For menuitems where 181.Va menu_command[x] 182is set to 183.Dq Li toggle_menuitem 184(or a derivative thereof), the text displayed 185will toggle between this and 186.Va menu_caption[x] . 187.It Va toggled_ansi[x] 188Like 189.Va toggled_text[x] 190except used when 191.Va loader_color 192is enabled 193.Pq default . 194.It Va menu_caption[x][y] 195For menuitems where 196.Va menu_command[x] 197is set to 198.Dq Li cycle_menuitem 199(or a derivative thereof), the text displayed will cycle between this and other 200.Va menu_caption[x][y] 201entries. 202.It Va ansi_caption[x][y] 203Like 204.Va menu_caption[x][y] 205except used when 206.Va loader_color 207is enabled 208.Pq default . 209.It Va menu_acpi 210When set to a number 211.Dq Li x 212associated with a given menuitem, that menuitem will allow to select 213acpi-user-options 214.Pq see Xr eeprom 1M . 215.It Va menu_options 216When set to a number 217.Dq Li x , 218a single blank-line and an 219.Dq Li Options 220header are inserted between 221.Va menu_caption[x-1] 222and 223.Va menu_caption[x] 224(if configured). 225.It Va menu_reboot 226If set, adds a built-in 227.Dq Li Reboot 228menuitem to the end of the last configured menuitem. 229If 230.Va menu_options 231is configured, the 232.Dq Li Reboot 233menuitem will be inserted before the 234.Dq Options 235separator. 236.El 237.Pp 238In addition, it provides the following FICL words: 239.Pp 240.Bl -tag -width disable-module_module -compact -offset indent 241.It Ic arch-i386? ( -- BOOL ) 242Returns true (-1) on i386 and false (0) otherwise. 243.It Ic acpipresent? ( -- BOOL ) 244Returns true (-1) if ACPI is present and false (0) otherwise. 245.It Ic acpienabled? ( -- BOOL ) 246Returns true (-1) if ACPI is enabled and false (0) otherwise. 247.It Ic toggle_menuitem ( N -- N ) 248Toggles menuitem 249.Dq Li N 250between 251.Va menu_caption[x] 252and 253.Va toggled_text[x] 254(where 255.Dq Li N 256represents the ASCII decimal value for 257.Dq Li x ) . 258.It Ic cycle_menuitem ( N -- N ) 259Cycles menuitem 260.Dq Li N 261between 262.Va menu_caption[x][y] 263entries (where 264.Va N 265represents the ASCII decimal value for 266.Va x ) . 267.El 268.Pp 269For all values of 270.Dq Li x 271above, use any number between 1 through 9. Sorry, double-digits are not 272currently supported. 273.Sh FILES 274.Bl -tag -width /boot/forth/loader.4th -compact 275.It Pa /boot/zfsloader 276The 277.Xr zfsloader 5 . 278.It Pa /boot/forth/menu.4th 279.Nm 280itself. 281.It Pa /boot/loader.rc 282.Xr loader 5 283bootstrapping script. 284.El 285.Sh EXAMPLES 286A simple boot menu: 287.Pp 288.Bd -literal -offset indent -compact 289include /boot/forth/menu.4th 290menu-init 291set menu_caption[1]="Boot" 292set menu_command[1]="boot" 293set menu_options=2 294set menu_caption[2]="Option: NO" 295set toggled_text[2]="Option: YES" 296set menu_command[2]="toggle_menuitem" 297set menu_timeout_command="boot" 298set menu_reboot 299menu-display 300.Ed 301.Sh SEE ALSO 302.Xr eeprom 1M , 303.Xr loader.conf 4 , 304.Xr beastie.4th 5 , 305.Xr loader 5 , 306.Xr loader.4th 5 307