xref: /titanic_51/usr/src/man/man5/menu.4th.5 (revision ba11c5b535a8958668f939901bdcacb3ee8b7570)
1*ba11c5b5SToomas Soome.\" Copyright (c) 2011-2013 Devin Teske
2*ba11c5b5SToomas Soome.\" All rights reserved.
3*ba11c5b5SToomas Soome.\"
4*ba11c5b5SToomas Soome.\" Redistribution and use in source and binary forms, with or without
5*ba11c5b5SToomas Soome.\" modification, are permitted provided that the following conditions
6*ba11c5b5SToomas Soome.\" are met:
7*ba11c5b5SToomas Soome.\" 1. Redistributions of source code must retain the above copyright
8*ba11c5b5SToomas Soome.\"    notice, this list of conditions and the following disclaimer.
9*ba11c5b5SToomas Soome.\" 2. Redistributions in binary form must reproduce the above copyright
10*ba11c5b5SToomas Soome.\"    notice, this list of conditions and the following disclaimer in the
11*ba11c5b5SToomas Soome.\"    documentation and/or other materials provided with the distribution.
12*ba11c5b5SToomas Soome.\"
13*ba11c5b5SToomas Soome.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14*ba11c5b5SToomas Soome.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15*ba11c5b5SToomas Soome.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16*ba11c5b5SToomas Soome.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17*ba11c5b5SToomas Soome.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18*ba11c5b5SToomas Soome.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19*ba11c5b5SToomas Soome.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20*ba11c5b5SToomas Soome.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21*ba11c5b5SToomas Soome.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22*ba11c5b5SToomas Soome.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23*ba11c5b5SToomas Soome.\" SUCH DAMAGE.
24*ba11c5b5SToomas Soome.\"
25*ba11c5b5SToomas Soome.Dd Apr 22, 2017
26*ba11c5b5SToomas Soome.Dt MENU.4TH 5
27*ba11c5b5SToomas Soome.Os
28*ba11c5b5SToomas Soome.Sh NAME
29*ba11c5b5SToomas Soome.Nm menu.4th
30*ba11c5b5SToomas Soome.Nd loader dynamic menu boot module
31*ba11c5b5SToomas Soome.Sh DESCRIPTION
32*ba11c5b5SToomas SoomeThe file that goes by the name of
33*ba11c5b5SToomas Soome.Nm
34*ba11c5b5SToomas Soomeis a set of commands designed to display a dynamic menu system managed through
35*ba11c5b5SToomas Soomea system of carefully named environment variables.
36*ba11c5b5SToomas SoomeThe commands of
37*ba11c5b5SToomas Soome.Nm
38*ba11c5b5SToomas Soomeby themselves are not enough for most uses.
39*ba11c5b5SToomas SoomePlease refer to the
40*ba11c5b5SToomas Soomeexamples below for the most common situations, and to
41*ba11c5b5SToomas Soome.Xr loader 5
42*ba11c5b5SToomas Soomefor additional commands.
43*ba11c5b5SToomas Soome.Pp
44*ba11c5b5SToomas SoomeBefore using any of the commands provided in
45*ba11c5b5SToomas Soome.Nm ,
46*ba11c5b5SToomas Soomeit must be included
47*ba11c5b5SToomas Soomethrough the command:
48*ba11c5b5SToomas Soome.Pp
49*ba11c5b5SToomas Soome.Dl include menu.4th
50*ba11c5b5SToomas Soome.Pp
51*ba11c5b5SToomas SoomeThis line is present in the default
52*ba11c5b5SToomas Soome.Pa /boot/forth/menu.rc
53*ba11c5b5SToomas Soomefile, so it is not needed (and should not be re-issued) in a normal setup.
54*ba11c5b5SToomas Soome.Pp
55*ba11c5b5SToomas SoomeThe commands provided by it are:
56*ba11c5b5SToomas Soome.Pp
57*ba11c5b5SToomas Soome.Bl -tag -width disable-module_module -compact -offset indent
58*ba11c5b5SToomas Soome.It Ic menu-init
59*ba11c5b5SToomas SoomeDraws the menu bounding box and initializes some internal state variables.
60*ba11c5b5SToomas SoomeThis should be called before any other menu-related functions.
61*ba11c5b5SToomas Soome.It Ic menu-display
62*ba11c5b5SToomas SoomeDisplays the menu (configured via the below documented environment variables)
63*ba11c5b5SToomas Soomeand blocks on keyboard input, awaiting user action.
64*ba11c5b5SToomas Soome.It Ic menu-erase
65*ba11c5b5SToomas SoomeClears the screen area within the menu bounding box.
66*ba11c5b5SToomas Soome.It Ic menu-redraw
67*ba11c5b5SToomas SoomeCalls
68*ba11c5b5SToomas Soome.Ic menu-erase
69*ba11c5b5SToomas Soomeand then redraws the menu.
70*ba11c5b5SToomas Soome.It Ic menu-unset
71*ba11c5b5SToomas SoomeUnsets the environment variables associated with individual menu items,
72*ba11c5b5SToomas Soomeclearing the way for a new menu.
73*ba11c5b5SToomas Soome.It Ic menu-clear
74*ba11c5b5SToomas SoomeCalls
75*ba11c5b5SToomas Soome.Ic menu-unset
76*ba11c5b5SToomas Soomeand then
77*ba11c5b5SToomas Soome.Ic menu-erase .
78*ba11c5b5SToomas Soome.El
79*ba11c5b5SToomas Soome.Pp
80*ba11c5b5SToomas SoomeThe environment variables that effect its behavior are:
81*ba11c5b5SToomas Soome.Bl -tag -width bootfile -offset indent
82*ba11c5b5SToomas Soome.It Va loader_color
83*ba11c5b5SToomas SoomeIf set to
84*ba11c5b5SToomas Soome.Dq Li NO
85*ba11c5b5SToomas Soome(case-insensitive) or
86*ba11c5b5SToomas Soome.Dq Li 0 ,
87*ba11c5b5SToomas Soomecauses the menu to be displayed without color.
88*ba11c5b5SToomas SoomeThe default is to use ANSI coloring whenever possible.
89*ba11c5b5SToomas SoomeIf serial boot is enabled, color is disabled by default.
90*ba11c5b5SToomas SoomeColor features include the use of ANSI bold for numbers appearing to the left
91*ba11c5b5SToomas Soomeof menuitems and the use of special
92*ba11c5b5SToomas Soome.Dq Li ansi
93*ba11c5b5SToomas Soomevariables described below.
94*ba11c5b5SToomas Soome.It Va autoboot_delay
95*ba11c5b5SToomas SoomeNumber of seconds
96*ba11c5b5SToomas Soome.Ic menu-display
97*ba11c5b5SToomas Soomewill wait before executing
98*ba11c5b5SToomas Soome.Va menu_timeout_command
99*ba11c5b5SToomas Soome.Ic ( boot
100*ba11c5b5SToomas Soomeby default) unless a key is pressed.
101*ba11c5b5SToomas SoomeIf set to
102*ba11c5b5SToomas Soome.Dq Li NO
103*ba11c5b5SToomas Soome(case-insensitive)
104*ba11c5b5SToomas Soome.Ic menu-display
105*ba11c5b5SToomas Soomewill wait for user input and never execute
106*ba11c5b5SToomas Soome.Ic menu_timeout_command .
107*ba11c5b5SToomas SoomeIf set to
108*ba11c5b5SToomas Soome.Dq Li -1 ,
109*ba11c5b5SToomas Soome.Ic menu-display
110*ba11c5b5SToomas Soomewill boot immediately, preventing both interruption of the
111*ba11c5b5SToomas Soome.Ic autoboot
112*ba11c5b5SToomas Soomeprocess and escaping to the loader prompt.
113*ba11c5b5SToomas SoomeDefault is
114*ba11c5b5SToomas Soome.Dq Li 10 .
115*ba11c5b5SToomas SoomeSee
116*ba11c5b5SToomas Soome.Xr loader 8
117*ba11c5b5SToomas Soomefor additional information.
118*ba11c5b5SToomas Soome.It Va menu_timeout_command
119*ba11c5b5SToomas SoomeThe command to be executed after
120*ba11c5b5SToomas Soome.Va autoboot_delay
121*ba11c5b5SToomas Soomeseconds if a key is not pressed.
122*ba11c5b5SToomas SoomeThe default is
123*ba11c5b5SToomas Soome.Ic boot .
124*ba11c5b5SToomas Soome.It Va loader_menu_frame
125*ba11c5b5SToomas SoomeSets the desired box style to draw around the boot menu.
126*ba11c5b5SToomas SoomePossible values are:
127*ba11c5b5SToomas Soome.Dq Li single
128*ba11c5b5SToomas Soome.Pq the default ,
129*ba11c5b5SToomas Soome.Dq Li double ,
130*ba11c5b5SToomas Soomeand
131*ba11c5b5SToomas Soome.Dq Li none .
132*ba11c5b5SToomas Soome.It Va loader_menu_timeout_x
133*ba11c5b5SToomas SoomeSets the desired column position of the timeout countdown text.
134*ba11c5b5SToomas SoomeDefault is 4.
135*ba11c5b5SToomas Soome.It Va loader_menu_timeout_y
136*ba11c5b5SToomas SoomeSets the desired row position of the timeout countdown text.
137*ba11c5b5SToomas SoomeDefault is 23.
138*ba11c5b5SToomas Soome.It Va loader_menu_title
139*ba11c5b5SToomas SoomeThe text to display above the menu.
140*ba11c5b5SToomas SoomeDefault is
141*ba11c5b5SToomas Soome.Dq Li "Welcome to FreeBSD" .
142*ba11c5b5SToomas Soome.It Va loader_menu_title_align
143*ba11c5b5SToomas SoomeDefault is to align
144*ba11c5b5SToomas Soome.Ic loader_menu_title
145*ba11c5b5SToomas Soomecentered above the menu. This can be set to
146*ba11c5b5SToomas Soome.Dq Li left
147*ba11c5b5SToomas Soomeor
148*ba11c5b5SToomas Soome.Dq Li right
149*ba11c5b5SToomas Soometo instead display the title left-or-right justified
150*ba11c5b5SToomas Soome.Pq respectively .
151*ba11c5b5SToomas Soome.It Va loader_menu_x
152*ba11c5b5SToomas SoomeSets the desired column position of the boot menu.
153*ba11c5b5SToomas SoomeDefault is 5.
154*ba11c5b5SToomas Soome.It Va loader_menu_y
155*ba11c5b5SToomas SoomeSets the desired row position of the boot menu.
156*ba11c5b5SToomas SoomeDefault is 10.
157*ba11c5b5SToomas Soome.It Va menu_caption[x]
158*ba11c5b5SToomas SoomeThe text to be displayed for the numbered menuitem
159*ba11c5b5SToomas Soome.Dq Li x .
160*ba11c5b5SToomas Soome.It Va menu_command[x]
161*ba11c5b5SToomas SoomeThe command to be executed when the number associated with menuitem
162*ba11c5b5SToomas Soome.Dq Li x
163*ba11c5b5SToomas Soomeis pressed.
164*ba11c5b5SToomas SoomeSee the list of included FICL words below for some ideas.
165*ba11c5b5SToomas Soome.It Va menu_keycode[x]
166*ba11c5b5SToomas SoomeAn optional decimal ASCII keycode to be associated with menuitem
167*ba11c5b5SToomas Soome.Dq Li x .
168*ba11c5b5SToomas SoomeWhen pressed, will cause the execution of
169*ba11c5b5SToomas Soome.Va menu_command[x] .
170*ba11c5b5SToomas Soome.It Va ansi_caption[x]
171*ba11c5b5SToomas SoomeIf
172*ba11c5b5SToomas Soome.Va loader_color
173*ba11c5b5SToomas Soomeis set
174*ba11c5b5SToomas Soome.Pq enabled by default ,
175*ba11c5b5SToomas Soomeuse this caption for menuitem
176*ba11c5b5SToomas Soome.Dq Li x
177*ba11c5b5SToomas Soomeinstead of
178*ba11c5b5SToomas Soome.Va menu_caption[x] .
179*ba11c5b5SToomas Soome.It Va toggled_text[x]
180*ba11c5b5SToomas SoomeFor menuitems where
181*ba11c5b5SToomas Soome.Va menu_command[x]
182*ba11c5b5SToomas Soomeis set to
183*ba11c5b5SToomas Soome.Dq Li toggle_menuitem
184*ba11c5b5SToomas Soome(or a derivative thereof), the text displayed
185*ba11c5b5SToomas Soomewill toggle between this and
186*ba11c5b5SToomas Soome.Va menu_caption[x] .
187*ba11c5b5SToomas Soome.It Va toggled_ansi[x]
188*ba11c5b5SToomas SoomeLike
189*ba11c5b5SToomas Soome.Va toggled_text[x]
190*ba11c5b5SToomas Soomeexcept used when
191*ba11c5b5SToomas Soome.Va loader_color
192*ba11c5b5SToomas Soomeis enabled
193*ba11c5b5SToomas Soome.Pq default .
194*ba11c5b5SToomas Soome.It Va menu_caption[x][y]
195*ba11c5b5SToomas SoomeFor menuitems where
196*ba11c5b5SToomas Soome.Va menu_command[x]
197*ba11c5b5SToomas Soomeis set to
198*ba11c5b5SToomas Soome.Dq Li cycle_menuitem
199*ba11c5b5SToomas Soome(or a derivative thereof), the text displayed will cycle between this and other
200*ba11c5b5SToomas Soome.Va menu_caption[x][y]
201*ba11c5b5SToomas Soomeentries.
202*ba11c5b5SToomas Soome.It Va ansi_caption[x][y]
203*ba11c5b5SToomas SoomeLike
204*ba11c5b5SToomas Soome.Va menu_caption[x][y]
205*ba11c5b5SToomas Soomeexcept used when
206*ba11c5b5SToomas Soome.Va loader_color
207*ba11c5b5SToomas Soomeis enabled
208*ba11c5b5SToomas Soome.Pq default .
209*ba11c5b5SToomas Soome.It Va menu_acpi
210*ba11c5b5SToomas SoomeWhen set to a number
211*ba11c5b5SToomas Soome.Dq Li x
212*ba11c5b5SToomas Soomeassociated with a given menuitem, that menuitem will allow to select
213*ba11c5b5SToomas Soomeacpi-user-options
214*ba11c5b5SToomas Soome.Pq see Xr eeprom 1M .
215*ba11c5b5SToomas Soome.It Va menu_options
216*ba11c5b5SToomas SoomeWhen set to a number
217*ba11c5b5SToomas Soome.Dq Li x ,
218*ba11c5b5SToomas Soomea single blank-line and an
219*ba11c5b5SToomas Soome.Dq Li Options
220*ba11c5b5SToomas Soomeheader are inserted between
221*ba11c5b5SToomas Soome.Va menu_caption[x-1]
222*ba11c5b5SToomas Soomeand
223*ba11c5b5SToomas Soome.Va menu_caption[x]
224*ba11c5b5SToomas Soome(if configured).
225*ba11c5b5SToomas Soome.It Va menu_reboot
226*ba11c5b5SToomas SoomeIf set, adds a built-in
227*ba11c5b5SToomas Soome.Dq Li Reboot
228*ba11c5b5SToomas Soomemenuitem to the end of the last configured menuitem.
229*ba11c5b5SToomas SoomeIf
230*ba11c5b5SToomas Soome.Va menu_options
231*ba11c5b5SToomas Soomeis configured, the
232*ba11c5b5SToomas Soome.Dq Li Reboot
233*ba11c5b5SToomas Soomemenuitem will be inserted before the
234*ba11c5b5SToomas Soome.Dq Options
235*ba11c5b5SToomas Soomeseparator.
236*ba11c5b5SToomas Soome.El
237*ba11c5b5SToomas Soome.Pp
238*ba11c5b5SToomas SoomeIn addition, it provides the following FICL words:
239*ba11c5b5SToomas Soome.Pp
240*ba11c5b5SToomas Soome.Bl -tag -width disable-module_module -compact -offset indent
241*ba11c5b5SToomas Soome.It Ic arch-i386? ( -- BOOL )
242*ba11c5b5SToomas SoomeReturns true (-1) on i386 and false (0) otherwise.
243*ba11c5b5SToomas Soome.It Ic acpipresent? ( -- BOOL )
244*ba11c5b5SToomas SoomeReturns true (-1) if ACPI is present and false (0) otherwise.
245*ba11c5b5SToomas Soome.It Ic acpienabled? ( -- BOOL )
246*ba11c5b5SToomas SoomeReturns true (-1) if ACPI is enabled and false (0) otherwise.
247*ba11c5b5SToomas Soome.It Ic toggle_menuitem ( N -- N )
248*ba11c5b5SToomas SoomeToggles menuitem
249*ba11c5b5SToomas Soome.Dq Li N
250*ba11c5b5SToomas Soomebetween
251*ba11c5b5SToomas Soome.Va menu_caption[x]
252*ba11c5b5SToomas Soomeand
253*ba11c5b5SToomas Soome.Va toggled_text[x]
254*ba11c5b5SToomas Soome(where
255*ba11c5b5SToomas Soome.Dq Li N
256*ba11c5b5SToomas Soomerepresents the ASCII decimal value for
257*ba11c5b5SToomas Soome.Dq Li x ) .
258*ba11c5b5SToomas Soome.It Ic cycle_menuitem ( N -- N )
259*ba11c5b5SToomas SoomeCycles menuitem
260*ba11c5b5SToomas Soome.Dq Li N
261*ba11c5b5SToomas Soomebetween
262*ba11c5b5SToomas Soome.Va menu_caption[x][y]
263*ba11c5b5SToomas Soomeentries (where
264*ba11c5b5SToomas Soome.Va N
265*ba11c5b5SToomas Soomerepresents the ASCII decimal value for
266*ba11c5b5SToomas Soome.Va x ) .
267*ba11c5b5SToomas Soome.El
268*ba11c5b5SToomas Soome.Pp
269*ba11c5b5SToomas SoomeFor all values of
270*ba11c5b5SToomas Soome.Dq Li x
271*ba11c5b5SToomas Soomeabove, use any number between 1 through 9. Sorry, double-digits are not
272*ba11c5b5SToomas Soomecurrently supported.
273*ba11c5b5SToomas Soome.Sh FILES
274*ba11c5b5SToomas Soome.Bl -tag -width /boot/forth/loader.4th -compact
275*ba11c5b5SToomas Soome.It Pa /boot/zfsloader
276*ba11c5b5SToomas SoomeThe
277*ba11c5b5SToomas Soome.Xr zfsloader 5 .
278*ba11c5b5SToomas Soome.It Pa /boot/forth/menu.4th
279*ba11c5b5SToomas Soome.Nm
280*ba11c5b5SToomas Soomeitself.
281*ba11c5b5SToomas Soome.It Pa /boot/loader.rc
282*ba11c5b5SToomas Soome.Xr loader 5
283*ba11c5b5SToomas Soomebootstrapping script.
284*ba11c5b5SToomas Soome.El
285*ba11c5b5SToomas Soome.Sh EXAMPLES
286*ba11c5b5SToomas SoomeA simple boot menu:
287*ba11c5b5SToomas Soome.Pp
288*ba11c5b5SToomas Soome.Bd -literal -offset indent -compact
289*ba11c5b5SToomas Soomeinclude /boot/forth/menu.4th
290*ba11c5b5SToomas Soomemenu-init
291*ba11c5b5SToomas Soomeset menu_caption[1]="Boot"
292*ba11c5b5SToomas Soomeset menu_command[1]="boot"
293*ba11c5b5SToomas Soomeset menu_options=2
294*ba11c5b5SToomas Soomeset menu_caption[2]="Option: NO"
295*ba11c5b5SToomas Soomeset toggled_text[2]="Option: YES"
296*ba11c5b5SToomas Soomeset menu_command[2]="toggle_menuitem"
297*ba11c5b5SToomas Soomeset menu_timeout_command="boot"
298*ba11c5b5SToomas Soomeset menu_reboot
299*ba11c5b5SToomas Soomemenu-display
300*ba11c5b5SToomas Soome.Ed
301*ba11c5b5SToomas Soome.Sh SEE ALSO
302*ba11c5b5SToomas Soome.Xr eeprom 1M ,
303*ba11c5b5SToomas Soome.Xr loader.conf 4 ,
304*ba11c5b5SToomas Soome.Xr beastie.4th 5 ,
305*ba11c5b5SToomas Soome.Xr loader 5 ,
306*ba11c5b5SToomas Soome.Xr loader.4th 5
307