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