SymInitialize 함수(dbghelp.h)

아티클
08/23/2023

프로세스에 대한 기호 처리기를 초기화합니다.

구문

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

매개 변수

[in] hProcess

호출자를 식별하는 핸들입니다. 이 값은 고유하고 0이 아니어야 하지만 프로세스 핸들일 필요는 없습니다. 그러나 프로세스 핸들을 사용하는 경우 올바른 핸들을 사용해야 합니다. 애플리케이션이 디버거인 경우 디버그 중인 프로세스에 대한 프로세스 핸들을 사용합니다. GetCurrentProcess에서 반환된 핸들을 사용하지 마세요. 사용된 핸들은 다른 구성 요소와 세션을 공유하지 않도록 고유해야 하며, 여러 구성 요소가 dbghelp를 사용하여 현재 프로세스를 검사하려고 할 때 GetCurrentProcess 를 사용하면 예기치 않은 결과가 발생할 수 있습니다. 다른 프로세스를 디버깅할 때 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 정의합니다.