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 .\" $FreeBSD: src/lib/libkvm/kvm_open.3,v 1.5.2.6 2001/12/17 10:08:30 ru Exp $
  34 .\" $DragonFly: src/lib/libkvm/kvm_open.3,v 1.4 2006/05/26 19:39:38 swildner Exp $
  35 .\"
  36 .Dd May 5, 2009
  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 sys/types.h
  48 .In kvm.h
  49 .Ft kvm_t *
  50 .Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr"
  51 .Ft kvm_t *
  52 .Fn kvm_openfiles "const char *execfile" "const char *corefile" "const 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.  Both active kernels (including vkernels) and crash
  64 dumps are accessible through this interface.
  65 .Pp
  66 .Fa execfile
  67 is the executable image of the kernel being examined.
  68 This file must contain a symbol table.
  69 If this argument is
  70 .Dv NULL ,
  71 the currently running system is assumed,
  72 as determined from
  73 .Xr getbootfile 3 .
  74 .Pp
  75 .Fa corefile
  76 is the kernel memory device file.  It can be /dev/mem, the path to
  77 the procfs mem file for a running vkernel (i.e. /proc/$pid/mem)
  78 or a crash dump core generated by
  79 .Xr savecore 8 .
  80 If
  81 .Fa corefile
  82 is
  83 .Dv NULL ,
  84 the default indicated by
  85 .Dv _PATH_MEM
  86 from
  87 .In paths.h
  88 is used.
  89 .Pp
  90 .Fa swapfile
  91 should indicate the swap device.  If
  92 .Dv NULL ,
  93 .Dv _PATH_DRUM
  94 from
  95 .In paths.h
  96 is used.
  97 .Pp
  98 The
  99 .Fa flags
 100 argument indicates read/write access as in
 101 .Xr open 2
 102 and applies only to the core file.
 103 Only
 104 .Dv O_RDONLY ,
 105 .Dv O_WRONLY ,
 106 and
 107 .Dv O_RDWR
 108 are permitted.
 109 .Pp
 110 There are two open routines which differ only with respect to
 111 the error mechanism.
 112 One provides backward compatibility with the SunOS kvm library, while the
 113 other provides an improved error reporting framework.
 114 .Pp
 115 The
 116 .Fn kvm_open
 117 function is the Sun kvm compatible open call.  Here, the
 118 .Fa errstr
 119 argument indicates how errors should be handled.  If it is
 120 .Dv NULL ,
 121 no errors are reported and the application cannot know the
 122 specific nature of the failed kvm call.
 123 If it is not
 124 .Dv NULL ,
 125 errors are printed to stderr with
 126 .Fa errstr
 127 prepended to the message, as in
 128 .Xr perror 3 .
 129 Normally, the name of the program is used here.
 130 The string is assumed to persist at least until the corresponding
 131 .Fn kvm_close
 132 call.
 133 .Pp
 134 The
 135 .Fn kvm_openfiles
 136 function provides
 137 .Bx
 138 style error reporting.
 139 Here, error messages are not printed out by the library.
 140 Instead, the application obtains the error message
 141 corresponding to the most recent kvm library call using
 142 .Fn kvm_geterr
 143 (see
 144 .Xr kvm_geterr 3 ) .
 145 The results are undefined if the most recent kvm call did not produce
 146 an error.
 147 Since
 148 .Fn kvm_geterr
 149 requires a kvm descriptor, but the open routines return
 150 .Dv NULL
 151 on failure,
 152 .Fn kvm_geterr
 153 cannot be used to get the error message if open fails.
 154 Thus,
 155 .Fn kvm_openfiles
 156 will place any error message in the
 157 .Fa errbuf
 158 argument.  This buffer should be _POSIX2_LINE_MAX characters large (from
 159 .In limits.h ) .
 160 .Sh RETURN VALUES
 161 The
 162 .Fn kvm_open
 163 and
 164 .Fn kvm_openfiles
 165 functions both return a descriptor to be used
 166 in all subsequent kvm library calls.
 167 The library is fully re-entrant.
 168 On failure,
 169 .Dv NULL
 170 is returned, in which case
 171 .Fn kvm_openfiles
 172 writes the error message into
 173 .Fa errbuf .
 174 .Pp
 175 The
 176 .Fn kvm_close
 177 function returns 0 on success and -1 on failure.
 178 .Sh SEE ALSO
 179 .Xr open 2 ,
 180 .Xr kvm 3 ,
 181 .Xr kvm_getargv 3 ,
 182 .Xr kvm_getenvv 3 ,
 183 .Xr kvm_geterr 3 ,
 184 .Xr kvm_getprocs 3 ,
 185 .Xr kvm_nlist 3 ,
 186 .Xr kvm_read 3 ,
 187 .Xr kvm_write 3
 188 .Sh BUGS
 189 There should not be two open calls.  The ill-defined error semantics
 190 of the Sun library and the desire to have a backward-compatible library
 191 for
 192 .Bx
 193 left little choice.