libkdumpfile-0.5.4
Kernel coredump file access
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs
kdumpfile.h File Reference

Public interface for libkdumpfile (kernel coredump file access). More...

#include <stddef.h>
#include <stdint.h>
#include <unistd.h>
#include <sys/sysmacros.h>
#include "addrxlat.h"

Data Structures

union  _kdump_attr_value
 Dump file attribute value. More...
 
struct  _kdump_attr
 Dump file attribute: type + value. More...
 
struct  _kdump_attr_ref
 Reference to an attribute. More...
 
struct  _kdump_attr_iter
 Attribute iterator. More...
 

Macros

#define KDUMPFILE_VER_MAJOR   0
 Major version (1st number in the release tag).
 
#define KDUMPFILE_VER_MINOR   5
 Minor version (2nd number in the release tag).
 
#define KDUMPFILE_VER_MICRO   4
 Micro version (3rd number in the release tag).
 
#define KDUMPFILE_MKVER(major, minor, micro)    (((major) << 16) | ((minor) << 8) | ((micro)))
 Make a single-number version from three digits of the release tag.
 
#define KDUMPFILE_VERSION
 Version as a single number.
 
#define KDUMPFILE_VERSION_STRING   "0.5.4"
 Version as a string constant.
 

Typedefs

typedef uint_fast64_t kdump_num_t
 Type of a generic number.
 

fprintf() macros for the libkdumpfile number type

POSIX PRI_xxx style macros for use with kdump_num_t.

#define KDUMP_PRIoNUM   PRIoFAST64
 Octal kdump_num_t.
 
#define KDUMP_PRIuNUM   PRIuFAST64
 Decimal kdump_num_t.
 
#define KDUMP_PRIxNUM   PRIxFAST64
 Lowercase hex kdump_num_t.
 
#define KDUMP_PRIXNUM   PRIXFAST64
 Uppercase hex kdump_num_t.
 
#define KDUMP_ADDR_MAX   ADDRXLAT_ADDR_MAX
 Maximum value represented by kdump_addr_t.
 
typedef addrxlat_addr_t kdump_addr_t
 Type of a physical or virtual address.
 
typedef kdump_addr_t kdump_paddr_t
 Type of a physical address.
 
typedef kdump_addr_t kdump_vaddr_t
 Type of a virtual addresses.
 

fprintf() macros for the libkdumpfile address type

POSIX PRI_xxx style macros for use with kdump_addr_t, kdump_paddr_t and kdump_vaddr_t.

#define KDUMP_PRIoADDR   ADDRXLAT_PRIoADDR
 Octal address.
 
#define KDUMP_PRIuADDR   ADDRXLAT_PRIuADDR
 Decimal address.
 
#define KDUMP_PRIxADDR   ADDRXLAT_PRIxADDR
 Lowercase hex address.
 
#define KDUMP_PRIXADDR   ADDRXLAT_PRIXADDR
 Uppercase hex address.
 
enum  _kdump_status {
  KDUMP_OK = 0 , KDUMP_ERR_SYSTEM , KDUMP_ERR_NOTIMPL , KDUMP_ERR_NODATA ,
  KDUMP_ERR_CORRUPT , KDUMP_ERR_INVALID , KDUMP_ERR_NOKEY , KDUMP_ERR_EOF ,
  KDUMP_ERR_BUSY , KDUMP_ERR_ADDRXLAT
}
 Status code. More...
 
enum  _kdump_byte_order { KDUMP_BIG_ENDIAN = ADDRXLAT_BIG_ENDIAN , KDUMP_LITTLE_ENDIAN = ADDRXLAT_LITTLE_ENDIAN }
 Target dump byte order. More...
 
enum  _kdump_mmap_policy { KDUMP_MMAP_NEVER , KDUMP_MMAP_ALWAYS , KDUMP_MMAP_TRY , KDUMP_MMAP_TRY_ONCE }
 File mmap policy. More...
 
enum  _kdump_xen_type { KDUMP_XEN_NONE , KDUMP_XEN_SYSTEM , KDUMP_XEN_DOMAIN }
 Type of a Xen dump. More...
 
enum  _kdump_xen_xlat { KDUMP_XEN_AUTO , KDUMP_XEN_NONAUTO }
 Xen physmap translation type. More...
 
enum  kdump_clone_bits { KDUMP_CLONE_BIT_XLAT }
 Clone flag bits. More...
 
typedef struct _kdump_ctx kdump_ctx_t
 Representation of a dump file.
 
typedef enum _kdump_status kdump_status
 Status code.
 
typedef enum _kdump_byte_order kdump_byte_order_t
 Target dump byte order.
 
typedef enum _kdump_mmap_policy kdump_mmap_policy_t
 File mmap policy.
 
typedef enum _kdump_xen_type kdump_xen_type_t
 Type of a Xen dump.
 
typedef enum _kdump_xen_xlat kdump_xen_xlat_t
 Xen physmap translation type.
 
kdump_ctx_tkdump_new (void)
 Initialize a new dump file object.
 

Clone Flags

#define KDUMP_CLONE_XLAT   (1UL << KDUMP_CLONE_BIT_XLAT)
 Do not share address translation.
 
#define KDUMP_ATTR_FILE_FD   "file.fd"
 File descriptor attribute.
 
#define KDUMP_ATTR_FILE_SET   "file.set"
 Base directory of a file set.
 
#define KDUMP_ATTR_FILE_FORMAT   "file.format"
 File format name attribute.
 
#define KDUMP_ATTR_FILE_PAGEMAP   "file.pagemap"
 File page map attribute.
 
#define KDUMP_ATTR_MEMORY_PAGEMAP   "memory.pagemap"
 Memory page map attribute.
 
#define KDUMP_ATTR_ARCH_NAME   "arch.name"
 Canonical architecture name attribute.
 
