Loading...
Searching...
No Matches
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 5
| Micro version (3rd number in the release tag).
#define | KDUMPFILE_MKVER(major, minor, 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.5"
| 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_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_type_t type, kdump_attr_value_t *valp)
| Get a dump file attribute with a given 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.
void | kdump_attr_discard (kdump_ctx_t *ctx, kdump_attr_t *attr)
| Discard attribute data value.
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_MKVER

#define KDUMPFILE_MKVER | ( |  | major,
|  |  | minor,
|  |  | micro )

Value:
(((major) << 16) | ((minor) << 8) | ((micro)))

Make a single-number version from three digits of the release tag.

## KDUMPFILE_VERSION

#define KDUMPFILE_VERSION

Value:
KDUMPFILE_MKVER( \
KDUMPFILE_VER_MAJOR, \
KDUMPFILE_VER_MINOR, \
KDUMPFILE_VER_MICRO)
KDUMPFILE_VER_MINOR
#define KDUMPFILE_VER_MINOR
Minor version (2nd number in the release tag).
Definition kdumpfile.h:44
KDUMPFILE_VER_MAJOR
#define KDUMPFILE_VER_MAJOR
Major version (1st number in the release tag).
Definition kdumpfile.h:42
KDUMPFILE_VER_MICRO
#define KDUMPFILE_VER_MICRO
Micro version (3rd number in the release tag).
Definition kdumpfile.h:46
KDUMPFILE_MKVER
#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

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.

## kdump_addrspace_t

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.

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

## kdump_attr_ref_t

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.

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

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.

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

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.

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

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.

## kdump_status

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.

## kdump_vaddr_t

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.

## kdump_xen_type_t

typedef enum _kdump_xen_type kdump_xen_type_t

Type of a Xen dump.

See also
  KDUMP_ATTR_XEN_TYPE

## kdump_xen_xlat_t

typedef enum _kdump_xen_xlat kdump_xen_xlat_t

Xen physmap translation type.

See also
  KDUMP_ATTR_XEN_XLAT

## Enumeration Type Documentation

## _kdump_addrspace

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.

## _kdump_attr_type

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

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.

See also
  KDUMP_ATTR_BYTE_ORDER

## _kdump_mmap_policy

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

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.

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

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

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

enum kdump_clone_bits

Clone flag bits.

Bit positions for individual clone flags.

## Function Documentation

## kdump_attr_discard()

void kdump_attr_discard | ( | kdump_ctx_t * | ctx,
|  | kdump_attr_t * | attr )

Discard attribute data value.

Parameters

  ctx | Dump file object.
  attr | Attribute data.

Perform any actions necessary to release resources by the attribute data. This function may decrement object references, free dynamically allocated memory, or even do nothing, depending on the data type.

Call this function when the data returned by kdump_attr_ref_get is no longer needed. Do NOT call this function on attribute data returned by kdump_get_attr.

## kdump_attr_iter_end()

void kdump_attr_iter_end | ( | kdump_ctx_t * | ctx,
|  | kdump_attr_iter_t * | iter )

De-initialize an attribute iterator.

Parameters

  ctx | Dump file object.
  iter | Attribute 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

  ctx | Dump file object.
  iter | Attribute 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

  | ctx | Dump file object.
  [in] | path | Path to an attribute directory.
  [out] | iter | Attribute 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

  | ctx | Dump file object.
  [in] | key | Attribute key.
  [out] | ref | Attribute 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

  | ctx | Dump file object.
  [in] | ref | Attribute reference.
  [out] | valp | Attribute value (filled on return).

Returns
  Error status.

This works similarly to kdump_get_attr, except:

- the attribute is denoted by a reference rather than by path,
- the returned data stays valid even if changes are made to the dump object.

The returned value may be a dynamically allocated copy of the attribute value and/or it may hold an extra reference to the underlying objects. You should free up these resources with kdump_attr_discard when the data is no longer needed.

If the function returns an error, it is not necessary to discard the result. However, the type of `valp` is set to `KDUMP_NIL`, so it is always safe to call kdump_attr_discard on the result. The goal of this feature is to simplify code flow in callers.

## kdump_attr_ref_isset()

int kdump_attr_ref_isset | ( | kdump_attr_ref_t * | ref | ) |

