Função RtlCaptureStackBackTrace (ntifs.h)

Artigo
02/07/2025

A rotina rtlCaptureStackBackTrace captura um rastreamento de pilha percorrendo a pilha e gravando as informações para cada quadro.

Sintaxe

NTSYSAPI USHORT RtlCaptureStackBackTrace(
  [in]            ULONG  FramesToSkip,
  [in]            ULONG  FramesToCapture,
  [out]           PVOID  *BackTrace,
  [out, optional] PULONG BackTraceHash
);

Parâmetros

[in] FramesToSkip

Número de quadros a serem ignoradas do início (ponto de chamada atual) do rastreamento de fundo.

[in] FramesToCapture

Número de quadros a serem capturados.

[out] BackTrace

Matriz alocada pelo chamador na qual os ponteiros para os endereços de retorno capturados do rastreamento de pilha atual são retornados.

[out, optional] BackTraceHash

Valor opcional que pode ser usado para organizar tabelas de hash. Se esse parâmetro for NULL, RtlCaptureStackBackTrace não calculará e retornará um valor de hash.

Esse valor de hash é calculado com base nos valores dos ponteiros retornados na matriz BackTrace. Dois rastreamentos de pilha idênticos gerarão valores de hash idênticos.

Valor de retorno

O número de quadros capturados.

Observações

RtlCaptureStackBackTrace captura um rastreamento de pilha para o chamador andando pela pilha (voltando no tempo de chamada) e gravando informações para cada quadro. Especificamente, RtlCaptureStackBackTrace retorna ponteiros para os endereços retornados de cada chamada na pilha, em que o primeiro ponteiro no BackTrace matriz aponta para o endereço de retorno da chamada mais recente e assim por diante.

Os valores de hash de rastreamento de volta podem ser usados para determinar rapidamente se dois rastreamentos de pilha são idênticos ou diferentes. Você pode usar o hash retornado em BackTraceHash para comparar rastreamentos de pilha. Se você não quiser usar hashes ou quiser calcular seus próprios valores de hash, defina BackTraceHash como NULL.

Normalmente, em computadores de 64 bits, você não pode capturar a pilha de kernel em determinados contextos quando falhas de página não são permitidas. Para habilitar o andamento da pilha de kernel em x64, defina o valor do registro de gerenciamento de memória DisablePagingExecutive disablePagingExecutive como 1. O valor do Registro DisablePagingExecutive está localizado na seguinte chave do Registro: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management. Isso só deve ser feito para fins de diagnóstico temporário porque aumenta o uso de memória do sistema.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP
da Plataforma de Destino	Universal
cabeçalho	ntifs.h (inclua Ntifs.h, FltKernel.h)
biblioteca	NtosKrnl.lib; OneCoreUAP.lib no Windows 10
de DLL	NtDll.dll (modo de usuário); NtosKrnl.exe (modo kernel)

Compartilhar via