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

Статья
03/11/2023

Инициализирует обработчик символов для процесса.

Синтаксис

BOOL IMAGEAPI SymInitialize(
  [in]           HANDLE hProcess,
  [in, optional] PCSTR  UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

Параметры

[in] hProcess

Дескриптор, идентифицирующий вызывающий объект. Это значение должно быть уникальным и ненулевым, но не должно быть дескриптором процесса. Однако если вы используете дескриптор процесса, обязательно используйте правильный дескриптор. Если приложение является отладчиком, используйте дескриптор процесса для отлаживаемого процесса. Не используйте дескриптор, возвращенный GetCurrentProcess. Используемый дескриптор должен быть уникальным, чтобы избежать совместного использования сеанса с другим компонентом, а использование GetCurrentProcess может привести к непредвиденным результатам, когда несколько компонентов пытаются использовать dbghelp для проверки текущего процесса. Использование GetCurrentProcess при отладке другого процесса также приведет к непредвиденным результатам таких функций, как SymLoadModuleEx .

Этот параметр не может иметь значение NULL.

[in, optional] UserSearchPath

Путь или ряд путей, разделенных точкой с запятой (;), которая используется для поиска файлов символов. Если этот параметр имеет значение NULL, библиотека пытается сформировать путь к символам из следующих источников:

Текущий рабочий каталог приложения
Переменная среды _NT_SYMBOL_PATH
Переменная среды _NT_ALTERNATE_SYMBOL_PATH

Обратите внимание, что путь поиска также можно задать с помощью функции SymSetSearchPath .

[in] fInvadeProcess

Если это значение равно TRUE, перечисляет загруженные модули для процесса и фактически вызывает функцию SymLoadModule64 для каждого модуля.

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

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

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

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

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

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

Процесс, вызывающий SymInitialize , не должен вызывать его снова, если он не вызывает SymCleanup первым. Если при вызове SymInitialize для параметра fInvadeProcess задано значение TRUE , и вам просто нужно перезагрузить список модулей, используйте функцию SymRefreshModuleList .

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

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

Примеры

Пример см. в разделе Инициализация обработчика символов.

Требования


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