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