Guide `man` pages : comprendre l'utilisation de `man`.

Description

Les man pages sont des clés pour mieux comprendre l’utilisation du système d’exploitation, que ce soit sous Linux ou l’un des *BSD.

manpages est un raccourci anglophone pour : pages de manuels de référence !

Bien souvent, toute commande utilisable est accompagnée d’un man page. Tout ce dont nous avons besoin de comprendre à-propos d’une commande y est écrit.
C’est la première source et LA source d’autorité bien connue, normalement complète.

Certains man sont plus fiables, car ils sont le reflet d’un processus de qualité demandé dès la production d’un binaire, c’est le cas des manpages d’OpenBSD, où si le manpage est inexistant ou ne respecte pas des qualités de critères, le paquet dans son ensemble est rejeté.
La communauté Debian se donne du mal pour fournir des man de qualité, pour l’ensemble des logiciels intégrant le système de paquets. Attention : certaines communautés ne répondront à aucune demande d’aide, quelque soit le canal, ou renverront absolument aux man pages, s’il est clairement explicite que l’effort n’a pas été du tout fait pour s’informer correctement ; autrement dit, sans lecture de man page, point de salut !

Il faut voir l’ensemble des man pages comme une collection de documentation plus ou moins technique, voire spécialisé, comme une encyclopédie fournie gratuitement pour nous aider à mieux comprendre les arcanes intrinséques à l’informatique.

Alors si jamais quelqu’un sur un forum ou dans la vraie vie répond “Lis le man relatif”, ne le prend pas comme une insanité, ou un reproche ; cette personne cherche à te rendre un service utile, qui t’apprend à être opérationnel. Elle ne le fait pas forcèment de la meilleure manière… mais il y a de grande probabilités pour que les usages aient été abordés dans cette documentation.

Ce n’est pas forcèment plaisant à lire, mais ô combien pratique et utile.
L’interface paraît austère mais elle remplit son rôle : être une interface de consultation des manuels de références du système.
c’est d’ailleurs ce qu’affiche assurément le man ad hoc.

Les pages sont structurées pour donner l’information la plus fiable de manière la plus concise possible.
S’y habituer peut prendre un peu de temps, mais l’investissement vaut vraiment le coup !

Structure

Un manpage a généralement la structure suivante, différentes sections — comprendre que ce sont des chapitres :

• NAME : reprend le nom de la commmande ainsi qu’une description brève

• SYNOPSIS : montre les options, sans explication, de la commande

• DESCRIPTION : décrit l’utilité de la commande, ce qu’elle fait et comment l’utiliser, avec ces options. Elle développe le propos, en affichant ce qu’ il convient de faire, voire de ne pas faire. La description peut être très longue

En plus de ces trois sections, ou chapitres, il peut en comporter d’autres, tels :

• EXAMPLES : fournit des examples de comment utiliser la commande, du cas concret d’utilisation aux cas plus complexes.

• DIAGNOSTIC : liste les messages de status ou d’erreurs retournés par l’utilisation de la commande.

• FILES : liste les emplacements des fichiers supplémentaires relatifs ; fichiers de configuration, fichiers d’exemples, fichiers de données, etc…

• LIMITS : décrit les limites spécifiques de l’utilisation de la commande ; limites indépendantes du système d’exploitation et/ou du matériel, qui ne peuvent être appréhendées car ces dernières échappent au contrôle du binaire.

• PORTABILITY : liste les autres systèmes d’exploitation où la commande est disponible, ou comment les versions peuvent différer.

• SEE ALSO : renvoie vers d’autres man relevant d’informations pertinentes.

• HISTORY : donne un bref aperçu de l’historique d’apparition de la commande

• WARNING : informe d’annotations très importantes si nécessaire.

• NOTES : sont des informations importantes à connaître, sans la gravité de la section ci-dessus.

⇒ Un même man peut différer d’un système d’exploitation à l’autre ; exemple :

• man(1) fourni par Debian
• et celui fourni par OpenBSD : man(1)

