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. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)kvm_read.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD: src/lib/libkvm/kvm_read.3,v 1.6.2.3 2001/12/17 10:08:30 ru Exp $ 34.\" $DragonFly: src/lib/libkvm/kvm_read.3,v 1.4 2008/09/07 08:36:54 swildner Exp $ 35.\" 36.Dd January 8, 2006 37.Dt KVM_READ 3 38.Os 39.Sh NAME 40.Nm kvm_read , 41.Nm kvm_readstr , 42.Nm kvm_write 43.Nd read or write kernel virtual memory 44.Sh LIBRARY 45.Lb libkvm 46.Sh SYNOPSIS 47.In sys/types.h 48.In kvm.h 49.Ft ssize_t 50.Fn kvm_read "kvm_t *kd" "unsigned long addr" "void *buf" "size_t nbytes" 51.Ft "char *" 52.Fn kvm_readstr "kvm_t *kd" "unsigned long addr" "char *buf" "size_t *len" 53.Ft ssize_t 54.Fn kvm_write "kvm_t *kd" "unsigned long addr" "const void *buf" "size_t nbytes" 55.Sh DESCRIPTION 56The 57.Fn kvm_read , 58.Fn kvm_readstr 59and 60.Fn kvm_write 61functions are used to read and write kernel virtual memory (or a crash 62dump file). See 63.Fn kvm_open 3 64or 65.Fn kvm_openfiles 3 66for information regarding opening kernel virtual memory and crash dumps. 67.Pp 68The 69.Fn kvm_read 70function transfers 71.Fa nbytes 72bytes of data from 73the kernel space address 74.Fa addr 75to 76.Fa buf . 77Conversely, 78.Fn kvm_write 79transfers data from 80.Fa buf 81to 82.Fa addr . 83Unlike their SunOS counterparts, these functions cannot be used to 84read or write process address spaces. 85.Pp 86The 87.Fn kvm_readstr 88function exists for convenience to read NUL terminated strings 89from the kernel address space. 90If 91.Fa buf 92is 93.Dv NULL , 94.Fn kvm_readstr 95will allocate a sufficiently large buffer, which needs to be 96deallocated via 97.Xr free 3 98by the caller. 99If 100.Fa len 101is not 102.Dv NULL , 103.Fn kvm_readstr 104will interpret the value it is pointing to as the size of 105.Fa buf 106and will store the size of the complete string at 107.Fa addr . 108Note that if only 109.Fa buf 110is too small to hold the complete string, 111.Fn kvm_readstr 112will return 113.Dv NULL 114but set 115.Fa len 116to the size needed. 117.Sh RETURN VALUES 118For 119.Fn kvm_read 120and 121.Fn kvm_write 122the number of bytes actually transferred is returned, if the request 123was successful. 124Otherwise, -1 is returned. 125.Pp 126For 127.Fn kvm_readstr 128.Dv NULL 129is returned on failure. 130Upon success, the address of the string is returned, which will be 131.Fa buf 132if this was supplied. 133.Sh SEE ALSO 134.Xr kvm 3 , 135.Xr kvm_close 3 , 136.Xr kvm_getargv 3 , 137.Xr kvm_getenvv 3 , 138.Xr kvm_geterr 3 , 139.Xr kvm_getprocs 3 , 140.Xr kvm_nlist 3 , 141.Xr kvm_open 3 , 142.Xr kvm_openfiles 3 143