KVM_DUMP(3) BSD Library Functions Manual KVM_DUMP(3)NAME
kvm_dump_mkheader, kvm_dump_wrtheader, kvm_dump_inval -- crash dump support functions
LIBRARY
Kernel Data Access Library (libkvm, -lkvm)
SYNOPSIS
#include <kvm.h>
int
kvm_dump_mkheader(kvm_t *kd, off_t dump_off);
int
kvm_dump_wrtheader(kvm_t *kd, FILE *fp, int dumpsize);
int
kvm_dump_inval(kvm_t *kd);
DESCRIPTION
First note that the functions described here were designed to be used by savecore(8).
The function kvm_dump_mkheader() checks if the physical memory file associated with kd contains a valid crash dump header as generated by a
dumping kernel. When a valid header is found, kvm_dump_mkheader() initializes the internal kvm data structures as if a crash dump generated
by the savecore(8) program was opened. This has the intentional side effect of enabling the address translation machinery.
A call to kvm_dump_mkheader() will most likely be followed by a call to kvm_dump_wrtheader(). This function takes care of generating the
generic header, the CORE_CPU section and the section header of the CORE_DATA section. The data is written to the file pointed at by fp. The
dumpsize argument is only used to properly the set the segment size of the CORE_DATA section. Note that this function assumes that fp is
positioned at file location 0. This function will not seek and therefore allows fp to be a file pointer obtained by zopen().
The kvm_dump_inval() function clears the magic number in the physical memory file associated with kd. The address translations must be
enabled for this to work (thus assuming that kvm_dump_mkheader() was called earlier in the sequence).
RETURN VALUES
All functions except kvm_dump_mkheader() return 0 on success, -1 on failure. The function kvm_dump_mkheader() returns the size of the head-
ers present before the actual dumpdata starts. If no valid headers were found but no fatal errors occurred, 0 is returned. On fatal errors
the return value is -1.
In the case of failure, kvm_geterr(3) can be used to retrieve the cause of the error.
SEE ALSO kvm(3), kvm_open(3)HISTORY
These functions first appeared in NetBSD 1.2.
BSD March 17, 1996 BSD
Check Out this Related Man Page
KVM_OPEN(3) BSD Library Functions Manual KVM_OPEN(3)NAME
kvm_open, kvm_openfiles, kvm_close -- initialize kernel virtual memory access
LIBRARY
Kernel Data Access Library (libkvm, -lkvm)
SYNOPSIS
#include <fcntl.h>
#include <kvm.h>
kvm_t *
kvm_open(const char *execfile, const char *corefile, char *swapfile, int flags, const char *errstr);
kvm_t *
kvm_openfiles(const char *execfile, const char *corefile, char *swapfile, int flags, char *errbuf);
int
kvm_close(kvm_t *kd);
DESCRIPTION
The functions kvm_open() and kvm_openfiles() return a descriptor used to access kernel virtual memory via the kvm(3) library routines. Both
active kernels and crash dumps are accessible through this interface.
execfile is the executable image of the kernel being examined. This file must contain a symbol table. If this argument is NULL, the cur-
rently running system is assumed; in this case, the functions will attempt to use the ksyms(4) device indicated by _PATH_KSYMS in <paths.h>;
if that fails, then they will use the file indicated by the sysctl(3) variable machdep.booted_kernel, or (if the sysctl information is not
available) the default kernel path indicated by _PATH_UNIX in <paths.h>.
corefile is the kernel memory device file. It can be either /dev/mem or a crash dump core generated by savecore(8). If corefile is NULL,
the default indicated by _PATH_MEM from <paths.h> is used.
swapfile should indicate the swap device. If NULL, _PATH_DRUM from <paths.h> is used.
The flags argument indicates read/write access as in open(2) and applies only to the core file. The only permitted flags from open(2) are
O_RDONLY, O_WRONLY, and O_RDWR.
As a special case, a flags argument of KVM_NO_FILES will initialize the kvm(3) library for use on active kernels only using sysctl(3) for
retrieving kernel data and ignores the execfile, corefile and swapfile arguments. Only a small subset of the kvm(3) library functions are
available using this method. These are currently kvm_getproc2(3), kvm_getargv2(3) and kvm_getenvv2(3).
There are two open routines which differ only with respect to the error mechanism. One provides backward compatibility with the SunOS kvm
library, while the other provides an improved error reporting framework.
The kvm_open() function is the Sun kvm compatible open call. Here, the errstr argument indicates how errors should be handled. If it is
NULL, no errors are reported and the application cannot know the specific nature of the failed kvm call. If it is not NULL, errors are
printed to stderr with errstr prepended to the message, as in perror(3). Normally, the name of the program is used here. The string is
assumed to persist at least until the corresponding kvm_close() call.
The kvm_openfiles() function provides BSD style error reporting. Here, error messages are not printed out by the library. Instead, the
application obtains the error message corresponding to the most recent kvm library call using kvm_geterr() (see kvm_geterr(3)). The results
are undefined if the most recent kvm call did not produce an error. Since kvm_geterr() requires a kvm descriptor, but the open routines
return NULL on failure, kvm_geterr() cannot be used to get the error message if open fails. Thus, kvm_openfiles() will place any error mes-
sage in the errbuf argument. This buffer should be _POSIX2_LINE_MAX characters large (from <limits.h>).
RETURN VALUES
The kvm_open() and kvm_openfiles() functions both return a descriptor to be used in all subsequent kvm library calls. The library is fully
re-entrant. On failure, NULL is returned, in which case kvm_openfiles() writes the error message into errbuf.
The kvm_close() function returns 0 on success and -1 on failure.
SEE ALSO open(2), kvm(3), kvm_getargv(3), kvm_getenvv(3), kvm_geterr(3), kvm_getkernelname(3), kvm_getprocs(3), kvm_nlist(3), kvm_read(3),
kvm_write(3)BUGS
There should not be two open calls. The ill-defined error semantics of the Sun library and the desire to have a backward-compatible library
for BSD left little choice.
BSD September 14, 2011 BSD