share/man/man5/menu.4th.5

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