From owner-dev-commits-src-all@freebsd.org Wed Sep 29 15:26:07 2021 Return-Path: Delivered-To: dev-commits-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id ECC6F676261; Wed, 29 Sep 2021 15:26:07 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4HKKvz6ClQz3vM3; Wed, 29 Sep 2021 15:26:07 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id B510B1A9B7; Wed, 29 Sep 2021 15:26:07 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 18TFQ7Fl036179; Wed, 29 Sep 2021 15:26:07 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 18TFQ7CY036178; Wed, 29 Sep 2021 15:26:07 GMT (envelope-from git) Date: Wed, 29 Sep 2021 15:26:07 GMT Message-Id: <202109291526.18TFQ7CY036178@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Warner Losh Subject: git: 9e1dc7bec331 - main - loader: create separate man pages for each of the loaders MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 9e1dc7bec331b4d120d4b0687cfd54692e4fddcb Auto-Submitted: auto-generated X-BeenThere: dev-commits-src-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the src repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 29 Sep 2021 15:26:08 -0000 The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=9e1dc7bec331b4d120d4b0687cfd54692e4fddcb commit 9e1dc7bec331b4d120d4b0687cfd54692e4fddcb Author: Warner Losh AuthorDate: 2021-09-29 15:21:17 +0000 Commit: Warner Losh CommitDate: 2021-09-29 15:24:47 +0000 loader: create separate man pages for each of the loaders Create a man page per loader. Loader(8) will have information common to all of them, while loader_${INTERP}(8) will have information relevant to that specific loader. Rewrite loader(8) to give an overview and point to the appropriate man page. Rewrite each of the loader_${INTER}(8) man pages to contain only the relevant information to that loader. Put all the common commands, environment variables, etc in loader_simp(8) and refernce that from the loader_lua or loader_4th man pages. The loader_lua(8) could use more details about the Lua integration. Additional organization may be benefitial. Sponsored by: Netflix Differential Revision: https://reviews.freebsd.org/D31340 --- stand/man/Makefile | 2 + stand/man/loader.8 | 1083 ++--------------------------------------------- stand/man/loader_4th.8 | 585 +++++++++++++++++++++++++ stand/man/loader_lua.8 | 277 ++++++++++++ stand/man/loader_simp.8 | 28 +- 5 files changed, 911 insertions(+), 1064 deletions(-) diff --git a/stand/man/Makefile b/stand/man/Makefile index 5523908b6814..27370624ff62 100644 --- a/stand/man/Makefile +++ b/stand/man/Makefile @@ -5,6 +5,8 @@ M.${MK_EFI}+= boot1.efi.8 M.yes+= loader.8 M.${MK_EFI}+= loader.efi.8 +M.${MK_FORTH}+= loader_4th.8 +M.${MK_LOADER_LUA}+= loader_lua.8 M.yes+= loader_simp.8 MAN=${M.yes} diff --git a/stand/man/loader.8 b/stand/man/loader.8 index c606068941a7..b71ac71e16ce 100644 --- a/stand/man/loader.8 +++ b/stand/man/loader.8 @@ -1,5 +1,6 @@ .\" Copyright (c) 1999 Daniel C. Sobral .\" All rights reserved. +.\" Copyright (c) 2021 Warner Losh .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -24,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd April 7, 2021 +.Dd September 29, 2021 .Dt LOADER 8 .Os .Sh NAME @@ -36,13 +37,14 @@ The program called is the final stage of .Fx Ns 's kernel bootstrapping process. -On IA32 (i386) architectures, it is a -.Pa BTX -client. -It is linked statically to -.Xr libstand 3 -and usually located in the directory -.Pa /boot . +It is responsible for bringing the kernel, kernel modules and other files into +memory. +It creates a set of +.Xr sh 1 +like environment variables that are passed to the kernel. +It executes boot scripts written in one of several interpreters. +Together with the scripts, it controls the booting process and +interaction with the user. .Pp It provides a scripting language that can be used to automate tasks, do pre-configuration or assist in recovery @@ -53,10 +55,17 @@ The smaller one is a set of commands designed for direct use by the casual user, called "builtin commands" for historical reasons. The main drive behind these commands is user-friendliness. -The bigger component is an -.Tn ANS -Forth compatible Forth interpreter based on FICL, by +The larger component is the scripting language built into +the boot loader. +.Fx +provides three different interpreters: Forth, Lua and Simple. +The Forth loader is based on an ANS Forth compatible +Forth interpreter based on FICL, by .An John Sadler . +The Lua loader is includes a full Lua interpreter from +.Pa https://www.lua.org/ . +The Simple loader only interprets a list of builtin commands +without any control structure. .Pp During initialization, .Nm @@ -73,1039 +82,36 @@ and are set, and .Va LINES is set to 24. -Next, -.Tn FICL -is initialized, the builtin words are added to its vocabulary, and -.Pa /boot/loader.4th -is processed if it exists. -No disk switching is possible while that file is being read. -The inner interpreter -.Nm -will use with -.Tn FICL -is then set to -.Ic interpret , -which is -.Tn FICL Ns 's -default. -After that, -.Pa /boot/loader.rc -is processed if available. -These files are processed through the -.Ic include -command, which reads all of them into memory before processing them, -making disk changes possible. -.Pp -At this point, if an -.Ic autoboot -has not been tried, and if -.Va autoboot_delay -is not set to -.Dq Li NO -(not case sensitive), then an -.Ic autoboot -will be tried. -If the system gets past this point, -.Va prompt -will be set and -.Nm -will engage interactive mode. -Please note that historically even when -.Va autoboot_delay -is set to -.Dq Li 0 -user will be able to interrupt autoboot process by pressing some key -on the console while kernel and modules are being loaded. -In some -cases such behaviour may be undesirable, to prevent it set -.Va autoboot_delay -to -.Dq Li -1 , -in this case -.Nm -will engage interactive mode only if -.Ic autoboot -has failed. +Finally, an interpreter specific file will be executed. .Sh BUILTIN COMMANDS -In -.Nm , -builtin commands take parameters from the command line. -Presently, -the only way to call them from a script is by using -.Pa evaluate -on a string. -If an error condition occurs, an exception will be generated, -which can be intercepted using -.Tn ANS -Forth exception handling -words. -If not intercepted, an error message will be displayed and -the interpreter's state will be reset, emptying the stack and restoring -interpreting mode. -.Pp -The builtin commands available are: -.Pp -.Bl -tag -width Ds -compact -.It Ic autoboot Op Ar seconds Op Ar prompt -Proceeds to bootstrap the system after a number of seconds, if not -interrupted by the user. -Displays a countdown prompt -warning the user the system is about to be booted, -unless interrupted by a key press. -The kernel will be loaded first if necessary. -Defaults to 10 seconds. -.Pp -.It Ic bcachestat -Displays statistics about disk cache usage. -For debugging only. -.Pp -.It Ic boot -.It Ic boot Ar kernelname Op Cm ... -.It Ic boot Fl flag Cm ... -Immediately proceeds to bootstrap the system, loading the kernel -if necessary. -Any flags or arguments are passed to the kernel, but they -must precede the kernel name, if a kernel name is provided. -.Pp -.Em WARNING : -The behavior of this builtin is changed if -.Xr loader.4th 8 -is loaded. -.Pp -.It Ic echo Xo -.Op Fl n -.Op Aq message -.Xc -Displays text on the screen. -A new line will be printed unless -.Fl n -is specified. -.Pp -.It Ic heap -Displays memory usage statistics. -For debugging purposes only. -.Pp -.It Ic help Op topic Op subtopic -Shows help messages read from -.Pa /boot/loader.help . -The special topic -.Em index -will list the topics available. -.Pp -.It Ic include Ar file Op Ar -Process script files. -Each file, in turn, is completely read into memory, -and then each of its lines is passed to the command line interpreter. -If any error is returned by the interpreter, the include -command aborts immediately, without reading any other files, and -returns an error itself (see -.Sx ERRORS ) . -.Pp -.It Ic load Xo -.Op Fl t Ar type -.Ar file Cm ... -.Xc -Loads a kernel, kernel loadable module (kld), disk image, -or file of opaque contents tagged as being of the type -.Ar type . -Kernel and modules can be either in a.out or ELF format. -Any arguments passed after the name of the file to be loaded -will be passed as arguments to that file. -Use the -.Li md_image -type to make the kernel create a file-backed -.Xr md 4 -disk. -This is useful for booting from a temporary rootfs. -Currently, argument passing does not work for the kernel. -.Pp -.It Ic load_geli Xo -.Op Fl n Ar keyno -.Ar prov Ar file -.Xc -Loads a -.Xr geli 8 -encryption keyfile for the given provider name. -The key index can be specified via -.Ar keyno -or will default to zero. -.Pp -.It Ic ls Xo -.Op Fl l -.Op Ar path -.Xc -Displays a listing of files in the directory -.Ar path , -or the root directory if -.Ar path -is not specified. -If -.Fl l -is specified, file sizes will be shown too. -.Pp -.It Ic lsdev Op Fl v -Lists all of the devices from which it may be possible to load modules, -as well as ZFS pools. -If -.Fl v -is specified, more details are printed, including ZFS pool information -in a format that resembles -.Nm zpool Cm status -output. -.Pp -.It Ic lsmod Op Fl v -Displays loaded modules. -If -.Fl v -is specified, more details are shown. -.Pp -.It Ic lszfs Ar filesystem -A ZFS extended command that can be used to explore the ZFS filesystem -hierarchy in a pool. -Lists the immediate children of the -.Ar filesystem . -The filesystem hierarchy is rooted at a filesystem with the same name -as the pool. -.Pp -.It Ic more Ar file Op Ar -Display the files specified, with a pause at each -.Va LINES -displayed. -.Pp -.It Ic pnpscan Op Fl v -Scans for Plug-and-Play devices. -This is not functional at present. -.Pp -.It Ic read Xo -.Op Fl t Ar seconds -.Op Fl p Ar prompt -.Op Va variable -.Xc -Reads a line of input from the terminal, storing it in -.Va variable -if specified. -A timeout can be specified with -.Fl t , -though it will be canceled at the first key pressed. -A prompt may also be displayed through the -.Fl p -flag. -.Pp -.It Ic reboot -Immediately reboots the system. -.Pp -.It Ic set Ar variable -.It Ic set Ar variable Ns = Ns Ar value -Set loader's environment variables. -.Pp -.It Ic show Op Va variable -Displays the specified variable's value, or all variables and their -values if -.Va variable -is not specified. -.Pp -.It Ic unload -Remove all modules from memory. -.Pp -.It Ic unset Va variable -Removes -.Va variable -from the environment. -.Pp -.It Ic \&? -Lists available commands. -.El +The commands common to all interpreters are described in the +.Xr loader_simp 8 +.Dq BUILTIN COMMANDS +section. .Ss BUILTIN ENVIRONMENT VARIABLES -The -.Nm -has actually two different kinds of -.Sq environment -variables. -There are ANS Forth's -.Em environmental queries , -and a separate space of environment variables used by builtins, which -are not directly available to Forth words. -It is the latter type that this section covers. -.Pp -Environment variables can be set and unset through the -.Ic set -and -.Ic unset -builtins, and can have their values interactively examined through the -use of the -.Ic show -builtin. -Their values can also be accessed as described in -.Sx BUILTIN PARSER . -.Pp -Notice that these environment variables are not inherited by any shell -after the system has been booted. -.Pp -A few variables are set automatically by -.Nm . -Others can affect the behavior of either -.Nm -or the kernel at boot. -Some options may require a value, -while others define behavior just by being set. -Both types of builtin variables are described below. -.Bl -tag -width bootfile -.It Va autoboot_delay -Number of seconds -.Ic autoboot -will wait before booting. -Configuration options are described in -.Xr loader.conf 5 . -.It Va boot_askname -Instructs the kernel to prompt the user for the name of the root device -when the kernel is booted. -.It Va boot_cdrom -Instructs the kernel to try to mount the root file system from CD-ROM. -.It Va boot_ddb -Instructs the kernel to start in the DDB debugger, rather than -proceeding to initialize when booted. -.It Va boot_dfltroot -Instructs the kernel to mount the statically compiled-in root file system. -.It Va boot_gdb -Selects gdb-remote mode for the kernel debugger by default. -.It Va boot_multicons -Enables multiple console support in the kernel early on boot. -In a running system, console configuration can be manipulated -by the -.Xr conscontrol 8 -utility. -.It Va boot_mute -All kernel console output is suppressed when console is muted. -In a running system, the state of console muting can be manipulated by the -.Xr conscontrol 8 -utility. -.It Va boot_pause -During the device probe, pause after each line is printed. -.It Va boot_serial -Force the use of a serial console even when an internal console -is present. -.It Va boot_single -Prevents the kernel from initiating a multi-user startup; instead, -a single-user mode will be entered when the kernel has finished -device probing. -.It Va boot_verbose -Setting this variable causes extra debugging information to be printed -by the kernel during the boot phase. -.It Va bootfile -List of semicolon-separated search path for bootable kernels. -The default is -.Dq Li kernel . -.It Va comconsole_speed -Defines the speed of the serial console (i386 and amd64 only). -If the previous boot stage indicated that a serial console is in use -then this variable is initialized to the current speed of the console -serial port. -Otherwise it is set to 9600 unless this was overridden using the -.Va BOOT_COMCONSOLE_SPEED -variable when -.Nm -was compiled. -Changes to the -.Va comconsole_speed -variable take effect immediately. -.It Va comconsole_port -Defines the base i/o port used to access console UART -(i386 and amd64 only). -If the variable is not set, its assumed value is 0x3F8, which -corresponds to PC port COM1, unless overridden by -.Va BOOT_COMCONSOLE_PORT -variable during the compilation of -.Nm . -Setting the -.Va comconsole_port -variable automatically set -.Va hw.uart.console -environment variable to provide a hint to kernel for location of the console. -Loader console is changed immediately after variable -.Va comconsole_port -is set. -.It Va comconsole_pcidev -Defines the location of a PCI device of the 'simple communication' -class to be used as the serial console UART (i386 and amd64 only). -The syntax of the variable is -.Li 'bus:device:function[:bar]' , -where all members must be numeric, with possible -.Li 0x -prefix to indicate a hexadecimal value. -The -.Va bar -member is optional and assumed to be 0x10 if omitted. -The bar must decode i/o space. -Setting the variable -.Va comconsole_pcidev -automatically sets the variable -.Va comconsole_port -to the base of the selected bar, and hint -.Va hw.uart.console . -Loader console is changed immediately after variable -.Va comconsole_pcidev -is set. -.It Va console -Defines the current console or consoles. -Multiple consoles may be specified. -In that case, the first listed console will become the default console for -userland output (e.g.\& from -.Xr init 8 ) . -.It Va currdev -Selects the default device to loader the kernel from. -The syntax is: -.Dl Ic loader_device: -or -.Dl Ic zfs:dataset: -Examples: -.Dl Ic disk0p2: -.Dl Ic zfs:zroot/ROOT/default: -.It Va dumpdev -Sets the device for kernel dumps. -This can be used to ensure that a device is configured before the corresponding -.Va dumpdev -directive from -.Xr rc.conf 5 -has been processed, allowing kernel panics that happen during the early stages -of boot to be captured. -.It Va init_chroot -See -.Xr init 8 . -.It Va init_exec -See -.Xr init 8 . -.It Va init_path -Sets the list of binaries which the kernel will try to run as the initial -process. -The first matching binary is used. -The default list is -.Dq Li /sbin/init:/sbin/oinit:/sbin/init.bak:\:/rescue/init . -.It Va init_script -See -.Xr init 8 . -.It Va init_shell -See -.Xr init 8 . -.It Va interpret -Has the value -.Dq Li OK -if the Forth's current state is interpreting. -.It Va LINES -Define the number of lines on the screen, to be used by the pager. -.It Va module_path -Sets the list of directories which will be searched for modules -named in a load command or implicitly required by a dependency. -The default value for this variable is -.Dq Li /boot/kernel;/boot/modules . -.It Va num_ide_disks -Sets the number of IDE disks as a workaround for some problems in -finding the root disk at boot. -This has been deprecated in favor of -.Va root_disk_unit . -.It Va prompt -Value of -.Nm Ns 's -prompt. -Defaults to -.Dq Li "${interpret}" . -If variable -.Va prompt -is unset, the default prompt is -.Ql > . -.It Va root_disk_unit -If the code which detects the disk unit number for the root disk is -confused, e.g.\& by a mix of SCSI and IDE disks, or IDE disks with -gaps in the sequence (e.g.\& no primary slave), the unit number can -be forced by setting this variable. -.It Va rootdev -By default the value of -.Va currdev -is used to set the root file system -when the kernel is booted. -This can be overridden by setting -.Va rootdev -explicitly. -.El -.Pp -Other variables are used to override kernel tunable parameters. -The following tunables are available: -.Bl -tag -width Va -.It Va efi.rt.disabled -Disable UEFI runtime services in the kernel, if applicable. -Runtime services are only available and used if the kernel is booted in a UEFI -environment. -.It Va hw.physmem -Limit the amount of physical memory the system will use. -By default the size is in bytes, but the -.Cm k , K , m , M , g -and -.Cm G -suffixes -are also accepted and indicate kilobytes, megabytes and gigabytes -respectively. -An invalid suffix will result in the variable being ignored by the -kernel. -.It Va hw.pci.host_start_mem , hw.acpi.host_start_mem -When not otherwise constrained, this limits the memory start -address. -The default is 0x80000000 and should be set to at least size of the -memory and not conflict with other resources. -Typically, only systems without PCI bridges need to set this variable -since PCI bridges typically constrain the memory starting address -(and the variable is only used when bridges do not constrain this -address). -.It Va hw.pci.enable_io_modes -Enable PCI resources which are left off by some BIOSes or are not -enabled correctly by the device driver. -Tunable value set to ON (1) by default, but this may cause problems -with some peripherals. -.It Va kern.maxusers -Set the size of a number of statically allocated system tables; see -.Xr tuning 7 -for a description of how to select an appropriate value for this -tunable. -When set, this tunable replaces the value declared in the kernel -compile-time configuration file. -.It Va kern.ipc.nmbclusters -Set the number of mbuf clusters to be allocated. -The value cannot be set below the default -determined when the kernel was compiled. -.It Va kern.ipc.nsfbufs -Set the number of -.Xr sendfile 2 -buffers to be allocated. -Overrides -.Dv NSFBUFS . -Not all architectures use such buffers; see -.Xr sendfile 2 -for details. -.It Va kern.maxswzone -Limits the amount of KVM to be used to hold swap -metadata, which directly governs the -maximum amount of swap the system can support, -at the rate of approximately 200 MB of swap space -per 1 MB of metadata. -This value is specified in bytes of KVA space. -If no value is provided, the system allocates -enough memory to handle an amount of swap -that corresponds to eight times the amount of -physical memory present in the system. -.Pp -Note that swap metadata can be fragmented, -which means that the system can run out of -space before it reaches the theoretical limit. -Therefore, care should be taken to not configure -more swap than approximately half of the -theoretical maximum. -.Pp -Running out of space for swap metadata can leave -the system in an unrecoverable state. -Therefore, you should only change -this parameter if you need to greatly extend the -KVM reservation for other resources such as the -buffer cache or -.Va kern.ipc.nmbclusters . -Modifies kernel option -.Dv VM_SWZONE_SIZE_MAX . -.It Va kern.maxbcache -Limits the amount of KVM reserved for use by the -buffer cache, specified in bytes. -The default maximum is 200MB on i386, -and 400MB on amd64. -This parameter is used to -prevent the buffer cache from eating too much -KVM in large-memory machine configurations. -Only mess around with this parameter if you need to -greatly extend the KVM reservation for other resources -such as the swap zone or -.Va kern.ipc.nmbclusters . -Note that -the NBUF parameter will override this limit. -Modifies -.Dv VM_BCACHE_SIZE_MAX . -.It Va kern.msgbufsize -Sets the size of the kernel message buffer. -The default limit of 96KB is usually sufficient unless -large amounts of trace data need to be collected -between opportunities to examine the buffer or -dump it to a file. -Overrides kernel option -.Dv MSGBUF_SIZE . -.It Va machdep.disable_mtrrs -Disable the use of i686 MTRRs (x86 only). -.It Va net.inet.tcp.tcbhashsize -Overrides the compile-time set value of -.Dv TCBHASHSIZE -or the preset default of 512. -Must be a power of 2. -.It Va twiddle_divisor -Throttles the output of the -.Sq twiddle -I/O progress indicator displayed while loading the kernel and modules. -This is useful on slow serial consoles where the time spent waiting for -these characters to be written can add up to many seconds. -The default is 16; a value of 32 spins half as fast, -while a value of 8 spins twice as fast. -.It Va vm.kmem_size -Sets the size of kernel memory (bytes). -This overrides the value determined when the kernel was compiled. -Modifies -.Dv VM_KMEM_SIZE . -.It Va vm.kmem_size_min -.It Va vm.kmem_size_max -Sets the minimum and maximum (respectively) amount of kernel memory -that will be automatically allocated by the kernel. -These override the values determined when the kernel was compiled. -Modifies -.Dv VM_KMEM_SIZE_MIN -and -.Dv VM_KMEM_SIZE_MAX . -.El -.Ss ZFS FEATURES -.Nm -supports the following format for specifying ZFS filesystems which -can be used wherever -.Xr loader 8 -refers to a device specification: -.Pp -.Ar zfs:pool/filesystem: -.Pp -where -.Pa pool/filesystem -is a ZFS filesystem name as described in -.Xr zfs 8 . -.Pp -If -.Pa /etc/fstab -does not have an entry for the root filesystem and -.Va vfs.root.mountfrom -is not set, but -.Va currdev -refers to a ZFS filesystem, then -.Nm -will instruct kernel to use that filesystem as the root filesystem. -.Ss BUILTIN PARSER -When a builtin command is executed, the rest of the line is taken -by it as arguments, and it is processed by a special parser which -is not used for regular Forth commands. -.Pp -This special parser applies the following rules to the parsed text: -.Bl -enum -.It -All backslash characters are preprocessed. -.Bl -bullet -.It -\eb , \ef , \er , \en and \et are processed as in C. -.It -\es is converted to a space. -.It -\ev is converted to -.Tn ASCII -11. -.It -\ez is just skipped. -Useful for things like -.Dq \e0xf\ez\e0xf . -.It -\e0xN and \e0xNN are replaced by the hex N or NN. -.It -\eNNN is replaced by the octal NNN -.Tn ASCII -character. -.It -\e" , \e' and \e$ will escape these characters, preventing them from -receiving special treatment in Step 2, described below. -.It -\e\e will be replaced with a single \e . -.It -In any other occurrence, backslash will just be removed. -.El -.It -Every string between non-escaped quotes or double-quotes will be treated -as a single word for the purposes of the remaining steps. -.It -Replace any -.Li $VARIABLE -or -.Li ${VARIABLE} -with the value of the environment variable -.Va VARIABLE . -.It -Space-delimited arguments are passed to the called builtin command. -Spaces can also be escaped through the use of \e\e . -.El -.Pp -An exception to this parsing rule exists, and is described in -.Sx BUILTINS AND FORTH . -.Ss BUILTINS AND FORTH -All builtin words are state-smart, immediate words. -If interpreted, they behave exactly as described previously. -If they are compiled, though, -they extract their arguments from the stack instead of the command line. -.Pp -If compiled, the builtin words expect to find, at execution time, the -following parameters on the stack: -.D1 Ar addrN lenN ... addr2 len2 addr1 len1 N -where -.Ar addrX lenX -are strings which will compose the command line that will be parsed -into the builtin's arguments. -Internally, these strings are concatenated in from 1 to N, -with a space put between each one. -.Pp -If no arguments are passed, a 0 -.Em must -be passed, even if the builtin accepts no arguments. -.Pp -While this behavior has benefits, it has its trade-offs. -If the execution token of a builtin is acquired (through -.Ic ' -or -.Ic ['] ) , -and then passed to -.Ic catch -or -.Ic execute , -the builtin behavior will depend on the system state -.Bf Em -at the time -.Ic catch -or -.Ic execute -is processed! -.Ef -This is particularly annoying for programs that want or need to -handle exceptions. -In this case, the use of a proxy is recommended. -For example: -.Dl : (boot) boot ; -.Sh FICL -.Tn FICL -is a Forth interpreter written in C, in the form of a forth -virtual machine library that can be called by C functions and vice -versa. -.Pp -In -.Nm , -each line read interactively is then fed to -.Tn FICL , -which may call -.Nm -back to execute the builtin words. -The builtin -.Ic include -will also feed -.Tn FICL , -one line at a time. -.Pp -The words available to -.Tn FICL -can be classified into four groups. -The -.Tn ANS -Forth standard words, extra -.Tn FICL -words, extra -.Fx -words, and the builtin commands; -the latter were already described. -The -.Tn ANS -Forth standard words are listed in the -.Sx STANDARDS +The environment variables common to all interpreters are described in the +.Xr loader_simp 8 +.Dq BUILTIN ENVIRONMENT VARIABLES section. -The words falling in the two other groups are described in the -following subsections. -.Ss FICL EXTRA WORDS -.Bl -tag -width wid-set-super -.It Ic .env -.It Ic .ver -.It Ic -roll -.It Ic 2constant -.It Ic >name -.It Ic body> -.It Ic compare -This is the STRING word set's -.Ic compare . -.It Ic compile-only -.It Ic endif -.It Ic forget-wid -.It Ic parse-word -.It Ic sliteral -This is the STRING word set's -.Ic sliteral . -.It Ic wid-set-super -.It Ic w@ -.It Ic w! -.It Ic x. -.It Ic empty -.It Ic cell- -.It Ic -rot -.El -.Ss FREEBSD EXTRA WORDS -.Bl -tag -width XXXXXXXX -.It Ic \&$ Pq -- -Evaluates the remainder of the input buffer, after having printed it first. -.It Ic \&% Pq -- -Evaluates the remainder of the input buffer under a -.Ic catch -exception guard. -.It Ic .# -Works like -.Ic "." -but without outputting a trailing space. -.It Ic fclose Pq Ar fd -- -Closes a file. -.It Ic fkey Pq Ar fd -- char -Reads a single character from a file. -.It Ic fload Pq Ar fd -- -Processes a file -.Em fd . -.It Ic fopen Pq Ar addr len mode Li -- Ar fd -Opens a file. -Returns a file descriptor, or \-1 in case of failure. -The -.Ar mode -parameter selects whether the file is to be opened for read access, write -access, or both. -The constants -.Dv O_RDONLY , O_WRONLY , -and -.Dv O_RDWR -are defined in -.Pa /boot/support.4th , -indicating read only, write only, and read-write access, respectively. -.It Xo -.Ic fread -.Pq Ar fd addr len -- len' -.Xc -Tries to read -.Em len -bytes from file -.Em fd -into buffer -.Em addr . -Returns the actual number of bytes read, or -1 in case of error or end of -file. -.It Ic heap? Pq -- Ar cells -Return the space remaining in the dictionary heap, in cells. -This is not related to the heap used by dynamic memory allocation words. -.It Ic inb Pq Ar port -- char -Reads a byte from a port. -.It Ic key Pq -- Ar char -Reads a single character from the console. -.It Ic key? Pq -- Ar flag -Returns -.Ic true -if there is a character available to be read from the console. -.It Ic ms Pq Ar u -- -Waits -.Em u -microseconds. -.It Ic outb Pq Ar port char -- -Writes a byte to a port. -.It Ic seconds Pq -- Ar u -Returns the number of seconds since midnight. -.It Ic tib> Pq -- Ar addr len -Returns the remainder of the input buffer as a string on the stack. -.It Ic trace! Pq Ar flag -- -Activates or deactivates tracing. -Does not work with -.Ic catch . -.El -.Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES -.Bl -tag -width Ds -.It arch-i386 -.Ic TRUE -if the architecture is IA32. -.It FreeBSD_version -.Fx -version at compile time. -.It loader_version -.Nm -version. -.El -.Sh SECURITY -Access to the -.Nm -command line provides several ways of compromising system security, -including, but not limited to: -.Pp -.Bl -bullet -.It -Booting from removable storage, by setting the -.Va currdev -or -.Va loaddev -variables -.It -Executing binary of choice, by setting the *** 1134 LINES SKIPPED ***