[unix-history] / usr / src / lib / libkvm / kvm_open.3

.\" Copyright (c) 1992 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)kvm_open.3	5.1 (Berkeley) %G%
.\"
.Dd 
.Dt KVM_OPEN 3
.Os
.Sh NAME
.Nm kvm_open ,
.Nm kvm_close
.Nd initialize kernel virtual memory access
.Sh SYNOPSIS
.Fd #include <kvm.h>
.\" .Fa kvm_t *kd
.br
.Ft kvm_t *
.Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr"
.Ft kvm_t *
.Fn kvm_openfiles "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errbuf"
.Ft int
.Fn kvm_close "kvm_t *kd"
.Sh DESCRIPTION
.Fn kvm_open
and 
.Fn kvm_openfiles
return a descriptor used to access kernel virtual memory
via the 
.Xr kvm 3
library routines.  Both active kernels and crash dumps are accessible
through this interface.
.Pp
.Fa execfile
is the executable image of the kernel being examined.
This file must contain a symbol table.
If this argument is NULL, the currently running system is assumed,
which is indicated by _PATH_UNIX in <paths.h>.
.Pp
.Fa corefile 
is the kernel memory device file.  It can be either /dev/mem
or a crash dump core generated by 
.Xr savecore 8 .
If
.Fa corefile
is null, the default indicated by _PATH_MEM is used.
.Pp
.Fa swapfile
should indicate the swap device.  If NULL, _PATH_DRUM from <paths.h>
is used.
.Pp
The
.Fa flags 
argument indicates the read/write access as in
.Xr open 2
and applies to only the core file.
Only O_RDONLY, O_WRONLY, and O_RDWR are permitted.
.Pp
There are two open routines which differ only with respect to 
the error mechanism.
One provides backward compatibility with the SunOS kvm library, while the
other provides an improved error reporting framework.
.Pp
The
.Fn kvm_open
function is the Sun kvm compatible open call.  Here, the
.Fa errstr
argument indicates how errors should be handled.  If it is NULL,
then no errors are reporting and the application cannot know the 
specific nature of the failed kvm call.
If it is not NULL, then errors are printed to stderr with 
.Fa errstr
prepended to the message, as in
.Xr perror 3 .
Normally, the name of the program is used here.
The string is assumed to be persistent.
.Pp
The
.Fn kvm_openfiles
function provides BSD style error reporting.
Here, error messages are not printed out by the library.
Instead, the application obtains the error message
corresponding to the most recent kvm library call using
.Fn kvm_geterr
(see
.Xr kvm_geterr 3 ).
The results are undefined if the most recent kvm call did not produce
an error.
Since
.Fn kvm_geterr
requires a kvm descriptor, but the open routines return NULL on failure,
.Fn kvm_geterr
cannot be used to get the error message if open fails.
Thus,
.Fn kvm_openfiles ,
will place any error message in the
.Fa errbuf
argument.  This buffer should be _POSIX2_LINE_MAX characters large (from
<limits.h>)
.Sh RETURN VALUES
.Fn kvm_open
and 
.Fn kvm_openfiles
both return a descriptor to be used in all subsequent kvm library calls.
The library is fully re-entrant.
On failure, NULL is returned, in which case
.Fn kvm_openfiles
writes the error message into 
.Fa errbuf .
.Pp
.Fn kvm_close
returns 0 on sucess and -1 on failure.
.Sh BUGS
There should not be two open calls.  The ill-defined error semantics
of the Sun library and the desire to have a backward-compatible library
for BSD left little choice.
.Sh SEE ALSO
.Xr kvm 3
Commit	Line	Data
b8b13822 KM	1	.\" Copyright (c) 1992 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" %sccs.include.redist.man%
	5	.\"
	6	.\" @(#)kvm_open.3 5.1 (Berkeley) %G%
	7	.\"
	8	.Dd
	9	.Dt KVM_OPEN 3
	10	.Os
	11	.Sh NAME
	12	.Nm kvm_open ,
	13	.Nm kvm_close
	14	.Nd initialize kernel virtual memory access
	15	.Sh SYNOPSIS
	16	.Fd #include <kvm.h>
	17	.\" .Fa kvm_t *kd
	18	.br
	19	.Ft kvm_t *
	20	.Fn kvm_open "const char execfile" "const char corefile" "char swapfile" "int flags" "const char errstr"
	21	.Ft kvm_t *
	22	.Fn kvm_openfiles "const char execfile" "const char corefile" "char swapfile" "int flags" "const char errbuf"
	23	.Ft int
	24	.Fn kvm_close "kvm_t *kd"
	25	.Sh DESCRIPTION
	26	.Fn kvm_open
	27	and
	28	.Fn kvm_openfiles
	29	return a descriptor used to access kernel virtual memory
	30	via the
	31	.Xr kvm 3
	32	library routines. Both active kernels and crash dumps are accessible
	33	through this interface.
	34	.Pp
	35	.Fa execfile
	36	is the executable image of the kernel being examined.
	37	This file must contain a symbol table.
	38	If this argument is NULL, the currently running system is assumed,
	39	which is indicated by _PATH_UNIX in <paths.h>.
	40	.Pp
	41	.Fa corefile
	42	is the kernel memory device file. It can be either /dev/mem
	43	or a crash dump core generated by
	44	.Xr savecore 8 .
	45	If
	46	.Fa corefile
	47	is null, the default indicated by _PATH_MEM is used.
	48	.Pp
	49	.Fa swapfile
	50	should indicate the swap device. If NULL, _PATH_DRUM from <paths.h>
	51	is used.
	52	.Pp
	53	The
	54	.Fa flags
	55	argument indicates the read/write access as in
	56	.Xr open 2
	57	and applies to only the core file.
	58	Only O_RDONLY, O_WRONLY, and O_RDWR are permitted.
	59	.Pp
	60	There are two open routines which differ only with respect to
	61	the error mechanism.
	62	One provides backward compatibility with the SunOS kvm library, while the
	63	other provides an improved error reporting framework.
	64	.Pp
