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

Статья
08/23/2023

Загружает таблицу символов для указанного модуля.

Синтаксис

DWORD64 IMAGEAPI SymLoadModuleExW(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCWSTR        ImageName,
  [in] PCWSTR        ModuleName,
  [in] DWORD64       BaseOfDll,
  [in] DWORD         DllSize,
  [in] PMODLOAD_DATA Data,
  [in] DWORD         Flags
);

Параметры

[in] hProcess

Дескриптор процесса, который изначально был передан в функцию SymInitialize .

[in] hFile

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

[in] ImageName

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

[in] ModuleName

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

[in] BaseOfDll

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

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

[in] DllSize

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

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

[in] Data

Указатель на структуру MODLOAD_DATA , представляющую заголовки, отличные от стандартного заголовка PE. Этот параметр является необязательным и может иметь значение NULL.

[in] Flags

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

Значение	Значение
SLMFLAG_NO_SYMBOLS 0x4	Загружает модуль, но не символы для модуля.
SLMFLAG_VIRTUAL 0x1	Создает виртуальный модуль с именем ModuleName по адресу, указанному в BaseOfDll. Чтобы добавить символы в этот модуль, вызовите функцию SymAddSymbol .

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

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

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

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

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

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

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

Чтобы вызвать версию этой функции в Юникоде, определите DBGHELP_TRANSLATE_TCHAR.

Примеры

Пример см. в разделе Загрузка модуля символов.

Примечание

Заголовок dbghelp.h определяет SymLoadModuleEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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

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

Поделиться через