fmtmsg(3C) fmtmsg(3C)
NAME
fmtmsg - Meldung über stderr oder die Systemkonsole anzeigen
SYNTAX
#include <fmtmsg.h>
int fmtmsg(long classification, const char *label, int severity,
const char *text, const char *action, const char *tag);
BESCHREIBUNG
Aufbauend auf der Klassifikationskomponente einer Meldung, schreibt
fmtmsg() eine formatierte Meldung auf stderr, auf die Systemkonsole
oder auf beide.
fmtmsg() kann anstelle der üblichen Schnittstelle printf() verwendet
werden, um Meldungen über stderr auszugeben. fmtmsg() bietet in Ver-
bindung mit gettxt() eine einfache Schnittstelle zum Erstellen von
sprachunabhängigen Anwendungsprogrammen.
Eine formatierte Meldung besteht aus bis zu fünf Standardkomponenten,
die weiter unten definiert werden. Die Komponente classification ist
nicht Teil der Standardmeldung, die dem Benutzer angezeigt wird, son-
dern definiert die Quelle der Meldung und steuert die Anzeige der for-
matierten Meldung.
classification
enthält Bezeichner aus den folgenden Gruppen der Haupt- und
Nebenklassifikationen. Jeder Bezeichner einer Nebenklassifikation
kann durch ODER-Verknüpfung mit einem anderen Bezeichner einer
anderen Nebenklassifikation verwendet werden. Zwei oder mehr
Bezeichner aus derselben Nebenklassifikation sollten nicht zusam-
men verwendet werden, mit Ausnahme der Anzeigeklassifikation.
Beide Bezeichner der Anzeigeklassifikation können so verwendet
werden, daß die Meldungen sowohl auf stderr als auch auf der
Systemkonsole erscheinen.
"Hauptklassifikationen"
Bezeichnen den Ursprung eines Zustands. Die Bezeichner sind:
MMHARD (Hardware), MMSOFT (Software) und MMFIRM (Firm-
ware).
"Nebenklassifikationen des Meldungsursprungs"
Bezeichnen die Art der Software, in der das Problem auftrat.
Die Bezeichner sind: MMAPPL (Anwendung), MMUTIL (Hilfspro-
gramm) und MMOPSYS (Betriebssystem).
"Nebenklassifikationen für die Anzeige"
Bezeichnen, wo die Meldung angezeigt werden soll. Die
Bezeichner sind MMPRINT, um die Meldung auf der Standard-
Fehlerausgabe auszugeben, und MMCONSOLE, um die Meldung auf
der Systemkonsole auszugeben. Keiner, einer oder beide
Bezeichner können verwendet werden.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
fmtmsg(3C) fmtmsg(3C)
"Nebenklassifikationen für den Status"
Geben an, ob sich das Anwendungsprogramm nach dem Zustand
stabilisieren kann. Bezeichner sind: MMRECOVER (stabili-
sierbar) und MMNRECOV (nicht stabilisierbar).
Ein weiterer Bezeichner, MMNULLMC, gibt an, daß keine Klassifi-
kationskomponente für die Meldung angegeben wird.
label
gibt den Ursprung der Meldung an. Das Format dieser Komponente
besteht aus zwei Feldern, die durch einen Doppelpunkt getrennt
werden. Das erste Feld ist bis zu 10 Zeichen lang; das zweite ist
bis zu 14 Zeichen lang. Es wird dazu geraten, mit label das Paket
und das Programm oder den Anwendungsnamen zu bezeichnen. So zeigt
beispielsweise der Inhalt UX:cat für label an, daß das Paket UNIX
System V und die Anwendung cat gemeint ist.
severity
zeigt die Warnstufe des Zustands an. Bezeichner für die Standard-
warnstufen für severity sind:
MMHALT Zeigt an, daß die Anwendung auf einen schwerwie-
genden Fehler gestoßen ist und die Bearbeitung
anhält. Die Zeichenkette "HALT" wird ausgegeben.
MMERROR Zeigt an, daß die Anwendung einen Fehler erkannt
hat. Die Zeichenkette "ERROR" wird ausgegeben.
MMWARNING Zeigt an, daß ein ungewöhnlicher Zustand eingetre-
ten ist, bei dem es sich um ein Problem handeln
könnte und der beobachtet werden sollte. Die Zei-
chenkette "WARNING" wird ausgegeben.
MMINFO Liefert Informationen über einen Zustand, der kei-
nen Fehler darstellt. Die Zeichenkette "INFO" wird
ausgegeben.
MMNOSEV Zeigt an, daß für die Meldung keine Warnstufe exi-
stiert.
Weitere Warnstufen können mit der Funktion addse-
verity() hinzugefügt werden.
text beschreibt die Ursache der Meldung. Die Zeichenkette text ist
nicht auf eine bestimmte Länge beschränkt.
action
beschreibt die erste Aktion, die im Fehlerbehebungsprozeß ausge-
führt werden soll. fmtmsg() schreibt vor dieser Zeichenkette das
Präfix: "TO FIX:". Die Zeichenkette action ist nicht auf eine
bestimmte Länge beschränkt.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
fmtmsg(3C) fmtmsg(3C)
tag Ein Bezeichner, der auf die Online-Dokumentation für die Meldung
verweist. Empfohlen wird, daß tag ein label und eine eindeutige
Zahl enthält. Ein Beispiel für tag ist "UX:cat:146".
Umgebungsvariablen
Es gibt zwei Umgebungsvariablen, die das Verhalten von fmtmsg() beein-
flussen: MSGVERB und SEVLEVEL.
MSGVERB teilt fmtmsg() mit, welche Meldungskomponenten beim Schreiben
der Meldungen auf stderr ausgewählt werden sollen. Der Wert von
MSGVERB besteht aus einer Liste optionaler Schlüsselwörter, die durch
Doppelpunkte getrennt werden. MSGVERB kann wie folgt gesetzt werden:
MSGVERB=[Schlüsselwort[:Schlüsselwort[:...]]]
export MSGVERB
Gültige Schlüsselwörter sind: label, severity, text, action, und tag.
Wenn MSGVERB ein Schlüsselwort für eine Komponente enthält und der
Komponentenwert nicht den Wert Null hat, schreibt fmtmsg diese Kompo-
nente bei der Meldungsausgabe über stderr hinaus. Wenn MSGVERB kein
Schlüsselwort für eine Meldungskomponente enthält, wird diese Kompo-
nente nicht mit der Meldung angezeigt. Die Schlüsselwörter können in
einer beliebigen Reihenfolge angegeben werden. Ist MSGVERB nicht defi-
niert, enthält dieser Bezeichner eine Nullzeichenkette, ist der Wert
nicht im korrekten Format angegeben, oder sind ungültige Schlüsselwör-
ter angegeben, so wählt fmtmsg() alle Komponenten aus.
Beim ersten Aufruf von fmtmsg() wird die MSGVERB-Umgebungsvariable
abgeprüft, um die Meldungskomponenten selektieren zu können, wenn eine
Meldung über die Standard-Fehlerausgabe stderr generiert wird. Die
Werte, die beim ersten Aufruf akzeptiert werden, werden für die nach-
folgenden Aufrufe gesichert.
MSGVERB beeinflußt nur die Selektion der Komponenten, die über die
Standard-Fehlerausgabe angezeigt werden sollen. Bei Ausgabe auf die
Konsole werden alle Meldungen selektiert.
SEVLEVEL definiert die Warnstufen und weist die auszugebenden Zei-
chenketten zu, die von fmtmsg() benutzt werden sollen. Die unten ange-
gebenen Standardwarnstufen können nicht verändert werden. Weitere
Warnstufen können definiert, verändert und entfernt werden. Dies
geschieht über die Funktion addseverity() [siehe addseverity(3C)].
Wenn dieselbe Warnstufe durch SEVLEVEL und addseverity() definiert
wird, so setzt sich die Definition von addseverity() durch.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
fmtmsg(3C) fmtmsg(3C)
0 (keine Warnstufe verwendet)
1 HALT
2 ERROR
3 WARNING
4 INFO
SEVLEVEL kann wie folgt eingestellt werden:
SEVLEVEL=[Beschreibung[:Beschreibung[:...]]]
export SEVLEVEL
Beschreibung enthält eine Liste mit drei Feldern, die durch Kommata
getrennt werden:
Beschreibung=severitykeyword,level,printstring
severitykeyword ist eine Zeichenkette, die als Schlüsselwort für die
Option -s severity vom Kommando fmtmsg verwendet wird. Dieses Feld
wird nicht von der Funktion fmtmsg() verwendet.
level ist eine Zeichenkette, die eine positive ganze Zahl enthält
(nicht 0, 1, 2, 3 oder 4, denn diese Werte sind für die Standardwarn-
stufen reserviert). Wenn das Schlüsselwort severitykeyword verwendet
wird, stellt level die Warnstufe des Wertes dar, der an die Funktion
fmtmsg() übergeben wurde.
printstring ist eine Zeichenkette, die von fmtmsg() für das Standard-
meldungsformat verwendet wird, wenn die Warnstufe level angegeben
wird.
Stellt Beschreibung in der Liste keine durch Kommata getrennte Liste
mit drei Feldern dar, oder ist das zweite Feld einer Liste keine ganze
Zahl, so wird Beschreibung in der Liste ignoriert.
Wird fmtmsg() erstmals aufgerufen, dann wird die Umgebungsvariable
SEVLEVEL überprüft, um festzustellen, ob neben den fünf Standardwarn-
stufen und den durch addseverity() festgelegten zusätzliche Warnstufen
definiert wurden. Die Werte, die beim erstmaligen Aufruf festgestellt
wurden, werden für spätere Aufrufe gespeichert.
Benutzung in Anwendungsprogrammen
Eine oder mehrere Meldungskomponenten können systematisch aus der Mel-
dung weggelassen werden, wenn der Nullwert der jeweiligen Komponente
angegeben wird.
Die unten angegebene Tabelle zeigt die Nullwerte und Bezeichner für
die Argumente von fmtmsg().
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
fmtmsg(3C) fmtmsg(3C)
Argument Typ Nullwert Bezeichner
____________________________________________
label char* (char*) NULL MMNULLLBL
severity int 0 MMNULLSEV
class long 0L MMNULLMC
text char* (char*) NULL MMNULLTXT
action char* (char*) NULL MMNULLACT
tag char* (char*) NULL MMNULLTAG
Ein weiteres Mittel zum systematischen Weglassen einer Komponenten
besteht im Auslassen der Schlüsselwörter der Komponenten bei der Defi-
nition der MSGVERB-Umgebungsvariablen (siehe Abschnitt "Umgebungsva-
riablen").
BEISPIELE
Beispiel 1:
fmtmsg(MMPRINT, "UX:cat", MMERROR, "Falsche Syntax",
"Siehe Handbuch", "UX:cat:001")
liefert eine komplette Meldung mit dem Standardmeldungsformat:
UX:cat: ERROR: Falsche Syntax
TO FIX: Siehe Handbuch UX:cat:001
Beispiel 2: Wird die Umgebungsvariable MSGVERB wie folgt gesetzt:
MSGVERB=severity:text:action
und das Beispiel 1 verwendet, so generiert fmtmsg:
ERROR: Falsche Syntax TO FIX: Siehe Handbuch
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
fmtmsg(3C) fmtmsg(3C)
Beispiel 3: Wird die Umgebungsvariable SEVLEVEL wie folgt gesetzt:
SEVLEVEL=note,5,NOTE
so liefert der folgende Aufruf von fmtmsg:
fmtmsg(MMUTIL | MMPRINT, "UX:cat", 5, "Falsche Syntax",
"Siehe Handbuch", "UX:cat:001")
die folgende Ausgabe:
UX:cat: NOTE: Falsche Syntax
TO FIX: Siehe Handbuch UX:cat:001
ERGEBNIS
Die Rückgabewerte von fmtmsg() sind:
MMOK Die Funktion wurde erfolgreich ausgeführt.
MMNOTOK Die Funktion wurde nicht erfolgreich ausgeführt.
MMNOMSG Die Funktion konnte eine Meldung über die Standard-
Fehlerausgabe nicht generieren, wurde aber ansonsten
erfolgreich ausgeführt.
MMNOCON Die Funktion konnte eine Meldung über die Systemkonsole
nicht generieren, wurde aber ansonsten erfolgreich ausge-
führt.
SIEHE AUCH
fmtmsg(1), addseverity(3C), gettxt(3C), printf(3S).
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98