Vue d’ensemble de la commande GFlags

Pour obtenir des informations générales sur l’installation et la localisation de gflags.exe, consultez GFlags.

Vous pouvez utiliser les commandes GFlags et la boîte de dialogue Indicateurs globaux de manière interchangeable.

Utilisation des commandes GFlags

Pour utiliser GFlags, tapez les commandes suivantes à la ligne de commande.

Pour ouvrir la boîte de dialogue GFlags :

gflags

Pour définir ou effacer des indicateurs globaux dans le Registre :

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

Pour définir ou effacer des indicateurs globaux pour la session active :

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

Pour définir ou effacer des indicateurs globaux pour un fichier image :

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

Pour définir ou effacer la fonctionnalité Pool spécial (Windows Vista et versions ultérieures)

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

Pour activer ou désactiver la fonctionnalité de suivi des références d’objet (Windows Vista et versions ultérieures)

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

gflags {/ro | /ko} /d

Pour activer et configurer la vérification du tas de pages :

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] 

Pour désactiver la vérification du tas de pages :

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

Pour afficher l’aide :

gflags /?

Paramètres

Drapeau
Spécifie une abréviation à trois lettres (FlagAbbr) ou une valeur hexadécimale (FlagHex) qui représente une fonctionnalité de débogage. Les abréviations et les valeurs hexadécimales sont répertoriées dans la table d’indicateurs GFlags.

Utilisez l’un des formats d’indicateur suivants :

Format	Description
{+ | -}FlagAbbr	Définit (+) ou efface (-) l’indicateur représenté par l’abréviation de l’indicateur. Sans symbole plus (+) ou moins (-), la commande n’a aucun effet.
[+ | -]FlagHex	Ajoute (+) ou soustrait (-) la valeur hexadécimale d’un indicateur. Un indicateur est défini lorsque sa valeur est incluse dans la somme. Ajouter (+) est la valeur par défaut. Entrez une valeur hexadécimale (sans 0x) qui représente un indicateur unique ou entrez la somme des valeurs hexadécimales pour plusieurs indicateurs.

ImageFile
Spécifie le nom d’un fichier exécutable, y compris l’extension de nom de fichier (par exemple, notepad.exe ou mydll.dll).

/r
Registre. Affiche ou modifie les indicateurs de débogage à l’échelle du système stockés dans le Registre. Ces paramètres prennent effet lorsque vous redémarrez Windows et restez effectif jusqu’à ce que vous les modifiez.

Sans paramètres supplémentaires, gflags /r affiche les indicateurs à l’échelle du système définis dans le Registre.

/k
Paramètres de l’indicateur du noyau. Affiche ou modifie les indicateurs de débogage à l’échelle du système pour cette session. Ces paramètres sont effectifs immédiatement, mais sont perdus lorsque Windows s’arrête. Les paramètres affectent les processus démarrés une fois cette commande terminée.

Sans paramètres supplémentaires, gflags /k affiche les indicateurs à l’échelle du système définis pour la session active.

/Je
Paramètres du fichier image. Affiche ou modifie les indicateurs de débogage pour un processus particulier. Ces paramètres sont stockés dans le Registre. Elles sont efficaces pour toutes les nouvelles instances de ce processus et restent effectives jusqu’à ce que vous les modifiez.

Sans paramètres supplémentaires, gflags /i ImageFile affiche les indicateurs définis pour le processus spécifié.

/tracedb SizeInMB
Définit la taille maximale de la base de données de trace de pile en mode utilisateur pour le processus. Pour utiliser ce paramètre, l’indicateur Créer une base de données de trace de pile en mode utilisateur (ust) doit être défini pour le processus.

SizeInMB est un nombre entier représentant le nombre de mégaoctets en unités décimales. La valeur par défaut est la taille minimale, 8 Mo ; il n’y a pas de taille maximale. Pour revenir à la taille par défaut, définissez SizeInMB sur 0.

Spp
(Windows Vista et versions ultérieures.) Définit ou efface la fonctionnalité Pool spécial. Pour obtenir un exemple, consultez l’exemple 14 : Configuration d’un pool spécial.

PoolTag
(Windows Vista et versions ultérieures.) Spécifie une balise de pool pour la fonctionnalité Pool spécial. Utilisez uniquement l’indicateur spp .

