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