libcrash(5)							File Formats Manual						       libcrash(5)

NAME

       libcrash - crash dump access library

SYNOPSIS

DESCRIPTION

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

	      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 corresponding to
				  one of the error or warning codes returned by another library call.

	      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 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 cor-
		     respondence 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, consists of a directory containing an file, the kernel file, and numerous
		     files, which contain portions of the physical 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 dynamically 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 memory 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 analyzing 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 supported
					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  meanings  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 ALSO

       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).

																       libcrash(5)