libcrash(5) libcrash(5)
NAME [Toc] [Back]
libcrash - crash dump access library
SYNOPSIS [Toc] [Back]
#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);
DESCRIPTION [Toc] [Back]
libcrash 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
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: Sep 2004
libcrash(5) libcrash(5)
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 Formats [Toc] [Back]
There 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
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: Sep 2004
libcrash(5) libcrash(5)
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.
Cache [Toc] [Back]
Caching 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 VALUE [Toc] [Back]
Most 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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: Sep 2004
libcrash(5) libcrash(5)
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.
AUTHOR [Toc] [Back]
libcrash was developed by HP.
SEE ALSO [Toc] [Back]
cr_close(3), cr_info(3), cr_isaddr(3), cr_open(3), cr_perror(3),
cr_read(3), cr_set_node(3), cr_uncompress(3), cr_verify(3).
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: Sep 2004 [ Back ] |
