xref: /freebsd/lib/libkvm/kvm_read.3 (revision 608da65de9552d5678c1000776ed69da04a45983)
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.\"
34.Dd November 27, 2015
35.Dt KVM_READ 3
36.Os
37.Sh NAME
38.Nm kvm_read ,
39.Nm kvm_read2 ,
40.Nm kvm_write
41.Nd read or write kernel virtual memory
42.Sh LIBRARY
43.Lb libkvm
44.Sh SYNOPSIS
45.In kvm.h
46.Ft ssize_t
47.Fn kvm_read "kvm_t *kd" "unsigned long addr" "void *buf" "size_t nbytes"
48.Ft ssize_t
49.Fn kvm_read2 "kvm_t *kd" "kvaddr_t addr" "void *buf" "size_t nbytes"
50.Ft ssize_t
51.Fn kvm_write "kvm_t *kd" "unsigned long addr" "const void *buf" "size_t nbytes"
52.Sh DESCRIPTION
53The
54.Fn kvm_read ,
55.Fn kvm_read2 ,
56and
57.Fn kvm_write
58functions are used to read and write kernel virtual memory (or a crash
59dump file).
60See
61.Fn kvm_open 3
62for information regarding opening kernel virtual memory and crash dumps.
63.Pp
64The
65.Fn kvm_read
66and
67.Fn kvm_read2
68functions transfer
69.Fa nbytes
70bytes of data from
71the kernel space address
72.Fa addr
73to
74.Fa buf .
75Conversely,
76.Fn kvm_write
77transfers data from
78.Fa buf
79to
80.Fa addr .
81Unlike their SunOS counterparts, these functions cannot be used to
82read or write process address spaces.
83.Pp
84The
85.Fn kvm_read2
86function uses a different type
87.Pq Vt kvaddr_t
88for the
89.Fa addr
90argument to allow use of addresses larger than
91.Dv ULONG_MAX
92when examining non-native kernel images.
93.Sh RETURN VALUES
94Upon success, the number of bytes actually transferred is returned.
95Otherwise, -1 is returned.
96.Sh SEE ALSO
97.Xr kvm 3 ,
98.Xr kvm_close 3 ,
99.Xr kvm_getargv 3 ,
100.Xr kvm_getenvv 3 ,
101.Xr kvm_geterr 3 ,
102.Xr kvm_getprocs 3 ,
103.Xr kvm_nlist 3 ,
104.Xr kvm_open 3 ,
105.Xr kvm_openfiles 3
106.Sh HISTORY
107The
108.Fn kvm_read2
109function first appeared in
110.Fx 11.0 .
111