1.\" $NetBSD: savecore.8,v 1.37 2012/03/15 22:35:03 njoly 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 September 13, 2011 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.Op 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 53When the 54.Nx 55kernel encounters a fatal error, the 56.Xr panic 9 57routine arranges for a snapshot of the contents of physical memory to 58be written into a dump area, typically in the swap partition. 59.Pp 60Upon a subsequent reboot, 61.Nm 62is typically run out of 63.Xr rc 8 , 64before swapping is enabled, to copy the kernel and the saved memory image 65into 66.Fa directory , 67and enters a reboot message and information about the core dump into 68the system log. 69If a directory is not specified, then 70.Pa /var/crash 71is used. 72.Pp 73The kernel and core file can then be analyzed using various tools, 74including 75.Xr crash 8 , 76.Xr dmesg 8 , 77.Xr fstat 1 , 78.Xr gdb 1 , 79.Xr iostat 8 , 80.Xr netstat 1 , 81.Xr ps 1 , 82and 83.Xr pstat 8 , 84to attempt to deduce the cause of the crash. 85.Pp 86Crashes are usually the result of hardware faults or kernel bugs. 87If a kernel bug is suspected, a full bug report should be filed at 88.Lk http://www.netbsd.org/ , 89or using 90.Xr send-pr 1 , 91containing as much information as possible about the circumstances of 92the crash. 93Since crash dumps are typically very large and may contain 94whatever (potentially confidential) information was in memory at the 95time of the crash, do 96.Em NOT 97include a copy of the crash dump file in the bug report; instead, save it 98somewhere in the event that a 99.Nx 100developer wants to examine it. 101.Pp 102The options are as follows: 103.Bl -tag -width directory 104.It Fl c 105Only clears the dump without saving it, so that future invocations of 106.Nm 107will ignore it. 108.It Fl f 109Forces a dump to be taken even if the dump doesn't appear correct or there 110is insufficient disk space. 111.It Fl n 112Check whether a dump is present without taking further action. 113The command exits with zero status if a dump is present, or with non-zero 114status otherwise. 115.It Fl N 116Use 117.Ar system 118as the kernel instead of the default (returned by 119.Xr getbootfile 3 ) . 120Note that 121.Xr getbootfile 3 122uses 123.Xr secure_path 3 124to check that kernel file is 125.Dq secure 126and will default to 127.Pa /netbsd 128if the check fails. 129.It Fl v 130Prints out some additional debugging information. 131.It Fl z 132Compresses the core dump and kernel (see 133.Xr gzip 1 ) . 134.It Fl Z Ar level 135Set the compression level for 136.Fl z 137to 138.Ar level . 139Defaults to 1 (the fastest compression mode). 140Refer to 141.Xr gzip 1 142for more information regarding the compression level. 143.El 144.Pp 145.Nm 146checks the core dump in various ways to make sure that it is current and 147that it corresponds to the currently running system. 148If it passes these checks, it saves the core image in 149.Ar directory Ns Pa /netbsd.#.core 150and the system in 151.Ar directory Ns Pa /netbsd.# 152(or in 153.Ar directory Ns Pa /netbsd.#.core.gz 154and 155.Ar directory Ns Pa /netbsd.#.gz , 156respectively, if the 157.Fl z 158option is used). 159The 160.Dq # 161is the number from the first line of the file 162.Ar directory Ns Pa /bounds , 163and it is incremented and stored back into the file each time 164.Nm 165successfully runs. 166.Pp 167.Nm 168also checks the available disk space before attempting to make the copies. 169If there is insufficient disk space in the file system containing 170.Ar directory , 171or if the file 172.Ar directory Ns Pa /minfree 173exists and the number of free kilobytes (for non-superusers) in the 174file system after the copies were made would be less than the number 175in the first line of this file, the copies are not attempted. 176.Pp 177If 178.Nm 179successfully copies the kernel and the core dump, the core dump is cleared 180so that future invocations of 181.Nm 182will ignore it. 183.Sh SEE ALSO 184.Xr fstat 1 , 185.Xr gdb 1 , 186.Xr gzip 1 , 187.Xr netstat 1 , 188.Xr ps 1 , 189.Xr send-pr 1 , 190.Xr crash 8 , 191.Xr dmesg 8 , 192.Xr iostat 8 , 193.Xr pstat 8 , 194.Xr rc 8 , 195.Xr syslogd 8 , 196.Xr panic 9 197.Sh HISTORY 198The 199.Nm 200command appeared in 201.Bx 4.1 . 202.Sh BUGS 203The minfree code does not consider the effect of compression. 204