sbin/savecore/savecore.8

   1 .\"     $NetBSD: savecore.8,v 1.33 2004/10/21 10:13:00 dsainty Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)savecore.8  8.1 (Berkeley) 6/5/93
  31 .\"
  32 .Dd March 3, 2009
  33 .Dt SAVECORE 8
  34 .Os
  35 .Sh NAME
  36 .Nm savecore
  37 .Nd save a core dump of the operating system
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl fvz
  41 .Op Fl N Ar system
  42 .Op Fl Z Ar level
  43 .Ar directory
  44 .Nm
  45 .Fl c
  46 .Op Fl v
  47 .Op Fl N Ar system
  48 .Nm
  49 .Fl n
  50 .Op Fl v
  51 .Op Fl N Ar system
  52 .Sh DESCRIPTION
  53 When the
  54 .Nx
  55 kernel encounters a fatal error, the
  56 .Xr panic 9
  57 routine arranges for a snapshot of the contents of physical memory to
  58 be written into a dump area, typically in the swap partition.
  59 .Pp
  60 Upon a subsequent reboot,
  61 .Nm
  62 is typically run out of
  63 .Xr rc 8 ,
  64 before swapping is enabled, to copy the kernel and the saved memory image
  65 into
  66 .Fa directory ,
  67 and enters a reboot message and information about the core dump into
  68 the system log.
  69 .Pp
  70 The kernel and core file can then be analyzed using various tools,
  71 including
  72 .Xr crash 8 ,
  73 .Xr dmesg 8 ,
  74 .Xr fstat 1 ,
  75 .Xr gdb 1 ,
  76 .Xr iostat 8 ,
  77 .Xr netstat 1 ,
  78 .Xr ps 1 ,
  79 and
  80 .Xr pstat 8 ,
  81 to attempt to deduce the cause of the crash.
  82 .Pp
  83 Crashes are usually the result of hardware faults or kernel bugs.
  84 If a kernel bug is suspected, a full bug report should be filed at
  85 http://www.netbsd.org/, or using
  86 .Xr send-pr 1 ,
  87 containing as much information as possible about the circumstances of
  88 the crash.
  89 Since crash dumps are typically very large and may contain
  90 whatever (potentially confidential) information was in memory at the
  91 time of the crash, do
  92 .Em NOT
  93 include a copy of the crash dump file in the bug report; instead, save it
  94 somewhere in the event that a
  95 .Nx
  96 developer wants to examine it.
  97 .Pp
  98 The options are as follows:
  99 .Bl -tag -width directory
 100 .It Fl c
 101 Only clears the dump without saving it, so that future invocations of
 102 .Nm
 103 will ignore it.
 104 .It Fl f
 105 Forces a dump to be taken even if the dump doesn't appear correct or there
 106 is insufficient disk space.
 107 .It Fl n
 108 Check whether a dump is present without taking further action.
 109 The command exits with zero status if a dump is present, or with non-zero
 110 status otherwise.
 111 .It Fl N
 112 Use
 113 .Ar system
 114 as the kernel instead of the default (returned by
 115 .Xr getbootfile 3 ) .
 116 Note that
 117 .Xr getbootfile 3
 118 uses
 119 .Xr secure_path 3
 120 to check that kernel file is
 121 .Dq secure
 122 and will default to
 123 .Pa /netbsd
 124 if the check fails.
 125 .It Fl v
 126 Prints out some additional debugging information.
 127 .It Fl z
 128 Compresses the core dump and kernel (see
 129 .Xr gzip 1 ) .
 130 .It Fl Z Ar level
 131 Set the compression level for
 132 .Fl z
 133 to
 134 .Ar level .
 135 Defaults to 1 (the fastest compression mode).
 136 Refer to
 137 .Xr gzip 1
 138 for more information regarding the compression level.
 139 .El
 140 .Pp
 141 .Nm
 142 checks the core dump in various ways to make sure that it is current and
 143 that it corresponds to the currently running system.
 144 If it passes these checks, it saves the core image in
 145 .Ar directory Ns Pa /netbsd.#.core
 146 and the system in
 147 .Ar directory Ns Pa /netbsd.#
 148 (or in
 149 .Ar directory Ns Pa /netbsd.#.core.gz
 150 and
 151 .Ar directory Ns Pa /netbsd.#.gz ,
 152 respectively, if the
 153 .Fl z
 154 option is used).
 155 The
 156 .Dq #
 157 is the number from the first line of the file
 158 .Ar directory Ns Pa /bounds ,
 159 and it is incremented and stored back into the file each time
 160 .Nm
 161 successfully runs.
 162 .Pp
 163 .Nm
 164 also checks the available disk space before attempting to make the copies.
 165 If there is insufficient disk space in the file system containing
 166 .Ar directory ,
 167 or if the file
 168 .Ar directory Ns Pa /minfree
 169 exists and the number of free kilobytes (for non-superusers) in the
 170 file system after the copies were made would be less than the number
 171 in the first line of this file, the copies are not attempted.
 172 .Pp
 173 If
 174 .Nm
 175 successfully copies the kernel and the core dump, the core dump is cleared
 176 so that future invocations of
 177 .Nm
 178 will ignore it.
 179 .Sh SEE ALSO
 180 .Xr fstat 1 ,
 181 .Xr gdb 1 ,
 182 .Xr gzip 1 ,
 183 .Xr netstat 1 ,
 184 .Xr ps 1 ,
 185 .Xr send-pr 1 ,
 186 .Xr crash 8 ,
 187 .Xr dmesg 8 ,
 188 .Xr iostat 8 ,
 189 .Xr pstat 8 ,
 190 .Xr rc 8 ,
 191 .Xr syslogd 8 ,
 192 .Xr panic 9
 193 .Sh HISTORY
 194 The
 195 .Nm
 196 command appeared in
 197 .Bx 4.1 .
 198 .Sh BUGS
 199 The minfree code does not consider the effect of compression.