Provided by: manpages-fr_1.67.0-1_all bug

NOM

       fmtmsg - Afficher des messages d’erreur formatés

SYNOPSIS

       #include <fmtmsg.h>

       int fmtmsg(long classification, const char *label, int severity,
                  const char *text, const char *action, const char *tag);

DESCRIPTION

       Cette  fonction  affiche un message décrit par ses paramètres sur le(s)
       périphérique(s) spécifié(s) par le paramètre classification.  Pour  les
       messages   écrits   sur   stderr,  le  format  dépend  de  la  variable
       d’environnement MSGVERB.

       Le paramètre label identifie la source du message. La chaîne doit  être
       composée  en deux parties, séparées par le caractère deux-points « : »,
       où la première partie ne comporte pas  plus  de  10  caractères  et  la
       seconde, pas plus de 14.

       Le paramètre text décrit la condition de l’erreur.

       Le   paramètre  action  décrit  les  étapes  possibles  pour  récupérer
       l’erreur.  Si elle est affichée, elle sera préfixée par "TO FIX: ".

       Le paramètre tag est une référence à la documentation en ligne où  l’on
       pourra  trouver plus d’information. Il devrait contenir la valeur label
       et un numéro d’identification unique.

   Paramètres factices
       Chacun des paramètres peut avoir une  valeur  factice.   La  valeur  de
       classification factice MM_NULLMC (0L) ne spécifie aucune sortie, aussi,
       rien n’est affiché.  La valeur de sévérité factice NO_SEV (0)  signifie
       qu’aucune  sévérité n’est fournie.  Les valeurs MM_NULLLBL, MM_NULLTXT,
       MM_NULLACT, MM_NULLTAG sont des synonymes de ((char *)  0),  la  chaîne
       vide, et MM_NULLSEV est un synonyme de NO_SEV.

   Le paramètre classification
       Le  paramètre  classification est la somme de valeurs décrivant 4 types
       d’informations.

       La première valeur définit le canal de sortie.

       MM_PRINT    Sortir sur stderr.

       MM_CONSOLE  Sortir sur la console du système.

       MM_PRINT | MM_CONSOLE
                   Sortir sur les deux.

       La deuxième valeur est la source de l’erreur :

       MM_HARD     Une erreur matérielle est survenue.

       MM_FIRM     Une erreur micro-logicielle (firmware) est survenue.

       MM_SOFT     Une erreur logicielle est survenue.

       La troisième valeur encode le détecteur du problème :

       MM_APPL     L’erreur a été détectée par une application.

       MM_UTIL     L’erreur a été détectée par un utilitaire.

       MM_OPSYS    L’erreur a été détectée par le système d’exploitation.

       La quatrième valeur indique la gravité de l’incident :

       MM_RECOVER  L’erreur est récupérable.

       MM_NRECOV   L’erreur n’est pas récupérable.

   Le paramètre severity
       Le paramètre severity peut prendre l’une des valeurs suivantes :

       MM_NOSEV    Aucune sévérité ne sera affichée.

       MM_HALT     Cette valeur est affichée en tant que HALT.

       MM_ERROR    Cette valeur est affichée en tant que ERROR.

       MM_WARNING  Cette valeur est affichée en tant que WARNING.

       MM_INFO     Cette valeur est affichée en tant que INFO.

       Les valeurs numériques sont prises entre 0 et 4. Utiliser addseverity()
       ou la variable d’environnement SEV_LEVEL vous permet d’ajouter d’autres
       niveaux et messages à afficher.

