| Debugging Tools for Windows |
To use GFlags, type the following commands at the command line.
You can use the GFlags commands and the Global Flags Dialog Box interchangeably.
To open the GFlags dialog box:
To set or clear global flags in the registry:
To set or clear global flags for the current session:
To set or clear global flags for an image file:
gflags /i ImageFile /tracedb SizeInMB
To set or clear the Special Pool feature (Windows Vista and later)
To enable or disable the Object Reference Tracing feature (Windows Vista and later)
To enable and configure page heap verification:
[/debug ["DebuggerCommand"] | /kdebug] [/unaligned] [/notraces] [/fault Rate [TimeOut]] [/leaks] [/protect] [/no_sync] [/no_lock_checks]
To disable page heap verification:
To display help:
Use one of the following flag formats:
| Format | Description |
|---|---|
| {+ | -}FlagAbbr | Sets (+) or clears (-) the flag represented by the flag abbreviation. Without a plus (+) or minus (-) symbol, the command has no effect. |
| [+ | -]FlagHex | Adds (+) or subtracts (-) the hexadecimal value of a flag. A flag is set when its value is included in the sum. Add (+) is the default. Enter a hexadecimal value (without 0x) that represents a single flag or enter the sum of hexadecimal values for multiple flags. |
With no additional parameters, gflags /r displays the system-wide flags set in the registry.
With no additional parameters, gflags /k displays system-wide flags set for the current session.
With no additional parameters, gflags /i ImageFile displays the flags set for the specified process.
SizeInMB is a whole number representing the number of megabytes in decimal units. The default value is the minimum size, 8 MB; there is no maximum size. To revert to the default size, set SizeInMB to 0.
Enter a four-character pattern for PoolTag, such as Tag1. It can include the ? (substitute for any single character) and * (substitute for multiple characters) wildcard characters. For example, Fat* or Av?4. Pool tags are always case-sensitive.
Without additional parameters, /ro displays the Object Reference Tracing settings in the registry.
To enable Object Reference Tracing, you must include at least one pool tag (/t PoolTag) or one image file (/i ImageFile) in the command. For details, see Example 15: Using Object Reference Tracing.
The following table lists the subparameters that are valid with /ro.
| /t PoolTags | Limits the trace to objects with the specified pool tags. Use a semicolon (;) to separate tag names. Enter up to 16 pool tags. Enter a four-character pattern for PoolTags, such as Tag1. If you specify more than one pool tag, Windows traces objects with any of the specified pool tags . If you do not specify any pool tags, Windows traces all objects that are created by the image. |
| /i ImageFile | Limits the trace to objects that are created by processes with the specified image file. You can specify only one image file with the /i parameter. Enter an image file name, such as notepad.exe, with up to 64 characters. "System" and "Idle" are not valid image names. If you do not specify an image file, Windows traces all objects with the specified pool tags. If you specify both an image file (/i) and one or more pool tags (/t), Windows traces objects with any of the specified pool tags that are created by the specified image. |
| /d | Clears the Object Reference Tracing feature settings. When used with /ro, it clears the settings in the registry. |
| /p | Permanent. The trace data is retained until Object Reference Tracing is disabled, or the computer is shut down or restarted. By default, the trace data for an object is discarded when the object is destroyed. |
Without additional parameters, /ko displays the kernel flag (run time) Object Reference Tracing settings.
To enable Object Reference Tracing, you must include at least one pool tag (/t PoolTag) or one image file (/i ImageFile) in the command.
The following table lists the subparameters that are valid with /ko.
| /t PoolTags | Limits the trace to objects with the specified pool tags. Use a semicolon (;) to separate tag names. Enter up to 16 pool tags. Enter a four-character pattern for PoolTags, such as Tag1. If you specify more than one pool tag, Windows traces objects with any of the specified pool tags. If you do not specify any pool tags, Windows traces all objects that are created by the image. |
| /i ImageFile | Limits the trace to objects that are created by processes with the specified image file. You can specify only one image file with the /i parameter. If you do not specify an image file, Windows traces all objects with the specified pool tags. If you specify both an image file (/i) and one or more pool tags (/t), Windows traces objects with any of the specified pool tags that are created by the specified image. |
| /d | Clears the Object Reference Tracing feature settings. When used with /ro, it clears the settings in the registry. |
| /p | Permanent. The trace data is retained until Object Reference Tracing is disabled, or the computer is shut down or restarted. By default, the trace data for an object is discarded when the object is destroyed. |
With no additional parameters, gflags /p displays a list of image files for which page heap verification is enabled.
Page heap verification monitors dynamic heap memory operations, including allocate operations and free operations, and causes a debugger break when it detects a heap error.
This command is equivalent to turning off the Enable page heap (hpa) flag for a process (gflags /i ImageFile -hpa). You can use the commands interchangeably.
By default, the /enable parameter turns on standard page heap verification for the image file. To enable full page heap verification for the image file, add the /full parameter to the command or use the /i parameter with the +hpa flag.
Using this parameter is equivalent to turning on the Enable page heap (hpa) flag for a process (gflags /i ImageFile +hpa). You can use the commands interchangeably.
Probability is a decimal integer from 0 through 100 representing the probability of full page heap verification. A probability of 100 is the same as using the /full parameter. A probability of 0 is the same as using standard page heap verification.
SizeStart and SizeEnd are decimal integers. The default is standard page heap verification for all allocations.
To use this feature, specify a range that includes the addresses of all functions that call the function with the suspect allocation. The address of the calling function will be on the call stack when the suspect allocation occurs.
AddressStart and AddressEnd specify the address range searched in allocation stack traces. The addresses are specified in hexadecimal format, such as, 0xAABBCCDD.
On Windows Server 2003 and earlier systems, the /address parameter is valid only on x86-based computers. On Windows Vista,: it is valid on all supported architectures.
DLL is the name of a binary file, including its file name extension. The specified file must be a function library that the process loads during execution.
By default, this parameter uses the NTSD debugger with the command line ntsd -g -G -x and with page heap enabled, but you can use the DebuggerCommand variable to specify a different debugger and command line.
For information about NTSD, see CDB and NTSD.
This option is useful for programs that are difficult to start from a command prompt and those that are started by other processes.
If the command includes a path to the debugger, the path cannot contain any other quotation marks. If other quotation marks appear, the command shell (cmd.exe) will misinterpret the command.
For information about NTSD, see CDB and NTSD.
This option is used to detect off-by-one-byte errors. When this parameter is used with the /full parameter, the zone of reserved virtual memory begins just after the last byte of the allocation and an immediate fault occurs when a process tries to read or write even one byte beyond the allocation.
The PageHeap program (pageheap.exe) included in Windows 2000 implemented full page heap verification by placing an inaccessible page after an allocation. In that tool, the /decommit parameter substituted a zone of reserved virtual memory for the inaccessible page. In this version of GFlags, a zone of reserved virtual memory is always used to implement full page heap verification.
This option improves performance slightly, but it makes debugging much more difficult. This parameter is valid, but its use is not recommended.
This parameter inserts heap allocation errors into the image file being tested (a practice known as "fault injection") so that some memory allocations fail, as might occur when the program runs in low memory conditions. This test helps to detect errors in handling allocation failure, such as failing to release resources.
| Rate | Specifies a decimal integer from 1 (.01%) through 10000 (100%) representing the probability that an allocation will fail. The default is 100 (1%). |
| TimeOut | Determines the time interval between the start of the program and the start of the fault injection routines. TimeOut is measured in seconds. The default is 5 (seconds). |
The /leaks parameter disables full page heap. When /leaks is used, the /full parameter and parameters that modify the /full parameter, such as /backwards, are ignored, and GFlags performs standard page heap verification with a leak check.
Do not use this flag to debug a program that includes a customized heap manager. Functions that synchronize heap access cause the page heap verifier to report synchronization faults that do not exist.
Typing gflags without parameters opens the Global Flags dialog box.
Typing gflags /p without additional parameters displays a list of programs that have page heap verification enabled.
To clear all flags, set Flag to -FFFFFFFF. (Setting Flag to 0 adds zero to the current flag value. It does not clear all flags.)
When you set Flag for an image file to FFFFFFFF, Windows clears all flags and deletes the GlobalFlag entry in the registry subkey for the image file. The subkey remains.
The /full, /random, /size, /address, and /dlls parameters for the page heap /enable operation determine which allocations are subject to page heap verification and the verification method used. You can use only one of these parameters in each command. The default is standard page heap verification of all allocations of the process. The remaining parameters set options for page heap verification.
The page heap features in GFlags only monitor heap memory allocations that use the standard Windows heap manager functions (HeapAlloc, GlobalAlloc, LocalAlloc, malloc, new, new[], or their corresponding deallocation functions), or those that use custom operations that call the standard heap manager functions.
To determine whether full or standard page heap verification is enabled for a program, at the command line, type gflags /p. In the resulting display, traces indicates that standard page heap verification is enabled for the program and full traces indicates that full page heap verification is enabled for the program.
The /enable parameter sets the Enable page heap (hpa) flag for the image file in the registry. However, the /enable parameter turns on standard heap verification for the image file by default, unlike the /i parameter with the +hpa flag, which turns on full heap verification for an image file.
Standard page heap verification places random patterns at the end of an allocation and examines the patterns when a heap block is freed. Full page heap verification places a zone of reserved virtual memory at the end of each allocation.
Full page heap verification can consume system memory quickly. To enable full page heap verification for memory-intensive processes, use the /size or /dlls parameter.
After using global flags for debugging, submit a gflags /p /disable command to turn off the page heap verification and delete associated registry entries. Otherwise, entries that the debugger reads remain in the registry. You cannot use the gflags /i hpa command for this task, because it turns off page heap verification, but does not delete the registry entries.
By default, on Windows Vista and later versions of Windows, program-specific settings (image file flags and page heap verification settings) are stored in the current user account.
This version of GFlags includes the -v options, which enable features being developed for GFlags. However, these features are not yet complete and, therefore, are not documented.