GFlags Commands

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

You can use the Gflags commands and the Global Flags dialog box interchangeably.

Syntax

gflags [/r [Flag [Flag...]] | /k [Flag [Flag...]] | /i ImageFile [Flag [Flag...]] | /i ImageFile /tracedb SizeInMB | /?]

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

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

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:

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.

ImageFile

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.

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-mode 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.

/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.

Note 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.

/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.

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

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.

Caution 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.

/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.

Note The /address parameter is valid only on x86 architectures. It is not reliable and is rarely used.

/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 the NTSD debugger with the command line ntsd -g -G -x and with page heap enabled.

For details on NTSD, see Debugging Tools for NT-Based Operating Systems.

This option is useful for programs that are difficult to start from a command prompt and those that are started by other processes.

Note When using the /debug or /kdebug parameters, use the /p /disable parameters to turn off the page heap functions (not the /i -hpa parameters). Otherwise, entries read by the debugger are not deleted from the registry.

/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 details on NTSD as well as the kernel debuggers KD and WinDbg, see Debugging Tools for NT-Based Operating Systems.

/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, and earlier systems, 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.

Rate

Specifies is 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 length (in seconds) of the interval between the the start of the program and the start of the fault injection routines. The default is 5 (five seconds).

/leaks

Checks for heap leaks when a process ends.

Caution 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.