libcrash(5)libcrash(5)NAMElibcrash - crash dump access library
SYNOPSISDESCRIPTION
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 driver.
All accesses to a dump through the library begin with a call to The
crash dump descriptor returned from this call is a necessary parameter
to all of the other calls. They are:
Verifies the integrity of a dump by checking the sizes and
checksums
of all of the files making up the dump.
Returns a pointer to a structure containing information about
the dump
and the machine and kernel that produced it.
Prepares a file in the crash dump for use, by uncompressing it
(if
needed) and validating its size and check‐
sum. This function is used internally by
the library for access to the physical mem‐
ory image, and can be used by callers for
access to the kernel and kernel module
files.
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.
Reads pages from the dump.
Sets the node number that is used by
and to access memory in the node private
memory areas.
Prints to standard error an error or warning message correspond‐
ing to
one of the error or warning codes returned
by another library call.
Terminates access to the crash dump and frees all space allo‐
cated by
the library.
Each of the above calls has its own manual page, describing its usage
more fully.
Crash Dump Formats
There are four current formats of system crash dumps:
(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.
(Version 1) This format, used in HP-UX 10.10, 10.20, and 10.30, con‐
sists of a directory containing an file, the kernel file,
and numerous files, which contain portions of the physi‐
cal memory image.
(Version 2) This format, used in HP-UX 11.00 and later, consists of a
directory containing an file, the kernel and all dynami‐
cally loaded kernel module files, and numerous files,
each of which contain portions of the physical memory
image and metadata describing which memory pages were
dumped and which were not.
(Version 5) This format is used in HP-UX Release 11i Version 1.0 and
later. It is very similar in structure to the format in
that it consists of a directory containing an file, the
kernel and all dynamically loaded kernel module files,
and numerous files, each of which contain portions of the
physical memory image and metadata describing which mem‐
ory pages were dumped and which were not. In addition to
the primary 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 crash‐
conf(1M).
Other formats, for example tape archival formats, may be added in the
future.
Cache
Caching mechanism is implemented to improve the performance while ana‐
lyzing 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 It will create the
cached files in the crash dump directory.
RETURN VALUE
Most of the calls in 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:
Success.
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.
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.
A raw device containing a portion of the crash dump has been
swapped
on, so the dump is probably corrupt.
The size or checksum of one or more files in the crash dump did
not
match what was expected. The dump is
probably corrupt.
A read or write request was issued for a memory address that
does not
exist on the target machine.
A write request was issued for a crash dump. Writes are sup‐
ported
only to running systems through the
driver.
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.
A portion of the crash dump still resides on a dump device of
the system
that dumped, which is not the current
system.
The specified node number does not exist.
A system error occurred. Consult
for the specific error. Note that
certain values for have specific mean‐
ings in the context of the library.
They include:
A portion of the crash dump could not
be uncompressed.
The specified pathname for the dump
was neither a plain file, nor a
directory containing an
INDEX file, nor the
pseudodriver.
Other values of have their traditional meanings.
AUTHOR
was developed by HP.
SEE ALSOcr_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).
libcrash(5)
