sys/boot/forth/menu.4th.8

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