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

   1 .\" Copyright (c) 2011 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 February 25, 2012
  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 YES
  87 (case-insensitive) or
  88 .Dq Li 1 ,
  89 causes the menu to be displayed in color wherever possible.
  90 This includes the
  91 use of ANSI bold for numbers appearing to the left of menuitems and the use of
  92 special
  93 .Dq Li ansi
  94 variables described below.
  95 .It Va autoboot_delay
  96 Number of seconds
  97 .Ic menu-display
  98 will wait before executing
  99 .Va menu_timeout_command
 100 .Ic ( boot
 101 by default) unless a key is pressed.
 102 If set to
 103 .Dq Li NO
 104 (case-insensitive)
 105 .Ic menu-display
 106 will wait for user input and never execute
 107 .Ic menu_timeout_command .
 108 If set to
 109 .Dq Li -1 ,
 110 .Ic menu-display
 111 will boot immediately, preventing both interruption of the autoboot process and
 112 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_timeout_x
 125 Sets the desired column position of the timeout countdown text.
 126 Default is 4.
 127 .It Va loader_menu_timeout_y
 128 Sets the desired row position of the timeout countdown text.
 129 Default is 23.
 130 .It Va loader_menu_title
 131 The text to display centered above the menu.
 132 Default is
 133 .Dq Li "Welcome to FreeBSD" .
 134 .It Va menu_caption[x]
 135 The text to be displayed for the numbered menuitem
 136 .Dq Li x .
 137 .It Va menu_command[x]
 138 The command to be executed when the number associated with menuitem
 139 .Dq Li x
 140 is pressed.
 141 See the list of included FICL words below for some ideas.
 142 .It Va menu_keycode[x]
 143 An optional decimal ASCII keycode to be associated with menuitem
 144 .Dq Li x .
 145 When pressed, will cause the execution of
 146 .Va menu_command[x] .
 147 .It Va ansi_caption[x]
 148 If
 149 .Va loader_color
 150 is set, use this caption for menuitem
 151 .Dq Li x
 152 instead of
 153 .Va menu_caption[x] .
 154 .It Va toggled_text[x]
 155 For menuitems where
 156 .Va menu_command[x]
 157 is set to
 158 .Dq Li toggle_menuitem
 159 (or a derivative thereof), the text displayed
 160 will toggle between this and
 161 .Va menu_caption[x] .
 162 .It Va toggled_ansi[x]
 163 Like
 164 .Va toggled_text[x]
 165 except used when
 166 .Va loader_color
 167 is enabled.
 168 .It Va menu_caption[x][y]
 169 For menuitems where
 170 .Va menu_command[x]
 171 is set to
 172 .Dq Li cycle_menuitem
 173 (or a derivative thereof), the text displayed will cycle between this and other
 174 .Va menu_caption[x][y]
 175 entries.
 176 .It Va ansi_caption[x][y]
 177 Like
 178 .Va menu_caption[x][y]
 179 except used when
 180 .Va loader_color
 181 is enabled.
 182 .It Va menu_acpi
 183 When set to a number
 184 .Dq Li x
 185 associated with a given menuitem, that menuitem will only appear when
 186 running on i386-compatible hardware,
 187 .Va hint.acpi.0.rsdp
 188 is set (indicating the presence of hardware ACPI support as detected by
 189 .Xr loader 8 ) ,
 190 and
 191 .Va hint.acpi.0.disabled
 192 is not set.
 193 On non-i386 hardware, menuitems configured after the
 194 .Dq Li menu_acpi
 195 menuitem will use a lower number (to compensate for the missing ACPI menuitem)
 196 but continue to function as expected.
 197 On i386-compatible hardware lacking ACPI support (as detected by
 198 .Xr loader 8 ) ,
 199 subsequent menuitems will retain their associated numbers.
 200 .It Va hint.acpi.0.rsdp
 201 Set automatically by
 202 .Xr loader 8
 203 on i386-compatible hardware when ACPI support is detected at boot time.
 204 Effects the display of the
 205 .Dq Li menu_acpi
 206 menuitem (if configured).
 207 .It Va hint.acpi.0.disabled
 208 Effects the display of the
 209 .Va menu_acpi
 210 menuitem.
 211 If set, the menuitem will display
 212 .Va toggled_text[x]
 213 .Va ( toggled_ansi[x]
 214 if
 215 .Va loader_color
 216 is set), otherwise
 217 .Va menu_caption[x]
 218 .Va ( ansi_caption[x]
 219 if
 220 .Va loader_color
 221 is set).
 222 .It Va menu_options
 223 When set to a number
 224 .Dq Li x ,
 225 a single blank-line and an
 226 .Dq Li Options
 227 header are inserted between
 228 .Va menu_caption[x-1]
 229 and
 230 .Va menu_caption[x]
 231 (if configured).
 232 .It Va menu_reboot
 233 If set, adds a built-in
 234 .Dq Li Reboot
 235 menuitem to the end of the last configured menuitem.
 236 If
 237 .Va menu_options
 238 is configured, the
 239 .Dq Li Reboot
 240 menuitem will be inserted before the
 241 .Dq Options
 242 separator.
 243 .El
 244 .Pp
 245 In addition, it provides the following FICL words:
 246 .Pp
 247 .Bl -tag -width disable-module_module -compact -offset indent
 248 .It Ic arch-i386? ( -- BOOL )
 249 Returns true (-1) on i386 and false (0) otherwise.
 250 .It Ic acpipresent? ( -- BOOL )
 251 Returns true (-1) if ACPI is present and false (0) otherwise.
 252 .It Ic acpienabled? ( -- BOOL )
 253 Returns true (-1) if ACPI is enabled and false (0) otherwise.
 254 .It Ic toggle_menuitem ( N -- N )
 255 Toggles menuitem
 256 .Dq Li N
 257 between
 258 .Va menu_caption[x]
 259 and
 260 .Va toggled_text[x]
 261 (where
 262 .Dq Li N
 263 represents the ASCII decimal value for
 264 .Dq Li x ) .
 265 .It Ic cycle_menuitem ( N -- N )
 266 Cycles menuitem
 267 .Dq Li N
 268 between
 269 .Va menu_caption[x][y]
 270 entries (where
 271 .Va N
 272 represents the ASCII decimal value for
 273 .Va x ) .
 274 .El
 275 .Pp
 276 For all values of
 277 .Dq Li x
 278 above, use any number between 1 through 9. Sorry, double-digits are not
 279 currently supported.
 280 .Sh FILES
 281 .Bl -tag -width /boot/loader.4th -compact
 282 .It Pa /boot/loader
 283 The
 284 .Xr loader 8 .
 285 .It Pa /boot/menu.4th
 286 .Nm
 287 itself.
 288 .It Pa /boot/loader.rc
 289 .Xr loader 8
 290 bootstrapping script.
 291 .El
 292 .Sh EXAMPLES
 293 A simple boot menu:
 294 .Pp
 295 .Bd -literal -offset indent -compact
 296 include /boot/menu.4th
 297 menu-init
 298 set menu_caption[1]="Boot"
 299 set menu_command[1]="boot"
 300 set menu_options=2
 301 set menu_caption[2]="Option: NO"
 302 set toggled_text[2]="Option: YES"
 303 set menu_command[2]="toggle_menuitem"
 304 set menu_timeout_command="boot"
 305 set menu_reboot
 306 menu-display
 307 .Ed
 308 .Sh SEE ALSO
 309 .Xr loader.conf 5 ,
 310 .Xr loader 8 ,
 311 .Xr loader.4th 8 ,
 312 .Xr beastie.4th 8
 313 .Sh HISTORY
 314 The
 315 .Nm
 316 set of commands first appeared in
 317 .Fx 9.0 .
 318 .Sh AUTHORS
 319 The
 320 .Nm
 321 set of commands was written by
 322 .An -nosplit
 323 .An Devin Teske Aq devinteske@hotmail.com .