1 .\" Copyright (c) 2011-2013 Devin Teske
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd FreeBSD dynamic menu boot module
34 The file that goes by the name of
36 is a set of commands designed to display a dynamic menu system managed through
37 a system of carefully named environment variables.
40 by themselves are not enough for most uses.
42 examples below for the most common situations, and to
44 for additional commands.
46 Before using any of the commands provided in
53 This line is present in the default
55 file, so it is not needed (and should not be re-issued) in a normal setup.
57 The commands provided by it are:
59 .Bl -tag -width disable-module_module -compact -offset indent
61 Draws the menu bounding box and initializes some internal state variables.
62 This should be called before any other menu-related functions.
64 Displays the menu (configured via the below documented environment variables)
65 and blocks on keyboard input, awaiting user action.
67 Clears the screen area within the menu bounding box.
71 and then redraws the menu.
73 Unsets the environment variables associated with individual menu items,
74 clearing the way for a new menu.
82 The environment variables that effect its behavior are:
83 .Bl -tag -width bootfile -offset indent
89 causes the menu to be displayed without color.
90 The default is to use ANSI coloring whenever possible.
91 If serial boot is enabled, color is disabled by default.
92 Color features include the use of ANSI bold for numbers appearing to the left
93 of menuitems and the use of special
95 variables described below.
99 will wait before executing
100 .Va menu_timeout_command
102 by default) unless a key is pressed.
107 will wait for user input and never execute
108 .Ic menu_timeout_command .
112 will boot immediately, preventing both interruption of the
114 process and escaping to the loader prompt.
119 for additional information.
120 .It Va menu_timeout_command
121 The command to be executed after
123 seconds if a key is not pressed.
126 .It Va loader_menu_frame
127 Sets the desired box style to draw around the boot menu.
134 .It Va loader_menu_timeout_x
135 Sets the desired column position of the timeout countdown text.
137 .It Va loader_menu_timeout_y
138 Sets the desired row position of the timeout countdown text.
140 .It Va loader_menu_title
141 The text to display above the menu.
143 .Dq Li "Welcome to FreeBSD" .
144 .It Va loader_menu_title_align
146 .Ic loader_menu_title
147 centered above the menu. This can be set to
151 to instead display the title left-or-right justified
154 Sets the desired column position of the boot menu.
157 Sets the desired row position of the boot menu.
159 .It Va menu_caption[x]
160 The text to be displayed for the numbered menuitem
162 .It Va menu_command[x]
163 The command to be executed when the number associated with menuitem
166 See the list of included FICL words below for some ideas.
167 .It Va menu_keycode[x]
168 An optional decimal ASCII keycode to be associated with menuitem
170 When pressed, will cause the execution of
171 .Va menu_command[x] .
172 .It Va ansi_caption[x]
176 .Pq enabled by default ,
177 use this caption for menuitem
180 .Va menu_caption[x] .
181 .It Va toggled_text[x]
185 .Dq Li toggle_menuitem
186 (or a derivative thereof), the text displayed
187 will toggle between this and
188 .Va menu_caption[x] .
189 .It Va toggled_ansi[x]
196 .It Va menu_caption[x][y]
200 .Dq Li cycle_menuitem
201 (or a derivative thereof), the text displayed will cycle between this and other
202 .Va menu_caption[x][y]
204 .It Va ansi_caption[x][y]
206 .Va menu_caption[x][y]
214 associated with a given menuitem, that menuitem will only appear when
215 running on i386-compatible hardware,
217 is set (indicating the presence of hardware ACPI support as detected by
220 .Va hint.acpi.0.disabled
222 On non-i386 hardware, menuitems configured after the
224 menuitem will use a lower number (to compensate for the missing ACPI menuitem)
225 but continue to function as expected.
226 On i386-compatible hardware lacking ACPI support (as detected by
228 subsequent menuitems will retain their associated numbers.
229 .It Va hint.acpi.0.rsdp
232 on i386-compatible hardware when ACPI support is detected at boot time.
233 Effects the display of the
235 menuitem (if configured).
236 .It Va hint.acpi.0.disabled
237 Effects the display of the
240 If set, the menuitem will display
242 .Va ( toggled_ansi[x]
247 .Va ( ansi_caption[x]
254 a single blank-line and an
256 header are inserted between
257 .Va menu_caption[x-1]
262 If set, adds a built-in
264 menuitem to the end of the last configured menuitem.
269 menuitem will be inserted before the
274 In addition, it provides the following FICL words:
276 .Bl -tag -width disable-module_module -compact -offset indent
277 .It Ic arch-i386? ( -- BOOL )
278 Returns true (-1) on i386 and false (0) otherwise.
279 .It Ic acpipresent? ( -- BOOL )
280 Returns true (-1) if ACPI is present and false (0) otherwise.
281 .It Ic acpienabled? ( -- BOOL )
282 Returns true (-1) if ACPI is enabled and false (0) otherwise.
283 .It Ic toggle_menuitem ( N -- N )
292 represents the ASCII decimal value for
294 .It Ic cycle_menuitem ( N -- N )
298 .Va menu_caption[x][y]
301 represents the ASCII decimal value for
307 above, use any number between 1 through 9. Sorry, double-digits are not
310 .Bl -tag -width /boot/loader.4th -compact
314 .It Pa /boot/menu.4th
317 .It Pa /boot/loader.rc
319 bootstrapping script.
324 .Bd -literal -offset indent -compact
325 include /boot/menu.4th
327 set menu_caption[1]="Boot"
328 set menu_command[1]="boot"
330 set menu_caption[2]="Option: NO"
331 set toggled_text[2]="Option: YES"
332 set menu_command[2]="toggle_menuitem"
333 set menu_timeout_command="boot"
345 set of commands first appeared in
350 set of commands was written by
352 .An Devin Teske Aq dteske@FreeBSD.org .