Функция 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.

Примеры

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

Требования

Требование	Ценность
целевая платформа	Виндоус
заголовка	dbghelp.h
библиотеки	Dbghelp.lib
DLL	Dbghelp.dll
распространяемый	DbgHelp.dll 6.0 или более поздней версии

См. также

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