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