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