| blob | e743327d1fabb54551441c20bde9725f0c90806e |
1 .\" $NetBSD: kvm_dump.3,v 1.14 2009/03/10 23:49:07 joerg 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
46 First note that the functions described here were designed to be used by
47 .Xr savecore 8 .
48 .Pp
49 The function
50 .Fn kvm_dump_mkheader
51 checks if the physical memory file associated with
52 .Fa kd
53 contains a valid crash dump header as generated by a dumping kernel.
54 When a valid header is found,
55 .Fn kvm_dump_mkheader
56 initializes the internal kvm data structures as if a crash dump generated by
57 the
58 .Xr savecore 8
59 program was opened.
60 This has the intentional side effect of enabling the
61 address translation machinery.
62 .Pp
63 A call to
64 .Fn kvm_dump_mkheader
65 will most likely be followed by a call to
66 .Fn kvm_dump_wrtheader .
67 This function takes care of generating the generic header, the CORE_CPU
68 section and the section header of the CORE_DATA section.
69 The data is written to the file pointed at by
70 .Fa fp .
71 The
72 .Fa dumpsize
73 argument is only used to properly the set the segment size of the CORE_DATA
74 section.
75 Note that this function assumes that
76 .Fa fp
77 is positioned at file location 0.
78 This function will not seek and therefore allows
79 .Fa fp
80 to be a file pointer obtained by
81 .Fn zopen .
82 .Pp
83 The
84 .Fn kvm_dump_inval
85 function clears the magic number in the physical memory file associated with
86 .Fa kd .
87 The address translations must be enabled for this to work (thus assuming
88 that
89 .Fn kvm_dump_mkheader
90 was called earlier in the sequence).
91 .Sh RETURN VALUES
92 All functions except
93 .Fn kvm_dump_mkheader
94 return 0 on success, -1 on failure.
95 The function
96 .Fn kvm_dump_mkheader
97 returns the size of the headers present before the actual dumpdata starts.
98 If no valid headers were found but no fatal errors occurred, 0 is returned.
99 On fatal errors the return value is -1.
100 .Pp
101 In the case of failure,
102 .Xr kvm_geterr 3
103 can 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
108 These functions first appeared in
109 .Nx 1.2 .