1.\" $NetBSD: kvm_dump.3,v 1.13 2003/05/16 10:24:55 wiz Exp $ 2.\" 3.\" Copyright (c) 1996 Leo Weppelman 4.\" 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 Leo Weppelman. 17.\" 4. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.\" 33.Dd March 17, 1996 34.Dt KVM_DUMP 3 35.Os 36.Sh NAME 37.Nm kvm_dump_mkheader , 38.Nm kvm_dump_wrtheader , 39.Nm kvm_dump_inval 40.Nd crash dump support functions 41.Sh LIBRARY 42.Lb libkvm 43.Sh SYNOPSIS 44.In kvm.h 45.br 46.Ft int 47.Fn kvm_dump_mkheader "kvm_t *kd" "off_t dump_off" 48.Ft int 49.Fn kvm_dump_wrtheader "kvm_t *kd" "FILE *fp" "int dumpsize" 50.Ft int 51.Fn kvm_dump_inval "kvm_t *kd" 52.Sh DESCRIPTION 53First note that the functions described here were designed to be used by 54.Xr savecore 8 . 55.Pp 56The function 57.Fn kvm_dump_mkheader 58checks if the physical memory file associated with 59.Fa kd 60contains a valid crash dump header as generated by a dumping kernel. 61When a valid header is found, 62.Fn kvm_dump_mkheader 63initializes the internal kvm data structures as if a crash dump generated by 64the 65.Xr savecore 8 66program was opened. 67This has the intentional side effect of enabling the 68address translation machinery. 69.Pp 70A call to 71.Fn kvm_dump_mkheader 72will most likely be followed by a call to 73.Fn kvm_dump_wrtheader . 74This function takes care of generating the generic header, the CORE_CPU 75section and the section header of the CORE_DATA section. 76The data is written to the file pointed at by 77.Fa fp . 78The 79.Fa dumpsize 80argument is only used to properly the set the segment size of the CORE_DATA 81section. 82Note that this function assumes that 83.Fa fp 84is positioned at file location 0. 85This function will not seek and therefore allows 86.Fa fp 87to be a file pointer obtained by 88.Fn zopen . 89.Pp 90The 91.Fn kvm_dump_inval 92function clears the magic number in the physical memory file associated with 93.Fa kd . 94The address translations must be enabled for this to work (thus assuming 95that 96.Fn kvm_dump_mkheader 97was called earlier in the sequence). 98.Sh RETURN VALUES 99All functions except 100.Fn kvm_dump_mkheader 101return 0 on success, -1 on failure. 102The function 103.Fn kvm_dump_mkheader 104returns the size of the headers present before the actual dumpdata starts. 105If no valid headers were found but no fatal errors occurred, 0 is returned. 106On fatal errors the return value is -1. 107.Pp 108In the case of failure, 109.Xr kvm_geterr 3 110can be used to retrieve the cause of the error. 111.Sh SEE ALSO 112.Xr kvm 3 , 113.Xr kvm_open 3 114.Sh HISTORY 115These functions first appeared in 116.Nx 1.2 . 117