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