diff options
Diffstat (limited to 'usr/src/man/man3kvm')
| -rw-r--r-- | usr/src/man/man3kvm/Makefile | 56 | ||||
| -rw-r--r-- | usr/src/man/man3kvm/kvm_getu.3kvm | 110 | ||||
| -rw-r--r-- | usr/src/man/man3kvm/kvm_kread.3kvm | 88 | ||||
| -rw-r--r-- | usr/src/man/man3kvm/kvm_nextproc.3kvm | 96 | ||||
| -rw-r--r-- | usr/src/man/man3kvm/kvm_nlist.3kvm | 68 | ||||
| -rw-r--r-- | usr/src/man/man3kvm/kvm_open.3kvm | 204 | ||||
| -rw-r--r-- | usr/src/man/man3kvm/kvm_read.3kvm | 71 |
7 files changed, 693 insertions, 0 deletions
diff --git a/usr/src/man/man3kvm/Makefile b/usr/src/man/man3kvm/Makefile new file mode 100644 index 0000000000..6ad1452b08 --- /dev/null +++ b/usr/src/man/man3kvm/Makefile @@ -0,0 +1,56 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3kvm + +MANFILES = kvm_getu.3kvm \ + kvm_kread.3kvm \ + kvm_nextproc.3kvm \ + kvm_nlist.3kvm \ + kvm_open.3kvm \ + kvm_read.3kvm + +MANSOFILES = kvm_close.3kvm \ + kvm_getcmd.3kvm \ + kvm_getproc.3kvm \ + kvm_kwrite.3kvm \ + kvm_setproc.3kvm \ + kvm_uread.3kvm \ + kvm_uwrite.3kvm \ + kvm_write.3kvm + +MANFILES += $(MANSOFILES) + +kvm_getcmd.3kvm := SOSRC = man3kvm/kvm_getu.3kvm + +kvm_kwrite.3kvm := SOSRC = man3kvm/kvm_kread.3kvm +kvm_uread.3kvm := SOSRC = man3kvm/kvm_kread.3kvm +kvm_uwrite.3kvm := SOSRC = man3kvm/kvm_kread.3kvm + +kvm_getproc.3kvm := SOSRC = man3kvm/kvm_nextproc.3kvm +kvm_setproc.3kvm := SOSRC = man3kvm/kvm_nextproc.3kvm + +kvm_close.3kvm := SOSRC = man3kvm/kvm_open.3kvm + +kvm_write.3kvm := SOSRC = man3kvm/kvm_read.3kvm + + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + + diff --git a/usr/src/man/man3kvm/kvm_getu.3kvm b/usr/src/man/man3kvm/kvm_getu.3kvm new file mode 100644 index 0000000000..9b3fcf0242 --- /dev/null +++ b/usr/src/man/man3kvm/kvm_getu.3kvm @@ -0,0 +1,110 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kvm_getu 3KVM "2 May 2002" "SunOS 5.11" "Kernel VM Library Functions" +.SH NAME +kvm_getu, kvm_getcmd \- get the u-area or invocation arguments for a process +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kvm.h> +#include <sys/param.h> +#include <sys/user.h> +#include <sys/proc.h> + +\fBstruct user *\fR\fBkvm_getu\fR(\fBkvm_t *\fR\fIkd\fR, \fBstruct proc *\fR\fIproc\fR); +.fi + +.LP +.nf +\fBint\fR \fBkvm_getcmd\fR(\fBkvm_t *\fR\fIkd\fR, \fBstruct proc *\fR\fIproc\fR, \fBstruct user *\fR\fIu\fR, \fBchar ***\fR\fIarg\fR, + \fBchar ***\fR\fIenv\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkvm_getu()\fR function reads the u-area of the process specified by +\fIproc\fR to an area of static storage associated with \fIkd\fR and returns a +pointer to it. Subsequent calls to \fBkvm_getu()\fR will overwrite this static +area. +.sp +.LP +The \fIkd\fR argument is a pointer to a kernel descriptor returned by +\fBkvm_open\fR(3KVM). The \fIproc\fR argument is a pointer to a copy in the +current process's address space of a \fIproc\fR structure, obtained, for +instance, by a prior \fBkvm_nextproc\fR(3KVM) call. +.sp +.LP +The \fBkvm_getcmd()\fR function constructs a list of string pointers that +represent the command arguments and environment that were used to initiate the +process specified by \fIproc\fR. +.sp +.LP +The \fIkd\fR argument is a pointer to a kernel descriptor returned by +\fBkvm_open\fR(3KVM). The \fIu\fR argument is a pointer to a copy in the +current process's address space of a \fBuser\fR structure, obtained, for +instance, by a prior \fBkvm_getu()\fR call. If \fIarg\fR is not \fINULL\fR, the +command line arguments are formed into a null-terminated array of string +pointers. The address of the first such pointer is returned in \fIarg\fR. If +\fIenv\fR is not \fINULL\fR, the environment is formed into a null-terminated +array of string pointers. The address of the first of these is returned in +\fIenv\fR. +.sp +.LP +The pointers returned in \fIarg\fR and \fIenv\fR refer to data allocated by +\fBmalloc()\fR and should be freed by a call to \fBfree()\fR when no longer +needed. See \fBmalloc\fR(3C). Both the string pointers and the strings +themselves are deallocated when freed. +.sp +.LP +Since the environment and command line arguments might have been modified by +the user process, there is no guarantee that it will be possible to reconstruct +the original command at all. The \fBkvm_getcmd()\fR function will make the +best attempt possible, returning \(mi1 if the user process data is +unrecognizable. +.SH RETURN VALUES +.sp +.LP +On success, \fBkvm_getu()\fR returns a pointer to a copy of the u-area of the +process specified by \fIproc\fR. On failure, it returns \fINULL\fR. +.sp +.LP +The \fBkvm_getcmd()\fR function returns 0 on success and \(mi1 on failure. If +\(mi1 is returned, the caller still has the option of using the command line +fragment that is stored in the u-area. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkvm_nextproc\fR(3KVM), \fBkvm_open\fR(3KVM), \fBkvm_kread\fR(3KVM), +\fBmalloc\fR(3C), \fBlibkvm\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +On systems that support both 32-bit and 64-bit processes, the 64-bit +implementation of \fBlibkvm\fR ensures that the \fIarg\fR and \fBenv\fR pointer +arrays for \fBkvm_getcmd()\fR are translated to the same form as if they were +64-bit processes. Applications that wish to access the raw 32-bit stack +directly can use \fBkvm_uread()\fR. See \fBkvm_read\fR(3KVM). diff --git a/usr/src/man/man3kvm/kvm_kread.3kvm b/usr/src/man/man3kvm/kvm_kread.3kvm new file mode 100644 index 0000000000..714d4f3f89 --- /dev/null +++ b/usr/src/man/man3kvm/kvm_kread.3kvm @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kvm_kread 3KVM "2 May 2002" "SunOS 5.11" "Kernel VM Library Functions" +.SH NAME +kvm_kread, kvm_kwrite, kvm_uread, kvm_uwrite \- copy data to or from a kernel +image or running system +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kvm.h> + +\fBssize_t\fR \fBkvm_kread\fR(\fBkvm_t *\fR\fIkd\fR, \fBuintptr_t\fR \fIaddr\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbytes\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBkvm_kwrite\fR(\fBkvm_t *\fR\fIkd\fR, \fBuintptr_t\fR \fIaddr\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbytes\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBkvm_uread\fR(\fBkvm_t\fR \fI*kd\fR, \fBuintptr_t\fR \fIaddr\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbytes\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBkvm_uwrite\fR(\fBkvm_t *\fR\fIkd\fR, \fBuintptr_t\fR \fIaddr\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbytes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkvm_kread()\fR function transfers data from the kernel address space to +the address space of the process. \fInbytes\fR bytes of data are copied from +the kernel virtual address given by \fIaddr\fR to the buffer pointed to by +\fIbuf\fR. +.sp +.LP +The \fBkvm_kwrite()\fR function is like \fBkvm_kread()\fR, except that the +direction of the transfer is reversed. To use this function, the +\fBkvm_open\fR(3KVM) call that returned \fIkd\fR must have specified write +access. +.sp +.LP +The \fBkvm_uread()\fR function transfers data from the address space of the +processes specified in the most recent \fBkvm_getu\fR(3KVM) call. \fInbytes\fR +bytes of data are copied from the user virtual address given by \fIaddr\fR to +the buffer pointed to by \fIbuf\fR. +.sp +.LP +The \fBkvm_uwrite()\fR function is like \fBkvm_uread()\fR, except that the +direction of the transfer is reversed. To use this function, the +\fBkvm_open\fR(3KVM) call that returned \fIkd\fR must have specified write +access. The address is resolved in the address space of the process specified +in the most recent \fBkvm_getu\fR(3KVM) call. +.SH RETURN VALUES +.sp +.LP +On success, these functions return the number of bytes actually transferred. On +failure, they return \(mi1. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkvm_getu\fR(3KVM), \fBkvm_nlist\fR(3KVM), \fBkvm_open\fR(3KVM), +\fBattributes\fR(5) diff --git a/usr/src/man/man3kvm/kvm_nextproc.3kvm b/usr/src/man/man3kvm/kvm_nextproc.3kvm new file mode 100644 index 0000000000..c14e4f742d --- /dev/null +++ b/usr/src/man/man3kvm/kvm_nextproc.3kvm @@ -0,0 +1,96 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kvm_nextproc 3KVM "2 May 2002" "SunOS 5.11" "Kernel VM Library Functions" +.SH NAME +kvm_nextproc, kvm_getproc, kvm_setproc \- read system process structures +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kvm.h> +#include <sys/param.h> +#include <sys/time.h> +#include <sys/proc.h> + +\fBstruct proc *\fR\fBkvm_nextproc\fR(\fBkvm_t *\fR\fIkd\fR); +.fi + +.LP +.nf +\fBint\fR \fBkvm_setproc\fR(\fBkvm_t *\fR\fIkd\fR); +.fi + +.LP +.nf +\fBstruct proc *\fR\fBkvm_getproc\fR(\fBkvm_t *\fR\fIkd\fR, \fBpid_t\fR \fIpid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkvm_nextproc()\fR function reads sequentially all of the system process +structures from the kernel identified by \fIkd\fR (see \fBkvm_open\fR(3KVM)). +Each call to \fBkvm_nextproc()\fR returns a pointer to the static memory area +that contains a copy of the next valid process table entry. There is no +guarantee that the data will remain valid across calls to \fBkvm_nextproc()\fR, +\fBkvm_setproc()\fR, or \fBkvm_getproc()\fR. If the process structure must be +saved, it should be copied to non-volatile storage. +.sp +.LP +For performance reasons, many implementations will cache a set of system +process structures. Since the system state is liable to change between calls to +\fBkvm_nextproc()\fR, and since the cache may contain obsolete information, +there is no guarantee that every process structure returned refers to an active +process, nor is it certain that all processes will be reported. +.sp +.LP +The \fBkvm_setproc()\fR function rewinds the process list, enabling +\fBkvm_nextproc()\fR to rescan from the beginning of the system process table. +This function will always flush the process structure cache, allowing an +application to re-scan the process table of a running system. +.sp +.LP +The \fBkvm_getproc()\fR function locates the \fBproc\fR structure of the +process specified by \fIpid\fR and returns a pointer to it. Although this +function does not interact with the process table pointer manipulated by +\fBkvm_nextproc()\fR, the restrictions regarding the validity of the data still +apply. +.SH RETURN VALUES +.sp +.LP +On success, \fBkvm_nextproc()\fR returns a pointer to a copy of the next valid +process table entry. On failure, it returns \fINULL\fR. +.sp +.LP +On success, \fBkvm_getproc()\fR returns a pointer to the \fIproc\fR structure +of the process specified by \fIpid\fR. On failure, it returns \fINULL\fR. +.sp +.LP +The \fBkvm_setproc()\fR function returns 0 on success and \(mi1 on failure. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkvm_getu\fR(3KVM), \fBkvm_open\fR(3KVM), \fBkvm_kread\fR(3KVM), +\fBattributes\fR(5) diff --git a/usr/src/man/man3kvm/kvm_nlist.3kvm b/usr/src/man/man3kvm/kvm_nlist.3kvm new file mode 100644 index 0000000000..f7063dc864 --- /dev/null +++ b/usr/src/man/man3kvm/kvm_nlist.3kvm @@ -0,0 +1,68 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kvm_nlist 3KVM "2 May 2002" "SunOS 5.11" "Kernel VM Library Functions" +.SH NAME +kvm_nlist \- get entries from kernel symbol table +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kvm.h> +#include <nlist.h> + +\fBint\fR \fBkvm_nlist\fR(\fBkvm_t *\fR\fIkd\fR, \fBstruct nlist *\fR\fInl\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkvm_nlist()\fR function examines the symbol table from the kernel image +identified by \fIkd\fR (see \fBkvm_open\fR(3KVM)) and selectively extracts a +list of values and puts them in the array of \fBnlist\fR structures pointed to +by \fInl\fR. The name list pointed to by \fInl\fR consists of an array of +structures containing names, types and values. The \fBn_name\fR field of each +such structure is taken to be a pointer to a character string representing a +symbol name. The list is terminated by an entry with a null pointer (or a +pointer to a null string) in the \fBn_name\fR field. For each entry in +\fInl\fR, if the named symbol is present in the kernel symbol table, its value +and type are placed in the \fBn_value\fR and \fBn_type\fR fields. If a symbol +cannot be located, the corresponding \fBn_type\fR field of \fInl\fR is set to +0. +.SH RETURN VALUES +.sp +.LP +The \fBkvm_nlist()\fR functions returns the value of \fBnlist\fR(3UCB) or +\fBnlist\fR(3ELF), depending on the library used. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkvm_open\fR(3KVM), \fBkvm_kread\fR(3KVM), \fBnlist\fR(3ELF), +\fBnlist\fR(3UCB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +Although the \fBlibkvm\fR API is Stable, the symbol names and data values that +can be accessed through this set of interfaces are Private and are subject to +ongoing change. diff --git a/usr/src/man/man3kvm/kvm_open.3kvm b/usr/src/man/man3kvm/kvm_open.3kvm new file mode 100644 index 0000000000..f75bb4ca28 --- /dev/null +++ b/usr/src/man/man3kvm/kvm_open.3kvm @@ -0,0 +1,204 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kvm_open 3KVM "2 May 2002" "SunOS 5.11" "Kernel VM Library Functions" +.SH NAME +kvm_open, kvm_close \- specify a kernel to examine +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kvm.h> +#include <fcntl.h> + +\fBkvm_t *\fR\fBkvm_open\fR(\fBchar *\fR\fInamelist\fR, \fBchar *\fR\fIcorefile\fR, \fBchar *\fR\fIswapfile\fR, \fBint\fR \fIflag\fR, + \fBchar *\fR\fIerrstr\fR); +.fi + +.LP +.nf +\fBint\fR \fBkvm_close\fR(\fBkvm_t *\fR\fIkd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkvm_open()\fR function initializes a set of file descriptors to be used +in subsequent calls to kernel virtual memory ( VM) routines. It returns a +pointer to a kernel identifier that must be used as the \fIkd\fR argument in +subsequent kernel VM function calls. +.sp +.LP +The \fInamelist\fR argument specifies an unstripped executable file whose +symbol table will be used to locate various offsets in \fIcorefile\fR. If +\fInamelist\fR is \fINULL\fR, the symbol table of the currently running kernel +is used to determine offsets in the core image. In this case, it is up to the +implementation to select an appropriate way to resolve symbolic references, for +instance, using \fB/dev/ksyms\fR as a default \fInamelist\fR file. +.sp +.LP +The \fIcorefile\fR argument specifies a file that contains an image of physical +memory, for instance, a kernel crash dump file (see \fBsavecore\fR(1M)) or the +special device \fB/dev/mem\fR. If \fIcorefile\fR is \fINULL\fR, the currently +running kernel is accessed, using \fB/dev/mem\fR and \fB/dev/kmem\fR. +.sp +.LP +The \fIswapfile\fR argument specifies a file that represents the swap device. +If both \fIcorefile\fR and \fIswapfile\fR are \fINULL\fR, the swap device of +the currently running kernel is accessed. Otherwise, if \fIswapfile\fR is +\fINULL\fR, \fBkvm_open()\fR may succeed but subsequent \fBkvm_getu\fR(3KVM) +function calls may fail if the desired information is swapped out. +.sp +.LP +The \fIflag\fR function is used to specify read or write access for +\fIcorefile\fR and may have one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBO_RDONLY\fR\fR +.ad +.RS 12n +.rt +open for reading +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_RDWR\fR\fR +.ad +.RS 12n +.rt +open for reading and writing +.RE + +.sp +.LP +The \fIerrstr\fR argument is used to control error reporting. If it is a null +pointer, no error messages will be printed. If it is non-null, it is assumed to +be the address of a string that will be used to prefix error messages generated +by \fBkvm_open\fR. Errors are printed to \fBstderr\fR. A useful value to supply +for \fIerrstr\fR would be \fIargv\fR[0]. This has the effect of printing the +process name in front of any error messages. +.sp +.LP +Applications using \fBlibkvm\fR are dependent on the underlying data model of +the kernel image, that is, whether it is a 32\(mibit or 64\(mibit kernel. +.sp +.LP +The data model of these applications must match the data model of the kernel in +order to correctly interpret the size and offsets of kernel data structures. +For example, a 32\(mibit application that uses the 32\(mibit version of the +\fBlibkvm\fR interfaces will fail to open a 64\(mibit kernel image. Similarly, +a 64\(mibit application that uses the 64\(mibit version of the \fBlibkvm\fR +interfaces will fail to open a 32\(mibit kernel image. +.sp +.LP +The \fBkvm_close()\fR function closes all file descriptors that were associated +with \fIkd\fR. These files are also closed on \fBexit\fR(2) and +\fBexecve\fR(\|) (see \fBexec\fR(2)). \fBkvm_close()\fR also resets the +\fBproc\fR pointer associated with \fBkvm_nextproc\fR(3KVM) and flushes any +cached kernel data. +.SH RETURN VALUES +.sp +.LP +The \fBkvm_open()\fR function returns a non-null value suitable for use with +subsequent kernel VM function calls. On failure, it returns \fINULL\fR and no +files are opened. +.sp +.LP +The \fBkvm_close()\fR function returns 0 on success and \(mi1 on failure. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/dev/kmem\fR\fR +.ad +.RS 14n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/ksyms\fR\fR +.ad +.RS 14n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/mem\fR\fR +.ad +.RS 14n +.rt + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsavecore\fR(1M), \fBexec\fR(2), \fBexit\fR(2), \fBpathconf\fR(2), +\fBgetloadavg\fR(3C), \fBkstat\fR(3KSTAT), \fBkvm_getu\fR(3KVM), +\fBkvm_nextproc\fR(3KVM), \fBkvm_nlist\fR(3KVM), \fBkvm_kread\fR(3KVM), +\fBlibkvm\fR(3LIB),\fBsysconf\fR(3C), \fBproc\fR(4), \fBattributes\fR(5), +\fBlfcompile\fR(5) +.SH NOTES +.sp +.LP +Kernel core dumps should be examined on the platform on which they were +created. While a 32-bit application running on a 64-bit kernel can examine a +32-bit core dump, a 64-bit application running on a 64-bit kernel cannot +examine a kernel core dump from the 32-bit system. +.sp +.LP +On 32-bit systems, applications that use \fBlibkvm\fR to access the running +kernel must be 32-bit applications. On systems that support both 32-bit and +64-bit applications, applications that use the \fBlibkvm\fR interfaces to +access the running kernel must themselves be 64-bit applications. +.sp +.LP +Although the \fBlibkvm\fR API is Stable, the symbol names and data values that +can be accessed through this set of interfaces are Private and are subject to +ongoing change. +.sp +.LP +Applications using \fBlibkvm\fR are likely to be platform- and +release-dependent. +.sp +.LP +Most of the traditional uses of \fBlibkvm\fR have been superseded by more +stable interfaces that allow the same information to be extracted more +efficiently, yet independent of the kernel data model. For examples, see +\fBsysconf\fR(3C), \fBproc\fR(4), \fBkstat\fR(3KSTAT), \fBgetloadavg\fR(3C), +and \fBpathconf\fR(2). diff --git a/usr/src/man/man3kvm/kvm_read.3kvm b/usr/src/man/man3kvm/kvm_read.3kvm new file mode 100644 index 0000000000..53d7932709 --- /dev/null +++ b/usr/src/man/man3kvm/kvm_read.3kvm @@ -0,0 +1,71 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kvm_read 3KVM "2 May 2002" "SunOS 5.11" "Kernel VM Library Functions" +.SH NAME +kvm_read, kvm_write \- copy data to or from a kernel image or running system +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kvm.h> + +\fBssize_t\fR \fBkvm_read\fR(\fBkvm_t *\fR\fIkd\fR, \fBuintptr_t\fR \fIaddr\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbytes\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBkvm_write\fR(\fBkvm_t *\fR\fIkd\fR, \fBuintptr_t\fR \fIaddr\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbytes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkvm_read()\fR function transfers data from the kernel image specified by +\fIkd\fR (see \fBkvm_open\fR(3KVM)) to the address space of the process. +\fInbytes\fR bytes of data are copied from the kernel virtual address given by +\fIaddr\fR to the buffer pointed to by \fIbuf\fR. +.sp +.LP +The \fBkvm_write()\fR function is like \fBkvm_read()\fR, except that the +direction of data transfer is reversed. To use this function, the +\fBkvm_open\fR(3KVM) call that returned \fIkd\fR must have specified write +access. If a user virtual address is given, it is resolved in the address space +of the process specified in the most recent \fBkvm_getu\fR(3KVM) call. +.SH USAGE +.sp +.LP +The \fBkvm_read()\fR and \fBkvm_write()\fR functions are obsolete and might be +removed in a future release. The functions described on the +\fBkvm_kread\fR(3KVM) manual page should be used instead. +.SH RETURN VALUES +.sp +.LP +On success, these functions return the number of bytes actually transferred. On +failure, they return \fB\(mi1\fR\&. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkvm_getu\fR(3KVM), \fBkvm_kread\fR(3KVM)\fBkvm_nlist\fR(3KVM), +\fBkvm_open\fR(3KVM), \fBattributes\fR(5) |