⇒ Ou d’une version de système d’exploitation à une autre ; exemple :

• le man page actuel de pf.conf(5) d’OpenBSD
• et la version pf.conf(5) d’OpenBSD 5.0

Tous les man pages n’ont pas l’exacte même structure ; certaines sections sont utilisées, d’autres non, et certains man ont des sections très spécifiques.

Pour l’exemple, allez comparer le man man(1) et celui de pf.conf(5) pour OpenBSD, dont les URL sont données ci-dessus.
Celui de pf.conf(5) est extrêmement spécifique et fourmille de sections dédiées, inconnues dans d’autres man !

Sections

Ce qui est appelé Section est différent des sections/chapitres dans le man.

Les sections sont une collection référentielle d’un ensemble de man, dédié à une catégorie d’informations. Elles sont au nombre défini de neuf, pas une de plus, pas une de moins.

• 1 : aborde les programmes exécutables et les commandes de l’interpréteur shell

• 2 : nomme les appels systèmes, les codes d’erreurs des services fournis par le noyau

• 3 : informe des appels et des fonctions des bibliothèques — section spécifique au développement.

• 4 : explique les pilotes et les périphériques systèmes, les fichiers spéciaux /dev.

• 5 : précise les formats de fichiers standardisés.

• 6 : cible les jeux

• 7 : promeut diverses documentations et autres informations

• 8 : est la catégorie dédiée aux commandes de maintenance et administration système — section spécifique à l’administration système.

• 9 : comporte les informations relatives aux interfaces et autres spécifications plus ou moins obscures du noyau — section spécifique aux développeurs, hors celles standardisées.

Le regroupement des man pages dans ces catégories — ou groupement de pages — permet la recherche plus facile, autant pour l’humain que la machine.

Certaines commandes ne seront lisibles que dans une catégories, d’autres dans plusieurs.

Utilisation

L’appel à un man page se fait en mode terminal/console suivi d’un espace, suivi du nom de la commande à étudier, tel que l’exemple ci-dessus :

man man

⇒ Le premier man à consulter est : intro(1) dont le propos est d’introduire à la compréhension du système ; là, encore, cela dépendra du système d’exploitation ; sur Debian, il prend par la main pour aider à donner du sens, pour introduire à l’usage…

⇒ le second serait help(1), mais il n’existe pas partout.

⇒ hier(1) est un exemple célébre pour la description de la hierarchie du système de fichiers, et non pas relative au terme français.

Et, comme il en existe des milliers, il y a une grande probabilité pour que l’un référence le besoin de compréhension informatique recherché.

HTML

De nombreux man pages sont accessibles sur le protocole HTTP, au format HTML ; exemples parmi tant d’autres :

• Manpages ‘man.cx’ : https://man.cx/ — près de 230 000 man disponibles, en plusieurs langues, dont le français.
• l’historique man7.org : https://man7.org (minimaliste, quoique…)
• Debian : https://manpages.debian.org/ — certains sont lisibles en français.
• OpenBSD : https://man.openbsd.org/
• mdoc.su : http://mdoc.su/ qui référence les man des 4 “majeurs” *BSD

Recherche affinée CLI

⇒ L’option -f, est similaire à la commande whatis(1), et restitue le mot recherché dans les noms de man page et affiche la ligne d’information pour toutes correspondances trouvées. La recherche est insensible à la casse de police de caractères et ne sera faite que sur le mot recherché.

En gros, l’option affiche une courte description des man pages selon le mot recherché, s’il y en a de disponible.

Exemple :

$ man -f ftp
ftp(1) - Internet file transfer program
Net::FTP(3p) - FTP Client class
Net::FTP::dataconn(3p) - FTP Client data connection class
Regexp::Common::URI::ftp(3p) - Returns a pattern for FTP URIs.
ftp-proxy(8) - Internet File Transfer Protocol proxy daemon

Exemple fait sous OpenBSD, et selon les différents paquets installés ; exemple qui peut différer selon le système d’exploitation utilisé ET les paquets installés.

