Função SymInitializeW (dbghelp.h)
Inicializa o manipulador de símbolos para um processo.
Sintaxe
BOOL IMAGEAPI SymInitializeW(
[in] HANDLE hProcess,
[in, optional] PCWSTR UserSearchPath,
[in] BOOL fInvadeProcess
);
Parâmetros
[in] hProcess
Um identificador que identifica o chamador. Esse valor deve ser exclusivo e diferente de zero, mas não precisa ser um identificador de processo. No entanto, se você usar um identificador de processo, use o identificador correto. Se o aplicativo for um depurador, use o identificador de processo para o processo que está sendo depurado. Não use o identificador retornado por GetCurrentProcess ao depurar outro processo, pois funções de chamada como SymLoadModuleEx podem ter resultados inesperados.
Esse parâmetro não pode ser NULL.
[in, optional] UserSearchPath
O caminho ou série de caminhos separados por um ponto-e-vírgula (;), que é usado para pesquisar arquivos de símbolo. Se esse parâmetro for NULL, a biblioteca tentará formar um caminho de símbolo das seguintes fontes:
- O diretório de trabalho atual do aplicativo
- A variável de ambiente _NT_SYMBOL_PATH
- A variável de ambiente _NT_ALTERNATE_SYMBOL_PATH
[in] fInvadeProcess
Se esse valor for TRUE, enumera os módulos carregados para o processo e chama efetivamente a função SymLoadModule64 para cada módulo.
Valor de retorno
Se a função for bem-sucedida, o valor retornado será VERDADEIRO.
Se a função falhar, o valor retornado será false. Para recuperar informações de erro estendidas, chame GetLastError.
Observações
A função SymInitialize é usada para inicializar o manipulador de símbolos para um processo. No contexto do manipulador de símbolos, um processo é um objeto conveniente a ser usado ao coletar informações de símbolo. Normalmente, os manipuladores de símbolos são usados por depuradores e outras ferramentas que precisam carregar símbolos para um processo que está sendo depurado.
O identificador passado para SymInitialize deve ser o mesmo valor passado para todas as outras funções de manipulador de símbolos chamadas pelo processo. É o identificador que as funções usam para identificar o chamador e localizar as informações de símbolo corretas. Quando terminar de usar as informações de símbolo, chame a função SymCleanup para desalocar todos os recursos associados ao processo para o qual os símbolos são carregados.
A pesquisa de arquivos de símbolos é executada recursivamente para todos os caminhos especificados no parâmetro UserSearchPath. Portanto, se você especificar o diretório raiz em uma pesquisa, toda a unidade será pesquisada, o que pode levar um tempo significativo. Observe que o diretório que contém o arquivo executável para o processo não faz parte automaticamente do caminho de pesquisa. Para incluir esse diretório no caminho de pesquisa, chame a função
Um processo que chama SymInitialize não deve chamá-lo novamente, a menos que chame SymCleanup primeiro. Se a chamada para
Todas as funções DbgHelp, como esta, são threaded simples. Portanto, chamadas de mais de um thread para essa função provavelmente resultarão em comportamento inesperado ou corrupção de memória. Para evitar isso, chame SymInitialize somente quando o processo for iniciado e SymCleanup somente quando o processo terminar. Não é necessário que cada thread no processo chame essas funções.
Para chamar a versão Unicode dessa função, defina DBGHELP_TRANSLATE_TCHAR.
Exemplos
Para obter um exemplo, consulte Inicializando o manipulador de símbolos.
Nota
O cabeçalho dbghelp.h define SymInitialize como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
Requisito | Valor |
---|---|
da Plataforma de Destino |
Windows |
cabeçalho | dbghelp.h |
biblioteca | Dbghelp.lib |
de DLL |
Dbghelp.dll |
redistribuível | DbgHelp.dll 5.1 ou posterior |
Consulte também
SymCleanup