ENVIRONNEMENT

       La variable d’environnement MSGVERB (« volubilité  du  message »)  peut
       être  utilisée  pour  supprimer  des  parties de la sortie vers stderr.
       (Cela n’a pas d’influence sur la  sortie  vers  la  console.)   Lorsque
       cette  variable  est  définie, non vide et que c’est une liste de mots-
       clés valides séparés par le caractère deux-points, seules  les  parties
       du message correspondantes à ces mots-clès seront affichées.  Les mots-
       clés valides sont  « label »,  « severity »,  « text »,  « action »  et
       « tag ».

       La   variable   d’environnement   SEV_LEVEL  peut  être  utilisée  afin
       d’introduire de nouveaux niveaux de gravité.   Par  défaut,  seuls  les
       cinqs  niveaux  de gravité décrits précédemment sont disponibles. Toute
       autre  valeur  numérique  fera  que  fmtmsg()  n’affichera  rien.    Si
       l’utilisateur positionne SEV_LEVEL avec un format comme

              SEV_LEVEL=[description[:description[:...]]]

       dans l’environnement du processus avant le premier appel à fmtmsg(), où
       chaque description est de la forme

              severity-keyword,level,printstring

       alors fmtmsg() acceptera également les valeurs indiquées pour le niveau
       (en  plus des niveaux standards 0-4), et utilisera la chaîne à afficher
       (printstring) indiquée lorsqu’un tel niveau surviendra.

       La partie « severity-keyword » n’est pas  utilisée  par  fmtmsg()  mais
       doit   être  présente.   La  partie  « level »  est  la  représentation
       alphabétique d’un nombre.  La valeur  numérique  doit  être  un  nombre
       strictement  supérieur  à  4.   Cette valeur doit être utilisée dans le
       paramètre « severity » de fmtmsg() pour sélectionner cette  classe.  Il
       n’est  pas  possible  de  surcharger les classes prédéfinies. La partie
       « printstring » est la chaîne qui sera affichée  lorsqu’un  message  de
       cette classe est traité par fmtmsg().

VALEURS RENVOYÉES

       La fonction peut retourner 4 valeurs :

       MM_OK       Tout c’est bien passé.

       MM_NOTOK    Échec complet.

       MM_NOMSG    Erreur lors de l’écriture sur stderr.

       MM_NOCON    Erreur lors de l’écriture sur la console.

CONFORMITÉ

       Les   fonctions   fmtmsg()   et   addseverity(),   et   les   variables
       d’environnement  MSGVERB  et  SEV_LEVEL   proviennent   de   System   V
       (XPG4-UNIX).   La  fonction  fmtmsg()  et  la  variable d’environnement
       MSGVERB sont décrites dans la spécification POSIX 1003.1-2001.

NOTES

       Les pages de manuel System V et Unixware nous disent que ces  fonctions
       ont été remplacées par « pfmt() et addsev() » ou par « pfmt(), vpfmt(),
       lfmt(), et vlfmt() », et seront supprimées par la suite.

EXEMPLE

       #include <stdio.h>
       #include <fmtmsg.h>

       int main() {
         long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
         int err;
         err = fmtmsg(class, "util-linux:mount", MM_ERROR,
               "unknown mount option", "See mount(8).", "util-linux:mount:017");
         switch(err) {
           case MM_OK:
             break;
           case MM_NOTOK:
             printf("Nothing printed\n");
             break;
           case MM_NOMSG:
             printf("Nothing printed to stderr\n");
             break;
           case MM_NOCON:
             printf("No console output\n");
             break;
           default:
             printf("Unknown error from fmtmsg()\n");
         }
         return 0;
       }

       La sortie devrait être :
         util-linux:mount: ERROR: unknown mount option
         TO FIX: See mount(8).  util-linux:mount:017
       et après
         MSGVERB=text:action; export MSGVERB
       la sortie devient :
         unknown mount option
         TO FIX: See mount(8).

VOIR AUSSI

       addseverity(3), perror(3)

TRADUCTION

       Ce document est une traduction réalisée par Alain  Portal  <aportal  AT
       univ-montp2 DOT fr> le 4 juillet 2005 et révisée le 14 décembre 2005.

       L’équipe  de  traduction a fait le maximum pour réaliser une adaptation
       française de qualité. La version anglaise la plus à jour de ce document
       est  toujours  consultable  via la commande : « LANG=en man 3 fmtmsg ».
       N’hésitez pas à signaler à l’auteur ou au  traducteur,  selon  le  cas,
       toute erreur dans cette page de manuel.

                               1er novembre 2003                     fmtmsg(3)