lib/libkvm/kvm_open.3

   1 .\" Copyright (c) 1992, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software developed by the Computer Systems
   5 .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
   6 .\" BG 91-66 and contributed to Berkeley.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)kvm_open.3  8.3 (Berkeley) 4/19/94
  33 .\"
  34 .Dd March 20, 2017
  35 .Dt KVM_OPEN 3
  36 .Os
  37 .Sh NAME
  38 .Nm kvm_open ,
  39 .Nm kvm_open2 ,
  40 .Nm kvm_openfiles ,
  41 .Nm kvm_close
  42 .Nd initialize kernel virtual memory access
  43 .Sh LIBRARY
  44 .Lb libkvm
  45 .Sh SYNOPSIS
  46 .In fcntl.h
  47 .In kvm.h
  48 .Ft kvm_t *
  49 .Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr"
  50 .Ft kvm_t *
  51 .Fo kvm_open2
  52 .Fa "const char *execfile"
  53 .Fa "const char *corefile"
  54 .Fa "int flags"
  55 .Fa "char *errbuf"
  56 .Fa "int (*resolver)(const char *name, kvaddr_t *addr)"
  57 .Fc
  58 .Ft kvm_t *
  59 .Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf"
  60 .Ft int
  61 .Fn kvm_close "kvm_t *kd"
  62 .Sh DESCRIPTION
  63 The functions
  64 .Fn kvm_open ,
  65 .Fn kvm_open2 ,
  66 and
  67 .Fn kvm_openfiles
  68 return a descriptor used to access kernel virtual memory
  69 via the
  70 .Xr kvm 3
  71 library routines.
  72 Both active kernels and crash dumps are accessible
  73 through this interface.
  74 .Pp
  75 The
  76 .Fa execfile
  77 argument is the executable image of the kernel being examined.
  78 This file must contain a symbol table.
  79 If this argument is
  80 .Dv NULL ,
  81 the currently running system is assumed,
  82 as determined from
  83 .Xr getbootfile 3 .
  84 .Pp
  85 The
  86 .Fa corefile
  87 argument is the kernel memory device file.
  88 It can be either
  89 .Pa /dev/mem
  90 or a crash dump core generated by
  91 .Xr savecore 8 .
  92 If
  93 .Fa corefile
  94 is
  95 .Dv NULL ,
  96 the default indicated by
  97 .Dv _PATH_MEM
  98 from
  99 .In paths.h
 100 is used.
 101 It can also be set to a special value
 102 .Pa /dev/null
 103 by utilities like
 104 .Xr ps 1
 105 that do not directly access kernel memory.
 106 .Pp
 107 The
 108 .Fa swapfile
 109 argument is currently unused.
 110 .Pp
 111 The
 112 .Fa flags
 113 argument indicates read/write access as in
 114 .Xr open 2
 115 and applies only to the core file.
 116 Only
 117 .Dv O_RDONLY ,
 118 .Dv O_WRONLY ,
 119 and
 120 .Dv O_RDWR
 121 are permitted.
 122 .Pp
 123 The
 124 .Nm kvm
 125 library provides two different error reporting mechanisms.
 126 One provides backward compatibility with the SunOS kvm library, while the
 127 other provides an improved error reporting framework.
 128 The mechanism used by a descriptor is determined by the function used to
 129 open the descriptor.
 130 .Pp
 131 The
 132 .Fn kvm_open
 133 function is the Sun kvm compatible open call.
 134 Here, the
 135 .Fa errstr
 136 argument indicates how errors should be handled.
 137 If it is
 138 .Dv NULL ,
 139 no errors are reported and the application cannot know the
 140 specific nature of the failed kvm call.
 141 If it is not
 142 .Dv NULL ,
 143 errors are printed to
 144 .Dv stderr
 145 with
 146 .Fa errstr
 147 prepended to the message, as in
 148 .Xr perror 3 .
 149 Normally, the name of the program is used here.
 150 The string is assumed to persist at least until the corresponding
 151 .Fn kvm_close
 152 call.
 153 .Pp
 154 The
 155 .Fn kvm_open2
 156 and
 157 .Fn kvm_openfiles
 158 functions provide
 159 .Bx
 160 style error reporting.
 161 Here, error messages are not printed out by the library.
 162 Instead, the application obtains the error message
 163 corresponding to the most recent kvm library call using
 164 .Fn kvm_geterr
 165 (see
 166 .Xr kvm_geterr 3 ) .
 167 The results are undefined if the most recent kvm call did not produce
 168 an error.
 169 Since
 170 .Fn kvm_geterr
 171 requires a kvm descriptor, but the open routines return
 172 .Dv NULL
 173 on failure,
 174 .Fn kvm_geterr
 175 cannot be used to get the error message if open fails.
 176 Thus,
 177 .Fn kvm_open2
 178 and
 179 .Fn kvm_openfiles
 180 will place any error message in the
 181 .Fa errbuf
 182 argument.
 183 This buffer should be _POSIX2_LINE_MAX characters large (from
 184 <limits.h>).
 185 .Pp
 186 The
 187 .Fa resolver
 188 argument points to a function used by the
 189 .Nm kvm
 190 library to map symbol names to kernel virtual addresses.
 191 When the
 192 .Fa resolver
 193 function is called,
 194 .Fa name
 195 specifies the requested symbol name.
 196 If the function is able to resolve the name to an address,
 197 the address should be set in
 198 .Fa addr
 199 and the function should return zero.
 200 If the function is not able to resolve the name to an address,
 201 it should return a non-zero value.
 202 When opening a native kernel image,
 203 .Fa resolver
 204 may be set to
 205 .Dv NULL
 206 to use an internal function to resolve symbol names.
 207 Non-native kernel images
 208 .Pq such as when cross-debugging a crash dump
 209 require a valid
 210 .Fa resolver .
 211 .Sh RETURN VALUES
 212 The
 213 .Fn kvm_open ,
 214 .Fn kvm_open2 ,
 215 and
 216 .Fn kvm_openfiles
 217 functions return a descriptor to be used
 218 in all subsequent kvm library calls.
 219 The library is fully re-entrant.
 220 On failure,
 221 .Dv NULL
 222 is returned, in which case
 223 .Fn kvm_open2
 224 and
 225 .Fn kvm_openfiles
 226 write the error message into
 227 .Fa errbuf .
 228 .Pp
 229 .Rv -std kvm_close
 230 .Sh ERRORS
 231 The
 232 .Fn kvm_close
 233 function may fail and set the global variable
 234 .Va errno
 235 for any of the errors specified for
 236 .Xr close 2 .
 237 .Pp
 238 The
 239 .Fn kvm_close
 240 function may also fail and set
 241 .Va errno
 242 if:
 243 .Bl -tag -width Er
 244 .It Bq Er EINVAL
 245 The value passed via
 246 .Fa kd
 247 was
 248 .Dv NULL .
 249 .El
 250 .Sh SEE ALSO
 251 .Xr close 2 ,
 252 .Xr open 2 ,
 253 .Xr kvm 3 ,
 254 .Xr kvm_getargv 3 ,
 255 .Xr kvm_getenvv 3 ,
 256 .Xr kvm_geterr 3 ,
 257 .Xr kvm_getprocs 3 ,
 258 .Xr kvm_native 3 ,
 259 .Xr kvm_nlist 3 ,
 260 .Xr kvm_read 3 ,
 261 .Xr kvm_write 3 ,
 262 .Xr kmem 4 ,
 263 .Xr mem 4
 264 .Sh BUGS
 265 There should not be three open calls.
 266 The ill-defined error semantics
 267 of the Sun library and the desire to have a backward-compatible library
 268 for
 269 .Bx
 270 left little choice.
 271 .Sh HISTORY
 272 The
 273 .Fn kvm_open2
 274 function first appeared in
 275 .Fx 11.0 .