1.\" $NetBSD: savecore.8,v 1.34 2009/03/07 22:08:08 ad 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 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. 69.Pp 70The kernel and core file can then be analyzed using various tools, 71including 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 , 79and 80.Xr pstat 8 , 81to attempt to deduce the cause of the crash. 82.Pp 83Crashes are usually the result of hardware faults or kernel bugs. 84If a kernel bug is suspected, a full bug report should be filed at 85http://www.netbsd.org/, or using 86.Xr send-pr 1 , 87containing as much information as possible about the circumstances of 88the crash. 89Since crash dumps are typically very large and may contain 90whatever (potentially confidential) information was in memory at the 91time of the crash, do 92.Em NOT 93include a copy of the crash dump file in the bug report; instead, save it 94somewhere in the event that a 95.Nx 96developer wants to examine it. 97.Pp 98The options are as follows: 99.Bl -tag -width directory 100.It Fl c 101Only clears the dump without saving it, so that future invocations of 102.Nm 103will ignore it. 104.It Fl f 105Forces a dump to be taken even if the dump doesn't appear correct or there 106is insufficient disk space. 107.It Fl n 108Check whether a dump is present without taking further action. 109The command exits with zero status if a dump is present, or with non-zero 110status otherwise. 111.It Fl N 112Use 113.Ar system 114as the kernel instead of the default (returned by 115.Xr getbootfile 3 ) . 116Note that 117.Xr getbootfile 3 118uses 119.Xr secure_path 3 120to check that kernel file is 121.Dq secure 122and will default to 123.Pa /netbsd 124if the check fails. 125.It Fl v 126Prints out some additional debugging information. 127.It Fl z 128Compresses the core dump and kernel (see 129.Xr gzip 1 ) . 130.It Fl Z Ar level 131Set the compression level for 132.Fl z 133to 134.Ar level . 135Defaults to 1 (the fastest compression mode). 136Refer to 137.Xr gzip 1 138for more information regarding the compression level. 139.El 140.Pp 141.Nm 142checks the core dump in various ways to make sure that it is current and 143that it corresponds to the currently running system. 144If it passes these checks, it saves the core image in 145.Ar directory Ns Pa /netbsd.#.core 146and the system in 147.Ar directory Ns Pa /netbsd.# 148(or in 149.Ar directory Ns Pa /netbsd.#.core.gz 150and 151.Ar directory Ns Pa /netbsd.#.gz , 152respectively, if the 153.Fl z 154option is used). 155The 156.Dq # 157is the number from the first line of the file 158.Ar directory Ns Pa /bounds , 159and it is incremented and stored back into the file each time 160.Nm 161successfully runs. 162.Pp 163.Nm 164also checks the available disk space before attempting to make the copies. 165If there is insufficient disk space in the file system containing 166.Ar directory , 167or if the file 168.Ar directory Ns Pa /minfree 169exists and the number of free kilobytes (for non-superusers) in the 170file system after the copies were made would be less than the number 171in the first line of this file, the copies are not attempted. 172.Pp 173If 174.Nm 175successfully copies the kernel and the core dump, the core dump is cleared 176so that future invocations of 177.Nm 178will 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 194The 195.Nm 196command appeared in 197.Bx 4.1 . 198.Sh BUGS 199The minfree code does not consider the effect of compression. 200