Visão geral do comando GFlags

Para obter informações gerais sobre como instalar e localizar gflags.exe, consulte GFlags.

Você pode usar os comandos GFlags e a caixa de diálogo Sinalizadores globais de forma intercambiável.

Uso do comando GFlags

Para usar GFlags, digite os seguintes comandos na linha de comando.

Para abrir a caixa de diálogo GFlags:

gflags

Para definir ou limpar sinalizadores globais no registro:

gflags /r [{+ | -}Flag [{+ | -}Flag...]]

Para definir ou limpar sinalizadores globais para a sessão atual:

gflags /k [{+ | -}Flag [{+ | -}Flag...]]

Para definir ou limpar sinalizadores globais para um arquivo de imagem:

gflags /i ImageFile [{+ | -}Flag [{+ | -}Flag...]]
gflags /i ImageFile /tracedb SizeInMB

Para definir ou limpar o recurso Pool Especial (Windows Vista e posterior)

gflags {/r | /k} {+ | -}spp {PoolTag | 0xSize}

Para habilitar ou desabilitar o recurso Rastreamento de Referência de Objeto (Windows Vista e posterior)

gflags {/ro | /ko} [/p] [/i ImageFile | /t PoolTag;[PoolTag...]]

gflags {/ro | /ko} /d

Para habilitar e configurar a verificação de heap de página:

gflags /p /enable ImageFile  [ /full [/backwards] | /random Probability | /size SizeStart SizeEnd | /address AddressStart AddressEnd | /dlls DLL [DLL...] ] 
[/debug ["DebuggerCommand"] | /kdebug] [/unaligned] [/notraces] [/fault Rate [TimeOut]] [/leaks] [/protect] [/no_sync] [/no_lock_checks] 

Para desativar a verificação de heap de página:

gflags /p [/disable ImageFile] [/?]

Para exibir a ajuda:

gflags /?

Parâmetros

Bandeira
Especifica uma abreviação de três letras (FlagAbbr) ou um valor hexadecimal (FlagHex) que representa um recurso de depuração. As abreviações e valores hexadecimais estão listados na Tabela de Sinalizadores GFlags.

Use um dos seguintes formatos de sinalizador:

Formatar	Descrição
{+ | -}FlagAbbr	Define (+) ou desmarca (-) o sinalizador representado pela abreviação do sinalizador. Sem um símbolo de mais (+) ou menos (-), o comando não tem efeito.
[+ | -]FlagHex	Adiciona (+) ou subtrai (-) o valor hexadecimal de um sinalizador. Um sinalizador é definido quando seu valor é incluído na soma. Adicionar (+) é o padrão. Insira um valor hexadecimal (sem 0x) que represente um único sinalizador ou insira a soma dos valores hexadecimais para vários sinalizadores.

Arquivo de imagem
Especifica o nome de um arquivo executável, incluindo a extensão do nome do arquivo (por exemplo, notepad.exe ou mydll.dll).

/r
Registro. Exibe ou altera sinalizadores de depuração em todo o sistema armazenados no Registro. Essas configurações entram em vigor quando você reinicia o Windows e permanecem em vigor até que você as altere.

Sem parâmetros adicionais, gflags /r exibe os sinalizadores de todo o sistema definidos no registro.

/k
Configurações de sinalizador do kernel. Exibe ou altera sinalizadores de depuração em todo o sistema para esta sessão. Essas configurações entram em vigor imediatamente, mas são perdidas quando o Windows é desligado. As configurações afetam os processos iniciados após a conclusão desse comando.

Sem parâmetros adicionais, gflags /k exibe sinalizadores de todo o sistema definidos para a sessão atual.

/eu
Configurações do arquivo de imagem. Exibe ou altera sinalizadores de depuração para um processo específico. Essas configurações são armazenadas no Registro. Eles são eficazes para todas as novas instâncias desse processo e permanecem em vigor até que você os altere.

Sem parâmetros adicionais, gflags /i ImageFile exibe os sinalizadores definidos para o processo especificado.

/tracedb TamanhoEmMB
Define o tamanho máximo do banco de dados de rastreamento de pilha do modo de usuário para o processo. Para usar esse parâmetro, o sinalizador Criar banco de dados de rastreamento de pilha (ust) do modo de usuário deve ser definido para o processo.

