SYSLOG(2)

NOM
syslog, klogctl - Lire et/ou effacer les tampons circulaires de messages du noyau

SYNOPSIS
int syslog(int type, char *bufp, int len);
           /* Aucune enveloppe fournie par la glibc */

/* L'interface glibc */
#include <sys/klog.h>

int klogctl(int type, char *bufp, int len);

DESCRIPTION
Si vous avez besoin de la fonction syslog() de la libc (celle qui dialogue avec syslogd(8)), consultez syslog(3). L'appel système de ce nom contrôle le tampon printk() du noyau, et la version de la glibc s'appelle klogctl(). L'argument type détermine l'action effectuée par cette fonction. Extrait de kernel/printk.c :
/*
 * Commandes de sys_syslog :
 *
 *   0 -- Fermer le journal (actuellement NOP)
 *   1 -- ouvrir le journal (actuellement NOP)
 *   2 -- Lire depuis le journal
 *   3 -- Lire tous les messages restants du tampon circulaire.
 *   4 -- Lire et effacer tous les messages restants du tampon circulaire.
 *   5 -- Vider le tampon circulaire
 *   6 -- Désactiver printk sur la console
 *   7 -- Activer printk sur la console
 *   8 -- Indiquer le niveau des messages à afficher sur la console.
 *   9 -- Renvoyer le nombre de caractères non lus dans le tampon.
 *  10 -- Renvoyer la taille du tampon de journalisation
 */
Seules les commandes de type 3 et 10 sont autorisées pour les processus non privilégiés. Le type 9 a été ajouté dans le noyau 2.4.10 ; le type 10 dans le noyau 2.6.6.

  Le tampon de journalisation du noyau.
Le noyau dispose d'un tampon circulaire d'une longueur LOG_BUF_LEN dans lequel les messages fournis en argument à la fonction du noyau printk(). sont stockés (quelque soit le niveau de journalisation). Dans les premiers noyaux LOG_BUF_LEN avait une valeur de 4096, 8192 depuis le noyau 1.3.54 et 16384 depuis le noyau 2.1.113). Depuis les noyaux 2.4.23/2.6, cette valeur est une option de configuration du noyau. Dans les noyaux récents, la taille peut être demandée avec la commande de type 10. L'appel syslog(2,buf,len) attend que ce journal soit non vide, puis lit au plus len octets qu'il place dans le tampon buf. Il renvoie le nombre d'octets lus. Les octets lus sont extraits du journal : les informations ne peuvent être lues qu'une seule fois. C'est la fonction exécutée par le noyau quand un programme utilisateur lit /proc/kmsg. L'appel syslog(3,buf,len) lit les len dernier octets depuis le journal (de manière non destructive). Il ne lira pas plus que ce qui a été écrit dans le tampon depuis la dernière commande de lecture destructrice (commande « clear ring buffer », qui en fait ne nettoie pas le tampon). Il renvoie le nombre d'octets lus. L'appel syslog(4,buf,len) effectue la même chose puis vide le tampon (avec la commande « clear ring buffer »). L'appel syslog(5,dummy,dummy) vide uniquement le tampon (avec la commande « clear ring buffer »). (Dans chaque apppel où buf ou len sont indiqués comme factice (« dummy »), la valeur de l'argument est ignorée par l'appel). L'appel syslog(6,dummy,dummy) définit le niveau de journalisation de la console au minimum, de telle sorte qu'aucun message n'est affiché sur la console. L'appel syslog(7,dummy,dummy) définit le niveau de journalisation de la console à la valeur par défaut, de telle sorte que les messages sont affichés sur la console. L'appel syslog(8,dummy,level) définit le niveau de journalisation de la console à la valeur level, qui doit être un entier compris entre 1 et 8 (de manière inclusive). Voir la section Le niveau de journalisation (loglevel) pour plus de détails. L'appel syslog(9,dummy,dummy) renvoie le nombre d'octets actuellement disponibles en lecture dans le tampon de journalisation du noyau. L'appel syslog(10,dummy,dummy) renvoie la taille totale du tampon de journalisation du noyau.

  Le niveau de journalisation (loglevel)