65	The
66	.Fn kvm_open
67	function is the Sun kvm compatible open call. Here, the
68	.Fa errstr
69	argument indicates how errors should be handled. If it is NULL,
70	then no errors are reporting and the application cannot know the
71	specific nature of the failed kvm call.
72	If it is not NULL, then errors are printed to stderr with
73	.Fa errstr
74	prepended to the message, as in
75	.Xr perror 3 .
76	Normally, the name of the program is used here.
77	The string is assumed to be persistent.
78	.Pp
79	The
80	.Fn kvm_openfiles
81	function provides BSD style error reporting.
82	Here, error messages are not printed out by the library.
83	Instead, the application obtains the error message
84	corresponding to the most recent kvm library call using
85	.Fn kvm_geterr
86	(see
87	.Xr kvm_geterr 3 ).
88	The results are undefined if the most recent kvm call did not produce
89	an error.
90	Since
91	.Fn kvm_geterr
92	requires a kvm descriptor, but the open routines return NULL on failure,
93	.Fn kvm_geterr
94	cannot be used to get the error message if open fails.
95	Thus,
96	.Fn kvm_openfiles ,
97	will place any error message in the
98	.Fa errbuf
99	argument. This buffer should be _POSIX2_LINE_MAX characters large (from
100	<limits.h>)
101	.Sh RETURN VALUES
102	.Fn kvm_open
103	and
104	.Fn kvm_openfiles
105	both return a descriptor to be used in all subsequent kvm library calls.
106	The library is fully re-entrant.
107	On failure, NULL is returned, in which case
108	.Fn kvm_openfiles
109	writes the error message into
110	.Fa errbuf .
111	.Pp
112	.Fn kvm_close
113	returns 0 on sucess and -1 on failure.
114	.Sh BUGS
115	There should not be two open calls. The ill-defined error semantics
116	of the Sun library and the desire to have a backward-compatible library
117	for BSD left little choice.
118	.Sh SEE ALSO
119	.Xr kvm 3