[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Attempt 2 at a documentation patch
|
From: |
James A Morrison |
|
Subject: |
Attempt 2 at a documentation patch |
|
Date: |
Tue, 29 Jan 2002 19:57:30 -0500 (EST) |
I've tried to fill in some gaps I found and reword some sections that
indicated they needed rewording.
Comments?
2002-01-29 James A. Morrison <ja2morri@student.math.uwaterloo.ca>
* hurd.texi (Invoking boot): Added Invoking boot section.
(showtrans): Added command line options
(fsysopts): Added command line options
Index: hurd.texi
===================================================================
RCS file: /cvsroot/hurd/hurd/doc/hurd.texi,v
retrieving revision 1.20
diff -u -r1.20 hurd.texi
--- hurd.texi 12 Mar 2001 00:43:50 -0000 1.20
+++ hurd.texi 30 Jan 2002 00:43:49 -0000
@@ -98,7 +98,7 @@
@end direntry
@ifinfo
-Copyright @copyright{} 1994-2000 Free Software Foundation, Inc.
+Copyright @copyright{} 1994-2002 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -131,7 +131,7 @@
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1994--2000 Free Software Foundation, Inc.
+Copyright @copyright{} 1994--2002 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -170,6 +170,7 @@
* Terminal Handling:: Helping people interact with the Hurd.
* Running Programs:: Program execution and process management.
* Authentication:: Verifying user and server privileges.
+* Invoking boot:: How to use the boot program.
* Index:: Guide to concepts, functions, and files.
@detailmenu
@@ -337,6 +338,10 @@
* Auth Protocol:: Bidirectional authentication.
+Invoking boot
+
+* boot Options:: Command line options for the boot program.
+
@end detailmenu
@end menu
@@ -666,12 +671,12 @@
@cindex GRUB
@cindex GRand Unified Bootloader
Currently, @dfn{GRUB}@footnote{The GRand Unified Bootloader, available
-from @uref{http://www.uruk.org/grub/}.} is the preferred GNU bootloader.
-GRUB provides advanced functionality, and is capable of loading several
+from @uref{http://www.gnu.org/software/grub/}.} is the GNU bootloader.
+GNU GRUB provides advanced functionality, and is capable of loading several
different kernels (such as Linux, DOS, and the *BSD family).
From the standpoint of the Hurd, the bootloader is just a mechanism to
-get the microkernel running and transfer control to @code{serverboot}.
+get the microkernel running and transfer control to the Hurd servers.
You will need to refer to your bootloader and microkernel documentation
for more information about the details of this process.
@@ -680,12 +685,16 @@
@section Server Bootstrap
@pindex serverboot
+The @code{serverboot} program has been deprecated but it is still possible
+to boot the Hurd using @code{serverboot} instead of booting the Hurd directly.
+
The @code{serverboot} program is responsible for loading and executing
the rest of the Hurd servers. Rather than containing specific
instructions for starting the Hurd, it follows general steps given in a
user-supplied boot script.
-To boot the Hurd, the microkernel must start @code{serverboot} as its
+To boot the Hurd using @code{serverboot}, the microkernel must start
+@code{serverboot} as its
first task, and pass it appropriate arguments. @code{serverboot} has a
counterpart, called @code{boot}, which can be invoked while the Hurd is
already running, and allows users to start their own complete sub-Hurds
@@ -744,6 +753,11 @@
@pindex /boot/servers.boot
@pindex servers.boot
+Boot Scripts are used to boot sub-hurds, and parsed by @code{serverboot} to
+boot the Hurd. Boot scripts are simply a selection of command lines using
+@code{#}'s to denote comments. See @file{/boot/servers.boot} for an example
+of a Hurd boot script.
+
FIXME: finish
@@ -762,6 +776,9 @@
far-reaching effects, and so it is nice to be able to test those effects
without having to reboot the machine.
+This feature can also be used to test another Hurd installation. This
+situation is illustrated in the second example.
+
@c FIXME: `boot' synopsis
Here are the steps you can follow to test out a new set of servers:
@@ -810,7 +827,7 @@
$ @kbd{cd my-root}
$ @kbd{tar -zxpf /pub/debian/FIXME/gnu-20000929.tar.gz}
$ @kbd{cd ..}
-$ @kbd{fsysopts ./my-root --read-only}
+$ @kbd{fsysopts ./my-root --readonly}
$
@end example
@@ -824,6 +841,19 @@
$ @kbd{boot -D ./my-boot ./my-boot/boot/servers.boot ./my-partition}
[...]
@end example
+
+@item
+ Here is an example using a hard drive that already has GNU Hurd installed.
+Assuming that the Hurd is installed on and extended 2 filesystem on /dev/hd2s1.
+
+@example
+$ @kbd{settrans /mnt /hurd/ex2fs --readonly /dev/hd2s1}
+$ @kbd{boot -d -D /mnt -I /mnt/boot/servers.boot /dev/hd2s1}
+@end example
+
+@item
+ See @pxref{boot Options} for help with boot.
+
@end enumerate
Note that it is impossible to share microkernel devices between the two
@@ -2008,10 +2038,10 @@
@item
@c FIXME: reword
-Hurd servers which translate rendezvous filesystem nodes in standard
-locations, so that other programs can easily find them and use
+Hurd servers which translate special filesystem nodes in standard
+locations, so that other programs can easily find them. Then use the
server-specific interfaces. For example, @code{pflocal} implements the
-filesystem interfaces, but it also provides a special Unix-domain socket
+standard filesystem interfaces, and it provides a special Unix-domain socket
RPC interface (FIXME xref). Programs can fetch a port to this
translator simply by calling @code{file_name_lookup} (FIXME xref) on
@file{/servers/socket/1}@footnote{The number 1 corresponds to the
@@ -2139,11 +2169,97 @@
FIXME: finish
@node Invoking showtrans
@subsection Invoking @code{showtrans}
+
+The @code{showtrans} program allows you to the passive translator(s) on a file
+or directory.
+
+The @code{showtrans} program has the following synopsis:
+
+@example
+showtrans [@var{option}]@dots{} @var{FILE}@dots{}
+@end example
+
+@code{showtrans} accepts the following options:
+
+@table @code
+@item -p
+@itemx --prefix
+Always display @var{FILENAME: } before translators
+
+@item -P
+@itemx --no-prefix
+Never display @var{FILENAME: } before translators
+@item -s
+@itemx --silent
+No output; useful when checking error status
+@item -t
+@itemx --translated
+Only display files that have translators
+
+@item -?
+@itemx --help
+Give a helpful list of options
+
+@item --usage
+Give a short usage message
+
+@item -V
+@itemx --version
+Print program version
+
+@end table
@node Invoking mount
@subsection Invoking @code{mount}
@node Invoking fsysopts
@subsection Invoking @code{fsysopts}
+The @code{fsysopts} program allows you to get or set command line options for
+running translator @var{FILESYS}.
+
+The @code{fsysopts} program has the following synopsis:
+
+@example
+fsysopts [@var{OPTION}@dots{}] @var{FILESYS} [@var{FS_OPTION}@dots{}]
+@end example
+
+@code{fsysopts} accepts the following options:
+
+@table @code
+
+@item -L
+@itemx --dereference
+If @var{FILESYS} is a symbolic link, follow it
+
+@item -R
+@itemx --recursive
+Pass these options to any child translators
+
+@item -?
+@itemx --help
+Gives a help list
+
+@item --usage
+Give a short usage message
+
+@item -V
+@itemx --version
+Print program version
+
+@end table
+The legal values for @var{FS_OPTION} depends on @var{FILESYS}, but some
+common ones are:
+
+@table @code
+
+@item --readonly
+@item --writable
+@item --remount
+@item --sync[=@var{INTERVAL}]
+@item --nosync
+
+@end table
+
+If no options are supplied, @var{FILESYS}'s existing options are printed
@node Trivfs Library
@section Trivfs Library
@@ -2208,7 +2324,9 @@
control structure (and advertise its port) with @code{trivfs_startup}:
@deftypefun error_t trivfs_startup (@w{mach_port_t @var{bootstrap}}, @w{int
@var{flags}}, @w{struct port_class *@var{control_class}}, @w{struct port_bucket
*@var{control_bucket}}, @w{struct port_class *@var{protid_class}}, @w{struct
port_bucket *@var{protid_bucket}}, @w{struct trivfs_control **@var{control}})
+
@deftypefunx error_t trivfs_create_control (@w{mach_port_t @var{bootstrap}},
@w{struct port_class *@var{control_class}}, @w{struct port_bucket
*@var{control_bucket}}, @w{struct port_class *@var{protid_class}}, @w{struct
port_bucket *@var{protid_bucket}}, @w{struct trivfs_control **@var{control}})
+
@code{trivfs_startup} creates a new trivfs control port, advertises it
to the underlying node @var{bootstrap} with @code{fsys_startup},
returning the results of this call, and places its control structure in
@@ -2245,7 +2363,9 @@
message-handling over to @code{trivfs_demuxer} and @code{libports}:
@deftypefun {struct trivfs_control *} trivfs_begin_using_control
(@w{mach_port_t @var{port}})
+
@deftypefunx {struct trivfs_protid *} trivfs_begin_using_protid
(@w{mach_port_t @var{port}})
+
These functions can be used as @code{intran} functions for a MiG port
type to have the stubs called with either the control or protid pointer.
@end deftypefun
@@ -2255,12 +2375,15 @@
@c tb: `intran' is a keyword in MiG.
@deftypefun void trivfs_end_using_control (@w{struct trivfs_control
*@var{port}})
+
@deftypefunx void trivfs_end_using_protid (@w{struct trivfs_protid
*@var{port}})
+
These can be used as `destructor' functions for a MiG port type, to have
the stubs called with the control or protid pointer.
@end deftypefun
@deftypefun error_t trivfs_open (@w{struct trivfs_control *@var{fsys}},
@w{struct iouser *@var{user}}, @w{unsigned @var{flags}}, @w{mach_port_t
@var{realnode}}, @w{struct trivfs_protid **@var{cred}})
+
Return a new protid (that is, a port representing an open of this node)
pointing to a new peropen in @var{cred}, with @var{realnode} as the
underlying node reference, with the given identity, and open flags in
@@ -2268,6 +2391,7 @@
@end deftypefun
@deftypefun error_t trivfs_protid_dup (@w{struct trivfs_protid *@var{cred}},
@w{struct trivfs_protid **@var{dup}})
+
Return a duplicate of @var{cred} in @var{dup}, sharing the same peropen
and hook. A non-null protid @var{hook} indicates that
@var{trivfs_peropen_create_hook} created this protid (@pxref{Trivfs
@@ -2275,6 +2399,7 @@
@end deftypefun
@deftypefun error_t trivfs_set_atime (@w{struct trivfs_control *@var{cntl}})
+
@deftypefunx error_t trivfs_set_mtime (@w{struct trivfs_control *@var{cntl}})
Call these to set atime or mtime for the node to the current time.
@end deftypefun
@@ -2289,33 +2414,41 @@
and functions:
@deftypevar {extern int} trivfs_fstype
+
@deftypevarx {extern int} trivfs_fsid
+
These variables are returned in the @var{st_fstype} and @var{st_fsid}
fields of @code{struct stat}. @var{trivfs_fstype} should be chosen
from the @code{FSTYPE_*} constants found in @code{<hurd/hurd_types.h>}.
@end deftypevar
@deftypevar {extern int} trivfs_allow_open
+
Set this to some bitwise OR combination of @code{O_READ},
@code{O_WRITE}, and @code{O_EXEC}; trivfs will only allow opens of the
specified modes.
@end deftypevar
@deftypevar {extern int} trivfs_support_read
+
@deftypevarx {extern int} trivfs_support_write
+
@deftypevarx {extern int} trivfs_support_exec
+
Set these to nonzero if trivfs should allow read, write, or execute of
the file. These variables are necessary because @var{trivfs_allow_open}
is used only to validate opens, not actual operations.
@end deftypevar
@deftypefun void trivfs_modify_stat (@w{struct trivfs_protid *@var{cred}},
@w{struct stat *@var{stbuf}})
+
This should modify a @code{struct stat} (as returned from the underlying
node) for presentation to callers of @code{io_stat}. It is permissible
for this function to do nothing, but it must still be defined.
@end deftypefun
@deftypefun error_t trivfs_goaway (@w{struct trivfs_control *@var{cntl}},
@w{int @var{flags}})
+
This function is called when someone wants the filesystem @var{cntl} to
go away. @var{flags} are from the set @code{FSYS_GOAWAY_*} found in
@code{<hurd/hurd_types.h>}.
@@ -2329,10 +2462,14 @@
default definitions in @code{libtrivfs}, so you are not forced to define
them; rather, they may be redefined on a case-by-case basis.
-@deftypevar {extern struct port_class *} trivfs_protid_portclasses[]
+@deftypevar {extern struct port_class *} trivfs_protid_portclasses []
+
@deftypevarx {extern int} trivfs_protid_nportclasses
-@deftypevarx {extern struct port_class *} trivfs_cntl_portclasses[]
+
+@deftypevarx {extern struct port_class *} trivfs_cntl_portclasses []
+
@deftypevarx {extern int} trivfs_cntl_nportclasses
+
If you define these, they should be vectors (and the associated sizes)
of port classes that will be translated into control and protid pointers
for passing to RPCs, in addition to those passed to or created by
@@ -2341,6 +2478,7 @@
@end deftypevar
@deftypefn {Variable} {error_t (*} trivfs_check_open_hook ) (@w{struct
trivfs_control *@var{cntl}}, @w{struct iouser *@var{user}}, @w{int @var{flags}})
+
If this variable is non-zero, it will be called every time an open happens.
@var{user} and @var{flags} are from the open; @var{cntl} identifies the
node being opened. This call need not check permissions on the
@@ -2351,18 +2489,23 @@
@end deftypefn
@deftypefn {Variable} {error_t (*} trivfs_protid_create_hook ) (@w{struct
trivfs_protid *@var{prot}})
+
@deftypefnx {Variable} {error_t (*} trivfs_peropen_create_hook ) (@w{struct
trivfs_peropen *@var{perop}})
+
If these variables are non-zero, they will be called every time a new protid or
peropen structure is created and initialized.
@end deftypefn
@deftypefn {Variable} {void (*} trivfs_protid_destroy_hook ) (@w{struct
trivfs_protid *@var{prot}})
+
@deftypefnx {Variable} {void (*} trivfs_peropen_destroy_hook ) (@w{struct
trivfs_peropen *@var{perop}})
+
If these variables is non-zero, they will be called every time a protid or
peropen structure is about to be destroyed.
@end deftypefn
@deftypefn {Variable} {error_t (*} trivfs_getroot_hook ) (@w{struct
trivfs_control *@var{cntl}}, @w{mach_port_t @var{reply_port}},
@w{mach_msg_type_name_t @var{reply_port_type}}, @w{mach_port_t @var{dotdot}},
@w{uid_t *@var{uids}}, @w{u_int @var{nuids}}, @w{uid_t *@var{gids}}, @w{u_int
@var{ngids}}, @w{int @var{flags}}, @w{retry_type *@var{do_retry}}, @w{char
*@var{retry_name}}, @w{mach_port_t *@var{node}}, @w{mach_msg_type_name_t
*@var{node_type}})
+
If this variable is set, it will be called by @code{trivfs_S_fsys_getroot}
before any other processing takes place. If the return value is
@code{EAGAIN}, normal trivfs getroot processing continues, otherwise the
@@ -2377,10 +2520,12 @@
following functions may come in handy:
@deftypefun error_t trivfs_add_port_bucket (@w{struct port_bucket
**@var{bucket}})
+
Add the port bucket @code{*@var{bucket}} to the list of dynamically-
allocated port buckets; if @code{*@var{bucket}} is zero, an attempt is
made to allocate a new port bucket, which is then stored in
@code{*@var{bucket}}.
+
@c FIXME: what if the allocation attempt fails?
@c tb: then an appropriate error (ENOMEM in this case) is returned.
@c tb: Users are not supposed to assume they know all the possible error
@@ -2388,19 +2533,24 @@
@end deftypefun
@deftypefun void trivfs_remove_port_bucket (@w{struct port_bucket
*@var{bucket}})
+
Remove the previously added dynamic port bucket @var{bucket}, freeing it
if it was allocated by @code{trivfs_add_port_bucket}.
@end deftypefun
@deftypefun error_t trivfs_add_control_port_class (@w{struct port_class
**@var{class}})
+
@deftypefunx error_t trivfs_add_protid_port_class (@w{struct port_class
**@var{class}})
+
Add the port class @code{*@var{class}} to the list of control or protid port
classes recognized by trivfs; if @code{*@var{class}} is zero, an attempt is
made to allocate a new port class, which is stored in @code{*@var{class}}.
@end deftypefun
@deftypefun void trivfs_remove_control_port_class (@w{struct port_class
*@var{class}})
+
@deftypefunx void trivfs_remove_protid_port_class (@w{struct port_class
*@var{class}})
+
Remove the previously added dynamic control or protid port class
@var{class}, freeing it if it was allocated by
@code{trivfs_add_control_port_class} or
@@ -2411,7 +2561,9 @@
able to use the default trivfs cleanroutines:
@deftypefun void trivfs_clean_cntl (@w{void *@var{port}})
+
@deftypefunx void trivfs_clean_protid (@w{void *@var{port}})
+
These functions should be installed as @code{libports} cleanroutines for
control port classes and protid port classes, respectively.
@end deftypefun
@@ -3137,7 +3289,7 @@
The store library comes with a number of standard store class
implementations:
-@deftypevar {extern const struct store_class *const} store_std_classes[]
+@deftypevar {extern const struct store_class *const} store_std_classes []
This is a null-terminated vector of the standard store classes
implemented by @code{libstore}.
@end deftypevar
@@ -4606,6 +4758,63 @@
FIXME: finish
+@node Invoking boot
+@chapter Invoking boot
+@menu
+* boot Options:: Boot program command line options
+@end menu
+
+@node boot Options
+@section boot Options
+
+Usage: boot [OPTION...] @var{BOOT-SCRIPT} @var{DEVICE}...
+
+@table @code
+@item --kernel-command-line=@var{COMMAND LINE}
+@itemx -c
+Simulated multiboot command line to supply
+
+@item --pause
+@itemx -d
+Pause for user confirmation at various times during booting
+
+@item --boot-root=@var{DIR}
+@itemx -D
+Root of a directory tree in which to find files specified in @var{BOOT-SCRIPT}
+
+@item --interleave=@var{BLOCKS}
+Interleave in runs of length @var{BLOCKS}
+
+@item --isig
+@itemx -I
+Do not disable terminal signals, so you can suspend and interrupt boot.
+
+@item --layer
+@itemx -L
+ Layer multiple devices for redundancy
+
+@item --single-user
+@itemx -s
+ Boot in single user mode
+
+@item --store-type=@var{TYPE}
+@itemx -T
+Each @var{DEVICE} names a store of type @var{TYPE}
+
+@item --help
+@itemx -?
+Gives a help list
+
+@item --usage
+Give a short usage message
+@end table
+
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+
+
+If neither @option{--interleave} or @option{--layer} is specified, multiple
+@var{DEVICE}s are concatenated.
@node Index
@unnumbered Index
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- Attempt 2 at a documentation patch,
James A Morrison <=