1.\" $NetBSD: kvm_open.3,v 1.18 2011/09/12 21:11:32 christos Exp $ 2.\" 3.\" Copyright (c) 1992, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software developed by the Computer Systems 7.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract 8.\" BG 91-66 and contributed to Berkeley. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)kvm_open.3 8.3 (Berkeley) 4/19/94 35.\" 36.Dd September 14, 2011 37.Dt KVM_OPEN 3 38.Os 39.Sh NAME 40.Nm kvm_open , 41.Nm kvm_openfiles , 42.Nm kvm_close 43.Nd initialize kernel virtual memory access 44.Sh LIBRARY 45.Lb libkvm 46.Sh SYNOPSIS 47.In fcntl.h 48.In kvm.h 49.Ft kvm_t * 50.Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr" 51.Ft kvm_t * 52.Fn kvm_openfiles "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "char *errbuf" 53.Ft int 54.Fn kvm_close "kvm_t *kd" 55.Sh DESCRIPTION 56The functions 57.Fn kvm_open 58and 59.Fn kvm_openfiles 60return a descriptor used to access kernel virtual memory 61via the 62.Xr kvm 3 63library routines. 64Both active kernels and crash dumps are accessible 65through this interface. 66.Pp 67.Fa execfile 68is 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; in this case, the functions will 73attempt to use the 74.Xr ksyms 4 75device indicated by 76.Dv _PATH_KSYMS 77in 78.In paths.h ; 79if that fails, then they will use the file indicated by the 80.Xr sysctl 3 81variable 82.Va machdep.booted_kernel , 83or (if the sysctl information is not available) 84the default kernel path indicated by 85.Dv _PATH_UNIX 86in 87.In paths.h . 88.Pp 89.Fa corefile 90is the kernel memory device file. 91It can be either 92.Pa /dev/mem 93or a crash dump core generated by 94.Xr savecore 8 . 95If 96.Fa corefile 97is 98.Dv NULL , 99the default indicated by 100.Dv _PATH_MEM 101from 102.In paths.h 103is used. 104.Pp 105.Fa swapfile 106should indicate the swap device. 107If 108.Dv NULL , 109.Dv _PATH_DRUM 110from 111.In paths.h 112is used. 113.Pp 114The 115.Fa flags 116argument indicates read/write access as in 117.Xr open 2 118and applies only to the core file. 119The only permitted flags from 120.Xr open 2 121are 122.Dv O_RDONLY , 123.Dv O_WRONLY , 124and 125.Dv O_RDWR . 126.Pp 127As a special case, a 128.Fa flags 129argument of 130.Dv KVM_NO_FILES 131will initialize the 132.Xr kvm 3 133library for use on active kernels only using 134.Xr sysctl 3 135for retrieving kernel data and ignores the 136.Fa execfile , 137.Fa corefile 138and 139.Fa swapfile 140arguments. 141Only a small subset of the 142.Xr kvm 3 143library functions are available using this method. 144These are currently 145.Xr kvm_getproc2 3 , 146.Xr kvm_getargv2 3 147and 148.Xr kvm_getenvv2 3 . 149.Pp 150There are two open routines which differ only with respect to 151the error mechanism. 152One provides backward compatibility with the SunOS kvm library, while the 153other provides an improved error reporting framework. 154.Pp 155The 156.Fn kvm_open 157function is the Sun kvm compatible open call. 158Here, the 159.Fa errstr 160argument indicates how errors should be handled. 161If it is 162.Dv NULL , 163no errors are reported and the application cannot know the 164specific nature of the failed kvm call. 165If it is not 166.Dv NULL , 167errors are printed to stderr with 168.Fa errstr 169prepended to the message, as in 170.Xr perror 3 . 171Normally, the name of the program is used here. 172The string is assumed to persist at least until the corresponding 173.Fn kvm_close 174call. 175.Pp 176The 177.Fn kvm_openfiles 178function provides 179.Bx 180style error reporting. 181Here, error messages are not printed out by the library. 182Instead, the application obtains the error message 183corresponding to the most recent kvm library call using 184.Fn kvm_geterr 185(see 186.Xr kvm_geterr 3 ) . 187The results are undefined if the most recent kvm call did not produce 188an error. 189Since 190.Fn kvm_geterr 191requires a kvm descriptor, but the open routines return 192.Dv NULL 193on failure, 194.Fn kvm_geterr 195cannot be used to get the error message if open fails. 196Thus, 197.Fn kvm_openfiles 198will place any error message in the 199.Fa errbuf 200argument. 201This buffer should be _POSIX2_LINE_MAX characters large (from 202.In limits.h ) . 203.Sh RETURN VALUES 204The 205.Fn kvm_open 206and 207.Fn kvm_openfiles 208functions both return a descriptor to be used 209in all subsequent kvm library calls. 210The library is fully re-entrant. 211On failure, 212.Dv NULL 213is returned, in which case 214.Fn kvm_openfiles 215writes the error message into 216.Fa errbuf . 217.Pp 218The 219.Fn kvm_close 220function returns 0 on success and -1 on failure. 221.Sh SEE ALSO 222.Xr open 2 , 223.Xr kvm 3 , 224.Xr kvm_getargv 3 , 225.Xr kvm_getenvv 3 , 226.Xr kvm_geterr 3 , 227.Xr kvm_getkernelname 3 , 228.Xr kvm_getprocs 3 , 229.Xr kvm_nlist 3 , 230.Xr kvm_read 3 , 231.Xr kvm_write 3 232.Sh BUGS 233There should not be two open calls. 234The ill-defined error semantics of the Sun library 235and the desire to have a backward-compatible library for 236.Bx 237left little choice. 238