import less(1)
[unleashed/tickless.git] / share / man / man3kvm / kvm_open.3kvm
blob8a8e4067a9280d4bf55a9644527807b74de066c9
1 '\" te
2 .\"  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH KVM_OPEN 3KVM "May 2, 2002"
7 .SH NAME
8 kvm_open, kvm_close \- specify a kernel to examine
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.]
13 #include <kvm.h>
14 #include <fcntl.h>
16 \fBkvm_t *\fR\fBkvm_open\fR(\fBchar *\fR\fInamelist\fR, \fBchar *\fR\fIcorefile\fR, \fBchar *\fR\fIswapfile\fR, \fBint\fR \fIflag\fR,
17      \fBchar *\fR\fIerrstr\fR);
18 .fi
20 .LP
21 .nf
22 \fBint\fR \fBkvm_close\fR(\fBkvm_t *\fR\fIkd\fR);
23 .fi
25 .SH DESCRIPTION
26 .sp
27 .LP
28 The \fBkvm_open()\fR function initializes a set of file descriptors to be used
29 in subsequent calls to kernel virtual memory ( VM) routines.  It returns a
30 pointer to a kernel identifier that must be used as the \fIkd\fR argument in
31 subsequent kernel VM function calls.
32 .sp
33 .LP
34 The \fInamelist\fR argument specifies an unstripped executable file whose
35 symbol table will be used to locate various offsets in \fIcorefile\fR. If
36 \fInamelist\fR is \fINULL\fR, the symbol table of the currently running kernel
37 is used to determine offsets in the core image.  In this case, it is up to the
38 implementation to select an appropriate way to resolve symbolic references, for
39 instance, using \fB/dev/ksyms\fR as a default \fInamelist\fR file.
40 .sp
41 .LP
42 The \fIcorefile\fR argument specifies a file that contains an image of physical
43 memory, for instance, a kernel crash dump file (see \fBsavecore\fR(1M)) or the
44 special device \fB/dev/mem\fR. If \fIcorefile\fR is \fINULL\fR, the currently
45 running kernel is accessed, using \fB/dev/mem\fR and \fB/dev/kmem\fR.
46 .sp
47 .LP
48 The \fIswapfile\fR argument specifies a file that represents the swap device.
49 If both \fIcorefile\fR and \fIswapfile\fR are \fINULL\fR, the swap device of
50 the currently running kernel is accessed.  Otherwise, if \fIswapfile\fR is
51 \fINULL\fR, \fBkvm_open()\fR may succeed but subsequent \fBkvm_getu\fR(3KVM)
52 function calls may fail if the desired information is swapped out.
53 .sp
54 .LP
55 The \fIflag\fR function is used to specify read or write access for
56 \fIcorefile\fR and may have one of the following values:
57 .sp
58 .ne 2
59 .na
60 \fB\fBO_RDONLY\fR\fR
61 .ad
62 .RS 12n
63 open for reading
64 .RE
66 .sp
67 .ne 2
68 .na
69 \fB\fBO_RDWR\fR\fR
70 .ad
71 .RS 12n
72 open for reading and writing
73 .RE
75 .sp
76 .LP
77 The \fIerrstr\fR argument is used to control error reporting.  If it is a null
78 pointer, no error messages will be printed. If it is non-null, it is assumed to
79 be the address of a string that will be used to prefix error messages generated
80 by \fBkvm_open\fR. Errors are printed to \fBstderr\fR. A useful value to supply
81 for \fIerrstr\fR would be \fIargv\fR[0]. This has the effect of printing the
82 process name in front of any error messages.
83 .sp
84 .LP
85 Applications using  \fBlibkvm\fR are dependent on the underlying data model of
86 the kernel image, that is, whether it is a 32\(mibit or 64\(mibit kernel.
87 .sp
88 .LP
89 The data model of these applications must match the data model of the kernel in
90 order to correctly interpret the size and offsets of kernel data structures.
91 For example, a 32\(mibit application that uses the 32\(mibit version of the
92 \fBlibkvm\fR interfaces will fail to open a 64\(mibit kernel image.  Similarly,
93 a 64\(mibit application that uses the 64\(mibit version of the \fBlibkvm\fR
94 interfaces will fail to open a 32\(mibit kernel image.
95 .sp
96 .LP
97 The \fBkvm_close()\fR function closes all file descriptors that were associated
98 with \fIkd\fR. These files are also closed on \fBexit\fR(2) and
99 \fBexecve\fR(\|) (see \fBexec\fR(2)). \fBkvm_close()\fR also resets the
100 \fBproc\fR pointer associated with \fBkvm_nextproc\fR(3KVM) and flushes any
101 cached kernel data.
102 .SH RETURN VALUES
105 The \fBkvm_open()\fR function returns a non-null value suitable for use with
106 subsequent kernel VM function calls. On failure, it returns \fINULL\fR and no
107 files are opened.
110 The \fBkvm_close()\fR function returns 0 on success and \(mi1 on failure.
111 .SH FILES
113 .ne 2
115 \fB\fB/dev/kmem\fR\fR
117 .RS 14n
122 .ne 2
124 \fB\fB/dev/ksyms\fR\fR
126 .RS 14n
131 .ne 2
133 \fB\fB/dev/mem\fR\fR
135 .RS 14n
139 .SH ATTRIBUTES
142 See \fBattributes\fR(5) for descriptions of the following attributes:
147 box;
148 c | c
149 l | l .
150 ATTRIBUTE TYPE  ATTRIBUTE VALUE
152 Interface Stability     Stable
154 MT-Level        Unsafe
157 .SH SEE ALSO
160 \fBsavecore\fR(1M), \fBexec\fR(2), \fBexit\fR(2), \fBpathconf\fR(2),
161 \fBgetloadavg\fR(3C), \fBkstat\fR(3KSTAT), \fBkvm_getu\fR(3KVM),
162 \fBkvm_nextproc\fR(3KVM), \fBkvm_nlist\fR(3KVM), \fBkvm_kread\fR(3KVM),
163 \fBlibkvm\fR(3LIB),\fBsysconf\fR(3C), \fBproc\fR(4), \fBattributes\fR(5),
164 \fBlfcompile\fR(5)
165 .SH NOTES
168 Kernel core dumps should be examined on the platform on which they were
169 created. While a 32-bit application running on a 64-bit kernel can examine a
170 32-bit core dump, a 64-bit application running on a 64-bit kernel cannot
171 examine a kernel core dump from the 32-bit system.
174 On 32-bit systems, applications that use \fBlibkvm\fR to access the running
175 kernel must be 32-bit applications. On systems that support both 32-bit and
176 64-bit applications, applications that use the \fBlibkvm\fR interfaces to
177 access the running kernel must themselves be 64-bit applications.
180 Although the \fBlibkvm\fR API is Stable, the symbol names and data values that
181 can be accessed through this set of interfaces are Private and are subject to
182 ongoing change.
185 Applications using  \fBlibkvm\fR are likely to be platform- and
186 release-dependent.
189 Most of the traditional uses of \fBlibkvm\fR have been superseded by more
190 stable interfaces that allow the same information to be extracted more
191 efficiently, yet  independent of the kernel data model.  For examples, see
192 \fBsysconf\fR(3C), \fBproc\fR(4), \fBkstat\fR(3KSTAT), \fBgetloadavg\fR(3C),
193 and \fBpathconf\fR(2).