Entrez un modèle à quatre caractères pour PoolTag, tel que Tag1. Il peut inclure les caractères génériques ? (remplacement d’un caractère unique) et * (remplacement de plusieurs caractères). Par exemple, Fat* ou Av ?4. Les balises de pool respectent toujours la casse.

Taille 0x
(Windows Vista et versions ultérieures.) Spécifie une plage de tailles pour la fonctionnalité Pool spécial. Utilisez uniquement l’indicateur spp . Pour obtenir des conseils sur la sélection d’une valeur de taille, consultez « Sélection d’une taille d’allocation » dans un pool spécial.

/Ro
Active, désactive et affiche les paramètres de suivi des références d’objet dans le Registre. Pour apporter une modification à ce paramètre, vous devez redémarrer Windows.

Sans paramètres supplémentaires, /ro affiche les paramètres de suivi de référence d’objet dans le Registre.

Pour activer le suivi de référence d’objet, vous devez inclure au moins une balise de pool (/t PoolTag) ou un fichier image (/i ImageFile) dans la commande. Pour plus d’informations, consultez l’exemple 15 : Utilisation du suivi de référence d’objet.

Le tableau suivant répertorie les sous-paramètres valides avec /ro.

/t PoolTags	Limite la trace aux objets avec les balises de pool spécifiées. Utilisez un point-virgule ( ;) pour séparer les noms d’étiquettes. Entrez jusqu’à 16 balises de pool. Entrez un modèle à quatre caractères pour PoolTags, tel que Tag1. Si vous spécifiez plusieurs balises de pool, Windows trace les objets avec l’une des balises de pool spécifiées. Si vous ne spécifiez aucune balise de pool, Windows trace tous les objets créés par l’image.
/i ImageFile	Limite la trace aux objets créés par les processus avec le fichier image spécifié. Vous ne pouvez spécifier qu’un seul fichier image avec le paramètre /i . Entrez un nom de fichier image, tel que notepad.exe, avec jusqu’à 64 caractères. « Système » et « Inactif » ne sont pas des noms d’images valides. Si vous ne spécifiez pas de fichier image, Windows trace tous les objets avec les balises de pool spécifiées. Si vous spécifiez à la fois un fichier image (/i) et une ou plusieurs balises de pool (/t), Windows trace les objets avec l’une des balises de pool spécifiées créées par l’image spécifiée.
/d	Efface les paramètres des fonctionnalités de suivi des références d’objet. Lorsqu’il est utilisé avec /ro, il efface les paramètres dans le Registre.
/p	Permanent. Les données de trace sont conservées jusqu’à ce que le suivi de référence d’objet soit désactivé, ou que l’ordinateur soit arrêté ou redémarré. Par défaut, les données de trace d’un objet sont ignorées lorsque l’objet est détruit.

/ko
Active, désactive et affiche les paramètres de suivi de référence d’objet de l’indicateur de noyau (heure d’exécution). Les modifications apportées à ce paramètre sont effectives immédiatement, mais sont perdues lorsque le système est arrêté ou redémarré. Pour plus d’informations, consultez l’exemple 15 : Utilisation du suivi de référence d’objet.

Sans paramètres supplémentaires, /ko affiche les paramètres de suivi de référence d’objet de l’indicateur de noyau (heure d’exécution).

Pour activer le suivi de référence d’objet, vous devez inclure au moins une balise de pool (/t PoolTag) ou un fichier image (/i ImageFile) dans la commande.

Le tableau suivant répertorie les sous-paramètres valides avec /ko.

/t PoolTags	Limite la trace aux objets avec les balises de pool spécifiées. Utilisez un point-virgule ( ;) pour séparer les noms d’étiquettes. Entrez jusqu’à 16 balises de pool. Entrez un modèle à quatre caractères pour PoolTags, tel que Tag1. Si vous spécifiez plusieurs balises de pool, Windows trace les objets avec l’une des balises de pool spécifiées. Si vous ne spécifiez aucune balise de pool, Windows trace tous les objets créés par l’image.
/i ImageFile	Limite la trace aux objets créés par les processus avec le fichier image spécifié. Vous ne pouvez spécifier qu’un seul fichier image avec le paramètre /i . Si vous ne spécifiez pas de fichier image, Windows trace tous les objets avec les balises de pool spécifiées. Si vous spécifiez à la fois un fichier image (/i) et une ou plusieurs balises de pool (/t), Windows trace les objets avec l’une des balises de pool spécifiées créées par l’image spécifiée.
/d	Efface les paramètres des fonctionnalités de suivi des références d’objet. Lorsqu’il est utilisé avec /ro, il efface les paramètres dans le Registre.
/p	Permanent. Les données de trace sont conservées jusqu’à ce que le suivi de référence d’objet soit désactivé, ou que l’ordinateur soit arrêté ou redémarré. Par défaut, les données de trace d’un objet sont ignorées lorsque l’objet est détruit.

