Gflags Syntax

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

Gflags 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 SizeStartSizeEnd] | [/address AddressStart AddressEnd] | [/dlls DLL [DLL...]]   [/debug | /kdebug] [/unaligned] [/decommit] [/notraces] [/fault Rate [TimeOut]] [/leaks] [/protect] [/no_sync] [/no_lock_checks]

Parameters

• Typing gflags without parameters opens the Gflags dialog box.

• Typing gflags /p without additional parameters displays a list of programs that have page heap verification enabled.

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

• Flag
  A three-letter abbreviation (FlagAbbr) or hexadecimal value (FlagHex) that represents a debugging feature. The abbreviations and hexadecimal values are listed in the Global Flags 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
  The name of an executable file (.exe or .dll), including the file name extension. For example, Notepad.exe or Mydll.dll. Note
  • The ImageFile name is case insensitive.

• /r[ Flag[ Flag...]]
  Registry. View and change systemwide debugging flags stored in the registry. These settings take effect when you restart the system and remain effective until you change them. Without flags, gflags /r displays the systemwide flags set in the registry.

• /k[ Flag[ Flag...]
  Kernel mode settings. View and change systemwide debugging flags for this session. These settings are effective immediately, but are lost when the system stops. The settings affect processes started after this command completes. Without flags, gflags /k displays systemwide flags set for the current session.

• /i ImageFile[ Flag[ Flag...]]
  Image file settings. View and change 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. Without flags, gflags /iImageFile 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 Gflags Flag Reference (ust) flag must be set for the process. SizeInMB is a whole number representing the number of MB 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 or 8.

• /p
  Sets page heap verification options for a process. Without additional parameters, gflags /p displays a list of programs for which page heap verification is enabled. Page heap verification monitors dynamic heap memory operations, including allocations and frees, 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, operator new, operator new[], or their corresponding deallocation functions) or those that use custom operations that call the standard heap manager functions.

• /disable ImageFile
  Turns off page heap verification (standard or full) for the process. This command is equivalent to turning off the Gflags Flag Reference flag for a process (gflags /iImageFile-hpa). You can use the commands interchangeably.

• /enable ImageFile
  Turns on standard page heap verification for the process. Standard page heap verification examines fill patterns when a heap block is freed. This parameter sets the Gflags Flag Reference flag for the process in the registry. However, the /enable parameter sets standard heap verification for the process, unlike the /i parameter, which sets full heap verification for a process.

• /full
  Turns on full page heap verification for the process. Full page heap verification places an inaccessible page at the end of each allocation. The default is standard page heap verification, which places fill patterns at the end of an allocation and examines the patterns when a heap block is freed. Using this parameter is equivalent to turning on the Gflags Flag Reference flag for a process (gflags /iImageFile**+hpa**). You can use the commands interchangeably. Caution
  • Because full page heap verification uses at least one page of committed memory for each allocation, system resources can be quickly exhausted. For memory intensive processes, use the /size or /dlls parameter.

• /backwards
  Places the inaccessible page at the beginning of an allocation, rather than 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.

• /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 program. 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 runtime call stack. It enables standard page heap verification for all other allocations by the process. To use this feature, specify the address of a function that calls 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 "C" format, such as, 0xAABBCCDD. 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 page heap enabled and with the following options: ntsd -g -G -x.

  • -g ignores initial breakpoint in debugger

  • -G ignores final breakpoint at process termination

  • -x sets second-chance break on AV exceptions

  This option is used 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 page heap enabled and the following options: ntsd -g -G -d -x. It also redirects the debugger output to the kernel debugger if one is attached.

  • -g ignores initial breakpoint in debugger

  • -G ignores final breakpoint at process termination

  • -d sends all debugger output to kernel debugger via DbgPrint

  • -x sets second-chance break on AV exceptions

  This parameter is not commonly used. 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.

• /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, but cannot always end at a page boundary. This option is used to to detect off-by-one-byte errors. When this parameter is used with the /full parameter, the inaccessible page begins at 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. Note
  • Some programs, including Microsoft Internet Explorer, assume 8-byte alignment and do not operate correctly with the /unaligned parameter.

• /decommit
  This option is no longer valid. It is accepted, but ignored. In previous versions of page heap, the /decommit parameter placed a zone of reserved virtual space after an allocation instead of an inaccessible page. In this version, the /decommit optimization is always implemented in full page heap verification.

• /notraces
  Specifies that runtime 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 Rate[ TimeOut]
  Forces the program's memory allocations to fail at the specified rate and after the specified timeout. 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 is a decimal integer from 1 through 10000 representing the probability that an allocation will fail. TimeOut is the number of seconds of delay between 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.

• /p /?
  Displays help for page heap verification options in Gflags.

Global Flags Table

The following table lists the flags that Gflags changes, the hexadecimal value and abbreviation for each flag, and the destination (R for registry, K for kernel, I for image file) in which the flag is valid.

For a detailed description of each flag, see the Gflags Flag Reference.

Caution

• The symbolic name of each flag is provided for reference only. Because symbolic names change, they are not a reliable identifier of a global flag.

Important

• Pool tagging is permanently enabled in all versions of Windows Server 2003. On these systems, the Enable pool tagging check box on the Gflags dialog box is dimmed and commands to enable or disable pool tagging fail.

See Also

Concepts

Gflags.exe
Gflags Remarks
Gflags UI
Gflags Examples
Gflags Flag Reference
Alphabetical List of Tools
Windiff Overview
Remote Overview
Poolmon Overview
Msizap Overview
Msicuu Overview
Memsnap Overview
Devcon Overview
Pviewer Overview
Exctrlst Overview
Devcon Overview
Apmstat Overview