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. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)kvm_open.3  8.3 (Berkeley) 4/19/94
  37 .\" $FreeBSD$
  38 .\"
  39 .Dd January 29, 2004
  40 .Dt KVM_OPEN 3
  41 .Os
  42 .Sh NAME
  43 .Nm kvm_open ,
  44 .Nm kvm_openfiles ,
  45 .Nm kvm_close
  46 .Nd initialize kernel virtual memory access
  47 .Sh LIBRARY
  48 .Lb libkvm
  49 .Sh SYNOPSIS
  50 .In fcntl.h
  51 .In kvm.h
  52 .Ft kvm_t *
  53 .Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr"
  54 .Ft kvm_t *
  55 .Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf"
  56 .Ft int
  57 .Fn kvm_close "kvm_t *kd"
  58 .Sh DESCRIPTION
  59 The functions
  60 .Fn kvm_open
  61 and
  62 .Fn kvm_openfiles
  63 return a descriptor used to access kernel virtual memory
  64 via the
  65 .Xr kvm 3
  66 library routines.
  67 Both active kernels and crash dumps are accessible
  68 through this interface.
  69 .Pp
  70 The
  71 .Fa execfile
  72 argument is the executable image of the kernel being examined.
  73 This file must contain a symbol table.
  74 If this argument is
  75 .Dv NULL ,
  76 the currently running system is assumed,
  77 as determined from
  78 .Xr getbootfile 3 .
  79 .Pp
  80 The
  81 .Fa corefile
  82 argument is the kernel memory device file.
  83 It can be either
  84 .Pa /dev/mem
  85 or a crash dump core generated by
  86 .Xr savecore 8 .
  87 If
  88 .Fa corefile
  89 is
  90 .Dv NULL ,
  91 the default indicated by
  92 .Dv _PATH_MEM
  93 from
  94 .In paths.h
  95 is used.
  96 It can also be set to a special value
  97 .Pa /dev/null
  98 by utilities like
  99 .Xr ps 1
 100 that do not directly access kernel memory.
 101 .Pp
 102 The
 103 .Fa swapfile
 104 argument is currently unused.
 105 .Pp
 106 The
 107 .Fa flags
 108 argument indicates read/write access as in
 109 .Xr open 2
 110 and applies only to the core file.
 111 Only
 112 .Dv O_RDONLY ,
 113 .Dv O_WRONLY ,
 114 and
 115 .Dv O_RDWR
 116 are permitted.
 117 .Pp
 118 There are two open routines which differ only with respect to
 119 the error mechanism.
 120 One provides backward compatibility with the SunOS kvm library, while the
 121 other provides an improved error reporting framework.
 122 .Pp
 123 The
 124 .Fn kvm_open
 125 function is the Sun kvm compatible open call.
 126 Here, the
 127 .Fa errstr
 128 argument indicates how errors should be handled.
 129 If it is
 130 .Dv NULL ,
 131 no errors are reported and the application cannot know the
 132 specific nature of the failed kvm call.
 133 If it is not
 134 .Dv NULL ,
 135 errors are printed to
 136 .Dv stderr
 137 with
 138 .Fa errstr
 139 prepended to the message, as in
 140 .Xr perror 3 .
 141 Normally, the name of the program is used here.
 142 The string is assumed to persist at least until the corresponding
 143 .Fn kvm_close
 144 call.
 145 .Pp
 146 The
 147 .Fn kvm_openfiles
 148 function provides
 149 .Bx
 150 style error reporting.
 151 Here, error messages are not printed out by the library.
 152 Instead, the application obtains the error message
 153 corresponding to the most recent kvm library call using
 154 .Fn kvm_geterr
 155 (see
 156 .Xr kvm_geterr 3 ) .
 157 The results are undefined if the most recent kvm call did not produce
 158 an error.
 159 Since
 160 .Fn kvm_geterr
 161 requires a kvm descriptor, but the open routines return
 162 .Dv NULL
 163 on failure,
 164 .Fn kvm_geterr
 165 cannot be used to get the error message if open fails.
 166 Thus,
 167 .Fn kvm_openfiles
 168 will place any error message in the
 169 .Fa errbuf
 170 argument.
 171 This buffer should be _POSIX2_LINE_MAX characters large (from
 172 <limits.h>).
 173 .Sh RETURN VALUES
 174 The
 175 .Fn kvm_open
 176 and
 177 .Fn kvm_openfiles
 178 functions both return a descriptor to be used
 179 in all subsequent kvm library calls.
 180 The library is fully re-entrant.
 181 On failure,
 182 .Dv NULL
 183 is returned, in which case
 184 .Fn kvm_openfiles
 185 writes the error message into
 186 .Fa errbuf .
 187 .Pp
 188 The
 189 .Fn kvm_close
 190 function returns 0 on success and -1 on failure.
 191 .Sh SEE ALSO
 192 .Xr open 2 ,
 193 .Xr kvm 3 ,
 194 .Xr kvm_getargv 3 ,
 195 .Xr kvm_getenvv 3 ,
 196 .Xr kvm_geterr 3 ,
 197 .Xr kvm_getprocs 3 ,
 198 .Xr kvm_nlist 3 ,
 199 .Xr kvm_read 3 ,
 200 .Xr kvm_write 3 ,
 201 .Xr kmem 4 ,
 202 .Xr mem 4
 203 .Sh BUGS
 204 There should not be two open calls.
 205 The ill-defined error semantics
 206 of the Sun library and the desire to have a backward-compatible library
 207 for
 208 .Bx
 209 left little choice.