Функция SymLoadModule (dbghelp.h)

Статья
08/23/2023

Загружает таблицу символов.

Эта функция заменена функцией SymLoadModuleEx .

Синтаксис

DWORD IMAGEAPI SymLoadModule(
  [in]           HANDLE hProcess,
  [in, optional] HANDLE hFile,
  [in, optional] PCSTR  ImageName,
  [in, optional] PCSTR  ModuleName,
  [in]           DWORD  BaseOfDll,
  [in]           DWORD  SizeOfDll
);

Параметры

[in] hProcess

Дескриптор процесса. Этот дескриптор должен быть ранее передан в функцию SymInitialize .

[in, optional] hFile

Дескриптор файла для исполняемого образа. Этот аргумент используется главным образом отладчиками, где отладчик передает дескриптор файла, полученный из события отладки. Значение NULL указывает, что hFile не используется.

[in, optional] ImageName

Имя исполняемого образа. Это имя может содержать частичный путь, полный путь или вообще не содержать пути. Если файл не может быть найден по указанному имени, используется путь поиска символов.

[in, optional] ModuleName

Имя ярлыка для модуля. Если значение указателя равно NULL, библиотека создает имя, используя базовое имя файла символов.

[in] BaseOfDll

Адрес загрузки модуля. Если значение равно нулю, библиотека получает адрес загрузки из файла символов. Адрес загрузки, содержащийся в файле символов, не обязательно является фактическим адресом загрузки. Отладчики и другие приложения, имеющие фактический адрес нагрузки, должны использовать реальный адрес нагрузки при вызове этой функции.

Если образ является PDB-файлом, этот параметр не может быть равен нулю.

[in] SizeOfDll

Размер модуля в байтах. Если значение равно нулю, библиотека получает размер из файла символов. Размер, содержащийся в файле символов, не обязательно совпадает с фактическим размером. Отладчики и другие приложения с фактическим размером должны использовать реальный размер при вызове этой функции.

Если образ является PDB-файлом, этот параметр не может быть равен нулю.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет базовым адресом загруженного модуля.

Если функция выполняется неудачно, возвращается нулевое значение. Чтобы получить расширенные сведения об ошибке, вызовите Метод GetLastError.

Если модуль уже загружен, возвращаемое значение равно нулю, а GetLastError возвращает ERROR_SUCCESS.

Обработчик символов создает запись для модуля, и если параметр отложенной загрузки символов отключен, предпринимается попытка загрузить символы. Если включена отложенная загрузка символов, модуль помечается как отложенный и символы не загружаются, пока не будет сделана ссылка на символ в модуле.

Чтобы выгрузить таблицу символов, используйте функцию SymUnloadModule64 .

Все функции DbgHelp, такие как эта, являются однопоточными. Таким образом, вызовы из нескольких потоков к этой функции, скорее всего, приведут к непредвиденному поведению или повреждению памяти. Чтобы избежать этого, необходимо синхронизировать все параллельные вызовы из нескольких потоков в эту функцию.

Эта функция заменяет функцию SymLoadModule . Дополнительные сведения см. в разделе Обновленная поддержка платформы. SymLoadModule определяется следующим образом в DbgHelp.h.

#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define SymLoadModule SymLoadModule64
#else
DWORD
IMAGEAPI
SymLoadModule(
    __in HANDLE hProcess,
    __in_opt HANDLE hFile,
    __in_opt PCSTR ImageName,
    __in_opt PCSTR ModuleName,
    __in DWORD BaseOfDll,
    __in DWORD SizeOfDll
    );
#endif

Требования


Целевая платформа	Windows
Header	dbghelp.h
Библиотека	Dbghelp.lib
DLL	Dbghelp.dll
Распространяемые компоненты	DbgHelp.dll 5.1 или более поздней версии

См. также раздел

Функции DbgHelp

SymInitialize

SymUnloadModule64