1 .\" Copyright (c) 2012 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 submenu boot module
34 The file that goes by the name of
36 is a set of commands designed to add submenu functionality to the dynamic menu
39 Submenus are managed through a system of carefully named environment variables.
42 by themselves are not enough for most uses.
43 Please refer to the examples below for the most common situations, and to
45 for additional commands.
47 Before using any of the commands provided in
52 .Dl include menusets.4th
54 This line is present in the default
55 .Pa /boot/menu-commands.4th
56 file, so it is not needed (and should not be re-issued) in a normal setup.
58 The commands provided by it are:
60 .Bl -tag -width menuset-loadinitial -compact -offset indent
61 .It Ic menuset-loadsetnum
62 Takes a single integer on the stack to identify the menuset environment
63 variables to be activated (see environment variables below).
64 .It Ic menuset-loadinitial
65 If $menuset_initial is set, passes the value to menuset-loadsetnum.
66 The value must be a number.
68 Unsets the environment variables associated with all menusets.
69 Increments starting at 1 and stops at the first unconfigured menuset.
70 A menuset is considered configured if the caption for item 1 is set.
73 The environment variables that effect its behavior are:
74 .Bl -tag -width bootfile -offset indent
75 .It Va menuset_initial
76 Number to pass to menuset-loadsetnum when menuset-loadinitial is called.
78 Used to give a name to a menuset.
81 When a menuset is NOT given a name (the default),
82 menuset N is comprised of the following environment variables:
84 .Bl -tag -width menusetN_caption[x][y] -compact -offset indent
85 .It Va ansisetN_caption[x]
87 .It Va ansisetN_caption[x][y]
91 .It Va menusetN_caption[x]
93 .It Va menusetN_caption[x][y]
95 .It Va menusetN_command[x]
100 .It Va menusetN_init[x]
102 .It Va menusetN_keycode[x]
104 .It Va menusetN_options
106 .It Va menusetN_optionstext
108 .It Va menusetN_reboot
110 .It Va toggledsetN_ansi[x]
112 .It Va toggledsetN_text[x]
116 When you choose to give a menuset a name (by setting $menuset_nameN),
117 menuset N is instead comprised of the following environment variables:
119 .Bl -tag -width NAMEmenu_caption[x][y] -compact -offset indent
120 .It Va NAMEansi_caption[x]
122 .It Va NAMEansi_caption[x][y]
123 -> ansi_caption[x][y]
126 .It Va NAMEmenu_caption[x]
128 .It Va NAMEmenu_caption[x][y]
129 -> menu_caption[x][y]
130 .It Va NAMEmenu_command[x]
135 .It Va NAMEmenu_init[x]
137 .It Va NAMEmenu_keycode[x]
139 .It Va NAMEmenu_options
141 .It Va NAMEmenu_optionstext
143 .It Va NAMEmenu_reboot
145 .It Va NAMEtoggled_ansi[x]
147 .It Va NAMEtoggled_text[x]
153 is the value of $menuset_nameN.
154 In the case of $NAMEmenu_init ($menusetN_init when $menuset_nameN is unset),
155 the value is evaluated as an FICL statement.
156 This can be used to dynamically adjust the menuset variables right before the
161 provides the following FICL words:
163 .Bl -tag -width menuset -compact -offset indent
164 .It Ic menuset-checksetnum ( N -- )
165 Given a single integer on the stack, sets a global variable
167 to a boolean based on whether $menuset_nameN is set (true) or not (false).
168 Also sets $affix temporary variable (prefix or infix depending on
170 Automatically called by menuset-loadsetnum and menusets-unset.
171 .It Ic menuset-loadvar ( -- )
172 Used indirectly to shorten syntax and mitigate dictionary size.
173 Requires the following temporary environment variables:
175 .Bl -tag -width affix -compact -offset indent
177 should be set to one of: menu toggled ansi
179 should be set to one of: caption command keycode text ...
181 either a prefix (menuset_use_name is true) or infix (menuset_use_name is false)
186 is true, the variable ${type}_${var} is made to
187 equal the value of the variable ${affix}${type}_${var}
188 (note: in this case menuset-checksetnum has set $affix to $menuset_nameN).
191 is false), the variable ${type}_${var} is made to
192 equal the value of the variable ${type}set${affix}_${var}
193 (note: in this case menuset-checksetnum has set $affix to N).
195 Both the global variable
197 and the environment variable $affix are automatically handled by
198 menuset-checksetnum above (which is automatically called by
200 .It Ic menuset-unloadvar ( -- )
201 Used indirectly to shorten syntax and mitigate dictionary size.
202 Like menuset-loadvar except it unsets the menuset variable.
205 is true ($affix is $menuset_nameN),
206 variable ${affix}${type}_${var} is unset.
207 Otherwise, $affix is N and variable ${type}set${affix}_${var} is unset.
208 .It Ic menuset-loadmenuvar ( -- )
211 and calls menuset-loadvar.
212 .It Ic menuset-unloadmenuvar ( -- )
215 and calls menuset-unloadvar.
216 .It Ic menuset-loadxvar ( -- )
217 Like menuset-loadvar except it takes an additional temporary variable $x.
220 is true (making $affix equal $menuset_nameN),
221 sets variable ${type}_${var}[${x}] to variable ${affix}${type}_${var}[${x}].
222 Otherwise ($affix being N), sets the same variable to instead
223 ${type}set{affix}_${var}[${x}].
224 .It Ic menuset-unloadxvar ( -- )
225 Like menuset-loadxvar except it unsets the menuset variable.
228 is true, unsets ${affix}${type}_${var}[${x}].
229 Otherwise, unsets ${type}set${affix}_${var}[${x}].
230 .It Ic menuset-loadansixvar ( -- )
233 and calls menuset-loadxvar
234 .It Ic menuset-unloadansixvar ( -- )
237 and calls menuset-unloadxvar
238 .It Ic menuset-loadmenuxvar ( -- )
241 and calls menuset-loadxvar
242 .It Ic menuset-unloadmenuxvar ( -- )
245 and calls menuset-unloadxvar
246 .It Ic menuset-loadtoggledxvar ( -- )
249 and calls menuset-loadxvar
250 .It Ic menuset-unloadtoggledxvar ( -- )
253 and calls menuset-unloadxvar
254 .It Ic menuset-loadxyvar ( -- )
255 Like menuset-loadxvar except it takes an additional temporary variable $y.
258 is true ($affix is $menuset_nameN),
259 sets variable ${type}_${var}[${x}][${y}] to ${affix}${type}_${var}[${x}][${y}].
260 Otherwise ($affix is N) sets the same variable to instead
261 ${type}set${affix}_${var}[${x}][${y}].
262 .It Ic menuset-unloadxyvar ( -- )
263 Like menuset-loadxyvar except it unsets the menuset variable.
266 is true, unsets ${affix}${type}_${var}[${x}][${y}].
267 Otherwise, unsets ${type}set${affix}_${var}[${x}][${y}].
268 .It Ic menuset-loadansixyvar ( -- )
271 and calls menuset-loadxyvar.
272 .It Ic menuset-unloadansixyvar ( -- )
275 and calls menuset-unloadxyvar.
276 .It Ic menuset-loadmenuxyvar ( -- )
279 and calls menuset-loadxyvar.
280 .It Ic menuset-unloadmenuxyvar ( -- )
283 and calls menuset-unloadxyvar.
284 .It Ic menuset-setnum-namevar ( N -- C-Addr/U )
285 Takes a single integer on the stack and replaces it with a string (in c-addr/u
286 format) whose value is
288 For example, if given 1 returns
290 .It Ic menuset-cleanup ( N -- )
291 Unsets all the various temporary variables, currently
302 above, use any number between 1 through 9. Sorry, double-digits are not
306 above, use any number between 1 and 65535.
308 .Bl -tag -width /boot/menu-commands.4th -compact
312 .It Pa /boot/menu.4th
314 .It Pa /boot/menu-commands.4th
315 Contains the goto_menu command.
316 .It Pa /boot/menusets.4th
319 .It Pa /boot/loader.rc
321 bootstrapping script.
324 A simple boot menu with a submenu:
326 .Bd -literal -offset indent -compact
327 include /boot/menu.4th
328 include /boot/menu-commands.4th
330 set menuset1_caption[1]="Boot"
331 set menuset1_command[1]="boot"
332 set menuset1_caption[2]="Submenu..."
333 set menuset1_command[2]="2 goto_menu"
334 set menuset2_caption[1]="Back"
335 set menuset2_command[1]="1 goto_menu"
336 set menuset_initial=2
341 The same boot menu with named menusets:
343 .Bd -literal -offset indent -compact
344 include /boot/menu.4th
345 include /boot/menu-commands.4th
347 set menuset_name1=main
348 set mainmenu_caption[1]="Boot"
349 set mainmenu_command[1]="boot"
350 set mainmenu_caption[2]="Submenu..."
351 set mainmenu_command[2]="2 goto_menu"
352 set menuset_name2=sub
353 set submenu_caption[1]="Back"
354 set submenu_command[1]="1 goto_menu"
365 set of commands first appeared in
370 set of commands was written by
372 .An Devin Teske Aq dteske@FreeBSD.org .