enum  _kdump_addrspace { KDUMP_KPHYSADDR = ADDRXLAT_KPHYSADDR , KDUMP_MACHPHYSADDR = ADDRXLAT_MACHPHYSADDR , KDUMP_KVADDR = ADDRXLAT_KVADDR , KDUMP_NOADDR = ADDRXLAT_NOADDR }
 Address spaces used by kdump_read() More...
 
enum  _kdump_attr_type {
  KDUMP_NIL , KDUMP_DIRECTORY , KDUMP_NUMBER , KDUMP_ADDRESS ,
  KDUMP_STRING , KDUMP_BITMAP , KDUMP_BLOB
}
 Dump file attribute value type. More...
 
typedef enum _kdump_addrspace kdump_addrspace_t
 Address spaces used by kdump_read()
 
typedef struct _kdump_bmp kdump_bmp_t
 Dump bitmap.
 
typedef struct _kdump_blob kdump_blob_t
 Dump binary large object (BLOB).
 
typedef enum _kdump_attr_type kdump_attr_type_t
 Dump file attribute value type.
 
typedef union _kdump_attr_value kdump_attr_value_t
 Dump file attribute value.
 
typedef struct _kdump_attr kdump_attr_t
 Dump file attribute: type + value.
 
typedef struct _kdump_attr_ref kdump_attr_ref_t
 Reference to an attribute.
 
typedef struct _kdump_attr_iter kdump_attr_iter_t
 Attribute iterator.
 
kdump_ctx_tkdump_clone (const kdump_ctx_t *orig, unsigned long flags)
 Clone a dump file object.
 
void kdump_free (kdump_ctx_t *ctx)
 Free a dump file object.
 
