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