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

Статья
11/20/2024

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

Синтаксис

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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

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