lib/libkvm/kvm_read.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_read.3  8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libkvm/kvm_read.3,v 1.6.2.3 2001/12/17 10:08:30 ru Exp $
  38 .\" $DragonFly: src/lib/libkvm/kvm_read.3,v 1.4 2008/09/07 08:36:54 swildner Exp $
  39 .\"
  40 .Dd January 8, 2006
  41 .Dt KVM_READ 3
  42 .Os
  43 .Sh NAME
  44 .Nm kvm_read ,
  45 .Nm kvm_readstr ,
  46 .Nm kvm_write
  47 .Nd read or write kernel virtual memory
  48 .Sh LIBRARY
  49 .Lb libkvm
  50 .Sh SYNOPSIS
  51 .In kvm.h
  52 .Ft ssize_t
  53 .Fn kvm_read "kvm_t *kd" "unsigned long addr" "void *buf" "size_t nbytes"
  54 .Ft "char *"
  55 .Fn kvm_readstr "kvm_t *kd" "unsigned long addr" "char *buf" "size_t *len"
  56 .Ft ssize_t
  57 .Fn kvm_write "kvm_t *kd" "unsigned long addr" "const void *buf" "size_t nbytes"
  58 .Sh DESCRIPTION
  59 The
  60 .Fn kvm_read ,
  61 .Fn kvm_readstr
  62 and
  63 .Fn kvm_write
  64 functions are used to read and write kernel virtual memory (or a crash
  65 dump file). See
  66 .Fn kvm_open 3
  67 or
  68 .Fn kvm_openfiles 3
  69 for information regarding opening kernel virtual memory and crash dumps.
  70 .Pp
  71 The
  72 .Fn kvm_read
  73 function transfers
  74 .Fa nbytes
  75 bytes of data from
  76 the kernel space address
  77 .Fa addr
  78 to
  79 .Fa buf .
  80 Conversely,
  81 .Fn kvm_write
  82 transfers data from
  83 .Fa buf
  84 to
  85 .Fa addr .
  86 Unlike their SunOS counterparts, these functions cannot be used to
  87 read or write process address spaces.
  88 .Pp
  89 The
  90 .Fn kvm_readstr
  91 function exists for convenience to read NUL terminated strings
  92 from the kernel address space.
  93 If
  94 .Fa buf
  95 is
  96 .Dv NULL ,
  97 .Fn kvm_readstr
  98 will allocate a sufficiently large buffer, which needs to be
  99 deallocated via
 100 .Xr free 3
 101 by the caller.
 102 If
 103 .Fa len
 104 is not
 105 .Dv NULL ,
 106 .Fn kvm_readstr
 107 will interpret the value it is pointing to as the size of
 108 .Fa buf
 109 and will store the size of the complete string at
 110 .Fa addr .
 111 Note that if only
 112 .Fa buf
 113 is too small to hold the complete string,
 114 .Fn kvm_readstr
 115 will return
 116 .Dv NULL
 117 but set
 118 .Fa len
 119 to the size needed.
 120 .Sh RETURN VALUES
 121 For
 122 .Fn kvm_read
 123 and
 124 .Fn kvm_write
 125 the number of bytes actually transferred is returned, if the request
 126 was successful.
 127 Otherwise, -1 is returned.
 128 .Pp
 129 For
 130 .Fn kvm_readstr
 131 .Dv NULL
 132 is returned on failure.
 133 Upon success, the address of the string is returned, which will be
 134 .Fa buf
 135 if this was supplied.
 136 .Sh SEE ALSO
 137 .Xr kvm 3 ,
 138 .Xr kvm_close 3 ,
 139 .Xr kvm_getargv 3 ,
 140 .Xr kvm_getenvv 3 ,
 141 .Xr kvm_geterr 3 ,
 142 .Xr kvm_getprocs 3 ,
 143 .Xr kvm_nlist 3 ,
 144 .Xr kvm_open 3 ,
 145 .Xr kvm_openfiles 3