Check whether an attribute is set.

Parameters

  ref | Attrbute 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

  | ctx | Dump file object.
  [in] | ref | Reference to an attribute directory.
  [out] | iter | Attribute 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

  | 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_ref_type()

kdump_attr_type_t kdump_attr_ref_type | ( | kdump_attr_ref_t * | ref | ) |

Get the type of an attribute by reference.

Parameters

  ref | Attribute 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

  ctx | Dump file object.
  ref | Attribute reference.

## kdump_blob_decref()

unsigned long kdump_blob_decref | ( | kdump_blob_t * | blob | ) |

Decrement kdump blob reference counter.

Parameters

  blob | Binary 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

  blob | Binary 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

  data | Raw data buffer (can be `NULL`).
  size | Length 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

  data | Raw data buffer (can be `NULL`).
  size | Length 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

  blob | Binary 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

  blob | Binary object.
  data | Pointer to new binary data.
  size | Size 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

  blob | Binary 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

  blob | Binary 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

  map | Translation 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

  bmp | Bitmap object.
  idx | Starting 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

  bmp | Bitmap object.
  idx | Starting 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

  bmp | Bitmap object.
  first | First index in the bitmap.
  last | Last index in the bitmap.
  raw | Raw 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

  bmp | Bitmap 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

  map | Translation map.

Returns
  New reference count.

## kdump_clear_err()

kdump_status void kdump_clear_err | ( | kdump_ctx_t * | ctx | ) |

Clear the error message.

Parameters

  ctx | Dump file object.

## kdump_clone()

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

Clone a dump file object.

Parameters

  orig | Original dump file object.
  flags | Specify 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

  ctx | Dump file object.
  val | Value 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

  ctx | Dump file object.
  val | Value 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

  ctx | Dump file object.
  val | Value 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

  ctx | Dump file object.
  status | Error status.
  msgfmt | Message 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

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

  ctx | Dump file object.
  axctx | Address translation context (filled on return).
  axsys | Address 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

  ctx | Dump file object.
  key | Attribute key.
  valp | Value (filled on successful return).

Returns
  Error status.

This function is useful only when the caller can fully control the lifetime of the returned attribute value. In that case, the value is valid only as long as no changes are made to the containing dump file object.

Note that attribute data (or the attribute hierarchy itself) may change as a side effect of another operation. Merely reading dump data or attributes will never invalidate the attribute value, i.e. it is safe to dereference pointers. However, the returned value may become stale, for example cache statistics.

A more robust API is provided by kdump_attr_ref_get.

## kdump_get_err()

const char * kdump_get_err | ( | kdump_ctx_t * | ctx | ) |

Get a detailed error string.

Parameters

  ctx | Dump 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_type_t | type,
|  | kdump_attr_value_t * | valp )

Get a dump file attribute with a given type.

Parameters

  ctx | Dump file object.
  key | Attribute key.
  type | Expected attribute type.
  valp | Value (updated on return).

Returns
  Error status.

If the attribute is of a different type, this function returns KDUMP_ERR_INVALID and does not change `valp`.

The caller must ensure the lifetime of the returned data is valid. See the description of kdump_get_attr for more details.

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

  ctx | Dump file object.
  nfds | Number of file descriptors in `fds`.
  fds | Open 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

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

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

  | ctx | Dump file object.
  [in] | as | Address space of `addr`.
  [in] | addr | Any type of address.
  [out] | pstr | String 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

  ctx | Dump file object.
  key | Attribute key.
  valp | New 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

  ctx | Dump file object.
  n | Number of names in `names`.
  names | Names. `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

  ctx | Dump file object.
  base | Reference to a base attribute.
  subkey | Attribute key, relative to `base`.
  valp | New attribute value.

Returns
  Error status.

## kdump_strerror()

const char * kdump_strerror | ( | kdump_status | status | ) |

Return the string describing a given error status.

Parameters

  status | Error 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

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

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

  | ctx | Dump file object.
  [in] | key | Name of the VMCOREINFO variable (part before '=').
  [out] | val | Filled 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

  ctx | Dump file object.
  raw | Filled 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

  | ctx | Dump file object.
  [in] | symname | Kernel symbol name.
  [out] | symvalue | Value of the symbol.

Returns
  Error status.

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