gitweb.dragonflybsd.org Git - dragonfly.git/blame_incremental

... / ...

Commit	Line	Data
	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