The SymInitialize function initializes the symbol handler for a process.
BOOL SymInitialize(
| IN HANDLE hProcess, | |
| IN LPSTR UserSearchPath, | |
| IN BOOL fInvadeProcess | |
| ); |
Parameters
hProcess
Process handle for which symbols are to be maintained. If the application is a debugger, then the process handle for the object being debugged is used, otherwise GetCurrentProcess provides a valid process handle. The handle is not used as a real process handle, so any value will work as well as the next. The only limitation placed on the handle value is that it be unique for each time the application calls SymInitialize. Also, if the fInvadeProcess flag is TRUE, then the handle must be a valid process ID.
UserSearchPath
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, then IMAGEHLP enumerates the loaded modules for the process and effectively calls SymLoadModule for each module. In this case, the hProcess parameter must be a valid Win32 process handle.
Return Values
If the function succeeds, the return value is TRUE.
If the function fails, then 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. The companion function, SymCleanup, must be called to deallocate all resources associated with the process for which symbols are loaded.