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