1.\" $NetBSD: kvm_dump.3,v 1.10 2002/02/07 07:00:48 ross 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.Fd #include \*[Lt]kvm.h\*[Gt] 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. When a 61valid 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. This has the intentional side effect of enabling the 67address translation machinery. 68.Pp 69A call to 70.Fn kvm_dump_mkheader 71will most likely be followed by a call to 72.Fn kvm_dump_wrtheader . 73This function takes care of generating the generic header, the CORE_CPU 74section and the section header of the CORE_DATA section. The data is written 75to the file pointed at by 76.Fa fp . 77The 78.Fa dumpsize 79argument is only used to properly the set the segment size of the CORE_DATA 80section. Note that this function assumes that 81.Fa fp 82is positioned at file location 0. This function will not seek and therefore 83allows 84.Fa fp 85to be a file pointer obtained by 86.Fn zopen . 87.Pp 88The 89.Fn kvm_dump_inval 90function clears the magic number in the physical memory file associated with 91.Fa kd . 92The address translations must be enabled for this to work (thus assuming 93that 94.Fn kvm_dump_mkheader 95was called earlier in the sequence). 96.Sh RETURN VALUES 97All functions except 98.Fn kvm_dump_mkheader 99return 0 on success, -1 on failure. The function 100.Fn kvm_dump_mkheader 101returns the size of the headers present before the actual dumpdata starts. If 102no valid headers were found but no fatal errors occurred, 0 is returned. On 103fatal errors the return value is -1. 104.Pp 105In the case of failure, 106.Xr kvm_geterr 3 107can be used to retrieve the cause of the error. 108.Sh SEE ALSO 109.Xr kvm 3 , 110.Xr kvm_open 3 111.Sh HISTORY 112These functions first appeared in 113.Nx 1.2 . 114