Função SymInitialize (dbghelp.h)

Artigo
03/11/2023

Inicializa o manipulador de símbolos para um processo.

Sintaxe

BOOL IMAGEAPI SymInitialize(
  [in]           HANDLE hProcess,
  [in, optional] PCSTR  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. O identificador usado deve ser exclusivo para evitar o compartilhamento de uma sessão com outro componente e o uso de GetCurrentProcess pode ter resultados inesperados quando vários componentes estão tentando usar dbghelp para inspecionar o processo atual. Usar GetCurrentProcess ao depurar outro processo também fará com que funções como SymLoadModuleEx tenham resultados inesperados.

Esse parâmetro não pode ser NULL.

[in, optional] UserSearchPath

O caminho ou a série de caminhos separados por 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

Observe que o caminho de pesquisa também pode ser definido usando a função SymSetSearchPath .

[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 retornado

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE. Para recuperar informações de erro estendidas, chame GetLastError.

Comentários

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 do 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 GetModuleFileNameEx e adicione o caminho retornado a UserSearchPath.

Um processo que chama SymInitialize não deve chamá-lo novamente, a menos que chame SymCleanup primeiro. Se a chamada para SymInitialize definir fInvadeProcess como TRUE e você simplesmente precisar recarregar a lista de módulos, use a função SymRefreshModuleList .

Todas as funções DbgHelp, como esta, são threaded único. 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.