$ ls
2Hypergraphes Impression Microsoft Sarah games
Admin LaTeX Mygale Transfert local
Archives Logo NT Web nsmail
Arkeia Mac Netscape archive test
ConfigNT Mail Oueb bin tmp
$
... et nous avons donc bien obtenu le contenu du répertoire courant. En conclu-sion,apropospeut être considéré comme un « moteur de recherche » sur le rôle des commandes disponibles.
7.1.2 Mais c’est quoi donc ?
Il arrive parfois d’oublier ce que peut faire une commande. Supposons que l’on vous ait parlé de la commandefinden vous disant qu’elle était fabuleuse. La com-mandewhatisdevrait vous éclairer.
$ whatis find
find (1) - search for files in a directory hierarchy
$
Notez quewhatisne sait pas nécessairement de quoi vous lui causez :
$ whatis trouver
trouver: nothing appropriate
$
whatispermet donc d’obtenir une information succincte sur le rôle d’une commande shell.
7.2 Les pages de manuel
Le paragraphe précédent nous a permis de constater que findpermettait de rechercher des fichiers dans une arborescence. Supposons que vous vouliez recher-cher un fichier dénommétotoperdu quelque part sur votre home. Unfind toto lancé en ligne de commande produit un navrant find: toto: No such file or directory. Vous vous douterez alors quefindattend peut-être autre chose pour lui permettre de trouver ce fameuxtoto. Une commande va nous aider grandement : man. Osons unman find. Devant vos yeux ébahis devrait apparaître une page de manuel (raccourci en anglais enmanpage) concernantfind.
7.2.1 Une page de manuel
Les pages de manuel ont cette propriété d’avoir une structure assez fixe. Dé-taillons quelques-unes de ses principales entrées :
Name qui définit en une ligne ce que fait la commande. C’est d’ailleurs cette ligne qui est affichée parwhatis. Il s’agit de la seule partie requise pour faire d’une page de documentation quelconque unemanpage;
Synopsis qui précise la forme d’appel de la commande. Le synopsis précise de plus toutes les options qu’il est possible de passer à la commande et ses arguments éventuels ;
7
$ ls
2Hypergraphes Impression Microsoft Sarah games
Admin LaTeX Mygale Transfert local
Archives Logo NT Web nsmail
Arkeia Mac Netscape archive test
ConfigNT Mail Oueb bin tmp
$
... et nous avons donc bien obtenu le contenu du répertoire courant. En conclu-sion,apropospeut être considéré comme un « moteur de recherche » sur le rôle des commandes disponibles.
7.1.2 Mais c’est quoi donc ?
Il arrive parfois d’oublier ce que peut faire une commande. Supposons que l’on vous ait parlé de la commandefinden vous disant qu’elle était fabuleuse. La com-mandewhatisdevrait vous éclairer.
$ whatis find
find (1) - search for files in a directory hierarchy
$
Notez quewhatisne sait pas nécessairement de quoi vous lui causez :
$ whatis trouver
trouver: nothing appropriate
$
whatispermet donc d’obtenir une information succincte sur le rôle d’une commande shell.
7.2 Les pages de manuel
Le paragraphe précédent nous a permis de constater que findpermettait de rechercher des fichiers dans une arborescence. Supposons que vous vouliez recher-cher un fichier dénommétotoperdu quelque part sur votrehome. Unfind toto lancé en ligne de commande produit un navrantfind: toto: No such file or directory. Vous vous douterez alors quefindattend peut-être autre chose pour lui permettre de trouver ce fameuxtoto. Une commande va nous aider grandement : man. Osons unman find. Devant vos yeux ébahis devrait apparaître une page de manuel (raccourci en anglais enmanpage) concernantfind.
7.2.1 Une page de manuel
Les pages de manuel ont cette propriété d’avoir une structure assez fixe. Dé-taillons quelques-unes de ses principales entrées :
Name qui définit en une ligne ce que fait la commande. C’est d’ailleurs cette ligne qui est affichée parwhatis. Il s’agit de la seule partie requise pour faire d’une page de documentation quelconque unemanpage;
Synopsis qui précise la forme d’appel de la commande. Le synopsis précise de plus toutes les options qu’il est possible de passer à la commande et ses arguments éventuels ;
7
Description qui décrit effectivement l’action de la commande, précise le rôle de chaque argument ;
Options précise le rôle de chaque option (vous vous en doutiez, non ?);
See Also vous donne quelques commandes qui ont une action similaire à la com-mande dont vous avez la page de manuel sous les yeux et parfois les comcom-mandes utilisées par la commande.
Parfois on trouve également en fin de page, des exemples et les bugs connus du programme documenté.
7.2.2 Hiérarchie des pages de manuel
Vous aurez constaté que la page de manuel defindcommence en fait non pas par NAME, mais en fait par un nébuleux FIND(1). Les pages de manuel sont souvent hiérarchisées en douze sections numérotées de 1 à 9,n,oetl. Décrivons succincte-ment cette hiérarchie.
1 commandes de l’utilisateur pouvant être lancées par n’importe qui ; 2 appels système (fonctions fournies par le noyau) ;
3 fonctions propres à certaines bibliothèques (C, X windows, etc.) ; 4 ports et périphériques (c’est-à-dire les fichiers de /dev) ; 5 descriptions de formats de fichier de configuration ; 6 jeux ;
7 divers (essentiellement des conventions) ; 8 outils d’administration système ; 9 routines des noyaux (propre àLINUX).
Les sections suivantes ont vraisemblablement été abondonnées mais peuvent être toutefois présentes sur de « vieux » systèmes :
n ce qu’il y a de nouveau. Les documentations résidant dans cette partie se doivent d’être déplacées au bout d’un certain temps dans la section appropriée ; o vieilles documentations condamnées à la disparition ;
l documentation locale propre à un système, un site.
Notons qu’il n’est pas conseillé d’utiliser les trois dernières sections et que ces der-nières ont de plus en plus tendance à disparaître (sur le système où ces lignes sont écrites, seule subsiste la sectionn4).
Il peut arriver qu’un mot donné corresponde à des pages de manuel de différentes sections. Par exemple, vous cherchez une information sur la fonction Cprintf:
$ apropos printf
format (n) - Format a string in the style of sprintf gl_printf (3) - write formatted output in graphic mode printf (1) - format and print data
sprintf, printf,(3) - formatted output conversion printftest (6) - tests the vgagl gl_printf function snprintf, vsnprintf (3) - formatted output conversion
$
4. Et elle ne contient que 210 pages de documentation alors que la section 1 en contient environ 1300.
7
Description qui décrit effectivement l’action de la commande, précise le rôle de chaque argument ;
Options précise le rôle de chaque option (vous vous en doutiez, non ?);
See Also vous donne quelques commandes qui ont une action similaire à la com-mande dont vous avez la page de manuel sous les yeux et parfois les comcom-mandes utilisées par la commande.
Parfois on trouve également en fin de page, des exemples et les bugs connus du programme documenté.
7.2.2 Hiérarchie des pages de manuel
Vous aurez constaté que la page de manuel defindcommence en fait non pas par NAME, mais en fait par un nébuleux FIND(1). Les pages de manuel sont souvent hiérarchisées en douze sections numérotées de 1 à 9,n,oetl. Décrivons succincte-ment cette hiérarchie.
1 commandes de l’utilisateur pouvant être lancées par n’importe qui ; 2 appels système (fonctions fournies par le noyau) ;
3 fonctions propres à certaines bibliothèques (C, X windows, etc.) ; 4 ports et périphériques (c’est-à-dire les fichiers de /dev) ; 5 descriptions de formats de fichier de configuration ; 6 jeux ;
7 divers (essentiellement des conventions) ; 8 outils d’administration système ; 9 routines des noyaux (propre àLINUX).
Les sections suivantes ont vraisemblablement été abondonnées mais peuvent être toutefois présentes sur de « vieux » systèmes :
n ce qu’il y a de nouveau. Les documentations résidant dans cette partie se doivent d’être déplacées au bout d’un certain temps dans la section appropriée ; o vieilles documentations condamnées à la disparition ;
l documentation locale propre à un système, un site.
Notons qu’il n’est pas conseillé d’utiliser les trois dernières sections et que ces der-nières ont de plus en plus tendance à disparaître (sur le système où ces lignes sont écrites, seule subsiste la sectionn4).
Il peut arriver qu’un mot donné corresponde à des pages de manuel de différentes sections. Par exemple, vous cherchez une information sur la fonction Cprintf:
$ apropos printf
format (n) - Format a string in the style of sprintf gl_printf (3) - write formatted output in graphic mode printf (1) - format and print data
sprintf, printf,(3) - formatted output conversion printftest (6) - tests the vgagl gl_printf function snprintf, vsnprintf (3) - formatted output conversion
$
4. Et elle ne contient que 210 pages de documentation alors que la section 1 en contient environ 1300.
7
Si vous vous contentez d’un man printf, à votre grand désarroi, vous ne pourrez visualiser que la page de documentation correspondant à la section 1. Comment spécifier àmand’aller regarder dans la section 3 ? Facile : essayez unman 3 printf et réjouissez-vous :
$ man 3 printf
PRINTF(3) Linux Programmer’s Manual PRINTF(3) NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion SYNOPSIS
#include <stdio.h>
...
$
Bien entendu, il est nécessaire d’interroger une section dans laquelle existe la page de documentation. Il y a fort à parier qu’unman 2 printfvous rétorque narquoisement qu’il n’y a pas d’entrée pourprintfdans la section 2 du manuel.
7.2.3 La variable d’environnement MANPATH
Le plus rageant avec l’utilisation demanest d’obtenir un insoutenableNo manual entry for (le nom de la commande). Par exemple, unman xvproduitNo manual entry for xv. La première idée qui peut vous venir à l’esprit est qu’il n’existe pas de documentation pour cet outil qu’estxv. C’est possible mais regardons de plus près une certaine variable d’environnement dénomméeMANPATH.
$ echo $MANPATH
/usr/share/man:/usr/local/man
$
Cette variable a le même format que ◮PATHNet indique à la commande man les § 6.1.4 p. 147◭ endroits où rechercher les pages de manuel. Dans l’exemple précédent,manira donc
dans/usr/share/manpuis (en cas d’échec) dans/usr/local/manpour tenter de trouver l’information qui vous intéresse. Aucune page n’étant associée à xv, man vous le signifie poliment. Il suffit de rajouter un nouveau répertoire de recherche (/usr/X11R6/mansous Linux) à la variableMANPATHpour voir apparaître la page de documentation.
$ export MANPATH=$MANPATH:/usr/X11R6/man
$ man xv
XV(1) XV(1)
NAME
xv - interactive image display for the X Window System ... etc ...
$
Cette variable devrait êtrea priori« correctement » configurée pour aller visiter les points de chute classiques des pages de manuel, c’est-à-dire (cette liste ne se veut en aucun cas exhaustive)/usr/share/man,/usr/local/manet/usr/X11R6/man.
Dans le cas où vous souhaiteriez installer certaines pages de manuel à certains endroits précis de votre compte utilisateur, vous pouvez utiliser la même démarche
et ajouter dans vos◮fichiersNde démarrage : § 6.1.6 p. 148◭
7
Si vous vous contentez d’unman printf, à votre grand désarroi, vous ne pourrez visualiser que la page de documentation correspondant à la section 1. Comment spécifier àmand’aller regarder dans la section 3 ? Facile : essayez unman 3 printf et réjouissez-vous :
$ man 3 printf
PRINTF(3) Linux Programmer’s Manual PRINTF(3) NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion SYNOPSIS
#include <stdio.h>
...
$
Bien entendu, il est nécessaire d’interroger une section dans laquelle existe la page de documentation. Il y a fort à parier qu’unman 2 printfvous rétorque narquoisement qu’il n’y a pas d’entrée pourprintfdans la section 2 du manuel.
7.2.3 La variable d’environnement MANPATH
Le plus rageant avec l’utilisation demanest d’obtenir un insoutenableNo manual entry for (le nom de la commande). Par exemple, unman xvproduitNo manual entry for xv. La première idée qui peut vous venir à l’esprit est qu’il n’existe pas de documentation pour cet outil qu’estxv. C’est possible mais regardons de plus près une certaine variable d’environnement dénomméeMANPATH.
$ echo $MANPATH
/usr/share/man:/usr/local/man
$
Cette variable a le même format que ◮PATHNet indique à la commandeman les § 6.1.4 p. 147◭ endroits où rechercher les pages de manuel. Dans l’exemple précédent,manira donc
dans/usr/share/man puis (en cas d’échec) dans/usr/local/manpour tenter de trouver l’information qui vous intéresse. Aucune page n’étant associée à xv, man vous le signifie poliment. Il suffit de rajouter un nouveau répertoire de recherche (/usr/X11R6/mansous Linux) à la variableMANPATHpour voir apparaître la page de documentation.
$ export MANPATH=$MANPATH:/usr/X11R6/man
$ man xv
XV(1) XV(1)
NAME
xv - interactive image display for the X Window System ... etc ...
$
Cette variable devrait êtrea priori« correctement » configurée pour aller visiter les points de chute classiques des pages de manuel, c’est-à-dire (cette liste ne se veut en aucun cas exhaustive)/usr/share/man,/usr/local/manet/usr/X11R6/man.
Dans le cas où vous souhaiteriez installer certaines pages de manuel à certains endroits précis de votre compte utilisateur, vous pouvez utiliser la même démarche
et ajouter dans vos◮fichiersNde démarrage : § 6.1.6 p. 148◭