dumper

QNX SDP8.0Utilities ReferenceUtilities

Dump the postmortem state of a program (QNX)

Syntax:

dumper [-abFfIlmnPStuvw] [-d path] [-E num] [-H size[G|M|K]]
       [-L num_pages] [-N max_files] [-o mode] [-p pid] [-s size[G|M|K]] 
       [-U string] [-z level] &

Runs on:

QNX OS

Options:

-a
Allow applications to write an ASCII process ID to /proc/dumper (e.g. echo 2 > /proc/dumper) to trigger a core dump of a process. With this option enabled, the application doesn't need all the abilities of dumper but rather requires only write access to /proc/dumper.
-b
Attempt to slog a backtrace (libbacktrace.so.1 and libunwind-generic.so.8 should be available).
-d path
The directory in which to place dumps. The default is the home directory of user that started the process, or /tmp if none.
-E num
The maximum size for the list of the names of the most recent dump files. The default is 10.
-F
Run at a fixed priority.
-f
Follow soft links for the creation of the dump files. The use of this option has security implications.
-H size[G|M|K]
Suppress the dumping of memory if the memory usage is greater than size.
-I
Include the process ID in the core file's name.
-L num_pages
Assign num_pages pages to the dumper utility's slog2 buffer. The minimum (and default) is 1 page.
-l
(el) Use only the secondary method of finding the link map. The primary method is to walk the link map created in the process memory by the loader, but this can fail for various reasons:
  • The link map is a linked list on the heap, so heap corruption can make it invalid.
  • Static linking was used.
  • The crash occurred before ldd created the linked list.

The secondary method queries the process manager for the memory mappings and then uses that list to create the link map. If the primary method fails, dumper tries the secondary one.

-m
Don't dump memory.
-N max_files
Save sequential dumps, to a maximum of max_files files. The behavior is identical to that described for the -n option, except that when a new core file is generated, the one with the minimum sequence number is deleted if there are more than max_files core files in the directory.

For example, if you specify -N 3 before running a program that you expect to crash and create core dumps, the first three core files are kept and are named executable.1.core, executable.2.core, and executable.3.core. When the next core file is generated, it's named executable.4.core and executable.1.core is deleted.

Note:
This design differs from that in previous releases, when all existing files named executable.number.core with number greater than or equal to max_files were deleted. In this release, only one core file (the one with the minimum sequence number) is deleted. So if you manually copy other core files with similar names and sequence numbers into the directory, you could end up with more than max_files files.
-n
Save sequential dumps. Every time a new core file is generated, it is saved as executable.latest.core, where latest is one more than the maximum sequence number of the previously existing files. Thus, the first core file generated is executable.1.core, the next one is executable.2.core, and so on.
Note:
This design differs from that in previous releases, when the latest dump was named executable.core and older core files were kept as executable.number.core, where number was decreasing based on how recently the file was generated. In this release, there is no more renaming in which existing files' numbers are incremented by 1 and executable.core is renamed executable.1.core.
-o mode
Set file permissions mode (e.g. 0664) for /proc/dumper.
-P
Dump the physical memory mappings.
Warning:

This option causes dumper to read parts of the process's address space that likely include hardware registers. When these registers are read, it may lead to side effects that can result in undefined and unsafe behavior, including system crashes or hanging.

To use this option at all, you must know the detailed behavior of every piece of hardware accessible to the processes being dumped. If you're running dumper in the background, it dumps any process that abnormally terminates, so all processes with access to hardware could be dumped and thus, all hardware accessible to processes could be examined. If you're manually running dumper with -p to save a dump file for a particular process, you have to worry about only the hardware accessible to this process.

-p pid
Save a dump file for this process immediately, and then exit dumper.
-S
Disable the dumping of shared memory mappings.
-s size[G|M|K]
Set the default maximum core size, in bytes. You can override this for a process by setting its RLIMIT_CORE resource; see the entry for setrlimit() in the QNX OS C Library Reference.
-t
Dump the stack of the errant thread only, instead of for all threads.
-U string
Once running, run as the specified user, so that the program doesn't need to run as root. The string can be in one of these forms:
  • uid[:gid[,sup_gid]*]
  • user_name[,sup_gid]*

