jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: kvm_dump.3,v 1.14 2025/06/06 21:53:13 schwarze 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: June 6 2025 $
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.Lb libkvm
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
68.Dv CORE_CPU
69section and the section header of the
70.Dv CORE_DATA
71section.
72The data is written to the file pointed at by
73.Fa fp .
74The
75.Fa dumpsize
76argument is only used to properly set the segment size of the
77.Dv CORE_DATA
78section.
79Note that this function assumes that
80.Fa fp
81is positioned at file location 0.
82This function will not seek and therefore allows
83.Fa fp
84to be a file pointer obtained by
85.Fn zopen .
86.Pp
87The
88.Fn kvm_dump_inval
89function clears the magic number in the physical memory file associated with
90.Fa kd .
91The address translations must be enabled for this to work (thus assuming
92that
93.Fn kvm_dump_mkheader
94was called earlier in the sequence).
95.Sh RETURN VALUES
96All functions return 0 on success, \-1 on failure.
97In the case of failure,
98.Xr kvm_geterr 3
99can be used to retrieve the cause of the error.
100.Sh SEE ALSO
101.Xr kvm 3
102.Sh HISTORY
103These functions first appeared in
104.Nx 1.1a .