share/man/man3kvm/kvm_open.3kvm

   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>
  15
  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
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBkvm_close\fR(\fBkvm_t *\fR\fIkd\fR);
  23 .fi
  24
  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(8)) 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
  65
  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
  74
  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
 103 .sp
 104 .LP
 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.
 108 .sp
 109 .LP
 110 The \fBkvm_close()\fR function returns 0 on success and \(mi1 on failure.
 111 .SH FILES
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fB/dev/kmem\fR\fR
 116 .ad
 117 .RS 14n
 118
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fB/dev/ksyms\fR\fR
 125 .ad
 126 .RS 14n
 127
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fB/dev/mem\fR\fR
 134 .ad
 135 .RS 14n
 136
 137 .RE
 138
 139 .SH ATTRIBUTES
 140 .sp
 141 .LP
 142 See \fBattributes\fR(5) for descriptions of the following attributes:
 143 .sp
 144
 145 .sp
 146 .TS
 147 box;
 148 c | c
 149 l | l .
 150 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 151 _
 152 Interface Stability     Stable
 153 _
 154 MT-Level        Unsafe
 155 .TE
 156
 157 .SH SEE ALSO
 158 .sp
 159 .LP
 160 \fBsavecore\fR(8), \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 .SH NOTES
 165 .sp
 166 .LP
 167 Kernel core dumps should be examined on the platform on which they were
 168 created. While a 32-bit application running on a 64-bit kernel can examine a
 169 32-bit core dump, a 64-bit application running on a 64-bit kernel cannot
 170 examine a kernel core dump from the 32-bit system.
 171 .sp
 172 .LP
 173 On 32-bit systems, applications that use \fBlibkvm\fR to access the running
 174 kernel must be 32-bit applications. On systems that support both 32-bit and
 175 64-bit applications, applications that use the \fBlibkvm\fR interfaces to
 176 access the running kernel must themselves be 64-bit applications.
 177 .sp
 178 .LP
 179 Although the \fBlibkvm\fR API is Stable, the symbol names and data values that
 180 can be accessed through this set of interfaces are Private and are subject to
 181 ongoing change.
 182 .sp
 183 .LP
 184 Applications using  \fBlibkvm\fR are likely to be platform- and
 185 release-dependent.
 186 .sp
 187 .LP
 188 Most of the traditional uses of \fBlibkvm\fR have been superseded by more
 189 stable interfaces that allow the same information to be extracted more
 190 efficiently, yet  independent of the kernel data model.  For examples, see
 191 \fBsysconf\fR(3C), \fBproc\fR(4), \fBkstat\fR(3KSTAT), \fBgetloadavg\fR(3C),
 192 and \fBpathconf\fR(2).