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 August 6, 2013 26.Dt MENU.4TH 8 27.Os 28.Sh NAME 29.Nm menu.4th 30.Nd FreeBSD 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 8 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/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 only appear when 213running on i386-compatible hardware, 214.Va hint.acpi.0.rsdp 215is set (indicating the presence of hardware ACPI support as detected by 216.Xr loader 8 ) , 217and 218.Va hint.acpi.0.disabled 219is not set. 220On non-i386 hardware, menuitems configured after the 221.Dq Li menu_acpi 222menuitem will use a lower number (to compensate for the missing ACPI menuitem) 223but continue to function as expected. 224On i386-compatible hardware lacking ACPI support (as detected by 225.Xr loader 8 ) , 226subsequent menuitems will retain their associated numbers. 227.It Va hint.acpi.0.rsdp 228Set automatically by 229.Xr loader 8 230on i386-compatible hardware when ACPI support is detected at boot time. 231Effects the display of the 232.Dq Li menu_acpi 233menuitem (if configured). 234.It Va hint.acpi.0.disabled 235Effects the display of the 236.Va menu_acpi 237menuitem. 238If set, the menuitem will display 239.Va toggled_text[x] 240.Va ( toggled_ansi[x] 241if 242.Va loader_color 243is set), otherwise 244.Va menu_caption[x] 245.Va ( ansi_caption[x] 246if 247.Va loader_color 248is set). 249.It Va menu_options 250When set to a number 251.Dq Li x , 252a single blank-line and an 253.Dq Li Options 254header are inserted between 255.Va menu_caption[x-1] 256and 257.Va menu_caption[x] 258(if configured). 259.It Va menu_reboot 260If set, adds a built-in 261.Dq Li Reboot 262menuitem to the end of the last configured menuitem. 263If 264.Va menu_options 265is configured, the 266.Dq Li Reboot 267menuitem will be inserted before the 268.Dq Options 269separator. 270.El 271.Pp 272In addition, it provides the following FICL words: 273.Pp 274.Bl -tag -width disable-module_module -compact -offset indent 275.It Ic arch-i386? ( -- BOOL ) 276Returns true (-1) on i386 and false (0) otherwise. 277.It Ic acpipresent? ( -- BOOL ) 278Returns true (-1) if ACPI is present and false (0) otherwise. 279.It Ic acpienabled? ( -- BOOL ) 280Returns true (-1) if ACPI is enabled and false (0) otherwise. 281.It Ic toggle_menuitem ( N -- N ) 282Toggles menuitem 283.Dq Li N 284between 285.Va menu_caption[x] 286and 287.Va toggled_text[x] 288(where 289.Dq Li N 290represents the ASCII decimal value for 291.Dq Li x ) . 292.It Ic cycle_menuitem ( N -- N ) 293Cycles menuitem 294.Dq Li N 295between 296.Va menu_caption[x][y] 297entries (where 298.Va N 299represents the ASCII decimal value for 300.Va x ) . 301.El 302.Pp 303For all values of 304.Dq Li x 305above, use any number between 1 through 9. Sorry, double-digits are not 306currently supported. 307.Sh FILES 308.Bl -tag -width /boot/loader.4th -compact 309.It Pa /boot/loader 310The 311.Xr loader 8 . 312.It Pa /boot/menu.4th 313.Nm 314itself. 315.It Pa /boot/loader.rc 316.Xr loader 8 317bootstrapping script. 318.El 319.Sh EXAMPLES 320A simple boot menu: 321.Pp 322.Bd -literal -offset indent -compact 323include /boot/menu.4th 324menu-init 325set menu_caption[1]="Boot" 326set menu_command[1]="boot" 327set menu_options=2 328set menu_caption[2]="Option: NO" 329set toggled_text[2]="Option: YES" 330set menu_command[2]="toggle_menuitem" 331set menu_timeout_command="boot" 332set menu_reboot 333menu-display 334.Ed 335.Sh SEE ALSO 336.Xr loader.conf 5 , 337.Xr beastie.4th 8 , 338.Xr loader 8 , 339.Xr loader.4th 8 340.Sh HISTORY 341The 342.Nm 343set of commands first appeared in 344.Fx 9.0 . 345.Sh AUTHORS 346The 347.Nm 348set of commands was written by 349.An -nosplit 350.An Devin Teske Aq dteske@FreeBSD.org . 351