GFlags Command Overview

For general information on how to install and locate gflags.exe, see GFlags.

You can use the GFlags commands and the Global Flags Dialog Box interchangeably.

GFlags Command Usage

To use GFlags, type the following commands at the command line.

To open the GFlags dialog box:

gflags

To set or clear global flags in the registry:

gflags /r [{+ | -}Flag [{+ | -}Flag...]]

To set or clear global flags for the current session:

gflags /k [{+ | -}Flag [{+ | -}Flag...]]

To set or clear global flags for an image file:

gflags /i ImageFile [{+ | -}Flag [{+ | -}Flag...]]
gflags /i ImageFile /tracedb SizeInMB

To set or clear the Special Pool feature (Windows Vista and later)

gflags {/r | /k} {+ | -}spp {PoolTag | 0xSize}

To enable or disable the Object Reference Tracing feature (Windows Vista and later)

gflags {/ro | /ko} [/p] [/i ImageFile | /t PoolTag;[PoolTag...]]

gflags {/ro | /ko} /d

To enable and configure page heap verification:

gflags /p /enable ImageFile  [ /full [/backwards] | /random Probability | /size SizeStart SizeEnd | /address AddressStart AddressEnd | /dlls DLL [DLL...] ] 
[/debug ["DebuggerCommand"] | /kdebug] [/unaligned] [/notraces] [/fault Rate [TimeOut]] [/leaks] [/protect] [/no_sync] [/no_lock_checks] 

To disable page heap verification:

gflags /p [/disable ImageFile] [/?]

To display help:

gflags /?

Parameters

Flag
Specifies a three-letter abbreviation (FlagAbbr) or hexadecimal value (FlagHex) that represents a debugging feature. The abbreviations and hexadecimal values are listed in the GFlags Flag Table.

Use one of the following flag formats:

ImageFile
Specifies the name of an executable file, including the file name extension (for example, notepad.exe or mydll.dll).

/r
Registry. Displays or changes system-wide debugging flags stored in the registry. These settings take effect when you restart Windows and remain effective until you change them.

With no additional parameters, gflags /r displays the system-wide flags set in the registry.

/k
Kernel flag settings. Displays or changes system-wide debugging flags for this session. These settings are effective immediately, but are lost when Windows shuts down. The settings affect processes started after this command completes.

With no additional parameters, gflags /k displays system-wide flags set for the current session.

/i
Image file settings. Displays or changes debugging flags for a particular process. These settings are stored in the registry. They are effective for all new instances of this process and they remain effective until you change them.

With no additional parameters, gflags /i ImageFile displays the flags set for the specified process.

/tracedb SizeInMB
Sets the maximum size of the user-mode stack trace database for the process. To use this parameter, the Create user mode stack trace database (ust) flag must be set for the 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.

spp
(Windows Vista and later.) Sets or clears the Special Pool feature. For an example, see Example 14: Configuring Special Pool.

PoolTag
(Windows Vista and later.) Specifies a pool tag for the Special Pool feature. Use only with the spp flag.

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.

0xSize
(Windows Vista and later.) Specifies a size range for the Special Pool feature. Use only with the spp flag. For guidance on selecting a size value, see "Selecting an Allocation Size" in Special Pool.

/ro
Enables, disables, and displays Object Reference Tracing settings in the registry. To make a change to this setting effective, you must restart Windows.

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.

/ko
Enables, disables, and displays kernel flag (run time) Object Reference Tracing settings. Changes to this setting are effective immediately, but are lost when the system is shut down or restarted. For details, see Example 15: Using Object Reference Tracing.

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.

/p
Sets page heap verification options for a process.

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.

/disable ImageFile
Turns off page heap verification (standard or full) for the specified image file.

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.

/enable ImageFile
Turns on page heap verification for the specified image file.

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.

/full
Turns on full page heap verification for the process. Full page heap verification places a zone of reserved virtual memory at the end of each allocation.

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.

/backwards
Places the zone of reserved virtual memory at the beginning of an allocation, rather than at the end. As a result, the debugger traps overruns at the beginning of the buffer, instead of those at the end of the buffer. Valid only with the /full parameter.

/random Probability
Chooses full or standard page heap verification for each allocation, based on the specified probability.

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.

/size SizeStart SizeEnd
Enables full page heap verification for allocations within the specified size range and enables standard page heap verification for all other allocations by the process.

SizeStart and SizeEnd are decimal integers. The default is standard page heap verification for all allocations.

/address AddressStart AddressEnd
Enables full page heap verification for memory allocated while a return address in the specified address range is on the run-time call stack. It enables standard page heap verification for all other allocations by the process.

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.

/dlls DLL[, DLL...]
Enables full page heap verification for allocations requested by the specified DLLs and standard page heap verification for all other allocations by the process.

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.

/debug
Automatically launches the process specified by the /enable parameter under a debugger.

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 Debugging Using 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.

"DebuggerCommand"
Specifies a debugger and the command sent to the debugger. This quoted string can include a fully qualified path to the debugger, the debugger name, and command parameters that the debugger interprets. The quotation marks are required.

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.

/kdebug
Automatically launches the process specified by the /enable parameter under the NTSD debugger with the command line ntsd -g -G -x, with page heap enabled, and with control of NTSD redirected to the kernel debugger.

For information about NTSD, see Debugging Using CDB and NTSD.

/unaligned
Aligns the end of each allocation at an end-of-page boundary, even if doing so means that the starting address is not aligned on an 8-byte block. By default, the heap manager guarantees that the starting address of an allocation is aligned on an 8-byte block.

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.

/decommit
This option is no longer valid. It is accepted, but ignored.

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.

/notraces
Specifies that run-time stack traces are not saved.

This option improves performance slightly, but it makes debugging much more difficult. This parameter is valid, but its use is not recommended.

/fault
Forces the program's memory allocations to fail at the specified rate and after the specified time-out.

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.

/leaks
Checks for heap leaks when a process ends.

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.

/protect
Protects heap internal structures. This test is used to detect random heap corruptions. It can make execution significantly slower.

/no_sync
Checks for unsynchronized access. This parameter causes a break if it detects that a heap created with the HEAP_NO_SERIALIZE flag is accessed by different threads.

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.

/no_lock_checks
Disables the critical section verifier.

/?
Displays help for GFlags. With /p, /? displays help for the page heap verification options in GFlags.

Comments

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.