share/man/man9/panic.9

   1 .\"     $NetBSD: panic.9,v 1.18 2009/01/12 16:28:03 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" Michael Graff.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd January 12, 2009
  31 .Dt PANIC 9
  32 .Os
  33 .Sh NAME
  34 .Nm panic
  35 .Nd Bring down system on fatal error
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/systm.h
  39 .Ft void
  40 .Fn panic "const char *fmt" "..."
  41 .Sh DESCRIPTION
  42 The
  43 .Fn panic
  44 function terminates the
  45 .Nx
  46 system.
  47 The message
  48 .Fa fmt
  49 is a
  50 .Xr printf 3
  51 style format string which is printed to the console and saved in the
  52 variable
  53 .Va panicstr
  54 for later retrieval via core dump inspection.
  55 A newline character is added at the end automatically, and is thus
  56 not needed in the format string.
  57 .Pp
  58 If a kernel debugger is installed, control is passed to it after the
  59 message is printed.
  60 If the kernel debugger is
  61 .Xr ddb 4 ,
  62 control may be passed to it, depending on the value of
  63 .Em ddb.onpanic .
  64 See
  65 .Xr options 4
  66 for more details on setting
  67 .Em ddb.onpanic .
  68 If control is not passed through to
  69 .Xr ddb 4 ,
  70 a
  71 .Xr ddb 4 Ns -specific
  72 function is used to print the kernel stack trace, and then control returns
  73 to
  74 .Fn panic .
  75 .Pp
  76 If control remains in
  77 .Fn panic ,
  78 an attempt is made to save an image of system memory on the
  79 configured dump device.
  80 .Pp
  81 If during the process of handling the panic,
  82 .Fn panic
  83 is called again
  84 .Pq from the filesystem synchronization routines, for example ,
  85 the system is rebooted immediately without synchronizing any filesystems.
  86 .Pp
  87 .Fn panic
  88 is meant to be used in situations where something unexpected has happened
  89 and it is difficult to recover the system to a stable state, or in
  90 situations where proceeding might make the things worse, leading to
  91 data corruption/loss.
  92 It is not meant to be used in scenarios where the system could easily
  93 ignore and/or isolate the condition/subsystem and proceed.
  94 .Pp
  95 In general developers should try to reduce the number of
  96 .Fn panic
  97 calls in the kernel to improve stability.
  98 .Sh RETURN VALUES
  99 The
 100 .Fn panic
 101 function does not return.
 102 .Sh SEE ALSO
 103 .Xr sysctl 3 ,
 104 .Xr ddb 4 ,
 105 .Xr ipkdb 4 ,
 106 .Xr options 4 ,
 107 .Xr savecore 8 ,
 108 .Xr swapctl 8 ,
 109 .Xr sysctl 8