SizeInMB é um número inteiro que representa o número de megabytes em unidades decimais. O valor padrão é o tamanho mínimo, 8 MB; Não há tamanho máximo. Para reverter para o tamanho padrão, defina SizeInMB como 0.

Spp
(Windows Vista e posterior.) Define ou limpa o recurso Pool Especial. Para obter um exemplo, consulte Exemplo 14: Configurando o pool especial.

Marca de Piscina
(Windows Vista e posterior.) Especifica uma marca de pool para o recurso Pool especial. Use apenas com o sinalizador spp .

Insira um padrão de quatro caracteres para PoolTag, como Tag1. Ele pode incluir os caracteres curinga ? (substituto para qualquer caractere único) e * (substituto para vários caracteres). Por exemplo, Fat* ou Av?4. As marcas de pool sempre diferenciam maiúsculas de minúsculas.

0xTamanho
(Windows Vista e posterior.) Especifica um intervalo de tamanho para o recurso Pool especial. Use apenas com o sinalizador spp . Para obter diretrizes sobre como selecionar um valor de tamanho, consulte "Selecionando um tamanho de alocação" em Pool especial.

/Ro
Habilita, desabilita e exibe as configurações de Rastreamento de Referência de Objeto no Registro. Para efetivar uma alteração nessa configuração, você deve reiniciar o Windows.

Sem parâmetros adicionais, /ro exibe as configurações de Rastreamento de Referência de Objeto no Registro.

Para habilitar o Rastreamento de Referência de Objeto, você deve incluir pelo menos uma marca de pool (/t PoolTag) ou um arquivo de imagem (/i ImageFile) no comando. Para obter detalhes, consulte Exemplo 15: Usando o rastreamento de referência de objeto.

A tabela a seguir lista os subparâmetros válidos com /ro.

/t Marcas de Piscina	Limita o rastreamento a objetos com as marcas de pool especificadas. Use um ponto-e-vírgula (;) para separar os nomes das marcas. Insira até 16 tags de pool. Insira um padrão de quatro caracteres para PoolTags, como Tag1. Se você especificar mais de uma marca de pool, o Windows rastreará objetos com qualquer uma das marcas de pool especificadas. Se você não especificar nenhuma marca de pool, o Windows rastreará todos os objetos criados pela imagem.
/i Arquivo de imagem	Limita o rastreio a objetos criados por processos com o arquivo de imagem especificado. Você pode especificar apenas um arquivo de imagem com o parâmetro /i . Insira um nome de arquivo de imagem, como notepad.exe, com até 64 caracteres. "Sistema" e "Ocioso" não são nomes de imagem válidos. Se você não especificar um arquivo de imagem, o Windows rastreará todos os objetos com as marcas de pool especificadas. Se você especificar um arquivo de imagem (/i) e uma ou mais marcas de pool (/t), o Windows rastreará objetos com qualquer uma das marcas de pool especificadas criadas pela imagem especificada.
/d	Desmarca as configurações do recurso Traçado de referência de objeto. Quando usado com /ro, ele limpa as configurações no registro.
/p	Permanente. Os dados de rastreamento são retidos até que o Rastreamento de Referência de Objeto seja desabilitado ou o computador seja desligado ou reiniciado. Por padrão, os dados de rastreamento de um objeto são descartados quando o objeto é destruído.

/Ko
Ativa, desativa e exibe as configurações de rastreamento de referência de objeto do sinalizador de kernel (tempo de execução). As alterações nessa configuração entram em vigor imediatamente, mas são perdidas quando o sistema é desligado ou reiniciado. Para obter detalhes, consulte Exemplo 15: Usando o rastreamento de referência de objeto.

Sem parâmetros adicionais, /ko exibe as configurações de Rastreamento de Referência de Objeto do sinalizador kernel (tempo de execução).

Para habilitar o Rastreamento de Referência de Objeto, você deve incluir pelo menos uma marca de pool (/t PoolTag) ou um arquivo de imagem (/i ImageFile) no comando.

A tabela a seguir lista os subparâmetros válidos com /ko.

