libcrash(5)

NAME

libcrash — 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); 
void       cr_perror(CRASH *crash_cb, int error); 
int        cr_close(CRASH *crash_cb); 

DESCRIPTION

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 page's contents were included in the dump.
cr_read(): Reads pages from the dump.
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

There are three 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

CURRENT

(Version 2 — the current version) 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.

Other formats, for example tape archival formats, may be added in the future.

RETURN VALUES

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.

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_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

libcrash was developed by HP.

libcrash(5)

Technical documentation

» Table of Contents

» Index