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.\" 4. 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_open.3 8.3 (Berkeley) 4/19/94 33.\" $FreeBSD$ 34.\" 35.Dd January 29, 2004 36.Dt KVM_OPEN 3 37.Os 38.Sh NAME 39.Nm kvm_open , 40.Nm kvm_openfiles , 41.Nm kvm_close 42.Nd initialize kernel virtual memory access 43.Sh LIBRARY 44.Lb libkvm 45.Sh SYNOPSIS 46.In fcntl.h 47.In kvm.h 48.Ft kvm_t * 49.Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr" 50.Ft kvm_t * 51.Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf" 52.Ft int 53.Fn kvm_close "kvm_t *kd" 54.Sh DESCRIPTION 55The functions 56.Fn kvm_open 57and 58.Fn kvm_openfiles 59return a descriptor used to access kernel virtual memory 60via the 61.Xr kvm 3 62library routines. 63Both active kernels and crash dumps are accessible 64through this interface. 65.Pp 66The 67.Fa execfile 68argument is the executable image of the kernel being examined. 69This file must contain a symbol table. 70If this argument is 71.Dv NULL , 72the currently running system is assumed, 73as determined from 74.Xr getbootfile 3 . 75.Pp 76The 77.Fa corefile 78argument is the kernel memory device file. 79It can be either 80.Pa /dev/mem 81or a crash dump core generated by 82.Xr savecore 8 . 83If 84.Fa corefile 85is 86.Dv NULL , 87the default indicated by 88.Dv _PATH_MEM 89from 90.In paths.h 91is used. 92It can also be set to a special value 93.Pa /dev/null 94by utilities like 95.Xr ps 1 96that do not directly access kernel memory. 97.Pp 98The 99.Fa swapfile 100argument is currently unused. 101.Pp 102The 103.Fa flags 104argument indicates read/write access as in 105.Xr open 2 106and applies only to the core file. 107Only 108.Dv O_RDONLY , 109.Dv O_WRONLY , 110and 111.Dv O_RDWR 112are permitted. 113.Pp 114There are two open routines which differ only with respect to 115the error mechanism. 116One provides backward compatibility with the SunOS kvm library, while the 117other provides an improved error reporting framework. 118.Pp 119The 120.Fn kvm_open 121function is the Sun kvm compatible open call. 122Here, the 123.Fa errstr 124argument indicates how errors should be handled. 125If it is 126.Dv NULL , 127no errors are reported and the application cannot know the 128specific nature of the failed kvm call. 129If it is not 130.Dv NULL , 131errors are printed to 132.Dv stderr 133with 134.Fa errstr 135prepended to the message, as in 136.Xr perror 3 . 137Normally, the name of the program is used here. 138The string is assumed to persist at least until the corresponding 139.Fn kvm_close 140call. 141.Pp 142The 143.Fn kvm_openfiles 144function provides 145.Bx 146style error reporting. 147Here, error messages are not printed out by the library. 148Instead, the application obtains the error message 149corresponding to the most recent kvm library call using 150.Fn kvm_geterr 151(see 152.Xr kvm_geterr 3 ) . 153The results are undefined if the most recent kvm call did not produce 154an error. 155Since 156.Fn kvm_geterr 157requires a kvm descriptor, but the open routines return 158.Dv NULL 159on failure, 160.Fn kvm_geterr 161cannot be used to get the error message if open fails. 162Thus, 163.Fn kvm_openfiles 164will place any error message in the 165.Fa errbuf 166argument. 167This buffer should be _POSIX2_LINE_MAX characters large (from 168<limits.h>). 169.Sh RETURN VALUES 170The 171.Fn kvm_open 172and 173.Fn kvm_openfiles 174functions both return a descriptor to be used 175in all subsequent kvm library calls. 176The library is fully re-entrant. 177On failure, 178.Dv NULL 179is returned, in which case 180.Fn kvm_openfiles 181writes the error message into 182.Fa errbuf . 183.Pp 184The 185.Fn kvm_close 186function returns 0 on success and -1 on failure. 187.Sh SEE ALSO 188.Xr open 2 , 189.Xr kvm 3 , 190.Xr kvm_getargv 3 , 191.Xr kvm_getenvv 3 , 192.Xr kvm_geterr 3 , 193.Xr kvm_getprocs 3 , 194.Xr kvm_nlist 3 , 195.Xr kvm_read 3 , 196.Xr kvm_write 3 , 197.Xr kmem 4 , 198.Xr mem 4 199.Sh BUGS 200There should not be two open calls. 201The ill-defined error semantics 202of the Sun library and the desire to have a backward-compatible library 203for 204.Bx 205left little choice. 206