Debug Help Library

This overview describes the function set provided by the debug help library, DbgHelp. It contains a set a debugging support routines that allow you to work with executable images in the portable executable (PE) format. For a description of this format, download the specification from the following location: http://www.microsoft.com/hwdev/hardware/PECOFF.asp.

  • About DbgHelp
  • Using DbgHelp
  • DbgHelp Reference
Built on Thursday, May 02, 2002


About DbgHelp

The following topics describe symbol files and the functionality provided by the DbgHelp functions.

  • DbgHelp Versions
  • Symbol Files
  • Symbol Handling
  • Symbol Servers and Symbol Stores
  • Minidump Files
  • Updated Platform Support

Note that all DbgHelp functions are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.


DbgHelp Versions

The DbgHelp library is implemented by DbgHelp.dll. This DLL is included with Windows® 2000 and later. To use this DLL on earlier systems, such as Windows NT® 4.0, Windows Me, Windows 98, and Windows 95, you can distribute the DLL with your application. To obtain the latest version of DbgHelp.dll, go to http://www.microsoft.com/ddk/debugging and download Debugging Tools for Windows.

Each version of DbgHelp includes additional functionality. To ensure that the correct version of DbgHelp is available for your application, review the Requirements blocks of the functions it uses. For example, the following text indicates that the application that uses this function will run on Windows 2000 or Windows XP, but will not run on Windows NT 4.0 unless you install the latest DbgHelp.dll:

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.

Whereas the following text indicates that the application that uses this function will run on Windows XP, but will not run on Windows 2000 unless you install the latest DbgHelp.dll:

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 2000, Windows NT 4.0, and Windows 95/98/Me.

Released Versions

The following is a summary of the released versions of DbgHelp, in chronological order.

Version | Distribution Vehicle
5.0 | Windows 2000
1.0 | Debugging Tools for Windows 1.0
2.0 | Debugging Tools for Windows 2.0
3.0 | Debugging Tools for Windows 3.0
5.1 | Windows XP
4.0 | Debugging Tools for Windows 4.0
6.0 | Debugging Tools for Windows 6.0

Versions 4.0 and 5.1

The following functions were added after the initial release.

MiniDumpReadDumpStream
MiniDumpWriteDump
SymEnumSymbols
SymEnumTypes
SymFindFileInPath
SymFromAddr
SymFromName
SymGetTypeFromName
SymGetTypeInfo
SymSetContext

Version 6.0

The following functions were added to version 6.0.

EnumDirTree
SymAddSymbol
SymDeleteSymbol
SymEnumSymbolsForAddr
SymLoadModuleEx
SymSetParentWindow


Symbol Files

A symbol file contains the same debugging information that an executable file would contain. However, the information is stored in a debug (.dbg) file or a program database (.pdb), rather than the executable file. Therefore, you can install only the symbol files you will need during debugging. This reduces the file size of the executable, saving load time and disk storage.

Debuggers can determine whether an executable file or DLL contains debugging information by searching for the IMAGE_FILE_DEBUG_STRIPPED characteristic. If this characteristic is present, the debugging information exists in a symbol file.

To create a .dbg file, build your executable file with debugging information according to the directions for your build tools. Next, use the SplitSymbols function or the Rebase tool. The resulting .dbg file uses the PE format.

To create a .pdb file, build your executable file with debugging information according to the directions for your build tools.

The operating system dynamic-link libraries (DLL) have associated symbol (.dbg) files. These files are not installed during installation. To install the system symbol files, create a directory on your hard disk, and copy the files from your system installation compact disc (CD). The symbol files are located in the SUPPORT\DEBUG\I386\SYMBOLS directory tree.

To work with the symbolic debugging information contained in a symbol file, use the symbol handling functions.


Symbol Handling

The symbol handler functions give applications easy and portable access to the symbolic debugging information of an image. These functions should be used exclusively to ensure access to symbolic information. This is necessary because these functions isolate the application from the symbol format.

For more information, see the following topics:

  • Symbol Handler Initialization
  • Symbol Paths
  • Symbol Loading
  • Deferred Symbol Loading
  • Decorated Symbol Names
  • Finding Symbols
  • Symbol Handler Cleanup


Symbol Handler Initialization

The symbol handler is designed to track various sets of symbol files.

To initialize the symbol handler, call the SymInitialize function. The hProcess parameter can be a unique arbitrary number, a value returned from the GetCurrentProcess function, or the identifier of any running process. The fInvadeProcess parameter indicates whether the symbol handler should enumerate the modules loaded by the process and load symbols for each of its modules. If fInvadeProcess is TRUE, the hProcess parameter must be the value returned from GetCurrentProcess or the identifier of an existing process.

Using fInvadeProcess is a simple way to load all symbol files for a process. However, the symbol handler will not attempt to load symbols for modules subsequently loaded by the LoadLibrary function. You must use the SymLoadModule64 function in this case.


Symbol Paths

The library uses the symbol search path to locate debug symbols (.dbg file) for .dll, .exe, and .sys files by appending "\symbols" and "\dll" or "\exe" or "\sys" to the path. For example, the typical location of symbol files for .dll files is c:\mysymbols\symbols\dll. For .exe files, the location is c:\mysymbols\symbols\exe.

To specify where the symbol handler will search disk directories for symbol files, call the SymSetSearchPath function. Alternatively, you can specify a symbol search path in the UserSearchPath parameter of the SymInitialize function.

The UserSearchPath parameter in SymInitialize and the SearchPath parameter in SymSetSearchPath take a pointer to a null-terminated string that specifies a path, or series of paths separated by a semicolon. The symbol handler uses these paths to search for symbol files. If this parameter is specified as a non-null value, the symbol handler searches only the paths set by the application. If this parameter is NULL, the symbol handler first searches the current working directory of the application, then the system root directory (%windir%). If you set the _NT_SYMBOL_PATH or _NT_ALT_SYMBOL_PATH environment variable, the symbol handler searches for symbol files in the following order:

  1. The current working directory of the application.
  2. The _NT_SYMBOL_PATH environment variable.
  3. The _NT_ALT_SYMBOL_PATH environment variable.

To retrieve the search paths, call the SymGetSearchPath function.

The search path for program database (.pdb) files is different than the path for debug (.dbg) files. The algorithm is determined by the functionality of the symbol library. By default, Microsoft Visual C/C++ creates Microsoft format symbols, strips them from the image, and places them in a separate .pdb file. Typically, the .pdb file will be located in the directory that contains the executable image. Visual C/C++ embeds the absolute path to the .pdb file in the executable image. If the symbol handler cannot find the .pdb file in that location or if the .pdb file was moved to another directory, the symbol handler will locate the .pdb file using the search path described for .dbg files.


Symbol Loading

The symbol handler will load symbols when you call the SymInitialize function with the fInvadeProcess parameter set to TRUE or when you call the SymLoadModule64 function to specify a module. In either case, the symbol handler either loads the symbols or defers symbol loading until symbols are requested, depending on the options set by the SymSetOptions function.

The symbol handler can be used to retrieve symbolic information for any module; it does not need to be associated with a process specified in the SymInitialize call. To use an arbitrary module, specify the full path to the module image in the ImageName parameter. You can use a path to any executable module that has debugging information (.exe, .dll, .drv, .sys, .scr, .cpl, or .com). Use the BaseOfDll parameter to specify any load address, then symbol addresses will be based from that address.

It may not be necessary to keep a symbol module loaded through the duration of an application. To release the symbol module from the symbol handler's list of modules, use the SymUnloadModule64 function. This function releases the memory allocated for the symbol module. To use symbols for that module again, you must call the SymLoadModule64 function even if the symbol deferred load option is set.


Deferred Symbol Loading

To conserve time and memory when working with many symbol files, use the SymSetOptions function to set the deferred symbol loading (SYMOPT_DEFERRED_LOADS) option, then use the SymLoadModule64 or SymInitialize function to load symbols deferred for all modules. The symbol handler will list symbols that are available for the modules, but will not map the debug information into memory until it is requested. This is the preferred method to efficiently use debugging symbols. The following functions will load the deferred symbols:

  • SymEnumerateSymbols64
  • SymEnumSymbols
  • SymFunctionTableAccess64
  • SymFromAddr
  • SymFromName
  • SymGetSymFromAddr64
  • SymGetSymFromName64
  • SymGetSymPrev64
  • SymGetSymNext64


Decorated Symbol Names

A decorated symbol name includes characters that distinguish how the symbol has been declared. For __stdcall functions, names include the "@" character and a decimal number that specifies the number of bytes in its function parameters. For example, the decorated name of the LoadLibrary function is LoadLibrary@4. For C++ functions the name decoration is more complex and varies from compiler to compiler.

To retrieve the undecorated symbol name, use the UnDecorateSymbolName function. Alternatively, you can call the SymSetOptions function to request that the symbol handler always present symbols with undecorated names. You must set this option before loading the symbols because the symbol handler creates the symbol name tables at load time.


Finding Symbols

After a symbol file has been loaded into the symbol handler, an application can use the symbol locator functions to return symbol information for a specified address. These functions can also find a source code file name and line number location for an address.

Enumerating Symbol Files

To retrieve a list of all symbol files loaded by module name, call the SymEnumerateModules64 function. To retrieve a list of symbols for a given module, call the SymEnumSymbols function.

Retrieving Symbols by Address

To retrieve symbolic information for a specific address, use the SymFromAddr function. This function retrieves information and stores it in a SYMBOL_INFO structure. Because symbol names are variable in length, you must provide additional buffer space following the SYMBOL_INFO structure declaration. The following is an example using SymFromAddr:

DWORD dwAddr;
DWORD dwDisp;
BYTE  buffer[MAX_BUFFER_LENGTH];
PSYMBOL_INFO pSymbol = (PSYMBOL_INFO)buffer;

pSymbol->SizeOfStruct = sizeof(SYMBOL_INFO);
pSymbol->MaxNameLen = sizeof(buffer) - sizeof(SYMBOL_INFO) + 1;

if (SymFromAddr(hProcess, dwAddr, &dwDisp, pSymbol) == FALSE)
   return FALSE;

Note that hProcess is the handle to the process originally passed to the SymInitialize function, and dwAddress contains the address for which a symbol is to be located. The address does not need to be on a symbol boundary. If the address comes after the beginning of a symbol but before the end of the symbol (the beginning of the symbol plus the symbol size), the function will locate the symbol.

Retrieving Symbols by Symbol Name

To retrieve symbolic information in a SYMBOL_INFO structure for a specific module and symbol name, use the SymFromName function. If deferred symbol loading is set, SymFromName will attempt to load the symbol file for a module if it has not already been loaded. To specify a module name along with a symbol name, use the syntax Module!SymName. The "!" character delimits the module name from the symbol name. The following is an example using SymFromName:

BYTE szSymbolName[MAX_SYMBOLNAME_LENGTH];
BYTE buffer[MAX_BUFFER_LENGTH];
PIMAGEHLP_SYMBOL64 pSymbol = (PSYMBOL_INFO)buffer;

pSymbol->SizeOfStruct = sizeof(SYMBOL_INFO);
pSymbol->MaxNameLen = sizeof(buffer) - sizeof(SYMBOL_INFO) + 1;
if (SymFromName(hProcess, szSymbolName, pSymbol) == FALSE )
   return FALSE;

Note that hProcess is the handle to the process originally passed to SymInitialize, and szSymbolName is a null-terminated string that specifies the symbol name for which a symbol is to be located.

Retrieving Line Numbers by Address

To retrieve the source code location for a specific address, use the SymGetLineFromAddr64 function. This function fills an IMAGEHLP_LINE64 structure that includes the source file name and line number location referred to by the specified address. The following is an example using SymGetLineFromAddr64:

DWORD dwAddr;
DWORD dwDisp;
IMAGEHLP_LINE64 line;

SymSetOptions(SYMOPT_LOAD_LINES);
...
line.SizeOfStruct = sizeof(IMAGEHLP_LINE64);
if (SymGetLineFromAddr64(hProcess, dwAddr, &dwDisp, &line) == FALSE)
   return FALSE;

Note that hProcess is the handle to the process originally passed to SymInitialize, and dwAddress contains the address for which the source file name and line number should be located.

Retrieving Line Numbers by Symbol Name

To retrieve source code location for a specific symbol name, use the SymGetLineFromName64 function. This function is similar to SymGetSymFromName64, but retrieves an IMAGEHLP_LINE64 structure. To use SymGetLineFromAddr64 or SymGetLineFromName64, you must set the load lines option (SYMOPT_LOAD_LINES) using the SymSetOptions function. The following is an example using SymGetLineFromName64:

BYTE   szModuleName[MAX_PATH];
BYTE   szFileName[MAX_PATH];
DWORD  dwLine;
LONG   lDisp;
IMAGEHLP_LINE64 line;

SymSetOptions(SYMOPT_LOAD_LINES);
...
line.SizeOfStruct = sizeof(IMAGEHLP_LINE64);
if (SymGetLineFromName64(hProcess, szModuleName, szFileName, dwLine, &lDisp, &line) == FALSE)
   return FALSE;

Note that hProcess is the handle to the process originally passed to SymInitialize. Also, szModuleName contains the source module name, which can be NULL. The szFileName parameter contains the source file name, and dwLineNumber contains the line number for which the virtual address should be retrieved.


Symbol Handler Cleanup

To free all the memory used by the symbol handler for a process, use the SymCleanup function. This function enumerates all loaded modules, frees each module, and frees the memory allocated for the list of modules. After you call SymCleanup, you cannot use the process handle in the symbol handling functions until you call the SymInitialize function.


Symbol Servers and Symbol Stores

To set up symbols correctly for debugging can be a challenging task, particularly for kernel debugging. It often requires that you know the names and releases of all products on your computer. The debugger must be able to locate the symbol files that correspond to each product release and service pack. This can result in an extremely long symbol path consisting of a long list of directories.

To simplify these difficulties in coordinating symbol files, a symbol server can be used. A symbol server enables the debuggers to automatically retrieve the correct symbol files without product names, releases, or build numbers. Debugging Tools for Windows contains a symbol server called SymSrv.

The symbol server is activated by including a certain text string in the symbol path. Each time the debugger needs to load symbols for a newly loaded module, it calls the symbol server to locate the appropriate symbol files. The symbol server locates the files in a symbol store. This is a collection of symbol files, an index, and a tool that can be used by an administrator to add and delete files. The files are indexed according to unique parameters such as the time stamp and image size. Debugging Tools for Windows contains a symbol store tool called SymStore.

For more information, see:

  • Using SymSrv
  • Using Other Symbol Servers
  • Using SymStore
  • Using Other Symbol Stores
  • SymStore Command-Line Options


Using SymSrv

SymSrv (symsrv.dll) is a symbol server that is included in the Debugging Tools for Windows package.

SymSrv can deliver symbol files from a centralized symbol store. This store can contain any number of symbol files, corresponding to any number of programs or operating systems. The store can also contain binary files (this is useful when debugging minidump files).

The store can contain the actual symbol and binary files, or it can simply contain pointers to symbol files. If the store contains pointers, SymSrv will retrieve the actual files directly from their sources.

SymSrv can also be used to separate a large symbol store into a smaller subset that is appropriate for a specialized debugging task.

Finally, SymSrv can obtain symbol files from an HTTP or HTTPS source using the logon information provided by the operating system. SymSrv supports HTTPS sites protected by smartcards, certificates, and regular logins and passwords.

Setting the Symbol Path

To use this symbol server, symsrv.dll must be installed in the same directory as the debugger. The symbol path must be set in one of the following ways:

set _NT_SYMBOL_PATH = symsrv*ServerDLL*DownstreamStore*\\Server\Share

set _NT_SYMBOL_PATH = symsrv*ServerDLL*\\Server\Share

set _NT_SYMBOL_PATH = srv*DownstreamStore*\\Server\Share

set _NT_SYMBOL_PATH = srv*\\Server\Share

The following table describes elements of this syntax.

Field | Description
symsrv | This keyword must always appear first. It indicates to the debugger that this item is a symbol server, not just a normal symbol directory.
ServerDLL | Specifies the name of the symbol server DLL. If you are using the SymSrv symbol server, this will always be symsrv.dll.
srv | This is shorthand for symsrv*symsrv.dll.
DownstreamStore | Specifies a local directory or network share that will be used to cache individual symbol files. If DownstreamStore specifies a directory that does not exist, SymStore will attempt to create it.
\\Server\Share | Specifies the server and share of the symbol store.

The DownstreamStore parameter can be omitted, as shown in the first syntax example above. This parameter is required if you are accessing symbols from an HTTP or HTTPS site, or if you are using compressed files on your store.

If DownstreamStore is not included, the debugger will load all symbol files from the specified Server and Share.

If DownstreamStore is included, the debugger will first look for a symbol file in this location. If the symbol file is not found, the debugger will locate the symbol file from the specified Server and Share, and then cache a copy of this file in the downstream store. The file will be copied to a subdirectory in the tree under DownstreamStore which corresponds to its location in the tree under \\Server\Share.

The symbol server does not have to be the only entry in the symbol path. If the symbol path consists of multiple entries, the debugger checks each entry for the needed symbol files, in order (from left to right), regardless of whether a symbol server or an actual directory is named.

Here are some examples. To use SymSrv as the symbol server with a symbol store on \\mybuilds\mysymbols, set the following symbol path:

set _NT_SYMBOL_PATH= symsrv*symsrv.dll*\\mybuilds\mysymbols

To set the symbol path so that the debugger will copy symbol files from a symbol store on \\mybuilds\mysymbols to your local directory c:\localsymbols, use:

set _NT_SYMBOL_PATH=symsrv*symsrv.dll*c:\localsymbols*\\mybuilds\mysymbols

In addition, the symbol path may contain several directories or symbol servers, separated by semicolons. This allows you to locate symbols from multiple locations (or even multiple symbol servers). If a binary has a mismatched symbol file, the debugger cannot locate it using the symbol server because it checks only for the exact parameters. However, the debugger may find a mismatched symbol file with the correct name, using the traditional symbol path, and successfully load it. Even though the file is technically not the correct symbol file, it may provide useful information.

Compressed Files

SymSrv is compatible with symbol stores that contain compressed files, as long as this compression has been done with the compress.exe tool that is distributed with the Platform SDK. Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd_ or module2.db_). For details, see Using SymStore.

If the files on the store are compressed, you must use a downstream store. SymSrv will uncompress all files before caching them on the downstream store.

Deleting the Cache

If you are using a DownstreamStore as a cache, you can delete this directory at any time to save disk space.

It is possible to have a vast symbol store that includes symbol files for many different programs or Windows versions. If you upgrade the version of Windows used on your target computer, the cached symbol files will all match the earlier version. These cached files will not be of any further use, and therefore this might be a good time to delete the cache.

How SymSrv Locates Files

SymSrv creates a fully-qualified UNC path to the desired symbol file. This path begins with the path to the symbol store recorded in the _NT_SYMBOL_PATH environment variable. The SymbolServer routine is then used to identify the name of the desired file; this name is appended to the path as a directory name. Another directory name, consisting of the concatenation of the id, two, and three parameters passed to SymbolServer, is then appended; if any of these values are zero, they are omitted.

The resulting directory is searched for the symbol file, or a symbol store pointer file.

If this search is successful, the path is passed to the caller and TRUE is returned. If the file is not found, FALSE is returned.


Using Other Symbol Servers

If you wish to use a different method for your symbol search, you can provide your own symbol server DLL rather than using SymSrv.

Setting the Symbol Path

When implementing a symbol server other than SymSrv, the debugger's symbol path is set in the same way as with SymSrv. See Using SymSrv for an explanation of the symbol path syntax. The only change needed is to replace the string symsrv.dll with the name of your own symbol server DLL.

If you wish, you are free to use a different syntax within the parameters to indicate the use of different technologies such as UNC paths, SQL database identifiers, or Internet specifications.

Implementing Your Own Symbol Server

The central portion of the server is the code that communicates with DbgHelp to find the symbols. Every time DbgHelp needs to load symbols for a newly loaded module, it calls the symbol server to locate the appropriate symbol files. The symbol server locates each file according to unique parameters such as the time stamp or image size. The server returns a validated path to the requested file. To implement this, the server must export the SymbolServer function. The server should also support the SymbolServerSetOptions and SymbolServerGetOptions functions.

Furthermore, DbgHelp will call the SymbolServerClose function, if exported by the server.

You may not change the actual symbol file name returned by your symbol server. DbgHelp stores the name of a symbol file in multiple locations. Therefore, the server must return a file of the same name as that specified when the symbol was requested. This restriction is needed to assure that the symbol names displayed during symbol loading are the ones that the programmer will recognize.

Restrictions on Multiple Symbol Servers

DbgHelp supports the use of only one symbol server at a time, although it is possible to switch to another symbol server by changing the symbol path. This does not limit the symbol server from obtaining its symbol information from a single source: the server can support multiple source instances through the parameters passed to it when it is called. In other words, your symbol path can contain multiple instances of the same symbol server DLL, but not two different symbol server DLLs.

Installing Your Symbol Server

The details of your symbol server installation will depend on your situation. You may wish to set up an installation process that copies your symbol server DLL and sets the _NT_SYMBOL_PATH environment variable automatically.

Depending on the technology used in your server, you may also need to install or access the symbol data itself.


Using SymStore

SymStore (symstore.exe) is a tool for creating symbol stores. It is included in the Debugging Tools for Windows package.

SymStore stores symbols in a format that enables the debugger to look up the symbols based on the time stamp and size of the image (for a .dbg or executable file), or signature and age (for a .pdb file). The advantage of the symbol store over the traditional symbol storage format is that all symbols can be stored or referenced on the same server and retrieved by the debugger without any prior knowledge of which product contains the corresponding symbol.

Note that multiple versions of .pdb symbol files (for example, public and private versions) cannot be stored on the same server, because they each contain the same signature and age.

SymStore Transactions

Every call to SymStore is recorded as a transaction. There are two types of transactions: add and delete.

When the symbol store is created, a directory, called "000admin", is created under the root of the server. The 000admin directory contains one file for each transaction, as well as the log files server.txt and history.txt. The server.txt file contains a list of all transactions that are currently on the server. The history.txt file contains a chronological history of all transactions.

Each time SymStore stores or removes symbol files, a new transaction number is created. Then, a file, whose name is this transaction number, is created in 000admin. This file contains a list of all the files or pointers that have been added to the symbol store during this transaction. If a transaction is deleted, SymStore will read through its transaction file to determine which files and pointers it should delete.

The add and del options specify whether an add or delete transaction is to be performed. Including the /p option with an add operation specifies that a pointer is to be added; omitting the /p option specifies that the actual symbol file is to be added.

It is also possible to create the symbol store in two separate stages. In the first stage, you use SymStore with the /x option to create an index file. In the second stage, you use SymStore with the /y option to create the actual store of files or pointers from the information in the index file.

This can be a useful technique for a variety of reasons. For instance, this allows the symbol store to be easily recreated if the store is somehow lost, as long as the index file still exists. Or perhaps the computer containing the symbol files has a slow network connection to the computer on which the symbol store will be created. In this case, you can create the index file on the same machine as the symbol files, transfer the index file to the second machine, and then create the store on the second machine.

For a full listing of all SymStore parameters, see SymStore Command-Line Options.

Note SymStore does not support simultaneous transactions from multiple users. It is recommended that one user be designated "administrator" of the symbol store and be responsible for all add and del transactions.

Transaction Examples

Here are two examples of SymStore adding symbol pointers for build 2195 of Windows 2000 to \\foo\symsrv:

symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\foo\symsrv /t "Windows 2000" /v "Build 2195 x86 free" /c "Sample add"
symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\foo\symsrv /t "Windows 2000" /v "Build 2195 x86 checked" /c "Sample add"

In the following example, SymStore adds the actual symbol files for an application project in \\largeapp\appserver\bins to \\foo\symsrv:

symstore add /r /f \\largeapp\appserver\bins\*.* /s \\foo\symsrv /t "Large Application" /v "Build 432" /c "Sample add"

Here is an example of how an index file is used. First, SymStore creates an index file based on the collection of symbol files in \\largeapp\appserver\bins\. In this case, the index file is placed on a third computer, \\hubserver\hubshare. You use the /g option to specify that the file prefix "\\largeapp\appserver" might change in the future:

symstore add /r /p /g \\largeapp\appserver /f \\largeapp\appserver\bins\*.* /x \\hubserver\hubshare\myindex.txt

Now suppose you move all the symbol files off of the machine \\largeapp\appserver and put them on \\myarchive\appserver. You can then create the symbol store itself from the index file \\hubserver\hubshare\myindex.txt as follows:

symstore add /y \\hubserver\hubshare\myindex.txt /g \\myarchive\appserver /s \\foo\symsrv /p /t "Large Application" /v "Build 432" /c "Sample Add from Index"

Finally, here is an example of SymStore deleting a file added by a previous transaction. See the following section for an explanation of how to determine the transaction ID (in this case, 0000000096).

symstore del /i 0000000096 /s \\foo\symsrv

Compressed Files

SymStore can be used with compressed files in two different ways.

  1. Use SymStore with the /p option to store pointers to the symbol files. After SymStore finishes, compress the files that the pointers refer to.
  2. Use SymStore with the /x option to create an index file. After SymStore finishes, compress the files listed in the index file. Then use SymStore with the /y option (and, if you wish, the /p option) to store the files or pointers to the files in the symbol store. (SymStore will not need to uncompress the files to perform this operation.)

Your symbol server will be responsible for uncompressing the files when they are needed.

If you are using SymSrv as your symbol server, any compression should be done using the compress.exe tool that is distributed with the Platform SDK. Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd_ or module2.db_). For details, see Using SymSrv.

The server.txt and history.txt Files

When a transaction is added, several items of information are added to server.txt and history.txt for future lookup capability. The following is an example of a line in server.txt and history.txt for an add transaction:

0000000096,add,ptr,10/09/99,00:08:32,Windows NT 4.0 SP 4,x86 fre 1.156c-RTM-2,Added from \\mybuilds\symbols,

This is a comma-separated line. The fields are defined as follows.

Field | Description
0000000096 | Transaction ID number, as created by SymStore.
add | Type of transaction. This field can be either add or del.
ptr | Whether files or pointers were added. This field can be either file or ptr.
10/09/99 | Date when transaction occurred.
00:08:32 | Time when transaction started.
Windows NT | Product.
x86 fre | Version (optional).
Added from | Comment (optional)
Unused | (Reserved for later use.)

Here are some sample lines from the transaction file 0000000096. Each line records the directory and the location of the file or pointer that was added to the directory.

canon800.dbg\35d9fd51b000,\\mybuilds\symbols\sp4\dll\canon800.dbg
canonlbp.dbg\35d9fd521c000,\\mybuilds\symbols\sp4\dll\canonlbp.dbg
certadm.dbg\352bf2f48000,\\mybuilds\symbols\sp4\dll\certadm.dbg
certcli.dbg\352bf2f1b000,\\mybuilds\symbols\sp4\dll\certcli.dbg
certcrpt.dbg\352bf04911000,\\mybuilds\symbols\sp4\dll\certcrpt.dbg
certenc.dbg\352bf2f7f000,\\mybuilds\symbols\sp4\dll\certenc.dbg

If you use a del transaction to undo the original add transactions, these lines will be removed from server.txt, and the following line will be added to history.txt:

0000000105,del,0000000096

The fields for the delete transaction are defined as follows.

Field | Description
0000000105 | Transaction ID number, as created by SymStore.
del | Type of transaction. This field can be either add or del.
0000000096 | Transaction that was deleted.

Symbol Storage Format

SymStore uses the file system itself as a database. It creates a large tree of directories, with directory names based on such things as the symbol file time stamps, signatures, age, and other data.

For example, after several different acpi.dbg files have been added to the server, the directories could look like this:

Directory of \\mybuilds\symsrv\acpi.dbg
10/06/1999  05:46p      <DIR>          .
10/06/1999  05:46p      <DIR>          ..
10/04/1999  01:54p      <DIR>          37cdb03962040
10/04/1999  01:49p      <DIR>          37cdb04027740
10/04/1999  12:56p      <DIR>          37e3eb1c62060
10/04/1999  12:51p      <DIR>          37e3ebcc27760
10/04/1999  12:45p      <DIR>          37ed151662060
10/04/1999  12:39p      <DIR>          37ed15dd27760
10/04/1999  11:33a      <DIR>          37f03ce962020
10/04/1999  11:21a      <DIR>          37f03cf7277c0
10/06/1999  05:38p      <DIR>          37fa7f00277e0
10/06/1999  05:46p      <DIR>          37fa7f01620a0

In this example, the lookup path for the acpi.dbg symbol file might look something like this: \\mybuilds\symsrv\acpi.dbg\37cdb03962040.

Three files may exist inside the lookup directory:

  1. If the file was stored, then acpi.dbg will exist there.
  2. If a pointer was stored, then a file called file.ptr will exist and contain the path to the actual symbol file.
  3. A file called refs.ptr, which contains a list of all the current locations for acpi.dbg with this timestamp and image size that are currently added to the symbol store.

Displaying the directory listing of \\mybuilds\symsrv\acpi.dbg\37cdb03962040 gives the following:

10/04/1999  01:54p                  52 file.ptr
10/04/1999  01:54p                  67 refs.ptr

The file file.ptr contains the text string "\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg". Since there is no file called acpi.dbg in this directory, the debugger will try to find the file at \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg.

The contents of refs.ptr are used only by SymStore, not the debugger. This file contains a record of all transactions that have taken place in this directory. A sample line from refs.ptr might be:

0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg

This shows that a pointer to \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg was added with transaction "0000000026".

Some symbol files stay constant through various products or builds or a particular product. One example of this is the Windows 2000 file msvcrt.pdb. Doing a directory of \\mybuilds\symsrv\msvcrt.pdb shows that only two versions of msvcrt.pdb have been added to the symbols server:

Directory of \\mybuilds\symsrv\msvcrt.pdb
10/06/1999  05:37p      <DIR>          .
10/06/1999  05:37p      <DIR>          ..
10/04/1999  11:19a      <DIR>          37a8f40e2
10/06/1999  05:37p      <DIR>          37f2c2272

However, doing a directory of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2 shows that refs.ptr has several pointers in it.

Directory of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2
10/05/1999  02:50p              54     file.ptr
10/05/1999  02:50p           2,039     refs.ptr

The contents of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2\refs.ptr are the following:

0000000001,ptr,\\mybuilds\symbols\x86\2137\symbols\dll\msvcrt.pdb
0000000002,ptr,\\mybuilds\symbols\x86\2137.chk\symbols\dll\msvcrt.pdb
0000000003,ptr,\\mybuilds\symbols\x86\2138\symbols\dll\msvcrt.pdb
0000000004,ptr,\\mybuilds\symbols\x86\2138.chk\symbols\dll\msvcrt.pdb
0000000005,ptr,\\mybuilds\symbols\x86\2139\symbols\dll\msvcrt.pdb
0000000006,ptr,\\mybuilds\symbols\x86\2139.chk\symbols\dll\msvcrt.pdb
0000000007,ptr,\\mybuilds\symbols\x86\2140\symbols\dll\msvcrt.pdb
0000000008,ptr,\\mybuilds\symbols\x86\2140.chk\symbols\dll\msvcrt.pdb
0000000009,ptr,\\mybuilds\symbols\x86\2136\symbols\dll\msvcrt.pdb
0000000010,ptr,\\mybuilds\symbols\x86\2136.chk\symbols\dll\msvcrt.pdb
0000000011,ptr,\\mybuilds\symbols\x86\2135\symbols\dll\msvcrt.pdb
0000000012,ptr,\\mybuilds\symbols\x86\2135.chk\symbols\dll\msvcrt.pdb
0000000013,ptr,\\mybuilds\symbols\x86\2134\symbols\dll\msvcrt.pdb
0000000014,ptr,\\mybuilds\symbols\x86\2134.chk\symbols\dll\msvcrt.pdb
0000000015,ptr,\\mybuilds\symbols\x86\2133\symbols\dll\msvcrt.pdb
0000000016,ptr,\\mybuilds\symbols\x86\2133.chk\symbols\dll\msvcrt.pdb
0000000017,ptr,\\mybuilds\symbols\x86\2132\symbols\dll\msvcrt.pdb
0000000018,ptr,\\mybuilds\symbols\x86\2132.chk\symbols\dll\msvcrt.pdb
0000000019,ptr,\\mybuilds\symbols\x86\2131\symbols\dll\msvcrt.pdb
0000000020,ptr,\\mybuilds\symbols\x86\2131.chk\symbols\dll\msvcrt.pdb
0000000021,ptr,\\mybuilds\symbols\x86\2130\symbols\dll\msvcrt.pdb
0000000022,ptr,\\mybuilds\symbols\x86\2130.chk\symbols\dll\msvcrt.pdb
0000000023,ptr,\\mybuilds\symbols\x86\2129\symbols\dll\msvcrt.pdb
0000000024,ptr,\\mybuilds\symbols\x86\2129.chk\symbols\dll\msvcrt.pdb
0000000025,ptr,\\mybuilds\symbols\x86\2128\symbols\dll\msvcrt.pdb
0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\dll\msvcrt.pdb
0000000027,ptr,\\mybuilds\symbols\x86\2141\symbols\dll\msvcrt.pdb
0000000028,ptr,\\mybuilds\symbols\x86\2141.chk\symbols\dll\msvcrt.pdb
0000000029,ptr,\\mybuilds\symbols\x86\2142\symbols\dll\msvcrt.pdb
0000000030,ptr,\\mybuilds\symbols\x86\2142.chk\symbols\dll\msvcrt.pdb

This shows that the same msvcrt.pdb was used for multiple builds of symbols for Windows 2000 stored on \\mybuilds\symsrv.

Here is an example of a directory that contains a mixture of file and pointer additions:

Directory of E:\symsrv\dbghelp.dbg\38039ff439000
10/12/1999  01:54p         141,232     dbghelp.dbg
10/13/1999  04:57p              49     file.ptr
10/13/1999  04:57p             306     refs.ptr

In this case, refs.ptr has the following contents:

0000000043,file,e:\binaries\symbols\retail\dll\dbghelp.dbg
0000000044,file,f:\binaries\symbols\retail\dll\dbghelp.dbg
0000000045,file,g:\binaries\symbols\retail\dll\dbghelp.dbg
0000000046,ptr,\\foo\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg

Thus, transactions 43, 44, and 45 added the same file to the server, and transactions 46 and 47 added pointers. If transactions 43, 44, and 45 are deleted, then the file dbghelp.dbg will be deleted from the directory. The directory will then have the following contents:

Directory of e:\symsrv\dbghelp.dbg\38039ff439000
10/13/1999  05:01p                   49 file.ptr
10/13/1999  05:01p                 130 refs.ptr

Now file.ptr contains "\\foo2\bin\symbols\retail\dll\dbghelp.dbg", and refs.ptr contains

0000000046,ptr,\\foo\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg

Whenever the final entry in refs.ptr is a pointer, the file file.ptr will exist and contain the path to the associated file. Whenever the final entry in refs.ptr is a file, no file.ptr will exist in this directory. Therefore, any delete operation that removes the final entry in refs.ptr may result in file.ptr being created, deleted, or changed.


Using Other Symbol Stores

It is possible to write your own symbol store creation program, rather than using SymStore.

Since SymStore transactions are all logged in CSV-format text files, you can leverage any existing SymStore log files for use in your own database program.

If you plan to use the SymSrv program provided with Debugging Tools for Windows, it is recommended that you use SymStore as well. Updates to these two programs will always be released together, and therefore their versions will always match.


SymStore Command-Line Options

The following syntax forms are supported for SymStore transactions. The first parameter must always be add or del. The order of the other parameters is immaterial.

symstore add [/r] [/p] [/l] /f File /s Store /t Product [/v Version] [/o] [/c Comment] [/d LogFile]
symstore add [/r] [/p] [/l] /g Share /f File /x IndexFile [/a] [/o] [/d LogFile]
symstore add /y IndexFile /g Share /s Store [/p] /t Product [/v Version] [/o] [/c Comment] [/d LogFile]
symstore del /i ID /s Store [/o] [/d LogFile]
symstore /?

