1 .\" Copyright (c) 2011 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 in color wherever possible.
91 use of ANSI bold for numbers appearing to the left of menuitems and the use of
94 variables described below.
98 will wait before executing
99 .Va menu_timeout_command
101 by default) unless a key is pressed.
106 will wait for user input and never execute
107 .Ic menu_timeout_command .
111 will boot immediately, preventing both interruption of the autoboot process and
112 escaping to the loader prompt.
117 for additional information.
118 .It Va menu_timeout_command
119 The command to be executed after
121 seconds if a key is not pressed.
124 .It Va loader_menu_timeout_x
125 Sets the desired column position of the timeout countdown text.
127 .It Va loader_menu_timeout_y
128 Sets the desired row position of the timeout countdown text.
130 .It Va loader_menu_title
131 The text to display centered above the menu.
133 .Dq Li "Welcome to FreeBSD" .
134 .It Va menu_caption[x]
135 The text to be displayed for the numbered menuitem
137 .It Va menu_command[x]
138 The command to be executed when the number associated with menuitem
141 See the list of included FICL words below for some ideas.
142 .It Va menu_keycode[x]
143 An optional decimal ASCII keycode to be associated with menuitem
145 When pressed, will cause the execution of
146 .Va menu_command[x] .
147 .It Va ansi_caption[x]
150 is set, use this caption for menuitem
153 .Va menu_caption[x] .
154 .It Va toggled_text[x]
158 .Dq Li toggle_menuitem
159 (or a derivative thereof), the text displayed
160 will toggle between this and
161 .Va menu_caption[x] .
162 .It Va toggled_ansi[x]
168 .It Va menu_caption[x][y]
172 .Dq Li cycle_menuitem
173 (or a derivative thereof), the text displayed will cycle between this and other
174 .Va menu_caption[x][y]
176 .It Va ansi_caption[x][y]
178 .Va menu_caption[x][y]
185 associated with a given menuitem, that menuitem will only appear when
186 running on i386-compatible hardware,
188 is set (indicating the presence of hardware ACPI support as detected by
191 .Va hint.acpi.0.disabled
193 On non-i386 hardware, menuitems configured after the
195 menuitem will use a lower number (to compensate for the missing ACPI menuitem)
196 but continue to function as expected.
197 On i386-compatible hardware lacking ACPI support (as detected by
199 subsequent menuitems will retain their associated numbers.
200 .It Va hint.acpi.0.rsdp
203 on i386-compatible hardware when ACPI support is detected at boot time.
204 Effects the display of the
206 menuitem (if configured).
207 .It Va hint.acpi.0.disabled
208 Effects the display of the
211 If set, the menuitem will display
213 .Va ( toggled_ansi[x]
218 .Va ( ansi_caption[x]
225 a single blank-line and an
227 header are inserted between
228 .Va menu_caption[x-1]
233 If set, adds a built-in
235 menuitem to the end of the last configured menuitem.
240 menuitem will be inserted before the
245 In addition, it provides the following FICL words:
247 .Bl -tag -width disable-module_module -compact -offset indent
248 .It Ic arch-i386? ( -- BOOL )
249 Returns true (-1) on i386 and false (0) otherwise.
250 .It Ic acpipresent? ( -- BOOL )
251 Returns true (-1) if ACPI is present and false (0) otherwise.
252 .It Ic acpienabled? ( -- BOOL )
253 Returns true (-1) if ACPI is enabled and false (0) otherwise.
254 .It Ic toggle_menuitem ( N -- N )
263 represents the ASCII decimal value for
265 .It Ic cycle_menuitem ( N -- N )
269 .Va menu_caption[x][y]
272 represents the ASCII decimal value for
278 above, use any number between 1 through 9. Sorry, double-digits are not
281 .Bl -tag -width /boot/loader.4th -compact
285 .It Pa /boot/menu.4th
288 .It Pa /boot/loader.rc
290 bootstrapping script.
295 .Bd -literal -offset indent -compact
296 include /boot/menu.4th
298 set menu_caption[1]="Boot"
299 set menu_command[1]="boot"
301 set menu_caption[2]="Option: NO"
302 set toggled_text[2]="Option: YES"
303 set menu_command[2]="toggle_menuitem"
304 set menu_timeout_command="boot"
316 set of commands first appeared in
321 set of commands was written by
323 .An Devin Teske Aq devinteske@hotmail.com .