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 37contains core functionality that does not have a more fitting module. 38.Pp 39Before hooking into or using the functionality provided by 40.Nm , 41it must be included with a statement such as the following: 42.Pp 43.Dl local core = require("core") 44.Ss CONSTANTS 45The following raw key code constants are defined in 46.Nm : 47.Bl -tag -width KEY_BACKSPACE -compact -offset indent 48.It Ic KEY_BACKSPACE 49The backspace code. 50Should generally be checked along with 51.Ic KEY_DELETE 52for backspace functionality. 53.It Ic KEY_ENTER 54The enter key, or hard return. 55.It Ic KEY_DELETE 56The delete code. 57Should generally be checked along with 58.Ic KEY_BACKSPACE 59for backspace functionality. 60.El 61.Pp 62The following key-string constants are defined in 63.Nm : 64.Bl -tag -width KEYSTR_ESCAPE -compact -offset indent 65.It Ic KEYSTR_ESCAPE 66The escape key. 67.It Ic KEYSTR_CSI 68The ANSI CSI sequence. 69.El 70.Pp 71The 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 75Return to the parent menu. 76.It Ic MENU_ENTRY 77A normal menu entry. 78.It Ic MENU_SEPARATOR 79A menu entry that serves as a separator. 80.It Ic MENU_SUBMENU 81A menu entry that opens a submenu when selected. 82.It Ic MENU_CAROUSEL_ENTRY 83A menu entry that rotates through items like a carousel upon selection of the 84menu entry. 85.El 86.Pp 87Please see 88.Xr menu.lua 8 89for extended descriptions and usage of the 90.Ic MENU_* 91constants. 92.Ss Exported functions 93The following functions are exported from 94.Nm : 95.Bl -tag -width core.getACPIPresent -offset indent 96.It Fn core.setVerbose verbose 97Sets or unsets 98.Ev boot_verbose . 99If 100.Fa verbose 101is omitted, toggle the current verbose setting. 102.It Fn core.setSingleUser singleUser 103Sets or unsets 104.Ev boot_single . 105If 106.Fa singleUser 107is omitted, toggle the current single user setting. 108.It Fn core.getACPIPresent checkingSystemDefaults 109Check whether ACPI is present. 110This will only be accurate for i386-compatible loaders, including non-UEFI 111loaders on amd64 systems. 112If 113.Fa checkingSystemDefaults 114is true, ignore the current value of 115.Ev hint.acpi.0.disabled . 116Otherwise, return true only if ACPI is both present and not disabled. 117.It Fn core.setACPI acpi 118Sets or unsets 119.Ev acpi_load , 120.Ev hint.acpi.0.disabled , 121and 122.Ev loader.acpi_disabled_by_user . 123If 124.Fa acpi 125is omitted, toggle the current ACPI setting. 126.It Fn core.setSafeMode safeMode 127Set the safe mode setting. 128Sets 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 , 135and 136.Ev kern.geom.part.check_integrity . 137If 138.Fa safeMode 139is omitted, toggle the current safe mode setting. 140.It Fn core.clearCachedKernels 141Clears out the cache of kernels to be displayed on the boot menu. 142This function is registered as a 143.Ev config.reloaded 144hook. 145It is used to invalidate the kernel list whenever it may have changed, either 146due to a boot environment change or a potential change in either 147.Ic kernel 148or 149.Ic kernels . 150.It Fn core.kernelList 151Returns a table of kernels to display on the boot menu. 152This will combine 153.Ic kernel 154and 155.Ic kernels 156from 157.Xr loader.conf 5 . 158If 159.Ic kernels_autodetect 160is set in 161.Xr loader.conf 5 , 162kernels will be autodetected from the current system. 163.It Fn core.bootenvDefault 164Returns the default boot environment, nil if unset. 165.It Fn core.bootenvList 166Returns a table of boot environments, or an empty table. 167These will be picked up using the 168.Ev bootenvs 169and 170.Ev bootenvs_count 171variables set by 172.Xr loader 8 . 173.It Fn core.setDefaults 174Resets ACPI, safe mode, single user, and verbose settings to their system 175defauilts. 176.It Fn core.autoboot argstr 177Loads the kernel and specified modules, then invokes the 178.Ic autoboot 179.Xr loader 8 180command with 181.Fa argstr 182as-is. 183.It Fn core.boot argstr 184Loads the kernel and specified modules, then invokes the 185.Ic boot 186.Xr loader 8 187command with 188.Fa argstr 189as-is. 190.It Fn core.isSingleUserBoot 191Returns true if 192.Ev boot_single 193is set to yes. 194.It Fn core.isZFSBoot 195Returns true if 196.Ev currdev 197is set to a 198.Xr zfs 8 199dataset. 200.It Fn core.isSerialBoot 201Returns true if we are booting over serial. 202This checks 203.Ev console , 204.Ev boot_serial , 205and 206.Ev boot_multicons . 207.It Fn core.isSystem386 208Returns true if this bootloader was compiled as an i386 binary. 209This generally applies to i386 loaders as well as non-UEFI loaders on amd64. 210.It Fn core.deepCopyTable tbl 211Recursively deep copies 212.Fa tbl 213and returns the result. 214.It Fn core.popFrontTable tbl 215Pops the front element off of 216.Fa tbl , 217and returns two return values: the front element, and the rest of the table. 218If there are no elements, this returns nil and nil. 219If there is one element, this returns the front element and an empty table. 220This will not operate on truly associative tables; numeric indices are 221required. 222.El 223.Sh SEE ALSO 224.Xr loader.conf 5 , 225.Xr loader 8 , 226.Xr menu.lua 8 227.Sh AUTHORS 228The 229.Nm 230file was originally written by 231.An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . 232Later work and this manual page was done by 233.An Kyle Evans Aq Mt kevans@FreeBSD.org . 234