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

Статья
08/23/2023

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

Синтаксис

BOOL IMAGEAPI SymInitializeW(
  [in]           HANDLE hProcess,
  [in, optional] PCWSTR UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

Параметры

[in] hProcess

Дескриптор, идентифицирующий вызывающий объект. Это значение должно быть уникальным и ненулевым, но не должно быть дескриптором процесса. Однако если вы используете дескриптор процесса, обязательно используйте правильный дескриптор. Если приложение является отладчиком, используйте дескриптор процесса для отлаживаемого процесса. Не используйте дескриптор, возвращенный Методом 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.

Примеры

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

Примечание

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

Требования

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