/t Marcas de Piscina	Limita o rastreamento a objetos com as marcas de pool especificadas. Use um ponto-e-vírgula (;) para separar os nomes das marcas. Insira até 16 tags de pool. Insira um padrão de quatro caracteres para PoolTags, como Tag1. Se você especificar mais de uma marca de pool, o Windows rastreará objetos com qualquer uma das marcas de pool especificadas. Se você não especificar nenhuma marca de pool, o Windows rastreará todos os objetos criados pela imagem.
/i Arquivo de imagem	Limita o rastreio a objetos criados por processos com o arquivo de imagem especificado. Você pode especificar apenas um arquivo de imagem com o parâmetro /i . Se você não especificar um arquivo de imagem, o Windows rastreará todos os objetos com as marcas de pool especificadas. Se você especificar um arquivo de imagem (/i) e uma ou mais marcas de pool (/t), o Windows rastreará objetos com qualquer uma das marcas de pool especificadas criadas pela imagem especificada.
/d	Desmarca as configurações do recurso Traçado de referência de objeto. Quando usado com /ro, ele limpa as configurações no registro.
/p	Permanente. Os dados de rastreamento são retidos até que o Rastreamento de Referência de Objeto seja desabilitado ou o computador seja desligado ou reiniciado. Por padrão, os dados de rastreamento de um objeto são descartados quando o objeto é destruído.

/p
Define as opções de verificação de heap de página para um processo.

Sem parâmetros adicionais, gflags /p exibe uma lista de arquivos de imagem para os quais a verificação de heap de página está habilitada.

A verificação de heap de página monitora operações dinâmicas de memória de heap, incluindo operações de alocação e operações livres, e causa uma interrupção do depurador quando detecta um erro de heap.

/desabilitar Arquivo de imagem
Desativa a verificação de heap de página (padrão ou completa) para o arquivo de imagem especificado.

Esse comando é equivalente a desativar o sinalizador Habilitar heap de página (hpa) para um processo (gflags /i ImageFile -hpa). Você pode usar os comandos de forma intercambiável.

/habilitar Arquivo de imagem
Ativa a verificação de heap de página para o arquivo de imagem especificado.

Por padrão, o parâmetro /enable ativa a verificação de heap de página padrão para o arquivo de imagem. Para habilitar a verificação de heap de página inteira para o arquivo de imagem, adicione o parâmetro /full ao comando ou use o parâmetro /i com o sinalizador +hpa .

/cheio
Ativa a verificação de heap de página inteira para o processo. A verificação de heap de página inteira coloca uma zona de memória virtual reservada no final de cada alocação.

Usar esse parâmetro é equivalente a ativar o sinalizador Habilitar heap de página (hpa) para um processo (gflags /i ImageFile +hpa). Você pode usar os comandos de forma intercambiável.

/para trás
Coloca a zona de memória virtual reservada no início de uma alocação, em vez de no final. Como resultado, o depurador intercepta saturações no início do buffer, em vez daquelas no final do buffer. Válido apenas com o parâmetro /full .

/aleatório Probabilidade
Escolhe a verificação de heap de página completa ou padrão para cada alocação, com base na probabilidade especificada.

Probabilidade é um inteiro decimal de 0 a 100 que representa a probabilidade de verificação de heap de página inteira. Uma probabilidade de 100 é o mesmo que usar o parâmetro /full . Uma probabilidade de 0 é o mesmo que usar a verificação de heap de página padrão.

/tamanho TamanhoInício TamanhoFim
Habilita a verificação de heap de página inteira para alocações dentro do intervalo de tamanho especificado e habilita a verificação de heap de página padrão para todas as outras alocações pelo processo.

SizeStart e SizeEnd são inteiros decimais. O padrão é a verificação de heap de página padrão para todas as alocações.

/endereço EndereçoInício EndereçoFim
Habilita a verificação de heap de página inteira para memória alocada enquanto um endereço de retorno no intervalo de endereços especificado está na pilha de chamadas em tempo de execução. Ele permite a verificação de heap de página padrão para todas as outras alocações pelo processo.

Para usar esse recurso, especifique um intervalo que inclua os endereços de todas as funções que chamam a função com a alocação suspeita. O endereço da função de chamada estará na pilha de chamadas quando ocorrer a alocação suspeita.

