OS-8361 IPD 4 (man page renumbering) tracking issue

Reviewed by: Brian Bennett <brian.bennett@joyent.com>
Approved by: Brian Bennett <brian.bennett@joyent.com>

1 files changed, 909 insertions, 0 deletions

diff --git a/usr/src/man/man7/loader.7 b/usr/src/man/man7/loader.7
new file mode 100644
index 0000000000..c3ab1d35b3
--- /dev/null
+++ b/usr/src/man/man7/loader.7
@@ -0,0 +1,909 @@
+.\" Copyright (c) 1999 Daniel C. Sobral
+.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd January 25, 2022
+.Dt LOADER 7
+.Os
+.Sh NAME
+.Nm loader
+.Nd kernel bootstrapping final stage
+.Sh DESCRIPTION
+The
+.Nm
+is the final stage of
+.Nm illumos Ns 's
+kernel bootstrapping process.
+The actual name for the stage depends on the platform.
+On IA32 (i386) architectures with BIOS firmware, it is a
+.Pa BTX
+client and named
+.Nm loader .
+It is linked statically to libstand and usually located in the directory
+.Pa /boot .
+.Pp
+.Nm
+supports booting from
+.Cm ZFS ,
+.Cm UFS ,
+.Cm PCFS ,
+.Cm HSFS
+and
+.Cm NFS
+file systems.
+Additionally,
+.Nm
+can load files from the
+.Cm TFTP
+file service.
+The NFS and TFTP based boot is enabled via
+.Xr pxeboot 7 .
+The
+.Nm
+also does support uncompressing gzip files while reading.
+The uncompression will happen automatically if the compressed file is stored
+without .gz suffix or if the file is accessed by leaving out the .gz suffix from
+the name.
+If the file is referred by full name, including .gz suffix, then the file
+content is read as is and the uncompression is not performed.
+.Pp
+.Nm
+provides a scripting language that can be used to
+automate tasks, do pre-configuration or assist in recovery
+procedures.
+This scripting language is roughly divided in
+two main components.
+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
+.An John Sadler .
+.Pp
+During initialization,
+.Nm
+will probe for a console and set the
+.Va console
+variable, or set it to serial console
+.Pq Do Li ttya Dc - Dq Li ttyd
+if the previous boot stage used that.
+If multiple consoles are selected, they will be listed separated by commas.
+Then, devices are probed,
+.Va currdev
+and
+.Va loaddev
+are set, and
+.Va screen-#cols ,
+.Va screen-#rows ,
+and
+.Va ISADIR
+are set.
+Next,
+.Tn FICL
+is initialized, the builtin words are added to its vocabulary.
+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.
+.Ss Builtin Commands
+In
+.Nm ,
+builtin commands take parameters from the command line.
+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 7
+is loaded.
+.Pp
+.It Ic chain Ar device
+Chain load another boot loader from the specified device.
+Device can be either disk name or partition.
+.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 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.
+.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.
+In addition to disks and partitions, ZFS pools are also listed.
+If
+.Fl v
+is specified, more details are printed.
+For ZFS pools the output 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 screen-#rows
+displayed.
+.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
+.Ss ZFS Features
+.Nm
+supports the following format for specifying ZFS filesystems which
+can be used wherever
+.Nm
+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 .
+.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.
+If this variable is not defined,
+.Ic autoboot
+will default to 10 seconds.
+.Pp
+If set to
+.Dq Li NO ,
+no
+.Ic autoboot
+will be automatically attempted after processing
+.Pa /boot/loader.rc ,
+though explicit
+.Ic autoboot Ns 's
+will be processed normally, defaulting to 10 seconds delay.
+.Pp
+If set to
+.Dq Li 0 ,
+no delay will be inserted, but user still will be able to interrupt
+.Ic autoboot
+process and escape into the interactive mode by pressing some key
+on the console while kernel and
+modules are being loaded.
+.Pp
+If set to
+.Dq Li -1 ,
+no delay will be inserted and
+.Nm
+will engage interactive mode only if
+.Ic autoboot
+has failed for some reason.
+.It Va boot_ask
+Will set
+.Xr kernel 8
+.Fl a
+option.
+.It Va boot_debug
+Will set
+.Xr kernel 8
+.Fl d
+option.
+.It Va boot_kmdb
+Will set
+.Xr kernel 8
+.Fl k
+option.
+.It Va boot_reconfigure
+Will set
+.Xr kernel 8
+.Fl r
+option.
+.It Va boot_single
+Will set
+.Xr kernel 8
+.Fl s
+option.
+.It Va boot_verbose
+Will set
+.Xr kernel 8
+.Fl v
+option.
+.It Va boot-args
+Will set custom arguments for the kernel.
+If set in
+.Nm
+configuration, the
+.Nm
+startup will parse the
+.Va boot-args
+value to set boot prefixed variables listed above, any unrecognized options
+are added to kernel command line verbatim.
+.It Va bootfile
+The name of the kernel.
+.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
+the
+.Xr kernel 8 .
+.It Va currdev
+Selects the default device.
+Syntax for devices is odd.
+.It Va interpret
+Has the value
+.Dq Li ok
+if the Forth's current state is interpreting.
+.It Va screen-#rows
+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 /platform/i86pc/${ISADIR}
+.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 os_console
+If set, the value is used to set
+.Xr kernel 8
+.Va console
+property.
+.El
+.Pp
+Other variables are used for loader or to set kernel properties or for
+informational purposes.
+.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 ;
+.Ss 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
+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 Loader 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/forth/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 isvirtualized? Pq -- Ar addr len flag | Ar flag
+Returns
+.Ic true
+and string with virtualization engine name or
+.Ic false .
+.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.
+.El
+.Ss Loader Extra Framebuffer Words
+.Bl -tag -width XXXXXXXX
+.It Ic fb-bezier Pq Ar x1 y1 x2 y2 x3 y3 width --
+Draws a quadratic Bezier curve in the current foreground color using the
+three provided points and specified line with.
+.It Ic fb-drawrect Pq Ar x1 y1 x2 y2 fill --
+Draws a rectangle to the screen with the top left at
+.Em (x1,y1)
+and the bottom right at
+.Em (x2,y2)
+, using the current foreground color.
+If
+.Em fill
+is
+.Ic true
+then the rectangle will be filled in.
+.It Ic fb-line Pq Ar x1 y1 x2 y2 width --
+Draws a line from
+.Em (x1,y1)
+to
+.Em (x2,y2)
+in the current foreground color and with the specified width.
+.It Ic fb-putimage Pq Ar flags x1 y1 x2 y2 addr len -- flag
+Outputs an image to the screen.
+Returns
+.Ic true
+if the image was able to be written and
+.Ic false
+otherwise.
+Only truecolor PNG images are supported and the path to the file
+must be provided through the
+.Em addr
+and
+.Em len
+arguments on the stack.
+The image will be displayed in the rectangular screen region with the top left
+at
+.Em (x1,y1)
+and the bottom right at
+.Em (x2,y2)
+.
+.Pp
+Either
+.Em x2
+or
+.Em y2
+can be set to "0" which causes it to be calculated to maintain the aspect
+ratio of the image.
+If both are "0" then the native resolution of the image will be used.
+.Pp
+If
+.Em x1
+is "0", then the image will be placed as far over to the right of the
+screen as possible.
+Similarly, if
+.Em y1
+is "0", then the image will be placed as far down the screen as possible.
+.Pp
+Flags is a bitfield; the following bits are defined:
+.Bl -tag -width XXXXX -offset indent
+.It 1
+Draw a single pixel border around the image in the current foreground color.
+.It 2
+Do not scroll the image with the rest of the screen.
+.It 128
+Output diagnostic information (for debugging).
+.El
+.It Ic fb-setpixel Pq Ar x y --
+Colors the pixel at
+.Em (x,y)
+with the current foreground color.
+.It Ic term-drawrect Pq Ar x1 y1 x2 y2 --
+Draws a rectangle with rounded corners using terminal coordinates and the
+current foreground color.
+.El
+.Ss Loader Defined Environmental Queries
+.Bl -tag -width Ds
+.It arch-i386
+.Ic TRUE
+if the architecture is IA32.
+.It loader_version
+.Nm
+version.
+.El
+.Ss Errors
+The following values are thrown by
+.Nm :
+.Bl -tag -width XXXXX -offset indent
+.It 100
+Any type of error in the processing of a builtin.
+.It -1
+.Ic Abort
+executed.
+.It -2
+.Ic Abort"
+executed.
+.It -56
+.Ic Quit
+executed.
+.It -256
+Out of interpreting text.
+.It -257
+Need more text to succeed -- will finish on next run.
+.It -258
+.Ic Bye
+executed.
+.It -259
+Unspecified error.
+.El
+.Sh FILES
+.Bl -tag -width /boot/defaults/loader.conf -compact
+.It Pa /boot/defaults/loader.conf
+.It Pa /boot/conf.d/*
+.It Pa /boot/loader.conf
+.It Pa /boot/loader.conf.local
+.Nm
+configuration files, as described in
+.Xr loader.conf 5 .
+.It Pa /boot/loader.help
+Loaded by
+.Ic help .
+Contains the help messages.
+.It Pa /boot/loader.rc
+.Nm
+bootstrapping script.
+.It Pa /boot/forth/loader.4th
+Extra builtin-like words.
+.It Pa /boot/forth/support.4th
+.Pa loader.conf
+processing words.
+.It Pa /boot/loader
+.Nm
+itself.
+.El
+.Sh EXAMPLES
+Boot in single user mode:
+.Pp
+.Dl boot -s
+.Pp
+Load the kernel, a boot_archive, and then autoboot in five seconds.
+Notice that a kernel must be loaded before any other
+.Ic load
+command is attempted.
+.Bd -literal -offset indent
+load /platform/i86pc/kernel/amd64/unix
+load -t rootfs /platform/i86pc/amd64/boot_archive
+autoboot 5
+.Ed
+.Pp
+Set the default device used for loading a kernel from a ZFS filesystem:
+.Bd -literal -offset indent
+set currdev=zfs:rpool/ROOT/knowngood:
+.Ed
+.Sh NOTES
+Although setting the
+.Va currdev
+as shown in the example above is supported, it is advisable to use loader
+beadm command or boot environment menu instead.
+The reason is, the beadm or menu selection will also instruct loader to clean up
+the currently set configuration and load configuration from the new boot
+environment.
+.Sh SEE ALSO
+.Xr btxld 1onbld ,
+.Xr loader.conf 5 ,
+.Xr boot 8
+.Sh STANDARDS
+For the purposes of ANS Forth compliance, loader is an
+.Bf Em
+ANS Forth System with Environmental Restrictions, Providing
+.Ef
+.Bf Li
+.No .( ,
+.No :noname ,
+.No ?do ,
+parse, pick, roll, refill, to, value, \e, false, true,
+.No <> ,
+.No 0<> ,
+compile\&, , erase, nip, tuck
+.Ef
+.Em and
+.Li marker
+.Bf Em
+from the Core Extensions word set, Providing the Exception Extensions
+word set, Providing the Locals Extensions word set, Providing the
+Memory-Allocation Extensions word set, Providing
+.Ef
+.Bf Li
+\&.s,
+bye, forget, see, words,
+\&[if],
+\&[else]
+.Ef
+.Em and
+.Li [then]
+.Bf Em
+from the Programming-Tools extension word set, Providing the
+Search-Order extensions word set.
+.Ef