lib/libkvm/kvm_open.3

   1 .\"     $NetBSD: kvm_open.3,v 1.18 2011/09/12 21:11:32 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1992, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software developed by the Computer Systems
   7 .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
   8 .\" BG 91-66 and contributed to Berkeley.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)kvm_open.3  8.3 (Berkeley) 4/19/94
  35 .\"
  36 .Dd September 14, 2011
  37 .Dt KVM_OPEN 3
  38 .Os
  39 .Sh NAME
  40 .Nm kvm_open ,
  41 .Nm kvm_openfiles ,
  42 .Nm kvm_close
  43 .Nd initialize kernel virtual memory access
  44 .Sh LIBRARY
  45 .Lb libkvm
  46 .Sh SYNOPSIS
  47 .In fcntl.h
  48 .In kvm.h
  49 .Ft kvm_t *
  50 .Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr"
  51 .Ft kvm_t *
  52 .Fn kvm_openfiles "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "char *errbuf"
  53 .Ft int
  54 .Fn kvm_close "kvm_t *kd"
  55 .Sh DESCRIPTION
  56 The functions
  57 .Fn kvm_open
  58 and
  59 .Fn kvm_openfiles
  60 return a descriptor used to access kernel virtual memory
  61 via the
  62 .Xr kvm 3
  63 library routines.
  64 Both active kernels and crash dumps are accessible
  65 through this interface.
  66 .Pp
  67 .Fa execfile
  68 is the executable image of the kernel being examined.
  69 This file must contain a symbol table.
  70 If this argument is
  71 .Dv NULL ,
  72 the currently running system is assumed; in this case, the functions will
  73 attempt to use the
  74 .Xr ksyms 4
  75 device indicated by
  76 .Dv _PATH_KSYMS
  77 in
  78 .In paths.h ;
  79 if that fails, then they will use the file indicated by the
  80 .Xr sysctl 3
  81 variable
  82 .Va machdep.booted_kernel ,
  83 or (if the sysctl information is not available)
  84 the default kernel path indicated by
  85 .Dv _PATH_UNIX
  86 in
  87 .In paths.h .
  88 .Pp
  89 .Fa corefile
  90 is the kernel memory device file.
  91 It can be either
  92 .Pa /dev/mem
  93 or a crash dump core generated by
  94 .Xr savecore 8 .
  95 If
  96 .Fa corefile
  97 is
  98 .Dv NULL ,
  99 the default indicated by
 100 .Dv _PATH_MEM
 101 from
 102 .In paths.h
 103 is used.
 104 .Pp
 105 .Fa swapfile
 106 should indicate the swap device.
 107 If
 108 .Dv NULL ,
 109 .Dv _PATH_DRUM
 110 from
 111 .In paths.h
 112 is used.
 113 .Pp
 114 The
 115 .Fa flags
 116 argument indicates read/write access as in
 117 .Xr open 2
 118 and applies only to the core file.
 119 The only permitted flags from
 120 .Xr open 2
 121 are
 122 .Dv O_RDONLY ,
 123 .Dv O_WRONLY ,
 124 and
 125 .Dv O_RDWR .
 126 .Pp
 127 As a special case, a
 128 .Fa flags
 129 argument of
 130 .Dv KVM_NO_FILES
 131 will initialize the
 132 .Xr kvm 3
 133 library for use on active kernels only using
 134 .Xr sysctl 3
 135 for retrieving kernel data and ignores the
 136 .Fa execfile ,
 137 .Fa corefile
 138 and
 139 .Fa swapfile
 140 arguments.
 141 Only a small subset of the
 142 .Xr kvm 3
 143 library functions are available using this method.
 144 These are currently
 145 .Xr kvm_getproc2 3 ,
 146 .Xr kvm_getargv2 3
 147 and
 148 .Xr kvm_getenvv2 3 .
 149 .Pp
 150 There are two open routines which differ only with respect to
 151 the error mechanism.
 152 One provides backward compatibility with the SunOS kvm library, while the
 153 other provides an improved error reporting framework.
 154 .Pp
 155 The
 156 .Fn kvm_open
 157 function is the Sun kvm compatible open call.
 158 Here, the
 159 .Fa errstr
 160 argument indicates how errors should be handled.
 161 If it is
 162 .Dv NULL ,
 163 no errors are reported and the application cannot know the
 164 specific nature of the failed kvm call.
 165 If it is not
 166 .Dv NULL ,
 167 errors are printed to stderr with
 168 .Fa errstr
 169 prepended to the message, as in
 170 .Xr perror 3 .
 171 Normally, the name of the program is used here.
 172 The string is assumed to persist at least until the corresponding
 173 .Fn kvm_close
 174 call.
 175 .Pp
 176 The
 177 .Fn kvm_openfiles
 178 function provides
 179 .Bx
 180 style error reporting.
 181 Here, error messages are not printed out by the library.
 182 Instead, the application obtains the error message
 183 corresponding to the most recent kvm library call using
 184 .Fn kvm_geterr
 185 (see
 186 .Xr kvm_geterr 3 ) .
 187 The results are undefined if the most recent kvm call did not produce
 188 an error.
 189 Since
 190 .Fn kvm_geterr
 191 requires a kvm descriptor, but the open routines return
 192 .Dv NULL
 193 on failure,
 194 .Fn kvm_geterr
 195 cannot be used to get the error message if open fails.
 196 Thus,
 197 .Fn kvm_openfiles
 198 will place any error message in the
 199 .Fa errbuf
 200 argument.
 201 This buffer should be _POSIX2_LINE_MAX characters large (from
 202 .In limits.h ) .
 203 .Sh RETURN VALUES
 204 The
 205 .Fn kvm_open
 206 and
 207 .Fn kvm_openfiles
 208 functions both return a descriptor to be used
 209 in all subsequent kvm library calls.
 210 The library is fully re-entrant.
 211 On failure,
 212 .Dv NULL
 213 is returned, in which case
 214 .Fn kvm_openfiles
 215 writes the error message into
 216 .Fa errbuf .
 217 .Pp
 218 The
 219 .Fn kvm_close
 220 function returns 0 on success and -1 on failure.
 221 .Sh SEE ALSO
 222 .Xr open 2 ,
 223 .Xr kvm 3 ,
 224 .Xr kvm_getargv 3 ,
 225 .Xr kvm_getenvv 3 ,
 226 .Xr kvm_geterr 3 ,
 227 .Xr kvm_getkernelname 3 ,
 228 .Xr kvm_getprocs 3 ,
 229 .Xr kvm_nlist 3 ,
 230 .Xr kvm_read 3 ,
 231 .Xr kvm_write 3
 232 .Sh BUGS
 233 There should not be two open calls.
 234 The ill-defined error semantics of the Sun library
 235 and the desire to have a backward-compatible library for
 236 .Bx
 237 left little choice.