dump

Synopsis:

dump directory
dump |shell_command

Options:

directory

The output directory in the host.

or:

|shell_command

If the first character of the argument is a pipe, the characters that follow it are spawned as a shell command in the host, and the contents of the dump file are written to the shell's standard input.

Description:

On receipt of a SIGUSR2 signal or when triggered by a watchdog (see “Watchdogs” in the “QNX Hypervisor for Safety: Protection Features” chapter), write a dump file for a guest hosted in this qvm process instance. If the argument does not start with a pipe (“|”), write the dump file to the directory specified by directory. If the argument starts with pipe, spawn a shell command instead.

The dump file

The dump file is called prefix-YYYYMMDD-hhmmsss.gcore where:

• prefix is the name of the VM hosting the guest, as specified by the system option; if the system option isn't specified (see system in this chapter), prefix is set to qvm-guest
• YYYYMMDD-hhmmss is the host date and time at the moment that the dump is requested

If a file with the name that the qvm process composes for the dump file already exists in the specified directory, the qvm process attempts to generate a unique name by inserting a hyphen and a number from 1 to 9 (-1, -2, ... -9) before the .gcore extension. For example, if the files qnx7-20170821-120619 and qnx7-20170821-120619-1 exist, the qvm process creates a file called qnx7-20170821-120619-2. If the qvm process is unable to create a unique filename, it doesn't create a dump file.

The dump file is output in ELF64 format. A PT_NOTE segment has the register states for the vCPUs, and PT_LOAD segments have the guest memory contents. The format of the PT_NOTE segment is described by the sys/kdump.h public header file.

To interpret the dump file, you can use GDB and kdserver (see “kdserver” in the QNX Neutrino Utilities Reference).

Example:

On receipt of a SIGUSR2 signal, the configuration excerpt shown below will execute a host shell command that compresses the guest's dump file and writes it to the spawned command line (gzip). The gzip utility will then write the compressed file to its stdout (dump_output.gz):

dump "|gzip >dump_output.gz"