Windows Tools

Gflags Examples
Overview | Notes | Syntax | UI | Examples | Flags | Related Tools Run Tool Open Command Prompt
Basic Example 1: Display debugging settings.

Example 2: Set a flag by using a flag abbreviation.

Example 3: Set a flag by using its hexadecimal value.

Example 4: Set multiple flags.

Example 5: Clear a flag.

Example 6: Clear all flags.

Example 7: Clear all flags for an image file.
Advanced Example 8: Change the maximum trace stack size.

Example 9: Detect a memory pool leak.

Example 10: Detect a heap memory leak in a process.

Example 1: Display debugging settings

The following command displays the current value of the system-level GlobalFlag registry entry (HKLM\System\CurrentControlSet\Control\Session Manager\GlobalFlag). It uses the /r parameter to specify the system-level registry entry.

gflags /r

In response, Gflags displays a single hexadecimal value representing the sum of all flags set and a list of the flags set.

Current Boot Registry Settings are: 40001400
	ptg - Enable pool tagging
	ust - Create user mode stack trace database
	bhd - Enable bad handles detection

In this example, the results show that there are three tags set, with a combined value of 0x40001400.

Remember that the value in the registry might not be the current value. Changes to the registry are not effective until the system is restarted.

You can use similar commands to display the debugging values for the current session, known as kernel mode, and debugging values for a particular image file.

The following command displays the debugging values for the current session. It uses the /k parameter to indicate kernel mode.

gflags /k

The following command displays the debugging values set in the registry for Notepad.exe. This value is stored in a GlobalFlag registry entry located in the program-specific subkey, HKLM\System\CurrentControlSet\Control\Session Manager\Image File Execution Options\Notepad.exe. It uses the /i parameter to indicate image file mode and specifies the image file.

gflags /i notepad.exe

Remember that the value in the registry might not be the current value. Changes to the registry are not effective until the system is restarted.

Example 2: Set a flag by using a flag abbreviation

The following command sets the Show loader snaps flag in the GlobalFlag registry entry for the Notepad.exe image file. Show loader snaps takes snapshots of the load process, capturing in detail the loading and unloading of executable images and their supporting library modules.

The command uses the /i parameter to indicate image file mode and specifies the name of the image file, Notepad.exe. To identify the flag, the command uses sls, the abbrevation for Show loader snaps and it precedes the abbreviation with a plus sign (+) to indicate that the flag is set. Without the plus sign, the command has no effect.

gflags /i notepad.exe +sls

In response, Gflags displays the current flags for Notepad.exe. The display indicates that the command is successful. The Show loader snaps flag is enabled for all new instances of the Notepad.exe process.


Current Registry Settings for notepad.exe executable are: 00000002
	sls - Show Loader Snaps

Example 3: Set a flag by using its hexadecimal value

The following command sets the Enable page heap flag in the systemwide GlobalFlag registry entry. Enable page heap adds a guard page and other tracking features to each heap allocation.

The command uses the /r parameter to indicate system registry mode. To identify the flag, the command uses 2000000, which represents 0x2000000, the hexadecimal value for Enable page heap.

Although the command sets a flag, it omits the plus sign. When using hexadecimal values, the sign is optional and add (+) is the default.

gflags /r 2000000

In response, Gflags displays the current value of GlobalFlag. The display indicates that the command is successful. The Enable page heap flag is set when you restart the system.


Current Boot Registry Settings are: 02000000
	hpa - Enable page heap

Example 4: Set multiple flags

The following command sets the following three debugging flags for the current session.

This command uses the /k parameter to specify kernel mode (session only). It sets the value for kernel mode to E0 (0xE0), the sum of the hexadecimal values of the flags.

gflags /k e0

In response, Gflags displays the current value of GlobalFlag. The display indicates that the command is successful and that the correct three flags are, indeed, set.


Current Running Kernel Settings are: 000000e0
	hfc - Enable heap free checking
	hpc - Enable heap parameter checking
	hvc - Enable heap validation on call

Please note that each of the following commands have the same effect as the command used in this example and can be used interchangeably.

