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