|
» |
|
|
|
NAMElibcrash — crash dump access library SYNOPSIS#include <libcrash.h> int cr_open(const char *path, CRASH **cb, int flags);
int cr_verify(CRASH *crash_cb, int flags);
cr_info_t *cr_info(CRASH *crash_cb);
int cr_uncompress(CRASH *crash_cb, const char *pathname,
uint64_t size, int flags);
int cr_isaddr(CRASH *crash_cb, uint64_t pagenum, int *avail);
int cr_read(CRASH *crash_cb, void *buf, uint64_t mem_page,
int *num_pages);
int cr_set_node(CRASH *crash_cb, int node_num,
int *old_node_num);
void cr_perror(CRASH *crash_cb, int error);
int cr_close(CRASH *crash_cb); DESCRIPTIONlibcrash
is a library which provides access to system crash dumps. Access to
a dump through the library is independent of the format of the crash
dump (there are several, described below). It is also independent of
the location of the dump, which could be on a raw dump device, in
files in a file system, or a mixture of the two. The memory of a
running system can also be treated as a "dump" through use of the
/dev/mem
driver. All accesses to a dump through the library begin with a call to
cr_open().
The crash dump descriptor returned from this call is a necessary
parameter to all of the other
libcrash
calls. They are:
- cr_verify()
Verifies the integrity of a dump by checking the sizes and checksums
of all of the files making up the dump. - cr_info()
Returns a pointer to a structure containing information about the dump
and the machine and kernel that produced it. - cr_uncompress()
Prepares a file in the crash dump for use, by uncompressing it (if
needed) and validating its size and checksum. This function is used
internally by the library for access to the physical memory image, and
can be used by callers for access to the kernel and kernel module
files. - cr_isaddr()
Gives information about whether a particular physical memory page
was valid on the machine that dumped, and if so, whether or not that
page's contents were included in the dump. - cr_read()
Reads pages from the dump. - cr_set_node()
Sets the node number that is used by
cr_read()
and
cr_isaddr()
to access memory in the node private memory areas. - cr_perror()
Prints to standard error an error or warning message corresponding to
one of the error or warning codes returned by another library call. - cr_close()
Terminates access to the crash dump and frees all space allocated by
the library.
Each of the above calls has its own manual page, describing its usage
more fully. Crash Dump FormatsThere are four current formats of system crash dumps:
- COREFILE
(Version 0)
This format, used up through
HP-UX
10.01, consists of a single file containing the physical memory
image, with a 1-to-1 correspondence between file offset and
memory address. Usually there is an associated file containing
the kernel image. - COREDIR
(Version 1)
This format, used in
HP-UX 10.10, 10.20, and 10.30,
consists of a
core.n
directory containing an
INDEX
file, the kernel
(vmunix)
file, and numerous
core.n.m
files, which contain portions of the physical memory image. - CRASHDIR
(Version 2)
This format, used in
HP-UX
11.00 and later, consists of a
crash.n
directory containing an
INDEX
file, the kernel and all dynamically loaded kernel module files,
and numerous
image.m.p
files, each of which contain portions of the physical memory image
and metadata describing which memory pages were dumped and which were not. - PARDIR
(Version 5)
This format is used in
HP-UX
Release 11i Version 1.0 and later. It is very similar in structure to the
CRASHDIR
format in that it consists of a
crash.n
directory containing an
INDEX
file, the kernel and all dynamically loaded kernel module files,
and numerous
image.m.p
files, each of which contain portions of the physical memory image and
metadata describing which memory pages were dumped and which were not.
In addition to the primary
INDEX
file, there are auxiliary index files, that contain
metadata describing the image files containing the memory pages. This
format will be used when the dump devices have compressed memory
images. See
crashconf(1M).
Other formats, for example tape archival formats, may be added in the
future. CacheCaching mechanism is implemented to improve the performance while analyzing
PARDIR
format crash dumps.
This caching mechanism is used to keep the uncompressed pages so
that subsequent requests can be satisfied from the cache.
By default, this caching mechanism will be disabled.
It can be enabled by setting the environment variable
LIBCRASH_ENABLE_CACHE.
It will create the cached files in the crash dump directory. RETURN VALUEMost of the calls in
libcrash
return an integer status value. A zero return value indicates
success. A positive return value indicates some sort of warning,
despite which the requested operation was completed. A negative
return value indicates some sort of error, which prevented completion
of the requested operation. The values returned by the library are:
- CR_OK
Success. - CRWARN_NOEXPECTED
The expected size or checksum of one or more files in the crash dump
was not recorded, so the integrity of the dump cannot be verified.
The dump might be corrupt. - CRWARN_NOACTUAL
The checksum of one or more files in the crash dump could not be
computed, so it could not be checked against the expected value. The
dump might be corrupt. - CRWARN_SWAPPEDON
A raw device containing a portion of the crash dump has been swapped
on, so the dump is probably corrupt. - CRWARN_MISMATCH
The size or checksum of one or more files in the crash dump did not
match what was expected. The dump is probably corrupt. - CRERR_NOPAGE
A read or write request was issued for a memory address that does not
exist on the target machine. - CRERR_READONLY
A write request was issued for a crash dump. Writes are supported
only to running systems through the
/dev/mem
driver. - CRERR_WRONGDUMP
A raw dump device which is supposed to contain part of the dump does not.
It may have been overwritten by swap activity or by a more recent dump. - CRERR_WRONGHOST
A portion of the crash dump still resides on a dump device of the system
that dumped, which is not the current system. - CRERR_NONODE
The specified node number does not exist. - CRERR_ERRNO
A system error occurred. Consult
errno
for the specific error. Note that certain values for
errno
have specific meanings in the context of the library. They include:
- [ENOEXEC]
A portion of the crash dump could not be uncompressed. - [ENOTDIR]
The specified pathname for the dump was neither a plain file, nor a
directory containing an INDEX file, nor the
/dev/mem
pseudodriver.
- \
Other values of
errno
have their traditional meanings.
AUTHORlibcrash
was developed by HP.
|