/p
Définit les options de vérification du tas de pages pour un processus.

Sans paramètres supplémentaires, gflags /p affiche une liste de fichiers image pour lesquels la vérification du tas de pages est activée.

La vérification du tas de pages surveille les opérations dynamiques de mémoire du tas, notamment l’allocation d’opérations et les opérations gratuites, et provoque un arrêt du débogueur lorsqu’il détecte une erreur de tas.

/désactiver ImageFile
Désactive la vérification du tas de pages (standard ou complète) pour le fichier image spécifié.

Cette commande équivaut à désactiver l’indicateur Activer le tas de pages (hpa) pour un processus (gflags /i ImageFile -hpa). Vous pouvez utiliser les commandes de façon interchangeable.

/Activer ImageFile
Active la vérification du tas de pages pour le fichier image spécifié.

Par défaut, le paramètre /enable active la vérification du tas de pages standard pour le fichier image. Pour activer la vérification complète du tas de pages pour le fichier image, ajoutez le paramètre /full à la commande ou utilisez le paramètre /i avec l’indicateur +hpa.

/plein
Active la vérification complète du tas de pages pour le processus. La vérification du tas de pages complètes place une zone de mémoire virtuelle réservée à la fin de chaque allocation.

L’utilisation de ce paramètre équivaut à activer l’indicateur Activer le tas de pages (hpa) pour un processus (gflags /i ImageFile +hpa). Vous pouvez utiliser les commandes de façon interchangeable.

/en arrière
Place la zone de mémoire virtuelle réservée au début d’une allocation, plutôt qu’à la fin. Par conséquent, le débogueur intercepte les dépassements au début de la mémoire tampon, au lieu de ceux à la fin de la mémoire tampon. Valide uniquement avec le paramètre /full .

/aléatoire Probabilité
Choisit la vérification complète ou standard du tas de pages pour chaque allocation, en fonction de la probabilité spécifiée.

La probabilité est un entier décimal compris entre 0 et 100 représentant la probabilité de la vérification du tas de pages complètes. Une probabilité de 100 est identique à l’utilisation du paramètre /full . Une probabilité de 0 est identique à l’utilisation de la vérification du tas de pages standard.

/taille SizeStart SizeEnd
Active la vérification complète du tas de pages pour les allocations dans la plage de tailles spécifiée et active la vérification du tas de pages standard pour toutes les autres allocations par le processus.

SizeStart et SizeEnd sont des entiers décimaux. La valeur par défaut est la vérification standard du tas de pages pour toutes les allocations.

/adresse AddressStart AddressEnd
Active la vérification complète du tas de pages pour la mémoire allouée pendant qu’une adresse de retour dans la plage d’adresses spécifiée se trouve sur la pile des appels d’exécution. Il active la vérification standard du tas de pages pour toutes les autres allocations par le processus.

Pour utiliser cette fonctionnalité, spécifiez une plage qui inclut les adresses de toutes les fonctions qui appellent la fonction avec l’allocation suspecte. L’adresse de la fonction appelante se trouve sur la pile des appels lorsque l’allocation suspecte se produit.

AddressStart et AddressEnd spécifient la plage d’adresses recherchée dans les traces de pile d’allocation. Les adresses sont spécifiées au format hexadécimal, par exemple, 0xAABBCCDD.

Sur les systèmes Windows Server 2003 et versions antérieures, le paramètre /address est valide uniquement sur les ordinateurs x86. Sur Windows Vista, il est valide sur toutes les architectures prises en charge.

/dlls DLL[, DLL...]
Active la vérification complète du tas de pages pour les allocations demandées par les DLL spécifiées et la vérification du tas de pages standard pour toutes les autres allocations par le processus.