AddressStart e AddressEnd especificam o intervalo de endereços pesquisado em rastreamentos de pilha de alocação. Os endereços são especificados em formato hexadecimal, como 0xAABBCCDD.

No Windows Server 2003 e em sistemas anteriores, o parâmetro /address é válido somente em computadores baseados em x86. No Windows Vista: é válido em todas as arquiteturas suportadas.

/dlls DLL[, DLL...]
Habilita a verificação de heap de página inteira para alocações solicitadas pelas DLLs especificadas e a verificação de heap de página padrão para todas as outras alocações pelo processo.

DLL é o nome de um arquivo binário, incluindo sua extensão de nome de arquivo. O arquivo especificado deve ser uma biblioteca de funções que o processo carrega durante a execução.

/depurar
Inicia automaticamente o processo especificado pelo parâmetro /enable em um depurador.

Por padrão, esse parâmetro usa o depurador NTSD com a linha de comando ntsd -g -G -x e com o heap de página habilitado, mas você pode usar a variável DebuggerCommand para especificar um depurador e uma linha de comando diferentes.

Para obter informações sobre NTSD, consulte Depuração usando CDB e NTSD.

Esta opção é útil para programas que são difíceis de iniciar a partir de um prompt de comando e aqueles que são iniciados por outros processos.

"Comando do Depurador"
Especifica um depurador e o comando enviado ao depurador. Essa cadeia de caracteres entre aspas pode incluir um caminho totalmente qualificado para o depurador, o nome do depurador e os parâmetros de comando que o depurador interpreta. As aspas são obrigatórias.

Se o comando incluir um caminho para o depurador, o caminho não poderá conter outras aspas. Se outras aspas aparecerem, o shell de comando (cmd.exe) interpretará incorretamente o comando.

/kdebug
Inicia automaticamente o processo especificado pelo parâmetro /enable no depurador NTSD com a linha de comando ntsd -g -G -x, com o heap de página habilitado e com o controle do NTSD redirecionado para o depurador de kernel.

Para obter informações sobre NTSD, consulte Depuração usando CDB e NTSD.

/Unaligned
Alinha o final de cada alocação em um limite de fim de página, mesmo que isso signifique que o endereço inicial não esteja alinhado em um bloco de 8 bytes. Por padrão, o gerenciador de heap garante que o endereço inicial de uma alocação esteja alinhado em um bloco de 8 bytes.

Essa opção é usada para detectar erros de um byte. Quando esse parâmetro é usado com o parâmetro /full , a zona de memória virtual reservada começa logo após o último byte da alocação e uma falha imediata ocorre quando um processo tenta ler ou gravar até mesmo um byte além da alocação.

/desconfirmar
Esta opção não é mais válida. É aceito, mas ignorado.

O programa PageHeap (pageheap.exe) incluído no Windows 2000 implementou a verificação de heap de página inteira colocando uma página inacessível após uma alocação. Nessa ferramenta, o parâmetro /decommit substituiu uma zona de memória virtual reservada pela página inacessível. Nesta versão do GFlags, uma zona de memória virtual reservada é sempre usada para implementar a verificação de heap de página inteira.

/não-corridas
Especifica que os rastreamentos de pilha em tempo de execução não são salvos.

Essa opção melhora um pouco o desempenho, mas torna a depuração muito mais difícil. Este parâmetro é válido, mas seu uso não é recomendado.

/falta
Força as alocações de memória do programa a falhar na taxa especificada e após o tempo limite especificado.

Esse parâmetro insere erros de alocação de heap no arquivo de imagem que está sendo testado (uma prática conhecida como "injeção de falha") para que algumas alocações de memória falhem, como pode ocorrer quando o programa é executado em condições de pouca memória. Esse teste ajuda a detectar erros no tratamento de falhas de alocação, como falha ao liberar recursos.

Taxa	Especifica um número inteiro decimal de 1 (0,01%) a 10000 (100%) representando a probabilidade de falha de uma alocação. O padrão é 100 (1%).
TimeOut	Determina o intervalo de tempo entre o início do programa e o início das rotinas de injeção de falhas. TimeOut é medido em segundos. O padrão é 5 (segundos).

/Vazamentos
Verifica se há vazamentos de heap quando um processo termina.

