1.\" $OpenBSD: kvm_dump.3,v 1.6 2001/08/06 10:42:26 mpech Exp $ 2.\" $NetBSD: kvm_dump.3,v 1.1 1996/03/18 21:11:12 leo Exp $ 3.\" 4.\" Copyright (c) 1996 Leo Weppelman 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by Leo Weppelman. 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 AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" 34.Dd March 17, 1996 35.Dt KVM_DUMP 3 36.Os 37.Sh NAME 38.Nm kvm_dump_mkheader , 39.Nm kvm_dump_wrtheader , 40.Nm kvm_dump_inval 41.Nd crash-dump support functions 42.Sh SYNOPSIS 43.Fd #include <kvm.h> 44.Ft int 45.Fn kvm_dump_mkheader "kvm_t *kd" "off_t dump_off" 46.Ft int 47.Fn kvm_dump_wrtheader "kvm_t *kd" "FILE *fp" "int dumpsize" 48.Ft int 49.Fn kvm_dump_inval "kvm_t *kd" 50.Sh DESCRIPTION 51First note that the functions described here were designed to be used by 52.Xr savecore 8 . 53.Pp 54The function 55.Fn kvm_dump_mkheader 56checks if the physical memory file associated with 57.Fa kd 58contains a valid crash-dump header as generated by a dumping kernel. 59When a valid header is found, 60.Fn kvm_dump_mkheader 61initializes the internal kvm data structures as if a crash-dump generated by 62the 63.Xr savecore 8 64program was opened. 65This has the intentional side effect of enabling the 66address translation machinery. 67.Pp 68A call to 69.Fn kvm_dump_mkheader 70will most likely be followed by a call to 71.Fn kvm_dump_wrtheader . 72This function takes care of generating the generic header, the 73.Dv CORE_CPU 74section and the section header of the 75.Dv CORE_DATA 76section. 77The data is written to the file pointed at by 78.Fa fp . 79The 80.Fa dumpsize 81argument is only used to properly set the segment size of the 82.Dv CORE_DATA 83section. 84Note that this function assumes that 85.Fa fp 86is positioned at file location 0. 87This function will not seek and therefore allows 88.Fa fp 89to be a file pointer obtained by 90.Fn zopen . 91.Pp 92The 93.Fn kvm_dump_inval 94function clears the magic number in the physical memory file associated with 95.Fa kd . 96The address translations must be enabled for this to work (thus assuming 97that 98.Fn kvm_dump_mkheader 99was called earlier in the sequence). 100.Sh RETURN VALUES 101All functions return 0 on success, \-1 on failure. 102In the case of failure, 103.Xr kvm_geterr 3 104can be used to retrieve the cause of the error. 105.Sh HISTORY 106These functions first appeared in 107.Nx 1.1 a. 108.Sh SEE ALSO 109.Xr kvm 3 110