Consistently use /:/boot:/modules as search path in the loader, the kernel
[dragonfly.git] / sys / boot / forth / loader.4th.8
1 .\" Copyright (c) 1999 Daniel C. Sobral
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD: src/sys/boot/forth/loader.4th.8,v 1.14 2002/08/13 15:09:33 ru Exp $
26 .\" $DragonFly: src/sys/boot/forth/loader.4th.8,v 1.4 2004/12/20 13:13:19 joerg Exp $
27 .\"
28 .Dd April 25, 1999
29 .Dt LOADER.4TH 8
30 .Os
31 .Sh NAME
32 .Nm loader.4th
33 .Nd loader.conf processing tools
34 .Sh DESCRIPTION
35 The file that goes by the name of
36 .Nm
37 is a set of commands designed to manipulate
38 .Xr loader.conf 5
39 files.
40 The default
41 .Pa /boot/loader.rc
42 includes
43 .Nm
44 and uses one of its commands to automatically read and process
45 the standard
46 .Xr loader.conf 5
47 files.
48 Other commands exists to help the user specify alternate
49 configurations.
50 .Pp
51 The commands of
52 .Nm
53 by themselves are not enough for most uses.
54 Please refer to the
55 examples below for the most common situations, and to
56 .Xr loader 8
57 for additional commands.
58 .Pp
59 Before using any of the commands provided in
60 .Nm ,
61 it must be included
62 through the command:
63 .Pp
64 .Dl include loader.4th
65 .Pp
66 This line is present in the default
67 .Pa /boot/loader.rc
68 file, so it isn't needed (and should not be re-issued) in a normal setup.
69 .Pp
70 The commands provided by it are:
71 .Bl -tag -width disable-module_module -compact -offset indent
72 .It Ic boot
73 .It Ic boot Ar kernelname Op Cm ...
74 .It Ic boot Ar directory Op Cm ...
75 .It Ic boot Fl flag Cm ...
76 Boot as specified by the
77 .Xr loader.conf 5
78 files read.
79 .Pp
80 Depending on the arguments passed, it can override boot flags and
81 either the kernel name or the search path for kernel and modules.
82 .Pp
83 .It Ic boot-conf
84 .It Ic boot-conf Ar kernelname Op Cm ...
85 .It Ic boot-conf Ar directory Op Cm ...
86 .It Ic boot-conf Fl flag Cm ...
87 Works like
88 .Ic boot
89 described above, but instead of booting immediately, uses
90 .Ic autoboot ,
91 so it can be stopped.
92 .Pp
93 .It Ic start
94 Reads
95 .Pa /boot/defaults/loader.conf ,
96 all other
97 .Xr loader.conf 5
98 files specified in it, and then proceeds to boot as specified in them.
99 This
100 is the command used in the default
101 .Pa /boot/loader.rc
102 file, and it uses the
103 .Pa autoboot
104 command (see
105 .Xr loader 8 ) ,
106 so it can be stopped for further interaction with
107 .Xr loader 8 .
108 .Pp
109 .It Ic initialize
110 Initialize the supporting library so commands can be used without
111 executing
112 .Ic start
113 first.
114 Like
115 .Ic start ,
116 reads
117 .Pa /boot/defaults/loader.conf
118 and all other
119 .Xr loader.conf 5
120 files specified in it.
121 Returns a flag on the stack to indicate
122 if any configuration file was successfully loaded.
123 .Pp
124 .It Ic read-conf Ar filename
125 Reads and processes a
126 .Xr loader.conf 5
127 file.
128 Does not proceed to boot.
129 .Pp
130 .It Ic enable-module Ar module
131 Enables the loading of
132 .Ar module .
133 .Pp
134 .It Ic disable-module Ar module
135 Disables the loading of
136 .Ar module .
137 .Pp
138 .It Ic toggle-module Ar module
139 Toggles the loading of
140 .Ar module
141 on and off.
142 .Pp
143 .It Ic show-module Ar module
144 Shows the information gathered in the
145 .Xr loader.conf 5
146 files about the module
147 .Ar module .
148 .Pp
149 .It Ic retry
150 Used inside
151 .Xr loader.conf 5
152 files to specify the action after a module loading fails.
153 .Pp
154 .It Ic ignore
155 Used inside
156 .Xr loader.conf 5
157 files to specify the action after a module loading fails.
158 .El
159 .Sh FILES
160 .Bl -tag -width /boot/loader.4th -compact
161 .It Pa /boot/loader
162 The
163 .Xr loader 8 .
164 .It Pa /boot/loader.4th
165 .Nm
166 itself.
167 .It Pa /boot/loader.rc
168 .Xr loader 8
169 bootstrapping script.
170 .It Pa /boot/defaults/loader.conf
171 File loaded by the
172 .Ic start
173 command.
174 .El
175 .Sh EXAMPLES
176 Standard
177 .Pa /boot/loader.rc :
178 .Pp
179 .Bd -literal -offset indent -compact
180 include /boot/loader.4th
181 start
182 .Ed
183 .Pp
184 Load a different kernel with the standard configuration:
185 .Pp
186 .Bd -literal -offset indent -compact
187 set kernel="/kernel.old"
188 unload
189 boot-conf
190 .Ed
191 .Pp
192 Read an additional configuration file and then proceed to boot:
193 .Pp
194 .Bd -literal -offset indent -compact
195 unload
196 read-conf /boot/special.conf
197 boot-conf
198 .Ed
199 .Pp
200 Disable the loading of the splash screen module and bitmap and then
201 proceed to boot:
202 .Pp
203 .Bd -literal -offset indent -compact
204 unload
205 disable-module splash_bmp
206 disable-module bitmap
207 boot-conf
208 .Ed
209 .Sh SEE ALSO
210 .Xr loader.conf 5 ,
211 .Xr loader 8
212 .Sh HISTORY
213 The
214 .Nm
215 set of commands first appeared in
216 .Fx 3.2 .
217 .Sh AUTHORS
218 The
219 .Nm
220 set of commands was written by
221 .An Daniel C. Sobral Aq dcs@FreeBSD.org .
222 .Sh BUGS
223 A British espionage series.