kdump_status kdump_err (kdump_ctx_t *ctx, kdump_status status, const char *msgfmt,...) __attribute__((format(printf
 Prepend an error message.
 
kdump_status void kdump_clear_err (kdump_ctx_t *ctx)
 Clear the error message.
 
const char * kdump_get_err (kdump_ctx_t *ctx)
 Get a detailed error string.
 
kdump_status kdump_get_addrxlat (kdump_ctx_t *ctx, addrxlat_ctx_t **axctx, addrxlat_sys_t **axsys)
 Get the associated address translation data structures.
 
uint_fast16_t kdump_d16toh (kdump_ctx_t *ctx, uint_fast16_t val)
 Convert a 16-bit value from dump to host byte order.
 
uint_fast32_t kdump_d32toh (kdump_ctx_t *ctx, uint_fast32_t val)
 Convert a 32-bit value from dump to host byte order.
 
uint_fast64_t kdump_d64toh (kdump_ctx_t *ctx, uint_fast64_t val)
 Convert a 64-bit value from dump to host byte order.
 
kdump_status kdump_set_filenames (kdump_ctx_t *ctx, unsigned n, const char *const *names)
 Set descriptive file names.
 
kdump_status kdump_open_fdset (kdump_ctx_t *ctx, unsigned nfds, const int *fds)
 Open a set of dump files.
 
kdump_status kdump_read (kdump_ctx_t *ctx, kdump_addrspace_t as, kdump_addr_t addr, void *buffer, size_t *plength)
 Read data from the dump file.
 
kdump_status kdump_read_string (kdump_ctx_t *ctx, kdump_addrspace_t as, kdump_addr_t addr, char **pstr)
 Read a string from the dump file.
 
unsigned long kdump_bmp_incref (kdump_bmp_t *bmp)
 Increment kdump bitmap reference counter.
 
unsigned long kdump_bmp_decref (kdump_bmp_t *bmp)
 Decrement kdump bitmap reference counter.
 
const char * kdump_bmp_get_err (const kdump_bmp_t *bmp)
 Get a detailed error string.
 
kdump_status kdump_bmp_get_bits (kdump_bmp_t *bmp, kdump_addr_t first, kdump_addr_t last, unsigned char *raw)
 Get bitmap bits as a raw bitmap.
 
kdump_status kdump_bmp_find_set (kdump_bmp_t *bmp, kdump_addr_t *idx)
 Find the closest set bit in a bitmap.
 
kdump_status kdump_bmp_find_clear (kdump_bmp_t *bmp, kdump_addr_t *idx)
 Find the closest zero bit in a bitmap.
 
kdump_blob_tkdump_blob_new (void *data, size_t size)
 Create a new blob object.
 
kdump_blob_tkdump_blob_new_dup (const void *data, size_t size)
 Create a new blob object from a copy of a buffer.
 
unsigned long kdump_blob_incref (kdump_blob_t *blob)
 Increment kdump blob reference counter.
 
unsigned long kdump_blob_decref (kdump_blob_t *blob)
 Decrement kdump blob reference counter.
 
void * kdump_blob_pin (kdump_blob_t *blob)
 Pin the internal data buffer.
 
unsigned long kdump_blob_unpin (kdump_blob_t *blob)
 Unpin the internal data buffer.
 
size_t kdump_blob_size (const kdump_blob_t *blob)
 Get a blob size in bytes.
 
kdump_status kdump_blob_set (kdump_blob_t *blob, void *data, size_t size)
 Set kdump blob data.
 
kdump_status kdump_set_attr (kdump_ctx_t *ctx, const char *key, const kdump_attr_t *valp)
 Set a dump file attribute.
 
kdump_status kdump_get_attr (kdump_ctx_t *ctx, const char *key, kdump_attr_t *valp)
 Get a dump file attribute.
 
kdump_status kdump_get_typed_attr (kdump_ctx_t *ctx, const char *key, kdump_attr_t *valp)
 Get a dump file attribute, checking its type.
 
kdump_status kdump_attr_ref (kdump_ctx_t *ctx, const char *key, kdump_attr_ref_t *ref)
 Get a reference to an attribute.
 
kdump_status kdump_sub_attr_ref (kdump_ctx_t *ctx, const kdump_attr_ref_t *base, const char *subkey, kdump_attr_ref_t *ref)
 Get a reference to a subordinate attribute.
 
void kdump_attr_unref (kdump_ctx_t *ctx, kdump_attr_ref_t *ref)
 Drop a reference to an attribute.
 
kdump_attr_type_t kdump_attr_ref_type (kdump_attr_ref_t *ref)
 Get the type of an attribute by reference.
 
int kdump_attr_ref_isset (kdump_attr_ref_t *ref)
 Check whether an attribute is set.
 
kdump_status kdump_attr_ref_get (kdump_ctx_t *ctx, const kdump_attr_ref_t *ref, kdump_attr_t *valp)
 Get attribute data by reference.
 
kdump_status kdump_attr_ref_set (kdump_ctx_t *ctx, kdump_attr_ref_t *ref, const kdump_attr_t *valp)
 Set attribute data by reference.
 
kdump_status kdump_set_sub_attr (kdump_ctx_t *ctx, const kdump_attr_ref_t *base, const char *subkey, const kdump_attr_t *valp)
 Set a dump file attribute.
 
kdump_status kdump_attr_iter_start (kdump_ctx_t *ctx, const char *path, kdump_attr_iter_t *iter)
 Get an attribute iterator.
 
kdump_status kdump_attr_ref_iter_start (kdump_ctx_t *ctx, const kdump_attr_ref_t *ref, kdump_attr_iter_t *iter)
 Get an attribute iterator by reference.
 
kdump_status kdump_attr_iter_next (kdump_ctx_t *ctx, kdump_attr_iter_t *iter)
 Advance an attribute iterator.
 
void kdump_attr_iter_end (kdump_ctx_t *ctx, kdump_attr_iter_t *iter)
 De-initialize an attribute iterator.
 

Canonical Architecture Names

Recognized values of the arch.name attribute.

These macros should be used instead of the actual string to prevent typos. Note that it is not an error to set the arch.name attribute to a value that is not recognized by the library. However, some functionality may be unavailable (e.g. virtual-to-physical address translation).

#define KDUMP_ARCH_AARCH64   "aarch64"
 AArch64 (ARM64)
 
#define KDUMP_ARCH_ALPHA   "alpha"
 DEC Alpha.
 
#define KDUMP_ARCH_ARM   "arm"
 ARM, 32-bit.
 
#define KDUMP_ARCH_IA32   "ia32"
 Intel i386, i586, i686.
 
#define KDUMP_ARCH_IA64   "ia64"
 Intel Itanium.
 
#define KDUMP_ARCH_MIPS   "mips"
 MIPS, 32-bit.
 
#define KDUMP_ARCH_PPC   "ppc"
 Power ISA, 32-bit.
 
#define KDUMP_ARCH_PPC64   "ppc64"
 Power ISA, 64-bit.
 
#define KDUMP_ARCH_RISCV32   "riscv32"
 RISC-V, 32-bit.
 
#define KDUMP_ARCH_RISCV64   "riscv64"
 RISC-V, 64-bit.
 
#define KDUMP_ARCH_S390   "s390"
 IBM z/Architecture, 31-bit.
 
#define KDUMP_ARCH_S390X   "s390x"
 IBM z/Architecture, 64-bit.
 
#define KDUMP_ARCH_X86_64   "x86_64"
 AMD64, Intel 64.
 
#define KDUMP_ATTR_BYTE_ORDER   "arch.byte_order"
 Byte order attribute.
 
#define KDUMP_ATTR_PTR_SIZE   "arch.ptr_size"
 Pointer size attribute.
 
#define KDUMP_ATTR_PAGE_SIZE   "arch.page_size"
 Page size attribute.
 
#define KDUMP_ATTR_PAGE_SHIFT   "arch.page_shift"
 Page shift attribute.
 
#define KDUMP_ATTR_NUM_CPUS   "cpu.number"
 Number of CPUs attribute.
 
#define KDUMP_ATTR_OSTYPE   "addrxlat.ostype"
 OS type attribute.
 
#define KDUMP_ATTR_XLAT_DEFAULT   "addrxlat.default"
 Default libaddrxlat options.
 
#define KDUMP_ATTR_XLAT_FORCE   "addrxlat.force"
 Forced libaddrxlat options.
 
#define KDUMP_ATTR_XEN_TYPE   "xen.type"
 Xen dump type file attribute.
 
#define KDUMP_ATTR_XEN_XLAT   "xen.xlat"
 Xen translation type attribute.
 
#define KDUMP_ATTR_LINUX_VERSION_CODE   "linux.version_code"
 Linux version code attribute.
 
#define KDUMP_ATTR_XEN_VERSION_CODE   "xen.version_code"
 Xen version code attribute.
 
#define KDUMP_ATTR_XEN_PHYS_START   "xen.phys_start"
 Xen physical start address attribute.
 
#define KDUMP_ATTR_ZERO_EXCLUDED   "file.zero_excluded"
 Fill excluded pages with zeroes?
 
#define KDUMP_ATTR_FILE_MMAP_POLICY   "file.mmap_policy"
 Policy for using mmap vs.
 
#define KDUMP_ATTR_ERASEINFO   "file.eraseinfo.raw"
 Raw content of makedumpfile ERASEINFO.
 
kdump_status kdump_vmcoreinfo_raw (kdump_ctx_t *ctx, char **raw)
 Get VMCOREINFO raw data.
 
kdump_status kdump_vmcoreinfo_line (kdump_ctx_t *ctx, const char *key, char **val)
 Get a VMCOREINFO line.
 
kdump_status kdump_vmcoreinfo_symbol (kdump_ctx_t *ctx, const char *symname, kdump_addr_t *symvalue)
 Get VMCOREINFO symbol value.
 
const char * kdump_strerror (kdump_status status)
 Return the string describing a given error status.
 

Detailed Description

Public interface for libkdumpfile (kernel coredump file access).

Macro Definition Documentation

◆ KDUMP_ATTR_ARCH_NAME

#define KDUMP_ATTR_ARCH_NAME   "arch.name"

Canonical architecture name attribute.

Unlike KDUMP_ATTR_MACHINE, which may contain the name of a particular platform (e.g. "i586" v. "i686") or may not even be initialised, this attribute (if set) always equals one of the KDUMP_ARCH_xxx strings defined below.

◆ KDUMP_ATTR_BYTE_ORDER

#define KDUMP_ATTR_BYTE_ORDER   "arch.byte_order"

Byte order attribute.

See also
kdump_byte_order_t

◆ KDUMP_ATTR_FILE_FORMAT

#define KDUMP_ATTR_FILE_FORMAT   "file.format"

File format name attribute.

This attribute is intended to be presented to humans rather than machine-parsed. In fact, some format handlers create the string dynamically, e.g. LKCD files will include the version in the string.

◆ KDUMP_ATTR_FILE_MMAP_POLICY

#define KDUMP_ATTR_FILE_MMAP_POLICY   "file.mmap_policy"

Policy for using mmap vs.

read. Default is KDUMP_MMAP_TRY.

See also
kdump_mmap_policy_t

◆ KDUMP_ATTR_FILE_PAGEMAP

#define KDUMP_ATTR_FILE_PAGEMAP   "file.pagemap"

File page map attribute.

This attribute contains a bitmap of pages that are contained in the file. If only part of a page is present, the corresponding bit is set to 1.

◆ KDUMP_ATTR_FILE_SET

#define KDUMP_ATTR_FILE_SET   "file.set"

Base directory of a file set.

The KDUMP_ATTR_FILE_FD attribute can be used only if the dump is contained in a single file. If the dump is split across multiple files (e.g. SADUMP), use file.set:

  • Set the number sub-attribute first. This creates numbered sub-attributes 0 to n-1.
  • Set 0.fd, 1.fd, ... $n_1.fd to the file descriptors (in any order).
  • Optionally, you may store the file name in 0.name, 1.name, ... $n_1.fd. It is used in error messages.
  • When all file descriptors are set, the dump file gets initialized automatically.

◆ KDUMP_ATTR_LINUX_VERSION_CODE

#define KDUMP_ATTR_LINUX_VERSION_CODE   "linux.version_code"

Linux version code attribute.

A Linux kernel version code is a 32-bit integer that combines the first three digits of the kernel version. See KERNEL_VERSION in <linux/version.h>.

◆ KDUMP_ATTR_MEMORY_PAGEMAP

#define KDUMP_ATTR_MEMORY_PAGEMAP   "memory.pagemap"

Memory page map attribute.

This attribute contains a bitmap of pages that are RAM. If only part of a page is present, the corresponding bit is set to 1.

◆ KDUMP_ATTR_NUM_CPUS

#define KDUMP_ATTR_NUM_CPUS   "cpu.number"

Number of CPUs attribute.

The number is not the number of CPUs in the system, but rather the number of CPUs with known register values.

◆ KDUMP_ATTR_XEN_TYPE

#define KDUMP_ATTR_XEN_TYPE   "xen.type"

Xen dump type file attribute.

See also
kdump_xen_type_t

◆ KDUMP_ATTR_XEN_VERSION_CODE

#define KDUMP_ATTR_XEN_VERSION_CODE   "xen.version_code"

Xen version code attribute.

A Xen version code is a 32-bit integer that combines the major and minor version. See XENVER_version in <xen/version.h>.

◆ KDUMP_ATTR_XEN_XLAT

#define KDUMP_ATTR_XEN_XLAT   "xen.xlat"

Xen translation type attribute.

See also
kdump_xen_xlat_t

◆ KDUMP_ATTR_XLAT_DEFAULT

#define KDUMP_ATTR_XLAT_DEFAULT   "addrxlat.default"

Default libaddrxlat options.

Atributes under this directory will be used if no better value can be inferred from the dump file.

◆ KDUMP_ATTR_XLAT_FORCE

#define KDUMP_ATTR_XLAT_FORCE   "addrxlat.force"

Forced libaddrxlat options.

Atributes under this directory override whatever is auto-detected.

◆ KDUMPFILE_VERSION

#define KDUMPFILE_VERSION
Value:
#define KDUMPFILE_VER_MINOR
Minor version (2nd number in the release tag).
Definition kdumpfile.h:44
#define KDUMPFILE_VER_MAJOR
Major version (1st number in the release tag).
Definition kdumpfile.h:42
#define KDUMPFILE_VER_MICRO
Micro version (3rd number in the release tag).
Definition kdumpfile.h:46
#define KDUMPFILE_MKVER(major, minor, micro)
Make a single-number version from three digits of the release tag.
Definition kdumpfile.h:49

Version as a single number.

Typedef Documentation

◆ kdump_addr_t

Type of a physical or virtual address.

This type is large enough to hold any possible address type on any architecture supported by libkdumpfile. Note that this type may be larger than the actual address in the target.

◆ kdump_addrspace_t

Address spaces used by kdump_read()

When passing an address to kdump_read(), this type is used to specify the kind of address.

The numeric values shall match those of addrxlat_addrspace_t.

◆ kdump_attr_iter_t

Attribute iterator.

Iterators are used to iterate over all children of a directory attribute. This is a public structure, so callers can allocate it e.g. on stack.

Note that the attribute name is stored in the structure, but the attribute value is not. This allows to keep the same ABI while implementing special attribute handling (e.g. calculate the value on the fly).

◆ kdump_attr_ref_t

Reference to an attribute.

This type is used to make a fixed-size reference to an attribute, rather than its (variable-size) key path.

This type points to an internal structure which may change layout without affecting the ABI, so callers must not make any attempts to interpret that data.

◆ kdump_blob_t

typedef struct _kdump_blob kdump_blob_t

Dump binary large object (BLOB).

A blob contains arbitrary binary data.

◆ kdump_bmp_t

typedef struct _kdump_bmp kdump_bmp_t

Dump bitmap.

A bitmap contains the validity of indexed objects, e.g. pages in a dump file (indexed by their page frame numbers). It may not be implemented internally as an actual bitmap.

◆ kdump_byte_order_t

Target dump byte order.

Target byte order. Note that this may be different from the host byte order. The library will convert any values it needs internally, but if you read any data from the dump file, you are responsible for converting the data to the host byte order.

See also
KDUMP_ATTR_BYTE_ORDER

◆ kdump_ctx_t

typedef struct _kdump_ctx kdump_ctx_t

Representation of a dump file.

The context contains all information needed to work with a dump file. It is an opaque type, so it can be modified and/or extended without breaking binary compatibility with existing programs.

◆ kdump_mmap_policy_t

File mmap policy.

Control if and how mmap(2) should be used to access data from the underlying core file.

See also
KDUMP_ATTR_FILE_MMAP_POLICY

◆ kdump_num_t

typedef uint_fast64_t kdump_num_t

Type of a generic number.

This type is large enough to hold register value on any architecture supported by libkdumpfile. Note that it may be larger than the registers in the target.

◆ kdump_paddr_t

Type of a physical address.

Use this type instead of kdump_addr_t if the entity is always known to be a physical address.

◆ kdump_status

Status code.

Return type of all (almost) library functions that may fail. It provides a very rough description of the error. See kdump_get_err if you want a human-readable error description.

◆ kdump_vaddr_t

Type of a virtual addresses.

Use this type instead of kdump_addr_t if the entity is always known to be a virtual address.

◆ kdump_xen_type_t

Type of a Xen dump.

See also
KDUMP_ATTR_XEN_TYPE

◆ kdump_xen_xlat_t

Xen physmap translation type.

See also
KDUMP_ATTR_XEN_XLAT

Enumeration Type Documentation

◆ _kdump_addrspace

Address spaces used by kdump_read()

When passing an address to kdump_read(), this type is used to specify the kind of address.

The numeric values shall match those of addrxlat_addrspace_t.

Enumerator
KDUMP_KPHYSADDR 

Kernel physical address.

KDUMP_MACHPHYSADDR 

Machine physical address.

KDUMP_KVADDR 

Kernel virtual address.

KDUMP_NOADDR 

Invalid address.

◆ _kdump_attr_type

Dump file attribute value type.

Enumerator
KDUMP_NIL 

No type; used for deletions.

KDUMP_DIRECTORY 

Attribute directory.

KDUMP_NUMBER 

General number.

KDUMP_ADDRESS 

Address or symbol value.

KDUMP_STRING 

String attribute.

KDUMP_BITMAP 

Bitmap.

KDUMP_BLOB 

Binary large object.

◆ _kdump_byte_order

Target dump byte order.

Target byte order. Note that this may be different from the host byte order. The library will convert any values it needs internally, but if you read any data from the dump file, you are responsible for converting the data to the host byte order.

See also
KDUMP_ATTR_BYTE_ORDER

◆ _kdump_mmap_policy

File mmap policy.

Control if and how mmap(2) should be used to access data from the underlying core file.

See also
KDUMP_ATTR_FILE_MMAP_POLICY
Enumerator
KDUMP_MMAP_NEVER 

Never use mmap(2), always use read(2).

KDUMP_MMAP_ALWAYS 

Always use mmap(2), never use read(2).

KDUMP_MMAP_TRY 

Try mmap(2), fall back to read(2).

KDUMP_MMAP_TRY_ONCE 

Same as KDUMP_MMAP_TRY, but change to KDUMP_MMAP_NEVER or KDUMP_MMAP_ALWAYS based on the result of the next read.

◆ _kdump_status

Status code.

Return type of all (almost) library functions that may fail. It provides a very rough description of the error. See kdump_get_err if you want a human-readable error description.

Enumerator
KDUMP_OK 

Success.

KDUMP_ERR_SYSTEM 

OS error, see errno.

KDUMP_ERR_NOTIMPL 

Unimplemented feature.

KDUMP_ERR_NODATA 

Data is not stored in the dump file.

KDUMP_ERR_CORRUPT 

Corrupted file data.

KDUMP_ERR_INVALID 

Invalid value.

KDUMP_ERR_NOKEY 

No such attribute key.

KDUMP_ERR_EOF 

Unexpected EOF.

KDUMP_ERR_BUSY 

Too many pending requests.

KDUMP_ERR_ADDRXLAT 

Address translation error.

◆ _kdump_xen_type

Type of a Xen dump.

See also
KDUMP_ATTR_XEN_TYPE
Enumerator
KDUMP_XEN_NONE 

Not running under Xen.

KDUMP_XEN_SYSTEM 

Comlete dump of a Xen machine.

KDUMP_XEN_DOMAIN 

Dump of a single domain.

◆ _kdump_xen_xlat

Xen physmap translation type.

See also
KDUMP_ATTR_XEN_XLAT
Enumerator
KDUMP_XEN_AUTO 

Auto-translated physmap.

KDUMP_XEN_NONAUTO 

Non-auto-translated physmap.

◆ kdump_clone_bits

Clone flag bits.

Bit positions for individual clone flags.

Function Documentation

◆ kdump_attr_iter_end()

void kdump_attr_iter_end ( kdump_ctx_t ctx,
kdump_attr_iter_t iter 
)

De-initialize an attribute iterator.

Parameters
ctxDump file object.
iterAttribute iterator.
Returns
Error status.

This function must be called when an iterator is no longer needed.

◆ kdump_attr_iter_next()

kdump_status kdump_attr_iter_next ( kdump_ctx_t ctx,
kdump_attr_iter_t iter 
)

Advance an attribute iterator.

Parameters
ctxDump file object.
iterAttribute iterator.
Returns
Error status.

If there are no more items in the iteration, this function sets the key field of iter to NULL and returns KDUMP_OK. If you try to advance past end of iteration, this function returns KDUMP_ERR_INVALID.

◆ kdump_attr_iter_start()

kdump_status kdump_attr_iter_start ( kdump_ctx_t ctx,
const char *  path,
kdump_attr_iter_t iter 
)

Get an attribute iterator.

Parameters
ctxDump file object.
[in]pathPath to an attribute directory.
[out]iterAttribute iterator.
Returns
Error status.

On return, the iterator is set to the first child attribute. If the attribute directory is empty, this function sets the key field of iter to NULL and returns KDUMP_OK.

◆ kdump_attr_ref()

kdump_status kdump_attr_ref ( kdump_ctx_t ctx,
const char *  key,
kdump_attr_ref_t ref 
)

Get a reference to an attribute.

Parameters
ctxDump file object.
[in]keyAttribute key.
[out]refAttribute reference (initialized on successful return).
Returns
Error status.

A reference is a persistent pointer to the attribute, which stays valid until the reference is dropped using kdump_attr_unref, or the whole dump file object is destroyed.

◆ kdump_attr_ref_get()

kdump_status kdump_attr_ref_get ( kdump_ctx_t ctx,
const kdump_attr_ref_t ref,
kdump_attr_t valp 
)

Get attribute data by reference.

Parameters
ctxDump file object.
[in]refAttribute reference.
[out]valpAttribute value (filled on successful return).

This works just like kdump_get_attr, except that the attribute is denoted by a reference rather than by its key path.

◆ kdump_attr_ref_isset()

int kdump_attr_ref_isset ( kdump_attr_ref_t ref)

Check whether an attribute is set.

Parameters
refAttrbute reference.
Returns
Non-zero if the attribute has a value, zero otherwise.

◆ kdump_attr_ref_iter_start()

kdump_status kdump_attr_ref_iter_start ( kdump_ctx_t ctx,
const kdump_attr_ref_t ref,
kdump_attr_iter_t iter 
)

Get an attribute iterator by reference.

Parameters
ctxDump file object.
[in]refReference to an attribute directory.
[out]iterAttribute iterator.
Returns
Error status.

This works just like kdump_attr_iter_start, but use an attribute reference rather than its key path.

◆ kdump_attr_ref_set()

kdump_status kdump_attr_ref_set ( kdump_ctx_t ctx,
kdump_attr_ref_t ref,
const kdump_attr_t valp 
)

Set attribute data by reference.

Parameters
ctxDump file object.
[in]refAttribute reference.
[in]valpNew attribute value.

This works just like kdump_set_attr, except that the attribute is denoted by a reference rather than by its key path.

◆ kdump_attr_ref_type()

kdump_attr_type_t kdump_attr_ref_type ( kdump_attr_ref_t ref)

Get the type of an attribute by reference.

Parameters
refAttribute reference.
Returns
Attribute type.

◆ kdump_attr_unref()

void kdump_attr_unref ( kdump_ctx_t ctx,
kdump_attr_ref_t ref 
)

Drop a reference to an attribute.

Parameters
ctxDump file object.
refAttribute reference.

◆ kdump_blob_decref()

unsigned long kdump_blob_decref ( kdump_blob_t blob)

Decrement kdump blob reference counter.

Parameters
blobBinary object.
Returns
New reference count.

If the new reference count is zero, the underlying object is freed and its address must not be used afterwards.

◆ kdump_blob_incref()

unsigned long kdump_blob_incref ( kdump_blob_t blob)

Increment kdump blob reference counter.

Parameters
blobBinary object.
Returns
New reference count.

◆ kdump_blob_new()

kdump_blob_t * kdump_blob_new ( void *  data,
size_t  size 
)

Create a new blob object.

Parameters
dataRaw data buffer (can be NULL).
sizeLength of data at data.
Returns
New blob object, or NULL on allocation error.

Create a new blob object from a dynamically allocated memory buffer. Keep in mind that the buffer will be eventually de-allocated with free(3) when the blob reference count drops to zero.

If data is NULL, then the blob does not contain any data.

The new object's reference count is initialized to 1 (the caller receives one reference), and the memory buffer is not pinned.

◆ kdump_blob_new_dup()

kdump_blob_t * kdump_blob_new_dup ( const void *  data,
size_t  size 
)

Create a new blob object from a copy of a buffer.

Parameters
dataRaw data buffer (can be NULL).
sizeLength of data at data.
Returns
New blob object, or NULL on allocation error.

Create a new blob object by duplicating data from a buffer. The data is copied into a newly allocated buffer which is owned by the blob object itself.

See also
kdump_blob_new

◆ kdump_blob_pin()

void * kdump_blob_pin ( kdump_blob_t blob)

Pin the internal data buffer.

Parameters
blobBinary object.
Returns
Pointer to binary data.

Returns pointer to the internal data buffer. The pointer is valid until a matching call to kdump_blob_unpin. While a blob is pinned, it cannot be modified by a call to kdump_blob_set or by any other internal library operation. The blob is pinned if there is at least one user of the data.

◆ kdump_blob_set()

kdump_status kdump_blob_set ( kdump_blob_t blob,
void *  data,
size_t  size 
)

Set kdump blob data.

Parameters
blobBinary object.
dataPointer to new binary data.
sizeSize of the new data in bytes.
Returns
Error status.

Set the internal buffer to data. The buffer must be allocated from the heap (i.e. using malloc and friends), because the library will eventually call free on it!

Attempts to set data of a pinned blob return KDUMP_ERR_BUSY, all other calls return KDUMP_OK.

It is OK to set the data to NULL.

◆ kdump_blob_size()

size_t kdump_blob_size ( const kdump_blob_t blob)

Get a blob size in bytes.

Parameters
blobBinary object.
Returns
Size of the binary object in bytes.

Note that an unpinned blob may be changed at any time, so you probably want to call kdump_blob_pin first.

◆ kdump_blob_unpin()

unsigned long kdump_blob_unpin ( kdump_blob_t blob)

Unpin the internal data buffer.

Parameters
blobBinary object.
Returns
Number of remaining pinned users.

This function releases the data pointer, decreasing an internal pin counter. When the counter reaches zero, any pointers to internal data are no longer valid (but the blob object itself remains valid).

◆ kdump_bmp_decref()

unsigned long kdump_bmp_decref ( kdump_bmp_t bmp)

Decrement kdump bitmap reference counter.

Parameters
mapTranslation map.
Returns
New reference count.

If the new reference count is zero, the underlying object is freed and its address must not be used afterwards.

◆ kdump_bmp_find_clear()

kdump_status kdump_bmp_find_clear ( kdump_bmp_t bmp,
kdump_addr_t idx 
)

Find the closest zero bit in a bitmap.

Parameters
bmpBitmap object.
idxStarting index in the bitmap, updated on success.
Returns
Error status.

◆ kdump_bmp_find_set()

kdump_status kdump_bmp_find_set ( kdump_bmp_t bmp,
kdump_addr_t idx 
)

Find the closest set bit in a bitmap.

Parameters
bmpBitmap object.
idxStarting index in the bitmap, updated on success.
Returns
Error status.

◆ kdump_bmp_get_bits()

kdump_status kdump_bmp_get_bits ( kdump_bmp_t bmp,
kdump_addr_t  first,
kdump_addr_t  last,
unsigned char *  raw 
)

Get bitmap bits as a raw bitmap.

Parameters
bmpBitmap object.
firstFirst index in the bitmap.
lastLast index in the bitmap.
rawRaw bitmap (updated on success).
Returns
Error status.

◆ kdump_bmp_get_err()

const char * kdump_bmp_get_err ( const kdump_bmp_t bmp)

Get a detailed error string.

Parameters
bmpBitmap object.
Returns
Last error string.

If an error status is returned, this function can be used to get a human-readable description of the error. The error string is not reset by calling this function, but it is reset by calling any other function that returns kdump_status.

◆ kdump_bmp_incref()

unsigned long kdump_bmp_incref ( kdump_bmp_t bmp)

Increment kdump bitmap reference counter.

Parameters
mapTranslation map.
Returns
New reference count.

◆ kdump_clear_err()

kdump_status void kdump_clear_err ( kdump_ctx_t ctx)

Clear the error message.

Parameters
ctxDump file object.

◆ kdump_clone()

kdump_ctx_t * kdump_clone ( const kdump_ctx_t orig,
unsigned long  flags 
)

Clone a dump file object.

Parameters
origOriginal dump file object.
flagsSpecify which data should be shared with the original.
Returns
Cloned dump file object, or NULL on allocation error.

A cloned dump file object shares file descriptor, cache, attributes and other data with the original, according to flags. Changes of shared data in one of the objects are also seen by the other object.

The following fields are not shared:

  • address translation context (see kdump_get_addrxlat_ctx),
  • error string (see kdump_get_err),

Private data and callbacks are initialized to their values from the orig context here.

See also
Multi-threading

◆ kdump_d16toh()

uint_fast16_t kdump_d16toh ( kdump_ctx_t ctx,
uint_fast16_t  val 
)

Convert a 16-bit value from dump to host byte order.

Parameters
ctxDump file object.
valValue in dump file byte order.
Returns
Value in host byte order.

◆ kdump_d32toh()

uint_fast32_t kdump_d32toh ( kdump_ctx_t ctx,
uint_fast32_t  val 
)

Convert a 32-bit value from dump to host byte order.

Parameters
ctxDump file object.
valValue in dump file byte order.
Returns
Value in host byte order.

◆ kdump_d64toh()

uint_fast64_t kdump_d64toh ( kdump_ctx_t ctx,
uint_fast64_t  val 
)

Convert a 64-bit value from dump to host byte order.

Parameters
ctxDump file object.
valValue in dump file byte order.
Returns
Value in host byte order.

◆ kdump_err()

kdump_status kdump_err ( kdump_ctx_t ctx,
kdump_status  status,
const char *  msgfmt,
  ... 
)

Prepend an error message.

Parameters
ctxDump file object.
statusError status.
msgfmtMessage format string (printf style).
Returns
The error status which was passed as argument.

This function prepends the new error message to the existing content of the error buffer, resulting in a kind of error backtrace.

◆ kdump_free()

void kdump_free ( kdump_ctx_t ctx)

Free a dump file object.

Parameters
ctxObject to be freed.

Free all resources associated with the dump file. Do not just call free(ctx), because that may leak some resources.

The object must not be used after calling this function.

◆ kdump_get_addrxlat()

kdump_status kdump_get_addrxlat ( kdump_ctx_t ctx,
addrxlat_ctx_t **  axctx,
addrxlat_sys_t **  axsys 
)

Get the associated address translation data structures.

Parameters
ctxDump file object.
axctxAddress translation context (filled on return).
axsysAddress translation system (filled on return).
Returns
Error status.

You may pass NULL as a target parameter if you don't need that specific object.

This function grabs a new reference. You should call addrxlat_ctx_decref and/or addrxlat_sys_decref on the returned object(s) when you no longer need them.

◆ kdump_get_attr()

kdump_status kdump_get_attr ( kdump_ctx_t ctx,
const char *  key,
kdump_attr_t valp 
)

Get a dump file attribute.

Parameters
ctxDump file object.
keyAttribute key.
valpValue (filled on successful return).
Returns
Error status.

Note that the caller does not hold a reference to the attribute, so it is not generally safe to use this function in a multi-threaded program, or across another library call which modifies the attribute (explicitly or implicitly).

◆ kdump_get_err()

const char * kdump_get_err ( kdump_ctx_t ctx)

Get a detailed error string.

Parameters
ctxDump file object.
Returns
Error string, or NULL if there was no error.

If an error status is returned, this function can be used to get a human-readable description of the error. The error string is not reset by calling this function, but it is reset by calling any library function that returns kdump_status.

◆ kdump_get_typed_attr()

kdump_status kdump_get_typed_attr ( kdump_ctx_t ctx,
const char *  key,
kdump_attr_t valp 
)

Get a dump file attribute, checking its type.

Parameters
ctxDump file object.
keyAttribute key.
valpValue (updated on return).
Returns
Error status.

The type field in valp must be set to the expected attribute type by the caller. It is an error if the attribute is of a different type, but valp is updated to its value anyway.

Note that the caller does not hold a reference to the attribute. See the description of kdump_get_attr for limitations.

◆ kdump_new()

kdump_ctx_t * kdump_new ( void  )

Initialize a new dump file object.

Returns
New initialized object, or NULL on failure.

Use this function to create a new kdump_ctx_t. When the object is no longer needed, you should free all resources with kdump_free.

◆ kdump_open_fdset()

kdump_status kdump_open_fdset ( kdump_ctx_t ctx,
unsigned  nfds,
const int *  fds 
)

Open a set of dump files.

Parameters
ctxDump file object.
nfdsNumber of file descriptors in fds.
fdsOpen file descriptors.
Returns
Error status.

Set up file.fdset attribute subtree to open a set of dump files.

Note: Only file descriptors are replaced by this call; if file name attributes were set before the call, they are not changed. However, this function sets file.set.number to nfds, which discards file.set.x sub-directories for x greater than or equal to nfds, INCLUDING any respective file.set.x.name attributes.

◆ kdump_read()

kdump_status kdump_read ( kdump_ctx_t ctx,
kdump_addrspace_t  as,
kdump_addr_t  addr,
void *  buffer,
size_t *  plength 
)

Read data from the dump file.

Parameters
ctxDump file object.
[in]asAddress space of addr.
[in]addrAny type of address.
[out]bufferBuffer to receive data.
[in,out]plengthLength of the buffer.
Returns
Error status.

Read data from a dump file. On return, the length of the buffer pointed to by plength is updated to reflect the actual number of bytes read from the dump file.

If kdump_read returns KDUMP_OK, then all requested bytes have been read successfully, and the value referenced by plength is not changed. However, if the read fails, some bytes may already have been read, and their number is reported in this variable, so the caller may process a partial read.

In particular, if some pages were filtered out, kdump_read may return KDUMP_ERR_NODATA when it reaches the filtered out page.

◆ kdump_read_string()

kdump_status kdump_read_string ( kdump_ctx_t ctx,
kdump_addrspace_t  as,
kdump_addr_t  addr,
char **  pstr 
)

Read a string from the dump file.

Parameters
ctxDump file object.
[in]asAddress space of addr.
[in]addrAny type of address.
[out]pstrString to be read.
Returns
Error status.

Use this function to read a NUL-terminated string at address addr. The resulting string is allocated dynamically, and you should free it with the free library function when it is no longer needed. This function is usually more efficient than implementing the same thing with kdump_read.

◆ kdump_set_attr()

kdump_status kdump_set_attr ( kdump_ctx_t ctx,
const char *  key,
const kdump_attr_t valp 
)

Set a dump file attribute.

Parameters
ctxDump file object.
keyAttribute key.
valpNew attribute value.
Returns
Error status.

◆ kdump_set_filenames()

kdump_status kdump_set_filenames ( kdump_ctx_t ctx,
unsigned  n,
const char *const *  names 
)

Set descriptive file names.

Parameters
ctxDump file object.
nNumber of names in names.
namesNames. NULL means clear the name.
Returns
Error status.

Set the optional file names. These names are used in error messages to give humans a clue which file of a multi-file dump the error is related.

◆ kdump_set_sub_attr()

kdump_status kdump_set_sub_attr ( kdump_ctx_t ctx,
const kdump_attr_ref_t base,
const char *  subkey,
const kdump_attr_t valp 
)

Set a dump file attribute.

Parameters
ctxDump file object.
baseReference to a base attribute.
subkeyAttribute key, relative to base.
valpNew attribute value.
Returns
Error status.

◆ kdump_strerror()

const char * kdump_strerror ( kdump_status  status)

Return the string describing a given error status.

Parameters
statusError status
Returns
Description of the error.

◆ kdump_sub_attr_ref()

kdump_status kdump_sub_attr_ref ( kdump_ctx_t ctx,
const kdump_attr_ref_t base,
const char *  subkey,
kdump_attr_ref_t ref 
)

Get a reference to a subordinate attribute.

Parameters
ctxDump file object.
[in]baseReference to base attribute.
[in]subkeyAttribute key, relative to base.
[out]refAttribute reference (initialized on successful return).
Returns
Error status.

◆ kdump_vmcoreinfo_line()

kdump_status kdump_vmcoreinfo_line ( kdump_ctx_t ctx,
const char *  key,
char **  val 
)

Get a VMCOREINFO line.

Parameters
ctxDump file object.
[in]keyName of the VMCOREINFO variable (part before '=').
[out]valFilled with the part after (first) '='.
Returns
Error status.

The output string is dynamically allocated and must be eventually deallocated by the caller using free(3).

◆ kdump_vmcoreinfo_raw()

kdump_status kdump_vmcoreinfo_raw ( kdump_ctx_t ctx,
char **  raw 
)

Get VMCOREINFO raw data.

Parameters
ctxDump file object.
rawFilled with a copy of the raw VMCOREINFO string on success.
Returns
Error status.

The output string is always NUL-terminated, but if there was a NUL byte inside VMCOREINFO, there is no way to know the full length.

The output string is dynamically allocated and must be eventually deallocated by the caller using free(3).

◆ kdump_vmcoreinfo_symbol()

kdump_status kdump_vmcoreinfo_symbol ( kdump_ctx_t ctx,
const char *  symname,
kdump_addr_t symvalue 
)

Get VMCOREINFO symbol value.

Parameters
ctxDump file object.
[in]symnameKernel symbol name.
[out]symvalueValue of the symbol.
Returns
Error status.

Get the content of SYMBOL(symname) row and parse it as a hexadecimal value.