dump

Synopsis:

dump directory

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” 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 file name, it doesn't create a dumpfile.

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 “Utilities and Drivers Reference” chapter).

Example:

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

dump "|gzip >dump_output.gz"