log(7) log(7)
NAME
log - Schnittstelle zur STREAMS-Fehlerprotokollierung und Ereignis-
Überwachung
BESCHREIBUNG
log ist ein Software-Treiber unter STREAMS, der eine Schnittstelle zur
Konsol-Protokollierung, zur STREAMS-Fehlerprotokollierung und zu
Ereignis-Überwachungs-Prozessen bietet [siehe strerr(1M), strace(1M)].
log bietet zwei verschiedene Schnittstellen: eine Funktionsaufruf-
Schnittstelle im Systemkern, über die STREAMS-Treiber und -Module
log-Nachrichten einbringen; außerdem eine Untermenge der ioctl(2)-
Systemaufrufe und STREAMS-Nachrichten für die Zusammenarbeit mit einem
Konsol-Protokollierer auf Benutzerebene, einem Fehler-Protokollierer,
einem Trace-Protokollierer oder mit Prozessen, die eigene Protokoll-
Nachrichten einbringen müssen.
Systemkern-Schnittstelle
log-Nachrichten werden innerhalb des Systemkerns durch Aufrufe der
Funktion strlog erzeugt:
strlog(mid, sid, level, flags, fmt, arg1, ...)
short mid, sid;
char level;
ushort flags;
char *fmt;
unsigned arg1;
Notwendige Definitionen sind in <sys/strlog.h>, <sys/log.h> und
<sys/syslog.h> enthalten. mid ist die Kennzahl des STREAMS-Moduls
(Treibers), das die log-Nachricht einbringt. sid ist eine interne
Unterkennzahl, die normalerweise dazu verwendet wird, ein bestimmtes
Minorgerät zu einem Treiber zu identifizieren. level ist eine Trace-
Ebene, die eine selektive Unterdrückung von Nachrichten niedriger
Priorität erlaubt. flags ist eine beliebige Kombination aus: SLERROR
(Nachricht für Fehler-Protokoll), SLTRACE (Nachricht für Trace-
Protokoll), SLCONSOLE (Nachricht für das Konsol-Protokoll), SLFATAL
(freiwillige Benachrichtigung über nichtbehebbaren Fehler), SLNOTIFY
(Kopie der Nachricht per mail an den Systemverwalter). fmt ist eine
Formatzeichenkette nach der Art von printf(3S), außer daß %s, %e, %E,
%g und %G nicht behandelt werden. Bis zu NLOGARGS (derzeit 3) numeri-
sche oder char-Argumente können übergeben werden.
Benutzer-Schnittstelle
log wird über die clone-Schnittstelle /dev/log geöffnet. Jedes Öffnen
von /dev/log liefert einen eigenen Stream zu log. Um Protokoll-Nach-
richten zu empfangen, muß ein Prozeß zunächst log darüber unterrich-
ten, ob er es sich um einen Fehler-Protokollierer, einen Trace-Proto-
kollierer oder einen Konsol-Protokollierer handelt. Dies geschieht mit
Hilfe eines ioctl-Aufrufs der Art ISTR (siehe unten). Im Fall eines
Konsol-Protokollierers ist in diesem ISTR die Komponente iccmd mit
ICONSLOG besetzt, und es werden keine weiteren Daten übergeben. Für
einen Fehler-Protokollierer ist die Komponente iccmd mit dem Wert
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
log(7) log(7)
IERRLOG besetzt, und es werden keine weiteren Daten übergeben. Für
einen Trace-Protokollierer ist die Komponente iccmd mit dem Wert
ITRCLOG besetzt, und es muß ein Datenpuffer übergeben werden, der
mindestens ein Element der Art struct traceids enthält. Jede
traceids-Struktur gibt jeweils einen Wert für mid, sid und level an,
für die Nachrichten akzeptiert werden. strlog akzeptiert Nachrichten,
deren mid- und sid-Werte exakt denen entsprechen, die in der
traceids-Struktur angegeben sind und deren level-Wert kleiner oder
gleich dem in der traceids-Struktur ist. Der Wert -1 in einer der
Komponenten der traceids-Struktur gibt an, daß ein beliebiger Wert
für diese Komponente akzeptiert wird.
Nachdem sich der Protokollierer über einen ioctl-Aufruf selbst identi-
fiziert hat, beginnt log damit, Nachrichten gemäß den oben angeführten
Einschränkungen zu senden. Diese Nachrichten werden mit dem Systemauf-
ruf getmsg(2) gelesen. Der Steuerteil dieser Nachricht enthält eine
logctl-Struktur, die folgende Daten enthält: mid, sid, level, flags,
Zeit in Ticks seit dem Booten, bei dem die Nachricht eingebracht
wurde, die entsprechende Zeit in Sekunden seit 1. Januar 1970 (Epo-
chenwert), eine Sequenznummer und eine Priorität. Die Zeit in Sekunden
seit 1970 wird mit übergeben, damit Datum und Zeit der Nachricht ein-
fach berechnet werden können, die Zeit in Ticks seit dem Booten ist
deshalb vorhanden, damit die relative Dauer der log-Nachrichten
bestimmt werden kann.
Die Priorität setzt sich zusammen aus einem Prioritäts- und einem
Einrichtungs-Code, die aus <sys/syslog.h> stammen. Wenn SLCONSOLE in
flags gesetzt ist, dann wird der Prioritäts-Code wie folgt gesetzt.
Wenn SLWARN gesetzt ist, dann wird der Prioritäts-Code gleich
LOGWARNING gesetzt. Ist SLFATAL gesetzt, dann ist der Prioritäts-
Code gleich LOGCRIT. Ist SLERROR gesetzt, dann ist der Prioritäts-
Code gleich LOGERR. Ist SLNOTE gesetzt, dann ist der Prioritäts-Code
gleich LOGNOTICE. Ist SLTRACE gesetzt, dann ist der Prioritäts-Code
gleich LOGDEBUG. Ist nur SLCONSOLE gesetzt, dann ist der Priori-
täts-Code gleich LOGINFO. Nachrichten, die aus dem Systemkern kommen,
besitzen den Einrichtungs-Code LOGKERN. Die meisten Nachrichten, die
von Benutzerprozessen stammen, besitzen den Einrichtungs-Code
LOGUSER.
Für die Fehler- und Trace-Protokollierung werden verschiedene Sequenz-
nummern verwaltet, so daß Lücken in der Abfolge der Nachrichten
erkannt werden können. In Zeiten hohen Nachrichten-Aufkommens kann es
sein, daß einige Nachrichten nicht ausgeliefert werden, um System-
Betriebsmittel aufzusparen. Der Datenteil der Nachricht enthält den
unveränderten Text der Formatzeichenkette, die mit dem Nullbyte abge-
schlossen ist, gefolgt von NLOGARGS Wörtern für die Argumente der For-
matzeichenkette, ausgerichtet auf die erste Wortgrenze nach der Zei-
chenkette.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
log(7) log(7)
Ein Prozeß kann eine Nachricht derselben Struktur an log senden, auch
wenn er kein Fehler- oder Überwachungs-Protokollierer ist. Die einzi-
gen Komponenten der logctl-Struktur im Steuerteil der Nachricht, die
akzeptiert werden, sind level, flags und pri; alle anderen Komponenten
werden von log aufgefüllt, bevor sie an den entsprechenden Protokol-
lierer weitergeleitet werden. Der Datenteil muß die mit dem Nullbyte
abgeschlossene Formatzeichenkette und die Argumente (wortweise, ab der
nächsten Wortgrenze, bis zu NLOGARGS) enthalten.
ENXIO wird für ITRCLOG-ioctl-Aufrufe ohne traceids-Strukturen
zurückgegeben und ebenso für alle nicht erkannten ioctl-Aufrufe der
Art ISTR. Fehlerhaft formatierte log-Nachrichten, die von einem
Benutzerprozeß an den Treiber gesendet werden, werden stillschweigend
ignoriert.
Prozesse, die eine Nachricht an den Konsol-Protokollierer schreiben
wollen, können Ihre Ausgabe in /dev/conslog lenken, indem Sie write(2)
oder putmsg(2) verwenden.
BEISPIELE
Beispiel für IERRLOG-Benachrichtigung.
struct strioctl ioc;
ioc.iccmd = IERRLOG;
ioc.ictimout = 0; /* Standard-Timeout (15 Sekunden) */
ioc.iclen = 0;
ioc.icdp = NULL;
ioctl(log, ISTR, &ioc);
Beispiel für ITRCLOG-Benachrichtigung.
struct traceids tid[2];
tid[0].timid = 2;
tid[0].tisid = 0;
tid[0].tilevel = 1;
tid[1].timid = 1002;
tid[1].tisid = -1; /* jede Unter-Kennzahl ist erlaubt */
tid[1].tilevel = -1; /* jede Ebene ist erlaubt */
ioc.iccmd = ITRCLOG;
ioc.ictimout = 0;
ioc.iclen = 2 * sizeof(struct traceids);
ioc.icdp = (char *)tid;
ioctl(log, ISTR, &ioc);
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
log(7) log(7)
Beispiel für eine log-Nachricht (keine Argumente).
struct strbuf ctl, dat;
struct logctl lc;
char *message =
"Vergiß nicht, auf dem Weg nach Hause Milch zu besorgen";
ctl.len = ctl.maxlen = sizeof(lc);
ctl.buf = (char *)&lc;
dat.len = dat.maxlen = strlen(message);
dat.buf = message;
lc.level = 0;
lc.flags = SLERROR|SLNOTIFY;
putmsg(log, &ctl, &dat, 0);
DATEIEN
/dev/log
/dev/conslog
<sys/log.h>
<sys/strlog.h>
<sys/syslog.h>
SIEHE AUCH
strace(1M), strerr(1M), getmsg(2), introprm2(2), putmsg(2), write(2),
clone(7).
Leitfaden für Programmierer: STREAMS
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98