1.\" $NetBSD: kvm_open.3,v 1.3 1997/08/20 05:42:58 mikel 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. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)kvm_open.3 8.3 (Berkeley) 4/19/94 39.\" 40.Dd April 19, 1994 41.Dt KVM_OPEN 3 42.Os 43.Sh NAME 44.Nm kvm_open , 45.Nm kvm_openfiles , 46.Nm kvm_close 47.Nd initialize kernel virtual memory access 48.Sh SYNOPSIS 49.Fd #include <fcntl.h> 50.Fd #include <kvm.h> 51.br 52.Ft kvm_t * 53.Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr" 54.Ft kvm_t * 55.Fn kvm_openfiles "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "char *errbuf" 56.Ft int 57.Fn kvm_close "kvm_t *kd" 58.Sh DESCRIPTION 59The functions 60.Fn kvm_open 61and 62.Fn kvm_openfiles 63return a descriptor used to access kernel virtual memory 64via the 65.Xr kvm 3 66library routines. Both active kernels and crash dumps are accessible 67through this interface. 68.Pp 69.Fa execfile 70is the executable image of the kernel being examined. 71This file must contain a symbol table. 72If this argument is 73.Dv NULL , 74the currently running system is assumed, 75which is indicated by 76.Dv _PATH_UNIX 77in 78.Pa Aq paths.h . 79.Pp 80.Fa corefile 81is the kernel memory device file. It can be either 82.Pa /dev/mem 83or a crash dump core generated by 84.Xr savecore 8 . 85If 86.Fa corefile 87is 88.Dv NULL , 89the default indicated by 90.Dv _PATH_MEM 91from 92.Pa Aq paths.h 93is used. 94.Pp 95.Fa swapfile 96should indicate the swap device. If 97.Dv NULL , 98.Dv _PATH_DRUM 99from 100.Pa Aq paths.h 101is used. 102.Pp 103The 104.Fa flags 105argument indicates read/write access as in 106.Xr open 2 107and applies only to the core file. 108Only 109.Dv O_RDONLY , 110.Dv O_WRONLY , 111and 112.Dv O_RDWR 113are permitted. 114.Pp 115There are two open routines which differ only with respect to 116the error mechanism. 117One provides backward compatibility with the SunOS kvm library, while the 118other provides an improved error reporting framework. 119.Pp 120The 121.Fn kvm_open 122function is the Sun kvm compatible open call. Here, the 123.Fa errstr 124argument indicates how errors should be handled. If it is 125.Dv NULL , 126no errors are reported and the application cannot know the 127specific nature of the failed kvm call. 128If it is not 129.Dv NULL , 130errors are printed to stderr with 131.Fa errstr 132prepended to the message, as in 133.Xr perror 3 . 134Normally, the name of the program is used here. 135The string is assumed to persist at least until the corresponding 136.Fn kvm_close 137call. 138.Pp 139The 140.Fn kvm_openfiles 141function provides BSD style error reporting. 142Here, error messages are not printed out by the library. 143Instead, the application obtains the error message 144corresponding to the most recent kvm library call using 145.Fn kvm_geterr 146(see 147.Xr kvm_geterr 3 ). 148The results are undefined if the most recent kvm call did not produce 149an error. 150Since 151.Fn kvm_geterr 152requires a kvm descriptor, but the open routines return 153.Dv NULL 154on failure, 155.Fn kvm_geterr 156cannot be used to get the error message if open fails. 157Thus, 158.Fn kvm_openfiles 159will place any error message in the 160.Fa errbuf 161argument. This buffer should be _POSIX2_LINE_MAX characters large (from 162.Pa Aq limits.h ) . 163.Sh RETURN VALUES 164The 165.Fn kvm_open 166and 167.Fn kvm_openfiles 168functions both return a descriptor to be used 169in all subsequent kvm library calls. 170The library is fully re-entrant. 171On failure, 172.Dv NULL 173is returned, in which case 174.Fn kvm_openfiles 175writes the error message into 176.Fa errbuf . 177.Pp 178The 179.Fn kvm_close 180function returns 0 on success and -1 on failure. 181.Sh BUGS 182There should not be two open calls. The ill-defined error semantics 183of the Sun library and the desire to have a backward-compatible library 184for BSD left little choice. 185.Sh SEE ALSO 186.Xr open 2 , 187.Xr kvm 3 , 188.Xr kvm_getargv 3 , 189.Xr kvm_getenvv 3 , 190.Xr kvm_geterr 3 , 191.Xr kvm_getprocs 3 , 192.Xr kvm_nlist 3 , 193.Xr kvm_read 3 , 194.Xr kvm_write 3 195