wiki:InsiaProgCDoc

Sommaire

Pratique - Les pages de manuel

Les sections

Les pages de manuel (man page en V.O.) sont rangées en volumes, appelées sections - à l'instar des volumes du manuel livrés originellement avec le système Unix (il a plus de 30 ans!) et qui étaient numérotés comme suit (source: Wikipedia):

  1. Commandes utilisateur
  2. Appels système
  3. Fonctions de bibliothèque
  4. Fichiers spéciaux
  5. Formats de fichier
  6. Jeux
  7. Divers
  8. Administration système

Quand un élément documenté est cité (fonction, fichier, commande, etc), en général on précise entre parenthèses la section du manuel à laquelle il appartient, par exemple mmap(2). Ceci est particulièrement utile dans le cas où un même nom est utilisé pour différents éléments: printf(1) est une commande, tandis que printf(2) est la fameuse fonction d'affichage de la bibliothèque standard.

Recherche et consultation

On peut chercher dans l'ensemble des sections la documentation d'un élément avec whatis:

$ whatis printf
printf (1)           - format and print data
printf (3)           - formatted output conversion

Si on veut accéder à une section donnée du manuelle, il faut la préciser avant l'élément:

$ man 3 printf

Notez qu'en général le pager utilisé pour visionner les pages de manuel est less et qu'il vous offre des raccourcis pratiques:

G Aller à la fin de la documentation
1G Aller au début
/toto Rechercher l'occurence toto et la(les) surligner
n Aller à l'occurence de recherche suivante
N Aller à l'occurence de recherche précédente
q Quitter

Structure

Une page de manuel a toujours la même structure. En particulier pour les fonctions des bibliothèques C, on doit toujours pouvoir retrouver d'un seul coup d'oeil les informations suivantes:

  • Prototype de la fonction ou du groupe de fonctions recherchée(s)
  • Entête contenant le ou les prototype(s) (#include...)
  • Description avec le comportement général de la ou les fonctions en détaillant la signification des paramètres
  • Valeurs de retour et détail de la gestion d'erreur éventuel (errno, etc)
  • Un exemple d'utilisation pour les fonctions non triviales
  • Compatibilité avec les standards (POSIX, SYSV, ec) et/ou les implémentations
  • Bugs connus
  • Voir aussi: suggestions de fonctions similaires ou associées
Last modified 14 years ago Last modified on Nov 5, 2006, 11:34:43 PM