⇒ L’option -k permet de chercher tous les man pages, quelque soit la catégorie, comportant le sujet de recherche, qui est considéré comme un ‘drapeau’, ou un ’tag’.

L’utilisation de l’option est l’équivalent d’utiliser la commande apropos(1).

Essayons man -k man et nous aurons l’ensemble complet des manpages existant dans le système d’exploitation utilisé.

Reprenons l’exemple plus ciblé ; man -k ssh restitue :

$ man -k ssh
authorized_keys (5)  - Démon d’OpenSSH
debrsign (1)         - Signer des fichiers .changes et .dsc Debian à distance avec SSH
scp (1)              - Copie de fichier sécurisée à l’aide d’OpenSSH
sftp (1)             - Transfert de fichier sécurisé par OpenSSH
ssh (1)              - Client de connexion à distance d’OpenSSH
ssh-add (1)          - Ajouter des identités de clé privée dans l'agent d'authentification d’OpenSSH
ssh-agent (1)        - Agent d’authentification d’OpenSSH
ssh-argv0 (1)        - Remplacer un nom de commande ssh par un nom d’hôte
ssh-copy-id (1)      - Utiliser des clés valables localement pour autoriser les connexions à un hôte distant
ssh-keygen (1)       - Utilitaire d’OpenSSH pour la gestion des clés d’authentification
ssh-keyscan (1)      - Collecter des clés publiques SSH auprès des serveurs
ssh-keysign (8)      - Assistant d’OpenSSH pour l'authentification basée sur l'hôte
ssh-pkcs11-helper (8) - Assistant d’OpenSSH pour la prise en charge de PKCS#11
ssh-sk-helper (8)    - Assistant d’OpenSSH pour la prise en charge de l’authentificateur FIDO
ssh_config (5)       - Fichier de configuration du client OpenSSH
sshd (8)             - Démon d’OpenSSH
sshd_config (5)      - Fichier de configuration du démon d’OpenSSH
systemd-ssh-issue (1) - (sujet inconnu)
systemd-ssh-proxy (1) - (sujet inconnu)
sshfs (1)            - filesystem client based on SSH
EVP_KDF-SSHKDF (7ssl) - The SSHKDF EVP_KDF implementation
git-shell (1)        - Restricted login shell for Git-only SSH access
Net::DNS::RR::SSHFP (3pm) - DNS SSHFP resource record
rrsync (1)           - a script to setup restricted rsync users via ssh logins
systemd-ssh-generator (8) - Generator for binding a socket-activated SSH server to local AF_VSOCK and AF_UNIX sockets
virt-ssh-helper (8)  - libvirt socket proxy
yubikey-agent (1)    - a seamless ssh-agent for YubiKeys

Exemple fait sous Debian, et selon différents paquets installés ; exemple qui peut différer selon le système d’exploitation utilisé ET les paquets installés.

Explications :

• le chiffre entre parenthèses est celui relatif à la catégorie dans lequel le man page en question est écrit.
  • ssh(1) est accessible ainsi ; man ssh retournera le man ssh renfermé dans la Section 1 — section des commandes shell,
  • alors que ssh_config(5) est accessible à la fois par man ssh_config que par man 5 ssh_config, situé dans la Section 5 — Formats des fichiers,
  • mais essayons man 5 ssh : le système devrait informer qu’aucune page de manuel n’existe.

Voilà !

EOD

Bien sûr le man man comporte plein d’options utiles, spécifiques au système d’exploitation utilisé. Et, dès le départ, j’aurais simplement pu vous dire d’aller lire man man sans autre forme de procès. ;)

Maintenant, vous savez quoi faire…
prenez le réflexe de le faire AVANT de demander “au-secours” !

Et dites-le…
n’hésitez pas à dire que “vous ne comprenez pas telle chose dans tel man” ;) ou “bizarre, j’étais à la recherche de telle option, ou tel usage, mais je ne la trouve pas dans tel man”…

Enjoy-ID!
Enjoy-IT!