[src/trunk]: src Add a boothowto(9) man page, and link it to BOOT_FLAGS(9).

[apb <apb%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/993c3ee18baf
branches:  trunk
changeset: 747178:993c3ee18baf
user:      apb <apb%NetBSD.org@localhost>
date:      Fri Sep 04 23:23:04 2009 +0000

description:
Add a boothowto(9) man page, and link it to BOOT_FLAGS(9).

diffstat:

 distrib/sets/lists/comp/mi |    4 +-
 share/man/man9/Makefile    |    5 +-
 share/man/man9/boothowto.9 |  276 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 283 insertions(+), 2 deletions(-)

diffs (truncated from 324 to 300 lines):

diff -r e2e7d2a36017 -r 993c3ee18baf distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Fri Sep 04 20:19:04 2009 +0000
+++ b/distrib/sets/lists/comp/mi        Fri Sep 04 23:23:04 2009 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1300 2009/09/04 17:21:34 pooka Exp $
+#      $NetBSD: mi,v 1.1301 2009/09/04 23:23:05 apb Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -19055,6 +19055,7 @@
 ./usr/share/man/man8/cvsbug.8                  comp-cvs-man            cvs,.man
 ./usr/share/man/man8/genassym.8                        comp-obsolete           obsolete
 ./usr/share/man/man8/kgmon.8                   comp-sysutil-man        .man
+./usr/share/man/man9/BOOT_FLAGS.9              comp-sys-man            .man
 ./usr/share/man/man9/CALLOUT_INITIALIZER.9     comp-obsolete           obsolete
 ./usr/share/man/man9/CALLOUT_INITIALIZER_SETFUNC.9     comp-obsolete           obsolete
 ./usr/share/man/man9/CARDBUS_PRODUCT.9         comp-sys-man            .man
@@ -19233,6 +19234,7 @@
 ./usr/share/man/man9/biowait.9                 comp-sys-man            .man
 ./usr/share/man/man9/bitmask_snprintf.9                comp-obsolete           obsolete
 ./usr/share/man/man9/bluetooth.9               comp-sys-man            .man
+./usr/share/man/man9/boothowto.9               comp-sys-man            .man
 ./usr/share/man/man9/boottime.9                        comp-sys-man            .man
 ./usr/share/man/man9/bounds_check_with_label.9 comp-sys-man            .man
 ./usr/share/man/man9/bread.9                   comp-sys-man            .man
diff -r e2e7d2a36017 -r 993c3ee18baf share/man/man9/Makefile
--- a/share/man/man9/Makefile   Fri Sep 04 20:19:04 2009 +0000
+++ b/share/man/man9/Makefile   Fri Sep 04 23:23:04 2009 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.288 2009/08/03 23:15:29 rmind Exp $
+#       $NetBSD: Makefile,v 1.289 2009/09/04 23:23:04 apb Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -57,6 +57,9 @@
        wdc.9 workqueue.9 \
        wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9
 
+MAN+=  boothowto.9
+MLINKS+=boothowto.9 BOOT_FLAGS.9
+
 MAN+=  dmover.9
 MLINKS+=dmover.9 dmover_backend_register.9 \
        dmover.9 dmover_backend_unregister.9 \
diff -r e2e7d2a36017 -r 993c3ee18baf share/man/man9/boothowto.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/boothowto.9        Fri Sep 04 23:23:04 2009 +0000
@@ -0,0 +1,276 @@
+.\"    $NetBSD: boothowto.9,v 1.1 2009/09/04 23:23:05 apb Exp $
+.\"
+.\" Copyright (c) 2009 The NetBSD Foundation, Inc.
+.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 September 4, 2009
+.Dt BOOTHOWTO 9
+.Os
+.Sh NAME
+.Nm boothowto ,
+.Nm BOOT_FLAG
+.Nd flags passed to kernel during boot or shutdown
+.Sh SYNOPSIS
+.In sys/reboot.h
+.In sys/systm.h
+.Vt extern int boothowto
+.In sys/boot_flag.h
+.Vt #define BOOT_FLAG(arg, retval) ...
+.Sh DESCRIPTION
+The
+.Va boothowto
+variable contains flags passed to the kernel by the boot loader (see
+.Xr boot 8 ) ,
+or the
+.Xr reboot 2
+system call.
+The value is interpreted as a bit mask, with bits defined by the
+.Dq Sy RB_ Ns No *
+and
+.Dq Sy AB_ Ns No *
+symbols in
+.In sys/reboot.h .
+.Pp
+The
+.Sy BOOT_FLAG
+macro defined in
+.In sys/boot_flag.h
+is used by many boot loaders to convert command line options
+into
+.Va boothowto
+flags.
+Note that not all boot loaders use this macro, and some boot loaders
+may have incompatible options.
+.Pp
+Where possible, flags set by the
+.Xr reboot 2
+system call will be passed to the new kernel after a reboot;
+the extent to which this is possible is machine dependent.
+.Pp
+In the following tables,
+each flag is listed with
+its symbolic name,
+the corresponding numeric value defined in
+.In sys/reboot.h ,
+and the option letter (if any) understood by the
+.Sy BOOT_FLAG
+macro.
+.
+.Ss Flags that affect booting or shutting down
+The following flags affect actions taken during system boot
+or shutdown.
+.Bl -column RB_INITNAMEA 0x00000000 \&-x
+.It Dv RB_AUTOBOOT Ta Li 0 Ta Ta
+The default if no other flags are set.
+Causes the system to boot in the normal way.
+.It Dv RB_ASKNAME Ta Li 0x00000001 Ta Fl a Ta
+This flag causes various parts of the system to prompt:
+.Bl -bullet -compact
+.It
+The boot loader may prompt for the name or location of the
+kernel to be booted.
+.It
+The kernel will prompt for the root file system device.
+.It
+The kernel will prompt for the root file system type.
+.It
+The kernel will prompt for the location of the dump device.
+.It
+The kernel will prompt for the path to the
+.Xr init 8
+program.
+.El
+Some subsystems set this flag when they are unable to automatically
+make a decision.
+.It Dv RB_SINGLE Ta Li 0x00000002 Ta Fl s Ta
+Boot in single-user mode.
+If this flag is set, the kernel passes the
+.Fl s
+option to
+.Xr init 8 .
+.It Dv RB_NOSYNC Ta Li 0x00000004 Ta Ta
+If this flag is set, then some parts of the shutdown process will
+be less graceful than usual:
+.Bl -bullet -compact
+.It
+Disks will not be synced
+(see
+.Xr sync 2
+and
+.Xr cpu_reboot 9 ) .
+.It
+Devices will not be detached (see
+.Xr autoconfig 9 ) .
+.\" actually, see config_detach_all, but that is undocumented
+.It
+File systems will not be unmounted (see
+.Xr cpu_reboot 9 ,
+and
+.Xr vfs_shutdown 9 ) .
+.It
+The time of day clock will not be set (see
+.Xr resettodr 9 ) .
+.El
+.It Dv RB_HALT Ta Li 0x00000008 Ta Fl b Ta
+If this flag is set, then
+.Xr reboot 2
+will cause the system to halt instead of rebooting.
+This flag may be set at boot time, and cannot be cleared by
+.Xr reboot 2 .
+.It Dv RB_INITNAME Ta Li 0x00000010 Ta Ta
+This flag is obsolete.
+It was previously used to cause the kernel to prompt for the name of the
+.Xr init 8
+program, but that function is now controlled by the
+.Dv RB_ASKNAME
+flag.
+.It Dv RB_KDB Ta Li 0x00000040 Ta Fl d Ta
+Gives control to a kernel debugger early in the boot sequence.
+See
+.Xr ddb 4 ,
+.Xs "options KGDB"
+in
+.Xr options 7 ,
+.\" the kgdb_* functions are undocumented
+and
+.Xr ipkdb 9 .
+.It Dv RB_RDONLY Ta Li 0x00000080 Ta Ta
+This flag is deprecated.
+It previously caused the kernel to mount the root file system
+in read-only mode, but now that is the default, and this flag
+has no effect.
+.It Dv RB_DUMP Ta Li 0x00000100 Ta Ta
+Causes the kernel to dump memory to the dump device during shutdown.
+See
+.Xr savecore 8 ,
+.Xr cpu_reboot 9 ,
+and
+.Xr dumpsys 9 .
+.It Dv RB_MINIROOT Ta Li 0x00000200 Ta Fl m Ta
+This flag informs the kernel that a mini-root file system is present
+in memory.
+See
+.Xr md 4 ,
+and
+.Xr mdsetimage 8 .
+.It Dv RB_STRING Ta Li 0x00000400 Ta Ta
+This flag indicates that a boot string is present.
+The string may be provided by
+.Xr reboot 2
+and will be passed to the boot loader if possible.
+.It Dv RB_POWERDOWN Ta Li (RB_HALT|0x800) Ta Ta
+This flag is used in conjunction with
+.Dv RB_HALT .
+If this flag is set, then then system will be powered down if possible.
+If powerdown is not supported, then the system will halt.
+.It Dv RB_USERCONF Ta Li 0x00001000 Ta Fl c Ta
+This flag causes the kernel to invoke the
+.Xr userconf 4
+device configuration manager early in the boot sequence.
+.El
+.
+.Ss Flags that affect verbosity
+The following flags affect the verbosity of messages printed by the kernel.
+These flags are used by several functions described in
+.Xr kprintf 9
+to control whether output is sent to the console, the system log,
+.\" the /dev/log device driver is undocumented
+both, or neither.
+The use of flags that increase verbosity simultaneously with
+the use of flags that decrease verbosity,
+is not well defined.
+.Bl -column RB_INITNAMEA 0x00000000 \&-x
+.It Dv AB_NORMAL Ta Li 0 Ta Ta
+The default, if none of the other
+.Dv AB_*
+flags is set, is that ordinary kernel messages are sent
+both to the console and to the system log.
+.It Dv AB_QUIET Ta Li 0x00010000 Ta Fl q Ta
+Boot quietly.
+Ordinary kernel messages are sent to the system log,
+but not to the console.
+Messages printed with
+.Xr aprint_naive 9
+are sent to the console, but not to the system log.
+.It Dv AB_VERBOSE Ta Li 0x00020000 Ta Fl v Ta
+Boot verbosely.
+Some messages will be printed that would otherwise not be printed.
+Both ordinary kernel messages, and messages printed with
+.Xr aprint_verbose 9 ,
+will be sent both to the console and to the system log.
+If this flag is not set, then messages printed with
+.Xr aprint_verbose 9
+will be sent only to the system log.
+.It Dv AB_SILENT Ta Li 0x00040000 Ta Fl z Ta
+Boot silently.
+Most kernel messages will be sent only to the system log, not to the console.
+The
+.Fn aprint_*
+functions display a spinning symbol on the console.
+.It Dv AB_DEBUG Ta Li 0x00080000 Ta Fl x Ta
+Boot with debug messages.
+.El
+.
+.Ss Machine-dependent flags
+The following flags have machine-dependent meanings.
+.Bl -column RB_INITNAMEA 0x00000000 \&-x
+.It Dv RB_MD1 Ta Li 0x10000000 Ta Fl 1 Ta
+Some ports use this flag to disable multiprocessor mode,
+making them use only a single CPU.
+The zaurus port uses this flag to enable the serial console.
+.It Dv RB_MD2 Ta Li 0x20000000 Ta Fl 2 Ta
+The i386 and amd64 ports use this flag to disable
+.Xr acpi 4 .
+.It Dv RB_MD3 Ta Li 0x40000000 Ta Fl 3 Ta
+This flag is currently not used by any ports.
+.It Dv RB_MD4 Ta Li 0x80000000 Ta Fl 4 Ta
+This flag is currently not used by any ports.
+.El
+.
+.Sh SEE ALSO
+.Xr reboot 2 ,       \" sets boothowto