gflags /k +20 +40 +80

gflags /k +E0

gflags /k +hfc +hpc +hvc

Flags set in kernel mode are effective immediately and remain effective until the system stops.

Example 5: Clear a flag

The following command clears the Enable page heap flag from the systemwide GlobalFlag registry entry. The command uses the /r parameter to indicate the systemwide registry and hpa, the abbreviation for the Enable page heap flag. The minus sign (-) specifies that the flag is to be cleared.

gflags /r -hpa

In response, Gflags displays the current value of GlobalFlag. The display indicates that the command is successful and that there are no longer any flags set in the registry value.

Current Boot Registry Settings are: 00000000

Please note that the following command, which uses the hexadecimal value of the Enable page heap flag, has the same effect as the command used in this example and can be used interchangeably:

gflags /r -02000000

Example 6: Clear all flags

There are two different ways to clear all flags set for a particular debugging mode:

Notes

Clear the current flags

The following command uses the first method for clearing flags. It clears the current value of GlobalFlag by clearing the flags set. In this example, the current value is 0xE0.

gflags /r -E0

In response, Gflags displays the current value of GlobalFlag. The display indicates that the command is successful and that there are no longer any flags set in the registry value.

Current Boot Registry Settings are: 00000000

Please note that the following commands have the same effect as the command used in this example and can be used interchangeably:

gflags /r -20 -40 -80

gflags /r -hfc -hpc -hvc

Clear all flags

The following command uses the second method for clearing flags. It clears all possible values set for GlobalFlag.

gflags /r -ffffffff

In response, Gflags displays the current value of GlobalFlag. The display indicates that the command is successful and that there are no longer any flags set in the registry value.

Current Boot Registry Settings are: 00000000

Note

Finally, the following example demonstrates that the intuitive method of clearing all flags does not work.

The following command sets the value of the systemwide GlobalFlag registry entry to 0. In this example, the current value of GlobalFlag is 0xE0.

gflags /r 0

In response, Gflags displays the value of GlobalFlag after the command completes:


Current Boot Registry Settings are: 000000e0
	hfc - Enable heap free checking
	hpc - Enable heap parameter checking
	hvc - Enable heap validation on call

The command has no effect because it adds the value 0 to the current value of GlobalFlag.

Example 7: Clear all flags for an image file

The following command clears all flags and image debugger options for an image file. The command adds high-values (0xFFFFFFFF) to the current flag value. Gflags responds by deleting the GlobalFlag entry for the image file, thereby deleting all of the values it stores.

This method does not clear flags set in the systemwide registry entry or in kernel mode.

gflags /i notepad.exe ffffffff

In response, Gflags displays a message indicating that there are no flags set for the image file:

No Registry Settings for notepad.exe executable

To determine which image files have flags set, use Regfind, a tool included in the Windows 2000 Server Resource Kit, to search the registry subkeys in the Image file Execution Options subkey.

The following command searches for GlobalFlag in the path specified by the -p parameter. The -n parameter directs Regfind to search for the names of subkeys and entries, instead of the data stored in the entry.

regfind GlobalFlag -n -p "HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options"

In response, Regfind displays all image file subkeys with GlobalFlag registry entries. It also displays the value of the entry. Because the gflags command deleted the entry for Notepad.exe, it does not appear in the Regfind list.


HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execu
tion Options
	f32main.exe
		GlobalFlag = 0x000000c0
	dgsetup.exe
		GlobalFlag = 0x00000080

Note

Example 8: Change the maximum trace stack size

The following command increases the maximum size of the stack trace to 24 items. This value is set in the systemwide GlobalFlag registry entry. The default value is 16 (0x10).

The command uses the /r parameter to indicate the systemwide GlobalFlag registry entry. It uses the maxdepth parameter to change the maximum stack trace size and the value 24 to indicate the desired size in decimal units. (Hexadecimal units are not valid.)

gflags /r maxdepth 24

In response, Gflags displays the current value of the systemwide GlobalFlag registry entry. Gflags does not report the success of the command or display the current stack trace size.


Current Boot Registry Settings are: 02000000
	hpa - Enable page heap

