User-Mode Dump Files

This section includes:

For information on analyzing a dump file, see Analyzing a User-Mode Dump File.

Varieties of User-Mode Dump Files

There are several kinds of user-mode crash dump files, but they are divided into two categories:

Full User-Mode Dumps

Minidumps

The difference between these dump files is one of size. Minidumps are usually more compact, and can be easily sent to an analyst.

Note   Much information can be obtained by analyzing a dump file. However, no dump file can provide as much information as actually debugging the crash directly with a debugger.

Full User-Mode Dumps

A full user-mode dump is the basic user-mode dump file.

This dump file includes the entire memory space of a process, the program's executable image itself, the handle table, and other information that will be useful to the debugger.

It is possible to "shrink" a full user-mode dump file into a minidump. Simply load the dump file into the debugger and then use the .dump (Create Dump File) command to save a new dump file in minidump format.

Note   Despite their names, the largest "minidump" file actually contains more information than the full user-mode dump. For example, .dump /mf or .dump /ma will create a larger and more complete file than .dump /f.

In user mode, .dump /m[MiniOptions] is the best choice. The dump files created with this switch can vary in size from very small to very large. By specifying the proper MiniOptions you can control exactly what information is included.

Minidumps

A user-mode dump file that includes only selected parts of the memory associated with a process is called a minidump.

The size and contents of a minidump file vary depending on the program being dumped and the application doing the dumping. Sometimes, a minidump file is fairly large and includes the full memory and handle table. Other times, it is much smaller -- for example, it might only contain information about a single thread, or only contain information about modules that are actually referenced in the stack.

The name "minidump" is misleading, because the largest minidump files actually contain more information than the "full" user-mode dump. For example, .dump /mf or .dump /ma will create a larger and more complete file than .dump /f. For this reason, .dump /m[MiniOptions] recommended over .dump /f for all user-mode dump file creation.

If you are creating a minidump file with the debugger, you can choose exactly what information to include. A simple .dump /m command will include basic information about the loaded modules that make up the target process, thread information, and stack information. This can be modified by using any of the following options:

.dump option Effect on dump file

/ma

Creates a minidump with all optional additions. The /ma option is equivalent to /mfFhut -- it adds full memory data, handle data, unloaded module information, basic memory information, and thread time information to the minidump.

/mf

Adds full memory data to the minidump. All accessible committed pages owned by the target application will be included.

/mF

Adds all basic memory information to the minidump. This adds a stream to the minidump that contains all basic memory information, not just information about valid memory. This allows the debugger to reconstruct the complete virtual memory layout of the process when the minidump is being debugged.

/mh

Adds data about the handles associated with the target application to the minidump.

/mu

Adds unloaded module information to the minidump. This is only available in Windows Server 2003 and later versions of Windows.

/mt

Adds additional thread information to the minidump. This includes thread times, which can be displayed by using .ttime (Display Thread Times) when debugging the minidump.

/mi

Adds secondary memory to the minidump. Secondary memory is any memory referenced by a pointer on the stack or backing store, plus a small region surrounding this address.

/mp

Adds process environment block (PEB) and thread environment block (TEB) data to the minidump. This can be useful if you need access to Windows system information regarding the application's processes and threads.

/mw

Adds all committed read-write private pages to the minidump.

/md

Adds all read-write data segments within the executable image to the minidump.

/mc

Adds code sections within images.

/mr

Deletes from the minidump those portions of the stack and store memory that are not useful for recreating the stack trace. Local variables and other data type values are deleted as well. This option does not make the minidump smaller (since these memory sections are simply zeroed), but it is useful if you wish to protect the privacy of other applications.

/mR

Deletes the full module paths from the minidump. Only the module names will be included. This is a useful option if you wish to protect the privacy of the user's directory structure.

/mk " FileName "

(Windows Vista only) Creates a kernel-mode minidump in addition to the user-mode minidump. The kernel-mode minidump will be restricted to the same threads that are stored in the user-mode minidump. FileName must be enclosed in quotation marks.

These options can be combined. For example, the command .dump /mfiu can be used to create a fairly large minidump, or the command .dump /mrR can be used to create a minidump that preserves the user's privacy. For full syntax details, see .dump (Create Dump File).

Creating a User-Mode Dump File

There are several different tools that can be used to create a user-mode dump file: CDB, WinDbg, Windows Error Reporting (WER), UserDump, and ADPlus.

For information about creating a user-mode dump file through ADPlus, see ADPlus.

For information about creating a user-mode dump file through WER, see Windows Error Reporting.

Choosing the Best Tool

There are several different tools that can create user-mode dump files. In most cases, ADPlus is the best tool to use.

The following table shows the features of each tool.

Feature ADPlus Windows Error Reporting CDB and WinDbg UserDump

Creating a dump file when an application crashes (postmortem debugging)

Yes

Yes

Yes

Yes

Creating a dump file when an application "hangs" (stops responding but does not actually crash)

Yes

No

Yes

Yes

Creating a dump file when an application encounters an exception

Yes

Yes

Yes

Yes

Creating a dump file while an application is running normally

No

No

Yes

No

Creating a dump file from an application that fails during startup

No

No

Yes

Yes

Shrinking an existing dump file

No

No

Yes

No

CDB and WinDbg

CDB and WinDbg can create user-mode dump files in a variety of ways.

Creating a Dump File Automatically

When an application error occurs, Windows can respond in several different ways, depending on the postmortem debugging settings. If these settings instruct a debugging tool to create a dump file, a user-mode memory dump file will be created. For more information, see Enabling Postmortem Debugging.

Creating Dump Files While Debugging

When CDB or WinDbg is debugging a user-mode application, you can also the .dump (Create Dump File) command to create a dump file.

This command does not cause the target application to terminate. By selecting the proper command options, you can create a minidump file that contains exactly the amount of information you wish.

Shrinking an Existing Dump File

CDB and WinDbg can also be used to shrink a dump file. To do this, begin debugging an existing dump file, and then use the .dump command to create a dump file of smaller size.

UserDump

The UserDump tool (Userdump.exe), also known as User-Mode Process Dump, can create user-mode dump files.

UserDump and its documentation are part of the OEM Support Tools package.

For more info and to download these tools, see How to use the Userdump.exe tool to create a dump file and follow the instructions on that page. Additionally, When CDB or WinDbg is debugging a user-mode application, you can also use the .dump (Create Dump File) command to create a dump file.