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