O parâmetro /leaks desabilita o heap de página inteira. Quando /leaks é usado, o parâmetro /full e os parâmetros que modificam o parâmetro /full, como /backwards, são ignorados e o GFlags executa a verificação de heap de página padrão com uma verificação de vazamento.

/proteger
Protege estruturas internas de heap. Esse teste é usado para detectar corrupções de heap aleatórias. Isso pode tornar a execução significativamente mais lenta.

/no_sync
Verifica se há acesso não sincronizado. Esse parâmetro causará uma interrupção se detectar que um heap criado com o sinalizador HEAP_NO_SERIALIZE é acessado por threads diferentes.

Não use esse sinalizador para depurar um programa que inclui um gerenciador de heap personalizado. As funções que sincronizam o acesso de heap fazem com que o verificador de heap de página relate falhas de sincronização que não existem.

/no_lock_checks
Desabilita o verificador de seção crítica.

/?
Exibe ajuda para GFlags. Com /p, /? exibe ajuda para as opções de verificação de heap de página em GFlags.

Comentários

Digitar gflags sem parâmetros abre a caixa de diálogo Sinalizadores Globais.

Digitar gflags /p sem parâmetros adicionais exibe uma lista de programas que têm a verificação de heap de página habilitada.

Para limpar todos os sinalizadores, defina Sinalizador como -FFFFFFFF. (Configuração Sinalizar como 0 adiciona zero ao valor do sinalizador atual. Não limpa todas as bandeiras.)

Quando você define Flag para um arquivo de imagem como FFFFFFFF, Windows limpa todos os sinalizadores e exclui a entrada GlobalFlag na subchave do Registro para o arquivo de imagem. A subchave permanece.

Os parâmetros /full, /random, /size, /address e /dlls para a operação /enable de heap de página determinam quais alocações estão sujeitas à verificação de heap de página e o método de verificação usado. Você pode usar apenas um desses parâmetros em cada comando. O padrão é a verificação de heap de página padrão de todas as alocações do processo. Os parâmetros restantes definem opções para verificação de heap de página.

Os recursos de heap de página no GFlags monitoram apenas as alocações de memória de heap que usam as funções padrão do gerenciador de heap do Windows (HeapAlloc, GlobalAlloc, LocalAlloc, malloc, new, new[] ou suas funções de desalocação correspondentes) ou aquelas que usam operações personalizadas que chamam as funções padrão do gerenciador de heap.

Para determinar se a verificação de heap de página completa ou padrão está habilitada para um programa, na linha de comando, digite gflags /p. Na exibição resultante, rastreamentos indica que a verificação de heap de página padrão está habilitada para o programa e rastreamentos completos indica que a verificação de heap de página inteira está habilitada para o programa.

O parâmetro /enable define o sinalizador Habilitar heap de página (hpa) para o arquivo de imagem no registro. No entanto, o parâmetro /enable ativa a verificação de heap padrão para o arquivo de imagem por padrão, ao contrário do parâmetro /i com o sinalizador +hpa , que ativa a verificação de heap completa para um arquivo de imagem.

A verificação de heap de página padrão coloca padrões aleatórios no final de uma alocação e examina os padrões quando um bloco de heap é liberado. A verificação de heap de página inteira coloca uma zona de memória virtual reservada no final de cada alocação.

A verificação de heap de página inteira pode consumir memória do sistema rapidamente. Para habilitar a verificação de heap de página inteira para processos com uso intensivo de memória, use o parâmetro /size ou /dlls .

Depois de usar sinalizadores globais para depuração, envie um comando gflags /p /disable para desativar a verificação de heap de página e excluir as entradas de registro associadas. Caso contrário, as entradas que o depurador lê permanecem no registro. Você não pode usar o comando gflags /i hpa para esta tarefa, pois ele desativa a verificação de heap de página, mas não exclui as entradas do Registro.

Por padrão, no Windows Vista e versões posteriores do Windows, as configurações específicas do programa (sinalizadores de arquivo de imagem e configurações de verificação de heap de página) são armazenadas na conta de usuário atual.

Esta versão do GFlags inclui as opções -v , que permitem o desenvolvimento de recursos para GFlags. No entanto, esses recursos ainda não estão completos e, portanto, não estão documentados.