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 .Dd March 20, 2017
  33 .Dt KVM_OPEN 3
  34 .Os
  35 .Sh NAME
  36 .Nm kvm_open ,
  37 .Nm kvm_open2 ,
  38 .Nm kvm_openfiles ,
  39 .Nm kvm_close
  40 .Nd initialize kernel virtual memory access
  41 .Sh LIBRARY
  42 .Lb libkvm
  43 .Sh SYNOPSIS
  44 .In fcntl.h
  45 .In kvm.h
  46 .Ft kvm_t *
  47 .Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr"
  48 .Ft kvm_t *
  49 .Fo kvm_open2
  50 .Fa "const char *execfile"
  51 .Fa "const char *corefile"
  52 .Fa "int flags"
  53 .Fa "char *errbuf"
  54 .Fa "int (*resolver)(const char *name, kvaddr_t *addr)"
  55 .Fc
  56 .Ft kvm_t *
  57 .Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf"
  58 .Ft int
  59 .Fn kvm_close "kvm_t *kd"
  60 .Sh DESCRIPTION
  61 The functions
  62 .Fn kvm_open ,
  63 .Fn kvm_open2 ,
  64 and
  65 .Fn kvm_openfiles
  66 return a descriptor used to access kernel virtual memory
  67 via the
  68 .Xr kvm 3
  69 library routines.
  70 Both active kernels and crash dumps are accessible
  71 through this interface.
  72 .Pp
  73 The
  74 .Fa execfile
  75 argument is the executable image of the kernel being examined.
  76 This file must contain a symbol table.
  77 If this argument is
  78 .Dv NULL ,
  79 the currently running system is assumed,
  80 as determined from
  81 .Xr getbootfile 3 .
  82 .Pp
  83 The
  84 .Fa corefile
  85 argument is the kernel memory device file.
  86 It can be either
  87 .Pa /dev/mem
  88 or a crash dump core generated by
  89 .Xr savecore 8 .
  90 If
  91 .Fa corefile
  92 is
  93 .Dv NULL ,
  94 the default indicated by
  95 .Dv _PATH_MEM
  96 from
  97 .In paths.h
  98 is used.
  99 It can also be set to a special value
 100 .Pa /dev/null
 101 by utilities like
 102 .Xr ps 1
 103 that do not directly access kernel memory.
 104 .Pp
 105 The
 106 .Fa swapfile
 107 argument is currently unused.
 108 .Pp
 109 The
 110 .Fa flags
 111 argument indicates read/write access as in
 112 .Xr open 2
 113 and applies only to the core file.
 114 Only
 115 .Dv O_RDONLY ,
 116 .Dv O_WRONLY ,
 117 and
 118 .Dv O_RDWR
 119 are permitted.
 120 .Pp
 121 The
 122 .Nm kvm
 123 library provides two different error reporting mechanisms.
 124 One provides backward compatibility with the SunOS kvm library, while the
 125 other provides an improved error reporting framework.
 126 The mechanism used by a descriptor is determined by the function used to
 127 open the descriptor.
 128 .Pp
 129 The
 130 .Fn kvm_open
 131 function is the Sun kvm compatible open call.
 132 Here, the
 133 .Fa errstr
 134 argument indicates how errors should be handled.
 135 If it is
 136 .Dv NULL ,
 137 no errors are reported and the application cannot know the
 138 specific nature of the failed kvm call.
 139 If it is not
 140 .Dv NULL ,
 141 errors are printed to
 142 .Dv stderr
 143 with
 144 .Fa errstr
 145 prepended to the message, as in
 146 .Xr perror 3 .
 147 Normally, the name of the program is used here.
 148 The string is assumed to persist at least until the corresponding
 149 .Fn kvm_close
 150 call.
 151 .Pp
 152 The
 153 .Fn kvm_open2
 154 and
 155 .Fn kvm_openfiles
 156 functions provide
 157 .Bx
 158 style error reporting.
 159 Here, error messages are not printed out by the library.
 160 Instead, the application obtains the error message
 161 corresponding to the most recent kvm library call using
 162 .Fn kvm_geterr
 163 (see
 164 .Xr kvm_geterr 3 ) .
 165 The results are undefined if the most recent kvm call did not produce
 166 an error.
 167 Since
 168 .Fn kvm_geterr
 169 requires a kvm descriptor, but the open routines return
 170 .Dv NULL
 171 on failure,
 172 .Fn kvm_geterr
 173 cannot be used to get the error message if open fails.
 174 Thus,
 175 .Fn kvm_open2
 176 and
 177 .Fn kvm_openfiles
 178 will place any error message in the
 179 .Fa errbuf
 180 argument.
 181 This buffer should be _POSIX2_LINE_MAX characters large (from
 182 <limits.h>).
 183 .Pp
 184 The
 185 .Fa resolver
 186 argument points to a function used by the
 187 .Nm kvm
 188 library to map symbol names to kernel virtual addresses.
 189 When the
 190 .Fa resolver
 191 function is called,
 192 .Fa name
 193 specifies the requested symbol name.
 194 If the function is able to resolve the name to an address,
 195 the address should be set in
 196 .Fa addr
 197 and the function should return zero.
 198 If the function is not able to resolve the name to an address,
 199 it should return a non-zero value.
 200 When opening a native kernel image,
 201 .Fa resolver
 202 may be set to
 203 .Dv NULL
 204 to use an internal function to resolve symbol names.
 205 Non-native kernel images
 206 .Pq such as when cross-debugging a crash dump
 207 require a valid
 208 .Fa resolver .
 209 .Sh RETURN VALUES
 210 The
 211 .Fn kvm_open ,
 212 .Fn kvm_open2 ,
 213 and
 214 .Fn kvm_openfiles
 215 functions return a descriptor to be used
 216 in all subsequent kvm library calls.
 217 The library is fully re-entrant.
 218 On failure,
 219 .Dv NULL
 220 is returned, in which case
 221 .Fn kvm_open2
 222 and
 223 .Fn kvm_openfiles
 224 write the error message into
 225 .Fa errbuf .
 226 .Pp
 227 .Rv -std kvm_close
 228 .Sh ERRORS
 229 The
 230 .Fn kvm_close
 231 function may fail and set the global variable
 232 .Va errno
 233 for any of the errors specified for
 234 .Xr close 2 .
 235 .Pp
 236 The
 237 .Fn kvm_close
 238 function may also fail and set
 239 .Va errno
 240 if:
 241 .Bl -tag -width Er
 242 .It Bq Er EINVAL
 243 The value passed via
 244 .Fa kd
 245 was
 246 .Dv NULL .
 247 .El
 248 .Sh SEE ALSO
 249 .Xr close 2 ,
 250 .Xr open 2 ,
 251 .Xr kvm 3 ,
 252 .Xr kvm_getargv 3 ,
 253 .Xr kvm_getenvv 3 ,
 254 .Xr kvm_geterr 3 ,
 255 .Xr kvm_getprocs 3 ,
 256 .Xr kvm_native 3 ,
 257 .Xr kvm_nlist 3 ,
 258 .Xr kvm_read 3 ,
 259 .Xr kvm_write 3 ,
 260 .Xr kmem 4 ,
 261 .Xr mem 4
 262 .Sh BUGS
 263 There should not be three open calls.
 264 The ill-defined error semantics
 265 of the Sun library and the desire to have a backward-compatible library
 266 for
 267 .Bx
 268 left little choice.
 269 .Sh HISTORY
 270 The
 271 .Fn kvm_open2
 272 function first appeared in
 273 .Fx 11.0 .