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 2, 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.kernelList
 142 Returns a table of kernels to display on the boot menu.
 143 This will combine
 144 .Ic kernel
 145 and
 146 .Ic kernels
 147 from
 148 .Xr loader.conf 5 .
 149 If
 150 .Ic kernels_autodetect
 151 is set in
 152 .Xr loader.conf 5 ,
 153 kernels will be autodetected from the current system.
 154 .It Fn core.bootenvDefault
 155 Returns the default boot environment, nil if unset.
 156 .It Fn core.bootenvList
 157 Returns a table of boot environments, or an empty table.
 158 These will be picked up using the
 159 .Ev bootenvs
 160 and
 161 .Ev bootenvs_count
 162 variables set by
 163 .Xr zfsloader 8 .
 164 .It Fn core.setDefaults
 165 Resets ACPI, safe mode, single user, and verbose settings to their system
 166 defauilts.
 167 .It Fn core.autoboot argstr
 168 Loads the kernel and specified modules, then invokes the
 169 .Ic autoboot
 170 .Xr loader 8
 171 command with
 172 .Fa argstr
 173 as-is.
 174 .It Fn core.boot argstr
 175 Loads the kernel and specified modules, then invokes the
 176 .Ic boot
 177 .Xr loader 8
 178 command with
 179 .Fa argstr
 180 as-is.
 181 .It Fn core.isSingleUserBoot
 182 Returns true if
 183 .Ev boot_single
 184 is set to yes.
 185 .It Fn core.isZFSBoot
 186 Returns true if
 187 .Ev currdev
 188 is set to a
 189 .Xr zfs 8
 190 dataset.
 191 .It Fn core.isSerialBoot
 192 Returns true if we are booting over serial.
 193 This checks
 194 .Ev console ,
 195 .Ev boot_serial ,
 196 and
 197 .Ev boot_multicons .
 198 .It Fn core.isSystem386
 199 Returns true if this bootloader was compiled as an i386 binary.
 200 This generally applies to i386 loaders as well as non-UEFI loaders on amd64.
 201 .It Fn core.deepCopyTable tbl
 202 Recursively deep copies
 203 .Fa tbl
 204 and returns the result.
 205 .It Fn core.popFrontTable tbl
 206 Pops the front element off of
 207 .Fa tbl ,
 208 and returns two return values: the front element, and the rest of the table.
 209 If there are no elements, this returns nil and nil.
 210 If there is one element, this returns the front element and an empty table.
 211 This will not operate on truly associative tables; numeric indices are
 212 required.
 213 .El
 214 .Sh SEE ALSO
 215 .Xr loader.conf 5 ,
 216 .Xr loader 8 ,
 217 .Xr menu.lua 8
 218 .Sh AUTHORS
 219 The
 220 .Nm
 221 file was originally written by
 222 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
 223 Later work and this manual page was done by
 224 .An Kyle Evans Aq Mt kevans@FreeBSD.org .