stand/lua/core.lua.8

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd March 21, 2018
  31 .Dt CORE.LUA 8
  32 .Os
  33 .Sh NAME
  34 .Nm core.lua
  35 .Nd FreeBSD core module
  36 .Sh DESCRIPTION
  37 .Nm
  38 contains core functionality that does not have a more fitting module.
  39 .Pp
  40 Before hooking into or using the functionality provided by
  41 .Nm ,
  42 it must be included with a statement such as the following:
  43 .Pp
  44 .Dl local core = require("core")
  45 .Ss CONSTANTS
  46 The following raw key code constants are defined in
  47 .Nm :
  48 .Bl -tag -width KEY_BACKSPACE -compact -offset indent
  49 .It Ic KEY_BACKSPACE
  50 The backspace code.
  51 Should generally be checked along with
  52 .Ic KEY_DELETE
  53 for backspace functionality.
  54 .It Ic KEY_ENTER
  55 The enter key, or hard return.
  56 .It Ic KEY_DELETE
  57 The delete code.
  58 Should generally be checked along with
  59 .Ic KEY_BACKSPACE
  60 for backspace functionality.
  61 .El
  62 .Pp
  63 The following key-string constants are defined in
  64 .Nm :
  65 .Bl -tag -width KEYSTR_ESCAPE -compact -offset indent
  66 .It Ic KEYSTR_ESCAPE
  67 The escape key.
  68 .It Ic KEYSTR_CSI
  69 The ANSI CSI sequence.
  70 .El
  71 .Pp
  72 The following menu entry type constants are defined in
  73 .Nm :
  74 .Bl -tag -width MENU_CAROUSEL_ENTRY -compact -offset indent
  75 .It Ic MENU_RETURN
  76 Return to the parent menu.
  77 .It Ic MENU_ENTRY
  78 A normal menu entry.
  79 .It Ic MENU_SEPARATOR
  80 A menu entry that serves as a separator.
  81 .It Ic MENU_SUBMENU
  82 A menu entry that opens a submenu when selected.
  83 .It Ic MENU_CAROUSEL_ENTRY
  84 A menu entry that rotates through items like a carousel upon selection of the
  85 menu entry.
  86 .El
  87 .Pp
  88 Please see
  89 .Xr menu.lua 8
  90 for extended descriptions and usage of the
  91 .Ic MENU_*
  92 constants.
  93 .Ss Exported functions
  94 The following functions are exported from
  95 .Nm :
  96 .Bl -tag -width core.getACPIPresent -offset indent
  97 .It Fn core.setVerbose verbose
  98 Sets or unsets
  99 .Ev boot_verbose .
 100 If
 101 .Fa verbose
 102 is omitted, toggle the current verbose setting.
 103 .It Fn core.setSingleUser singleUser
 104 Sets or unsets
 105 .Ev boot_single .
 106 If
 107 .Fa singleUser
 108 is omitted, toggle the current single user setting.
 109 .It Fn core.getACPIPresent checkingSystemDefaults
 110 Check whether ACPI is present.
 111 This will only be accurate for i386-compatible loaders, including non-UEFI
 112 loaders on amd64 systems.
 113 If
 114 .Fa checkingSystemDefaults
 115 is true, ignore the current value of
 116 .Ev hint.acpi.0.disabled .
 117 Otherwise, return true only if ACPI is both present and not disabled.
 118 .It Fn core.setACPI acpi
 119 Sets or unsets
 120 .Ev acpi_load ,
 121 .Ev hint.acpi.0.disabled ,
 122 and
 123 .Ev loader.acpi_disabled_by_user .
 124 If
 125 .Fa acpi
 126 is omitted, toggle the current ACPI setting.
 127 .It Fn core.setSafeMode safeMode
 128 Set the safe mode setting.
 129 Sets or unsets
 130 .Ev kern.smp.disabled ,
 131 .Ev hw.ata.ata_dma ,
 132 .Ev hw.ata.atapi_dma ,
 133 .Ev hw.ata.wc ,
 134 .Ev hw.eisa_slots ,
 135 .Ev kern.eventtimer.periodic ,
 136 and
 137 .Ev kern.geom.part.check_integrity .
 138 If
 139 .Fa safeMode
 140 is omitted, toggle the current safe mode setting.
 141 .It Fn core.clearCachedKernels
 142 Clears out the cache of kernels to be displayed on the boot menu.
 143 This function is registered as a
 144 .Ev config.reloaded
 145 hook.
 146 It is used to invalidate the kernel list whenever it may have changed, either
 147 due to a boot environment change or a potential change in either
 148 .Ic kernel
 149 or
 150 .Ic kernels .
 151 .It Fn core.kernelList
 152 Returns a table of kernels to display on the boot menu.
 153 This will combine
 154 .Ic kernel
 155 and
 156 .Ic kernels
 157 from
 158 .Xr loader.conf 5 .
 159 If
 160 .Ic kernels_autodetect
 161 is set in
 162 .Xr loader.conf 5 ,
 163 kernels will be autodetected from the current system.
 164 .It Fn core.bootenvDefault
 165 Returns the default boot environment, nil if unset.
 166 .It Fn core.bootenvList
 167 Returns a table of boot environments, or an empty table.
 168 These will be picked up using the
 169 .Ev bootenvs
 170 and
 171 .Ev bootenvs_count
 172 variables set by
 173 .Xr loader 8 .
 174 .It Fn core.setDefaults
 175 Resets ACPI, safe mode, single user, and verbose settings to their system
 176 defauilts.
 177 .It Fn core.autoboot argstr
 178 Loads the kernel and specified modules, then invokes the
 179 .Ic autoboot
 180 .Xr loader 8
 181 command with
 182 .Fa argstr
 183 as-is.
 184 .It Fn core.boot argstr
 185 Loads the kernel and specified modules, then invokes the
 186 .Ic boot
 187 .Xr loader 8
 188 command with
 189 .Fa argstr
 190 as-is.
 191 .It Fn core.isSingleUserBoot
 192 Returns true if
 193 .Ev boot_single
 194 is set to yes.
 195 .It Fn core.isZFSBoot
 196 Returns true if
 197 .Ev currdev
 198 is set to a
 199 .Xr zfs 8
 200 dataset.
 201 .It Fn core.isSerialBoot
 202 Returns true if we are booting over serial.
 203 This checks
 204 .Ev console ,
 205 .Ev boot_serial ,
 206 and
 207 .Ev boot_multicons .
 208 .It Fn core.isSystem386
 209 Returns true if this bootloader was compiled as an i386 binary.
 210 This generally applies to i386 loaders as well as non-UEFI loaders on amd64.
 211 .It Fn core.deepCopyTable tbl
 212 Recursively deep copies
 213 .Fa tbl
 214 and returns the result.
 215 .It Fn core.popFrontTable tbl
 216 Pops the front element off of
 217 .Fa tbl ,
 218 and returns two return values: the front element, and the rest of the table.
 219 If there are no elements, this returns nil and nil.
 220 If there is one element, this returns the front element and an empty table.
 221 This will not operate on truly associative tables; numeric indices are
 222 required.
 223 .El
 224 .Sh SEE ALSO
 225 .Xr loader.conf 5 ,
 226 .Xr loader 8 ,
 227 .Xr menu.lua 8
 228 .Sh AUTHORS
 229 The
 230 .Nm
 231 file was originally written by
 232 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
 233 Later work and this manual page was done by
 234 .An Kyle Evans Aq Mt kevans@FreeBSD.org .