Platform SDK: Debugging and Error Handling

SymLoadModule

The SymLoadModule function loads the symbol table.

This function is implemented as a wrapper that calls SymLoadModule64. For more information, see New 64-bit Functions.

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

For SymLoadModule64, the parameter list is as follows.

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

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] Specifies the 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] Specifies the size of the module. 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 SymUnloadModule function.

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, SymInitialize, SymUnloadModule