La routine du noyau printk() n'écrira un message sur la console que si celui-ci a un niveau de journalisation inférieur à la valeur de la variable console_loglevel. Cette variable a initialement la valeur DEFAULT_CONSOLE_LOGLEVEL (7), mais est augmentée à 10 si la ligne de commande du noyau contient le mot « debug », et à 15 si une faute du noyau se produit (en réalité, les valeurs 10 et 15 sont idiotes et n'apportent rien de plus que 8). Cette variable est positionnée (dans l'intervalle 1-8) par l'appel syslog(8,dummy,value). L'appel syslog(type,dummy,dummy) avec type égal à 6 ou 7 la positionne à 1 (seulement les messages kernel panics) ou 7 (tout sauf les messages de débogage), respectivement. Chaque ligne de texte dans un message a son propre niveau de journalisation. Ce niveau est DEFAULT_MESSAGE_LOGLEVEL - 1 (6) à moins que la ligne ne commence par <d> où d est un chiffre dans l'intervalle 1-7. La signification conventionnelle des niveaux de journalisation est définie dans <linux/kernel.h> comme suit :
#define KERN_EMERG    "<0>"  /* système inutilisable             */
#define KERN_ALERT    "<1>"  /* action à effectuer immédiatement */
#define KERN_CRIT     "<2>"  /* conditions critiques             */
#define KERN_ERR      "<3>"  /* conditions d'erreurs             */
#define KERN_WARNING  "<4>"  /* message d'avertissement          */
#define KERN_NOTICE   "<5>"  /* normal mais significatif         */
#define KERN_INFO     "<6>"  /* informations                     */
#define KERN_DEBUG    "<7>"  /* messages de débogage             */

VALEUR RENVOYÉE
Pour type valant 2, 3 ou 4, un appel réussi à syslog() renvoie le nombre d'octets lus. Pour type valant 9, syslog() renvoie le nombre d'octets actuellement disponibles en lecture dans le tampon de journalisation du noyau. Pour type valant 10, syslog() renvoie la taille totale du tampon de journalisation du noyau. Pour les autres valeurs de type, syslog() renvoie 0 s'il réussit. En cas d'erreur, -1 est renvoyé et errno contient le code d'erreur.

ERREURS

EINVAL
    Mauvais paramètres (par exemple, mauvaise valeur de type ; ou pour type valant 2, 3 ou 4, buf est NULL, ou len est inférieur à zéro ; ou pour type valant 8, level n'est pas dans l'intervalle 1 à 8).

EPERM
    Une tentative de changer console_loglevel ou d'effacer le tampon circulaire du noyau par un processus sans les privilèges suffisants (plus précisément, sans la capacité CAP_SYS_ADMIN).

ERESTARTSYS
    L'appel système a été interrompu par un signal ; rien n'a été lu. (Ceci ne peut être vu que pendant un suivi de processus).

ENOSYS
    L'appel système syslog() n'est pas disponible car le noyau a été compilé sans que l'option CONFIG_PRINTK de configuration du noyau n'ait été activée.

CONFORMITÉ
Cet appel système est spécifique à Linux et ne doit pas être employé dans des programmes destinés à être portables.

NOTES
Depuis longtemps, des gens trouvent regrettable qu'un appel système du noyau et une routine de bibliothèque aient le même nom bien qu'ils n'aient pas de rapport entre eux. Dans les libc4 et libc5, le numéro de cet appel système était défini par SYS_klog. Dans la glibc 2.0, l'appel système est nommé klogctl().

VOIR AUSSI
syslog(3)

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 15 octobre 1996 et révisée le 2 juillet 2008.

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=C man 2 syslog ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.