In the second form, the primary group is the one specified for user_name in /etc/passwd.

-u
Enable timestamping on core files (e.g., executable-YYYYMMDD_HHMMSS_MSEC.core).
Note:

The number sequencing in filenames doesn't apply to timestamped files; when -u is set, -N and -n are not allowed.

Users can have either timestamping or sequential dumping but not both at the same time. If both file-naming features are set, dumper prints an error and exits.

-v
Be verbose.
-w
Make core files world-readable.
-z level
Use gzip to compress the core files. The compression level must be in the range from 1 (fastest) through 9 (best compressed).

Description:

The dumper utility runs in the background and provides a postmortem dump service for all processes. Whenever a program terminates abnormally, a dump of the current state of the program is written to disk. The dump filename is the same as the program name with a .core extension. For example, if the program name is experiment, the dump is written to experiment.core in your home directory.

Note:
Dump files can be large, so make sure the destination filesystem has lots of space.

The -p option lets you get a dump immediately for a particular process. If you specify -p, dumper doesn't run in the background, but exits right away.

When dumper runs as a service it provides two client interfaces. The first client interface allows for notification of core dump creation through a devctl() interface. The second client interface allows for triggering a core dump by writing an (ASCII) process ID to /proc/dumper; this is how the OS triggers core dumps to happen.

To run as as service, dumper must maintain some high-risk privileges that allow it to:

  • Read the memory of any process in the system.
  • Switch to/from root (euid = 0) in order to create (and possibly change ownership) of files.
  • Possibly retain the ability to deliver a signal to any process in the system (to handle the client write to dump a pid).
Notice:
The dump creation interface is a high-risk interface since it can be used to temporarily and even repeatedly freeze (SIGSTOP) processes (denial of service), or to dump the process memory somewhere accessible (data exposure). This has been mitigated in two ways:
  • The default permissions are 0640, making it easy for a process to be given only read access.
  • By default, dumper accepts write requests only from Proc.

To register for dump notifications, use the DCMD_DUMPER_NOTIFYEVENT devctl() command. It will notify you when the core dump is available. You can also use the DCMD_DUMPER_GETPATH command to get the name of the dump file for a process. Using these devctl() commands requires read access to /proc/dumper. For more information, see Devctl and Ioctl Commands.

You can use a debugger such as gdb to examine a dump file: 
gdb program_binary program_core
A program may terminate in one of two ways: it may exit cleanly under its own control, returning an exit status, or it may be forcibly terminated by the receipt of a signal that it isn't prepared to handle. In the latter case, dumper writes a dump file for the following set of signals:
Signal Description
SIGABRT Program-called abort function
SIGBUS Parity error
SIGEMT EMT instruction (emulation trap)

Note that SIGEMT and SIGDEADLK refer to the same signal.

SIGFPE Floating-point error or division by zero
SIGILL Illegal instruction executed
SIGQUIT Quit
SIGSEGV Segmentation violation
SIGSYS Bad argument to a system call
SIGTRAP Trace trap (not reset when caught)
SIGXCPU Exceeded the CPU limit

You can force the dump of a running program by setting one of the preceding signals, assuming that the program isn't masking or handling the signal itself.

For example, to force a dump using the kill command and a process ID (pid): 
kill -SIGABRT pid
To force a dump using the slay utility and the process name: 
slay -s SIGABRT process_name

Examples:

Start dumper, with dump files to be written to the default directory: 
dumper &
Start dumper, with dump files to be placed in the directory /home/dumps: 
dumper -d /home/dumps &

Files:

/proc/dumper
A special entry in the /proc filesystem (see procnto*) that receives notification when a process terminates abnormally.

Exit status:

The dumper utility normally doesn't terminate. However, it may terminate if it encounters an error on startup (for instance, if it wasn't run by root) or if it receives a signal.

0
A signal was received and dumper shut down successfully.
1
An error was encountered on startup (not run by root or bad command-line options).
Page updated: