Gflags Examples
Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2
Gflags Examples
Example 1: Display flags
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.
Enable pool tagging (ptg) = 0x400
Create user mode stack trace database (ust) = 0x1000
Enable bad handles detection (bhd) = 0x40000000
Remember that the value in the registry might not be the current value. Changes to the registry are not effective until the process 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 process 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:
Enable heap free checking (hfc, 0x20)
Enable heap parameter checking (hpc, 0x40)
Enable heap validation on call (hvc, 0x80)
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 has 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:
Clear the current flags.
Clear all flags.
Note
- The methods demonstrated by this example clear flags only. They do not reset the maximum stack trace size or kernel special pool tag to the default values.
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
- Type this command into Notepad, then save the file as ClearFlag.bat. Thereafter, to clear all flags, just type
ClearFlag.
Finally, the following example demonstrates that the intuitive method of clearing all flags does not work.
The following command should set the value of the systemwide GlobalFlag registry entry to 0 intuitively but it does not. 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 the query operation of Reg.exe, a tool included in %windir%\system32, to search the registry subkeys in the Image file Execution Options subkey.
The following command searches for GlobalFlag in the specified path. The /v parameter directs Reg query to search for the value GlobalFlag. The /s parameter specifies to search all subkeys and values recursively.
reg query "HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options" /v GlobalFlag /s
In response, Reg query 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 Reg query list.
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execu
tion Options
f32main.exe
GlobalFlag = 0x000000c0
dgsetup.exe
GlobalFlag = 0x00000080
Note
- Type the reg query command into Notepad, then save the file as Images.bat. Thereafter, to find image files for which flags have been set, just type
Images.
Example 8: Enlarge the user mode stack trace database
The following command increases the maximum size of the user mode stack trace database for the MyApp.exe process from 8 MB to 24 MB.
The command uses the /i parameter to specify the image file. It uses the /tracedb parameter to set the maximum stack trace database size and the value 24 to indicate the desired MB size in decimal units. (Hexadecimal units are not valid.)
gflags /i MyApp.exe /tracedb 24
As the following error message indicates, this command fails because the "Create user mode stack trace database" (+ust) flag is not set for the process. You cannot set the size of a trace database until you create one.
Failed to set the trace database size for `MyApp.exe'
The user mode stack trace database flag (+ust) must be enabled before setting /tracedb.
The following commands fix the error. The first command creates a trace database for MyApp.exe and the second command sets the maximum size of the trace database to 24 MB. These commands cannot be combined into a single command. The listing below shows the commands and the success message from Gflags.
gflags /i MyApp.exe +ust
Current Registry Settings for MyApp.exe executable are: 00001000
ust - Create user mode stack trace database
gflags /i MyApp.exe /tracedb 24
Trace database size for `MyApp.exe' set to 24 Mb.
Gflags can change the size of the user mode stack trace database, but it does not display it. To display the trace database size, use registry APIs, Regedit.exe, or Reg, to check the value of the StackTraceDatabaseSizeInMB registry entry (HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\StackTraceDatabaseSizeInMB).
The following command uses Reg.exe to query the value of StackTraceDatabaseSizeInMB:
reg query "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\MyApp.exe" /v StackTraceDatabaseSizeInMB
In response, Reg.exe returns the value of StackTraceDatabaseSizeInMB, which confirms that the new value, 24 (0x18), was set. This value becomes effective when you restart the MyApp.exe.
! REG.EXE VERSION 3.0
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execu
tion Options\MyApp.exe
StackTraceDatabaseSizeInMB REG_DWORD 0x18
Notes
Type the reg query command into Notepad, then save the file as TraceDb.bat. Thereafter, to display the value of StackTraceDatabaseSizeInMB, just type
TraceDb.To see the registry locations of values set by Gflags, see Gflags Remarks.
Example 9: Detect a pool 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 Overview, 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.
Notes
Pool tagging is permanently enabled on 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.
If pool tagging is not enabled, Poolmon fails and diplays the following message: "Query pooltags Failed c0000002."
Set the Enable pool tagging flag in the systemwide registry entry.
Use one of the following methods. These methods have the same effect and can be used interchangeably.
In the Gflags dialog box, click the Registry button, click the Enable pool tagging check box, and then click Apply.
At the command line, use the /r parameter to specify the systemwide registry entry, and the ptg abbreviation to specify the flag.
gflags /r +ptgAt the command line, use the /r parameter to specify the systemwide registry entry, and the 0x400 hexadecimal value to specify the flag. The plus sign (+) is optional in this format.
gflags /r +400
Restart the computer to make the registry change effective.
Run Poolmon periodically by using the following command. In this command, the /b parameter sorts the pools in descending size order.
poolmon /bIn 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) 482If the value of Bytes in a pool expands continuously for no obvious reason, there might be a memory leak in that pool.
Turn off Enable pool tagging.
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 -ptgRestart the system to make the registry change effective.
Note
Use the append symbol (>>) to redirect the Poolmon output to a log file. Later, you can examine the log file for pool size trends. For example:
poolmon.exe /b >> poolmon.log
Example 10: Get a complete dump of active heaps in a process
This example uses Gflags and Umdh.exe (User Mode Dump Heap), a tool available from Microsoft Product Support Services.
To detect a leak in heap memory in Notepad.exe:
Set the Create user mode stack trace database flag for the Notepad.exe image file.
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 +ustAs a result of this command, a user mode stack trace is created for all new instances of the Notepad process.
Set the symbol file path.
The following command creates an environment variable that stores the path to the directory of symbol files:
set _NT_SYMBOL_PATH=C:\Windows\symbolsStart Notepad.
Find the process identifier (PID) of the Notepad process.
You can find the PID of any running process from Task Manager or Tasklist, a tool included in Windows XP Professional and Windows Server 2003 operating systems. In this example, the Notepad PID is 1228.
Run Umdh.exe
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.dmpIn response, Umdh writes a complete dump of all active heaps to the Notepad.dmp file.
Example 11: Enable page heap verification
The following command enables standard page heap verification for the MyApp.exe program.
gflags /p /enable myapp.exe
The following commands enable full page heap verification for the MyApp.exe program. Although these commands create different settings in the registry, they are all functionally equivalent to selecting the Enable page heap check box for the MyApp.exe image file in the Gflags dialog box. These methods can be used interchangeably.
gflags /p /enable myapp.exe /fullgflags /i myapp.exe +hpagflags /i myapp.exe +02000000
The following commands disable full or standard page heap verification for the Myapp.exe program, regardless of the command or dialog box method used to enable page heap verification.
gflags /p /disable myapp.exegflags /i myapp.exe -hpagflags /i myapp.exe -02000000
Note
- When using the /debug or /kdebug parameters, use the /p /disable parameters to turn off the page heap verification (not the /i -hpa parameters). Otherwise, entries read by the debugger are not deleted from the registry.
Example 12: Use page heap verification to find a bug
This series of commands demonstrates how to use the page heap verification features of Gflags and the Windows NT Symbolic Debugger (NTSD) to detect an error in heap memory use. In this example, the programmer suspects that a fictitious application, Pheap-buggy.exe, has a heap error, and proceeds through a series of tests to identify the error.
Step 1: Enable standard page heap verification
The following command enables standard page heap verification for Pheap-buggy.exe:
gflags /p /enable pheap-buggy.exe
Step 2: Verify that page heap is enabled
The following command lists the programs on the system for which page heap verification is enabled:
gflags /p
In response, Gflags displays the following list of programs. In this display, traces indicates standard page heap verification and full traces indicates full page heap verification. In this case, Pheap-buggy.exe is listed with traces, indicating that standard page heap verification is enabled, as intended.
pheap-buggy.exe: page heap enabled with flags (traces )
Step 3: Run the debugger
The following command runs the CorruptAfterEnd function of Pheap-buggy.exe in NTSD with the -g (ignore initial breakpoint) and -x (set second-chance break on access violation exceptions) parameters set:
ntsd -g -x pheap-buggy /CorruptAfterEnd
When the application fails, NTSD generates the following display, which indicates that it detected an error in Pheap-buggy.exe:
===========================================================
VERIFIER STOP 00000008: pid 0xAA0: corrupted suffix pattern
00C81000 : Heap handle
00D81EB0 : Heap block
00000100 : Block size
00000000 :
===========================================================
Break instruction exception - code 80000003 (first chance)
eax=00000000 ebx=00d81eb0 ecx=77f7e257 edx=0006fa18 esi=00000008 edi=00c81000
eip=77f7e098 esp=0006fc48 ebp=0006fc5c iopl=0 nv up ei pl zr na po nc
cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000 efl=00000246
ntdll!DbgBreakPoint:
77f7e098 cc int 3
The header information includes the address of the heap with the corrupted block (00C81000 : Heap handle), the address of the corrupted block (00D81EB0 : Heap block) and the size of the allocation (00000100 : Block size).
The "corrupted suffix pattern" message indicates that the application violated the data integrity pattern that Gflags inserted after the end of the Pheap-buggy.exe heap allocation.
Step 4: Display the call stack
The next step is to use the addresses detected to locate the function that caused the error. The next two commands turn on line number dumping in the debugger and display the call stack with line numbers.
C:\>.linesLine number information will be loaded
C:\>kb
ChildEBP RetAddr Args to Child
WARNING: Stack unwind information not available. Following frames may be wrong.
0006fc5c 77f9e6dd 00000008 77f9e3e8 00c81000 ntdll!DbgBreakPoint
0006fcd8 77f9f3c8 00c81000 00000004 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x2879
0006fcfc 77f9f5bb 00c81000 01001002 00000010 ntdll!RtlpNtEnumerateSubKey+0x3564
0006fd4c 77fa261e 00c80000 01001002 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x3757
0006fdc0 77fc0dc2 00c80000 01001002 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x67ba
0006fe78 77fbd87b 00c80000 01001002 00d81eb0 ntdll!RtlSizeHeap+0x16a8
0006ff24 010013a4 00c80000 01001002 00d81eb0 ntdll!RtlFreeHeap+0x69
0006ff3c 01001450 00000000 00000001 0006ffc0 pheap-buggy!TestCorruptAfterEnd+0x2b [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 185]
0006ff4c 0100157f 00000002 00c65a68 00c631d8 pheap-buggy!main+0xa9 [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 69]
0006ffc0 77de43fe 00000000 00000001 7ffdf000 pheap-buggy!mainCRTStartup+0xe3 [crtexe.c @ 349]
0006fff0 00000000 0100149c 00000000 78746341 kernel32!DosPathToSessionPathA+0x204
The debugger displays the call stack for Pheap-buggy.exe with line numbers. The call stack display shows that the error occurred when the TestCorruptAfterEnd function in Pheap-buggy.exe tried to free an allocation at 0x00c80000 by calling HeapFree, a redirect to RtlFreeHeap.
The most likely cause of this error is that the program wrote past the end of the buffer that it allocated in this function.
Step 5: Enable full page heap verification
Unlike standard mode, full page heap verification can catch the misuse of this heap buffer as soon as it occurs. The following command enables full page heap verification for Pheap-buggy.exe:
gflags /p /enable pheap-buggy.exe /full
Step 6: Verify that full page heap is enabled
The following command lists the programs on the system for which page heap verification is enabled:
gflags /p
In response, Gflags displays the following list of programs. In this display, traces indicates standard page heap verification and full traces indicates full page heap verification. In this case, Pheap-buggy.exe is listed with full traces, indicating that full page heap verification is enabled, as intended.
pheap-buggy.exe: page heap enabled with flags (full traces )
Step 7: Run the debugger again
The following command runs the CorruptAfterEnd function of Pheap-buggy.exe in the NTSD debugger with the -g (ignore initial breakpoint) and -x (set second-chance break on access violation exceptions) parameters set:
ntsd -g -x pheap-buggy /CorruptAfterEnd
When the application fails, NTSD generates the following display, which indicates that it detected an error in Pheap-buggy.exe:
Page heap: process 0x5BC created heap @ 00880000 (00980000, flags 0x3)
ModLoad: 77db0000 77e8c000 kernel32.dll
ModLoad: 78000000 78046000 MSVCRT.dll
Page heap: process 0x5BC created heap @ 00B60000 (00C60000, flags 0x3)
Page heap: process 0x5BC created heap @ 00C80000 (00D80000, flags 0x3)
Access violation - code c0000005 (first chance)
Access violation - code c0000005 (!!! second chance !!!)
eax=00c86f00 ebx=00000000 ecx=77fbd80f edx=00c85000 esi=00c80000 edi=00c16fd0
eip=01001398 esp=0006ff2c ebp=0006ff4c iopl=0 nv up ei pl nz na po nc
cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000 efl=00000206
pheap-buggy!TestCorruptAfterEnd+1f:
01001398 889801010000 mov [eax+0x101],bl ds:0023:00c87001=??
With full page heap verification enabled, the debugger breaks at an access violation. To find the precise location of the access violation, turn on line number dumping and display the call stack trace.
The numbered call stack trace appears as follows:
ChildEBP RetAddr Args to Child
0006ff3c 01001450 00000000 00000001 0006ffc0 pheap-buggy!TestCorruptAfterEnd+0x1f [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 184]
0006ff4c 0100157f 00000002 00c16fd0 00b70eb0 pheap-buggy!main+0xa9 [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 69]
0006ffc0 77de43fe 00000000 00000001 7ffdf000 pheap-buggy!mainCRTStartup+0xe3 [crtexe.c @ 349]
WARNING: Stack unwind information not available. Following frames may be wrong.
0006fff0 00000000 0100149c 00000000 78746341 kernel32!DosPathToSessionPathA+0x204
The stack trace shows that the problem occurs in line 184 of Pheap-buggy.exe ([d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 184]). Because full page heap verification is enabled, the call stack ends in the program code, not in a system DLL. As a result, the violation was caught where it happened, instead of when the heap block was freed.
Step 8: Locate the error in the code
A quick inspection reveals the source of the problem: The program tries to write to the 101st byte of a 100-byte buffer, a common off-by-one error.
*((PCHAR)Block + 0x100 + 1) = 0;
See Also
Concepts
Gflags.exe
Gflags Remarks
Gflags Syntax
Gflags UI
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