Parameter | Meaning
/f File | Specifies the network path of files or directories to add.
/g Share | Specifies the server and share where the symbol files were originally stored. When used with /f, Share should be identical to the beginning of the File specifier. When used with /y, Share should be the location of the original symbol files (not the index file). This allows you to later change this portion of the file path in case you move the symbol files to a different server and share.
/i ID | Specifies the transaction ID string.
/l | Allows the file to be in a local directory rather than a network path. (This option is only used with the /p option.)
/p | Causes SymStore to store a pointer to the file, rather than the file itself.
/r | Causes SymStore to add files or directories recursively.
/s Store | Specifies the root directory for the symbol store.
/t Product | Specifies the name of the product.
/v Version | Specifies the version of the product.
/c Comment | Specifies a comment for the transaction.
/d LogFile | Specifies a log file to be used for command output. If this is not included, transaction information and other output is sent to stdout.
/o | Causes SymStore to display verbose output.
/x IndexFile | Causes SymStore not to store the actual symbol files. Instead, SymStore records information in the IndexFile that will enable SymStore to access the symbol files at a later time.
/a | Causes SymStore to append new indexing information to an existing index file. (This option is only used with the /x option.)
/y IndexFile | Causes SymStore to read the data from a file created with /x.
/? | Displays help text for the SymStore command.


Minidump Files

Applications can produce user-mode minidump files, which contain a useful subset of the information contained in a crash dump file. Applications can create minidump files very quickly and efficiently. Because minidump files are small, they can be easily sent over the internet to technical support for the application.

A minidump file does not contain as much information as a full crash dump file, but it contains enough information to perform basic debugging operations. To read a minidump file, you must have the binaries and symbol files available for the debugger.

Microsoft® Office® XP and Windows® XP create minidump files for the purpose of analyzing failures on customers' computers.

The following DbgHelp functions are used with minidump files.

MiniDumpCallback
MiniDumpReadDumpStream
MiniDumpWriteDump


Updated Platform Support

Where necessary, the DbgHelp library has been widened to support both 32- and 64-bit Windows. The original function and structure definitions are still in DbgHelp.h, but there are also updated versions of these definitions that are compatible with 64-bit Windows. If you use the updated functions in your code, it can be compiled for both 32- and 64-bit Windows. Your code will also be more efficient, since the original functions simply call the updated functions to perform the work.

For example, DbgHelp.h contains definitions for SymLoadModule (original function) and SymLoadModule64 (updated function). These definitions are nearly identical, but use different types for the return value and the BaseOfDll parameter. (SymLoadModule uses the DWORD type for these values, while SymLoadModule64 uses the DWORD64 type.) If you write your code to use SymLoadModule64, it can be compiled for both 32- and 64-bit Windows. The code is also more efficient than if it were to call SymLoadModule.

The following is a list of the updated functions:

  • EnumerateLoadedModules64
  • StackWalk64
  • SymEnumerateModules64
  • SymEnumerateSymbols64
  • SymFunctionTableAccess64
  • SymGetLineFromAddr64
  • SymGetLineFromName64
  • SymGetLineNext64
  • SymGetLinePrev64
  • SymGetModuleBase64
  • SymGetModuleInfo64
  • SymGetSymFromAddr64
  • SymGetSymFromName64
  • SymGetSymNext64
  • SymGetSymPrev64
  • SymLoadModule64
  • SymRegisterCallback64
  • SymRegisterFunctionEntryCallback64
  • SymUnloadModule64

The following is a list of the updated structures:

  • ADDRESS64
  • IMAGEHLP_DEFERRED_SYMBOL_LOAD64
  • IMAGEHLP_DUPLICATE_SYMBOL64
  • IMAGEHLP_LINE64
  • IMAGEHLP_MODULE64
  • IMAGEHLP_SYMBOL64
  • KDHELP64
  • STACKFRAME64


Using DbgHelp

The following topics demonstrate how an application can use the symbol handler functions:

  • Initializing the Symbol Handler
  • Loading a Symbol Module
  • Enumerating Symbol Modules
  • Enumerating Symbols
  • Retrieving Symbol Information by Name
  • Retrieving Symbol Information by Address
  • Retrieving Undecorated Symbol Names
  • Unloading a Symbol Module
  • Terminating the Symbol Handler


Initializing the Symbol Handler

The following code demonstrates how to initialize the symbol handler. The SymSetOptions function defers symbol loading until symbol information is requested. The code loads the symbols for each module in the specified process by passing a value of TRUE for the bInvade parameter of the SymInitialize function. (This function calls the SymLoadModule64 function for each module the process has mapped into its address space.)

If the specified process is not the process that called SymInitialize, the code passes a process identifier as the first parameter of SymInitialize.

Specifying NULL as the second parameter of SymInitialize indicates that the symbol handler should use the default search path to locate symbol files. For detailed information on how the symbol handler locates symbol files or how an application can specify a symbol search path, see Symbol Paths.

DWORD  error;
HANDLE hProcess;
DWORD  processId;

SymSetOptions(SYMOPT_UNDNAMES | SYMOPT_DEFERRED_LOADS);

hProcess = GetCurrentProcess();
// hProcess = (HANDLE)processId;

if (SymInitialize(hProcess, NULL, TRUE))
{
    // SymInitialize returned success
}
else
{
    // SymInitialize failed
    error = GetLastError();
    printf("SymInitialize returned error : %d\n", error);
}


Loading a Symbol Module

If an application does not call the SymInitialize function with the fInvadeProcess parameter set to TRUE, it must load symbols for a module when they are required. To load a symbol module on demand, the application can call the SymLoadModule64 function with a full path to a module name. When the module is loaded, the symbol handler will either load the symbols immediately or defer the load, depending on the options set using the SymSetOptions function.

The following code loads a symbol module.

char  szImageName[MAX_PATH+1];
DWORD64 dwBaseAddr;

if (SymLoadModule64(hProcess, NULL, szImageName, NULL, dwBaseAddr, 0))
{
    // SymLoadModule64 returned success
}
else
{
    // SymLoadModule64 failed
    error = GetLastError();
    printf("SymLoadModule64 returned error : %d\n", error);
}

Note that szImageName can be a path to any executable module that has debugging information (.exe, .dll, .drv, .sys, .scr, .cpl, .com). Also, dwBaseAddr is the base address of the symbol module to be loaded. If this value is 0, the symbol handler will obtain the base address from the specified symbol module.


Enumerating Symbol Modules

The following code lists the modules that have been loaded by the SymLoadModule64 or SymInitialize function. The SymEnumerateModules64 function requires a callback function, which will be called once for each module loaded. In this example, EnumModules is an implementation of the callback function.

BOOL CALLBACK EnumModules(
    LPSTR   ModuleName,
    DWORD64 BaseOfDll,
    PVOID   UserContext )
{
    printf("%08X %s\n", BaseOfDll, ModuleName);
    return TRUE;
}

if (SymEnumerateModules64(hProcess, EnumModules, NULL))
{
    // SymEnumerateModules64 returned success
}
else
{
    // SymEnumerateModules64 failed
    error = GetLastError();
    printf("SymEnumerateModules64 returned error : %d\n", error);
}


Enumerating Symbols

The following code displays the name, address, and size of each loaded symbol in the specified module. The SymEnumSymbols function requires a callback function, which will be called once for each module loaded. In this example, EnumerateSymbolsProc is an implementation of the callback function.

BOOL CALLBACK EnumerateSymbolsProc(
    PSYMBOL_INFO pSymInfo,
    ULONG SymbolSize,
    PVOID UserContext)
{
    printf("%08X %4u %s\n", pSymInfo.Address, SymbolSize, pSymInfo.Name);
    return TRUE;
}

if (SymEnumSymbols(hProcess, BaseOfDll, Mask, EnumerateSymbolsProc, NULL))
{
    // SymEnumSymbols returned success
}
else
{
    // SymEnumSymbols failed
    error = GetLastError();
    printf("SymEnumSymbols returned error : %d\n", error);
}


Retrieving Symbol Information by Name

The following code demonstrates how to call the SymFromName function. This function fills in a SYMBOL_INFO structure. Because the name is variable in length, you must supply a buffer that is large enough to hold the name stored at the end of the SYMBOL_INFO structure. Also, the MaxNameLen member must be set to the number of bytes reserved for the name. In this example, szSymbolName is a buffer that stores the name of the requested symbol.

BYTE szSymbolName[256];
BYTE buffer[256];
PSYMBOL_INFO pSymbol = (PSYMBOL_INFO)buffer;

lstrcpy(szSymbolName, "WinMain");
pSymbol->SizeOfStruct = sizeof(SYMBOL_INFO);
pSymbol->MaxNameLen = sizeof(buffer) - sizeof(SYMBOL_INFO) + 1;

if (SymFromName(hProcess, szSymbolName, pSymbol))
{
    // SymFromName returned success
}
else
{
    // SymFromName failed
    error = GetLastError();
    printf("SymFromName returned error : %d\n", error);
}

If an application has a module or source file name as well as line number information, it can use SymGetLineFromName64 to retrieve a virtual code address. This function requires a pointer to an IMAGEHLP_LINE64 structure to receive the virtual code address. Note that the symbol handler can retrieve line number information only when SYMOPT_LOAD_LINES option is set using the SymSetOptions function. This option must be set before loading the module. The szModuleName parameter contains the source module name; it is optional and can be NULL. The szFileName parameter should contain the source file name, and dwLineNumber parameter should contain the line number for which the virtual address will be retrieved.

BYTE   szModuleName[MAX_PATH];
BYTE   szFileName[MAX_PATH];
DWORD  dwLineNumber;
LONG   lDisplacement;
IMAGEHLP_LINE64 line;

SymSetOptions(SYMOPT_LOAD_LINES);

line.SizeOfStruct = sizeof(IMAGEHLP_LINE64);
lstrcpy(szModuleName, "MyApp");
lstrcpy(szFileName, "main.c");
dwLineNumber = 248;

if (SymGetLineFromName64(hProcess, szModuleName, szFileName,
    dwLineNumber, &lDisplacement, &line))
{
    // SymGetLineFromName64 returned success
}
else
{
    // SymGetLineFromName64 failed
    error = GetLastError();
    printf("SymGetLineFromName64 returned error : %d\n", error);
}


Retrieving Symbol Information by Address

The following code demonstrates how to call the SymFromAddr function. This function fills in a SYMBOL_INFO structure. Because the name is variable in length, you must supply a buffer that is large enough to hold the name stored at the end of the SYMBOL_INFO structure. Also, the MaxNameLen member must be set to the number of bytes reserved for the name. In this example, dwAddress is the address to be mapped to a symbol. The SymFromAddr function will store an offset to the beginning of the symbol to the address in dwDisplacement.

DWORD  dwAddress;
DWORD  dwDisplacement;
BYTE   buffer[256];
PSYMBOL_INFO pSymbol = (PSYMBOL_INFO)buffer;

pSymbol->SizeOfStruct = sizeof(SYMBOL_INFO);
pSymbol->MaxNameLen = sizeof(buffer) - sizeof(SYMBOL_INFO) + 1;

if (SymFromAddr(hProcess, dwAddress, &dwDisplacement, pSymbol))
{
// SymFromAddr returned success
}
else
{
    // SymFromAddr failed
    error = GetLastError();
    printf("SymFromAddr returned error : %d\n", error);
}

To retrieve the source code line number for a specified address, an application can use SymGetLineFromAddr64. This function requires a pointer to an IMAGEHLP_LINE64 structure to receive the source file name and line number corresponding to a specified code address. Note that the symbol handler can retrieve line number information only when SYMOPT_LOAD_LINES is set using the SymSetOptions function. This option must be set before loading the module. The dwAddress parameter contains the code address for which the source file name and line number will be located.

DWORD64  dwAddress;
DWORD  dwDisplacement;
IMAGEHLP_LINE64 line;

SymSetOptions(SYMOPT_LOAD_LINES);

line.SizeOfStruct = sizeof(IMAGEHLP_LINE64);

if (SymGetLineFromAddr64(hProcess, dwAddress, &dwDisplacement, &line))
{
    // SymGetLineFromAddr64 returned success
}
else
{
    // SymGetLineFromAddr64 failed
    error = GetLastError();
    printf("SymGetLineFromAddr64 returned error : %d\n", error);
}


Retrieving Undecorated Symbol Names

The following code demonstrates how to retrieve an undecorated symbol name from a symbol name using UnDecorateSymbolName. The decorated name is stored in szName.

if (UnDecorateSymbolName(szName, szUndName, sizeof(szUndName), UNDNAME_COMPLETE))
{
    // UnDecorateSymbolName returned success
    printf ("Symbol : %s\n", szUndName);
}
else
{
    // UnDecorateSymbolName failed
    error = GetLastError();
    printf("UnDecorateSymbolName returned error %d\n", error);
}


Unloading a Symbol Module

The following code unloads a symbol module referred to by the BaseOfDll module address using SymUnloadModule64.

if (SymUnloadModule64(hProcess, BaseOfDll)
{
    // SymUnloadModule64 returned success
}
else
{
    // SymUnloadModule64 failed
    error = GetLastError();
    printf("SymUnloadModule64 returned error : %d\n", error);
}


Terminating the Symbol Handler

The following code cleans up all memory associated with symbol handling for the specified process, using SymCleanup.

if (SymCleanup(hProcess))
{
    // SymCleanup returned success
}
else
{
    // SymCleanup failed
    error = GetLastError();
    printf("SymCleanup returned error : %d\n", error);
}


DbgHelp Reference

The following elements are part of DbgHelp.

  • DbgHelp Functions
  • DbgHelp Structures
  • DbgHelp Enumerations


DbgHelp Functions

The following are the DbgHelp functions.

General

The following are general helper functions:

EnumDirTree
ImagehlpApiVersion
ImagehlpApiVersionEx
MakeSureDirectoryPathExists
SearchTreeForFile

Debugger

The debugging service functions are the functions most suited for use by a debugger or the debugging code in an application. These functions can be used in concert with the symbol handler functions for easier use.

EnumerateLoadedModules64
FindDebugInfoFile
FindDebugInfoFileEx
FindExecutableImage
FindExecutableImageEx
StackWalk64
SymSetParentWindow
UnDecorateSymbolName

Image Access

The image access functions access the data in an executable image. The functions provide high-level access to the base of images and very specific access to the most common parts of an image's data.

GetTimestampForLoadedLibrary
ImageDirectoryEntryToData
ImageDirectoryEntryToDataEx
ImageNtHeader
ImageRvaToSection
ImageRvaToVa

Symbol Handler

The symbol handler functions give applications easy and portable access to the symbolic debugging information of an image. These functions should be used exclusively to ensure access to symbolic information. This is necessary because these functions isolate the application from the symbol format.

SymAddSymbol
SymCleanup
SymDeleteSymbol
SymEnumerateModules64
SymEnumSymbols
SymEnumSymbolsForAddr
SymEnumTypes
SymFindFileInPath
SymFromAddr
SymFromName
SymFunctionTableAccess64
SymGetLineFromAddr64
SymGetLineFromName64
SymGetLineNext64
SymGetLinePrev64
SymGetModuleBase64
SymGetModuleInfo64
SymGetOptions
SymGetSearchPath
SymGetSymNext64
SymGetSymPrev64
SymGetTypeFromName
SymGetTypeInfo
SymInitialize
SymLoadModule64
SymLoadModuleEx
SymMatchFileName
SymRegisterCallback64
SymRegisterFunctionEntryCallback64
SymSetContext
SymSetOptions
SymSetSearchPath
SymUnloadModule64

Symbol Server

The symbol server enables debuggers to automatically retrieve the correct symbol files without product names, releases, or build numbers.

SymbolServer
SymbolServerClose
SymbolServerGetOptions
SymbolServerSetOptions

User-mode Minidump Files

The minidump functions provide a way for applications to produce crashdump files that contain a useful subset of the entire process context. The following functions are used with minidump files.

MiniDumpCallback
MiniDumpReadDumpStream
MiniDumpWriteDump

Obsolete Functions

MapDebugInformation
SymEnumerateSymbols64
SymGetSymFromAddr64
SymGetSymFromName64
UnMapDebugInformation


EnumDirTree

The EnumDirTree function enumerates all occurrences of the specified file in the specified directory tree.

BOOL EnumDirTree(
  HANDLE hProcess,
  LPSTR RootPath,
  LPSTR InputPathName,
  LPSTR OutputPathBuffer,
  PENUMDIRTREE_CALLBACK Callback,
  PVOID CallbackData
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
RootPath
[in] Pointer to a null-terminated string that specifies the path where the function should begin searching for the file.
InputPathName
[in] Pointer to a null-terminated string that specifies the name of the file to be found. You can specify a partial path.
OutputPathBuffer
[out] Pointer to a buffer that receives the full path of the file that is found. If the function fails, this buffer is not modified. This parameter is optional and can be NULL.
Callback
[in] Pointer to an application-defined callback function, or NULL. For more information, see EnumDirTreeProc.
CallbackData
[in] User-defined data or NULL. This value is passed to the callback function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The search can be canceled if you register a SymRegisterCallbackProc64 callback function. For every file operation, EnumDirTree calls this callback function with CBA_DEFERRED_SYMBOL_LOAD_CANCEL. If the callback function returns TRUE, EnumDirTree cancels the search.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, EnumDirTreeProc


EnumDirTreeProc

The EnumDirTreeProc function is an application-defined callback function used with the EnumDirTree function. It is called every time a match is found.

The PENUMDIRTREE_CALLBACK type defines a pointer to this callback function. EnumDirTreeProc is a placeholder for the application-defined function name.

BOOL CALLBACK EnumDirTreeProc(
  LPCSTR FilePath,
  PVOID  CallerData
);

Parameters

FilePath
Pointer to a buffer that receives the full path of the file that is found.
CallerData
User-defined value specified in EnumDirTree, or NULL. Typically, this parameter is used by an application to pass a pointer to a data structure that enables the callback function to establish some context.

Return Values

If the function returns TRUE, the enumerationwill continue.

If the function returns FALSE, the enumeration will stop.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, EnumDirTree


EnumerateLoadedModules64

The EnumerateLoadedModules64 function enumerates the loaded modules for the specified process.

This function supersedes the EnumerateLoadedModules function. For more information, see Updated Platform Support.

BOOL EnumerateLoadedModules64(
  HANDLE hProcess,
  PENUMLOADED_MODULES_CALLBACK64 EnumLoadedModulesCallback,
  PVOID UserContext
);

Parameters

hProcess
[in] Handle to the process whose modules will be enumerated.
EnumLoadedModulesCallback
[in] Pointer to an application-defined callback function. For more information, see EnumerateLoadedModulesProc64.
UserContext
[in] User-defined data. This value is passed to the callback function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, EnumerateLoadedModulesProc64


EnumerateLoadedModulesProc64

The EnumerateLoadedModulesProc64 function is an application-defined callback function used with the EnumerateLoadedModules64 function.

The PENUMLOADED_MODULES_CALLBACK64 type defines a pointer to this callback function. EnumerateLoadedModulesProc64 is a placeholder for the application-defined function name.

This function supersedes the EnumerateLoadedModulesProc function. For more information, see Updated Platform Support.

BOOL CALLBACK EnumerateLoadedModulesProc64(
  PSTR ModuleName,
  DWORD64 ModuleBase,
  ULONG ModuleSize,
  PVOID UserContext
);

Parameters

ModuleName
[in] Pointer to the name of the enumerated module.
ModuleBase
[in] Module's base address.
ModuleSize
[in] Size of the module, in bytes.
UserContext
[in] User-defined data. This value is passed from EnumerateLoadedModules64.

Return Values

To continue enumeration, the callback function must return TRUE.

To stop enumeration, the callback function must return FALSE.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, EnumerateLoadedModules64


FindDebugInfoFile

The FindDebugInfoFile function locates a debug (.dbg) file.

To provide a callback function to verify the symbol file located, use the FindDebugInfoFileEx function .

HANDLE FindDebugInfoFile(
  PSTR FileName,
  PSTR SymbolPath,
  PSTR DebugFilePath
);

Parameters

FileName
[in] Pointer to a null-terminated string that specifies the name of the .dbg file that is desired. You can use a partial path.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path where symbol files are located. This can be multiple paths separated by semicolons. To retrieve the symbol path, use the SymGetSearchPath function.
DebugFilePath
[out] Pointer to a string buffer that receives the full path of the .dbg file.

Return Values

If the function succeeds, the return value is an open handle to the .dbg file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The FindDebugInfoFile function is used to locate a .dbg file. This function is provided so the search can be conducted in several different directories through a single function call. The SymbolPath parameter can contain multiple paths, with each separated by a semicolon (;). When multiple paths are specified, the function searches each directory for the file. Subdirectories are not searched. When the file is located, the search stops. Thus, be sure to specify SymbolPath with the paths in the correct order.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, FindDebugInfoFileEx, SymGetSearchPath


FindDebugInfoFileEx

The FindDebugInfoFileEx function locates a debug (.dbg) file.

HANDLE FindDebugInfoFileEx(
  PSTR FileName,
  PSTR SymbolPath,
  PSTR DebugFilePath,
  PFIND_DEBUG_FILE_CALLBACK Callback,
  PVOID CallerData
);

Parameters

FileName
[in] Pointer to a null-terminated string that specifies the name of the .dbg file to locate. You can use a partial path.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path where symbol files are located. This can be multiple paths separated by semicolons. To retrieve the symbol path, use the SymGetSearchPath function.
DebugFilePath
[out] Pointer to a string buffer that receives the full path of the .dbg file.
Callback
[in] Pointer to an application-defined callback function that verifies whether the correct file was found or the function should continue its search. For more information, see FindDebugInfoFileProc.

This parameter may be NULL.

CallerData
[in] User-defined data to pass to the callback function. This parameter may be NULL.

Return Values

If the function succeeds, the return value is an open handle to the .dbg file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The FindDebugInfoFileEx function is used to locate a .dbg file. This function is provided so the search can be conducted in several different directories through a single function call. The SymbolPath parameter can contain multiple paths, with each separated by a semicolon (;). When multiple paths are specified, the function searches each directory tree for the file. When the file is located, the search stops. Thus, be sure to specify SymbolPath with the paths in the correct order.

If the file name specified does not include a .dbg extension, FindDebugInfoFileEx searches for the file in the following sequence:

  1. <SymbolPath>\Symbols\<ext>\<filename>.dbg
  2. <SymbolPath>\Symbols\<ext>\<filename>.sym
  3. <SymbolPath>\<ext>\<filename>.dbg
  4. <SymbolPath>\<ext>\<filename>.sym
  5. <SymbolPath>\<filename>.dbg
  6. <SymbolPath>\<filename>.sym
  7. <FileNamePath>\<filename>.dbg
  8. <FileNamePath>\<filename>.sym

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, FindDebugInfoFileProc, SymGetSearchPath


FindDebugInfoFileProc

The FindDebugInfoFileProc function is an application-defined callback function used with the FindDebugInfoFileEx function. It verifies whether the symbol file located by FindDebugInfoFileEx is the correct symbol file.

The PFIND_DEBUG_FILE_CALLBACK type defines a pointer to this callback function. FindDebugInfoFileProc is a placeholder for the application-defined function name.

BOOL CALLBACK FindDebugInfoFileProc(
  HANDLE FileHandle,
  PSTR FileName,
  PVOID CallerData
);

Parameters

FileHandle
[in] Handle to the symbol file.
FileName
[in] Pointer to a null-terminated string that specifies the name of the symbol file.
CallerData
[in] User-defined data. This parameter can be NULL.

Return Values

If the symbol file is valid, return TRUE. Otherwise, return FALSE.

Remarks

One way to verify the symbol file is to compare its timestamp to the timestamp in the image. To retrieve the timestamp of the image, use the GetTimestampForLoadedLibrary function. To retrieve the timestamp of the symbol file, use the SymGetModuleInfo64 function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, FindDebugInfoFileEx, GetTimestampForLoadedLibrary, SymGetModuleInfo64


FindExecutableImage

The FindExecutableImage function locates an executable file.

To specify a callback function, use the FindExecutableImageEx function.

HANDLE FindExecutableImage(
  PSTR FileName,
  PSTR SymbolPath,
  PSTR ImageFilePath
);

Parameters

FileName
[in] Pointer to a null-terminated string that specifies the name of the symbol file to locate. You can use a partial path.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path where symbol files are located. This can be multiple paths separated by semicolons. To retrieve the symbol path, use the SymGetSearchPath function.
ImageFilePath
[out] Pointer to a string buffer that receives the full path of the executable file.

Return Values

If the function succeeds, the return value is an open handle to the executable file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The FindExecutableImage function is provided so executable files can be located in several different directories through a single function call. The SymbolPath parameter can contain multiple paths, with each separated by a semicolon (;). When multiple paths are specified, the function searches each directory tree for the executable file. When the file is located, the search stops. Thus, be sure to specify SymbolPath with the paths in the correct order.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, FindExecutableImageEx, SymGetSearchPath


FindExecutableImageEx

The FindExecutableImageEx function locates an executable file.

HANDLE FindExecutableImageEx(
  PSTR FileName,
  PSTR SymbolPath,
  PSTR ImageFilePath,
  PFIND_EXE_FILE_CALLBACK Callback,
  PVOID CallerData
);

Parameters

FileName
[in] Pointer to a null-terminated string that specifies the name of the symbol file to locate. You can use a partial path.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path where symbol files are located. This string can contain multiple paths separated by semicolons. To retrieve the symbol path, use the SymGetSearchPath function.
ImageFilePath
[out] Pointer to a string buffer that receives the full path of the executable file.
Callback
[in] Pointer to an application-defined callback function that verifies whether the correct executable file was found, or whether the function should continue its search. For more information, see FindExecutableImageProc.

This parameter can be NULL.

CallerData
[in] User-defined data to pass to the callback function. This parameter can be NULL.

Return Values

If the function succeeds, the return value is an open handle to the executable file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The FindExecutableImageEx function is provided so executable files can be found in several different directories by using a single function call. If the SymbolPath parameter containins multiple paths, the function searches each specified directory tree for the executable file. When the file is found, the search stops. Thus, be sure to specify SymbolPath with the paths in the correct order.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, FindExecutableImageProc, SymGetSearchPath


FindExecutableImageProc

The FindExecutableImageProc function is an application-defined callback function used with the FindExecutableImageEx function. It verifies whether the executable file found by FindExecutableImageEx is the correct executable file.

The PFIND_EXE_FILE_CALLBACK type defines a pointer to this callback function. FindExecutableImageProc is a placeholder for the application-defined function name.

BOOL CALLBACK FindExecutableImageProc(
  HANDLE FileHandle,
  PSTR FileName,
  PVOID CallerData
);

Parameters

FileHandle
[in] Handle to the executable file.
FileName
[in] Pointer to a null-terminated string that specifies the name of the executable file.
CallerData
[in] User-defined data. This parameter can be NULL.

Return Values

If the executable file is valid, return TRUE. Otherwise, return FALSE.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, FindExecutableImageEx


FunctionTableAccessProc64

The FunctionTableAccessProc64 function is an application-defined callback function used with the StackWalk64 function. It provides access to the run-time function table for the process.

The PFUNCTION_TABLE_ACCESS_ROUTINE64 type defines a pointer to this callback function. FunctionTableAccessProc64 is a placeholder for the application-defined function name.

This function supersedes the FunctionTableAccessProc function. For more information, see Updated Platform Support.

PVOID CALLBACK FunctionTableAccessProc64(
  HANDLE hProcess,
  DWORD64 AddrBase
);

Parameters

hProcess
[in] Handle to the process for which the stack trace is generated.
AddrBase
[in] Address of the instruction for which you are searching.

Return Values

The function returns a pointer to the run-time function table. On an x86 computer, this is a pointer to an FPO_DATA structure. On an Alpha computer, this is a pointer to an IMAGE_FUNCTION_ENTRY structure.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, FPO_DATA, IMAGE_FUNCTION_ENTRY, StackWalk64


GetModuleBaseProc64

The GetModuleBaseProc64 function is an application-defined callback function used with the StackWalk64 function. It is called when StackWalk64 needs a module base address for a given virtual address.

The PGET_MODULE_BASE_ROUTINE64 type defines a pointer to this callback function. GetModuleBaseProc64 is a placeholder for the application-defined function name.

This function supersedes the GetModuleBaseProc function. For more information, see Updated Platform Support.

DWORD CALLBACK GetModuleBaseProc64(
  HANDLE hProcess,
  DWORD64 Address
);

Parameters

hProcess
[in] Handle to the process for which the stack trace is generated.
Address
[in] Address whose module image should be located.

Return Values

The function returns the base address of the module.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, StackWalk64


GetTimestampForLoadedLibrary

The GetTimestampForLoadedLibrary function returns the timestamp of a loaded image.

DWORD GetTimestampForLoadedLibrary(
  HMODULE ImageBase
);

Parameters

ImageBase
[in] Base address of an image that is mapped into memory by a call to the MapViewOfFile function.

Return Values

If the function succeeds, the return value is the timestamp from the image.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Remarks

The timestamp for an image indicates the date and time that the image was created by the linker. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The timestamp can be printed using the C run-time (CRT) function ctime.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, MapViewOfFile


ImageDirectoryEntryToData

The ImageDirectoryEntryToData function obtains access to image-specific data.

This function has been superseded by the ImageDirectoryEntryToDataEx function. Use ImageDirectoryEntryToDataEx to retrieve the section header.

PVOID ImageDirectoryEntryToData(
  PVOID Base,
  BOOLEAN MappedAsImage,
  USHORT DirectoryEntry,
  PULONG Size
);

Parameters

Base
[in] Base address of the image.
MappedAsImage
[in] If this parameter is TRUE, the file is mapped by the system as an image. If the flag is FALSE, the file is mapped as a data file by the MapViewOfFile function.
DirectoryEntry
[in] Index number of the desired directory entry. This parameter can be one of the following values.
Value | Meaning
IMAGE_DIRECTORY_ENTRY_EXPORT | Export directory
IMAGE_DIRECTORY_ENTRY_IMPORT | Import directory
IMAGE_DIRECTORY_ENTRY_RESOURCE | Resource directory
IMAGE_DIRECTORY_ENTRY_EXCEPTION | Exception directory
IMAGE_DIRECTORY_ENTRY_SECURITY | Security directory
IMAGE_DIRECTORY_ENTRY_BASERELOC | Base relocation table
IMAGE_DIRECTORY_ENTRY_DEBUG | Debug directory
IMAGE_DIRECTORY_ENTRY_ARCHITECTURE | Architecture-specific data
IMAGE_DIRECTORY_ENTRY_GLOBALPTR | Relative virtual address of global pointer
IMAGE_DIRECTORY_ENTRY_TLS | Thread local storage directory
IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG | Load configuration directory
IMAGE_DIRECTORY_ENTRY_BOUND_IMPORT | Bound import directory
IMAGE_DIRECTORY_ENTRY_IAT | Import address table
IMAGE_DIRECTORY_ENTRY_DELAY_IMPORT | Delay import table
IMAGE_DIRECTORY_ENTRY_COM_DESCRIPTOR | COM descriptor table

Size
[out] Pointer to a variable that receives the size of the data for the directory entry, in bytes.

Return Values

If the function succeeds, the return value is a pointer to the directory entry's data.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The ImageDirectoryEntryToData function is used to obtain access to image-specific data.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, ImageDirectoryEntryToDataEx, MapViewOfFile


ImageDirectoryEntryToDataEx

The ImageDirectoryEntryToDataEx function locates a directory entry within the image header and returns the address of the data for the directory entry. This function returns the section header for the data located, if one exists.

PVOID ImageDirectoryEntryToDataEx(
  PVOID Base,
  BOOLEAN MappedAsImage,
  USHORT DirectoryEntry,
  PULONG Size,
  PIMAGE_SECTION_HEADER *FoundHeader
);

Parameters

Base
[in] Base address of the image or data file.
MappedAsImage
[in] If the flag is TRUE, the file is mapped by the system as an image. If this flag is FALSE, the file is mapped as a data file by the MapViewOfFile function.
DirectoryEntry
[in] Directory entry to be located. The value must be one of the following values.
Value | Meaning
IMAGE_DIRECTORY_ENTRY_EXPORT | Export directory
IMAGE_DIRECTORY_ENTRY_IMPORT | Import directory
IMAGE_DIRECTORY_ENTRY_RESOURCE | Resource directory
IMAGE_DIRECTORY_ENTRY_EXCEPTION | Exception directory
IMAGE_DIRECTORY_ENTRY_SECURITY | Security directory
IMAGE_DIRECTORY_ENTRY_BASERELOC | Base relocation table
IMAGE_DIRECTORY_ENTRY_DEBUG | Debug directory
IMAGE_DIRECTORY_ENTRY_ARCHITECTURE | Architecture-specific data
IMAGE_DIRECTORY_ENTRY_GLOBALPTR | Relative virtual address of global pointer
IMAGE_DIRECTORY_ENTRY_TLS | Thread local storage directory
IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG | Load configuration directory
IMAGE_DIRECTORY_ENTRY_BOUND_IMPORT | Bound import directory
IMAGE_DIRECTORY_ENTRY_IAT | Import address table
IMAGE_DIRECTORY_ENTRY_DELAY_IMPORT | Delay load import descriptors
IMAGE_DIRECTORY_ENTRY_COM_DESCRIPTOR | COM run-time descriptor

Size
[out] Pointer to a variable that receives the size of the data for the directory entry that is located.
FoundHeader
[out] Pointer to an IMAGE_SECTION_HEADER structure that receives the data. If the section header does not exist, this parameter is NULL.

Return Values

If the function succeeds, the return value is a pointer to the data for the directory entry.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGE_SECTION_HEADER, MapViewOfFile


ImagehlpApiVersion

The ImagehlpApiVersion function retrieves the information about the version of the library installed on the system.

To indicate the version of the library with which the application was built, use the ImagehlpApiVersionEx function.

LPAPI_VERSION ImagehlpApiVersion(VOID);

Parameters

This function has no parameters.

Return Values

The return value is a pointer to an API_VERSION structure.

Remarks

Use the information in the API_VERSION structure to determine whether the version of the library installed on the system is compatible with the version of the library used by the application. Although the library functions are backward compatible, functions introduced in one version are obviously not available in earlier versions.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, API_VERSION, ImagehlpApiVersionEx


ImagehlpApiVersionEx

The ImagehlpApiVersionEx function modifies the information about the version of the library used by the application.

LPAPI_VERSION ImagehlpApiVersionEx(
  LPAPI_VERSION AppVersion
);

Parameters

AppVersion
[in] Pointer to an API_VERSION structure that contains valid version information for your application.

Return Values

The return value is a pointer to an API_VERSION structure.

Remarks

Use the ImagehlpApiVersionEx function to indicate the version of the library with which the application was built. The library uses this information to ensure compatibility. For example, consider walking through kernel-mode callback stack frames (starting with Windows NT 4.0, User and GDI exist in kernel mode). If you call ImagehlpApiVersionEx to set the Revision member to version 4 or later, the StackWalk64 function will continue through a callback stack frame. Otherwise, if you set Revision to a version earlier than 4, StackWalk64 will stop at the kernel transition.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, API_VERSION, ImagehlpApiVersion


ImageNtHeader

The ImageNtHeader function locates the IMAGE_NT_HEADERS structure in a PE image and returns a pointer to the data.

PIMAGE_NT_HEADERS ImageNtHeader(
  PVOID ImageBase
);

Parameters

ImageBase
[in] Base address of an image that is mapped into memory by a call to the MapViewOfFile function.

Return Values

If the function succeeds, the return value is a pointer to an IMAGE_NT_HEADERS structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGE_NT_HEADERS, MapViewOfFile


ImageRvaToSection

The ImageRvaToSection function locates a relative virtual address (RVA) within the image header of a file that is mapped as a file and returns a pointer to the section table entry for that virtual address.

PIMAGE_SECTION_HEADER ImageRvaToSection(
  PIMAGE_NT_HEADERS NtHeaders,
  PVOID Base,
  ULONG Rva
);

Parameters

NtHeaders
[in] Pointer to an IMAGE_NT_HEADERS structure. This structure can be obtained by calling the ImageNtHeader function.
Base
[in] Base address of an image that is mapped into memory through a call to MapViewOfFile.
Rva
[in] Relative virtual address to be located.

Return Values

If the function succeeds, the return value is a pointer to an IMAGE_SECTION_HEADER structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The ImageRvaToSection function locates an RVA within the image header of a file that is mapped as a file and returns a pointer to the section table entry for that virtual address.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGE_NT_HEADERS, IMAGE_SECTION_HEADER, ImageNtHeader, MapViewOfFile


ImageRvaToVa

The ImageRvaToVa function locates a relative virtual address (RVA) within the image header of a file that is mapped as a file and returns the virtual address of the corresponding byte in the file.

PVOID ImageRvaToVa(
  PIMAGE_NT_HEADERS NtHeaders,
  PVOID Base,
  ULONG Rva,
  PIMAGE_SECTION_HEADER *LastRvaSection
);

Parameters

NtHeaders
[in] Pointer to an IMAGE_NT_HEADERS structure. This structure can be obtained by calling the ImageNtHeader function.
Base
[in] Base address of an image that is mapped into memory through a call to the MapViewOfFile function.
Rva
[in] Relative virtual address to be located.
LastRvaSection
[in/out] Pointer to an IMAGE_SECTION_HEADER structure that specifies the last RVA section. This is an optional parameter. When specified, it points to a variable that contains the last section value used for the specified image to translate an RVA to a VA.

Return Values

If the function succeeds, the return value is the virtual address in the mapped file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The ImageRvaToVa function locates an RVA within the image header of a file that is mapped as a file and returns the virtual address of the corresponding byte in the file.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGE_NT_HEADERS, IMAGE_SECTION_HEADER, ImageNtHeader, MapViewOfFile


MakeSureDirectoryPathExists

The MakeSureDirectoryPathExists function creates all the directories in the specified DirPath, beginning with the root.

BOOL MakeSureDirectoryPathExists(
  PCSTR DirPath
);

Parameters

DirPath
[in] Pointer to a null-terminated string that specifies a valid path name. If the final component of the path is a directory, not a file name, the string must end with a backslash (\) character.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

Each directory specified is created, if it does not already exist. If only some of the directories are created, the function will return FALSE.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions


MapDebugInformation

The MapDebugInformation function gains access to the debugging information for an image.

Note This function is provided only for backward compatibility. It does not return reliable information. New applications should use the SymGetModuleInfo64 and SymLoadModule64 functions. If you need the information provided by this function, the source code is available on the Platform SDK CD-ROM for you to adapt.

PIMAGE_DEBUG_INFORMATION MapDebugInformation(
  HANDLE FileHandle,
  PSTR FileName,
  PSTR SymbolPath,
  DWORD ImageBase
);

Parameters

FileHandle
[in] Handle to an open executable image or NULL.
FileName
[in] Pointer to a null-terminated string that specifies the name of an executable image file or NULL.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path where symbol files are located. The path can be multiple paths separated by semicolons. To retrieve the symbol path, use the SymGetSearchPath function.
ImageBase
[in] Base address for the image or zero.

Return Values

If the function succeeds, the return value is a pointer to an IMAGE_DEBUG_INFORMATION structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The MapDebugInformation function is used to gain access to an image's debugging information. The debugging information is extracted from the image or the symbol file and placed into the IMAGE_DEBUG_INFORMATION structure. This structure is allocated by the library and must be deallocated by using the UnmapDebugInformation function. The memory for the structure is not in the process's default heap, so attempts to free it with a memory deallocation routine will fail.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGE_DEBUG_INFORMATION, SymGetSearchPath, UnmapDebugInformation


MiniDumpCallback

The MiniDumpCallback function is an application-defined callback function used with MiniDumpWriteDump. It receives extended minidump information.

The MINIDUMP_CALLBACK_ROUTINE type defines a pointer to this callback function. MiniDumpCallback is a placeholder for the application-defined function name.

BOOL CALLBACK MiniDumpCallback (
  PVOID CallbackParam,
  CONST PMINIDUMP_CALLBACK_INPUT CallbackInput,
  PMINIDUMP_CALLBACK_OUTPUT CallbackOutput
);

Parameters

CallbackParam
[in] Application-defined parameter value.
CallbackInput
[in] Pointer to a MINIDUMP_CALLBACK_INPUT structure that specifies extended minidump information.
CallbackOutput
[out] Pointer to a MINIDUMP_CALLBACK_OUTPUT structure that receives application-defined information from the callback function.

Return Values

If the function succeeds, return TRUE; otherwise, return FALSE.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions, MINIDUMP_CALLBACK_INFORMATION, MiniDumpWriteDump


MiniDumpReadDumpStream

The MiniDumpReadDumpStream function reads a stream from a user-mode minidump file.

BOOL MiniDumpReadDumpStream (
  PVOID BaseOfDump,
  ULONG StreamNumber,
  PMINIDUMP_DIRECTORY *Dir,
  PVOID *StreamPointer,
  ULONG *StreamSize
);

Parameters

BaseOfDump
[in] Pointer to the base of the mapped minidump file. The file should have been mapped into memory using the MapViewOfFile function.
StreamNumber
[in] Type of data to be read from the minidump file. This member can be one of the values in the MINIDUMP_STREAM_TYPE enumeration.
Dir
[out] Pointer to a MINIDUMP_DIRECTORY structure.
StreamPointer
[out] Pointer to the beginning of the minidump stream. The format of this stream depends on the value of StreamNumber. For more information, see MINIDUMP_STREAM_TYPE.
StreamSize
[out] Size of the stream pointed to by StreamPointer, in bytes.

Return Values

If the function succeeds, the return value is TRUE; otherwise, the return value is FALSE.

Remarks

In this context, a data stream is a block of data written to a minidump file.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, MINIDUMP_DIRECTORY, MINIDUMP_STREAM_TYPE, MiniDumpWriteDump


MiniDumpWriteDump

The MiniDumpWriteDump function writes user-mode minidump information to the specified file.

BOOL MiniDumpWriteDump (
  HANDLE hProcess,
  DWORD ProcessId,
  HANDLE hFile,
  MINIDUMP_TYPE DumpType,
  PMINIDUMP_EXCEPTION_INFORMATION ExceptionParam,
  PMINIDUMP_USER_STREAM_INFORMATION UserStreamParam,
  PMINIDUMP_CALLBACK_INFORMATION CallbackParam
);

Parameters

hProcess
[in] Handle to the process for which the information is to be generated. This handle must have read and query access.
ProcessId
[in] Identifier of the process for which the information is to be generated.
hFile
[in] Handle to the file in which the information is to be written.
DumpType
[in] Type of information to be generated. This parameter can be one of the values from the MINIDUMP_TYPE enumeration.
ExceptionParam
[in] Pointer to a MINIDUMP_EXCEPTION_INFORMATION structure describing the client exception that caused the minidump to be generated. If the value of this parameter is NULL, no exception information is included in the minidump file.
UserStreamParam
[in] Pointer to an array of MINIDUMP_USER_STREAM_INFORMATION structures. If the value of this parameter is NULL, no user-defined information is included in the minidump file.
CallbackParam
[in] Pointer to a MINIDUMP_CALLBACK_INFORMATION structure that specifies a callback routine which is to receive extended minidump information. If the value of this parameter is NULL, no callbacks are performed.

Return Values

If the function succeeds, the return value is TRUE; otherwise, the return value is FALSE.

Remarks

The MiniDumpCallback function receives extended minidump information from MiniDumpWriteDump. It also provides a way for the caller to determine the granularity of information written to the minidump file, as the callback function can filter the default information.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, MINIDUMP_CALLBACK_INFORMATION, MINIDUMP_EXCEPTION_INFORMATION, MINIDUMP_USER_STREAM_INFORMATION, MiniDumpCallback, MiniDumpReadDumpStream


ReadProcessMemoryProc64

The ReadProcessMemoryProc64 function is an application-defined callback function used with the StackWalk64 function. It is called when StackWalk64 needs to read memory from the address space of the process.

The PREAD_PROCESS_MEMORY_ROUTINE64 type defines a pointer to this callback function. ReadProcessMemoryProc64 is a placeholder for the application-defined function name.

This function supersedes the ReadProcessMemoryProc function. For more information, see Updated Platform Support.

BOOL CALLBACK ReadProcessMemoryProc64(
  HANDLE hProcess,
  DWORD64 lpBaseAddress,
  PVOID lpBuffer,
  DWORD nSize,
  LPDWORD lpNumberOfBytesRead
);

Parameters

hProcess
[in] Handle to the process for which the stack trace is generated.
lpBaseAddress
[in] Base address of the memory to be read.
lpBuffer
[in] Pointer to a buffer that receives the memory to be read.
nSize
[in] Size of the memory to be read, in bytes.
lpNumberOfBytesRead
[in] Pointer to a variable that receives the number of bytes actually read.

Return Values

If the function succeeds, the return value should be TRUE. If the function fails, the return value should be FALSE.

Remarks

This function should read as much of the requested memory as possible. The StackWalk64 function handles the case where only part of the requested memory is read.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, StackWalk64


SearchTreeForFile

The SearchTreeForFile function searches a directory tree for a specified file.

BOOL SearchTreeForFile(
  PSTR RootPath,
  PSTR InputPathName,
  PSTR OutputPathBuffer
);

Parameters

RootPath
[in] Pointer to a null-terminated string that specifies the path where the function should begin searching for the file.
InputPathName
[in] Pointer to a null-terminated string that specifies the file for which the function will search. You can use a partial path.
OutputPathBuffer
[out] Pointer to a buffer that receives the full path to the file that is found. This string is not modified if the return value is FALSE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The function searches for the file specified by the InputPathName parameter beginning at the path specified in the RootPath parameter. The maximum path depth that is allowed in the RootPath is 32 directories. When the function finds the file in the directory tree, it places the full path to the file in the buffer specified by the OutputPathBuffer parameter. The underlying file system specifies the order of the subdirectory search.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions


StackWalk64

The StackWalk64 function provides a portable method for obtaining a stack trace.

This function supersedes the StackWalk function. For more information, see Updated Platform Support.

BOOL StackWalk64(
  DWORD MachineType,
  HANDLE hProcess,
  HANDLE hThread,
  LPSTACKFRAME64 StackFrame,
  PVOID ContextRecord,
  PREAD_PROCESS_MEMORY_ROUTINE64 ReadMemoryRoutine,
  PFUNCTION_TABLE_ACCESS_ROUTINE64 FunctionTableAccessRoutine,
  PGET_MODULE_BASE_ROUTINE64 GetModuleBaseRoutine,
  PTRANSLATE_ADDRESS_ROUTINE64 TranslateAddress
);

Parameters

MachineType
[in] Architecture type of the computer for which the stack trace is generated. This parameter can be one of the following values.
Value | Meaning
IMAGE_FILE_MACHINE_I386 | Intel (32-bit)
IMAGE_FILE_MACHINE_IA64 | Intel (64-bit)
IMAGE_FILE_MACHINE_AMD64 | AMD (64-bit)

hProcess
[in] Handle to the process for which the stack trace is generated. If the caller supplies a valid callback pointer for the ReadMemoryRoutine parameter, then this value does not have to be a valid process handle. It can be a token that is unique and consistently the same for all calls to the StackWalk64 function. If the symbol handler is used with StackWalk64, use the same process handles for the calls to each function.
hThread
[in] Handle to the thread for which the stack trace is generated. If the caller supplies a valid callback pointer for the ReadMemoryRoutine parameter, then this value does not have to be a valid thread handle. It can be a token that is unique and consistently the same for all calls to the StackWalk64 function.
StackFrame
[in/out] Pointer to a STACKFRAME64 structure. This structure receives information for the next frame, if the function call succeeds.
ContextRecord
[in/out] Pointer to a CONTEXT structure. This parameter is required only when the MachineType parameter is not IMAGE_FILE_MACHINE_I386. However, it is recommended that this parameter contain a valid context record. This allows StackWalk64 to handle a greater variety of situations.

This context may be modified, so do not pass a context record that should not be modified.

ReadMemoryRoutine
[in] Pointer to a callback routine that provides memory read services. When the StackWalk64 function needs to read memory from the process's address space, the ReadProcessMemoryProc64 callback is used.

If this parameter is NULL, then the function uses a default routine. In this case, the hProcess parameter must be a valid process handle.

FunctionTableAccessRoutine
[in] Pointer to a callback routine that provides access to the run-time function table for the process. For RISC computers, this function accesses the pdata table, while on X86 computers this function accesses the fpo table. This parameter is required because the StackWalk64 function does not have access to the process's run-time function table. For more information, see FunctionTableAccessProc64.

The symbol handler provides functions that load and access the run-time table. If these functions are used, then SymFunctionTableAccess64 can be passed as a valid parameter.

GetModuleBaseRoutine
[in] Pointer to a callback routine that provides a module base for any given virtual address. This parameter is required. For more information, see GetModuleBaseProc64.

The symbol handler provides functions that load and maintain module information. If these functions are used, then SymGetModuleBase64 can be passed as a valid parameter.

TranslateAddress
[in] Pointer to a callback routine that provides address translation for 16-bit addresses. For more information, see TranslateAddressProc64.

Most callers of StackWalk64 can safely pass NULL for this parameter.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Note that StackWalk64 generally does not set the last error code.

Remarks

The StackWalk64 function provides a portable method for obtaining a stack trace. Using the StackWalk64 function is recommended over writing your own function because of all the complexities associated with stack walking on platforms. In addition, there are compiler options that cause the stack to appear differently, depending on how the module is compiled. By using this function, your application has a portable stack trace that continues to work as the compiler and operating system change.

The first call to this function will fail if the AddrPC and AddrFrame members of the STACKFRAME64 structure passed in the StackFrame parameter are not initialized.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, CONTEXT, FunctionTableAccessProc64, GetModuleBaseProc64, ReadProcessMemoryProc64, STACKFRAME64, TranslateAddressProc64


SymAddSymbol

The SymAddSymbol function adds a virtual symbol to the specified module.

BOOL SymAddSymbol(
  HANDLE  hProcess,
  ULONG64  BaseOfDll,
  PCSTR  Name,
  DWORD64  Address,
  DWORD  Size,
  DWORD  Flags
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
BaseOfDll
[in] Base address of the module.
Name
[in] Pointer to a null-terminated string that specifies the name of the symbol. The maximum size of a symbol name is MAX_SYM_NAME characters.
Address
[in] Address of the symbol. This address must be within the address range of the specified module.
Size
[in] Size of the symbol, in bytes. This parameter is optional.
Flags
[in] Unused.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymDeleteSymbol


SymbolServer

The SymbolServer function is an entry point to the symbol server DLL. It is used to locate a symbol file. The PSYMBOLSERVERPROC type defines a pointer to this callback function. SymbolServer is a placeholder for the library-defined function name.

BOOL CALLBACK SymbolServer(
  LPCSTR params,
  LPCSTR filename,
  PVOID  id,
  DWORD  two,
  DWORD  three,
  LPSTR  path
);

Parameters

params
[in] Pointer to a string that specifies server-specific information. This information is used to identify which store to use for locating symbols. For more information, see Symbol Servers and Symbol Stores.
filename
[in] Name of the symbol file to be returned.
id
[in] First of three identifying parameters (see Remarks).
two
[in] Second of three identifying parameters (see Remarks).
three
[in] Third of three identifying parameters (see Remarks).
path
[out] Pointer to a buffer that receives the fully qualified path to the symbol file. This buffer should be at least MAX_PATH bytes.

Return Values

If the server locates a valid symbol file, it returns TRUE; otherwise, it returns FALSE and GetLastError returns a value that indicates why the symbol file was not returned.

Remarks

The identifying parameters are filled in as follows.

  • If DbgHelp is looking for a .dbg file, the id parameter contains the TimeDateStamp of the original image as found in its PE header. Parameter two contains the SizeOfImage field, also extracted from the PE header. Parameter three is unused and set to zero.
  • If DbgHelp is looking for a .pdb file, the id parameter contains the PDB signature as found in the codeview debug directory of the original image. Parameter two contains the PDB age. Parameter three is unused and set to zero.
  • If DbgHelp is looking for any other type of image, such as an executable file, it is probably being called through the SymFindFileInPath function. In this case, the parameters are opaque to DbgHelp. However, if this function is being used to retrieve an executable file, it is expected that the parameters will be filled in as for a .dbg file, using TimeDateStamp and the image size as parameters.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions, SymFindFileInPath


SymbolServerCallback

The SymbolServerCallback function is an entry point to the symbol server DLL. The PSYMBOLSERVERCALLBACKPROC type defines a pointer to this callback function. SymbolServerCallback is a placeholder for the library-defined function name.

BOOL SymbolServerCallback(
  UINT_PTR action,
  ULONG64 data,
  ULONG64 context
);

Parameters

action
Action code. At this time, this parameter can be SSRVACTION_TRACE to provide debug trace information.
data
Text string.
context
Ignored.

Return Values

To indicate success, return TRUE.

To indicate failure, return FALSE and call the SetLastError function to indicate an error condition. If you do not handle SSRVACTION_TRACE, you should also return FALSE. (Returning TRUE in this case may have unintended consequences.)

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions


SymbolServerClose

The SymbolServerClose function is an entry point to the symbol server DLL. It is called every time the SymCleanup function is called. The PSYMBOLSERVERCLOSEPROC type defines a pointer to this callback function. SymbolServerClose is a placeholder for the library-defined function name.

BOOL SymbolServerClose( );

Parameters

This function has no parameters.

Return Values

The server can return TRUE to indicate success, or return FALSE and call the SetLastError function to indicate an error condition.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions


SymbolServerGetOptions

The SymbolServerGetOptions function is an entry point to the symbol server DLL. It is used to retrieve the symbol server options. The PSYMBOLSERVERGETOPTIONSPROC type defines a pointer to this callback function. SymbolServerGetOptions is a placeholder for the library-defined function name.

UINT_PTR CALLBACK SymbolServerGetOptions();

Parameters

This function has no parameters.

Return Values

The function returns the symbol server options that have been set.

Remarks

If you are using SymSrv (symsrv.dll) as your symbol server, the return value will be a combination of the following values.

Value | Meaning
SSRVOPT_CALLBACK | SymSrv is expecting a callback function of type PSYMBOLSERVERCALLBACKPROC. For more information, see SymbolServerCallback.
SSRVOPT_NOCOPY | SymSrv will not verify that the path parameter passed out by the SymbolServer function actually exists. In this case, SymbolServer will always return a TRUE value.
SSRVOPT_PARENTWIN | SymSrv is using a user-specified window as the parent window of all dialog boxes and popups, rather than using the desktop window.
SSRVOPT_PARAMTYPE | Data type of the id parameter passed to the SymbolServer function. The following values for data are permitted: SSRVOPT_DWORD (default) SSRVOPT_DWORDPTR SSRVOPT_GUIDPTR
SSRVOPT_SECURE | Windows .NET Server: SymSrv will not use the downstream store specified in _NT_SYMBOL_PATH.
SSRVOPT_TRACE | Windows .NET Server: SymSrv will provide debug trace information.
SSRVOPT_UNATTENDED | SymSrv will not display dialog boxes or popups.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions, SymbolServerSetOptions


SymbolServerSetOptions

The SymbolServerSetOptions function is an entry point to the symbol server DLL. It is used to set the symbol server options. The PSYMBOLSERVERSETOPTIONSPROC type defines a pointer to this callback function. SymbolServerSetOptions is a placeholder for the library-defined function name.

BOOL CALLBACK SymbolServerSetOptions(
  UINT_PTR options,
  ULONG64  data
);

Parameters

options
Option to be set (see Remarks).
data
Server-specific option data. The format of this data depends on the value of options (see Remarks).

Return Values

The server can return TRUE to indicate success, or return FALSE and call the SetLastError function to indicate an error condition.

Remarks

If you are using SymSrv (symsrv.dll) as your symbol server, the options parameter should be one of the following values.

id | Meaning
SSRVOPT_CALLBACK Callback function.

The data parameter is a pointer to a callback function of type PSYMBOLSERVERCALLBACKPROC. For more information, see SymbolServerCallback.

If data is NULL, any previously-set callback function is ignored.
SSRVOPT_PARAMTYPE Data type of the id parameter passed to the SymbolServer function.

The data parameter is of type UINT_PTR and can be one of the following values:

SSRVOPT_DWORD (default);
SSRVOPT_DWORDPTR;
SSRVOPT_GUIDPTR

SSRVOPT_NOCOPY | If data is TRUE, SymSrv will not verify that the path parameter passed by the SymbolServer function actually exists. In this case, SymbolServer will always return TRUE.
SSRVOPT_PARENTWIN | The data parameter is an HWND value that specifies the handle to the parent window that should be used for all dialog boxes and popups. If data is NULL, SymSrv will use the desktop window as the parent (this is the default).
SSRVOPT_SECURE | Windows .NET Server: If data is TRUE, SymSrv will not use the downstream store specified in _NT_SYMBOL_PATH.
SSRVOPT_UNATTENDED | If data is TRUE, SymSrv will not display dialog boxes or popups. If data is FALSE, SymSrv will display these graphical features when making connections.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions, SymbolServerGetOptions


SymCleanup

The SymCleanup function deallocates all resources associated with the process handle.

BOOL SymCleanup(
  HANDLE hProcess
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

This function frees all resources associated with the process handle. Failure to call this function causes memory and resource leaks in the calling application

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, call SymInitialize only when your process starts and SymCleanup only when your process ends. It is not necessary for each thread in the process to call these functions.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymInitialize


SymDeleteSymbol

The SymDeleteSymbol function deletes a virtual symbol from the specified module.

BOOL SymDeleteSymbol(
  HANDLE  hProcess,
  ULONG64  BaseOfDll,
  PCSTR  Name,
  DWORD64  Address,
  DWORD  Flags
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
BaseOfDll
[in] Base address of the module.
Name
[in] Pointer to a null-terminated string that specifies the name of the symbol.
Address
[in] Address of the symbol. This address must be within the arrange range of the specified module.
Flags
[in] Unused.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymAddSymbol


SymEnumerateModules64

The SymEnumerateModules64 function enumerates all modules that have been loaded for the process by the SymLoadModule64 function.

This function supersedes the SymEnumerateModules function. For more information, see Updated Platform Support.

BOOL SymEnumerateModules64(
  HANDLE hProcess,
  PSYM_ENUMMODULES_CALLBACK64 EnumModulesCallback,
  PVOID UserContext
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
EnumModulesCallback
[in] Pointer to the enumeration callback function. This function is called once per module. For more information, see SymEnumerateModulesProc64.
UserContext
[in] User-defined value or NULL. This value is simply passed to the callback function. Normally, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some type of context.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymEnumerateModules64 function enumerates all modules that have been loaded for the process by SymLoadModule64, even if the symbol loading is deferred. The enumeration callback function is called once for each module and is passed the module information.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymEnumerateModulesProc64, SymInitialize, SymLoadModule64


SymEnumerateModulesProc64

The SymEnumerateModulesProc64 function is an application-defined callback function used with the SymEnumerateModules64 function. It is called once for each enumerated module, and receives the module information.

The PSYM_ENUMMODULES_CALLBACK64 type defines a pointer to this callback function. SymEnumerateModulesProc64 is a placeholder for the application-defined function name.

This function supersedes the SymEnumerateModulesProc function. For more information, see Updated Platform Support.

BOOL CALLBACK SymEnumerateModulesProc64(
  PSTR ModuleName,
  DWORD64 BaseOfDll,
  PVOID UserContext
);

Parameters

ModuleName
[in] Pointer to a null-terminated string that specifies the name of the module.
BaseOfDll
[in] Base address where the module is loaded into memory.
UserContext
[in] User-defined value specified in SymEnumerateModules64, or NULL. Typically, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some type of context.

Return Values

If the return value is TRUE, the enumeration will continue.

If the return value is FALSE, the enumeration will stop.

Remarks

The calling application is called once per module until all modules are enumerated, or until the enumeration callback function returns FALSE.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, SymEnumerateModules64


SymEnumerateSymbols64

The SymEnumerateSymbols64 function enumerates all the symbols for a specified module.

This function supersedes the SymEnumerateSymbols function. For more information, see Updated Platform Support.

Note This function is provided only for compatibility. Applications should use SymEnumSymbols, which is faster and more powerful.

BOOL SymEnumerateSymbols64(
  HANDLE hProcess,
  DWORD64 BaseOfDll,
  PSYM_ENUMSYMBOLS_CALLBACK64 EnumSymbolsCallback,
  PVOID UserContext
);

Parameters

hProcess
[in] Handle to the process. This handle must have been previously passed to the SymInitialize function.
BaseOfDll
[in] Base address of the module for which symbols are to be enumerated.
EnumSymbolsCallback
[in] Pointer to the callback function that receives the symbol information. For more information, see SymEnumerateSymbolsProc64.
UserContext
[in] User-defined value or NULL. This value is passed to the callback function. Typically, this parameter is used by an application to pass a pointer to a data structure that enables the callback function establish some type of context.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymEnumerateSymbols64 function enumerates all the symbols for the specified module. The module information is located by the BaseOfDll parameter. The EnumSymbolsCallback function is called once per symbol and is passed the information for each symbol.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymEnumerateSymbolsProc64, SymEnumSymbols, SymInitialize


SymEnumerateSymbolsProc64

The SymEnumerateSymbolsProc64 function is an application-defined callback function used with the SymEnumerateSymbols64 function. It is called once for each enumerated symbol, and receives the symbol information.

This function supersedes the SymEnumerateSymbolsProc function. For more information, see Updated Platform Support.

Note This function is provided only for compatibility. Applications should use SymEnumSymbols.

The PSYM_ENUMSYMBOLS_CALLBACK64 type defines a pointer to this callback function. SymEnumerateSymbolsProc64 is a placeholder for the application-defined function name.

BOOL CALLBACK SymEnumerateSymbolsProc64(
  PTSTR  SymbolName,
  DWORD64 SymbolAddress,
  ULONG SymbolSize,
  PVOID UserContext
);

Parameters

SymbolName
[in] Pointer to a null-terminated string that specifies the name of the symbol. The name can be undecorated if the SYMOPT_UNDNAME option is used with the SymSetOptions function.
SymbolAddress
[in] Virtual address for the beginning of the symbol.
SymbolSize
[in] Size of the symbol, in bytes. The size is calculated and is actually a best-guess value. In some cases, the value can be zero.
UserContext
[in] User-defined value specified in SymEnumerateSymbols64, or NULL. Typically, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some type of context.

Return Values

If the function returns TRUE, the enumeration will continue.

If the function returns FALSE, the enumeration will stop.

Remarks

The calling application is called once per symbol until all the symbols are enumerated or until the enumeration callback function returns FALSE.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, SymEnumerateSymbols64, SymEnumSymbols


SymEnumSymbols

The SymEnumSymbols function enumerates all symbols in a process.

BOOL SymEnumSymbols(
  HANDLE  hProcess,
  ULONG64  BaseOfDll,
  PCSTR  Mask,
  PSYM_ENUMERATESYMBOLS_CALLBACK  EnumSymbolsCallback,
  PVOID  UserContext
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
BaseOfDll
[in] Base address of the module. If this value is zero and Mask contains an exclamation point (!), the function looks across modules. If this value is zero and Mask does not contain an exclamation point, the function uses the scope established by the SymSetContext function.
Mask
[in] Regular expression that indicates the names of the symbols to be enumerated. To specify a module name, use the !mod syntax.
EnumSymbolsCallback
[in] Pointer to a SymEnumSymbolsProc callback function that receives the symbol information.
UserContext
[in] User-defined value that is passed to the callback function, or NULL. This parameter is typically used by an application to pass a pointer to a data structure that provides context for the callback function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymEnumSymbolsProc


SymEnumSymbolsForAddr

The SymEnumSymbolsForAddr function enumerates the symbols for the specified address.

BOOL SymEnumSymbolsForAddr(
  HANDLE  hProcess,
  DWORD64  Address,
  PSYM_ENUMERATESYMBOLS_CALLBACK  EnumSymbolsCallback,
  PVOID  UserContext
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
Address
[in] Address for which symbols are to be located. The address does not have to be on a symbol boundary. If the address comes after the beginning of a symbol and before the end of the symbol (the beginning of the symbol plus the symbol size), the function will find the symbol.
EnumSymbolsCallback
[in] Pointer to an application-defined callback function. This function is called for every symbol found at Address. For more information, see SymEnumSymbolsProc.
UserContext
[in] User-defined data. This value is passed to the callback function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymEnumSymbolsProc


SymEnumSymbolsProc

The SymEnumSymbolsProc function is an application-defined callback function used with the SymEnumSymbols or SymEnumTypes function.

The PSYM_ENUMERATESYMBOLS_CALLBACK type defines a pointer to this callback function. SymEnumSymbolsProc is a placeholder for the application-defined function name.

BOOL CALLBACK SymEnumSymbolsProc(
  PSYMBOL_INFO  pSymInfo,
  ULONG  SymbolSize,
  PVOID  UserContext
);

Parameters

pSymInfo
[in] Pointer to a SYMBOL_INFO structure that provides information about the symbol.
SymbolSize
[in] Size of the symbol, in bytes. The size is calculated and is actually a guess. In some cases, this value can be zero.
UserContext
[in] User-defined value passed from the SymEnumSymbols or SymEnumTypes function, or NULL. This parameter is typically used by an application to pass a pointer to a data structure that provides context information for the callback function.

Return Values

If the function returns TRUE, the enumeration will continue.

If the function returns FALSE, the enumeration will stop.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions, SymEnumSymbols, SymEnumTypes


SymEnumTypes

The SymEnumTypes function enumerates all user-defined types.

BOOL SymEnumTypes(
  HANDLE  hProcess,
  ULONG64  BaseOfDll,
  PSYM_ENUMERATESYMBOLS_CALLBACK  EnumSymbolsCallback,
  PVOID  UserContext
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
BaseOfDll
[in] Base address of the module.
EnumSymbolsCallback
[in] Pointer to an SymEnumSymbolsProc callback function that receives the symbol information.
UserContext
[in] User-defined value which is passed to the callback function, or NULL. This parameter is typically used by an application to pass a pointer to a data structure that provides context information for the callback function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymEnumSymbolsProc


SymFindFileInPath

The SymFindFileInPath function is used to locate a symbol file.

BOOL SymFindFileInPath(
  HANDLE hprocess,
  LPSTR  SearchPath,
  LPSTR  FileName,
  PVOID  id,
  DWORD  two,
  DWORD  three,
  DWORD  flags,
  LPSTR  FilePath,
  PFINDFILEINPATHCALLBACK callback,
  PVOID context
);

Parameters

hprocess
[in] Handle to the process that was originally passed to the SymInitialize function.
SearchPath
[in] Pointer to a null-terminated string that specifies the path where symbol files are located. This can be multiple paths separated by semicolons. If this parameter is NULL, the function uses the symbol path set using the SymSetSearchPath function.
FileName
[in] Pointer to a null-terminated string that specifies the name of the file. You can use a partial path.
id
[in] First of three identifying parameters (see Remarks).
two
[in] Second of three identifying parameters (see Remarks).
three
[in] Third of three identifying parameters (see Remarks).
flags
[in] Format of the id parameter. This parameter can be one of the following values.
Value | Meaning
SSRVOPT_DWORD | The id parameter is a DWORD.
SSRVOPT_DWORDPTR | The id parameter is a pointer to a DWORD.
SSRVOPT_GUIDPTR | The id parameter is a pointer to a GUID.

FilePath
[out] Pointer to a buffer that receives the fully qualified path to the symbol file. This buffer must be at least MAX_PATH bytes.
callback
[in] Pointer to a callback function. For more information, see SymFindFileInPathProc.
context
[in] User-defined value or NULL. This value is simply passed to the callback function. This parameter is typically used by an application to pass a pointer to a data structure that provides some context for the callback function.

Return Values

If the server locates a valid symbol file, it returns TRUE; otherwise, it returns FALSE and GetLastError returns a value that indicates why the symbol file was not returned.

Remarks

The identifying parameters are filled in as follows:

  • If DbgHelp is looking for a .pdb file, the id parameter specifies the PDB signature as found in the codeview debug directory of the original image. Parameter two specifies the PDB age. Parameter three is unused and set to zero.
  • If DbgHelp is looking for any other type of image, such as an executable file or .dbg file, the id parameter specifies the TimeDateStamp of the original image as found in its PE header. Parameter two specifies the SizeOfImage field, also extracted from the PE header. Parameter three is unused and set to zero.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymFindFileInPathProc, SymInitialize, SymSetSearchPath


SymFindFileInPathProc

The SymFindFileInPathProc function is an application-defined callback function used with the SymFindFileInPath function.

The PFINDFILEINPATHCALLBACK type defines a pointer to this callback function. SymFindFileInPathProc is a placeholder for the application-defined function name.

BOOL SymFindFileInPathProc(
  PSTR  fileName,
  PVOID context
);

Parameters

fileName
[in] Pointer to a null-terminated string that specifies the name of the file. This string can be a partial path.
context
[in] User-defined value specified in SymFindFileInPath, or NULL. This parameter is typically used by an application to pass a pointer to a data structure that provides some context for the callback function.

Return Values

Return TRUE to indicate success.

Return FALSE to indicate failure.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Functions, SymFindFileInPath


SymFromAddr

The SymFromAddr function retrieves symbol information for the specified address.

BOOL SymFromAddr(
  HANDLE  hProcess,
  DWORD64  Address,
  PDWORD64  Displacement,
  PSYMBOL_INFO  Symbol
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
Address
[in] Address for which a symbol should be located. The address does not have to be on a symbol boundary. If the address comes after the beginning of a symbol and before the end of the symbol, the symbol is found.
Displacement
[out] Displacement from the beginning of the symbol, or zero.
Symbol
[in, out] Pointer to a SYMBOL_INFO structure that provides information about the symbol.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SYMBOL_INFO


SymFromName

The SymFromName function retrieves symbol information for the specified name.

BOOL SymFromName(
  HANDLE  hProcess,
  LPSTR  Name,
  PSYMBOL_INFO  Symbol
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
Name
[in] Pointer to a null-terminated string that specifies the name of the symbol to be located.
Symbol
[out] Pointer to a SYMBOL_INFO structure that provides information about the symbol.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SYMBOL_INFO


SymFunctionTableAccess64

The SymFunctionTableAccess64 function retrieves the function table entry for the specified address.

This function supersedes the SymFunctionTableAccess function. For more information, see Updated Platform Support.

PVOID SymFunctionTableAccess64(
  HANDLE hProcess,
  DWORD64 AddrBase
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
AddrBase
[in] Base address for which function table information is required.

Return Values

If the function succeeds, the return value is a pointer to the function table entry. The page in memory that contains the function table entry is marked as read-only. Any attempt to write to the returned pointer results in an access violation exception.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The type of pointer returned is specific to the image from which symbols are loaded. If the image is from an Intel x86 computer, this is a pointer to an FPO_DATA structure. If the image is for any of the RISC platforms supported by Windows NT, this is a pointer to an IMAGE_FUNCTION_ENTRY structure.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, FPO_DATA, IMAGE_FUNCTION_ENTRY, SymInitialize


SymGetLineFromAddr64

The SymGetLineFromAddr64 function locates the source line for the specified address.

This function supersedes the SymGetLineFromAddr function. For more information, see Updated Platform Support.

BOOL SymGetLineFromAddr64(
  HANDLE hProcess,
  DWORD64 dwAddr,
  PDWORD pdwDisplacement,
  PIMAGEHLP_LINE64 Line
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
dwAddr
[in] Address for which a line should be located. It is not necessary for the address to be on a line boundary. If the address appears after the beginning of a line and before the end of the line, the line is found.
pdwDisplacement
[out] Displacement from the beginning of the line, or zero.
Line
[out] Pointer to an IMAGEHLP_LINE64 structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The caller must allocate the Line buffer properly and fill in the required members of the IMAGEHLP_LINE64 structure before calling SymGetLineFromAddr64.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_LINE64, SymGetLineFromName64, SymInitialize


SymGetLineFromName64

The SymGetLineFromName64 function locates a source line for the specified module, file name, and line number.

This function supersedes the SymGetLineFromName function. For more information, see Updated Platform Support.

BOOL SymGetLineFromName64(
  HANDLE hProcess,
  PSTR ModuleName,
  PSTR FileName,
  DWORD dwLineNumber,
  PLONG lpDisplacement,
  PIMAGEHLP_LINE64 Line
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
ModuleName
[in] Pointer to a null-terminated string that specifies the name of the module in which a line is to be located.
FileName
[in] Pointer to a null-terminated string that specifies the name of the file in which a line is to be located.
dwLineNumber
[in] Line number to be located.
lpDisplacement
[out] Displacement from the beginning of the line, or zero.
Line
[in/out] Pointer to an IMAGEHLP_LINE64 structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The caller must allocate the Line buffer properly and fill in the required members of the IMAGEHLP_LINE64 structure before calling SymGetLineFromName64.

Before calling this function, ensure that the symbols are initialized correctly by first calling SymInitialize, SymSetOptions, and SymLoadModule64.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_LINE64, SymGetLineFromAddr64, SymInitialize


SymGetLineNext64

The SymGetLineNext64 function retrieves the line information for the next source line.

This function supersedes the SymGetLineNext function. For more information, see Updated Platform Support.

BOOL SymGetLineNext64(
  HANDLE hProcess,
  PIMAGEHLP_LINE64 Line
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
Line
[in/out] Pointer to an IMAGEHLP_LINE64 structure that contains the line information.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymGetLineNext64 function requires that the IMAGEHLP_LINE64 structure have valid data, presumably obtained from a call to the SymGetLineFromAddr64 or SymGetLineFromName64 function. This structure receives the line information for the next line in sequence.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_LINE64, SymGetLineFromAddr64, SymGetLineFromName64, SymGetLinePrev64, SymInitialize


SymGetLinePrev64

The SymGetLinePrev64 function retrieves the line information for the previous source line.

This function supersedes the SymGetLinePrev function. For more information, see Updated Platform Support.

BOOL SymGetLinePrev64(
  HANDLE hProcess,
  PIMAGEHLP_LINE64 Line
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
Line
[in/out] Pointer to an IMAGEHLP_LINE64 structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymGetLinePrev64 function requires that the IMAGEHLP_LINE64 structure have valid data, presumably obtained from a call to the SymGetLineFromAddr64 or SymGetLineFromName64 function. This structure is filled with the line information for the previous line in sequence.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_LINE64, SymGetLineFromAddr64, SymGetLineFromName64, SymGetLineNext64, SymInitialize


SymGetModuleBase64

The SymGetModuleBase64 function retrieves the base address of the module that contains the specified address.

This function supersedes the SymGetModuleBase function. For more information, see Updated Platform Support.

DWORD64 SymGetModuleBase64(
  HANDLE hProcess,
  DWORD64 dwAddr
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
dwAddr
[in] Virtual address that is contained in one of the modules loaded by the SymLoadModule64 function.

Return Values

If the function succeeds, the return value is a nonzero virtual address. The value is the base address of the module containing the address specified by the dwAddr parameter.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Remarks

The module table is searched for a module that contains dwAddr. The module is located based on the load address and size of each module.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymInitialize, SymLoadModule64


SymGetModuleInfo64

The SymGetModuleInfo64 function retrieves the module information of the specified module.

This function supersedes the SymGetModuleInfo function. For more information, see Updated Platform Support.

BOOL SymGetModuleInfo64(
  HANDLE hProcess,
  DWORD64 dwAddr,
  PIMAGEHLP_MODULE64 ModuleInfo
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
dwAddr
[in] Virtual address that is contained in one of the modules loaded by the SymLoadModule64 function
ModuleInfo
[out] Pointer to an IMAGEHLP_MODULE64 structure. The SizeOfStruct member must be set to the size of the IMAGEHLP_MODULE64 structure. An invalid value will result in an error.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The module table is searched for a module that contains the dwAddr. The module is located based on the load address and size of each module. If a valid module is found, the ModuleInfo parameter is filled with the information about the module.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_MODULE64, SymInitialize, SymLoadModule64


SymGetOptions

The SymGetOptions function retrieves the current options mask.

DWORD SymGetOptions(VOID);

Parameters

This function has no parameters.

Return Values

The SymGetOptions function always returns the current options mask. Zero is a valid value and indicates that all options are turned off. The options values are masks that are combined using the OR operator to form a valid options value. The valid mask values are as follows.

Value | Meaning
SYMOPT_ALLOW_ABSOLUTE_SYMBOL | Windows .NET Server: Enables symbols that are stored with absolute addresses. Most symbols are stored as RVAs from the base of the module. DbgHelp translates them to absolute addresses. There are symbols that are stored as an absolute address. These have very specialized purposes and are typically not used.
SYMOPT_AUTO_PUBLICS | Windows .NET Server: Do not search the public symbols when searching for symbols by address, or when enumerating symbols, unless they were not found in the global symbols or within the current scope. This option has no effect with SYMOPT_PUBLICS_ONLY.
SYMOPT_CASE_INSENSITIVE | All symbol searches are insensitive to case.
SYMOPT_DEBUG | Pass debug output to the callback function as CBA_DEBUG.
SYMOPT_DEFERRED_LOADS | Symbols are not loaded until a reference is made requiring the symbols be loaded. This is the fastest, most efficient way to use the symbol handler.
SYMOPT_EXACT_SYMBOLS | Do not load an unmatched .pdb file. Do not load export symbols if all else fails.
SYMOPT_FAIL_CRITICAL_ERRORS | Do not display system dialog boxes when there is a media failure such as no media in a drive. Instead, the failure happens silently.
SYMOPT_IGNORE_CVREC | Ignore path information in the CodeView record of the image header when loading a .pdb file.
SYMOPT_IGNORE_NT_SYMPATH | Windows .NET Server: Do not use the path specified by _NT_SYMBOL_PATH if the user calls SymSetSearchPath without a valid path.
SYMOPT_INCLUDE_32BIT_MODULES | When debugging on 64-bit Windows, include any 32-bit modules.
SYMOPT_LOAD_ANYTHING | Disable checks to ensure a file (.exe, .dbg., or .pdb) is the correct file. Instead, load the first file located.
SYMOPT_LOAD_LINES | Loads line number information.
SYMOPT_NO_IMAGE_SEARCH | Windows .NET Server: Do not search the image for the symbol path when loading the symbols for a module if the module header cannot be read.
SYMOPT_NO_CPP | All C++ decorated symbols containing the symbol separator "::" are replaced by "__". This option exists for debuggers that cannot handle parsing real C++ symbol names.
SYMOPT_NO_PUBLICS | Windows .NET Server: Do not search the publics table for symbols. This option should have little effect because there are copies of the public symbols in the globals table.
SYMOPT_NO_UNQUALIFIED_LOADS | Prevents symbols from being loaded when the caller examines symbols across multiple modules. Examine only the module whose symbols have already been loaded.
SYMOPT_PUBLICS_ONLY | Windows .NET Server: Do not use private symbols. The version of DbgHelp that shipped with Windows 2000 and earlier supported only public symbols; this option provides compatibility with this limitation.
SYMOPT_SECURE | Windows .NET Server: DbgHelp will not load any symbol server other than SymSrv. SymSrv will not use the downstream store specified in _NT_SYMBOL_PATH.
SYMOPT_UNDNAME | All symbols are presented in undecorated form. This option has no effect on global or local symbols because they are stored undecorated. This option applies only to public symbols.

Remarks

The options value can be changed several times while the library is in use by an application. The option change affects all future calls to the symbol handler.

To set the current options mask, use the SymSetOptions function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions


SymGetSearchPath

The SymGetSearchPath function retrieves the symbol search path for the specified process.

BOOL SymGetSearchPath(
  HANDLE hProcess,
  PSTR SearchPath,
  DWORD SearchPathLength
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
SearchPath
[out] Pointer to the buffer that receives the symbol search path.
SearchPathLength
[in] Size of the SearchPath buffer, in bytes.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymGetSearchPath function copies the symbol search path for the specified process into the SearchPath buffer. If the function fails, the contents of the buffer are undefined.

To specify a symbol search path for the process, use the SymSetSearchPath function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymInitialize, SymSetSearchPath


SymGetSymFromAddr64

The SymGetSymFromAddr64 function locates the symbol for the specified address.

This function supersedes the SymGetSymFromAddr function. For more information, see Updated Platform Support.

Note This function is provided only for compatibility. Applications should use SymFromAddr.

BOOL SymGetSymFromAddr64(
  HANDLE hProcess,
  DWORD64 Address,
  PDWORD64 Displacement,
  PIMAGEHLP_SYMBOL64 Symbol
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
Address
[in] Address for which a symbol is to be located. The address does not have to be on a symbol boundary. If the address comes after the beginning of a symbol and before the end of the symbol (the beginning of the symbol plus the symbol size), the symbol is found.
Displacement
[out] Displacement from the beginning of the symbol, or zero.
Symbol
[out] Pointer to an IMAGEHLP_SYMBOL64 structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymGetSymFromAddr64 function locates the symbol for a specified address. The modules are searched for the one the address belongs to. When the module is found, its symbol table is searched for a match. When the symbol is found, the symbol information is copied into the Symbol buffer provided by the caller. The caller must allocate the Symbol buffer properly and fill in the required parameters in the IMAGEHLP_SYMBOL64 structure before calling SymGetSymFromAddr64.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_SYMBOL64, SymFromAddr, SymInitialize


SymGetSymFromName64

The SymGetSymFromName64 function locates a symbol for the specified name.

This function supersedes the SymGetSymFromName function. For more information, see Updated Platform Support.

Note This function is provided only for compatibility. Applications should use SymFromName.

BOOL SymGetSymFromName64(
  HANDLE hProcess,
  PSTR Name,
  PIMAGEHLP_SYMBOL64 Symbol
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
Name
[in] Pointer to a null-terminated string that specifies the symbol name for which a symbol is to be located.
Symbol
[out] Pointer to an IMAGEHLP_SYMBOL64 structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymGetSymFromName64 function is used to locate a symbol for a specified name. The name can contain a module prefix that isolates the symbol search to a single module's symbol table.

The module prefix is in the form of "module!". The "!" character is the delimiter between the module name and the symbol name. If there is no module prefix, then the search is performed on each module's symbol table in a linear manner, beginning with the first module that is loaded.

Using the module prefix is preferable for two reasons. First, the symbol search occurs much faster. Second, when deferred symbol loading is turned on, the search causes symbols to be loaded for each module that is searched. When the symbol is found, the symbol information is copied into the Symbol buffer provided by the caller. The caller must allocate the Symbol buffer properly and fill in the required parameters in the IMAGEHLP_SYMBOL64 structure before calling SymGetSymFromName64.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_SYMBOL64, SymFromName, SymInitialize


SymGetSymNext64

The SymGetSymNext64 function retrieves the symbol information of the next symbol.

This function supersedes the SymGetSymNext function. For more information, see Updated Platform Support.

BOOL SymGetSymNext64(
  HANDLE hProcess,
  PIMAGEHLP_SYMBOL64 Symbol
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
Symbol
[in/out] Pointer to an IMAGEHLP_SYMBOL64 structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymGetSymNext64 function requires that the IMAGEHLP_SYMBOL64 structure have valid data, presumably obtained from a call to the SymGetSymFromAddr64 or SymGetSymFromName64 function. This structure is filled with the symbol information for the next symbol in sequence by virtual address.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_SYMBOL64, SymGetSymFromAddr64, SymGetSymFromName64, SymGetSymPrev64, SymInitialize


SymGetSymPrev64

The SymGetSymPrev64 function retrieves the symbol information of the previous symbol.

This function supersedes the SymGetSymPrev function. For more information, see Updated Platform Support.

BOOL SymGetSymPrev64(
  HANDLE hProcess,
  PIMAGEHLP_SYMBOL64 Symbol
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
Symbol
[in/out] Pointer to an IMAGEHLP_SYMBOL64 structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymGetSymPrev64 function requires the IMAGEHLP_SYMBO64L structure to have valid data, presumably obtained from a call to the SymGetSymFromAddr64 or SymGetSymFromName64 function. This structure is filled in with the symbol information for the previous symbol in sequence by virtual address.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_SYMBOL64, SymGetSymFromAddr64, SymGetSymFromName64, SymGetSymNext64, SymInitialize


SymGetTypeFromName

The SymGetTypeFromName function retrieves a type index for the specified type name.

BOOL SymGetTypeFromName(
  HANDLE  hProcess,
  ULONG64  BaseOfDll,
  LPSTR  Name,
  PSYMBOL_INFO  Symbol
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
BaseOfDll
[in] Base address of the module.
Name
[in] Pointer to a null-terminated string that specifies the name of the type.
Symbol
[out] Pointer to a SYMBOL_INFO structure. The TypeIndex member contains the type index.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

To retrieve information about the type, pass the type index to the SymGetTypeInfo function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SYMBOL_INFO, SymGetTypeInfo


SymGetTypeInfo

The SymGetTypeInfo function retrieves type information for the specified type index.

BOOL SymGetTypeInfo(
  HANDLE  hProcess,
  DWORD64  ModBase,
  ULONG  TypeId,
  IMAGEHLP_SYMBOL_TYPE_INFO  GetType,
  PVOID pInfo
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
ModBase
[in] Base address of the module.
TypeId
[in] Type index. (A number of functions return a type index in the TypeIndex member of the SYMBOL_INFO structure.)
GetType
[in] Information type. This parameter can be one of more of the following values.
Value | Meaning
TI_FINDCHILDREN Type index of all children in pInfo.

The pInfo parameter is a pointer to a TI_FINDCHILDREN_PARAMS structure. The Count member should be initialized with the number of children.
TI_GET_ADDRESS Index address.

The pInfo parameter is of type ULONG64*.
TI_GET_ADDRESSOFFSET Address offset.

The pInfo parameter is of type DWORD*.
TI_GET_ARRAYINDEXTYPEID Type index for index of an array type.

The pInfo parameter is of type DWORD*.
TI_GET_BASETYPE Base type for the type index.

The pInfo parameter is of type DWORD*.
TI_GET_BITPOSITION Bit position of a bitfield.

The pInfo parameter is of type DWORD*.
TI_GET_CHILDRENCOUNT Number of children.

The pInfo parameter is of type DWORD*.
TI_GET_CLASSPARENTID Type index of class parent.

The pInfo parameter is of type DWORD*.
TI_GET_COUNT Count of array elements.

The pInfo parameter is of type DWORD*.
TI_GET_DATAKIND Data kind.

The pInfo parameter is of type DWORD*.
TI_GET_LENGTH Length of the type.

The pInfo parameter is of type ULONG64*.
TI_GET_LEXICALPARENT Lexical parent of the type.

The pInfo parameter is of type DWORD*.
TI_GET_NESTED If type index is nested, *pInfo is TRUE. Otherwise, it is FALSE.

The pInfo parameter is of type DWORD*.
TI_GET_OFFSET Offset of the type in parent. Members can use this to get their offset in a structure.

The pInfo parameter is of type DWORD*.
TI_GET_SYMINDEX Symbol index for a type.

The pInfo parameter is of type DWORD*.
TI_GET_SYMNAME Symbol name.

The pInfo parameter is of type WCHAR**. The caller must free the buffer.
TI_GET_SYMTAG Symbol tag.

The pInfo parameter is of type DWORD*.
TI_GET_THISADJUST | Offset from the "this" pointer to the actual "this" value.
TI_GET_TYPEID Type index.

The pInfo parameter is of type DWORD*.
TI_GET_UDTKIND Windows .NET Server: UDT kind.

The pInfo parameter is of type DWORD*.
TI_GET_VALUE Value of constants and enumeration values.

The pInfo parameter is of type VARIANT*.
TI_GET_VIRTUALBASECLASS Type index of base class of caller's type index.

The pInfo parameter is of type DWORD*.
TI_GET_VIRTUALBASEPOINTEROFFSET Offset of virtual base pointer.

The pInfo parameter is of type DWORD*.
TI_GET_VIRTUALTABLESHAPEID | Symbol interface of the type of virtual table, for a user-defined type.
TI_IS_EQUIV_TO Windows .NET Server: Returns S_OK is the two types are equivalent, and S_FALSE otherwise.

The pInfo parameter is of type DWORD*.

pInfo
[out] Data. The format of the data depends on the value of the GetType parameter.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

For more details on the type information, see the documentation for the PDB format.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SYMBOL_INFO, SymGetTypeFromName, TI_FINDCHILDREN_PARAMS


SymInitialize

The SymInitialize function initializes the symbol handler for a process.

BOOL SymInitialize(
  HANDLE hProcess,
  PSTR UserSearchPath,
  BOOL fInvadeProcess
);

Parameters

hProcess
[in] Handle to the process for which symbols are to be maintained. If the application is a debugger, use the process handle for the object being debugged, otherwise use the GetCurrentProcess function to obtain the process handle.

Windows 95/98/Me: Use the process identifier, not the process handle.

UserSearchPath
[in] Pointer to a null-terminated string that specifies a path, or series of paths separated by a semicolon (;), that is used to search for symbol files. If a value of NULL is used, then the library attempts to form a symbol path from the following sources:
  • The current working directory of the application
  • The _NT_SYMBOL_PATH environment variable
  • The _NT_ALTERNATE_SYMBOL_PATH environment variable
fInvadeProcess
[in] If this value is TRUE, enumerates the loaded modules for the process and effectively calls the SymLoadModule64 function for each module.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymInitialize function is used to initialize the symbol handler for a process. In the context of the symbol handler, a process is a convenient object to use when collecting symbol information. Usually, symbol handlers are used by debuggers and other tools that need to load symbols for a process being debugged.

The process handle passed to SymInitialize can be any unique value, except in the case when fInvadeProcess is TRUE. The value passed to SymInitialize must be the same value passed to all other symbol handler functions. It is the process handle that the functions use to identify the caller and locate the correct symbol information. When you have finished using the symbol information, call the SymCleanup function to deallocate all resources associated with the process for which symbols are loaded.

The search for symbols files is performed recursively for all paths specified in the UserSearchPath parameter. Therefore, if you specify the root directory in a search, the whole drive is searched, which can take significant time. Note that the directory that contains the executable file for the process is not automatically part of the search path. To include this directory in the search path, call the GetModuleFileNameEx function, then add the path returned to UserSearchPath.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, call SymInitialize only when your process starts and SymCleanup only when your process ends. It is not necessary for each thread in the process to call these functions.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, GetModuleFileNameEx, SymCleanup, SymLoadModule64


SymLoadModule64

The SymLoadModule64 function loads the symbol table.

This function supersedes the SymLoadModule function. For more information, see Updated Platform Support.

DWORD64 SymLoadModule64(
  HANDLE hProcess,
  HANDLE hFile,
  PSTR ImageName,
  PSTR ModuleName,
  DWORD64 BaseOfDll,
  DWORD SizeOfDll
);

Parameters

hProcess
[in] Handle to the process. This handle must have been previously passed to the SymInitialize function.
hFile
[in] Handle to the file for the executable image. This argument is used mostly by debuggers, where the debugger passes the file handle obtained from a debugging event. A value of NULL indicates that hFile is not used.
ImageName
[in] Pointer to a null-terminated string that specifies the name of the executable image. This name can contain a partial path, a full path, or no path at all. If the file cannot be located by the name provided, the symbol search path is used.
ModuleName
[in] Pointer to a null-terminated string that specifies a shortcut name for the module. If the pointer value is NULL, the library creates a name using the base name of the symbol file.
BaseOfDll
[in] Load address of the module. If the value is zero, the library obtains the load address from the symbol file. The load address contained in the symbol file is not necessarily the actual load address. Debuggers and other applications having an actual load address should use the real load address when calling this function.
SizeOfDll
[in] Size of the module, in bytes. If the value is zero, the library obtains the size from the symbol file. The size contained in the symbol file is not necessarily the actual size. Debuggers and other applications having an actual size should use the real size when calling this function.

Return Values

If the function succeeds, the return value is the base address of the loaded module.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Remarks

The symbol handler creates an entry for the module and if the deferred symbol loading option is turned off, an attempt is made to load the symbols. If deferred symbol loading is enabled, the module is marked as deferred and the symbols are not loaded until a reference is made to a symbol in the module.

To unload the symbol table, use the SymUnloadModule64 function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymInitialize, SymUnloadModule64


SymLoadModuleEx

The SymLoadModuleEx function loads the symbol table for the specified module.

DWORD64 SymLoadModuleEx(
  HANDLE hProcess,
  HANDLE hFile,
  PSTR ImageName,
  PSTR ModuleName,
  DWORD64 BaseOfDll,
  DWORD DllSize,
  PMODLOAD_DATA Data,
  DWORD Flags
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
hFile
[in] Handle to the file for the executable image. This argument is used mostly by debuggers, where the debugger passes the file handle obtained from a debugging event. A value of NULL indicates that hFile is not used.
ImageName
[in] Pointer to a null-terminated string that specifies the name of the executable image. This name can contain a partial path, a full path, or no path at all. If the file cannot be located by the name provided, the symbol search path is used.
ModuleName
[in] Pointer to a null-terminated string that specifies a shortcut name for the module. If the pointer value is NULL, the library creates a name using the base name of the symbol file.
BaseOfDll
[in] Load address of the module. If the value is zero, the library obtains the load address from the symbol file. The load address contained in the symbol file is not necessarily the actual load address. Debuggers and other applications having an actual load address should use the real load address when calling this function.
DllSize
[in] Size of the module, in bytes. If the value is zero, the library obtains the size from the symbol file. The size contained in the symbol file is not necessarily the actual size. Debuggers and other applications having an actual size should use the real size when calling this function.
Data
[in] Pointer to a MODLOAD_DATA structure that represents headers other than the standard PE header. This parameter is optional and can be NULL.
Flags
[in] If this parameter is SLMFLAG_VIRTUAL, the function creates a virtual module named ModuleName at the address specified in BaseOfDll. To add symbols to this module, call the SymAddSymbol function.

Return Values

If the function succeeds, the return value is the base address of the loaded module.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Remarks

The symbol handler creates an entry for the module and if the deferred symbol loading option is turned off, an attempt is made to load the symbols. If deferred symbol loading is enabled, the module is marked as deferred and the symbols are not loaded until a reference is made to a symbol in the module.

To unload the symbol table, use the SymUnloadModule64 function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, MODLOAD_DATA, SymAddSymbol, SymUnloadModule64


SymMatchFileName

The SymMatchFileName function compares a string to a file name and path.

BOOL SymMatchFileName(
  PSTR FileName,
  PSTR Match,
  PSTR *FileNameStop,
  PSTR *MatchStop
);

Parameters

FileName
[in] Pointer to the file name to compare to the Match parameter.
Match
[in] Pointer to the string to compare to the FileName parameter.
FileNameStop
[out] Pointer to a string buffer that receives a pointer to the location in FileName where matching stopped. For a complete match, this value can be one character before FileName. This value can also be NULL.
MatchStop
[out] Pointer to a string buffer that receives a pointer to the location in Match where matching stopped. For a complete match, this value may be one character before Match. This value may be NULL.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

Because the match string can be a suffix of the complete file name, this function can be used to match a plain file name to a fully qualified file name.

Matching begins from the end of both strings and proceeds backward. Matching is case-insensitive and equates a backslash ('\') with a forward slash ('/').

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions


SymRegisterCallback64

The SymRegisterCallback64 function lets an application register a callback function for use by the symbol handler.

This function supersedes the SymRegisterCallback function. For more information, see Updated Platform Support.

BOOL SymRegisterCallback64(
  HANDLE hProcess,
  PSYMBOL_REGISTERED_CALLBACK64 CallbackFunction,
  ULONG64 UserContext
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
CallbackFunction
[in] Pointer to a callback function. For more information, see SymRegisterCallbackProc64.
UserContext
[in] User-defined value or NULL. This value is simply passed to the callback function. Normally, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some context.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymRegisterCallback64 function lets an application register a callback function for use by the symbol handler. The symbol handler calls the registered callback function when there is status or progress information for the application.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymRegisterCallbackProc64, SymInitialize


SymRegisterCallbackProc64

The SymRegisterCallbackProc64 function is an application-defined callback function used with the SymRegisterCallback64 function. It is called by the symbol handler.

The PSYMBOL_REGISTERED_CALLBACK64 type defines a pointer to this callback function. SymRegisterCallbackProc64 is a placeholder for the application-defined function name.

This function supersedes the SymRegisterCallbackProc function. For more information, see Updated Platform Support.

BOOL CALLBACK SymRegisterCallbackProc64(
  HANDLE hProcess,
  ULONG ActionCode,
  ULONG64 CallbackData,
  ULONG64 UserContext
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
ActionCode
[in] Callback code. This parameter can be one of the following values.
Code | Meaning
CBA_DEBUG_INFO | Display verbose information. The CallbackData parameter is a pointer to a string.
CBA_DEFERRED_SYMBOL_LOAD_CANCEL Deferred symbol loading has started. To cancel the symbol load, return TRUE.

The CallbackData parameter is NULL and should be ignored.
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE Deferred symbol load has completed.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure.
CBA_DEFERRED_SYMBOL_LOAD_FAILURE Deferred symbol load has failed.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure. The symbol handler will attempt to load the symbols again if the callback function sets the FileName member of this structure.
CBA_DEFERRED_SYMBOL_LOAD_PARTIAL Windows .NET Server: Deferred symbol load has partially completed. The symbol loader is unable to read the image header from either the image file or the specified module.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure. The symbol handler will attempt to load the symbols again if the callback function sets the FileName member of this structure.
CBA_DEFERRED_SYMBOL_LOAD_START Deferred symbol load has started.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure.
CBA_DUPLICATE_SYMBOL Duplicate symbols were found. This reason is used only in COFF or CodeView format.

The CallbackData parameter is a pointer to a IMAGEHLP_DUPLICATE_SYMBOL64 structure. To specify which symbol to use, set the SelectedSymbol member of this structure.
CBA_READ_MEMORY The loaded image has been read.

The CallbackData parameter is a pointer to a IMAGEHLP_CBA_READ_MEMORY structure.
CBA_SET_OPTIONS Symbol options have been updated. To retrieve the current options, call the SymGetOptions function.

The CallbackData parameter is NULL and should be ignored.
CBA_SYMBOLS_UNLOADED Symbols have been unloaded.

The CallbackData parameter is NULL and should be ignored.

CallbackData
[in] Data for the operation. The format of this data depends on the value of the ActionCode parameter.
UserContext
[in] User-defined value specified in SymRegisterCallback64, or NULL. Typically, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some context.

Return Values

To indicate success handling the code, return TRUE.

To indicate failure handling the code, return FALSE. If your code does not handle a particular code, you should also return FALSE. (Returning TRUE in this case may have unintended consequences.)

Remarks

The calling application gets called through the registered callback function as a result of another call to one of the symbol handler functions. The calling application must be prepared for the possible side effects that this can cause. If the application has only one callback function that is being used by multiple threads, then care may be necessary to synchronize some types of data access while in the context of the callback function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, IMAGEHLP_CBA_READ_MEMORY, IMAGEHLP_DEFERRED_SYMBOL_LOAD64, IMAGEHLP_DUPLICATE_SYMBOL64, SymRegisterCallback64


SymRegisterFunctionEntryCallback64

The SymRegisterFunctionEntryCallback64 function lets an application register a callback function for use by the stack walking procedure on Alpha computers.

This function supersedes the SymRegisterFunctionEntryCallback function. For more information, see Updated Platform Support.

BOOL SymRegisterFunctionEntryCallback64(
  HANDLE hProcess,
  PSYMBOL_FUNCENTRY_CALLBACK64 CallbackFunction,
  ULONG64 UserContext
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the StackWalk64 function.
CallbackFunction
[in] Pointer to a callback function. For more information, see SymRegisterFunctionEntryCallbackProc64.
UserContext
[in] User-defined value or NULL. This value is simply passed to the callback function. Normally, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some context.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SymRegisterFunctionEntryCallback64 function lets an application register a callback function for use by the stack walking procedure. The stack walking procedure calls the registered callback function when it is unable to locate a function table entry for an address. In most cases, the stack walking procedure locates the function table entries in the function table of the image containing the address. However, in situations where the function table entries are not in the image, this callback allows the debugger to provide the function table entry from another source. For example, run-time generated code on Alpha computers can define dynamic function tables to support exception handling and stack tracing.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymRegisterFunctionEntryCallbackProc64, StackWalk64


SymRegisterFunctionEntryCallbackProc64

The SymRegisterFunctionEntryCallbackProc64 function is an application-defined callback function used with the SymRegisterFunctionEntryCallback64 function. It is called by the stack walking procedure.

The PSYMBOL_FUNCENTRY_CALLBACK64 type defines a pointer to this callback function. SymRegisterFunctionEntryCallbackProc64 is a placeholder for the application-defined function name.

This function supersedes the SymRegisterFunctionEntryCallbackProc function. For more information, see Updated Platform Support.

PVOID CALLBACK SymRegisterFunctionEntryCallbackProc64(
  HANDLE hProcess,
  ULONG64 AddrBase,
  ULONG64 UserContext
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the StackWalk64 function.
AddrBase
[in] Address of an instruction for which the callback function should return a function table entry.
UserContext
[in] User-defined value specified in SymRegisterFunctionEntryCallback64, or NULL. Typically, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some context.

Return Values

Returning the value NULL indicates that no function table entry is available.

On success, return a pointer to an IMAGE_RUNTIME_FUNCTION_ENTRY structure. Refer to the header file WinNT.h for the definition of this function.

Remarks

The structure must be returned in exactly the form it exists in the process being debugged. Some members may be pointers to other locations in the process address space. The ReadProcessMemoryProc64 callback function may be called to retrieve the information at these locations.

The calling application gets called through the registered callback function as a result of a call to the StackWalk64 function. The calling application must be prepared for the possible side effects that this can cause. If the application has only one callback function that is being used by multiple threads, then it may be necessary to synchronize some types of data access while in the context of the callback function.

This function is similar to the FunctionTableAccessProc64 callback function. The difference is that FunctionTableAccessProc64 returns an IMAGE_FUNCTION_ENTRY structure, while this function returns an IMAGE_RUNTIME_FUNCTION_ENTRY structure.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, SymRegisterFunctionEntryCallback64


SymSetContext

The SymSetContext function sets context information used by the SymEnumSymbols function.

BOOL SymSetContext(
  HANDLE hProcess,
  PIMAGEHLP_STACK_FRAME StackFrame,
  PIMAGEHLP_CONTEXT Context
);

Parameters

hProcess
[in] Handle to a process. This handle must have been previously passed to the SymInitialize function.
StackFrame
[in] Pointer to an IMAGEHLP_STACK_FRAME structure that contains frame information.
Context
[in] Ignored.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGEHLP_STACK_FRAME, SymEnumSymbols


SymSetOptions

The SymSetOptions function sets the options mask.

DWORD SymSetOptions(
  DWORD SymOptions
);

Parameters

SymOptions
[in] Symbol options. Zero is a valid value and indicates that all options are turned off. The options values are combined using the OR operator to form a valid options value. The following are valid values.
Value | Meaning
SYMOPT_ALLOW_ABSOLUTE_SYMBOL | Windows .NET Server: Enables the use of symbols that are stored with absolute addresses. Most symbols are stored as RVAs from the base of the module. DbgHelp translates them to absolute addresses. There are symbols that are stored as an absolute address. These have very specialized purposes and are typically not used.
SYMOPT_AUTO_PUBLICS | Windows .NET Server: Do not search the public symbols when searching for symbols by address, or when enumerating symbols, unless they were not found in the global symbols or within the current scope. This option has no effect with SYMOPT_PUBLICS_ONLY.
SYMOPT_CASE_INSENSITIVE | All symbol searches are insensitive to case.
SYMOPT_DEBUG | Pass debug output to the callback function as CBA_DEBUG.
SYMOPT_DEFERRED_LOADS | Symbols are not loaded until a reference is made requiring the symbols be loaded. This is the fastest, most efficient way to use the symbol handler.
SYMOPT_EXACT_SYMBOLS | Do not load an unmatched .pdb file. Do not load export symbols if all else fails.
SYMOPT_FAIL_CRITICAL_ERRORS | Do not display system dialog boxes when there is a media failure such as no media in a drive. Instead, the failure happens silently.
SYMOPT_IGNORE_CVREC | Ignore path information in the CodeView record of the image header when loading a .pdb file.
SYMOPT_IGNORE_NT_SYMPATH | Windows .NET Server: Do not use the path specified by _NT_SYMBOL_PATH if the user calls SymSetSearchPath without a valid path.
SYMOPT_INCLUDE_32BIT_MODULES | When debugging on 64-bit Windows, include any 32-bit modules.
SYMOPT_LOAD_ANYTHING | Disable checks to ensure a file (.exe, .dbg., or .pdb) is the correct file. Instead, load the first file located.
SYMOPT_LOAD_LINES | Loads line number information.
SYMOPT_NO_CPP | All C++ decorated symbols containing the symbol separator "::" are replaced by "__". This option exists for debuggers that cannot handle parsing real C++ symbol names.
SYMOPT_NO_IMAGE_SEARCH | Windows .NET Server: Do not search the image for the symbol path when loading the symbols for a module if the module header cannot be read.
SYMOPT_NO_PUBLICS | Windows .NET Server: Do not search the publics table for symbols. This option should have little effect because there are copies of the public symbols in the globals table.
SYMOPT_NO_UNQUALIFIED_LOADS | Prevents symbols from being loaded when the caller examines symbols across multiple modules. Examine only the module whose symbols have already been loaded.
SYMOPT_PUBLICS_ONLY | Windows .NET Server: Do not use private symbols. The version of DbgHelp that shipped with Windows 2000 and earlier supported only public symbols; this option provides compatibility with this limitation.
SYMOPT_SECURE | Windows .NET Server: DbgHelp will not load any symbol server other than SymSrv. SymSrv will not use the downstream store specified in _NT_SYMBOL_PATH.
SYMOPT_UNDNAME All symbols are presented in undecorated form.

This option has no effect on global or local symbols because they are stored undecorated. This option applies only to public symbols.

Return Values

The function returns the current options mask.

Remarks

The options value can be changed any number of times while the library is in use by an application. The option change affects all future calls to the symbol handler.

To get the current options mask, call the SymGetOptions function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymGetOptions


SymSetParentWindow

The SymSetParentWindow function specifies the window that the debugger will use to display a user interface.

BOOL SymSetParentWindow(
  HWND hwnd
);

Parameters

hwnd
[in] Handle to the window.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions


SymSetSearchPath

The SymSetSearchPath function sets the search path for the specified process.

BOOL SymSetSearchPath(
  HANDLE hProcess,
  PSTR SearchPath
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
SearchPath
[in] Symbol search path. The string can contain multiple paths separated by semicolons.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The symbol search path can be changed any number of times while the library is in use by an application. The change affects all future calls to the symbol handler.

To get the current search path, call the SymGetSearchPath function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymGetSearchPath, SymInitialize


SymUnloadModule64

The SymUnloadModule64 function unloads the symbol table.

This function supersedes the SymUnloadedModule function. For more information, see Updated Platform Support.

BOOL SymUnloadModule64(
  HANDLE hProcess,
  DWORD64 BaseOfDll
);

Parameters

hProcess
[in] Handle to the process that was originally passed to the SymInitialize function.
BaseOfDll
[in] Base address of the module that is to be unloaded.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymInitialize


TranslateAddressProc64

The TranslateAddressProc64 function is an application-defined callback function used with the StackWalk64 function. It provides address translation for 16-bit addresses.

The PTRANSLATE_ADDRESS_ROUTINE64 type defines a pointer to this callback function. TranslateAddressProc64 is a placeholder for the application-defined function name.

This function supersedes the TranslateAddressProc function. For more information, see Updated Platform Support.

DWORD64 CALLBACK TranslateAddressProc64(
  HANDLE hProcess,
  HANDLE hThread,
  LPADDRESS64 lpaddr
);

Parameters

hProcess
[in] Handle to the process for which the stack trace is generated.
hThread
[in] Handle to the thread for which the stack trace is generated.
lpaddr
[in] Address to be translated.

Return Values

The function returns the translated address.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Functions, StackWalk64


UnDecorateSymbolName

The UnDecorateSymbolName function undecorates decorated C++ symbol names.

DWORD UnDecorateSymbolName(
  PCSTR DecoratedName,
  PSTR UnDecoratedName,
  DWORD UndecoratedLength,
  DWORD Flags
);

Parameters

DecoratedName
[in] Pointer to a null-terminated string that specifies a decorated C++ symbol name. This name can be identified by the first character of the name, which is always a question mark (?).
UnDecoratedName
[in] Pointer to a null-terminated string that specifies the buffer that receives the undecorated name.
UndecoratedLength
[in] Size of the UnDecoratedName buffer, in bytes.
Flags
[in] Options for how the decorated name is undecorated. This parameter can be zero or more of the following values.
Value | Description
UNDNAME_32_BIT_DECODE | Undecorate 32-bit decorated names.
UNDNAME_COMPLETE | Enable full undecoration.
UNDNAME_NAME_ONLY | Crack only the name for primary declaration. Returns [scope::]name. Does expand template parameters.
UNDNAME_NO_ACCESS_SPECIFIERS | Disable expansion of access specifiers for members.
UNDNAME_NO_ALLOCATION_LANGUAGE | Disable expansion of the declaration language specifier.
UNDNAME_NO_ALLOCATION_MODEL | Disable expansion of the declaration model.
UNDNAME_NO_ARGUMENTS | Do not undecorate function arguments.
UNDNAME_NO_CV_THISTYPE | Disable expansion of CodeView modifiers on the this type for primary declaration.
UNDNAME_NO_FUNCTION_RETURNS | Disable expansion of return types for primary declarations.
UNDNAME_NO_LEADING_UNDERSCORES | Remove leading underscores from Microsoft keywords.
UNDNAME_NO_MEMBER_TYPE | Disable expansion of the static or virtual attribute of members.
UNDNAME_NO_MS_KEYWORDS | Disable expansion of Microsoft keywords.
UNDNAME_NO_MS_THISTYPE | Disable expansion of Microsoft keywords on the this type for primary declaration.
UNDNAME_NO_RETURN_UDT_MODEL | Disable expansion of Microsoft model for user-defined type returns.
UNDNAME_NO_SPECIAL_SYMS | Do not undecorate special names, such as vtable, vcall, vector, metatype, and so on.
UNDNAME_NO_THISTYPE | Disable all modifiers on the this type.
UNDNAME_NO_THROW_SIGNATURES | Disable expansion of throw-signatures for functions and pointers to functions.

Return Values

If the function succeeds, the return value is the number of characters in the UnDecoratedName buffer, not including the NULL terminator.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

If the function fails and returns zero, the content of the UnDecoratedName buffer is undetermined.

Remarks

To use undecorated symbols, call the SymSetOptions function with the SYMOPT_UNDNAME option.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, SymSetOptions


UnmapDebugInformation

The UnmapDebugInformation function deallocates the memory and resources allocated by a call to the MapDebugInformation function.

Note This function is provided only for backward compatibility. New applications should use the SymUnloadModule64 function.

BOOL UnmapDebugInformation(
  PIMAGE_DEBUG_INFORMATION DebugInfo
);

Parameters

DebugInfo
[in] Pointer to an IMAGE_DEBUG_INFORMATION structure that is returned from a call to MapDebugInformation.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The UnmapDebugInformation function is the counterpart to the MapDebugInformation function and must be used to deallocate the memory and resources allocated by a call to the MapDebugInformation function.

All DbgHelp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.
Library: Use Dbghelp.lib.

See Also

DbgHelp Functions, IMAGE_DEBUG_INFORMATION, MapDebugInformation


DbgHelp Structures

The following are the DbgHelp structures.

ADDRESS64
API_VERSION
IMAGE_DEBUG_INFORMATION
IMAGEHLP_CBA_READ_MEMORY
IMAGEHLP_DEFERRED_SYMBOL_LOAD64
IMAGEHLP_DUPLICATE_SYMBOL64
IMAGEHLP_LINE64
IMAGEHLP_MODULE64
IMAGEHLP_STACK_FRAME
IMAGEHLP_SYMBOL64
KDHELP64
LOADED_IMAGE
MINIDUMP_CALLBACK_INFORMATION
MINIDUMP_CALLBACK_INPUT
MINIDUMP_CALLBACK_OUTPUT
MINIDUMP_DIRECTORY
MINIDUMP_EXCEPTION
MINIDUMP_EXCEPTION_INFORMATION
MINIDUMP_EXCEPTION_STREAM
MINIDUMP_FUNCTION_TABLE_DESCRIPTOR
MINIDUMP_FUNCTION_TABLE_STREAM
MINIDUMP_HANDLE_DATA_STREAM
MINIDUMP_HANDLE_DESCRIPTOR
MINIDUMP_HEADER
MINIDUMP_INCLUDE_MODULE_CALLBACK
MINIDUMP_INCLUDE_THREAD_CALLBACK
MINIDUMP_LOCATION_DESCRIPTOR
MINIDUMP_MEMORY_DESCRIPTOR
MINIDUMP_MEMORY_LIST
MINIDUMP_MISC_INFO
MINIDUMP_MODULE
MINIDUMP_MODULE_CALLBACK
MINIDUMP_MODULE_LIST
MINIDUMP_STRING
MINIDUMP_SYSTEM_INFO
MINIDUMP_THREAD
MINIDUMP_THREAD_CALLBACK
MINIDUMP_THREAD_EX
MINIDUMP_THREAD_EX_CALLBACK
MINIDUMP_THREAD_EX_LIST
MINIDUMP_THREAD_LIST
MINIDUMP_UNLOADED_MODULE
MINIDUMP_UNLOADED_MODULE_LIST
MINIDUMP_USER_STREAM
MINIDUMP_USER_STREAM_INFORMATION
MODLOAD_DATA
STACKFRAME64
SYMBOL_INFO
TI_FINDCHILDREN_PARAMS


ADDRESS64

The ADDRESS64 structure represents an address. It is used in the STACKFRAME64 structure.

This structure supersedes the ADDRESS structure. For more information, see Updated Platform Support.

typedef struct _tagADDRESS64 {
  DWORD64      Offset;
  WORD         Segment;
  ADDRESS_MODE Mode;
} ADDRESS64, *LPADDRESS64;

Members

Offset
Offset into the segment, or a 32-bit virtual address. The interpretation of this value depends on the value contained in the Mode member.
Segment
Segment number. This value is used only for 16-bit addressing.
Mode
Addressing mode. This member can be one of the following values.
Value | Meaning
AddrMode1616 | 16:16 addressing. To support this addressing mode, you must supply a TranslateAddressProc64 callback function.
AddrMode1632 | 16:32 addressing. To support this addressing mode, you must supply a TranslateAddressProc64 callback function.
AddrModeReal | Real-mode addressing. To support this addressing mode, you must supply a TranslateAddressProc64 callback function.
AddrModeFlat | Flat addressing. This is the only addressing mode supported by the library.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures


API_VERSION

The API_VERSION structure contains the library version.

typedef struct API_VERSION {
  USHORT MajorVersion;
  USHORT MinorVersion;
  USHORT Revision;
  USHORT Reserved;
} API_VERSION, *LPAPI_VERSION;

Members

MajorVersion
Major version number.
MinorVersion
Minor version number.
Revision
Revision number.
Reserved
Reserved for use by the operating system.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, ImagehlpApiVersion, ImagehlpApiVersionEx


IMAGE_DEBUG_INFORMATION

The IMAGE_DEBUG_INFORMATION structure contains debugging information.

Note This structure is used by the MapDebugInformation and UnmapDebugInformation functions, which are provided only for backward compatibility.

typedef struct _IMAGE_DEBUG_INFORMATION {
  LIST_ENTRY List;
  DWORD Size;
  PVOID MappedBase;
  USHORT Machine;
  USHORT Characteristics;
  DWORD CheckSum;
  DWORD ImageBase;
  DWORD SizeOfImage;
  DWORD NumberOfSections;
  PIMAGE_SECTION_HEADER Sections;
  DWORD ExportedNamesSize;
  PSTR ExportedNames;
  DWORD NumberOfFunctionTableEntries;
  PIMAGE_FUNCTION_ENTRY FunctionTableEntries;
  DWORD LowestFunctionStartingAddress;
  DWORD HighestFunctionEndingAddress;
  DWORD NumberOfFpoTableEntries;
  PFPO_DATA FpoTableEntries;
  DWORD SizeOfCoffSymbols;
  PIMAGE_COFF_SYMBOLS_HEADER CoffSymbols;
  DWORD SizeOfCodeViewSymbols;
  PVOID CodeViewSymbols;
  PSTR ImageFilePath;
  PSTR ImageFileName;
  PSTR ReservedDebugFilePath;
  DWORD ReservedTimeDateStamp;
  BOOL ReservedRomImage;
  PIMAGE_DEBUG_DIRECTORY ReservedDebugDirectory;
  DWORD ReservedNumberOfDebugDirectories;
  DWORD ReservedOriginalFunctionTableBaseAddress;
  DWORD Reserved[2];
} IMAGE_DEBUG_INFORMATION, *PIMAGE_DEBUG_INFORMATION;

Members

List
Linked list pointers.
Size
Size of the memory allocated for the IMAGE_DEBUG_INFORMATION structure and all debugging information, in bytes.
MappedBase
Base address of the image.
Machine
Computer type. This member can be one of the following values.
Value | Meaning
IMAGE_FILE_MACHINE_I386 | Intel (32-bit)
IMAGE_FILE_MACHINE_IA64 | Intel (64-bit)
IMAGE_FILE_MACHINE_ALPHA | DEC Alpha
IMAGE_FILE_MACHINE_POWERPC | Power PC

Characteristics
Characteristics of the image. This member can be one of the following values.
Value | Meaning
IMAGE_FILE_RELOCS_STRIPPED | Relocation information is stripped from the file.
IMAGE_FILE_EXECUTABLE_IMAGE | The file is executable (there are no unresolved external references).
IMAGE_FILE_LINE_NUMS_STRIPPED | Line numbers are stripped from the file.
IMAGE_FILE_LOCAL_SYMS_STRIPPED | Local symbols are stripped from file.
IMAGE_FILE_AGGRESIVE_WS_TRIM | Aggressively trim the working set.
IMAGE_FILE_LARGE_ADDRESS_AWARE | The application can handle addresses larger than 2 GB.
IMAGE_FILE_BYTES_REVERSED_LO | Bytes of the word are reversed.
IMAGE_FILE_32BIT_MACHINE | Computer supports 32-bit words.
IMAGE_FILE_DEBUG_STRIPPED | Debugging information is stored separately in a .dbg file.
IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP | If the image is on removable media, copy and run from the swap file.
IMAGE_FILE_NET_RUN_FROM_SWAP | If the image is on the network, copy and run from the swap file.
IMAGE_FILE_SYSTEM | System file.
IMAGE_FILE_DLL | DLL file.
IMAGE_FILE_UP_SYSTEM_ONLY | File should be run only on a uniprocessor computer.
IMAGE_FILE_BYTES_REVERSED_HI | Bytes of the word are reversed.

CheckSum
Checksum of the image.
ImageBase
Requested base address of the image.
SizeOfImage
Size of the image, in bytes.
NumberOfSections
Number of COFF section headers.
Sections
Pointer to the first COFF section header. For more information, see IMAGE_SECTION_HEADER.
ExportedNamesSize
Size of the ExportedNames member, in bytes.
ExportedNames
Pointer to a series of null-terminated strings that name all the functions exported from the image.
NumberOfFunctionTableEntries
Number of entries contained in the FunctionTableEntries member.
FunctionTableEntries
Pointer to the first function table entry. For more information, see IMAGE_FUNCTION_ENTRY.
LowestFunctionStartingAddress
Lowest function table starting address.
HighestFunctionEndingAddress
Highest function table ending address.
NumberOfFpoTableEntries
Number of entries contained in the FpoTableEntries member.
FpoTableEntries
Pointer to the first FPO entry. For more information, see FPO_DATA.
SizeOfCoffSymbols
Size of the COFF symbol table, in bytes.
CoffSymbols
Pointer to the COFF symbol table.
SizeOfCodeViewSymbols
Size of the CodeView symbol table, in bytes.
CodeViewSymbols
Pointer to the beginning of the CodeView symbol table.
ImageFilePath
Relative path to the image file name.
ImageFileName
Image file name.
ReservedDebugFilePath
Full path to the symbol file.
ReservedTimeDateStamp
Timestamp of the image. This represents the date and time the image was created by the linker.
ReservedRomImage
This value is TRUE if the image is a ROM image.
ReservedDebugDirectory
Pointer to the first debug directory. For more information, see IMAGE_DEBUG_DIRECTORY.
ReservedNumberOfDebugDirectories
Number of entries contained in the DebugDirectory member.
ReservedOriginalFunctionTableBaseAddress
Original function table base address.
Reserved
Reserved for use by the operating system.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, FPO_DATA, IMAGE_COFF_SYMBOLS_HEADER, IMAGE_DEBUG_DIRECTORY, IMAGE_FUNCTION_ENTRY, IMAGE_SECTION_HEADER, MapDebugInformation, UnmapDebugInformation


IMAGEHLP_CBA_READ_MEMORY

The IMAGEHLP_CBA_READ_MEMORY structure contains information about a memory read operation.

typedef struct _IMAGEHLP_CBA_READ_MEMORY {
  DWORD64   addr;
  PVOID     buf;
  DWORD     bytes;
  DWORD    *bytesread;
} IMAGEHLP_CBA_READ_MEMORY, *PIMAGEHLP_CBA_READ_MEMORY;

Members

addr
Address to be read.
buf
Pointer to a buffer that receives the memory read.
bytes
Number of bytes to read.
bytesread
Pointer to a variable that receives the number of bytes read.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, SymRegisterCallbackProc64


IMAGEHLP_DEFERRED_SYMBOL_LOAD64

The IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure contains information about a deferred symbol load.

This structure supersedes the IMAGEHLP_DEFERRED_SYMBOL_LOAD structure. For more information, see Updated Platform Support.

typedef struct _IMAGEHLP_DEFERRED_SYMBOL_LOAD64 {
  DWORD   SizeOfStruct;
  DWORD64 BaseOfImage;
  DWORD   CheckSum;
  DWORD   TimeDateStamp;
  CHAR    FileName[MAX_PATH];
  BOOLEAN Reparse;
  HANDLE  hFile;
} IMAGEHLP_DEFERRED_SYMBOL_LOAD64, *PIMAGEHLP_DEFERRED_SYMBOL_LOAD64;

Members

SizeOfStruct
Size of the structure, in bytes. The caller must set this member to sizeof(IMAGEHLP_DEFERRED_SYMBOL_LOAD64).
BaseOfImage
Base virtual address where the image is loaded.
CheckSum
Computed checksum of the image. This value can be zero.
TimeDateStamp
Date and timestamp value. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The timestamp can be printed using the C run-time (CRT) function ctime.
FileName
Image name. The name may or may not contain a full path.
Reparse
Windows 2000/XP: If this member is TRUE, the operation should be performed again. Otherwise, it should not.
hFile
Windows .NET Server: Handle to a file. This member is used with CBA_DEFERRED_SYMBOL_LOAD_PARTIAL and IMAGEHLP_DEFERRED_SYMBOL_LOAD_FAILURE callbacks.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, SymRegisterCallbackProc64


IMAGEHLP_DUPLICATE_SYMBOL64

The IMAGEHLP_DUPLICATE_SYMBOL64 structure contains duplicate symbol information.

This structure supersedes the IMAGEHLP_DUPLICATE_SYMBOL structure. For more information, see Updated Platform Support.

typedef struct _IMAGEHLP_DUPLICATE_SYMBOL64 {
  DWORD              SizeOfStruct;
  DWORD              NumberOfDups;
  PIMAGEHLP_SYMBOL64 Symbol;
  DWORD              SelectedSymbol;
} IMAGEHLP_DUPLICATE_SYMBOL64, *PIMAGEHLP_DUPLICATE_SYMBOL64;

Members

SizeOfStruct
Size of the structure, in bytes. The caller must set this member to sizeof(IMAGEHLP_DUPLICATE_SYMBOL64).
NumberOfDups
Number of duplicate symbols.
Symbol
Pointer to an array of symbols (IMAGEHLP_SYMBOL64 structures). The number of entries in the array is specified by the NumberOfDups member.
SelectedSymbol
Index into the symbol array for the selected symbol.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, IMAGEHLP_SYMBOL64, SymRegisterCallbackProc64


IMAGEHLP_LINE64

The IMAGEHLP_LINE64 structure represents a source file line.

This structure supersedes the IMAGEHLP_LINE structure. For more information, see Updated Platform Support.

typedef struct _IMAGEHLP_LINE64 {
  DWORD   SizeOfStruct;
  PVOID   Key;
  DWORD   LineNumber;
  PCHAR   FileName;
  DWORD64 Address;
} IMAGEHLP_LINE64, *PIMAGEHLP_LINE64;

Members

SizeOfStruct
Size of the structure, in bytes. The caller must set this member to sizeof(IMAGEHLP_LINE64).
Key
Reserved for use by the operating system.
LineNumber
Line number in the file.
FileName
Name of the file, including the full path.
Address
Address of the first instruction in the line.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, SymGetLineFromAddr64, SymGetLineFromName64, SymGetLineNext64, SymGetLinePrev64


IMAGEHLP_MODULE64

The IMAGEHLP_MODULE64 structure contains module information.

This structure supersedes the IMAGEHLP_MODULE structure. For more information, see Updated Platform Support.

typedef struct _IMAGEHLP_MODULE64 {
  DWORD    SizeOfStruct;
  DWORD64  BaseOfImage;
  DWORD    ImageSize;
  DWORD    TimeDateStamp;
  DWORD    CheckSum;
  DWORD    NumSyms;
  SYM_TYPE SymType;
  TCHAR    ModuleName[32];
  TCHAR    ImageName[256];
  TCHAR    LoadedImageName[256];
} IMAGEHLP_MODULE64, *PIMAGEHLP_MODULE64;

Members

SizeOfStruct
Size of the structure, in bytes. The caller must set this member to sizeof(IMAGEHLP_MODULE64).
BaseOfImage
Base virtual address where the image is loaded.
ImageSize
Size of the image, in bytes.
TimeDateStamp
Date and timestamp value. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The timestamp can be printed using the C run-time (CRT) function ctime.
CheckSum
Checksum of the image. This value can be zero.
NumSyms
Number of symbols in the symbol table.
SymType
Type of symbols that are loaded. This member can be one of the following values.
Value | Meaning
SymCoff | COFF symbols.
SymCv | CodeView symbols.
SymDeferred | Symbol loading deferred.
SymDia | DIA symbols.
SymExport | Symbols generated from a DLL export table.
SymNone | No symbols are loaded.
SymPdb | PDB symbols.
SymSym | .SYM file.
SymVirtual | Windows .NET Server: Virtual module created by SymLoadModuleEx with SLMFLAG_VIRTUAL.

ModuleName
Module name.
ImageName
Image name. The name may or may not contain a full path.
LoadedImageName
Full path and file name from which symbols were loaded.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, SymGetModuleInfo64


IMAGEHLP_STACK_FRAME

The IMAGEHLP_STACK_FRAME structure is used with the SymSetContext function.

typedef struct _IMAGEHLP_STACK_FRAME {
    ULONG64 InstructionOffset;
    ULONG64 ReturnOffset;
    ULONG64 FrameOffset;
    ULONG64 StackOffset;
    ULONG64 BackingStoreOffset;
    ULONG64 FuncTableEntry;
    ULONG64 Params[4];
    ULONG64 Reserved[5];
    BOOL    Virtual;
    ULONG   Reserved2;
} IMAGEHLP_STACK_FRAME, *PIMAGEHLP_STACK_FRAME;

Members

InstructionOffset
Program counter.

x86: The program counter is EIP.

IA64: The program counter is StIIP.

AMD64: The program counter is RIP.

ReturnOffset
Return address.
FrameOffset
Frame pointer.

x86: The frame pointer is EBP.

IA64: There is no frame pointer, but AddrBStore is used.

AMD64: The frame pointer is RBP. AMD64 does not always use this value.

Alpha: There is no frame pointer, so the Offset member is not used and should be zero. However, the Offset member is used when walking a kernel stack which terminates in an exception frame. This is a special case.

StackOffset
Stack pointer.

x86: The stack pointer is ESP.

IA64: The stack pointer is SP.

AMD64: The stack pointer is RSP.

BackingStoreOffset
IA64: Backing store address.
FuncTableEntry
x86: An FPO_DATA structure. If there is no function table entry, this member is NULL.
Params
Possible arguments to the function.
Reserved
Reserved for system use.
Virtual
If this is a virtual frame, this member is TRUE. Otherwise, this member is FALSE.
Reserved2
Reserved for system use.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, SymSetContext


IMAGEHLP_SYMBOL64

The IMAGEHLP_SYMBOL64 structure contains symbol information.

This structure supersedes the IMAGEHLP_SYMBOL structure. For more information, see Updated Platform Support.

typedef struct _IMAGEHLP_SYMBOL64 {
  DWORD   SizeOfStruct;
  DWORD64 Address;
  DWORD   Size;
  DWORD   Flags;
  DWORD   MaxNameLength;
  CHAR    Name[1];
} IMAGEHLP_SYMBOL64, *PIMAGEHLP_SYMBOL64;

Members

SizeOfStruct
Size of the structure, in bytes. The caller must set this member to sizeof(IMAGEHLP_SYMBOL64).
Address
Virtual address for the symbol.
Size
Size of the symbol, in bytes. This value is a best guess and can be zero.
Flags
Reserved for use by the operating system.
MaxNameLength
Maximum length of the string that the Name member can contain. Because symbol names can vary in length, this data structure is allocated by the caller. This member is used so the library knows how much memory is available for use by the symbol name.
Name
Null-terminated string specifying either the decorated or undecorated symbol name. If the buffer is not large enough for the complete name, it is truncated to MaxNameLength characters.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, SymGetSymFromAddr64, SymGetSymFromName64


KDHELP64

The KDHELP64 structure is included in the STACKFRAME64 structure, and is used to trace through user-mode callbacks in a thread's kernel stack. This structure is used by kernel debuggers.

This structure supersedes the KDHELP structure. For more information, see Updated Platform Support.

typedef struct _KDHELP64 {
  DWORD64 Thread;
  DWORD   ThCallbackStack;
  DWORD   ThCallbackBStore;
  DWORD   NextCallback;
  DWORD   FramePointer;
  DWORD64 KiCallUserMode;
  DWORD64 KeUserCallbackDispatcher;
  DWORD64 SystemRangeStart;
  DWORD64 Reserved[8];
} KDHELP64, *PKDHELP64;

Members

Thread
Address of the kernel thread object, as provided in the WAIT_STATE_CHANGE packet.
ThCallbackStack
Offset in the thread object to the pointer to the current callback frame in the kernel stack.
NextCallback
Address of the next callback frame.
FramePointer
Address of the saved frame pointer, if applicable.
KiCallUserMode
Address of the kernel function that calls out to user mode.
KeUserCallbackDispatcher
Address of the user-mode dispatcher function.
SystemRangeStart
Lowest kernel-mode address.
ThCallbackBStore
IA64: Offset in the thread object to a pointer to the current callback backing store frame in the kernel stack.
Reserved
Reserved for use by the operating system.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures


LOADED_IMAGE

The LOADED_IMAGE structure contains information about the loaded image.

typedef struct _LOADED_IMAGE {
  PSTR ModuleName;
  HANDLE hFile;
  PUCHAR MappedAddress;
#ifdef _IMAGEHLP64
  PIMAGE_NT_HEADERS64 FileHeader;
#else
  PIMAGE_NT_HEADERS32 FileHeader;
#endif
  PIMAGE_SECTION_HEADER LastRvaSection;
  ULONG NumberOfSections;
  PIMAGE_SECTION_HEADER Sections;
  ULONG Characteristics;
  BOOLEAN fSystemImage;
  BOOLEAN fDOSImage;
  LIST_ENTRY Links;
  ULONG SizeOfImage;
} LOADED_IMAGE, *PLOADED_IMAGE;

Members

ModuleName
Null-terminated string that specifies the file name of the mapped file.
hFile
Handle to the mapped file.
MappedAddress
Base address of the mapped file.
FileHeader
Pointer to an IMAGE_NT_HEADERS structure.
LastRvaSection
Pointer to an IMAGE_SECTION_HEADER structure.
NumberOfSections
Number of COFF section headers.
Sections
Pointer to an IMAGE_SECTION_HEADER structure.
Characteristics
Image characteristics value. This member can be one of the following values.
Value | Meaning
IMAGE_FILE_RELOCS_STRIPPED | Relocation information is stripped from the file.
IMAGE_FILE_EXECUTABLE_IMAGE | The file is executable (there are no unresolved external references).
IMAGE_FILE_LINE_NUMS_STRIPPED | Line numbers are stripped from the file.
IMAGE_FILE_LOCAL_SYMS_STRIPPED | Local symbols are stripped from file.
IMAGE_FILE_AGGRESIVE_WS_TRIM | Aggressively trim the working set.
IMAGE_FILE_LARGE_ADDRESS_AWARE | The application can handle addresses larger than 2 GB.
IMAGE_FILE_BYTES_REVERSED_LO | Bytes of word are reversed.
IMAGE_FILE_32BIT_MACHINE | Computer supports 32-bit words.
IMAGE_FILE_DEBUG_STRIPPED | Debugging information is stored separately in a .dbg file.
IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP | If the image is on removable media, copy and run from the swap file.
IMAGE_FILE_NET_RUN_FROM_SWAP | If the image is on the network, copy and run from the swap file.
IMAGE_FILE_SYSTEM | System file.
IMAGE_FILE_DLL | DLL file.
IMAGE_FILE_UP_SYSTEM_ONLY | File should be run only on a uniprocessor computer.
IMAGE_FILE_BYTES_REVERSED_HI | Bytes of the word are reversed.

fSystemImage
If the image is a kernel mode executable image, this value is TRUE.
fDOSImage
If the image is a 16-bit executable image, this value is TRUE.
Links
List of loaded images.
SizeOfImage
Size of the image, in bytes.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, IMAGE_NT_HEADERS, IMAGE_SECTION_HEADER, ImageLoad, MapAndLoad


MINIDUMP_CALLBACK_INFORMATION

The MINIDUMP_CALLBACK_INFORMATION structure contains a pointer to an optional callback function that can be used by the MiniDumpWriteDump function.

typedef struct _MINIDUMP_CALLBACK_INFORMATION {
  MINIDUMP_CALLBACK_ROUTINE CallbackRoutine;
  PVOID CallbackParam;
} MINIDUMP_CALLBACK_INFORMATION, *PMINIDUMP_CALLBACK_INFORMATION;

Members

CallbackRoutine
Pointer to the MiniDumpCallback callback function.
CallbackParam
Application-defined data for CallbackRoutine.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MiniDumpCallback, MiniDumpWriteDump


MINIDUMP_CALLBACK_INPUT

The MINIDUMP_CALLBACK_INPUT structure contains information used by the MiniDumpCallback function.

typedef struct _MINIDUMP_CALLBACK_INPUT {
  ULONG ProcessId;
  HANDLE ProcessHandle;
  ULONG CallbackType;
  union {
     MINIDUMP_THREAD_CALLBACK Thread;
     MINIDUMP_THREAD_EX_CALLBACK ThreadEx;
     MINIDUMP_MODULE_CALLBACK Module;
     MINIDUMP_INCLUDE_THREAD_CALLBACK IncludeThread;
     MINIDUMP_INCLUDE_MODULE_CALLBACK IncludeModule;
  };
} MINIDUMP_CALLBACK_INPUT, *PMINIDUMP_CALLBACK_INPUT;

Members

ProcessId
Identifier of the process that contains callback function.
ProcessHandle
Handle to the process that contains the callback function.
CallbackType
Type of callback function. This member can be one of the values in the MINIDUMP_CALLBACK_TYPE enumeration.
Thread
If CallbackType is ThreadCallback, the union is a MINIDUMP_THREAD_CALLBACK structure.
ThreadEx
If CallbackType is ThreadExCallback, the union is a MINIDUMP_THREAD_EX_CALLBACK structure.
Module
If CallbackType is ModuleCallback, the union is a MINIDUMP_MODULE_CALLBACK structure.
IncludeThread
If CallbackType is IncludeThreadCallback, the union is a MINIDUMP_INCLUDE_THREAD_CALLBACK structure.
IncludeModule
If CallbackType is IncludeModuleCallback, the union is a MINIDUMP_INCLUDE_MODULE_CALLBACK structure.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MINIDUMP_CALLBACK_TYPE, MINIDUMP_INCLUDE_MODULE_CALLBACK, MINIDUMP_INCLUDE_THREAD_CALLBACK, MINIDUMP_MODULE_CALLBACK, MINIDUMP_THREAD_CALLBACK, MINIDUMP_THREAD_EX_CALLBACK, MiniDumpCallback


MINIDUMP_CALLBACK_OUTPUT

The MINIDUMP_CALLBACK_OUTPUT structure contains information returned from the MiniDumpCallback function.

typedef struct _MINIDUMP_CALLBACK_OUTPUT {
  union {
    ULONG ModuleWriteFlags;
    ULONG ThreadWriteFlags;
  };
} MINIDUMP_CALLBACK_OUTPUT, *PMINIDUMP_CALLBACK_OUTPUT;

Members

ModuleWriteFlags
Module write operation flags. This member can be one or more of the values in the MODULE_WRITE_FLAGS enumeration.
ThreadWriteFlags
Thread write operation flags. This member can be one or more of the values in the THREAD_WRITE_FLAGS enumeration.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MiniDumpCallback, MODULE_WRITE_FLAGS, THREAD_WRITE_FLAGS


MINIDUMP_DIRECTORY

The MINIDUMP_DIRECTORY structure contains information needed to access a specific data stream in a minidump file.

typedef struct _MINIDUMP_DIRECTORY {
  ULONG32 StreamType;
  MINIDUMP_LOCATION_DESCRIPTOR Location;
} MINIDUMP_DIRECTORY, *PMINIDUMP_DIRECTORY;

Members

StreamType
Type of data stream. This member can be one of the values in the MINIDUMP_STREAM_TYPE enumeration.
Location
A MINIDUMP_LOCATION_DESCRIPTOR structure that specifies the location of the data stream.

Remarks

In this context, a data stream is a block of data within a minidump file.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MiniDumpReadDumpStream, MINIDUMP_LOCATION_DESCRIPTOR, MINIDUMP_STREAM_TYPE


MINIDUMP_EXCEPTION

The MINIDUMP_EXCEPTION structure describes an exception.

typedef struct _MINIDUMP_EXCEPTION  {
    ULONG32 ExceptionCode;
    ULONG32 ExceptionFlags;
    ULONG64 ExceptionRecord;
    ULONG64 ExceptionAddress;
    ULONG32 NumberParameters;
    ULONG32 __unusedAlignment;
    ULONG64 ExceptionInformation [EXCEPTION_MAXIMUM_PARAMETERS];
} MINIDUMP_EXCEPTION, *PMINIDUMP_EXCEPTION;

Members

ExceptionCode
Reason the exception occurred. This is the code generated by a hardware exception, or the code specified in the RaiseException function for a software-generated exception. Following are the exception codes likely to occur due to common programming errors.
Value | Meaning
EXCEPTION_ACCESS_VIOLATION | The thread tried to read from or write to a virtual address for which it does not have the appropriate access.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED | The thread tried to access an array element that is out of bounds and the underlying hardware supports bounds checking.
EXCEPTION_BREAKPOINT | A breakpoint was encountered.
EXCEPTION_DATATYPE_MISALIGNMENT | The thread tried to read or write data that is misaligned on hardware that does not provide alignment. For example, 16-bit values must be aligned on 2-byte boundaries; 32-bit values on 4-byte boundaries, and so on.
EXCEPTION_FLT_DENORMAL_OPERAND | One of the operands in a floating-point operation is denormal. A denormal value is one that is too small to represent as a standard floating-point value.
EXCEPTION_FLT_DIVIDE_BY_ZERO | The thread tried to divide a floating-point value by a floating-point divisor of zero.
EXCEPTION_FLT_INEXACT_RESULT | The result of a floating-point operation cannot be represented exactly as a decimal fraction.
EXCEPTION_FLT_INVALID_OPERATION | This exception represents any floating-point exception not included in this list.
EXCEPTION_FLT_OVERFLOW | The exponent of a floating-point operation is greater than the magnitude allowed by the corresponding type.
EXCEPTION_FLT_STACK_CHECK | The stack overflowed or underflowed as the result of a floating-point operation.
EXCEPTION_FLT_UNDERFLOW | The exponent of a floating-point operation is less than the magnitude allowed by the corresponding type.
EXCEPTION_ILLEGAL_INSTRUCTION | The thread tried to execute an invalid instruction.
EXCEPTION_IN_PAGE_ERROR | The thread tried to access a page that was not present, and the system was unable to load the page. For example, this exception might occur if a network connection is lost while running a program over the network.
EXCEPTION_INT_DIVIDE_BY_ZERO | The thread tried to divide an integer value by an integer divisor of zero.
EXCEPTION_INT_OVERFLOW | The result of an integer operation caused a carry out of the most significant bit of the result.
EXCEPTION_INVALID_DISPOSITION | An exception handler returned an invalid disposition to the exception dispatcher. Programmers using a high-level language such as C should never encounter this exception.
EXCEPTION_NONCONTINUABLE_EXCEPTION | The thread tried to continue execution after a noncontinuable exception occurred.
EXCEPTION_PRIV_INSTRUCTION | The thread tried to execute an instruction whose operation is not allowed in the current machine mode.
EXCEPTION_SINGLE_STEP | A trace trap or other single-instruction mechanism signaled that one instruction has been executed.
EXCEPTION_STACK_OVERFLOW | The thread used up its stack.

Another exception code is likely to occur when debugging console processes. It does not arise because of a programming error. The DBG_CONTROL_C exception code occurs when CTRL+C is input to a console process that handles CTRL+C signals and is being debugged. This exception code is not meant to be handled by applications. It is raised only for the benefit of the debugger, and is raised only when a debugger is attached to the console process.

ExceptionFlags
This member can be either zero, indicating a continuable exception, or EXCEPTION_NONCONTINUABLE, indicating a noncontinuable exception. Any attempt to continue execution after a noncontinuable exception causes the EXCEPTION_NONCONTINUABLE_EXCEPTION exception.
ExceptionRecord
Pointer to an associated MINIDUMP_EXCEPTION structure. Exception records can be chained together to provide additional information when nested exceptions occur.
ExceptionAddress
Address where the exception occurred.
NumberParameters
Number of parameters associated with the exception. This is the number of defined elements in the ExceptionInformation array.
ExceptionInformation
Array of additional arguments that describe the exception. The RaiseException function can specify this array of arguments. For most exception codes, the array elements are undefined. For the following exception code, the array elements are defined as follows.
Exception code Array contents
EXCEPTION_ACCESS_VIOLATION The first element of the array contains a read/write flag that indicates the type of operation that caused the access violation. If this value is zero, the thread attempted to read the inaccessible data. If this value is 1, the thread attempted to write to an inaccessible address.

The second array element specifies the virtual address of the inaccessible data.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_EXCEPTION_STREAM, RaiseException


MINIDUMP_EXCEPTION_INFORMATION

The MINIDUMP_EXCEPTION_INFORMATION structure contains exception information written to the minidump file by the MiniDumpWriteDump function.

typedef struct _MINIDUMP_EXCEPTION_INFORMATION {
  DWORD ThreadId;
  PEXCEPTION_POINTERS ExceptionPointers;
  BOOL ClientPointers;
} MINIDUMP_EXCEPTION_INFORMATION, *PMINIDUMP_EXCEPTION_INFORMATION;

Members

ThreadId
Identifier of the thread throwing the exception.
ExceptionPointers
Pointer to an EXCEPTION_POINTERS structure specifying a computer-independent description of the exception and the processor context at the time of the exception.
ClientPointers
Memory location to which the value of ExceptionPointers refers. If this member is TRUE, the exception pointer is located in the address space of the client, or the process that crashed. If this member is FALSE, the exception pointer is located in the address space of the calling program.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, EXCEPTION_POINTERS, MiniDumpWriteDump


MINIDUMP_EXCEPTION_STREAM

The MINIDUMP_EXCEPTION_STREAM structure describes an exception information stream.

typedef struct MINIDUMP_EXCEPTION_STREAM {
    ULONG32 ThreadId;
    ULONG32  __alignment;
    MINIDUMP_EXCEPTION ExceptionRecord;
    MINIDUMP_LOCATION_DESCRIPTOR ThreadContext;
} MINIDUMP_EXCEPTION_STREAM, *PMINIDUMP_EXCEPTION_STREAM;

Members

ThreadId
Identifier of the thread that caused the exception.
ExceptionRecord
A MINIDUMP_EXCEPTION structure.
ThreadContext
A MINIDUMP_LOCATION_DESCRIPTOR structure.

Remarks

In this context, a data stream is a set of data in a minidump file.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_EXCEPTION, MINIDUMP_LOCATION_DESCRIPTOR, MINIDUMP_STREAM_TYPE


MINIDUMP_FUNCTION_TABLE_DESCRIPTOR

The MINIDUMP_FUNCTION_TABLE_DESCRIPTOR structure describes a function table stream.

typedef struct _MINIDUMP_FUNCTION_TABLE_DESCRIPTOR {
    ULONG64 MinimumAddress;
    ULONG64 MaximumAddress;
    ULONG64 BaseAddress;
    ULONG32 EntryCount;
    ULONG32 SizeOfAlignPad;
} MINIDUMP_FUNCTION_TABLE_DESCRIPTOR, *PMINIDUMP_FUNCTION_TABLE_DESCRIPTOR;

Members

MinimumAddress
Minimum address of functions described by the table.
MaximumAddress
Maximum address of functions described by the table.
BaseAddress
Base address to use when computing full virtual addresses from relative virtual addresses in function entries.
EntryCount
Number of entries in the function table.
SizeOfAlignPad
Size of alignment padding that follows the function entry data, in bytes. The function entry data in the stream is guaranteed to be aligned appropriately for access to the data members. If a minidump is directly mapped in memory, it is always possible to directly reference structure members in the stream.

Remarks

The first descriptor in the function table stream follows the header, MINIDUMP_FUNCTION_TABLE_STREAM. The generic descriptor is followed by a native system descriptor, then by EntryCount native system function entry structures.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_FUNCTION_TABLE_STREAM


MINIDUMP_FUNCTION_TABLE_STREAM

The MINIDUMP_FUNCTION_TABLE_STREAM structure is the header for the function table stream.

typedef struct _MINIDUMP_FUNCTION_TABLE_STREAM {
    ULONG32 SizeOfHeader;
    ULONG32 SizeOfDescriptor;
    ULONG32 SizeOfNativeDescriptor;
    ULONG32 SizeOfFunctionEntry;
    ULONG32 NumberOfDescriptors;
    ULONG32 SizeOfAlignPad;
} MINIDUMP_FUNCTION_TABLE_STREAM, *PMINIDUMP_FUNCTION_TABLE_STREAM;

Members

SizeOfHeader
Size of header information for the stream, in bytes. This value is sizeof(MINIDUMP_FUNCTION_TABLE_STREAM).
SizeOfDescriptor
Size of a descriptor in the stream, in bytes. This value is sizeof(MINIDUMP_FUNCTION_TABLE_DESCRIPTOR).
SizeOfNativeDescriptor
Size of a raw system descriptor in the stream, in bytes. This value depends on the particular platform and system version on which the minidump was generated.
SizeOfFunctionEntry
Size of a raw system function table entry, in bytes. This value depends on the particular platform and system version on which the minidump was generated.
NumberOfDescriptors
Number of descriptors in the stream.
SizeOfAlignPad
Size of alignment padding that follows the header, in bytes.

Remarks

In this context, a data stream is a set of data in a minidump file. This header structure is followed by NumberOfDescriptors function tables. For each function table there is a MINIDUMP_FUNCTION_TABLE_DESCRIPTOR structure, then the raw system descriptor for the table, then the raw system function entry data. If necessary, alignment padding is placed between tables to properly align the initial structures.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_FUNCTION_TABLE_DESCRIPTOR, MINIDUMP_STREAM_TYPE


MINIDUMP_HANDLE_DATA_STREAM

The MINIDUMP_HANDLE_DATA_STREAM structure is the header for a handle data stream.

typedef struct _MINIDUMP_HANDLE_DATA_STREAM {
    ULONG32 SizeOfHeader;
    ULONG32 SizeOfDescriptor;
    ULONG32 NumberOfDescriptors;
    ULONG32 Reserved;
} MINIDUMP_HANDLE_DATA_STREAM, *PMINIDUMP_HANDLE_DATA_STREAM;

Members

SizeOfHeader
Size of the header information for the stream, in bytes. This value is sizeof(MINIDUMP_HANDLE_DATA_STREAM).
SizeOfDescriptor
Size of a descriptor in the stream, in bytes. This value is sizeof(MINIDUMP_HANDLE_DESCRIPTOR).
NumberOfDescriptors
Number of descriptors in the stream.
Reserved
Reserved for future use; must be zero.

Remarks

In this context, a data stream is a set of data in a minidump file. This header structure is followed by NumberOfDescriptors MINIDUMP_HANDLE_DESCRIPTOR structures.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_HANDLE_DESCRIPTOR, MINIDUMP_STREAM_TYPE


MINIDUMP_HANDLE_DESCRIPTOR

The MINIDUMP_HANDLE_DESCRIPTOR structure describes the state of an individual system handle at the time the minidump was written.

typedef struct _MINIDUMP_HANDLE_DESCRIPTOR {
    ULONG64 Handle;
    RVA TypeNameRva;
    RVA ObjectNameRva;
    ULONG32 Attributes;
    ULONG32 GrantedAccess;
    ULONG32 HandleCount;
    ULONG32 PointerCount;
} MINIDUMP_HANDLE_DESCRIPTOR, *PMINIDUMP_HANDLE_DESCRIPTOR;

Members

Handle
Operating system handle value.
TypeNameRva
An RVA to a MINIDUMP_STRING structure that specifies the object type of the handle. This member can be zero.
ObjectNameRva
An RVA to a MINIDUMP_STRING structure that specifies the object name of the handle. This member can be zero.
Attributes
The meaning of this member depends on the handle type and the operating system.
GrantedAccess
The meaning of this member depends on the handle type and the operating system.
HandleCount
The meaning of this member depends on the handle type and the operating system.
PointerCount
The meaning of this member depends on the handle type and the operating system.

Remarks

The first descriptor in the handle data stream follows the header, MINIDUMP_HANDLE_DATA_STREAM.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_HANDLE_DATA_STREAM, MINIDUMP_STRING


MINIDUMP_HEADER

The MINIDUMP_HEADER structure contains header information for the minidump file.

typedef struct _MINIDUMP_HEADER {
    ULONG32 Signature;
    ULONG32 Version;
    ULONG32 NumberOfStreams;
    RVA StreamDirectoryRva;
    ULONG32 CheckSum;
    union {
        ULONG32 Reserved;
        ULONG32 TimeDateStamp;
    };
    ULONG64 Flags;
} MINIDUMP_HEADER, *PMINIDUMP_HEADER;

Members

Signature
Set to MINIDUMP_SIGNATURE.
Version
Version of the minidump format. The low-order word is MINIDUMP_VERSION. The high-order word is an internal value that is implementation specific.
NumberOfStreams
Number of streams in the minidump directory.
StreamDirectoryRva
Base RVA of the minidump directory. The directory is an array of MINIDUMP_DIRECTORY structures.
CheckSum
Checksum for the minidump file. This member can be zero.
TimeDateStamp
Time and date, in time_t format.
Flags
One or more of the MINIDUMP_TYPE values.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_DIRECTORY, MINIDUMP_TYPE


MINIDUMP_INCLUDE_MODULE_CALLBACK

The MINIDUMP_INCLUDE_MODULE_CALLBACK structure contains information for the MiniDumpCallback function when the callback type is IncludeModuleCallback.

typedef struct _MINIDUMP_INCLUDE_MODULE_CALLBACK {
    ULONG64 BaseOfImage;
} MINIDUMP_INCLUDE_MODULE_CALLBACK, *PMINIDUMP_INCLUDE_MODULE_CALLBACK;

Members

BaseOfImage
Base address of the executable image in memory.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_CALLBACK_INPUT, MiniDumpCallback


MINIDUMP_INCLUDE_THREAD_CALLBACK

The MINIDUMP_INCLUDE_THREAD_CALLBACK structure contains information for the MiniDumpCallback function when the callback type is IncludeThreadCallback.

typedef struct _MINIDUMP_INCLUDE_THREAD_CALLBACK {
    ULONG ThreadId;
} MINIDUMP_INCLUDE_THREAD_CALLBACK, *PMINIDUMP_INCLUDE_THREAD_CALLBACK;

Members

ThreadId
Identifier of the thread.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_CALLBACK_INPUT, MiniDumpCallback


MINIDUMP_LOCATION_DESCRIPTOR

The MINIDUMP_LOCATION_DESCRIPTOR structure contains information describing the location of a data stream within a minidump file.

This structure uses 32-bit locations for RVAs in the first 4GB and 64-bit locations are used for larger RVAs.

typedef struct _MINIDUMP_LOCATION_DESCRIPTOR {
  ULONG32 DataSize;
  RVA Rva;
} MINIDUMP_LOCATION_DESCRIPTOR;

The MINIDUMP_LOCATION_DESCRIPTOR64 structure is defined as follows.

typedef struct _MINIDUMP_LOCATION_DESCRIPTOR64 {
  ULONG64 DataSize;
  RVA64 Rva;
} MINIDUMP_LOCATION_DESCRIPTOR64;

Members

DataSize
Size of the data stream, in bytes.
Rva
Relative virtual address (RVA) of the data. This is the byte offset of the data stream from the beginning of the minidump file.

Remarks

In this context, a data stream refers to a block of data within a minidump file.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MINIDUMP_DIRECTORY, MINIDUMP_EXCEPTION_STREAM, MINIDUMP_MEMORY_DESCRIPTOR


MINIDUMP_MEMORY_DESCRIPTOR

The MINIDUMP_MEMORY_DESCRIPTOR structure describes a range of memory.

typedef struct _MINIDUMP_MEMORY_DESCRIPTOR {
    ULONG64 StartOfMemoryRange;
    MINIDUMP_LOCATION_DESCRIPTOR Memory;
} MINIDUMP_MEMORY_DESCRIPTOR, *PMINIDUMP_MEMORY_DESCRIPTOR;

The MINIDUMP_MEMORY_DESCRIPTOR64 structure is defined as follows. It is used for full-memory minidumps.

typedef struct _MINIDUMP_MEMORY_DESCRIPTOR64 {
    ULONG64 StartOfMemoryRange;
    ULONG64 DataSize;
} MINIDUMP_MEMORY_DESCRIPTOR64, *PMINIDUMP_MEMORY_DESCRIPTOR64;

Members

StartOfMemoryRange
Starting address of the memory range.
Memory
A MINIDUMP_LOCATION_DESCRIPTOR structure.
DataSize
Size of the data block, in bytes.

Remarks

MINIDUMP_MEMORY_DESCRIPTOR64 is used for full-memory minidumps where all of the raw memory is laid out sequentially at the end of the minidump. There is no need for individual relative virtual addresses (RVAs), because the RVA is the base RVA plus the sum of the preceding data blocks.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_LOCATION_DESCRIPTOR


MINIDUMP_MEMORY_LIST

The MINIDUMP_MEMORY_LIST structure contains a list of memory ranges.

typedef struct _MINIDUMP_MEMORY_LIST {
    ULONG32 NumberOfMemoryRanges;
    MINIDUMP_MEMORY_DESCRIPTOR MemoryRanges [0];
} MINIDUMP_MEMORY_LIST, *PMINIDUMP_MEMORY_LIST;

The MINIDUMP_MEMORY64_LIST structure is defined as follows. It is used for full-memory minidumps.

typedef struct _MINIDUMP_MEMORY64_LIST {
    ULONG64 NumberOfMemoryRanges;
    RVA64 BaseRva;
    MINIDUMP_MEMORY_DESCRIPTOR64 MemoryRanges [0];
} MINIDUMP_MEMORY64_LIST, *PMINIDUMP_MEMORY64_LIST;

Members

NumberOfMemoryRanges
Number of structures in the MemoryRanges array.
BaseRva
Overall base RVA for the memory list. To locate the data for a particular descriptor, start at BaseRva and increment by the size of a descriptor until you reach the descriptor.
MemoryRanges
An array of MINIDUMP_MEMORY_DESCRIPTOR structures.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_MEMORY_DESCRIPTOR, MINIDUMP_STREAM_TYPE


MINIDUMP_MISC_INFO

The MINIDUMP_MISC_INFO structure contains a variety of information.

typedef struct _MINIDUMP_MISC_INFO {
    ULONG32 SizeOfInfo;
    ULONG32 Flags1;
    ULONG32 ProcessId;
    ULONG32 ProcessCreateTime;
    ULONG32 ProcessUserTime;
    ULONG32 ProcessKernelTime;
} MINIDUMP_MISC_INFO, *PMINIDUMP_MISC_INFO;

Members

SizeOfInfo
Size of the structure, in bytes.
Flags1
Valid members of this structure. This member can be one or more of the following values.
Value | Meaning
MINIDUMP_MISC1_PROCESS_ID | ProcessId is used.
MINIDUMP_MISC1_PROCESS_TIMES | ProcessCreateTime, ProcessKernelTime, and ProcessUserTime are used.

ProcessId
Identifier of the process. If Flags1 does not specify MINIDUMP_MISC1_PROCESS_ID, this member is unused.
ProcessCreateTime
Creation time of the process, in time_t format. If Flags1 does not specify MINIDUMP_MISC1_PROCESS_TIMES, this member is unused.
ProcessUserTime
Time the process has executed in user mode, in seconds. The time that each of the threads of the process has executed in user mode is determined, then all these times are summed to obtain this value. If Flags1 does not specify MINIDUMP_MISC1_PROCESS_TIMES, this member is unused.
ProcessKernelTime
Time the process has executed in kernel mode, in seconds. The time that each of the threads of the process has executed in kernel mode is determined, then all these times are summed to obtain this value. If Flags1 does not specify MINIDUMP_MISC1_PROCESS_TIMES, this member is unused.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_STREAM_TYPE


MINIDUMP_MODULE

The MINIDUMP_MODULE structure contains information for a specific module.

typedef struct _MINIDUMP_MODULE {
    ULONG64 BaseOfImage;
    ULONG32 SizeOfImage;
    ULONG32 CheckSum;
    ULONG32 TimeDateStamp;
    RVA ModuleNameRva;
    VS_FIXEDFILEINFO VersionInfo;
    MINIDUMP_LOCATION_DESCRIPTOR CvRecord;
    MINIDUMP_LOCATION_DESCRIPTOR MiscRecord;
    ULONG64 Reserved0;
    ULONG64 Reserved1;
} MINIDUMP_MODULE, *PMINIDUMP_MODULE;

Members

BaseOfImage
Base address of the module executable image in memory.
SizeOfImage
Size of the module executable image in memory, in bytes.
CheckSum
Checksum value of the module executable image.
TimeDateStamp
Timestamp value of the module executable image, in time_t format..
ModuleNameRva
An RVA to a MINIDUMP_STRING structure that specifies the name of the module.
VersionInfo
A VS_FIXEDFILEINFO structure that specifies the version of the module.
CvRecord
Pointer to a string containing the CodeView record of the module.
MiscRecord
Pointer to a string that specifies the miscellaneous record of the module.
Reserved0
Reserved for future use.
Reserved1
Reserved for future use.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_MODULE_LIST, MINIDUMP_STRING, VS_FIXEDFILEINFO


MINIDUMP_MODULE_CALLBACK

The MINIDUMP_MODULE_CALLBACK structure contains module information for the MiniDumpCallback function when the callback type is ModuleCallback.

typedef struct _MINIDUMP_MODULE_CALLBACK {
  PWCHAR FullPath;
  ULONG64 BaseOfImage;
  ULONG SizeOfImage;
  ULONG CheckSum;
  ULONG TimeDateStamp;
  VS_FIXEDFILEINFO VersionInfo;
  PVOID CvRecord;
  ULONG SizeOfCvRecord;
  PVOID MiscRecord;
  ULONG SizeOfMiscRecord;
} MINIDUMP_MODULE_CALLBACK, *PMINIDUMP_MODULE_CALLBACK;

Members

FullPath
Pointer to a string that specifies the fully qualified path of the module executable.
BaseOfImage
Base address of the module executable image in memory.
SizeOfImage
Size of the module executable image in memory, in bytes.
CheckSum
Checksum value of the module executable image.
TimeDateStamp
Timestamp value of the module executable image, in time_t format..
VersionInfo
A VS_FIXEDFILEINFO structure that specifies the version of the module.
CvRecord
Pointer to a string containing the CodeView record of the module.
SizeOfCvRecord
Size of the Codeview record of the module in the CvRecord member, in bytes.
MiscRecord
Pointer to a string that specifies the miscellaneous record of the module.
SizeOfMiscRecord
Size of the miscellaneous record of the module in the MiscRecord member, in bytes.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MINIDUMP_CALLBACK_INPUT, MiniDumpCallback, VS_FIXEDFILEINFO


MINIDUMP_MODULE_LIST

The MINIDUMP_MODULE_LIST structure contains a list of modules.

typedef struct _MINIDUMP_MODULE_LIST {
    ULONG32 NumberOfModules;
    MINIDUMP_MODULE Modules[0];
} MINIDUMP_MODULE_LIST, *PMINIDUMP_MODULE_LIST;

Members

NumberOfModules
Number of structures in the Modules array.
Modules
Array of MINIDUMP_MODULE structures.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_MODULE, MINIDUMP_STREAM_TYPE


MINIDUMP_STRING

The MINIDUMP_STRING structure describes a string.

typedef struct _MINIDUMP_STRING {
    ULONG32 Length;
    WCHAR   Buffer [0];
} MINIDUMP_STRING, *PMINIDUMP_STRING;

Members

Length
Size of Buffer, in bytes.
Buffer
Pointer to a variably sized buffer that contains the null-terminated string.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_HANDLE_DESCRIPTOR, MINIDUMP_MODULE, MINIDUMP_UNLOADED_MODULE


MINIDUMP_SYSTEM_INFO

The MINIDUMP_SYSTEM_INFO structure contains processor and operating system information.

typedef struct _MINIDUMP_SYSTEM_INFO {
    USHORT ProcessorArchitecture;
    USHORT ProcessorLevel;
    USHORT ProcessorRevision;
    union {
        USHORT Reserved0;
        struct {
            UCHAR NumberOfProcessors;
            UCHAR ProductType;
        };
    };
    ULONG32 MajorVersion;
    ULONG32 MinorVersion;
    ULONG32 BuildNumber;
    ULONG32 PlatformId;
    RVA CSDVersionRva;
    union {
        ULONG32 Reserved1;
        struct {
            USHORT SuiteMask;
            USHORT Reserved2;
        };
    };
    union _CPU_INFORMATION {
        struct {
            ULONG32 VendorId[3];
            ULONG32 VersionInformation;
            ULONG32 FeatureInformation;
            ULONG32 AMDExtendedCpuFeatures;
        } X86CpuInfo;

        struct {
            ULONG64 ProcessorFeatures[2];
        } OtherCpuInfo;

    } Cpu;
} MINIDUMP_SYSTEM_INFO, *PMINIDUMP_SYSTEM_INFO;

Members

ProcessorArchitecture
System's processor architecture. This member can be one of the following values:

PROCESSOR_ARCHITECTURE_UNKNOWN
PROCESSOR_ARCHITECTURE_INTEL
64-bit Windows: PROCESSOR_ARCHITECTURE_IA64
64-bit Windows: PROCESSOR_ARCHITECTURE_IA32_ON_WIN64
64-bit Windows: PROCESSOR_ARCHITECTURE_AMD64

ProcessorLevel
System's architecture-dependent processor level.

If ProcessorArchitecture is PROCESSOR_ARCHITECTURE_INTEL, ProcessorLevel can be one of the following values.
Value | Meaning
3 | Intel 80386
4 | Intel 80486
5 | Intel Pentium
6 | Intel Pentium Pro or Pentium II

If ProcessorArchitecture is PROCESSOR_ARCHITECTURE_IA64, ProcessorLevel is set to 1.

ProcessorRevision
Architecture-dependent processor revision.
Processor Value
Intel 80386 or 80486 A value of the form xxyz.

If xx is equal to 0xFF, y - 0xA is the model number, and z is the stepping identifier. For example, an Intel 80486-D0 system returns 0xFFD0.

If xx is not equal to 0xFF, xx + 'A' is the stepping letter and yz is the minor stepping.

Intel Pentium, Cyrix, or NextGen 586 A value of the form xxyy, where xx is the model number and yy is the stepping. Display this value of 0x0201 as follows:

Model xx, Stepping yy

Reserved0
Reserved for future use. Must be zero.
NumberOfProcessors
Number of processors in the system.
ProductType
Additional information about the system. This member can be one of the following values.
Value | Meaning
VER_NT_WORKSTATION | The system is running Windows NT 4.0 Workstation, Windows 2000 Professional, Windows XP Home Edition, or Windows XP Professional.
VER_NT_DOMAIN_CONTROLLER | The system is a domain controller.
VER_NT_SERVER | The system is a server.

MajorVersion
Major version number of the operating system. This member can be one of the following values.
Operating system | Value
Windows 95 | 4
Windows 98 | 4
Windows Me | 4
Windows NT 3.51 | 3
Windows NT 4.0 | 4
Windows 2000 | 5
Windows XP | 5
Windows .NET Server | 5

MinorVersion
Minor version number of the operating system. This member can be one of the following values.
Operating system | Value
Windows 95 | 0
Windows 98 | 10
Windows Me | 90
Windows NT 3.51 | 51
Windows NT 4.0 | 0
Windows 2000 | 0
Windows XP | 1
Windows .NET Server | 2

BuildNumber
Windows NT/2000/XP: Build number of the operating system.

Windows 95/98/Me: The low-order word contains the build number of the operating system. The high-order word contains the major and minor version numbers.

PlatformId
Operating system platform. This member can be one of the following values.
Value | Platform
VER_PLATFORM_WIN32s | Win32s on Windows 3.1.
VER_PLATFORM_WIN32_WINDOWS | Windows 95, Windows 98, or Windows Me.
VER_PLATFORM_WIN32_NT | Windows NT 3.51, Windows NT 4.0, Windows 2000, Windows XP, or Windows .NET Server.

CSDVersionRva
Windows NT/2000/XP: A null-terminated string, such as "Service Pack 3", that indicates the latest Service Pack installed on the system. If no Service Pack has been installed, the string is empty.

Windows 95/98/Me: A null-terminated string that indicates additional version information. For example, " C" indicates Windows 95 OSR2 and " A" indicates Windows 98 SE.

Reserved1
Reserved for future use.
SuiteMask
Bit flags that identify the product suites available on the system. This member can be a combination of the following values.
Value | Meaning
VER_SUITE_BACKOFFICE | Microsoft BackOffice components are installed.
VER_SUITE_BLADE | Windows .NET Web Server is installed.
VER_SUITE_DATACENTER | Windows 2000 or Windows .NET Datacenter Server is installed.
VER_SUITE_ENTERPRISE | Windows 2000 Advanced Server or Windows .NET Enterprise Server is installed.
VER_SUITE_PERSONAL | Windows XP Home Edition is installed.
VER_SUITE_SMALLBUSINESS | Microsoft Small Business Server is installed.
VER_SUITE_SMALLBUSINESS_RESTRICTED | Microsoft Small Business Server is installed with the restrictive client license in force.
VER_SUITE_TERMINAL | Terminal Services is installed.

Reserved2
Reserved for future use.
X86CpuInfo
CPU information obtained from the CPUID instruction. This structure is supported only for x86 computers.
Member | Description
VendorId CPUID subfunction 0. The array elements are as follows:

VendorId[0] is EAX
VendorId[1] is EBX
VendorId[2] is ECX
VersionInformation | CPUID subfunction 1. Value of EAX.
FeatureInformation | CPUID subfunction 1. Value of EDX.
AMDExtendedCpuFeatures | CPUID subfunction 80000001. Value of EBX. This member is supported only if the vendor is "AuthenticAMD".

OtherCpuInfo
Other CPU information. This structure is supported only for non-x86 computers.
Member | Description
ProcessorFeatures | For a list of possible values, see the IsProcessorFeaturePresent function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, IsProcessorFeaturePresent, MINIDUMP_STREAM_TYPE


MINIDUMP_THREAD

The MINIDUMP_THREAD structure contains information for a specific thread.

typedef struct _MINIDUMP_THREAD {
    ULONG32 ThreadId;
    ULONG32 SuspendCount;
    ULONG32 PriorityClass;
    ULONG32 Priority;
    ULONG64 Teb;
    MINIDUMP_MEMORY_DESCRIPTOR Stack;
    MINIDUMP_LOCATION_DESCRIPTOR ThreadContext;
} MINIDUMP_THREAD, *PMINIDUMP_THREAD;

Members

ThreadId
Identifier of the thread.
SuspendCount
Suspend count for the thread. If the suspend count is greater than zero, the thread is suspended; otherwise, the thread is not suspended. The maximum value is MAXIMUM_SUSPEND_COUNT.
PriorityClass
Priority class of the thread. See Scheduling Priorities.
Priority
Priority level of the thread.
Teb
Thread environment block.
Stack
A MINIDUMP_MEMORY_DESCRIPTOR structure.
ThreadContext
A MINIDUMP_LOCATION_DESCRIPTOR structure.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_LOCATION_DESCRIPTOR, MINIDUMP_MEMORY_DESCRIPTOR


MINIDUMP_THREAD_CALLBACK

The MINIDUMP_THREAD_CALLBACK structure contains thread information for the MiniDumpCallback function when the callback type is ThreadCallback.

typedef struct _MINIDUMP_THREAD_CALLBACK {
  ULONG ThreadId;
  HANDLE ThreadHandle;
  CONTEXT Context;
  ULONG SizeOfContext;
  ULONG64 StackBase;
  ULONG64 StackEnd;
} MINIDUMP_THREAD_CALLBACK, *PMINIDUMP_THREAD_CALLBACK;

Members

ThreadId
Identifier of the thread.
ThreadHandle
Handle to the thread
Context
Processor-specific data returned in a CONTEXT structure.
SizeOfContext
Size of the returned processor-specific data in the Context member, in bytes.
StackBase
Base address of the thread stack.
StackEnd
Ending address of the thread stack.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MINIDUMP_CALLBACK_INPUT, MiniDumpCallback, CONTEXT


MINIDUMP_THREAD_EX

The MINIDUMP_THREAD_EX structure contains extended information for a specific thread.

typedef struct _MINIDUMP_THREAD_EX {
    ULONG32 ThreadId;
    ULONG32 SuspendCount;
    ULONG32 PriorityClass;
    ULONG32 Priority;
    ULONG64 Teb;
    MINIDUMP_MEMORY_DESCRIPTOR Stack;
    MINIDUMP_LOCATION_DESCRIPTOR ThreadContext;
    MINIDUMP_MEMORY_DESCRIPTOR BackingStore;
} MINIDUMP_THREAD_EX, *PMINIDUMP_THREAD_EX;

Members

ThreadId
Identifier of the thread.
SuspendCount
Suspend count for the thread. If the suspend count is greater than zero, the thread is suspended; otherwise, the thread is not suspended. The maximum value is MAXIMUM_SUSPEND_COUNT.
PriorityClass
Priority class of the thread. See Scheduling Priorities.
Priority
Priority level of the thread.
Teb
Thread environment block.
Stack
A MINIDUMP_MEMORY_DESCRIPTOR structure.
ThreadContext
A MINIDUMP_LOCATION_DESCRIPTOR structure.
BackingStore
IA64: Backing store for the thread.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_LOCATION_DESCRIPTOR, MINIDUMP_MEMORY_DESCRIPTOR


MINIDUMP_THREAD_EX_CALLBACK

The MINIDUMP_THREAD_EX_CALLBACK structure contains extended thread information for the MiniDumpCallback function when the callback type is ThreadExCallback.

typedef struct _MINIDUMP_THREAD_EX_CALLBACK {
    ULONG ThreadId;
    HANDLE ThreadHandle;
    CONTEXT Context;
    ULONG SizeOfContext;
    ULONG64 StackBase;
    ULONG64 StackEnd;
    ULONG64 BackingStoreBase;
    ULONG64 BackingStoreEnd;
} MINIDUMP_THREAD_EX_CALLBACK, *PMINIDUMP_THREAD_EX_CALLBACK;

Members

ThreadId
Identifier of the thread.
ThreadHandle
Handle to the thread
Context
Processor-specific data returned in a CONTEXT structure.
SizeOfContext
Size of the returned processor-specific data in the Context member, in bytes.
StackBase
Base address of the thread stack.
StackEnd
Ending address of the thread stack.
BackingStoreBase
IA64: Base address of the thread backing store.
BackingStoreEnd
IA64: Ending address of the thread backing store.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_CALLBACK_INPUT, MiniDumpCallback, CONTEXT


MINIDUMP_THREAD_EX_LIST

The MINIDUMP_THREAD_EX_LIST structure contains a list of threads.

typedef struct _MINIDUMP_THREAD_EX_LIST {
    ULONG32 NumberOfThreads;
    MINIDUMP_THREAD_EX Threads [0];
} MINIDUMP_THREAD_EX_LIST, *PMINIDUMP_THREAD_EX_LIST;

Members

NumberOfThreads
Number of structures in the Threads array.
Threads
Array of MINIDUMP_THREAD_EX structures.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_STREAM_TYPE, MINIDUMP_THREAD_EX


MINIDUMP_THREAD_LIST

The MINIDUMP_THREAD_LIST structure contains a list of threads.

typedef struct _MINIDUMP_THREAD_LIST {
    ULONG32 NumberOfThreads;
    MINIDUMP_THREAD Threads [0];
} MINIDUMP_THREAD_LIST, *PMINIDUMP_THREAD_LIST;

Members

NumberOfThreads
Number of structures in the Threads array.
Threads
Array of MINIDUMP_THREAD structures.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_STREAM_TYPE, MINIDUMP_THREAD


MINIDUMP_UNLOADED_MODULE

The MINIDUMP_UNLOADED_MODULE structure contains information about a module that has been unloaded. This can help diagnose problems calling code that is no longer loaded.

typedef struct _MINIDUMP_UNLOADED_MODULE {
    ULONG64 BaseOfImage;
    ULONG32 SizeOfImage;
    ULONG32 CheckSum;
    ULONG32 TimeDateStamp;
    RVA ModuleNameRva;
} MINIDUMP_UNLOADED_MODULE, *PMINIDUMP_UNLOADED_MODULE;

Members

BaseOfImage
Base address of the module executable image in memory.
SizeOfImage
Size of the module executable image in memory, in bytes.
CheckSum
Checksum value of the module executable image.
TimeDateStamp
Timestamp value of the module executable image, in time_t format.
ModuleNameRva
An RVA to a MINIDUMP_STRING structure that specifies the name of the module.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_UNLOADED_MODULE_LIST


MINIDUMP_UNLOADED_MODULE_LIST

The MINIDUMP_UNLOADED_MODULE_LIST structure contains a list of unloaded modules.

typedef struct _MINIDUMP_UNLOADED_MODULE_LIST {
    ULONG32 SizeOfHeader;
    ULONG32 SizeOfEntry;
    ULONG32 NumberOfEntries;
} MINIDUMP_UNLOADED_MODULE_LIST, *PMINIDUMP_UNLOADED_MODULE_LIST;

Members

SizeOfHeader
Size of the header data for the stream, in bytes. This is generally sizeof(MINIDUMP_UNLOADED_MODULE_LIST).
SizeOfEntry
Size of each entry following the header, in bytes. This is generally sizeof(MINIDUMP_UNLOADED_MODULE).
NumberOfEntries
Number of entries in the stream.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, MINIDUMP_STREAM_TYPE, MINIDUMP_UNLOADED_MODULE


MINIDUMP_USER_STREAM

The MINIDUMP_USER_STREAM structure contains user-defined information stored in a data stream.

typedef struct _MINIDUMP_USER_STREAM {
  ULONG32 Type;
  ULONG BufferSize;
  PVOID Buffer;
} MINIDUMP_USER_STREAM, *PMINIDUMP_USER_STREAM;

Members

Type
Type of data stream. For more information, see MINIDUMP_STREAM_TYPE.
BufferSize
Size of the user-defined data stream buffer, in bytes.
Buffer
Pointer to a buffer that contains the user-defined data stream.

Remarks

In this context, a data stream refers to a block of data within a minidump file.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MINIDUMP_STREAM_TYPE, MINIDUMP_USER_STREAM_INFORMATION, MiniDumpCallback


MINIDUMP_USER_STREAM_INFORMATION

The MINIDUMP_USER_STREAM_INFORMATION structure contains a list of user data streams used by the MiniDumpWriteDump function.

typedef struct _MINIDUMP_USER_STREAM_INFORMATION {
  ULONG UserStreamCount;
  PMINIDUMP_USER_STREAM UserStreamArray;
} MINIDUMP_USER_STREAM_INFORMATION, *PMINIDUMP_USER_STREAM_INFORMATION;

Members

UserStreamCount
Number of user streams.
UserStreamArray
Array of MINIDUMP_USER_STREAM structures.

Remarks

In this context, a data stream refers to a block of data within a minidump file.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, MINIDUMP_USER_STREAM, MiniDumpWriteDump


MODLOAD_DATA

The MODLOAD_DATA structure represents module data.

typedef struct _DBGHELP_MODLOAD_DATA {
    DWORD   ssize;
    DWORD   ssig;
    PVOID   data;
    DWORD   size;
    DWORD   flags;
} MODLOAD_DATA, *PMODLOAD_DATA;

Members

ssize
Size of this structure, in bytes.
ssig
Type of data. If this member is DBHHEADER_DEBUGDIRS, the data member is a buffer that contains an array of IMAGE_DEBUG_DIRECTORY structures.
data
Data. The format of this data depends on the value of ssig.
size
Size of the data buffer, in bytes.
flags
Unused.

Requirements

Windows NT/2000/XP: Included in Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows XP; Windows 2000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, IMAGE_DEBUG_DIRECTORY, SymLoadModuleEx


STACKFRAME64

The STACKFRAME64 structure represents a stack frame.

This structure supersedes the STACKFRAME structure. For more information, see Updated Platform Support.

typedef struct _tagSTACKFRAME64 {
  ADDRESS64 AddrPC;
  ADDRESS64 AddrReturn;
  ADDRESS64 AddrFrame;
  ADDRESS64 AddrStack;
  ADDRESS64 AddrBStore;
  PVOID     FuncTableEntry;
  DWORD64   Params[4];
  BOOL      Far;
  BOOL      Virtual;
  DWORD64   Reserved[3];
  KDHELP64  KdHelp;
} STACKFRAME64, *LPSTACKFRAME64;

Members

AddrPC
An ADDRESS64 structure that specifies the program counter.

x86: The program counter is EIP.

IA64: The program counter is StIIP.

AMD64: The program counter is RIP.

AddrReturn
An ADDRESS64 structure that specifies the return address.
AddrFrame
An ADDRESS64 structure that specifies the frame pointer.

x86: The frame pointer is EBP.

Alpha: There is no frame pointer, so the Offset member is not used and should be zero. However, the Offset member is used when walking a kernel stack which terminates in an exception frame. This is a special case.

IA64: There is no frame pointer, but AddrBStore is used.

AMD64: The frame pointer is RBP. AMD64 does not always use this value.

AddrStack
An ADDRESS64 structure that specifies the stack pointer.

x86: The stack pointer is ESP.

IA64: The stack pointer is SP.

AMD64: The stack pointer is RSP.

FuncTableEntry
On x86 computers, this member is an FPO_DATA structure. On Alpha computers, this member is an IMAGE_FUNCTION_ENTRY structure. If there is no function table entry, this member is NULL.
Params
Possible arguments to the function.
Far
This member is TRUE if this is a WOW far call.
Virtual
This member is TRUE if this is a virtual frame.
Reserved
Used internally by the StackWalk64 function.
KdHelp
A KDHELP64 structure that specifies helper data for walking kernel callback frames.
AddrBStore
IA64: An ADDRESS64 structure that specifies the backing store (RsBSP).

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Redistributable: Requires DbgHelp.dll on Windows NT 4.0 and Windows 95/98/Me.
Header: Declared in Dbghelp.h.

See Also

DbgHelp Structures, ADDRESS64, FPO_DATA, IMAGE_FUNCTION_ENTRY, KDHELP64, StackWalk64


SYMBOL_INFO

The SYMBOL_INFO structure contains symbol information.

typedef struct _SYMBOL_INFO {
    ULONG       SizeOfStruct;
    ULONG       TypeIndex;
    ULONG64     Reserved[2];
    ULONG       Reserved2;
    ULONG       Size;
    ULONG64     ModBase;
    ULONG       Flags;
    ULONG64     Value;
    ULONG64     Address;
    ULONG       Register;
    ULONG       Scope;
    ULONG       Tag;
    ULONG       NameLen;
    ULONG       MaxNameLen;
    CHAR        Name[1];
} SYMBOL_INFO, *PSYMBOL_INFO;

Members

SizeOfStruct
Size of the structure, in bytes.
TypeIndex
Type index of the symbol.
Reserved
Reserved for system use.
Reserved2
Reserved for system use.
Size
Symbol size, in bytes. This value is typically zero and should be ignored.
ModBase
Base address of the module that contains the symbol.
Flags
Options. This member can be one or more of the following values.
Value | Meaning
IMAGEHLP_SYMBOL_FUNCTION | The symbol is a function.
IMAGEHLP_SYMBOL_INFO_CONSTANT | The symbol is a constant.
IMAGEHLP_SYMBOL_INFO_FRAMERELATIVE | Offsets are frame relative.
IMAGEHLP_SYMBOL_INFO_LOCAL | The symbol is a local variable.
IMAGEHLP_SYMBOL_INFO_PARAMETER | The symbol is a parameter.
IMAGEHLP_SYMBOL_INFO_REGISTER | The symbol is a register. The Register member is used.
IMAGEHLP_SYMBOL_INFO_REGRELATIVE | Offsets are register relative.
IMAGEHLP_SYMBOL_INFO_TLSRELATIVE | Windows .NET Server: The symbol is an offset into the TLS data area.
IMAGEHLP_SYMBOL_INFO_VALUEPRESENT | The Value member is used.
IMAGEHLP_SYMBOL_THUNK | Windows .NET Server: The symbol is a thunk.
IMAGEHLP_SYMBOL_VIRTUAL | Windows .NET Server: The symbol is a virtual symbol created by the SymAddSymbol function.

Value
Value of a constant.
Address
Virtual address of the start of the symbol.
Register
Indicates the register.
Scope
DIA scope. For more information, see the DIA information included with Visual Studio 7.0.
Tag
PDB classification. For more information, see the PDB documentation.
NameLen
Length of the name, in characters.
MaxNameLen
Size of the Name buffer.
Name
Name of the symbol. The name can be undecorated if the SYMOPT_UNDNAME option is used with the SymSetOptions function.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, SymEnumSymbolsProc, SymFromAddr, SymFromName, SymGetTypeFromName


TI_FINDCHILDREN_PARAMS

The TI_FINDCHILDREN_PARAMS structure is used by the SymGetTypeInfo function.

typedef struct _TI_FINDCHILDREN_PARAMS {
    ULONG Count;
    ULONG Start;
    ULONG ChildId[1];
} TI_FINDCHILDREN_PARAMS;

Members

Count
Number of children.
Start
Zero-based index of the child from which the child indexes are to be retrieved. For example, in an array with five elements, if Start is two, this indicates the third array element. In most cases, this member is zero.
ChildId
Array of type indexes. There is one index per child.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Structures, SymGetTypeInfo


DbgHelp Enumerations

The following are the DbgHelp enumerations.

MINIDUMP_CALLBACK_TYPE
MINIDUMP_STREAM_TYPE
MINIDUMP_TYPE
MODULE_WRITE_FLAGS
THREAD_WRITE_FLAGS


MINIDUMP_CALLBACK_TYPE

The MINIDUMP_CALLBACK_TYPE enumeration values identify the type of information returned by the MiniDumpCallback function.

typedef enum _MINIDUMP_CALLBACK_TYPE {
  ModuleCallback,
  ThreadCallback,
  ThreadExCallback,
  IncludeThreadCallback,
  IncludeModuleCallback
} MINIDUMP_CALLBACK_TYPE;

Member

ModuleCallback
The callback function returns module information.
ThreadCallback
The callback function returns thread information.
ThreadExCallback
The callback function returns extended thread information.
IncludeThreadCallback
The callback function is called as the minidump library is enumerating the threads in a process, rather than after the information gathered, as it is with ThreadCallback or ThreadExCallback. If the callback function returns FALSE, the thread is subsequently ignored. This allows the caller to obtain information for a subset of the threads in a process, without suspending threads that are not of interest.
IncludeModuleCallback
The callback function is called as the minidump library is enumerating the modules in a process, rather than after the information is gathered, as it is with ModuleCallback. If the callback function returns FALSE, the module is subsequently ignored. Additionally, you can modify the ModuleWriteFlags member of the MINIDUMP_CALLBACK_OUTPUT structure to avoid gathering unnecessary information for the remaining modules. These steps can improve performance.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Enumerations, MINIDUMP_CALLBACK_INPUT, MiniDumpCallback


MINIDUMP_STREAM_TYPE

The MINIDUMP_STREAM_TYPE enumeration values identify the type of a data stream.

typedef enum _MINIDUMP_STREAM_TYPE {
  UnusedStream                = 0,
  ReservedStream0             = 1,
  ReservedStream1             = 2,
  ThreadListStream            = 3,
  ModuleListStream            = 4,
  MemoryListStream            = 5,
  ExceptionStream             = 6,
  SystemInfoStream            = 7,
  ThreadExListStream          = 8,
  Memory64ListStream          = 9,
  CommentStreamA              = 10,
  CommentStreamW              = 11,
  HandleDataStream            = 12,
  FunctionTableStream         = 13,
  UnloadedModuleListStream    = 14,
  MiscInfoStream              = 15,
  LastReservedStream          = 0xffff
} MINIDUMP_STREAM_TYPE;

Members

UnusedStream
Reserved. Do not use this enumeration value.
ReservedStream0
Reserved. Do not use this enumeration value.
ReservedStream1
Reserved. Do not use this enumeration value.
ThreadListStream
The stream contains thread information. For more information, see MINIDUMP_THREAD_LIST.
ModuleListStream
The stream contains module information. For more information, see MINIDUMP_MODULE_LIST.
MemoryListStream
The stream contains memory allocation information. For more information, see MINIDUMP_MEMORY_LIST.
ExceptionStream
The stream contains exception information. For more information, see MINIDUMP_EXCEPTION_STREAM.
SystemInfoStream
The stream contains general system information. For more information, see MINIDUMP_SYSTEM_INFO.
ThreadExListStream
The stream contains extended thread information. For more information, see MINIDUMP_THREAD_EX_LIST.
Memory64ListStream
The stream contains memory allocation information. For more information, see MINIDUMP_MEMORY64_LIST.
CommentStreamA
The stream contains an ANSI string used for documentation purposes.
CommentStreamW
The stream contains a Unicode string used for documentation purposes.
HandleDataStream
The stream contains high-level information about the active operating system handles. For more information, see MINIDUMP_HANDLE_DATA_STREAM.
FunctionTableStream
The stream contains function table information. For more information, see MINIDUMP_FUNCTION_TABLE_STREAM.
UnloadedModuleListStream
Windows .NET Server: The stream contains module information for the unloaded modules. For more information, see MINIDUMP_UNLOADED_MODULE_LIST.
MiscInfoStream
Windows .NET Server: The stream contains miscellaneous information. For more information, see MINIDUMP_MISC_INFO.
LastReservedStream
Any value greater than this value will not be used by the system and can be used to represent application-defined data streams. For more information, see MINIDUMP_USER_STREAM.

Remarks

In this context, a data stream is a set of data in a minidump file.

The StreamType member of the MINIDUMP_DIRECTORY structure can be one of these types. Additional types may be added in the future, so if a program reading the minidump header encounters a stream type it does not recognize, it should ignore the stream altogether.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Enumerations, MINIDUMP_DIRECTORY, MINIDUMP_EXCEPTION_STREAM, MINIDUMP_FUNCTION_TABLE_STREAM, MINIDUMP_HANDLE_DATA_STREAM, MINIDUMP_MEMORY_LIST, MINIDUMP_MISC_INFO, MINIDUMP_MODULE_LIST, MINIDUMP_SYSTEM_INFO, MINIDUMP_THREAD_EX_LIST, MINIDUMP_THREAD_LIST, MINIDUMP_UNLOADED_MODULE_LIST, MINIDUMP_USER_STREAM


MINIDUMP_TYPE

The MINIDUMP_TYPE enumeration values identify the type of information that will be written to the minidump file by the MiniDumpWriteDump function.

typedef enum _MINIDUMP_TYPE {
  MiniDumpNormal                          = 0x0000,
  MiniDumpWithDataSegs                    = 0x0001,
  MiniDumpWithFullMemory                  = 0x0002,
  MiniDumpWithHandleData                  = 0x0004,
  MiniDumpFilterMemory                    = 0x0008,
  MiniDumpScanMemory                      = 0x0010,
  MiniDumpWithUnloadedModules             = 0x0020,
  MiniDumpWithIndirectlyReferencedMemory  = 0x0040,
  MiniDumpFilterModulePaths               = 0x0080,
  MiniDumpWithProcessThreadData           = 0x0100,
  MiniDumpWithPrivateReadWriteMemory      = 0x0200
} MINIDUMP_TYPE;

Members

MiniDumpNormal
Include just the information necessary to capture stack traces for all existing threads in a process.
MiniDumpWithDataSegs
Include the data sections from all loaded modules. This results in the inclusion of global variables, which can make the minidump file significantly larger.
MiniDumpWithFullMemory
Include all accessible memory in the process. The raw memory data is included at the end, so that the initial structures can be mapped directly without the raw memory information. This option can result in a very large file.
MiniDumpWithHandleData
Windows NT/2000/XP: Include high-level information about the operating system handles that are active when the minidump is made.
MiniDumpFilterMemory
Stack and backing store memory written to the minidump file should be filtered to remove all but the pointer values necessary to reconstruct a stack trace. Typically, this removes any private information.
MiniDumpScanMemory
Stack and backing store memory should be scanned for pointer references to modules in the module list. If a module is referenced by stack or backing store memory, the ModuleWriteFlags member of the MINIDUMP_CALLBACK_OUTPUT structure is set to ModuleReferencedByMemory.
MiniDumpWithUnloadedModules
Windows .NET Server: Include information from the list of modules that were recently unloaded, if this information is maintained by the operating system.
MiniDumpWithIndirectlyReferencedMemory
Windows .NET Server: Include pages with data referenced by locals or other stack memory. This option can increase the size of the minidump file significantly.
MiniDumpFilterModulePaths
Windows .NET Server: Filter module paths for information such as user names or important directories. This option may prevent the system from locating the image file and should be used only in special situations.
MiniDumpWithProcessThreadData
Windows .NET Server: Include complete per-process and per-thread information from the operating system.
MiniDumpWithPrivateReadWriteMemory
Windows .NET Server: Scan the virtual address space for other types of memory to be included.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Enumerations, MiniDumpWriteDump


MODULE_WRITE_FLAGS

The MODULE_WRITE_FLAGS enumeration values identify the type of module information that will be written to the minidump file by the MiniDumpWriteDump function.

typedef enum _MODULE_WRITE_FLAGS {
  ModuleWriteModule        = 0x0001,
  ModuleWriteDataSeg       = 0x0002,
  ModuleWriteMiscRecord    = 0x0004,
  ModuleWriteCvRecord      = 0x0008,
  ModuleReferencedByMemory = 0x0010
} MODULE_WRITE_FLAGS;

Members

ModuleWriteModule
Only module information will be written to the minidump file.
ModuleWriteDataSeg
Module and data segment information will be written to the minidump file.
ModuleWriteMiscRecord
Module, data segment, and miscellaneous record information will be written to the minidump file.
ModuleWriteCvRecord
CodeView information will be written to the minidump file. Some debuggers need the CodeView information to properly locate symbols.
ModuleReferencedByMemory
Indicates that a module was referenced by a pointer on the stack or backing store of a thread in the minidump. This value is set only if the DumpType parameter of the MiniDumpWriteDump function includes MiniDumpScanMemory.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Enumerations, MINIDUMP_CALLBACK_OUTPUT, MiniDumpWriteDump


THREAD_WRITE_FLAGS

The THREAD_WRITE_FLAGS enumeration values identify the type of thread information that will be written to the minidump file by the MiniDumpWriteDump function.

typedef enum _THREAD_WRITE_FLAGS {
  ThreadWriteThread            = 0x0001,
  ThreadWriteStack             = 0x0002,
  ThreadWriteContext           = 0x0004
  ThreadWriteBackingStore      = 0x0008,
  ThreadWriteInstructionWindow = 0x0010,
  ThreadWriteThreadData        = 0x0020
} THREAD_WRITE_FLAGS;

Members

ThreadWriteThread
Only basic thread information will be written to the minidump file.
ThreadWriteStack
Basic thread and thread stack information will be written to the minidump file.
ThreadWriteContext
The entire thread context will be written to the minidump file.
ThreadWriteBackingStore
IA64: The backing store memory of every thread will be written to the minidump file.
ThreadWriteInstructionWindow
A small amount of memory surrounding each thread's instruction pointer will be written to the minidump file. This allows instructions near a thread's instruction pointer to be disassembled even if an executable image matching the module cannot be found.
ThreadWriteThreadData
Windows .NET Server: When the minidump type includes MiniDumpWithProcessThreadData, the ThreadWriteThreadData flag is set. The callback function can clear this flag to control which threads provide complete thread data in the minidump file.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
Redistributable: Requires DbgHelp.dll on Windows 20000; Windows NT 4.0; and Windows 95/98/Me.
Header: Declared in DbgHelp.h.

See Also

DbgHelp Enumerations, MINIDUMP_CALLBACK_OUTPUT, MiniDumpWriteDump


Image Help Library

This overview describes the function set provided by the ImageHlp DLL. These functions allow you to work with a portable executable (PE) image.

  • About ImageHlp
  • ImageHlp Reference

Warning Starting with Windows® 2000, you can no longer redistribute the ImageHlp DLL that is included with the operating system. A subset of the functions have been moved to a DLL that is redistributable. Existing applications will continue to work because ImageHlp uses forwarders to call into the new DLL. However, these applications should be modified to use the new DLL. For more information, see Debug Help Library.


About ImageHlp

The ImageHlp functions are used mostly by programming tools, application setup utilities, and other programs that need access to the data contained in a PE image. All ImageHlp functions are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

The following topics describe PE images and the functionality provided by the ImageHlp functions.

  • PE Format
  • Image Access Functions
  • Image Integrity Functions
  • Image Modification Functions


PE Format

Executable (image) files are structured according to the Portable Executable (PE) format. For a description of this format, see the specification available for download from the following location: http://www.microsoft.com/hwdev/hardware/PECOFF.asp.


Image Access Functions

The image access functions access the data in an executable image. These functions provide high-level access to the base of images and very specific access to the most common parts of an image's data.

  • GetImageConfigInformation
  • GetImageUnusedHeaderBytes
  • ImageLoad
  • ImageUnload
  • MapAndLoad
  • SetImageConfigInformation
  • UnMapAndLoad


ImageHlp Image Integrity Functions

DbgHelp and ImageHlp APIs

Image Integrity Functions

The image integrity functions manage the set of certificates in an image file. Routines are provided to add, remove, and query certificates. There is also a function available for obtaining the byte stream of an image file required to calculate a message digest of the image file. This is needed to create signature certificates.

Every certificate in a file has an index which can change as certificates are removed. New certificates will always be added "at the end" of the list of existing certificates. That is, they will be assigned indices that are greater than any index currently in use. In general, an application should not assume that a given certificate has the same index it had the last time it was referenced.

  • DigestFunction
  • ImageAddCertificate
  • ImageEnumerateCertificates
  • ImageGetCertificateData
  • ImageGetCertificateHeader
  • ImageGetDigestStream
  • ImageRemoveCertificate


ImageHlp Image Modification Functions

The image modification functions allow you to change the executable image. They are mostly for use by development tools and install programs. They can be used to bind an image, compute its checksum (which is important for ensuring image integrity), change its load address, and produce symbol files.

The following are the image modification functions.

  • BindImage
  • BindImageEx
  • CheckSumMappedFile
  • MapFileAndCheckSum
  • ReBaseImage
  • SplitSymbols
  • StatusRoutine
  • TouchFileTimes
  • UpdateDebugInfoFile
  • UpdateDebugInfoFileEx


ImageHlp Reference

The following elements are part of ImageHlp.

  • ImageHlp Functions
  • ImageHlp Structures


ImageHlp Functions

The following are the ImageHlp functions.

Image Access

The image access functions access the data in an executable image. The functions provide high-level access to the base of images and very specific access to the most common parts of an image's data.

GetImageConfigInformation
GetImageUnusedHeaderBytes
ImageLoad
ImageUnload
MapAndLoad
SetImageConfigInformation
UnMapAndLoad

Image Integrity

The image integrity functions manage the set of certificates in an image file.

DigestFunction
ImageAddCertificate
ImageEnumerateCertificates
ImageGetCertificateData
ImageGetCertificateHeader
ImageGetDigestStream
ImageRemoveCertificate

Image Modification

The image modification functions allow you to change the executable image.

BindImage
BindImageEx
CheckSumMappedFile
MapFileAndCheckSum
ReBaseImage
SplitSymbols
StatusRoutine
TouchFileTimes
UpdateDebugInfoFile
UpdateDebugInfoFileEx


BindImage

The BindImage function computes the virtual address of each imported function.

This function has been superseded by the BindImageEx function. Use BindImageEx to provide a status routine or flags to control the image binding.

BOOL BindImage(
  PSTR ImageName,
  PSTR DllPath,
  PSTR SymbolPath
);

Parameters

ImageName
[in] Pointer to a null-terminated string that specifies the name of the file to be bound. This value can be a file name, a partial path, or a full path.
DllPath
[in] Pointer to a null-terminated string that specifies the root of the search path to use if the file specified by the ImageName parameter cannot be opened.
SymbolPath
[in] Pointer to a null-terminated string that specifies the root of the path to search for the file's corresponding symbol file.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

A call to BindImage is equivalent to the following call:

BindImageEx( 0, ImageName, DllPath, SymbolPath, NULL );

For more information, see BindImageEx .

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, BindImageEx


BindImageEx

The BindImageEx function computes the virtual address of each function that is imported.

This function supersedes the BindImage function. Use BindImageEx to provide a status routine or flags to control the image binding.

BOOL BindImageEx(
  DWORD Flags,
  PSTR ImageName,
  PSTR DllPath,
  PSTR SymbolPath,
  PIMAGEHLP_STATUS_ROUTINE StatusRoutine
);

Parameters

Flags
[in] Bind options. This parameter can be a combination of the following values.
Value | Meaning
BIND_NO_BOUND_IMPORTS Do not generate a new import address table.

Windows 95/98/Me: This flag is required.

BIND_NO_UPDATE | Do not make changes to the file.
BIND_ALL_IMAGES | Bind all images in the call tree for this file.
BIND_CACHE_IMPORT_DLLS | Do not discard DLL information in the cache between calls. This improves performance when binding a large number of images.

ImageName
[in] Pointer to a null-terminated string that specifies the name of the file to be bound. This value can be a file name, a partial path, or a full path.
DllPath
[in] Pointer to a null-terminated string that specifies the root of the search path to use if the file specified by the ImageName parameter cannot be opened.
SymbolPath
[in] Pointer to a null-terminated string that specifies the root of the path to search for the file's corresponding symbol file.
StatusRoutine
[in] Pointer to a status routine. The status routine is called during the progress of the image binding. For more information, see StatusRoutine.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The process of binding an image consists of computing the virtual address of each imported function. The computed virtual address is then saved in the importing image's Import Address Table (IAT). As a result, the image is loaded much faster, particularly if it uses many DLLs, because the system loader does not have to computer the address of each imported function.

If a corresponding symbol file can be located, its time stamp and checksum are updated.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, StatusRoutine


CheckSumMappedFile

The CheckSumMappedFile function computes the checksum of the specified image file.

PIMAGE_NT_HEADERS CheckSumMappedFile(
  PVOID BaseAddress,
  DWORD FileLength,
  PDWORD HeaderSum,
  PDWORD CheckSum
);

Parameters

BaseAddress
[in] Base address of the mapped file. This value is obtained by calling the MapViewOfFile function.
FileLength
[in] Size of the file, in bytes.
HeaderSum
[out] Pointer to a variable that receives the original checksum from the image file, or zero if there is an error.
CheckSum
[out] Pointer to the variable that receives the computed checksum.

Return Values

If the function succeeds, the return value is a pointer to the IMAGE_NT_HEADERS structure contained in the mapped image.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The CheckSumMappedFile function computes a new checksum for the file and returns it in the CheckSum parameter. This function is used by any application that creates or modifies an executable image. Checksums are required for kernel-mode drivers and some system DLLs. The linker computes the original checksum at link time, if you use the appropriate linker switch. For more details, see your linker documentation.

It is recommended that all images have valid checksums. It is the caller's responsibility to place the newly computed checksum into the mapped image and update the on-disk image of the file.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, IMAGE_NT_HEADERS, MapFileAndCheckSum, MapViewOfFile


DigestFunction

The DigestFunction function is an application-defined callback function used by the ImageGetDigestStream function to process data.

The DIGEST_FUNCTION type defines a pointer to this callback function. DigestFunction is a placeholder for the application-defined function name.

BOOL DigestFunction (
  DIGEST_HANDLE refdata,
  PBYTE pData,
  DWORD dwLength
);

Parameters

refdata
[in] User-supplied handle to the digest. This value is passed as a parameter to the ImageGetDigestStream function.
pData
[in] Data stream.
dwLength
[in] Size of the data stream, in bytes.

Return Value

If the function succeeds, the return value should be TRUE. If the function fails, the return value should be FALSE.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.

See Also

Image Help Library Overview, ImageHlp Functions, ImageGetDigestStream


GetImageConfigInformation

The GetImageConfigInformation function locates and returns the load configuration data of an image.

BOOL GetImageConfigInformation(
  PLOADED_IMAGE LoadedImage,
  PIMAGE_LOAD_CONFIG_DIRECTORY ImageConfigInformation
);

Parameters

LoadedImage
[in] Pointer to a LOADED_IMAGE structure that is returned from a call to MapAndLoad or LoadImage.
ImageConfigInformation
[out] Pointer to an IMAGE_LOAD_CONFIG_DIRECTORY structure that receives the configuration information.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SetImageConfigInformation function locates and changes the load configuration data of an image.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, IMAGE_LOAD_CONFIG_DIRECTORY, LOADED_IMAGE, SetImageConfigInformation


GetImageUnusedHeaderBytes

The GetImageUnusedHeaderBytes function returns the offset and size of the part of the PE header that is currently unused.

DWORD GetImageUnusedHeaderBytes(
  PLOADED_IMAGE LoadedImage,
  PDWORD SizeUnusedHeaderBytes
);

Parameters

LoadedImage
[in] Pointer to a LOADED_IMAGE structure that is returned from a call to MapAndLoad or LoadImage.
SizeUnusedHeaderBytes
[out] Pointer to a variable to receive the size, in bytes, of the part of the image's header which is unused.

Return Values

If the function succeeds, the return value is the offset from the base address of the first unused header byte.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, LOADED_IMAGE


ImageAddCertificate

The ImageAddCertificate function is used to add a certificate to the specified file.

BOOL ImageAddCertificate(
  HANDLE FileHandle,
  LPWIN_CERTIFICATE Certificate,
  PDWORD Index
);

Parameters

FileHandle
[in] Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA and FILE_WRITE_DATA access.
Certificate
[in] Pointer to a WIN_CERTIFICATE header and all associated sections. The Length member in the certificate header will be used to determine the length of this buffer.
Index
[out] Receives the index of the newly added certificate.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The certificate is added at the end of the existing list of certificates and is assigned an index.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, ImageRemoveCertificate


ImageEnumerateCertificates

The ImageEnumerateCertificates function is used to return information about the certificates currently contained in an image file.

BOOL ImageEnumerateCertificates(
  HANDLE FileHandle,
  WORD TypeFilter,
  PDWORD CertificateCount,
  PDWORD Indices,
  DWORD IndexCount
);

Parameters

FileHandle
[in] Handle to the image file to be examined. This handle must be opened for FILE_READ_DATA access.
TypeFilter
[in] Certificate section type to be used as a filter when returning certificate information. CERT_SECTION_TYPE_ANY should be passed for information on all section types present in the image.
CertificateCount
[out] Pointer to a variable that receives the number of certificates in the image containing sections of the type specified by the TypeFilter parameter. If none are found, this parameter is zero .
Indices
[in/out] Optionally provides a buffer to use to return an array of indices to the certificates containing sections of the specified type. No ordering should be assumed for the index values, nor are they guaranteed to be contiguous when CERT_SECTION_TYPE_ANY is queried.
IndexCount
[in/out] Size of the Indices buffer, in DWORDs. This parameter will be examined whenever Indices is present. If CertificateCount is greater than IndexCount, Indices will be filled in with the first IndexCount sections found in the image and an appropriate warning will be returned.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The ImageEnumerateCertificates function returns information about the certificates currently contained in an image file. It has filtering capabilities which allow certificates containing sections of any single type (or of any type) to be returned.

After the indices of interesting certificates are discovered, they can be passed to the ImageGetCertificateData function to obtain the actual bodies of the certificates.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, ImageGetCertificateData


ImageGetCertificateData

The ImageGetCertificateData function is used to return a complete certificate from a file.

BOOL ImageGetCertificateData(
  HANDLE FileHandle,
  DWORD CertificateIndex,
  LPWIN_CERTIFICATE Certificate,
  PDWORD RequiredLength
);

Parameters

FileHandle
[in] Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA access.
CertificateIndex
[in] Index of the certificate to be returned.
Certificate
[out] Pointer to a WIN_CERTIFICATE structure that receives the certificate data.
RequiredLength
[in/out] On input, this parameter specifies the length of the Certificate buffer in bytes. On return, it receives the length of the certificate.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions


ImageGetCertificateHeader

The ImageGetCertificateHeader function is used to return only the header part of the specified certificate, up to, but not including, the section offset array.

BOOL ImageGetCertificateHeader(
  HANDLE FileHandle,
  DWORD CertificateIndex,
  LPWIN_CERTIFICATE CertificateHeader
);

Parameters

FileHandle
[in] Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA access.
CertificateIndex
[in] Index of the certificate whose header is to be returned.
CertificateHeader
[in/out] Pointer to the WIN_CERTIFICATE structure that receives the certificate header.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions


ImageGetDigestStream

The ImageGetDigestStream function returns the data to be digested from a given image file, subject to the passed DigestLevel parameter.

BOOL ImageGetDigestStream(
  HANDLE FileHandle,
  DWORD DigestLevel,
  DIGEST_FUNCTION DigestFunction,
  DIGEST_HANDLE DigestHandle,
);

Parameters

FileHandle
[in] Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA access.
DigestLevel
[in] Aspects of the image that are to be included in the returned data stream. This parameter can be one or more of the following values.
Value | Meaning
CERT_PE_IMAGE_DIGEST_DEBUG_INFO | Include symbolic debugging information.
CERT_PE_IMAGE_DIGEST_RESOURCES | Include resource information.
CERT_PE_IMAGE_DIGEST_ALL_IMPORT_INFO | Include all import information.

DigestFunction
[in] Pointer to a callback routine to process the data. For more information, see DigestFunction.
DigestHandle
[in] User-supplied handle to the digest. This parameter is passed to DigestFunction as the first argument.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The ImageGetDigestStream function returns the data to be digested from a specified image file, subject to the passed DigestLevel parameter. The order of the bytes will be consistent for different calls, which is required to ensure that the same message digest is always produced from the retrieved byte stream.

To ensure cross-platform compatibility, all implementations of this function must behave in a consistent manner with respect to the order in which the various parts of the image file are returned.

Data should be returned in the following order:

  1. Image (executable and static data) information.
  2. Resource data.
  3. Debugging information.

If any of these are not specified, the remaining parts must be returned in the same order.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions


ImageLoad

The ImageLoad function maintains a list of loaded DLLs.

PLOADED_IMAGE ImageLoad(
  PSTR DllName,
  PSTR DllPath
);

Parameters

DllName
[in] Pointer to a null-terminated string that specifies the name of the image that is loaded.
DllPath
[in] Pointer to a null-terminated string that specifies the path used to locate the image if the name provided cannot be found. If NULL is used, then the search path rules set forth in the SearchPath function apply.

Return Values

If the function succeeds, the return value is a pointer to a LOADED_IMAGE structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks

The ImageLoad function is used to maintain a list of loaded DLLs. If the image has already been loaded, the prior LOADED_IMAGE is returned. Otherwise, the new image is added to the list.

The LOADED_IMAGE structure must be deallocated by the ImageUnload function.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, ImageUnload, LOADED_IMAGE


ImageRemoveCertificate

The ImageRemoveCertificate function is used to remove the specified certificate from the given file.

BOOL ImageRemoveCertificate(
  HANDLE FileHandle,
  DWORD Index
);

Parameters

FileHandle
[in] Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA and FILE_WRITE_DATA access.
Index
[in] Index of the certificate to be removed.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, ImageAddCertificate


ImageUnload

The ImageUnload function is used to deallocate resources from a previous call to the ImageLoad function.

BOOL ImageUnload(
  PLOADED_IMAGE LoadedImage
);

Parameters

LoadedImage
[in] Pointer to a LOADED_IMAGE structure that is returned from a call to the ImageLoad function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

ImageLoad and ImageUnload share internal data that can be corrupted if multiple consecutive calls to ImageLoad are performed. Therefore, make sure that you have called ImageLoad only once before calling ImageUnload.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, ImageLoad, LOADED_IMAGE


MapAndLoad

The MapAndLoad function maps an image and preloads data from the mapped file.

BOOL MapAndLoad(
  PSTR ImageName,
  PSTR DllPath,
  PLOADED_IMAGE LoadedImage,
  BOOL DotDll,
  BOOL ReadOnly
);

Parameters

ImageName
[in] Pointer to a null-terminated string that specifies the name of the image that is loaded.
DllPath
[in] Pointer to a null-terminated string that specifies the path used to locate the image if the name provided cannot be found. If NULL is used, then the search path rules set forth in the SearchPath function apply.
LoadedImage
[out] Pointer to a LOADED_IMAGE structure that receives information about the image after it is loaded.
DotDll
[in] Default extension to be used if the image name does not contain a file extension. If the value is TRUE, a .DLL extension is used. If the value is FALSE, then an .EXE extension is used.
ReadOnly
[in] Access mode. If this value is TRUE, the file is mapped for read-access only. If the value is FALSE, the file is mapped for read and write access.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The MapAndLoad function maps an image and preloads data from the mapped file. The corresponding function, UnMapAndLoad, must be used to deallocate all resources that are allocated by the MapAndLoad function.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 3.1 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, LOADED_IMAGE, UnMapAndLoad


MapFileAndCheckSum

The MapFileAndCheckSum function computes the checksum of the specified file.

DWORD MapFileAndCheckSum(
  PTSTR Filename,
  PDWORD HeaderSum,
  PDWORD CheckSum
);

Parameters

Filename
[in] Pointer to a null-terminated string that specifies the file name of the file for which the checksum is to be computed.
HeaderSum
[out] Pointer to a variable that receives the original checksum from the image file, or zero if there is an error.
CheckSum
[out] Pointer to the variable that receives the computed checksum.

Return Values

If the function succeeds, the return value is CHECKSUM_SUCCESS.

If the function fails, the return value is one of the following.

Value | Meaning
CHECKSUM_OPEN_FAILURE | Could not open the file.
CHECKSUM_MAP_FAILURE | Could not map the file.
CHECKSUM_MAPVIEW_FAILURE | Could not map a view of the file.
CHECKSUM_UNICODE_FAILURE | Could not convert the file name to Unicode.

Remarks

The MapFileAndCheckSum function computes a new checksum for the file and returns it in the CheckSum parameter. This function is used by any application that creates or modifies an executable image. Checksums are required for kernel-mode drivers and some system DLLs. The linker computes the original checksum at link time, if you use the appropriate linker switch. For more details, see your linker documentation.

It is recommended that all images have valid checksums. It is the caller's responsibility to place the newly computed checksum into the mapped image and update the on-disk image of the file.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 3.1 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.

See Also

Image Help Library Overview, ImageHlp Functions, CheckSumMappedFile


ReBaseImage

The ReBaseImage function is used to change the load address for the specified image, which reduces the required load time for a DLL.

Alternatively, you can use the Rebase tool.

BOOL ReBaseImage(
  PSTR CurrentImageName,
  PSTR SymbolPath,
  BOOL fReBase,
  BOOL fRebaseSysfileOk,
  BOOL fGoingDown,
  ULONG CheckImageSize,
  ULONG *OldImageSize,
  ULONG_PTR *OldImageBase,
  ULONG *NewImageSize,
  ULONG_PTR *NewImageBase,
  ULONG TimeStamp
);

Parameters

CurrentImageName
[in] Pointer to a null-terminated string that specifies file name of the file to be rebased.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path used to find the corresponding symbol file.
fReBase
[in] If this value is TRUE, the image is rebased. Otherwise, the image is not rebased.
fRebaseSysfileOk
[in] If this value is TRUE, the system image is rebased. Otherwise, the system image is not rebased.
fGoingDown
[in] If this value is TRUE, the image can be rebased below the given base; otherwise, it cannot.
CheckImageSize
[in] Maximum size that the image can grow to, in bytes, or zero if there is no limit.
OldImageSize
[out] Pointer to a variable that receives the original image size, in bytes.
OldImageBase
[out] Pointer to a variable that receives the original image base.
NewImageSize
[out] Pointer to a variable that receives the new image size after the rebase operation, in bytes.
NewImageBase
[in/out] Pointer to a variable that receives the new image base after the rebase operation.
TimeStamp
[in] New time stamp for the image. The value must be represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The ReBaseImage function changes the desired load address for the specified image. This operation involves reading the entire image and updating all fixups, debugging information, checksum, and time stamp values. You can rebase an image to reduce the required load time for its DLLs. If an application can rely on a DLL being loaded at the desired load address, then the system loader does not have to relocate the image. The image is simply loaded into the application's virtual address space and the DllMain function is called, if one is present.

A well-behaved application has its DLLs rebased so they each fall within a unique range of the virtual address space. The system DLLs are currently based in memory from 0x70000000 to 0x78000000 (0x68000000 to 0x78000000 on MIPS). Therefore, you should base your DLLs from 0x60000000 to 0x68000000. One possible scheme is to choose a base address based on the first letter of the DLL name, as shown in the following table.

First Letter | Base Address
A - C | 0x60000000
D - F | 0x61000000
G - I | 0x62000000
J - L | 0x63000000
M - O | 0x64000000
P - R | 0x65000000
S - U | 0x66000000
V - X | 0x67000000
Y - Z | 0x68000000

By using these suggestions with the ReBaseImage function, each DLL in an application can be assigned a unique base address. This process can be part of the build process or part of the final release procedure for the application.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 3.1 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, DllMain


SetImageConfigInformation

The SetImageConfigInformation function locates and changes the load configuration data of an image.

BOOL SetImageConfigInformation(
  PLOADED_IMAGE LoadedImage,
  PIMAGE_LOAD_CONFIG_DIRECTORY ImageConfigInformation
);

Parameters

LoadedImage
[in] Pointer to a LOADED_IMAGE structure that is returned from a call to MapAndLoad or LoadImage.
ImageConfigInformation
[in] Pointer to an IMAGE_LOAD_CONFIG_DIRECTORY structure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The GetImageConfigInformation function locates and returns the load configuration data of an image.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, GetImageConfigInformation, IMAGE_LOAD_CONFIG_DIRECTORY, LOADED_IMAGE


SplitSymbols

The SplitSymbols function strips symbols from the specified image.

BOOL SplitSymbols(
  PSTR ImageName,
  PSTR SymbolsPath,
  PSTR SymbolFilePath,
  DWORD Flags
);

Parameters

ImageName
[in] Pointer to a null-terminated string that specifies the name of the image from which to split symbols.
SymbolsPath
[in] Pointer to a null-terminated string that specifies a subdirectory for storing symbols. This parameter is optional.
SymbolFilePath
[in] Pointer to a null-terminated string that specifies the name of the generated symbol file. This file typically has a .dbg extension.
Flags
[in] Information to be split from the image. This parameter can be zero or a combination of the following values.
Value | Meaning
SPLITSYM_EXTRACT_ALL | Usually, an image with the symbols split off will still contain a MISC debug directory with the name of the symbol file. Therefore, the debugger can still find the symbols. Using this flag removes this link. The end result is similar to using the -debug:none switch on the Microsoft linker.
SPLITSYM_REMOVE_PRIVATE | This strips off the private CodeView symbolic information when generating the symbol file.
SPLITSYM_SYMBOLPATH_IS_SRC | The symbol file path contains an alternate path to locate the .pdb file.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The SplitSymbols function should be used when stripping symbols from an image. It will create a symbol file that all compatible debuggers understand. The format is defined in WINNT.H and consists of an image header, followed by the array of section headers, the exception information (on RISC only) or FPO information (on X86 only), and all debugging symbolic information from the image.

If the SymbolsPath parameter is NULL, the symbol file is stored in the directory where the image exists. Otherwise, it is stored in the subdirectory below SymbolsPath that matches the extension of the image. Using this method reduces the chances of symbol file collision. For example, the symbols for myapp.exe will be in the SymbolsPath\exe directory and the symbols for myapp.dll will be in the SymbolsPath\dll directory.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions


StatusRoutine

The StatusRoutine function is an application-defined callback function used with the BindImageEx function. The status routine is called during the process of the image binding.

The PIMAGEHLP_STATUS_ROUTINE type defines a pointer to this callback function. StatusRoutine is a placeholder for the application-defined function name.

BOOL StatusRoutine(
  IMAGEHLP_STATUS_REASON Reason,
  PSTR ImageName,
  PSTR DllName,
  ULONG_PTR Va,
  ULONG_PTR Parameter
);

Parameters

Reason
[in] Current status of the bind operation. This parameter can be one of the following values.
Value | Meaning
BindOutOfMemory | Out of memory. The Parameter value is the number of bytes in the allocation attempt.
BindRvaToVaFailed | The relative virtual address is invalid for the image. The Parameter value is not used.
BindNoRoomInImage | No room in the image for new format import table. The Parameter value is not used.
BindImportModuleFailed | Module import failed. The Parameter value is not used.
BindImportProcedureFailed | Procedure import failed. The Parameter value is the name of the function.
BindImportModule | Module import is starting. The Parameter value is not used.
BindImportProcedure | Procedure import is starting. The Parameter value is the name of the function.
BindForwarder | The Parameter value is the name of the function forwarded.
BindForwarderNOT | The Parameter value is the name of the function not forwarded.
BindImageModified | Image modified. The Parameter value is not used.
BindExpandFileHeaders | File headers expanded. The Parameter value is the number of bytes
BindImageComplete | Binding is complete. For more information on the Parameter value, see the following Remarks section.
BindMismatchedSymbols | Checksum did not match. The Parameter value is the name of the symbol file.
BindSymbolsNotUpdated | Symbol file was not updated. The Parameter value is the name of the symbol file not updated.

ImageName
[in] Pointer to a null-terminated string that specifies the name of the file to be bound. This value can be a file name, a partial path, or a full path.
DllName
[in] Pointer to a null-terminated string that specifies the name of the DLL.
Va
[in] Computed virtual address.
Parameter
[in] Additional status information. This value depends on the value of the Reason parameter. For more information, see the code fragment in the following Remarks section.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

The following code fragment describes the contents of the Parameter value when the status is BindImageComplete.

case BindImageComplete:
    if (fVerbose) {
        fprintf(stderr, "BIND: Details of binding %s\n", ImageName );
        NewImports = (PIMAGE_BOUND_IMPORT_DESCRIPTOR)Va;
        NewImport = NewImports;
        while (NewImport->OffsetModuleName) {
            fprintf( stderr, "    Import from %s [%x]",
                     (LPSTR)NewImports + NewImport->OffsetModuleName,
                     NewImport->TimeDateStamp
                   );
            if (NewImport->NumberOfModuleForwarderRefs != 0) {
                fprintf( stderr, " with %u forwarders", NewImport->
                         NumberOfModuleForwarderRefs );
            }
            fprintf( stderr, "\n" );
            NewForwarder = (PIMAGE_BOUND_FORWARDER_REF)(NewImport+1);
            for (i=0; i<NewImport->NumberOfModuleForwarderRefs; i++) {
                fprintf( stderr, "        Forward to %s [%x]\n",
                   (LPSTR)NewImports + NewForwarder->OffsetModuleName,
                   NewForwarder->TimeDateStamp);
                NewForwarder += 1;
            }
            NewImport = (PIMAGE_BOUND_IMPORT_DESCRIPTOR)NewForwarder;
        }
    }
    break;

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.

See Also

Image Help Library Overview, ImageHlp Functions, BindImageEx


TouchFileTimes

The TouchFileTimes function updates the date and time at which the specified file was last modified.

BOOL TouchFileTimes (
  HANDLE FileHandle,
  PSYSTEMTIME pSystemTime
);

Parameters

FileHandle
[in] Handle to the file of interest.
pSystemTime
[in] Pointer to a SYSTEMTIME structure. If this parameter is NULL, the current system date and time is used.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.
Windows 95/98/Me: Unsupported.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, SYSTEMTIME


UnMapAndLoad

The UnMapAndLoad function is used to deallocate all resources that are allocated by a previous call to the MapAndLoad function.

BOOL UnMapAndLoad(
  PLOADED_IMAGE LoadedImage
);

Parameters

LoadedImage
[in] Pointer to a LOADED_IMAGE structure. This structure is obtained through a call to the MapAndLoad function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The UnMapAndLoad function must be used to deallocate all resources that are allocated by a previous call to MapAndLoad. This function also writes a new checksum value into the image before the file is closed. This ensures that if a file is changed, it can be successfully loaded by the system loader.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, LOADED_IMAGE, MapAndLoad


UpdateDebugInfoFile

The UpdateDebugInfoFile function uses the specified information to update the corresponding fields in the symbol file.

This function has been superseded by the UpdateDebugInfoFileEx function. Use UpdateDebugInfoFileEx to verify the checksum value.

BOOL UpdateDebugInfoFile(
  PSTR ImageFileName,
  PSTR SymbolPath,
  PSTR DebugFilePath,
  PIMAGE_NT_HEADERS NtHeaders
);

Parameters

ImageFileName
[in] Pointer to a null-terminated string that specifies the name of the image that is now out of date with respect to its symbol file.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path in which to look for the symbol file.
DebugFilePath
[out] Pointer to a buffer that receives the name of the symbol file that was updated.
NtHeaders
[in] Pointer to an IMAGE_NT_HEADERS structure that specifies the new header information.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The UpdateDebugInfoFile function takes the information stored in the IMAGE_NT_HEADERS structure and updates the corresponding fields in the symbol file. Any time an image file is modified, this function should be called to keep the numbers in sync. Specifically, whenever an image checksum changes, the symbol file should be updated to match.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, IMAGE_NT_HEADERS, UpdateDebugInfoFileEx


UpdateDebugInfoFileEx

The UpdateDebugInfoFileEx function uses the specified information to update the corresponding fields in the symbol file.

This function supersedes the UpdateDebugInfoFile function. Use UpdateDebugInfoFileEx to verify the checksum value.

BOOL UpdateDebugInfoFileEx(
  PSTR ImageFileName,
  PSTR SymbolPath,
  PSTR DebugFilePath,
  PIMAGE_NT_HEADERS NtHeaders,
  DWORD OldChecksum
);

Parameters

ImageFileName
[in] Pointer to a null-terminated string that specifies the name of the image that is now out of date with respect to its symbol file.
SymbolPath
[in] Pointer to a null-terminated string that specifies the path in which to look for the symbol file.
DebugFilePath
[out] Pointer to a buffer that receives the name of the symbol file that was updated.
NtHeaders
[in] Pointer to an IMAGE_NT_HEADERS structure that specifies the new header information.
OldChecksum
[in] Original checksum value. If this value does not match the checksum that is present in the mapped image, the flags in the symbol file contain IMAGE_SEPARATE_DEBUG_MISMATCH and the last error value is set to ERROR_INVALID_DATA.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The UpdateDebugInfoFileEx function takes the information stored in the IMAGE_NT_HEADERS structure and updates the corresponding fields in the symbol file. Any time an image file is modified, this function should be called to keep the numbers in sync. Specifically, whenever an image checksum changes, the symbol file should be updated to match.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Imagehlp.h.
Library: Use Imagehlp.lib.

See Also

Image Help Library Overview, ImageHlp Functions, IMAGE_NT_HEADERS


ImageHlp Structures

The following are the ImageHlp data structures.

FPO_DATA
IMAGE_COFF_SYMBOLS_HEADER
IMAGE_DATA_DIRECTORY
IMAGE_DEBUG_DIRECTORY
IMAGE_FILE_HEADER
IMAGE_FUNCTION_ENTRY
IMAGE_LOAD_CONFIG_DIRECTORY
IMAGE_NT_HEADERS
IMAGE_OPTIONAL_HEADER
IMAGE_SECTION_HEADER


FPO_DATA

The FPO_DATA structure represents the stack frame layout for a function on an x86 computer when frame pointer omission (FPO) optimization is used. The structure is used to locate the base of the call frame.

typedef struct _FPO_DATA {
  DWORD ulOffStart;
  DWORD cbProcSize;
  DWORD cdwLocals;
  WORD cdwParams;
  WORD cbProlog : 8;
  WORD cbRegs   : 3;
  WORD fHasSEH  : 1;
  WORD fUseBP   : 1;
  WORD reserved : 1;
  WORD cbFrame  : 2;
} FPO_DATA, *PFPO_DATA;

Members

ulOffStart
Offset of the first byte of the function code.
cbProcSize
Number of bytes in the function.
cdwLocals
Number of local variables, in DWORDs.
cdwParams
Size of the parameters, in DWORDs.
cbProlog
Number of bytes in the function prolog code.
cbRegs
Number of registers saved.
fHasSEH
Indicates whether the function uses structured exception handling.
fUseBP
Indicates whether the EBP register has been allocated.
reserved
Reserved for future use.
cbFrame
Indicates the frame type.
Type | Meaning
FRAME_FPO | FPO frame
FRAME_TRAP | Trap frame
FRAME_TSS | TSS frame
FRAME_NONFPO | Non-FPO frame

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, FunctionTableAccessProc64, STACKFRAME64, SymFunctionTableAccess64


IMAGE_COFF_SYMBOLS_HEADER

The IMAGE_COFF_SYMBOLS_HEADER structure represents the COFF symbols header.

typedef struct _IMAGE_COFF_SYMBOLS_HEADER {
  DWORD   NumberOfSymbols;
  DWORD   LvaToFirstSymbol;
  DWORD   NumberOfLinenumbers;
  DWORD   LvaToFirstLinenumber;
  DWORD   RvaToFirstByteOfCode;
  DWORD   RvaToLastByteOfCode;
  DWORD   RvaToFirstByteOfData;
  DWORD   RvaToLastByteOfData;
} IMAGE_COFF_SYMBOLS_HEADER, *PIMAGE_COFF_SYMBOLS_HEADER;

Members

NumberOfSymbols
Number of symbols.
LvaToFirstSymbol
Virtual address of the first symbol.
NumberOfLinenumbers
Number of line-number entries.
LvaToFirstLinenumber
Virtual address of the first line-number entry.
RvaToFirstByteOfCode
Relative virtual address of the first byte of code.
RvaToLastByteOfCode
Relative virtual address of the last byte of code.
RvaToFirstByteOfData
Relative virtual address of the first byte of data.
RvaToLastByteOfData
Relative virtual address of the last byte of data.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures


IMAGE_DATA_DIRECTORY

The IMAGE_DATA_DIRECTORY structure represents the data directory.

typedef struct _IMAGE_DATA_DIRECTORY {
  DWORD   VirtualAddress;
  DWORD   Size;
} IMAGE_DATA_DIRECTORY, *PIMAGE_DATA_DIRECTORY;

Members

VirtualAddress
Relative virtual address of the table.
Size
Size of the table, in bytes.

Remarks

The following is a list of the data directories:

Offset | Description
96 | Export table address and size
104 | Import table address and size
112 | Resource table address and size
120 | Exception table address and size
128 | Certificate table address and size
136 | Base relocation table address and size
144 | Debugging information starting address and size
152 | Architecture-specific data address and size
160 | Global pointer register relative virtual address
168 | Thread local storage (TLS) table address and size
176 | Load configuration table address and size
184 | Bound import table address and size
192 | Import address table address and size
200 | Delay import descriptor address and size
208 | Reserved

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, IMAGE_OPTIONAL_HEADER


IMAGE_DEBUG_DIRECTORY

The IMAGE_DEBUG_DIRECTORY structure represents the debug directory format.

typedef struct _IMAGE_DEBUG_DIRECTORY {
  DWORD   Characteristics;
  DWORD   TimeDateStamp;
  WORD    MajorVersion;
  WORD    MinorVersion;
  DWORD   Type;
  DWORD   SizeOfData;
  DWORD   AddressOfRawData;
  DWORD   PointerToRawData;
} IMAGE_DEBUG_DIRECTORY, *PIMAGE_DEBUG_DIRECTORY;

Members

Characteristics
Reserved.
TimeDateStamp
Time and date the debugging information was created.
MajorVersion
Major version number of the debugging information format.
MinorVersion
Minor version number of the debugging information format.
Type
Format of the debugging information. This member can be one of the following values.
Constant | Description
IMAGE_DEBUG_TYPE_UNKNOWN | Unknown value, ignored by all tools.
IMAGE_DEBUG_TYPE_COFF | COFF debugging information (line numbers, symbol table, and string table). This type of debugging information is also pointed to by fields in the file headers.
IMAGE_DEBUG_TYPE_CODEVIEW | CodeView debugging information. The format of the data block is described by the CodeView 4.0 specification.
IMAGE_DEBUG_TYPE_FPO | Frame pointer omission (FPO) information. This information tells the debugger how to interpret nonstandard stack frames, which use the EBP register for a purpose other than as a frame pointer.
IMAGE_DEBUG_TYPE_MISC | Miscellaneous information.
IMAGE_DEBUG_TYPE_EXCEPTION | Exception information.
IMAGE_DEBUG_TYPE_FIXUP | Fixup information.
IMAGE_DEBUG_TYPE_BORLAND | Borland debugging information.

SizeOfData
Size of the debugging information, in bytes. This value does not include the debug directory itself.
AddressOfRawData
Address of the debugging information when the image is loaded, relative to the image base.
PointerToRawData
File pointer to the debugging information.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures


IMAGE_FILE_HEADER

The IMAGE_FILE_HEADER structure represents the COFF header format.

typedef struct _IMAGE_FILE_HEADER {
  WORD Machine;
  WORD NumberOfSections;
  DWORD TimeDateStamp;
  DWORD PointerToSymbolTable;
  DWORD NumberOfSymbols;
  WORD SizeOfOptionalHeader;
  WORD Characteristics;
} IMAGE_FILE_HEADER, *PIMAGE_FILE_HEADER;

Members

Machine
Architecture type of the computer. This member can be one of the following values.
Value | Meaning
IMAGE_FILE_MACHINE_I386 | Intel
IMAGE_FILE_MACHINE_IA64 | 64-bit Windows: Intel
IMAGE_FILE_MACHINE_AMD64 | 64-bit Windows: AMD
IMAGE_FILE_MACHINE_ALPHA | Windows NT 4.0 and earlier: DEC Alpha
IMAGE_FILE_MACHINE_POWERPC | Windows NT 4.0 and earlier: Power PC

NumberOfSections
Number of sections.
TimeDateStamp
Time stamp of the image. This represents the date and time the image was created by the linker. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock.
PointerToSymbolTable
Offset of the symbol table, in bytes, or zero if no symbol table exists.
NumberOfSymbols
Number of symbols in the symbol table.
SizeOfOptionalHeader
Size of the optional header, in bytes.
Characteristics
Characteristics of the image. This member can be one or more of the following values.
Value | Meaning
IMAGE_FILE_RELOCS_STRIPPED | Relocation information is stripped from the file.
IMAGE_FILE_EXECUTABLE_IMAGE | The file is executable (there are no unresolved external references).
IMAGE_FILE_LINE_NUMS_STRIPPED | Line numbers are stripped from the file.
IMAGE_FILE_LOCAL_SYMS_STRIPPED | Local symbols are stripped from file.
IMAGE_FILE_AGGRESIVE_WS_TRIM | Aggressively trim the working set.
IMAGE_FILE_LARGE_ADDRESS_AWARE | The application can handle addresses larger than 2 GB.
IMAGE_FILE_BYTES_REVERSED_LO | Bytes of the word are reversed.
IMAGE_FILE_32BIT_MACHINE | Computer supports 32-bit words.
IMAGE_FILE_DEBUG_STRIPPED | Debugging information is stored separately in a .dbg file.
IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP | If the image is on removable media, copy and run from the swap file.
IMAGE_FILE_NET_RUN_FROM_SWAP | If the image is on the network, copy and run from the swap file.
IMAGE_FILE_SYSTEM | System file.
IMAGE_FILE_DLL | DLL file.
IMAGE_FILE_UP_SYSTEM_ONLY | File should be run only on a uniprocessor computer.
IMAGE_FILE_BYTES_REVERSED_HI | Bytes of word are reversed.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, IMAGE_NT_HEADERS


IMAGE_FUNCTION_ENTRY

The IMAGE_FUNCTION_ENTRY structure represents an entry in the function table.

typedef struct _IMAGE_FUNCTION_ENTRY {
  DWORD StartingAddress;
  DWORD EndingAddress;
  DWORD EndOfPrologue;
} IMAGE_FUNCTION_ENTRY, *PIMAGE_FUNCTION_ENTRY;

Members

StartingAddress
Image address of the start of the function.
EndingAddress
Image address of the end of the function.
EndOfPrologue
Image address of the end of the prologue code.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, STACKFRAME64


IMAGE_LOAD_CONFIG_DIRECTORY

The IMAGE_LOAD_CONFIG_DIRECTORY structure contains the load configuration data of an image.

typedef struct _IMAGE_LOAD_CONFIG_DIRECTORY {
  DWORD   Characteristics;
  DWORD   TimeDateStamp;
  WORD    MajorVersion;
  WORD    MinorVersion;
  DWORD   GlobalFlagsClear;
  DWORD   GlobalFlagsSet;
  DWORD   CriticalSectionDefaultTimeout;
  DWORD   DeCommitFreeBlockThreshold;
  DWORD   DeCommitTotalFreeThreshold;
  DWORD   LockPrefixTable;
  DWORD   MaximumAllocationSize;
  DWORD   VirtualMemoryThreshold;
  DWORD   ProcessHeapFlags;
  DWORD   ProcessAffinityMask;
  WORD    CSDVersion;
  WORD    Reserved1;
  DWORD   EditList;
  DWORD   Reserved[ 1 ];
} IMAGE_LOAD_CONFIG_DIRECTORY, *PIMAGE_LOAD_CONFIG_DIRECTORY;

64-bit Windows: This structure is defined as follows.

typedef struct {
  DWORD      Characteristics;
  DWORD      TimeDateStamp;
  WORD       MajorVersion;
  WORD       MinorVersion;
  DWORD      GlobalFlagsClear;
  DWORD      GlobalFlagsSet;
  DWORD      CriticalSectionDefaultTimeout;
  ULONGLONG  DeCommitFreeBlockThreshold;
  ULONGLONG  DeCommitTotalFreeThreshold;
  ULONGLONG  LockPrefixTable;
  ULONGLONG  MaximumAllocationSize;
  ULONGLONG  VirtualMemoryThreshold;
  ULONGLONG  ProcessAffinityMask;
  DWORD      ProcessHeapFlags;
  WORD       CSDVersion;
  WORD       Reserved1;
  ULONGLONG  EditList;
  DWORD      Reserved[ 2 ];
} IMAGE_LOAD_CONFIG_DIRECTORY64, *PIMAGE_LOAD_CONFIG_DIRECTORY64;

Members

Characteristics
Flags indicating attributes of the file. This member is currently unused.
TimeDateStamp
Date and time stamp value. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The time stamp can be printed using the C run-time (CRT) function ctime.
MajorVersion
Major version number.
MinorVersion
Minor version number.
GlobalFlagsClear
Global flags that control system behavior. For more information, see Gflags.exe, which is available as part of the Windows NT 4.0 Resource Kit or on the Windows 2000 CD in the Support\Tools directory.
GlobalFlagsSet
Global flags that control system behavior. For more information, see Gflags.exe, which is available as part of the Windows NT 4.0 Resource Kit or on the Windows 2000 CD in the Support\Tools directory.
CriticalSectionDefaultTimeout
Critical section default time-out value.
DeCommitFreeBlockThreshold
Memory that must be freed before it is returned to the system, in bytes.
DeCommitTotalFreeThreshold
Total amount of free memory, in bytes.
LockPrefixTable
Reserved for use by the system.
MaximumAllocationSize
Maximum allocation size, in bytes.
VirtualMemoryThreshold
Maximum virtual memory size, in bytes.
ProcessHeapFlags
Process heap flags.
ProcessAffinityMask
Process affinity mask. For more information, see GetProcessAffinityMask.
CSDVersion
CSD version.
Reserved1
Reserved for use by the operating system.
EditList
Reserved for use by the system.
Reserved
Reserved for use by the operating system.

Requirements

Windows NT/2000/XP: Included in Windows NT 3.51 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, GetImageConfigInformation, GetProcessAffinityMask, SetImageConfigInformation


IMAGE_NT_HEADERS

The IMAGE_NT_HEADERS structure represents the PE header format.

typedef struct _IMAGE_NT_HEADERS {
  DWORD Signature;
  IMAGE_FILE_HEADER FileHeader;
  IMAGE_OPTIONAL_HEADER OptionalHeader;
} IMAGE_NT_HEADERS, *PIMAGE_NT_HEADERS;

Members

Signature
A 4-byte signature identifying the file as a PE image. The bytes are "PE\0\0".
FileHeader
An IMAGE_FILE_HEADER structure that specifies the file header.
OptionalHeader
An IMAGE_OPTIONAL_HEADER structure that specifies the optional file header.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, CheckSumMappedFile, IMAGE_FILE_HEADER, IMAGE_OPTIONAL_HEADER, ImageNtHeader, ImageRvaToSection, ImageRvaToVa, LOADED_IMAGE, UpdateDebugInfoFile


IMAGE_OPTIONAL_HEADER

The IMAGE_OPTIONAL_HEADER structure represents the optional header format.

typedef struct _IMAGE_OPTIONAL_HEADER {
  WORD    Magic;
  BYTE    MajorLinkerVersion;
  BYTE    MinorLinkerVersion;
  DWORD   SizeOfCode;
  DWORD   SizeOfInitializedData;
  DWORD   SizeOfUninitializedData;
  DWORD   AddressOfEntryPoint;
  DWORD   BaseOfCode;
  DWORD   BaseOfData;
  DWORD   ImageBase;
  DWORD   SectionAlignment;
  DWORD   FileAlignment;
  WORD    MajorOperatingSystemVersion;
  WORD    MinorOperatingSystemVersion;
  WORD    MajorImageVersion;
  WORD    MinorImageVersion;
  WORD    MajorSubsystemVersion;
  WORD    MinorSubsystemVersion;
  DWORD   Win32VersionValue;
  DWORD   SizeOfImage;
  DWORD   SizeOfHeaders;
  DWORD   CheckSum;
  WORD    Subsystem;
  WORD    DllCharacteristics;
  DWORD   SizeOfStackReserve;
  DWORD   SizeOfStackCommit;
  DWORD   SizeOfHeapReserve;
  DWORD   SizeOfHeapCommit;
  DWORD   LoaderFlags;
  DWORD   NumberOfRvaAndSizes;
  IMAGE_DATA_DIRECTORY DataDirectory[IMAGE_NUMBEROF_DIRECTORY_ENTRIES];
} IMAGE_OPTIONAL_HEADER, *PIMAGE_OPTIONAL_HEADER;

Members

Magic
State of the image file. This member can be one of the following values.
Value | Meaning
IMAGE_NT_OPTIONAL_HDR_MAGIC | The file is an executable image.
IMAGE_ROM_OPTIONAL_HDR_MAGIC | The file is a ROM image.

MajorLinkerVersion
Major version number of the linker.
MinorLinkerVersion
Minor version number of the linker.
SizeOfCode
Size of the code section, in bytes, or the sum of all such sections if there are multiple code sections.
SizeOfInitializedData
Size of the initialized data section, in bytes, or the sum of all such sections if there are multiple initialized data sections.
SizeOfUninitializedData
Size of the uninitialized data section, in bytes, or the sum of all such sections if there are multiple uninitialized data sections.
AddressOfEntryPoint
Pointer to the entry point function, relative to the image base address. The entry point function is optional for DLLs. When no entry point is present, this member is zero.
BaseOfCode
Pointer to the beginning of the code section, relative to the image base.
BaseOfData
Pointer to the beginning of the data section, relative to the image base.
ImageBase
Preferred address of the first byte of the image when it is loaded in memory. This value is a multiple of 64K bytes. The default value for DLLs is 0x10000000. The default value for applications is 0x00400000.
SectionAlignment
Alignment of sections loaded in memory, in bytes. This value must be greater than or equal to the FileAlignment member. The default value is the page size for the system.
FileAlignment
Alignment of the raw data of sections in the image file, in bytes. The value should be a power of 2 between 512 and 64K (inclusive). The default is 512. If the SectionAlignment member is less than the system page size, this member must be the same as SectionAlignment.
MajorOperatingSystemVersion
Major version number of the required operating system.
MinorOperatingSystemVersion
Minor version number of the required operating system.
MajorImageVersion
Major version number of the image.
MinorImageVersion
Minor version number of the image.
MajorSubsystemVersion
Major version number of the subsystem.
MinorSubsystemVersion
Minor version number of the subsystem.
Win32VersionValue
This member is reserved.
SizeOfImage
Size of the image, in bytes, including all headers. Must be a multiple of SectionAlignment.
SizeOfHeaders
Combined size of the MS-DOS stub, the PE header, and the section headers, rounded to a multiple of the value specified in the FileAlignment member.
CheckSum
Image file checksum.
Subsystem
Subsystem required to run this image. The following values are defined.
Value | Description
IMAGE_SUBSYSTEM_UNKNOWN | Unknown subsystem.
IMAGE_SUBSYSTEM_NATIVE | No subsystem required.
IMAGE_SUBSYSTEM_WINDOWS_CUI | Windows character-mode user interface (CUI) subsystem.
IMAGE_SUBSYSTEM_WINDOWS_GUI | Windows graphical user interface (GUI) subsystem..
IMAGE_SUBSYSTEM_OS2_CUI | OS/2 CUI subsystem.
IMAGE_SUBSYSTEM_POSIX_CUI | POSIX CUI subsystem.
IMAGE_SUBSYSTEM_WINDOWS_CE_GUI | Windows CE system.
IMAGE_SUBSYSTEM_XBOX | Xbox system.

DllCharacteristics
DLL characteristics of the image. The following values are defined.
Value | Meaning
0x0001 | Reserved
0x0002 | Reserved
0x0004 | Reserved
0x0008 | Reserved
0x2000 | A WDM driver.

SizeOfStackReserve
Number of bytes to reserve for the stack.
SizeOfStackCommit
Number of bytes to commit for the stack.
SizeOfHeapReserve
Number of bytes to reserve for the local heap.
SizeOfHeapCommit
Number of bytes to commit for the local heap.
LoaderFlags
This member is obsolete.
NumberOfRvaAndSizes
Number of directory entries.
DataDirectory
Pointer to the first IMAGE_DATA_DIRECTORY structure in the data directory.

Remarks

The number of directories is not fixed. Check the NumberOfRvaAndSizes member before looking for a specific directory.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, IMAGE_DATA_DIRECTORY


IMAGE_SECTION_HEADER

The IMAGE_SECTION_HEADER structure represents the image section header format.

typedef struct _IMAGE_SECTION_HEADER {
  BYTE    Name[IMAGE_SIZEOF_SHORT_NAME];
  union {
      DWORD   PhysicalAddress;
      DWORD   VirtualSize;
  } Misc;
  DWORD   VirtualAddress;
  DWORD   SizeOfRawData;
  DWORD   PointerToRawData;
  DWORD   PointerToRelocations;
  DWORD   PointerToLinenumbers;
  WORD    NumberOfRelocations;
  WORD    NumberOfLinenumbers;
  DWORD   Characteristics;
} IMAGE_SECTION_HEADER, *PIMAGE_SECTION_HEADER;

Members

Name
An 8-byte, null-filled string. There is no terminating null character if the string is exactly eight characters long. For longer names, this member contains a forward slash (/) followed by a decimal number that is an offset into the string table. Executable images do not use a string table and do not support section names longer than eight characters.
PhysicalAddress
File address.
VirtualSize
Total size of the section when loaded into memory, in bytes. If this value is greater than the SizeOfRawData member, the section is filled with zeroes.
VirtualAddress
Address of the first byte of the section when loaded into memory, relative to the image base.
SizeOfRawData
Size of the initialized data on disk, in bytes. This value must be a multiple of the FileAlignment member of the IMAGE_OPTIONAL_HEADER structure. If this value is less than the VirtualSize member, the remainder of the section is filled with zeroes. If the section contains only uninitialized data, the member is zero.
PointerToRawData
File pointer to the first page within the COFF file. This value must be a multiple of the FileAlignment member of the IMAGE_OPTIONAL_HEADER structure. If a section contains only uninitialized data, this member is zero.
PointerToRelocations
File pointer to the beginning of the relocation entries for the section. If there are no relocations, this value is zero.
PointerToLinenumbers
File pointer to the beginning of the line-number entries for the section. If there are no COFF line numbers, this value is zero.
NumberOfRelocations
Number of relocation entries for the section. This value is zero for executable images.
NumberOfLinenumbers
Number of line-number entries for the section.
Characteristics
Characteristics of the image. The following values are defined.
Flag | Description
IMAGE_SCN_TYPE_REG | Reserved.
IMAGE_SCN_TYPE_DSECT | Reserved.
IMAGE_SCN_TYPE_NOLOAD | Reserved.
IMAGE_SCN_TYPE_GROUP | Reserved.
IMAGE_SCN_TYPE_NO_PAD | Reserved.
IMAGE_SCN_TYPE_COPY | Reserved.
IMAGE_SCN_CNT_CODE | Section contains executable code.
IMAGE_SCN_CNT_INITIALIZED_DATA | Section contains initialized data.
IMAGE_SCN_CNT_UNINITIALIZED_DATA | Section contains uninitialized data.
IMAGE_SCN_LNK_OTHER | Reserved.
IMAGE_SCN_LNK_INFO | Reserved.
IMAGE_SCN_TYPE_OVER | Reserved.
IMAGE_SCN_LNK_COMDAT | Section contains COMDAT data.
IMAGE_SCN_MEM_FARDATA | Reserved.
IMAGE_SCN_MEM_PURGEABLE | Reserved.
IMAGE_SCN_MEM_16BIT | Reserved.
IMAGE_SCN_MEM_LOCKED | Reserved.
IMAGE_SCN_MEM_PRELOAD | Reserved.
IMAGE_SCN_ALIGN_1BYTES | Align data on a 1-byte boundary.
IMAGE_SCN_ALIGN_2BYTES | Align data on a 2-byte boundary.
IMAGE_SCN_ALIGN_4BYTES | Align data on a 4-byte boundary.
IMAGE_SCN_ALIGN_8BYTES | Align data on a 8-byte boundary.
IMAGE_SCN_ALIGN_16BYTES | Align data on a 16-byte boundary.
IMAGE_SCN_ALIGN_32BYTES | Align data on a 32-byte boundary.
IMAGE_SCN_ALIGN_64BYTES | Align data on a 64-byte boundary.
IMAGE_SCN_LNK_NRELOC_OVFL | Section contains extended relocations.
IMAGE_SCN_MEM_DISCARDABLE | Section can be discarded as needed.
IMAGE_SCN_MEM_NOT_CACHED | Section cannot be cached.
IMAGE_SCN_MEM_NOT_PAGED | Section cannot be paged.
IMAGE_SCN_MEM_SHARED | Section can be shared in memory.
IMAGE_SCN_MEM_EXECUTE | Section can be executed as code.
IMAGE_SCN_MEM_READ | Section can be read.
IMAGE_SCN_MEM_WRITE | Section can be written to.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winnt.h; include Windows.h.

See Also

Image Help Library Overview, ImageHlp Structures, ImageDirectoryEntryToDataEx, ImageRvaToSection, ImageRvaToVa, LOADED_IMAGE


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Requirements

Many topics that introduce the syntax of an API element contain information about the build and run-time requirements for using the element. The format is as follows:

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 and later.
Windows 95/98/Me: Included in Windows 98 and later.
Redistributable: Requires IE 4.01 or later on Windows 95.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.
Unicode: Implemented as Unicode and ANSI versions.

The first line indicates the versions of Windows NT on which an element is natively supported. (Note that Windows 2000 and Windows XP are based on the Windows NT code base.) If an element is not supported, the line reads "Windows NT/2000/XP: Unsupported."

The second line indicates whether an element is supported natively on Windows 95, Windows 98, or Windows Me. If an element is not supported, the line reads "Windows 95/98/Me: Unsupported."

The Redistributable line indicates additional requirements to support an element that is not supported natively in a particular version of Windows. For elements that are only supported natively, this line is omitted.

The Header line indicates the header file that defines an element. This value can be an .h file, .idl file, or .odl file. This line can indicate that your code should include a different header file (one that includes the header file in which the element is defined, plus other required headers or definitions). If the header file is supplied by the user, or no header file is required, this line is omitted. For more information, see Using the SDK Headers.

The Library line indicates the file used to resolve calls to a function or member. This value can be a .lib file, .dll file, or .tlb file. If the library is supplied by the user, or the element type does not require a library, this line is omitted.

The Unicode line indicates whether an element exists as both a Unicode (W) version and an ANSI (A) version. Otherwise, this line is omitted. For more information, see Conventions for Function Prototypes.