Linux / Commande whatis : trouver la description courte d’un manuel

whatis nom affiche la description courte des pages de manuel dont vous connaissez le nom. Dans man-db, essayez whatis ls ou man -f ls ; pour trouver des pages à partir d’une fonction comme « copier », utilisez plutôt une recherche par sujet avec apropos.

Lire une description sans la confondre avec un exécutable

Une page de manuel contient normalement une rubrique de nom, souvent intitulée NAME, associée à une brève description. man-db conserve des informations issues des pages dans un index. whatis recherche les noms dans cet index et affiche les résumés correspondants, sans ouvrir les pages complètes.

La syntaxe générale est la suivante ; les crochets et points de suspension décrivent la forme des arguments et ne sont pas à recopier :

whatis [options] nom ...

whatis ls
man -f ls

La seconde forme utilise la fonction de recherche équivalente de man dans un environnement man-db. Les résultats dépendent des manuels et index disponibles, de la langue et des chemins consultés. Leur présentation suit généralement ce modèle :

nom (section) - description courte

Le nombre entre parenthèses désigne une section de manuel, pas la version du programme. Après avoir identifié la bonne page, ouvrez-la pour lire les options et conditions d’utilisation :

man 1 ls

whatis ne vous indique pas si ls est un alias, une fonction ou un fichier dans le shell courant. La commande type et ses options de résolution permettent cette inspection. Un résultat documentaire ne garantit pas la présence d’un programme exécutable, et un programme peut exister sans page installée.

Comparer plusieurs noms et distinguer les sections

Pour parcourir rapidement les descriptions de plusieurs commandes, passez plusieurs noms :

whatis ls cp mv rm

Cette commande consulte la documentation : elle ne copie, ne déplace et ne supprime aucun fichier. Des réponses présentes dans la sortie ne suffisent pas à prouver qu’une description existe pour chacun des noms demandés. En automatisation, une interrogation séparée par nom rend les résultats plus faciles à attribuer.

Un nom peut aussi correspondre à plusieurs sujets. passwd peut notamment désigner une commande utilisateur et un format de fichier :

whatis passwd

Si des résultats existent dans les sections 1 et 5, consultez séparément :

man 1 passwd
man 5 passwd

La section 1 décrit généralement les commandes utilisateur, la 8 l’administration, la 5 les formats et conventions de fichiers, la 2 les appels système et la 3 les fonctions de bibliothèque. Le guide de lecture de man détaille ces catégories et le choix d’une page.

Vous pouvez limiter directement la recherche aux sections pertinentes :

whatis -s 1 passwd
whatis -s 5 passwd
whatis --sections=2,3 printf

Avec man-db, une section simple comme 3 inclut aussi ses extensions, telles que 3perl, si elles existent. Pour ne viser que cette partie, indiquez la section avec son extension. Les listes de sections acceptent des virgules ou des deux-points.

Élargir la recherche sur les noms avec un motif

Une expression régulière peut correspondre à une partie du nom

Par défaut, whatis est adapté à la recherche d’un nom précis. L’option -r change ce mode et interprète chaque argument comme une expression régulière :

whatis -r '^ssh'
whatis -r 'printf$'
whatis -r '^printf$'

^ssh sélectionne un début de nom, printf$ une fin de nom, et ^printf$ le nom entier. Le deuxième motif peut donc retenir un nom plus long se terminant par printf. La recherche porte sur les noms de pages, pas sur tous les mots de leurs descriptions.

Un joker doit correspondre au nom entier

whatis -w 'ssh*'
whatis --wildcard '*printf*'

-w utilise des motifs de style shell. Le premier vise les noms commençant par ssh ; le second accepte du texte avant et après printf. Le motif doit couvrir le nom entier, contrairement à une expression régulière non ancrée.

Les guillemets empêchent le shell de remplacer les jokers par des noms de fichiers du répertoire courant avant l’appel à whatis. Ces modes peuvent demander une recherche plus coûteuse que celle d’un nom précis. Le manuel de whatis fourni par man-db décrit leurs règles.

Choisir la longueur, la langue et les chemins consultés

Par exemple, pour garder toute une description et rechercher dans le contexte linguistique C :

whatis -l -L C ls

-L C ne traduit pas une description et n’installe pas de documentation anglaise manquante. La langue des messages d’aide ou d’erreur peut aussi rester celle déterminée au démarrage de l’outil : l’option agit lorsque la recherche des pages commence.

