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.\" 3. 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.\" 34.Dd March 20, 2017 35.Dt KVM_OPEN 3 36.Os 37.Sh NAME 38.Nm kvm_open , 39.Nm kvm_open2 , 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.Fo kvm_open2 52.Fa "const char *execfile" 53.Fa "const char *corefile" 54.Fa "int flags" 55.Fa "char *errbuf" 56.Fa "int (*resolver)(const char *name, kvaddr_t *addr)" 57.Fc 58.Ft kvm_t * 59.Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf" 60.Ft int 61.Fn kvm_close "kvm_t *kd" 62.Sh DESCRIPTION 63The functions 64.Fn kvm_open , 65.Fn kvm_open2 , 66and 67.Fn kvm_openfiles 68return a descriptor used to access kernel virtual memory 69via the 70.Xr kvm 3 71library routines. 72Both active kernels and crash dumps are accessible 73through this interface. 74.Pp 75The 76.Fa execfile 77argument is the executable image of the kernel being examined. 78This file must contain a symbol table. 79If this argument is 80.Dv NULL , 81the currently running system is assumed, 82as determined from 83.Xr getbootfile 3 . 84.Pp 85The 86.Fa corefile 87argument is the kernel memory device file. 88It can be either 89.Pa /dev/mem 90or a crash dump core generated by 91.Xr savecore 8 . 92If 93.Fa corefile 94is 95.Dv NULL , 96the default indicated by 97.Dv _PATH_MEM 98from 99.In paths.h 100is used. 101It can also be set to a special value 102.Pa /dev/null 103by utilities like 104.Xr ps 1 105that do not directly access kernel memory. 106.Pp 107The 108.Fa swapfile 109argument is currently unused. 110.Pp 111The 112.Fa flags 113argument indicates read/write access as in 114.Xr open 2 115and applies only to the core file. 116Only 117.Dv O_RDONLY , 118.Dv O_WRONLY , 119and 120.Dv O_RDWR 121are permitted. 122.Pp 123The 124.Nm kvm 125library provides two different error reporting mechanisms. 126One provides backward compatibility with the SunOS kvm library, while the 127other provides an improved error reporting framework. 128The mechanism used by a descriptor is determined by the function used to 129open the descriptor. 130.Pp 131The 132.Fn kvm_open 133function is the Sun kvm compatible open call. 134Here, the 135.Fa errstr 136argument indicates how errors should be handled. 137If it is 138.Dv NULL , 139no errors are reported and the application cannot know the 140specific nature of the failed kvm call. 141If it is not 142.Dv NULL , 143errors are printed to 144.Dv stderr 145with 146.Fa errstr 147prepended to the message, as in 148.Xr perror 3 . 149Normally, the name of the program is used here. 150The string is assumed to persist at least until the corresponding 151.Fn kvm_close 152call. 153.Pp 154The 155.Fn kvm_open2 156and 157.Fn kvm_openfiles 158functions provide 159.Bx 160style error reporting. 161Here, error messages are not printed out by the library. 162Instead, the application obtains the error message 163corresponding to the most recent kvm library call using 164.Fn kvm_geterr 165(see 166.Xr kvm_geterr 3 ) . 167The results are undefined if the most recent kvm call did not produce 168an error. 169Since 170.Fn kvm_geterr 171requires a kvm descriptor, but the open routines return 172.Dv NULL 173on failure, 174.Fn kvm_geterr 175cannot be used to get the error message if open fails. 176Thus, 177.Fn kvm_open2 178and 179.Fn kvm_openfiles 180will place any error message in the 181.Fa errbuf 182argument. 183This buffer should be _POSIX2_LINE_MAX characters large (from 184<limits.h>). 185.Pp 186The 187.Fa resolver 188argument points to a function used by the 189.Nm kvm 190library to map symbol names to kernel virtual addresses. 191When the 192.Fa resolver 193function is called, 194.Fa name 195specifies the requested symbol name. 196If the function is able to resolve the name to an address, 197the address should be set in 198.Fa addr 199and the function should return zero. 200If the function is not able to resolve the name to an address, 201it should return a non-zero value. 202When opening a native kernel image, 203.Fa resolver 204may be set to 205.Dv NULL 206to use an internal function to resolve symbol names. 207Non-native kernel images 208.Pq such as when cross-debugging a crash dump 209require a valid 210.Fa resolver . 211.Sh RETURN VALUES 212The 213.Fn kvm_open , 214.Fn kvm_open2 , 215and 216.Fn kvm_openfiles 217functions return a descriptor to be used 218in all subsequent kvm library calls. 219The library is fully re-entrant. 220On failure, 221.Dv NULL 222is returned, in which case 223.Fn kvm_open2 224and 225.Fn kvm_openfiles 226write the error message into 227.Fa errbuf . 228.Pp 229.Rv -std kvm_close 230.Sh ERRORS 231The 232.Fn kvm_close 233function may fail and set the global variable 234.Va errno 235for any of the errors specified for 236.Xr close 2 . 237.Pp 238The 239.Fn kvm_close 240function may also fail and set 241.Va errno 242if: 243.Bl -tag -width Er 244.It Bq Er EINVAL 245The value passed via 246.Fa kd 247was 248.Dv NULL . 249.El 250.Sh SEE ALSO 251.Xr close 2 , 252.Xr open 2 , 253.Xr kvm 3 , 254.Xr kvm_getargv 3 , 255.Xr kvm_getenvv 3 , 256.Xr kvm_geterr 3 , 257.Xr kvm_getprocs 3 , 258.Xr kvm_native 3 , 259.Xr kvm_nlist 3 , 260.Xr kvm_read 3 , 261.Xr kvm_write 3 , 262.Xr kmem 4 , 263.Xr mem 4 264.Sh BUGS 265There should not be three open calls. 266The ill-defined error semantics 267of the Sun library and the desire to have a backward-compatible library 268for 269.Bx 270left little choice. 271.Sh HISTORY 272The 273.Fn kvm_open2 274function first appeared in 275.Fx 11.0 . 276