1.\" Copyright (c) 1992 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)kvm_open.3 5.2 (Berkeley) 04/29/92 7.\" 8.Dd 9.Dt KVM_OPEN 3 10.Os 11.Sh NAME 12.Nm kvm_open , 13.Nm kvm_openfiles , 14.Nm kvm_close 15.Nd initialize kernel virtual memory access 16.Sh SYNOPSIS 17.Fd #include <kvm.h> 18.\" .Fa kvm_t *kd 19.br 20.Ft kvm_t * 21.Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr" 22.Ft kvm_t * 23.Fn kvm_openfiles "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errbuf" 24.Ft int 25.Fn kvm_close "kvm_t *kd" 26.Sh DESCRIPTION 27The functions 28.Fn kvm_open 29and 30.Fn kvm_openfiles 31return a descriptor used to access kernel virtual memory 32via the 33.Xr kvm 3 34library routines. Both active kernels and crash dumps are accessible 35through this interface. 36.Pp 37.Fa execfile 38is the executable image of the kernel being examined. 39This file must contain a symbol table. 40If this argument is 41.Dv NULL , 42the currently running system is assumed, 43which is indicated by 44.Dv _PATH_UNIX 45in <paths.h>. 46.Pp 47.Fa corefile 48is the kernel memory device file. It can be either /dev/mem 49or a crash dump core generated by 50.Xr savecore 8 . 51If 52.Fa corefile 53is 54.Dv NULL , 55the default indicated by 56.Dv _PATH_MEM 57from <paths.h> is used. 58.Pp 59.Fa swapfile 60should indicate the swap device. If 61.Dv NULL , 62.Dv _PATH_DRUM 63from <paths.h> is used. 64.Pp 65The 66.Fa flags 67argument indicates read/write access as in 68.Xr open 2 69and applies to only the core file. 70Only 71.Dv O_RDONLY , 72.Dv O_WRONLY , 73and 74.Dv O_RDWR 75are permitted. 76.Pp 77There are two open routines which differ only with respect to 78the error mechanism. 79One provides backward compatibility with the SunOS kvm library, while the 80other provides an improved error reporting framework. 81.Pp 82The 83.Fn kvm_open 84function is the Sun kvm compatible open call. Here, the 85.Fa errstr 86argument indicates how errors should be handled. If it is 87.Dv NULL , 88no errors are reported and the application cannot know the 89specific nature of the failed kvm call. 90If it is not 91.Dv NULL , 92errors are printed to stderr with 93.Fa errstr 94prepended to the message, as in 95.Xr perror 3 . 96Normally, the name of the program is used here. 97The string is assumed to persist at least until the corresponding 98.Fn kvm_close 99call. 100.Pp 101The 102.Fn kvm_openfiles 103function provides BSD style error reporting. 104Here, error messages are not printed out by the library. 105Instead, the application obtains the error message 106corresponding to the most recent kvm library call using 107.Fn kvm_geterr 108(see 109.Xr kvm_geterr 3 ). 110The results are undefined if the most recent kvm call did not produce 111an error. 112Since 113.Fn kvm_geterr 114requires a kvm descriptor, but the open routines return 115.Dv NULL 116on failure, 117.Fn kvm_geterr 118cannot be used to get the error message if open fails. 119Thus, 120.Fn kvm_openfiles 121will place any error message in the 122.Fa errbuf 123argument. This buffer should be _POSIX2_LINE_MAX characters large (from 124<limits.h>). 125.Sh RETURN VALUES 126The 127.Fn kvm_open 128and 129.Fn kvm_openfiles 130functions both return a descriptor to be used 131in all subsequent kvm library calls. 132The library is fully re-entrant. 133On failure, 134.Dv NULL 135is returned, in which case 136.Fn kvm_openfiles 137writes the error message into 138.Fa errbuf . 139.Pp 140The 141.Fn kvm_close 142function returns 0 on sucess and -1 on failure. 143.Sh BUGS 144There should not be two open calls. The ill-defined error semantics 145of the Sun library and the desire to have a backward-compatible library 146for BSD left little choice. 147.Sh SEE ALSO 148.Xr open 2 , 149.Xr kvm 3 , 150.Xr kvm_getargv 3 , 151.Xr kvm_getenvv 3 , 152.Xr kvm_geterr 3 , 153.Xr kvm_getprocs 3 , 154.Xr kvm_nlist 3 , 155.Xr kvm_read 3 , 156.Xr kvm_write 3 157