Changeset View
Changeset View
Standalone View
Standalone View
lib/libkvm/kvm_open.3
Show All 31 Lines | |||||
.\" @(#)kvm_open.3 8.3 (Berkeley) 4/19/94 | .\" @(#)kvm_open.3 8.3 (Berkeley) 4/19/94 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd January 29, 2004 | .Dd January 29, 2004 | ||||
.Dt KVM_OPEN 3 | .Dt KVM_OPEN 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm kvm_open , | .Nm kvm_open , | ||||
.Nm kvm_open2 , | |||||
.Nm kvm_openfiles , | .Nm kvm_openfiles , | ||||
.Nm kvm_close | .Nm kvm_close | ||||
.Nd initialize kernel virtual memory access | .Nd initialize kernel virtual memory access | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libkvm | .Lb libkvm | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In fcntl.h | .In fcntl.h | ||||
.In kvm.h | .In kvm.h | ||||
.Ft kvm_t * | .Ft kvm_t * | ||||
.Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr" | .Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr" | ||||
.Ft kvm_t * | .Ft kvm_t * | ||||
.Fo kvm_open2 | |||||
.Fa "const char *execfile" | |||||
.Fa "const char *corefile" | |||||
.Fa "int flags" | |||||
.Fa "char *errbuf" | |||||
.Fa "int (*resolver)(const char *name, kvaddr_t *addr)" | |||||
.Fc | |||||
.Ft kvm_t * | |||||
.Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf" | .Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf" | ||||
.Ft int | .Ft int | ||||
.Fn kvm_close "kvm_t *kd" | .Fn kvm_close "kvm_t *kd" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The functions | The functions | ||||
.Fn kvm_open | .Fn kvm_open , | ||||
.Fn kvm_open2 , | |||||
and | and | ||||
.Fn kvm_openfiles | .Fn kvm_openfiles | ||||
return a descriptor used to access kernel virtual memory | return a descriptor used to access kernel virtual memory | ||||
via the | via the | ||||
.Xr kvm 3 | .Xr kvm 3 | ||||
library routines. | library routines. | ||||
Both active kernels and crash dumps are accessible | Both active kernels and crash dumps are accessible | ||||
through this interface. | through this interface. | ||||
▲ Show 20 Lines • Show All 41 Lines • ▼ Show 20 Lines | |||||
and applies only to the core file. | and applies only to the core file. | ||||
Only | Only | ||||
.Dv O_RDONLY , | .Dv O_RDONLY , | ||||
.Dv O_WRONLY , | .Dv O_WRONLY , | ||||
and | and | ||||
.Dv O_RDWR | .Dv O_RDWR | ||||
are permitted. | are permitted. | ||||
.Pp | .Pp | ||||
There are two open routines which differ only with respect to | The | ||||
the error mechanism. | .Nm kvm | ||||
library provides two different error reporting mechanisms. | |||||
One provides backward compatibility with the SunOS kvm library, while the | One provides backward compatibility with the SunOS kvm library, while the | ||||
other provides an improved error reporting framework. | other provides an improved error reporting framework. | ||||
The mechanism used by a descriptor is determined by the function used to | |||||
open the descriptor. | |||||
.Pp | .Pp | ||||
The | The | ||||
.Fn kvm_open | .Fn kvm_open | ||||
function is the Sun kvm compatible open call. | function is the Sun kvm compatible open call. | ||||
Here, the | Here, the | ||||
.Fa errstr | .Fa errstr | ||||
argument indicates how errors should be handled. | argument indicates how errors should be handled. | ||||
If it is | If it is | ||||
Show All 9 Lines | |||||
prepended to the message, as in | prepended to the message, as in | ||||
.Xr perror 3 . | .Xr perror 3 . | ||||
Normally, the name of the program is used here. | Normally, the name of the program is used here. | ||||
The string is assumed to persist at least until the corresponding | The string is assumed to persist at least until the corresponding | ||||
.Fn kvm_close | .Fn kvm_close | ||||
call. | call. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn kvm_open2 | |||||
and | |||||
.Fn kvm_openfiles | .Fn kvm_openfiles | ||||
function provides | functions provide | ||||
.Bx | .Bx | ||||
style error reporting. | style error reporting. | ||||
Here, error messages are not printed out by the library. | Here, error messages are not printed out by the library. | ||||
Instead, the application obtains the error message | Instead, the application obtains the error message | ||||
corresponding to the most recent kvm library call using | corresponding to the most recent kvm library call using | ||||
.Fn kvm_geterr | .Fn kvm_geterr | ||||
(see | (see | ||||
.Xr kvm_geterr 3 ) . | .Xr kvm_geterr 3 ) . | ||||
The results are undefined if the most recent kvm call did not produce | The results are undefined if the most recent kvm call did not produce | ||||
an error. | an error. | ||||
Since | Since | ||||
.Fn kvm_geterr | .Fn kvm_geterr | ||||
requires a kvm descriptor, but the open routines return | requires a kvm descriptor, but the open routines return | ||||
.Dv NULL | .Dv NULL | ||||
on failure, | on failure, | ||||
.Fn kvm_geterr | .Fn kvm_geterr | ||||
cannot be used to get the error message if open fails. | cannot be used to get the error message if open fails. | ||||
Thus, | Thus, | ||||
.Fn kvm_open2 | |||||
and | |||||
.Fn kvm_openfiles | .Fn kvm_openfiles | ||||
will place any error message in the | will place any error message in the | ||||
.Fa errbuf | .Fa errbuf | ||||
argument. | argument. | ||||
This buffer should be _POSIX2_LINE_MAX characters large (from | This buffer should be _POSIX2_LINE_MAX characters large (from | ||||
<limits.h>). | <limits.h>). | ||||
.Pp | |||||
The | |||||
.Fa resolver | |||||
argument points to a function used by the | |||||
.Nm kvm | |||||
library to map symbol names to kernel virtual addresses. | |||||
When the | |||||
.Fa resolver | |||||
function is called, | |||||
.Fa name | |||||
specifies the requested symbol name. | |||||
If the function is able to resolve the name to an address, | |||||
the address should be set in | |||||
.Fa *addr | |||||
and the function should return zero. | |||||
If the function is not able to resolve the name to an address, | |||||
it should return a non-zero value. | |||||
When opening a native kernel image, | |||||
.Fa resolver | |||||
may be set to | |||||
.Dv NULL | |||||
to use an internal function to resolve symbol names. | |||||
Non-native kernel images | |||||
.Pq such as when cross-debugging a crash dump | |||||
require a valid | |||||
.Fa resolver . | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
The | The | ||||
.Fn kvm_open | .Fn kvm_open , | ||||
.Fn kvm_open2 , | |||||
and | and | ||||
.Fn kvm_openfiles | .Fn kvm_openfiles | ||||
functions both return a descriptor to be used | functions return a descriptor to be used | ||||
in all subsequent kvm library calls. | in all subsequent kvm library calls. | ||||
The library is fully re-entrant. | The library is fully re-entrant. | ||||
On failure, | On failure, | ||||
.Dv NULL | .Dv NULL | ||||
is returned, in which case | is returned, in which case | ||||
.Fn kvm_open2 | |||||
and | |||||
.Fn kvm_openfiles | .Fn kvm_openfiles | ||||
writes the error message into | write the error message into | ||||
.Fa errbuf . | .Fa errbuf . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn kvm_close | .Fn kvm_close | ||||
function returns 0 on success and -1 on failure. | function returns 0 on success and -1 on failure. | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr open 2 , | .Xr open 2 , | ||||
.Xr kvm 3 , | .Xr kvm 3 , | ||||
.Xr kvm_getargv 3 , | .Xr kvm_getargv 3 , | ||||
.Xr kvm_getenvv 3 , | .Xr kvm_getenvv 3 , | ||||
.Xr kvm_geterr 3 , | .Xr kvm_geterr 3 , | ||||
.Xr kvm_getprocs 3 , | .Xr kvm_getprocs 3 , | ||||
.Xr kvm_native 3 , | |||||
.Xr kvm_nlist 3 , | .Xr kvm_nlist 3 , | ||||
.Xr kvm_read 3 , | .Xr kvm_read 3 , | ||||
.Xr kvm_write 3 , | .Xr kvm_write 3 , | ||||
.Xr kmem 4 , | .Xr kmem 4 , | ||||
.Xr mem 4 | .Xr mem 4 | ||||
.Sh BUGS | .Sh BUGS | ||||
There should not be two open calls. | There should not be three open calls. | ||||
The ill-defined error semantics | The ill-defined error semantics | ||||
of the Sun library and the desire to have a backward-compatible library | of the Sun library and the desire to have a backward-compatible library | ||||
for | for | ||||
.Bx | .Bx | ||||
left little choice. | left little choice. |