add start of a crash page

1 files changed, 144 insertions, 0 deletions

diff --git a/share/man/man8/crash.8 b/share/man/man8/crash.8
new file mode 100644
index 00000000000..e1b98b02a50
--- /dev/null
+++ b/share/man/man8/crash.8
@@ -0,0 +1,144 @@
+.\" Copyright (c) 1980, 1991 The Regents of the University of California.
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
+.\"
+.\"	from: @(#)crash.8	6.5 (Berkeley) 4/20/91
+.\"	$Id: crash.8,v 1.1 2000/02/28 22:36:42 deraadt Exp $
+.\"
+.Dd February 23, 2000
+.Dt crash 8
+.Os
+.Sh NAME
+.Nm crash
+.Nd system failure and diagnosis
+.Sh DESCRIPTION
+This section explains what happens when the system crashes
+and (very briefly) how to analyze crash dumps.
+.Pp
+When the system crashes voluntarily it prints a message of the form
+.Pp
+.Bd -literal
+        panic: why i gave up the ghost
+.Ed
+.Pp
+on the console, and enters the kernel debugger
+.Xr ddb 4
+if it is compiled into the kernel.
+If
+.Xr ddb 4
+is not in the kernel, the system takes a dump on a mass storage
+peripheral, and then invokes an automatic reboot procedure as
+described in
+.Xr reboot 8 .
+(If auto-reboot is disabled (in a machine dependent way) the system
+will simply halt at this point.)
+Unless some unexpected inconsistency is encountered in the state
+of the file systems due to hardware or software failure, the system
+will then resume multi-user operations.
+.Pp
+The system has a large number of internal consistency checks; if one
+of these fails, then it will panic with a very short message indicating
+which one failed.
+In many instances, this will be the name of the routine which detected
+the error, or a two-word description of the inconsistency.
+A full understanding of most panic messages requires perusal of the
+source code for the system.
+.Pp
+The most common cause of system failures is hardware failure, which
+can reflect itself in different ways.  Here are the messages which
+are most likely, with some hints as to causes.
+Left unstated in all cases is the possibility that hardware or software
+error produced the message in some unexpected way.
+.Bl -tag -width indent
+.It no init
+This panic message indicates filesystem problems, and reboots are likely
+to be futile.  Late in the bootstrap procedure, the system was unable to
+locate and execute the initialization process,
+.Xr init 8 .
+The root filesystem is incorrect or has been corrupted, or the mode
+or type of /sbin/init forbids execution.
+.It timeout table overflow
+.ns
+This really shouldn't be a panic, but until the data structure
+involved is made to be extensible, running out of entries causes a crash.
+If this happens, make the timeout table bigger.
+.It trap type %d, code=%x, pc=%x
+A unexpected trap has occurred within the system; the trap types are
+machine dependent and can be found listed in
+.Pa /sys/arch/ARCH/include/trap.h .
+.Pp
+The code is the referenced address, and the pc at the
+time of the fault is printed.  These problems tend to be easy to track
+down if they are kernel bugs since the processor stops cold, but random
+flakiness seems to cause this sometimes.
+The kernel debugger
+.Xr ddb 4
+can be used to locate the instruction and subroutine corresponding
+to the PC value.
+If that is insufficient to suggest the nature of the problem,
+more detailed examination of the system status at the time of the trap
+usually can produce an explanation.
+.It init died
+The system initialization process has exited.  This is bad news, as no new
+users will then be able to log in.  Rebooting is the only fix, so the
+system just does it right away.
+.It out of mbufs: map full
+The network has exhausted its private page map for network buffers.
+This usually indicates that buffers are being lost, and rather than
+allow the system to slowly degrade, it reboots immediately.
+The map may be made larger if necessary.
+.El
+.Pp
+That completes the list of panic types you are likely to see.
+.Pp
+When the system crashes it writes (or at least attempts to write)
+an image of memory into the back end of the dump device,
+usually the same as the primary swap
+area.  After the system is rebooted, the program
+.Xr savecore 8
+runs and preserves a copy of this core image and the current
+system in a specified directory for later perusal.  See
+.Xr savecore 8
+for details.
+.Pp
+To analyze a dump you should begin by running
+.Xr gdb 1 .
+Once gdb starts, use the command
+.Pp
+.Bd -literal
+        target kcore /dev/mem
+.Ed
+NIKLAS NIKLAS.
+.Pp
+Then a traceback and other such things can be gotten.
+.Sh "SEE ALSO"
+.Xr gdb 1 ,
+.Xr ddb 4 ,
+.Xr reboot 8