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