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