kvm_open(3kvm)

1kvm_open(3KVM)            Kernel VM Library Functions           kvm_open(3KVM)
2
3
4

NAME

6       kvm_open, kvm_close - specify a kernel to examine
7

SYNOPSIS

9       cc [ flag... ] file... -lkvm [ library...]
10       #include <kvm.h>
11       #include <fcntl.h>
12
13       kvm_t *kvm_open(char *namelist, char *corefile, char *swapfile, int flag,
14            char *errstr);
15
16
17       int kvm_close(kvm_t *kd);
18
19

DESCRIPTION

21       The  kvm_open()  function  initializes  a set of file descriptors to be
22       used in subsequent calls to kernel virtual memory ( VM)  routines.   It
23       returns  a  pointer  to a kernel identifier that must be used as the kd
24       argument in subsequent kernel VM function calls.
25
26
27       The namelist argument specifies an  unstripped  executable  file  whose
28       symbol  table  will  be  used to locate various offsets in corefile. If
29       namelist is NULL, the symbol table of the currently running  kernel  is
30       used to determine offsets in the core image.  In this case, it is up to
31       the implementation to select an appropriate  way  to  resolve  symbolic
32       references, for instance, using /dev/ksyms as a default namelist file.
33
34
35       The corefile argument specifies a file that contains an image of physi‐
36       cal memory, for instance, a kernel crash dump file  (see  savecore(1M))
37       or the special device /dev/mem. If corefile is NULL, the currently run‐
38       ning kernel is accessed, using /dev/mem and /dev/kmem.
39
40
41       The swapfile argument specifies a file that represents the swap device.
42       If  both  corefile  and  swapfile are NULL, the swap device of the cur‐
43       rently running kernel is accessed.  Otherwise,  if  swapfile  is  NULL,
44       kvm_open() may succeed but subsequent kvm_getu(3KVM) function calls may
45       fail if the desired information is swapped out.
46
47
48       The flag function is used to specify read or write access for  corefile
49       and may have one of the following values:
50
51       O_RDONLY    open for reading
52
53
54       O_RDWR      open for reading and writing
55
56
57
58       The  errstr  argument  is  used to control error reporting.  If it is a
59       null pointer, no error messages will be printed. If it is non-null,  it
60       is  assumed  to  be the address of a string that will be used to prefix
61       error messages generated by kvm_open. Errors are printed to  stderr.  A
62       useful value to supply for errstr would be argv[0]. This has the effect
63       of printing the process name in front of any error messages.
64
65
66       Applications using  libkvm are dependent on the underlying  data  model
67       of the kernel image, that is, whether it is a 32−bit or 64−bit kernel.
68
69
70       The  data  model of these applications must match the data model of the
71       kernel in order to correctly interpret the size and offsets  of  kernel
72       data  structures.   For  example,  a  32−bit  application that uses the
73       32−bit version of the libkvm interfaces will fail to open a 64−bit ker‐
74       nel  image.   Similarly, a 64−bit application that uses the 64−bit ver‐
75       sion of the libkvm interfaces will fail to open a 32−bit kernel image.
76
77
78       The kvm_close() function closes all file descriptors that were  associ‐
79       ated  with kd. These files are also closed on exit(2) and execve() (see
80       exec(2)). kvm_close() also resets  the  proc  pointer  associated  with
81       kvm_nextproc(3KVM) and flushes any cached kernel data.
82

RETURN VALUES

84       The  kvm_open() function returns a non-null value suitable for use with
85       subsequent kernel VM function calls. On failure, it returns NULL and no
86       files are opened.
87
88
89       The kvm_close() function returns 0 on success and −1 on failure.
90

FILES

92       /dev/kmem
93
94
95       /dev/ksyms
96
97
98       /dev/mem
99
100

ATTRIBUTES

102       See attributes(5) for descriptions of the following attributes:
103
104
105
106
107       ┌─────────────────────────────┬─────────────────────────────┐
108       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
109       ├─────────────────────────────┼─────────────────────────────┤
110       │Interface Stability          │Stable                       │
111       ├─────────────────────────────┼─────────────────────────────┤
112       │MT-Level                     │Unsafe                       │
113       └─────────────────────────────┴─────────────────────────────┘
114

NOTES

122       Kernel core dumps should be examined on the platform on which they were
123       created.  While  a  32-bit  application  running on a 64-bit kernel can
124       examine a 32-bit core dump, a 64-bit application running  on  a  64-bit
125       kernel cannot examine a kernel core dump from the 32-bit system.
126
127
128       On  32-bit  systems, applications that use libkvm to access the running
129       kernel must be 32-bit applications. On systems that support both 32-bit
130       and 64-bit applications, applications that use the libkvm interfaces to
131       access the running kernel must themselves be 64-bit applications.
132
133
134       Although the libkvm API is Stable, the symbol  names  and  data  values
135       that can be accessed through this set of interfaces are Private and are
136       subject to ongoing change.
137
138
139       Applications using  libkvm are likely  to  be  platform-  and  release-
140       dependent.
141
142
143       Most  of  the  traditional  uses of libkvm have been superseded by more
144       stable interfaces that allow the same information to be extracted  more
145       efficiently,  yet  independent of the kernel data model.  For examples,
146       see sysconf(3C),  proc(4),  kstat(3KSTAT),  getloadavg(3C),  and  path‐
147       conf(2).
148
149
150
151SunOS 5.11                        2 May 2002                    kvm_open(3KVM)