Partager via

Gflags Syntax

  • Article

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

Gflags Syntax

Art Imagegflags[/r [Flag [Flag...]] | /k [Flag [Flag...]] | **/i **ImageFile [Flag [Flag...]] | **/i **ImageFile **/tracedb **SizeInMB | /?]

Art Imagegflags /p [/disable ImageFile] [/?]

Art Imagegflags /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.
Description Symbolic name Hexadecimal Value Abbreviation Destination

Gflags Flag Reference

FLG_DISABLE_DBGPRINT

0x08000000

ddp

R,K

Gflags Flag Reference

FLG_KERNEL_STACK_TRACE_DB

0x2000

kst

R

Gflags Flag Reference

FLG_USER_STACK_TRACE_DB

0x1000

ust

R,K,I

Gflags Flag Reference

FLG_DEBUG_INITIAL_COMMAND

0x4

dic

R,K

Gflags Flag Reference

FLG_DEBUG_INITIAL_COMMAND_EX

0x04000000

dwl

R, K

Gflags Flag Reference

FLG_HEAP_DISABLE_COALESCING

0x00200000

dhc

R,K,I

Gflags Flag Reference

FLG_DISABLE_PAGE_KERNEL_STACKS

0x80000

dps

R,K

Gflags Flag Reference

FLG_DISABLE_PROTDLLS

0x80000000

dpd

R,K,I

Gflags Flag Reference

FLG_DISABLE_STACK_EXTENSION

0x10000

dse

I

Gflags Flag Reference

FLG_CRITSEC_EVENT_CREATION

0x10000000

cse

R,K,I

Gflags Flag Reference

FLG_APPLICATION_VERIFIER

0x100

vrf

R,K,I

Gflags Flag Reference

FLG_ENABLE_HANDLE_EXCEPTIONS

0x40000000

bhd

R,K

Gflags Flag Reference

FLG_ENABLE_CLOSE_EXCEPTIONS

0x00400000

ece

R,K

Gflags Flag Reference

FLG_ENABLE_CSRDEBUG

0x20000

d32

R,K

Gflags Flag Reference

FLG_ENABLE_EXCEPTION_LOGGING

0x00800000

eel

R,K

Gflags Flag Reference

FLG_HEAP_ENABLE_FREE_CHECK

0x20

hfc

R,K,I

Gflags Flag Reference

FLG_HEAP_VALIDATE_PARAMETERS

0x40

hpc

R,K,I

Gflags Flag Reference

FLG_HEAP_ENABLE_TAGGING

0x800

htg

R,K,I

Gflags Flag Reference

FLG_HEAP_ENABLE_TAG_BY_DLL

0x8000

htd

R,K,I

Gflags Flag Reference

FLG_HEAP_ENABLE_TAIL_CHECK

0x10

htc

R,K,I

Gflags Flag Reference

FLG_HEAP_VALIDATE_ALL

0x80

hvc

R,K,I

Gflags Flag Reference

FLG_ENABLE_KDEBUG_SYMBOL_LOAD

0x40000

ksl

R,K

Gflags Flag Reference

FLG_ENABLE_HANDLE_TYPE_TAGGING

0x01000000

eot

R,K

Gflags Flag Reference

FLG_HEAP_PAGE_ALLOCS

0x02000000

hpa

R,K,I

Gflags Flag Reference (Windows 2000 and Windows XP only)

FLG_POOL_ENABLE_TAGGING

0x400

ptg

R

Gflags Flag Reference

FLG_ENABLE_SYSTEM_CRIT_BREAKS

0x100000

scb

R, K, I

Gflags Flag Reference

FLG_LDR_TOP_DOWN

0x20000000

ltd

R, K, I

Gflags Flag Reference

FLG_MAINTAIN_OBJECT_TYPELIST

0x4000

otl

R,K

Gflags Flag Reference

FLG_SHOW_LDR_SNAPS

0x2

sls

R,K,I

Gflags Flag Reference

FLG_STOP_ON_EXCEPTION

0x1

soe

R,K,I

Gflags Flag Reference

FLG_STOP_ON_HUNG_GUI

0x8

shg

K

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