DLL est le nom d’un fichier binaire, y compris son extension de nom de fichier. Le fichier spécifié doit être une bibliothèque de fonctions que le processus charge pendant l’exécution.

/déboguer
Lance automatiquement le processus spécifié par le paramètre /enable sous un débogueur.

Par défaut, ce paramètre utilise le débogueur NTSD avec la ligne de commande ntsd -g -g -x et avec le tas de pages activé, mais vous pouvez utiliser la variable DebuggerCommand pour spécifier un autre débogueur et ligne de commande.

Pour plus d’informations sur NTSD, consultez Débogage à l’aide de CDB et NTSD.

Cette option est utile pour les programmes qui sont difficiles à démarrer à partir d’une invite de commandes et ceux qui sont démarrés par d’autres processus.

« DebuggerCommand »
Spécifie un débogueur et la commande envoyée au débogueur. Cette chaîne entre guillemets peut inclure un chemin complet vers le débogueur, le nom du débogueur et les paramètres de commande que le débogueur interprète. Les guillemets sont obligatoires.

Si la commande inclut un chemin d’accès au débogueur, le chemin d’accès ne peut pas contenir d’autres guillemets. Si d’autres guillemets apparaissent, l’interpréteur de commandes (cmd.exe) interprète mal la commande.

/kdebug
Lance automatiquement le processus spécifié par le paramètre /enable sous le débogueur NTSD avec la ligne de commande ntsd -g -G -x, avec le tas de pages activé et avec le contrôle de NTSD redirigé vers le débogueur du noyau.

Pour plus d’informations sur NTSD, consultez Débogage à l’aide de CDB et NTSD.

/non aligné
Aligne la fin de chaque allocation à une limite de fin de page, même si cela signifie que l’adresse de départ n’est pas alignée sur un bloc de 8 octets. Par défaut, le gestionnaire de tas garantit que l’adresse de départ d’une allocation est alignée sur un bloc de 8 octets.

Cette option est utilisée pour détecter les erreurs off-by-one-by-octet. Lorsque ce paramètre est utilisé avec le paramètre /full , la zone de mémoire virtuelle réservée commence juste après le dernier octet de l’allocation et une erreur immédiate se produit lorsqu’un processus tente de lire ou d’écrire un octet au-delà de l’allocation.

/decommit
Cette option n’est plus valide. Elle est acceptée, mais ignorée.

Le programme PageHeap (pageheap.exe) inclus dans Windows 2000 a implémenté la vérification du tas de pages complètes en plaçant une page inaccessible après une allocation. Dans cet outil, le paramètre /decommit a remplacé une zone de mémoire virtuelle réservée pour la page inaccessible. Dans cette version de GFlags, une zone de mémoire virtuelle réservée est toujours utilisée pour implémenter la vérification complète du tas de pages.

/notraces
Spécifie que les traces de pile au moment de l’exécution ne sont pas enregistrées.

Cette option améliore légèrement les performances, mais elle rend le débogage beaucoup plus difficile. Ce paramètre est valide, mais son utilisation n’est pas recommandée.

/faute
Force les allocations de mémoire du programme à échouer à la vitesse spécifiée et après le délai d’attente spécifié.

Ce paramètre insère des erreurs d’allocation de tas dans le fichier image testé (une pratique appelée « injection d’erreur ») afin que certaines allocations de mémoire échouent, comme cela peut se produire lorsque le programme s’exécute dans des conditions de mémoire faible. Ce test permet de détecter les erreurs de gestion des défaillances d’allocation, telles que l’échec de la mise en production des ressources.

Taux	Spécifie un entier décimal compris entre 1 (,01 %) et 1 000 (100 %) représentant la probabilité qu’une allocation échoue. La valeur par défaut est 100 (1 %).
TimeOut	Détermine l’intervalle de temps entre le début du programme et le début des routines d’injection d’erreur. TimeOut est mesuré en secondes. La valeur par défaut est 5 (secondes).

/Fuites
Vérifie les fuites de tas lorsqu’un processus se termine.

Le paramètre /leaks désactive le tas de pages complète. Lorsque /leaks est utilisé, le paramètre /full et les paramètres qui modifient le paramètre /full , tels que /backwards, sont ignorés, et GFlags effectue la vérification du tas de pages standard avec une vérification de fuite.