To display the stack trace size, use registry APIs, Regedit.exe, or Reg, to check the value of the MaxStackTraceDepth registry entry (HKLM\System\CurrentControlSet\Control\Session Manager\MaxStackTraceDepth).

The following command uses Reg.exe to query the value of MaxStackTraceDepth:

reg query "hklm\system\currentcontrolset\control\session manager" /v maxstacktracedepth

In response, Reg.exe returns the value of MaxStackTraceDepth, which confirms that the new value, 24 (0x18), was set. This value becomes effective when you restart the system.


! REG.EXE VERSION 2.0

HKEY_LOCAL_MACHINE\system\currentcontrolset\control\session manager
	maxstacktracedepth  REG_DWORD	 0x18

Notes

Example 9: Detect a memory leak

The following example uses Gflags to set the Enable pool tagging flag in the registry entry for the system. Then, it uses Poolmon, a Windows Support Tool, to display the size of the memory pools. Poolmon uses pool tags to monitor the bytes in the paged and nonpaged memory pools. By running Poolmon periodically, you can identify pools that expand continuously over time. This pattern often indicates a memory leak.

Note

  1. Set the Enable pool tagging flag in the systemwide registry entry.

  2. Use one of the following methods. These methods have the same effect and can be used interchangeably.

  3. Restart the computer to make the registry change effective.

  4. Run Poolmon periodically by using the following command. In this command, the /b parameter sorts the pools in descending size order.

  5. poolmon /b

    In response, Poolmon displays a table of memory pool size, including the number of allocs and frees, and the amount of memory remaining in the pool (in the Bytes column).

    Memory: 16224K Avail: 4564K PageFlts: 31 InRam Krnl: 684K P: 680K
 Commit: 24140K Limit: 24952K Peak: 24932K  Pool N: 744K P: 2180K

 Tag  Type	Allocs		Frees		 Diff   Bytes	Per Alloc
-----------------------------------------------------------------------

 CM   Paged	1283 (   0)	1002 (   0)	281 1377312 (	 0) 4901
Strg  Paged   10385 (  10)	6658 (   4)   3727  317952 (   512)   85
 Fat  Paged	6662 (   8)	4971 (   6)   1691  174560 (   128)  103
MmSt  Paged	 614 (   0)	 441 (   0)	173   83456 (	 0)  482

    If the value of Bytes in a pool expands continuously for no obvious reason, there might be a memory leak in that pool.

  6. Turn off Enable pool tagging.

  7. The following command line uses the flag abbreviation method, but you can identify the flag by its hexadecimal value or use the Global Flags dialog box:

    gflags /r -ptg

  8. Restart the system to make the registry change effective.

Note

Example 10: Detect a heap memory leak in a process

This example uses Gflags and Umdh.exe (User Mode Dump Heap), a tool available from Microsoft Product Support Services (http://go.microsoft.com/fwlink/?LinkId=1679).

To detect a leak in heap memory in Notepad.exe:

  1. Set the Create user mode stack trace database flag for the Notepad.exe image file.

  2. The following command uses Gflags to set the Create user mode stack trace database flag. It uses the /i parameter to identify the image file and the ust abbreviation for the flag.

    gflags /i Notepad.exe +ust

    As a result of this command, a user mode stack trace is created for all new instances of the Notepad process.

  3. Set the symbol file path.

  4. The following command creates an environment variable that stores the path to the directory of symbol files:

    set _NT_SYMBOL_PATH=C:\Windows\symbols

  5. Start Notepad.
  6. Find the process identifier (PID) of the Notepad process.

  7. You can find the PID of any running process from Task Manager or Tasklist.exe, a tool included in Windows XP Professional. In this example, the Notepad PID is 1228.

  8. Run Umdh.exe

  9. The following command runs Umdh.exe. It uses the -p: parameter to specify the PID which, in this example, is 1228. It uses the /f: parameter to specify the name and location of the output file for the heap dump, Notepad.dmp.

    umdh -p:1228 -f:notepad.dmp

    In response, Umdh writes a complete dump of all active heaps to the notepad.dmp file.