NAME

ucoredev — user coredump extraction interface

SYNOPSIS

To load the driver as a module at boot time, place the following line in loader.conf(5):

ucoredev_load="YES"

Note that ucored(8) will attempt to autoload

ucoredev when it starts, if it has not been loaded.

DESCRIPTION

The ucoredev device is used to extract user coredumps from the kernel. When ucoredev is loaded, it uses the coredumper_register(9) interface to claim all coredump collection. When a user process subsequently dumps core, ucoredev processes it and writes that into a shared memory object for later extraction.

A read(2) from ucoredev will then materialize that coredump into a shmfd, as if the process reading had called shm_open(2) itself to create an anonymous shared memory object. ucoredev does not retain any references to the coredump after it has been read(2) from the device, so a subsequent close(2) will discard the coredump entirely if it has not been persisted to disk by the reader.

Note that ucoredev will create and return as many file descriptors as will fit into the buffer provided. If it fails to create a file descriptor, ucoredev will retain the core until a subsequent read(2) in case the failure was a transient condition.

PROTOCOL

The ucoredev device will frame coredumps with its own header for various metadata that it collects about the process that was dumped. The data structures in <ucoredev.h> should be used to process the coredump. It is expected that a process would mmap(2) the shm fd that is returned and map out the header, data segments, and coredump data there.

Each shm object will begin with a struct ucore, which records all of the numeric properties that are necessary for every coredump. The ucore_datasegs member describes how many struct ucore_data segments will follow. The size of the coredump is encoded in ucore_size for convenience, so that one need not parse through all of the data segments to get to the data.

Data segments are mostly used for string properties of the jail. Each segment begins with a struct ucore_data_hdr that describes the type of data, and the size of the data that will follow. The uhdr_size does not include the size of the header itself.

Note that the header may be padded more than expected to align the ud_data element sufficiently for any data that we may want to extract and ud_data is a VLA, so sizeof(struct ucore_data) describes the position of the data relative to the struct before it more accurately than sizeof(struct ucore_data_hdr) would.

Metadata ends at the last data segment, only the coredump itself follows.

NAME

SYNOPSIS

DESCRIPTION

PROTOCOL

SEE ALSO