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 all possible environment variables used
74 to configure the menu and then calls
78 The environment variables that effect its behavior are:
79 .Bl -tag -width bootfile -offset indent
85 causes the menu to be displayed in color wherever possible. This includes the
86 use of ANSI bold for numbers appearing to the left of menuitems and the use of
89 variables describd below.
93 will wait before executing
94 .Va menu_timeout_command
96 by default) unless a key is pressed.
101 will wait for user input and never execute
102 .Ic menu_timeout_command .
106 will boot immediately, preventing both interruption of the autoboot process and
107 escaping to the loader prompt.
112 for additional information.
113 .It Va menu_timeout_command
114 The command to be executed after
116 seconds if a key is not pressed. The default is
118 .It Va loader_menu_timeout_x
119 Sets the desired column position of the timeout countdown text. Default is 4.
120 .It Va loader_menu_timeout_y
121 Sets the desired row position of the timeout countdown text. Default is 23.
122 .It Va loader_menu_title
123 The text to display centered above the menu. Default is
124 .Dq Li "Welcome to FreeBSD" .
125 .It Va menu_caption[x]
126 The text to be displayed for the numbered menuitem
128 .It Va menu_command[x]
129 The command to be executed when the number associated with menuitem
131 is pressed. See the list of included FICL words below for some ideas.
132 .It Va menu_keycode[x]
133 An optional decimal ASCII keycode to be associated with menuitem
135 When pressed, will cause the execution of
136 .Va menu_command[x] .
137 .It Va ansi_caption[x]
140 is set, use this caption for menuitem
143 .Va menu_caption[x] .
144 .It Va toggled_text[x]
148 .Dq Li toggle_menuitem
149 (or a derivative thereof), the text displayed
150 will toggle between this and
151 .Va menu_caption[x] .
152 .It Va toggled_ansi[x]
158 .It Va menu_caption[x][y]
162 .Dq Li cycle_menuitem
163 (or a derivative thereof), the text displayed will cycle between this and other
164 .Va menu_caption[x][y]
166 .It Va ansi_caption[x][y]
168 .Va menu_caption[x][y]
175 associated with a given menuitem, that menuitem will only appear when
176 running on i386-compatible hardware,
178 is set (indicating the presence of hardware ACPI support as detected by
181 .Va hint.acpi.0.disabled
183 On non-i386 hardware, menuitems configured after the
185 menuitem will use a lower number (to compensate for the missing ACPI menuitem)
186 but continue to function as expected.
187 On i386-compatible hardware lacking ACPI support (as detected by
189 subsequent menuitems will retain their associated numbers.
190 .It Va hint.acpi.0.rsdp
193 on i386-compatible hardware when ACPI support is detected at boot time.
194 Effects the display of the
196 menuitem (if configured).
197 .It Va hint.acpi.0.disabled
198 Effects the display of the
200 menuitem. If set, the menuitem will display
202 .Va ( toggled_ansi[x]
207 .Va ( ansi_caption[x]
214 a single blank-line and an
216 header are inserted between
217 .Va menu_caption[x-1]
222 If set, adds a built-in
224 menuitem to the end of the last configured menuitem. If
228 menuitem will be inserted before the
233 In addition, it provides the following FICL words:
235 .Bl -tag -width disable-module_module -compact -offset indent
236 .It Ic arch-i386? ( -- BOOL )
237 Returns true (-1) on i386 and false (0) otherwise.
238 .It Ic acpipresent? ( -- BOOL )
239 Returns true (-1) if ACPI is present and false (0) otherwise.
240 .It Ic acpienabled? ( -- BOOL )
241 Returns true (-1) if ACPI is enabled and false (0) otherwise.
242 .It Ic toggle_menuitem ( N -- N )
251 represents the ASCII decimal value for
253 .It Ic cycle_menuitem ( N -- N )
257 .Va menu_caption[x][y]
260 represents the ASCII decimal value for
266 above, use any number between 1 through 9. Sorry, double-digits are not
269 .Bl -tag -width /boot/loader.4th -compact
273 .It Pa /boot/menu.4th
276 .It Pa /boot/loader.rc
278 bootstrapping script.
283 .Bd -literal -offset indent -compact
284 include /boot/menu.4th
286 set menu_caption[1]="Boot"
287 set menu_command[1]="boot"
289 set menu_caption[2]="Option: NO"
290 set toggled_text[2]="Option: YES"
291 set menu_command[2]="toggle_menuitem"
292 set menu_timeout_command="boot"
304 set of commands first appeared in
309 set of commands was written by
311 .An Devin Teske Aq devinteske@hotmail.com .