/protéger
Protège les structures internes du tas. Ce test est utilisé pour détecter les altérations aléatoires du tas. Il peut rendre l’exécution beaucoup plus lente.

/no_sync
Vérifie l’accès non synchronisé. Ce paramètre provoque un arrêt s’il détecte qu’un tas créé avec l’indicateur de HEAP_NO_SERIALIZE est accessible par différents threads.

N’utilisez pas cet indicateur pour déboguer un programme qui inclut un gestionnaire de tas personnalisé. Les fonctions qui synchronisent l’accès au tas entraînent le vérificateur de tas de pages à signaler les erreurs de synchronisation qui n’existent pas.

/no_lock_checks
Désactive le vérificateur de section critique.

/ ?
Affiche de l’aide pour GFlags. Avec /p, / ? affiche l’aide pour les options de vérification du tas de pages dans GFlags.

Commentaires

La saisie de gflags sans paramètres ouvre la boîte de dialogue Indicateurs globaux.

La saisie de gflags /p sans paramètres supplémentaires affiche une liste de programmes sur utilisant la vérification du tas de pages activée.

Pour effacer tous les indicateurs, définissez Indicateur sur -FFFFFFFF. (Paramètre L’indicateur à 0 ajoute zéro à la valeur d’indicateur actuelle. Il n’efface pas tous les indicateurs.)

Lorsque vous définissez Flag pour un fichier image sur FFFFFFFF, Windows efface tous les indicateurs et supprime l’entrée GlobalFlag dans la sous-clé de Registre pour le fichier image. La sous-clé reste.

Les paramètres /full, /random, /size, /address et /dlls pour le tas de pages /enable déterminent quelles allocations sont soumises à la vérification du tas de pages et à la méthode de vérification utilisée. Vous ne pouvez utiliser qu’un de ces paramètres dans chaque commande. La valeur par défaut est la vérification standard du tas de pages de toutes les allocations du processus. Les autres paramètres définissent les options de vérification du tas de pages.

Les fonctionnalités du tas de pages dans GFlags surveillent uniquement les allocations de mémoire de tas qui utilisent les fonctions standard du gestionnaire de tas Windows (HeapAlloc, GlobalAlloc, LocalAlloc, malloc, new, new[] ou leurs fonctions de désallocation correspondantes), ou celles qui utilisent des opérations personnalisées qui appellent les fonctions de gestionnaire de tas standard.

Pour déterminer si la vérification complète ou standard du tas de pages est activée pour un programme, à la ligne de commande, tapez gflags /p. Dans l’affichage obtenu, les traces indiquent que la vérification du tas de pages standard est activée pour le programme et que les traces complètes indiquent que la vérification complète du tas de pages est activée pour le programme.

Le paramètre /enable définit l’indicateur Activer le tas de pages (hpa) pour le fichier image dans le Registre. Toutefois, le paramètre /enable active la vérification standard du tas pour le fichier image par défaut, contrairement au paramètre /i avec l’indicateur +hpa, qui active la vérification complète du tas pour un fichier image.

La vérification du tas de pages standard place des modèles aléatoires à la fin d’une allocation et examine les modèles lorsqu’un bloc de tas est libéré. La vérification du tas de pages complètes place une zone de mémoire virtuelle réservée à la fin de chaque allocation.

La vérification complète du tas de pages peut consommer rapidement la mémoire système. Pour activer la vérification complète du tas de pages pour les processus nécessitant beaucoup de mémoire, utilisez le paramètre /size ou /dlls .

Après avoir utilisé des indicateurs globaux pour le débogage, envoyez une commande gflags /p /disable pour désactiver la vérification du tas de pages et supprimer les entrées de Registre associées. Sinon, les entrées que le débogueur lit restent dans le Registre. Vous ne pouvez pas utiliser la commande gflags /i hpa pour cette tâche, car elle désactive la vérification du tas de pages, mais ne supprime pas les entrées du Registre.

Par défaut, sur Windows Vista et les versions ultérieures de Windows, les paramètres spécifiques au programme (indicateurs de fichier image et paramètres de vérification du tas de pages) sont stockés dans le compte d’utilisateur actuel.

Cette version de GFlags inclut les options -v, qui permettent de développer des fonctionnalités pour GFlags. Toutefois, ces fonctionnalités ne sont pas encore complètes et, par conséquent, ne sont pas documentées.