libkdumpfile-0.5.4
Kernel coredump file access
|
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 | |
#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 | |
#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_t * | kdump_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_t * | kdump_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_t * | kdump_blob_new (void *data, size_t size) |
Create a new blob object. | |
kdump_blob_t * | kdump_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 These macros should be used instead of the actual string to prevent typos. Note that it is not an error to set the | |
#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. | |
Public interface for libkdumpfile
(kernel coredump file access).
#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.
#define KDUMP_ATTR_BYTE_ORDER "arch.byte_order" |
Byte order attribute.
#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.
#define KDUMP_ATTR_FILE_MMAP_POLICY "file.mmap_policy" |
#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.
#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:
number
sub-attribute first. This creates numbered sub-attributes 0 to n-1.#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>.
#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.
#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.
#define KDUMP_ATTR_XEN_TYPE "xen.type" |
Xen dump type file attribute.
#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>.
#define KDUMP_ATTR_XEN_XLAT "xen.xlat" |
Xen translation type attribute.
#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.
#define KDUMP_ATTR_XLAT_FORCE "addrxlat.force" |
Forced libaddrxlat options.
Atributes under this directory override whatever is auto-detected.
#define KDUMPFILE_VERSION |
Version as a single number.
typedef addrxlat_addr_t 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.
typedef enum _kdump_addrspace 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.
typedef struct _kdump_attr_iter 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).
typedef struct _kdump_attr_ref 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.
typedef struct _kdump_blob kdump_blob_t |
Dump binary large object (BLOB).
A blob contains arbitrary binary data.
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.
typedef enum _kdump_byte_order 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.
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.
typedef enum _kdump_mmap_policy kdump_mmap_policy_t |
File mmap policy.
Control if and how mmap(2) should be used to access data from the underlying core file.
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.
typedef kdump_addr_t 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.
typedef enum _kdump_status 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.
typedef kdump_addr_t 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.
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.
enum _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. |
enum _kdump_attr_type |
enum _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.
enum _kdump_mmap_policy |
File mmap policy.
Control if and how mmap(2) should be used to access data from the underlying core file.
enum _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.
enum _kdump_xen_type |
Type of a Xen dump.
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. |
enum _kdump_xen_xlat |
Xen physmap translation type.
Enumerator | |
---|---|
KDUMP_XEN_AUTO | Auto-translated physmap. |
KDUMP_XEN_NONAUTO | Non-auto-translated physmap. |
enum kdump_clone_bits |
Clone flag bits.
Bit positions for individual clone flags.
void kdump_attr_iter_end | ( | kdump_ctx_t * | ctx, |
kdump_attr_iter_t * | iter | ||
) |
De-initialize an attribute iterator.
ctx | Dump file object. |
iter | Attribute iterator. |
This function must be called when an iterator is no longer needed.
kdump_status kdump_attr_iter_next | ( | kdump_ctx_t * | ctx, |
kdump_attr_iter_t * | iter | ||
) |
Advance an attribute iterator.
ctx | Dump file object. |
iter | Attribute iterator. |
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_status kdump_attr_iter_start | ( | kdump_ctx_t * | ctx, |
const char * | path, | ||
kdump_attr_iter_t * | iter | ||
) |
Get an attribute iterator.
ctx | Dump file object. | |
[in] | path | Path to an attribute directory. |
[out] | iter | Attribute iterator. |
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_status kdump_attr_ref | ( | kdump_ctx_t * | ctx, |
const char * | key, | ||
kdump_attr_ref_t * | ref | ||
) |
Get a reference to an attribute.
ctx | Dump file object. | |
[in] | key | Attribute key. |
[out] | ref | Attribute reference (initialized on successful return). |
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_status kdump_attr_ref_get | ( | kdump_ctx_t * | ctx, |
const kdump_attr_ref_t * | ref, | ||
kdump_attr_t * | valp | ||
) |
Get attribute data by reference.
ctx | Dump file object. | |
[in] | ref | Attribute reference. |
[out] | valp | Attribute 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.
int kdump_attr_ref_isset | ( | kdump_attr_ref_t * | ref | ) |
Check whether an attribute is set.
ref | Attrbute reference. |
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.
ctx | Dump file object. | |
[in] | ref | Reference to an attribute directory. |
[out] | iter | Attribute iterator. |
This works just like kdump_attr_iter_start, but use an attribute reference rather than its key path.
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.
ctx | Dump file object. | |
[in] | ref | Attribute reference. |
[in] | valp | New 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_type_t kdump_attr_ref_type | ( | kdump_attr_ref_t * | ref | ) |
Get the type of an attribute by reference.
ref | Attribute reference. |
void kdump_attr_unref | ( | kdump_ctx_t * | ctx, |
kdump_attr_ref_t * | ref | ||
) |
Drop a reference to an attribute.
ctx | Dump file object. |
ref | Attribute reference. |
unsigned long kdump_blob_decref | ( | kdump_blob_t * | blob | ) |
Decrement kdump blob reference counter.
blob | Binary object. |
If the new reference count is zero, the underlying object is freed and its address must not be used afterwards.
unsigned long kdump_blob_incref | ( | kdump_blob_t * | blob | ) |
Increment kdump blob reference counter.
blob | Binary object. |
kdump_blob_t * kdump_blob_new | ( | void * | data, |
size_t | size | ||
) |
Create a new blob object.
data | Raw data buffer (can be NULL ). |
size | Length of data at data . |
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_t * kdump_blob_new_dup | ( | const void * | data, |
size_t | size | ||
) |
Create a new blob object from a copy of a buffer.
data | Raw data buffer (can be NULL ). |
size | Length of data at data . |
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.
void * kdump_blob_pin | ( | kdump_blob_t * | blob | ) |
Pin the internal data buffer.
blob | Binary object. |
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_status kdump_blob_set | ( | kdump_blob_t * | blob, |
void * | data, | ||
size_t | size | ||
) |
Set kdump blob data.
blob | Binary object. |
data | Pointer to new binary data. |
size | Size of the new data in bytes. |
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
.
size_t kdump_blob_size | ( | const kdump_blob_t * | blob | ) |
Get a blob size in bytes.
blob | Binary object. |
Note that an unpinned blob may be changed at any time, so you probably want to call kdump_blob_pin first.
unsigned long kdump_blob_unpin | ( | kdump_blob_t * | blob | ) |
Unpin the internal data buffer.
blob | Binary object. |
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).
unsigned long kdump_bmp_decref | ( | kdump_bmp_t * | bmp | ) |
Decrement kdump bitmap reference counter.
map | Translation map. |
If the new reference count is zero, the underlying object is freed and its address must not be used afterwards.
kdump_status kdump_bmp_find_clear | ( | kdump_bmp_t * | bmp, |
kdump_addr_t * | idx | ||
) |
Find the closest zero bit in a bitmap.
bmp | Bitmap object. |
idx | Starting index in the bitmap, updated on success. |
kdump_status kdump_bmp_find_set | ( | kdump_bmp_t * | bmp, |
kdump_addr_t * | idx | ||
) |
Find the closest set bit in a bitmap.
bmp | Bitmap object. |
idx | Starting index in the bitmap, updated on success. |
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.
bmp | Bitmap object. |
first | First index in the bitmap. |
last | Last index in the bitmap. |
raw | Raw bitmap (updated on success). |
const char * kdump_bmp_get_err | ( | const kdump_bmp_t * | bmp | ) |
Get a detailed error string.
bmp | Bitmap object. |
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.
unsigned long kdump_bmp_incref | ( | kdump_bmp_t * | bmp | ) |
Increment kdump bitmap reference counter.
map | Translation map. |
kdump_status void kdump_clear_err | ( | kdump_ctx_t * | ctx | ) |
Clear the error message.
ctx | Dump file object. |
kdump_ctx_t * kdump_clone | ( | const kdump_ctx_t * | orig, |
unsigned long | flags | ||
) |
Clone a dump file object.
orig | Original dump file object. |
flags | Specify which data should be shared with the original. |
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:
Private data and callbacks are initialized to their values from the orig
context here.
uint_fast16_t kdump_d16toh | ( | kdump_ctx_t * | ctx, |
uint_fast16_t | val | ||
) |
Convert a 16-bit value from dump to host byte order.
ctx | Dump file object. |
val | Value in dump file 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.
ctx | Dump file object. |
val | Value in dump file 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.
ctx | Dump file object. |
val | Value in dump file byte order. |
kdump_status kdump_err | ( | kdump_ctx_t * | ctx, |
kdump_status | status, | ||
const char * | msgfmt, | ||
... | |||
) |
Prepend an error message.
ctx | Dump file object. |
status | Error status. |
msgfmt | Message format string (printf style). |
This function prepends the new error message to the existing content of the error buffer, resulting in a kind of error backtrace.
void kdump_free | ( | kdump_ctx_t * | ctx | ) |
Free a dump file object.
ctx | Object 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_status kdump_get_addrxlat | ( | kdump_ctx_t * | ctx, |
addrxlat_ctx_t ** | axctx, | ||
addrxlat_sys_t ** | axsys | ||
) |
Get the associated address translation data structures.
ctx | Dump file object. |
axctx | Address translation context (filled on return). |
axsys | Address translation system (filled on return). |
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_status kdump_get_attr | ( | kdump_ctx_t * | ctx, |
const char * | key, | ||
kdump_attr_t * | valp | ||
) |
Get a dump file attribute.
ctx | Dump file object. |
key | Attribute key. |
valp | Value (filled on successful return). |
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).
const char * kdump_get_err | ( | kdump_ctx_t * | ctx | ) |
Get a detailed error string.
ctx | Dump file object. |
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_status kdump_get_typed_attr | ( | kdump_ctx_t * | ctx, |
const char * | key, | ||
kdump_attr_t * | valp | ||
) |
Get a dump file attribute, checking its type.
ctx | Dump file object. |
key | Attribute key. |
valp | Value (updated on return). |
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_ctx_t * kdump_new | ( | void | ) |
Initialize a new dump file object.
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_status kdump_open_fdset | ( | kdump_ctx_t * | ctx, |
unsigned | nfds, | ||
const int * | fds | ||
) |
Open a set of dump files.
ctx | Dump file object. |
nfds | Number of file descriptors in fds . |
fds | Open file descriptors. |
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_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.
ctx | Dump file object. | |
[in] | as | Address space of addr . |
[in] | addr | Any type of address. |
[out] | buffer | Buffer to receive data. |
[in,out] | plength | Length of the buffer. |
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_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.
ctx | Dump file object. | |
[in] | as | Address space of addr . |
[in] | addr | Any type of address. |
[out] | pstr | String to be read. |
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_status kdump_set_attr | ( | kdump_ctx_t * | ctx, |
const char * | key, | ||
const kdump_attr_t * | valp | ||
) |
Set a dump file attribute.
ctx | Dump file object. |
key | Attribute key. |
valp | New attribute value. |
kdump_status kdump_set_filenames | ( | kdump_ctx_t * | ctx, |
unsigned | n, | ||
const char *const * | names | ||
) |
Set descriptive file names.
ctx | Dump file object. |
n | Number of names in names . |
names | Names. NULL means clear the name. |
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_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.
ctx | Dump file object. |
base | Reference to a base attribute. |
subkey | Attribute key, relative to base . |
valp | New attribute value. |
const char * kdump_strerror | ( | kdump_status | status | ) |
Return the string describing a given error status.
status | Error status |
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.
ctx | Dump file object. | |
[in] | base | Reference to base attribute. |
[in] | subkey | Attribute key, relative to base . |
[out] | ref | Attribute reference (initialized on successful return). |
kdump_status kdump_vmcoreinfo_line | ( | kdump_ctx_t * | ctx, |
const char * | key, | ||
char ** | val | ||
) |
Get a VMCOREINFO line.
ctx | Dump file object. | |
[in] | key | Name of the VMCOREINFO variable (part before '='). |
[out] | val | Filled with the part after (first) '='. |
The output string is dynamically allocated and must be eventually deallocated by the caller using free(3)
.
kdump_status kdump_vmcoreinfo_raw | ( | kdump_ctx_t * | ctx, |
char ** | raw | ||
) |
Get VMCOREINFO raw data.
ctx | Dump file object. |
raw | Filled with a copy of the raw VMCOREINFO string on success. |
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_status kdump_vmcoreinfo_symbol | ( | kdump_ctx_t * | ctx, |
const char * | symname, | ||
kdump_addr_t * | symvalue | ||
) |
Get VMCOREINFO symbol value.
ctx | Dump file object. | |
[in] | symname | Kernel symbol name. |
[out] | symvalue | Value of the symbol. |
Get the content of SYMBOL(symname
) row and parse it as a hexadecimal value.