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