Função SymLoadModuleEx (dbghelp.h)

Artigo
08/23/2023

Carrega a tabela de símbolos para o módulo especificado.

Sintaxe

DWORD64 IMAGEAPI SymLoadModuleEx(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCSTR         ImageName,
  [in] PCSTR         ModuleName,
  [in] DWORD64       BaseOfDll,
  [in] DWORD         DllSize,
  [in] PMODLOAD_DATA Data,
  [in] DWORD         Flags
);

Parâmetros

[in] hProcess

Um identificador para o processo que foi originalmente passado para a função SymInitialize .

[in] hFile

Um identificador para o arquivo para a imagem executável. Esse argumento é usado principalmente por depuradores, em que o depurador passa o identificador de arquivo obtido de um evento de depuração. Um valor nulo indica que hFile não é usado.

[in] ImageName

O nome da imagem executável. Esse nome pode conter um caminho parcial, um caminho completo ou nenhum caminho. Se o arquivo não puder ser localizado pelo nome fornecido, o caminho de pesquisa de símbolos será usado.

[in] ModuleName

Um nome de atalho para o módulo. Se o valor do ponteiro for NULL, a biblioteca criará um nome usando o nome base do arquivo de símbolo.

[in] BaseOfDll

O endereço de carregamento do módulo. Se o valor for zero, a biblioteca obterá o endereço de carga do arquivo de símbolo. O endereço de carga contido no arquivo de símbolo não é necessariamente o endereço de carga real. Depuradores e outros aplicativos com um endereço de carga real devem usar o endereço de carga real ao chamar essa função.

Se a imagem for um arquivo .pdb, esse parâmetro não poderá ser zero.

[in] DllSize

O tamanho do módulo, em bytes. Se o valor for zero, a biblioteca obterá o tamanho do arquivo de símbolo. O tamanho contido no arquivo de símbolo não é necessariamente o tamanho real. Depuradores e outros aplicativos com um tamanho real devem usar o tamanho real ao chamar essa função.

Se a imagem for um arquivo .pdb, esse parâmetro não poderá ser zero.

[in] Data

Um ponteiro para uma estrutura MODLOAD_DATA que representa cabeçalhos diferentes do cabeçalho PE padrão. Esse parâmetro é opcional e pode ser NULL.

[in] Flags

Esse parâmetro pode ser zero ou um ou mais dos valores a seguir. Se esse parâmetro for zero, a função carregará os módulos e os símbolos do módulo.

Valor	Significado
SLMFLAG_NO_SYMBOLS 0x4	Carrega o módulo, mas não os símbolos do módulo.
SLMFLAG_VIRTUAL 0x1	Cria um módulo virtual chamado ModuleName no endereço especificado em BaseOfDll. Para adicionar símbolos a este módulo, chame a função SymAddSymbol .

Retornar valor

Se a função for bem-sucedida, o valor retornado será o endereço base do módulo carregado.

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

Se o módulo já estiver carregado, o valor retornado será zero e GetLastError retornará ERROR_SUCCESS.

Comentários

O manipulador de símbolos cria uma entrada para o módulo e, se a opção de carregamento de símbolo adiado estiver desativada, será feita uma tentativa de carregar os símbolos. Se o carregamento de símbolo adiado estiver habilitado, o módulo será marcado como adiado e os símbolos não serão carregados até que uma referência seja feita a um símbolo no módulo. Portanto, você sempre deve chamar a função SymGetModuleInfo64 depois de chamar SymLoadModuleEx.

Para descarregar a tabela de símbolos, use a função SymUnloadModule64 .

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, você deve sincronizar todas as chamadas simultâneas de mais de um thread para essa função.

Para chamar a versão Unicode dessa função, defina DBGHELP_TRANSLATE_TCHAR.