Overview

The introspection API (IAPI) is a collection of kernel messages that allows you to obtain information about the system and other processes. It's also required if you implement a dumper service, which creates core files of (abnormally terminating) processes. The API is meant to be used in production systems (i.e., using it doesn't violate the Safety Manual).

The IAPI can:

retrieve all process IDs (PIDs) (introspection_allocate_and_get_all_pids(), introspection_get_all_pids()).
retrieve the PIDs of all child processes of a process (introspection_allocate_and_get_all_child_pids(), introspection_get_all_child_pids()).
register as the system dumper.
continue the termination of a faulted process after creating a core file.
process status (introspection_get_proc_info(), introspection_get_process_name()).
thread status (introspection_get_thread_status()).
general purpose registers of the user persona of a thread (introspection_get_generalpurpose_regs()).
floating point registers of the user persona of a thread (introspection_get_floatingpoint_regs()).
provide information about process mappings (introspection_get_pagetableinfo(), introspection_get_physical_regions(), introspection_get_virtual_regions()).
read process memory (introspection_read_process_memory()).
provide path information of memory mapped filesystem objects (introspection_get_mapped_object_path()).

Retrieving all PIDs

For example, the following image illustrates the general usage pattern of the IAPI. When a process sends a message to the process manager, it gets a list of PIDs back. The process can then get information from those PIDs, such as their process names:

Creating a dumper

To implement a custom dumper service, a process has to do the following:

proc_coredump_t	msg;

msg.i.type = _PROC_COREDUMP;
msg.i.subtype = _PROC_COREDUMP_REGISTER_EVENT;
SIGEV_PULSE_INIT(&msg.i.event, -dump_thread_chid, -1, DUMP_PULSE_CODE_EVENT, 0);
SIGEV_MAKE_UPDATEABLE(&msg.i.event);

if (MsgRegisterEvent(&msg.i.event, PROCMGR_COID) == -1) {
    perror("Failed to register dumper event");
    exit(EXIT_FAILURE);
}

if (MsgSend(PROCMGR_COID, &msg, sizeof(msg), NULL, 0) == -1) {
    perror("Failed to register dumper event with the kernel");
    exit(EXIT_FAILURE);
}

The event doesn't have to be a pulse, but it must be registered. A process must have the PROCMGR_AID_DUMPER ability enabled.

Sit and wait for the event. The kernel delivers the event when a process abnormally terminates or receives a signal that requires core dumping. The event carries the process identifier of the affected process:
```
const pid64_t pid = pulse.value.sival_long
```
Using that PID, the dumper can use the introspection API to collect all information that is required to create a core file, which includes the name of the process, its thread count, mappings, memory contents, etc.

After the core file is created, the process being dumped must be removed from the system. This is done by sending another message:

proc_coredump_t	msg;
msg.i.type = _PROC_COREDUMP;
msg.i.subtype = _PROC_COREDUMP_CONT_TERM;
msg.i.pid = pid;
msg.i.status = status;

if (MsgSend(PROCMGR_COID, &msg, sizeof(msg), NULL, 0) == -1) {
    perror("dump_finished: MsgSend failed, cannot clean process, exiting");
    exit(EXIT_FAILURE);
}

Only the dumper can send the message.

The following image illustrates the core dump creation process:

Page updated: June 11, 2026