-M prend une liste de hiérarchies séparées par des deux-points et remplace la sélection issue de MANPATH pour cet appel. Utilisez des chemins qui existent réellement sur votre machine. Pour connaître l’implémentation et les options installées, consultez whatis --version et man whatis ; les détails de cet article concernent man-db.

Trouver pourquoi une description manque

Vérifier le nom, la page et le contexte de recherche

Si vous avez saisi une idée telle que archive au lieu d’un nom de page, élargissez la recherche aux résumés. Si vous connaissez le programme tar, distinguez sa résolution dans le shell et sa documentation :

apropos -L C archive
command -v tar
whatis tar
man 1 tar

Ces vérifications ne posent pas la même question. Le guide d’apropos explique la recherche par sujet. Une page peut aussi manquer sur une installation minimale : vérifiez les paquets de documentation proposés par votre distribution et l’existence de la page, sans supposer qu’un index neuf créera son contenu.

Une locale, un filtre de section ou un chemin personnalisé peut écarter la page attendue. Examinez le contexte avant de reconstruire quoi que ce soit :

locale
manpath
printf '%s\n' "$MANPATH"

Actualiser l’index lorsque c’est nécessaire

Si la page existe et s’ouvre avec man, mais que sa description n’apparaît pas, l’index peut être absent ou incomplet. Une actualisation administrative peut alors convenir :

sudo mandb

Lisez les diagnostics, puis répétez la recherche. mandb crée ou met à jour les caches de l’index ; il n’installe pas les pages absentes. Il peut signaler des pages dont le nom ou le résumé ne se laisse pas analyser correctement. Le manuel de mandb précise ces diagnostics.

Votre distribution peut déjà actualiser les index pendant l’installation des paquets ou par une tâche périodique. N’ajoutez pas une reconstruction systématique à chaque recherche. Sans droit d’administration, vérifiez d’abord les chemins et les documents accessibles à votre compte.

Contrôler chaque nom dans un script, avec des erreurs distinctes

Dans man-db, whatis distingue une recherche réussie avec le code 0, l’absence de correspondance avec 16, une erreur d’usage, de syntaxe ou de configuration avec 1, et une erreur de fonctionnement avec 2. Ne transformez pas toutes les erreurs en « aucun manuel ».

Le script complet suivant interroge chaque nom séparément et conserve les descriptions sur la sortie standard. Il s’arrête au premier échec, en gardant son code et ses diagnostics. Enregistrez-le dans un nouveau fichier controler-notices.sh :

#!/usr/bin/env bash
if [ "$#" -eq 0 ]; then
  printf 'Utilisation : bash controler-notices.sh nom [nom ...]\n' >&2
  exit 64
fi

for nom in "$@"; do
  if [ -z "$nom" ]; then
    printf '%s\n' 'Un nom vide n’est pas accepté.' >&2
    exit 64
  fi
done

for nom in "$@"; do
  if whatis -l -- "$nom"; then
    :
  else
    statut=$?
    case "$statut" in
      16)
        printf 'Aucune description trouvée pour : %s\n' "$nom" >&2
        ;;
      *)
        printf 'Erreur de recherche pour %s : code %d\n' "$nom" "$statut" >&2
        ;;
    esac
    exit "$statut"
  fi
done

Exécutez-le avec Bash :

bash controler-notices.sh ls cp mv
printf 'Code de retour : %s\n' "$?"

Si chaque recherche réussit, les descriptions sont affichées et le script termine avec 0. Une absence de correspondance produit 16 ; les noms suivants ne sont alors pas examinés. En cas d’erreur d’arguments du script, le code 64 est utilisé. Une autre erreur garde le code de l’outil, y compris si whatis lui-même est indisponible.

Une sortie partielle avant un échec ne constitue donc pas un contrôle réussi de toute la liste. Les guillemets autour des variables conservent chaque nom comme un seul argument, et -- évite de traiter un nom commençant par un tiret comme une option. Aucune phrase traduite n’est analysée pour prendre la décision.

Séparer description, recherche par sujet et résolution

Une description en une ligne sert à identifier le sujet avant la lecture détaillée. Elle ne remplace pas les options, préconditions et avertissements de la page complète, et ne prouve pas que l’exécutable sélectionné par votre shell corresponde à l’implémentation documentée.