xref: /titanic_51/usr/src/man/man5/menu.4th.5 (revision d828baa435f064b9a001576f57c5f19a0a32755c)
1.\" Copyright (c) 2011-2013 Devin Teske
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
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
23.\" SUCH DAMAGE.
24.\"
25.Dd Apr 22, 2017
26.Dt MENU.4TH 5
27.Os
28.Sh NAME
29.Nm menu.4th
30.Nd loader dynamic menu boot module
31.Sh DESCRIPTION
32The file that goes by the name of
33.Nm
34is a set of commands designed to display a dynamic menu system managed through
35a system of carefully named environment variables.
36The commands of
37.Nm
38by themselves are not enough for most uses.
39Please refer to the
40examples below for the most common situations, and to
41.Xr loader 5
42for additional commands.
43.Pp
44Before using any of the commands provided in
45.Nm ,
46it must be included
47through the command:
48.Pp
49.Dl include menu.4th
50.Pp
51This line is present in the default
52.Pa /boot/forth/menu.rc
53file, so it is not needed (and should not be re-issued) in a normal setup.
54.Pp
55The commands provided by it are:
56.Pp
57.Bl -tag -width disable-module_module -compact -offset indent
58.It Ic menu-init
59Draws the menu bounding box and initializes some internal state variables.
60This should be called before any other menu-related functions.
61.It Ic menu-display
62Displays the menu (configured via the below documented environment variables)
63and blocks on keyboard input, awaiting user action.
64.It Ic menu-erase
65Clears the screen area within the menu bounding box.
66.It Ic menu-redraw
67Calls
68.Ic menu-erase
69and then redraws the menu.
70.It Ic menu-unset
71Unsets the environment variables associated with individual menu items,
72clearing the way for a new menu.
73.It Ic menu-clear
74Calls
75.Ic menu-unset
76and then
77.Ic menu-erase .
78.El
79.Pp
80The environment variables that effect its behavior are:
81.Bl -tag -width bootfile -offset indent
82.It Va loader_color
83If set to
84.Dq Li NO
85(case-insensitive) or
86.Dq Li 0 ,
87causes the menu to be displayed without color.
88The default is to use ANSI coloring whenever possible.
89If serial boot is enabled, color is disabled by default.
90Color features include the use of ANSI bold for numbers appearing to the left
91of menuitems and the use of special
92.Dq Li ansi
93variables described below.
94.It Va autoboot_delay
95Number of seconds
96.Ic menu-display
97will wait before executing
98.Va menu_timeout_command
99.Ic ( boot
100by default) unless a key is pressed.
101If set to
102.Dq Li NO
103(case-insensitive)
104.Ic menu-display
105will wait for user input and never execute
106.Ic menu_timeout_command .
107If set to
108.Dq Li -1 ,
109.Ic menu-display
110will boot immediately, preventing both interruption of the
111.Ic autoboot
112process and escaping to the loader prompt.
113Default is
114.Dq Li 10 .
115See
116.Xr loader 8
117for additional information.
118.It Va menu_timeout_command
119The command to be executed after
120.Va autoboot_delay
121seconds if a key is not pressed.
122The default is
123.Ic boot .
124.It Va loader_menu_frame
125Sets the desired box style to draw around the boot menu.
126Possible values are:
127.Dq Li single
128.Pq the default ,
129.Dq Li double ,
130and
131.Dq Li none .
132.It Va loader_menu_timeout_x
133Sets the desired column position of the timeout countdown text.
134Default is 4.
135.It Va loader_menu_timeout_y
136Sets the desired row position of the timeout countdown text.
137Default is 23.
138.It Va loader_menu_title
139The text to display above the menu.
140Default is
141.Dq Li "Welcome to FreeBSD" .
142.It Va loader_menu_title_align
143Default is to align
144.Ic loader_menu_title
145centered above the menu. This can be set to
146.Dq Li left
147or
148.Dq Li right
149to instead display the title left-or-right justified
150.Pq respectively .
151.It Va loader_menu_x
152Sets the desired column position of the boot menu.
153Default is 5.
154.It Va loader_menu_y
155Sets the desired row position of the boot menu.
156Default is 10.
157.It Va menu_caption[x]
158The text to be displayed for the numbered menuitem
159.Dq Li x .
160.It Va menu_command[x]
161The command to be executed when the number associated with menuitem
162.Dq Li x
163is pressed.
164See the list of included FICL words below for some ideas.
165.It Va menu_keycode[x]
166An optional decimal ASCII keycode to be associated with menuitem
167.Dq Li x .
168When pressed, will cause the execution of
169.Va menu_command[x] .
170.It Va ansi_caption[x]
171If
172.Va loader_color
173is set
174.Pq enabled by default ,
175use this caption for menuitem
176.Dq Li x
177instead of
178.Va menu_caption[x] .
179.It Va toggled_text[x]
180For menuitems where
181.Va menu_command[x]
182is set to
183.Dq Li toggle_menuitem
184(or a derivative thereof), the text displayed
185will toggle between this and
186.Va menu_caption[x] .
187.It Va toggled_ansi[x]
188Like
189.Va toggled_text[x]
190except used when
191.Va loader_color
192is enabled
193.Pq default .
194.It Va menu_caption[x][y]
195For menuitems where
196.Va menu_command[x]
197is set to
198.Dq Li cycle_menuitem
199(or a derivative thereof), the text displayed will cycle between this and other
200.Va menu_caption[x][y]
201entries.
202.It Va ansi_caption[x][y]
203Like
204.Va menu_caption[x][y]
205except used when
206.Va loader_color
207is enabled
208.Pq default .
209.It Va menu_acpi
210When set to a number
211.Dq Li x
212associated with a given menuitem, that menuitem will allow to select
213acpi-user-options
214.Pq see Xr eeprom 1M .
215.It Va menu_options
216When set to a number
217.Dq Li x ,
218a single blank-line and an
219.Dq Li Options
220header are inserted between
221.Va menu_caption[x-1]
222and
223.Va menu_caption[x]
224(if configured).
225.It Va menu_reboot
226If set, adds a built-in
227.Dq Li Reboot
228menuitem to the end of the last configured menuitem.
229If
230.Va menu_options
231is configured, the
232.Dq Li Reboot
233menuitem will be inserted before the
234.Dq Options
235separator.
236.El
237.Pp
238In addition, it provides the following FICL words:
239.Pp
240.Bl -tag -width disable-module_module -compact -offset indent
241.It Ic arch-i386? ( -- BOOL )
242Returns true (-1) on i386 and false (0) otherwise.
243.It Ic acpipresent? ( -- BOOL )
244Returns true (-1) if ACPI is present and false (0) otherwise.
245.It Ic acpienabled? ( -- BOOL )
246Returns true (-1) if ACPI is enabled and false (0) otherwise.
247.It Ic toggle_menuitem ( N -- N )
248Toggles menuitem
249.Dq Li N
250between
251.Va menu_caption[x]
252and
253.Va toggled_text[x]
254(where
255.Dq Li N
256represents the ASCII decimal value for
257.Dq Li x ) .
258.It Ic cycle_menuitem ( N -- N )
259Cycles menuitem
260.Dq Li N
261between
262.Va menu_caption[x][y]
263entries (where
264.Va N
265represents the ASCII decimal value for
266.Va x ) .
267.El
268.Pp
269For all values of
270.Dq Li x
271above, use any number between 1 through 9. Sorry, double-digits are not
272currently supported.
273.Sh FILES
274.Bl -tag -width /boot/forth/loader.4th -compact
275.It Pa /boot/zfsloader
276The
277.Xr zfsloader 5 .
278.It Pa /boot/forth/menu.4th
279.Nm
280itself.
281.It Pa /boot/loader.rc
282.Xr loader 5
283bootstrapping script.
284.El
285.Sh EXAMPLES
286A simple boot menu:
287.Pp
288.Bd -literal -offset indent -compact
289include /boot/forth/menu.4th
290menu-init
291set menu_caption[1]="Boot"
292set menu_command[1]="boot"
293set menu_options=2
294set menu_caption[2]="Option: NO"
295set toggled_text[2]="Option: YES"
296set menu_command[2]="toggle_menuitem"
297set menu_timeout_command="boot"
298set menu_reboot
299menu-display
300.Ed
301.Sh SEE ALSO
302.Xr eeprom 1M ,
303.Xr loader.conf 4 ,
304.Xr beastie.4th 5 ,
305.Xr loader 5 ,
306.Xr loader.4th 5
307