dump

Write a dump file for the guest

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: Protection Features chapter), write a dump file for the 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 this 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 qnx8-20170821-120619 and qnx8-20170821-120619-1 exist, the qvm process creates a file called qnx8-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 OS Utilities Reference). You can also run use -i dump_file to display much more information than usual to assist with troubleshooting. The information displayed in this case includes:
  • pidin information about the host machine that qvm is running on
  • information about the version of qvm that is running
  • the qvm configuration being used
  • the same output you get when you send SIGUSR1 (QL_QVM_INFO, or information-level, messages)
For more information about this last utility, see the use entry in the Utilities Reference.

Example:

On receipt of a SIGUSR2 signal, the configuration excerpt shown below will direct the guest's dump file contents to a host shell command that compresses these contents (gzip) and then writes the compressed file to stdout, which is the file dump_output.gz: 
dump "|gzip >dump_output.gz"
Note:
The quotation marks around the argument are used so that when qvm parses the configuration it reads the full shell command as a single qvm argument.
Page updated: