SymInitialize

The SymInitialize function initializes the symbol handler for a process.

BOOL SymInitialize(
  IN HANDLE hProcess,     
  IN LPSTR UserSearchPath,  
  IN BOOL fInvadeProcess  
);
 

Parameters

hProcess

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.

UserSearchPath

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 ImageHlp attempts to form a symbol path from the following sources:

• Current directory
• Environment variable _NT_SYMBOL_PATH
• Environment variable _NT_ALTERNATE_SYMBOL_PATH
• Environment variable SYSTEMROOT

fInvadeProcess

If this value is TRUE, ImageHlp enumerates the loaded modules for the process and effectively calls the SymLoadModule 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 ImageHlp symbol handler functions. It is the process handle that ImageHlp uses to identify the caller and locate the correct symbol information. You must call the SymCleanup function to deallocate all resources associated with the process for which symbols are loaded.

QuickInfo

  Windows NT: Requires version 4.0 or later.
  Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in imagehlp.h.
  Import Library: Use imagehlp.lib.

See Also

PE Image Helper (ImageHlp) Overview, Symbol Handler, SymLoadModule