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

Статья
08/23/2023

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

Синтаксис

DWORD64 IMAGEAPI SymLoadModuleEx(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCSTR         ImageName,
  [in] PCSTR         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.

Примеры

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

Требования

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