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: 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:

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

fInvadeProcess

[in] If this value is TRUE, 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 symbol handler functions. It is the process handle that the functions use 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.

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.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in Dbghelp.h.
  Library: Use Dbghelp.lib.

See Also

Debug Help Library Overview, DbgHelp Functions, GetModuleFileNameEx, SymLoadModule