Функция SymInitialize (dbghelp.h)
Инициализирует обработчик символов для процесса.
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
[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 или более поздней версии |