fmtmsg - Meldung auf stderr und/oder die Systemkonsole ausgeben

Definition

#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 an Stelle der üblichen printf() Schnittstelle verwendet werden, um Meldungen über stderr auszugeben. fmtmsg() bietet in Verbindung 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, sondern definiert die Quelle der Meldung und steuert die Anzeige der formatierten 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 zusammen verwendet werden, mit Ausnahme der Anzeigeklassifikation. Beide Bezeichner der Anzeigeklassifikation können so verwendet werden, dass die Meldungen sowohl auf stderr als auch auf der Systemkonsole erscheinen.

Hauptklassifikationen

bezeichnen den Ursprung eines Zustands. Die Bezeichner sind: MM_HARD (Hardware), MM_SOFT (Software) und MM_FIRM (Firmware).

Nebenklassifikationen des Meldungsursprungs

bezeichnen die Art der Software, in der das Problem auftrat. Die Bezeichner sind: MM_APPL (Anwendung), MM_UTIL (Hilfsprogramm) und MM_OPSYS (Betriebssystem).

Nebenklassifikationen für die Anzeige

bezeichnen, wo die Meldung angezeigt werden soll. Die Bezeichner sind MM_PRINT, um die Meldung auf der Standard-Fehlerausgabe auszugeben, und MM_CONSOLE, um die Meldung auf der Systemkonsole auszugeben. Sie können einen oder beide Bezeichner verwenden oder die Angabe weglassen (in diesem Falle wird nichts ausgegeben).

Nebenklassifikationen für den Status

geben an, ob sich das Anwendungsprogramm nach dem Zustand stabilisieren kann. Bezeichner sind: MM_RECOVER (stabilisierbar) und MM_NRECOV (nicht stabilisierbar).

Zusätzlicher Bezeichner MM_NULLMC

gibt an, dass keine Klassifikationskomponente 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, dass das Paket UNIX-System V und die Anwendung cat gemeint ist.

severity

zeigt die Warnstufe des Zustands an. Bezeichner für die Warnstufen für severity sind:

MM_HALT	zeigt an, dass die Anwendung auf einen schwer wiegenden Fehler gestoßen ist und die Bearbeitung anhält. Die Zeichenkette „HALT“ wird ausgegeben.
MM_ERROR	zeigt an, dass die Anwendung einen Fehler erkannt hat. Die Zeichenkette „ERROR“ wird ausgegeben.
MM_WARNING	zeigt an, dass ein ungewöhnlicher Zustand eingetreten ist, bei dem es sich um ein Problem handeln könnte und der beobachtet werden sollte. Die Zeichenkette „WARNING“ wird ausgegeben.
MM_INFO	liefert Informationen über einen Zustand, der keinen Fehler darstellt. Die Zeichenkette „INFO“ wird ausgegeben.
MM_NOSEV	zeigt an, dass für die Meldung keine Warnstufe existiert.

 

text

beschreibt die Ursache der Meldung. Die Zeichenkette text ist nicht auf eine bestimmte Länge beschränkt. Wenn die Zeichenkette leer ist, ist der ausgegebene Text undefiniert.

 

action

beschreibt die erste Aktion, die im Fehlerbehebungsprozess ausgefü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.

 

tag

Ein Bezeichner, der auf die Online-Dokumentation für die Meldung verweist.
Empfohlen wird, dass tag den über label angesprochenen Ursprung der Meldung 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() beeinflussen: MSGVERB und SEV_LEVEL.

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 diese Komponente nicht den ihr zugeordneten Nullwert hat (siehe unten), gibt fmtmsg() diese Komponente bei der Meldungsausgabe auf stderr aus. Wenn MSGVERB das Schlüsselwort für eine Meldungskomponente nicht enthält, wird diese Komponente nicht ausgegeben. Die Schlüsselwörter können in einer beliebigen Reihenfolge angegeben werden. Ist MSGVERB nicht definiert, enthält dieser Bezeichner eine Nullzeichenkette, ist der Wert nicht im korrekten Format angegeben, oder sind ungültige Schlüsselwörter 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 nachfolgenden Aufrufe gesichert.

MSGVERB beeinflusst nur die Selektion der Komponenten, die über die Standard-Fehlerausgabe angezeigt werden sollen. Bei Ausgabe auf die Konsole werden alle Meldungen selektiert.

SEV_LEVEL definiert die Warnstufen und weist die auszugebenden Zeichenketten zu, die von fmtmsg() benutzt werden sollen. Die unten angegebenen 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 SEV_LEVEL und addseverity() definiert wird, so setzt sich die Definition von addseverity() durch.

0   (keine Warnstufe verwendet)
1   HALT
2   ERROR
3   WARNING
4   INFO

SEV_LEVEL kann wie folgt eingestellt werden:

SEV_LEVEL=[Beschreibung[: Beschreibung[:...]]]

export SEV_LEVEL

Beschreibung enthält eine Liste mit drei Feldern, die durch Kommata getrennt werden:

Beschreibung = severity_keyword , level , printstring

severity_keyword 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 Standardwarnstufen reserviert). Wenn das Schlüsselwort sseverity_keyword 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 Standardmeldungsformat 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 SEV_LEVEL überprüft, um festzustellen, ob neben den fünf Standardwarnstufen 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.

Returnwert

MM_OK

bei Erfolg.

 

MM_NOTOK

Die Funktion ist völlig fehlgeschlagen.

 

MM_NOMSG

Die Funktion konnte eine Meldung über die Standard-Fehlerausgabe nicht generieren, wurde aber ansonsten erfolgreich ausgeführt.

 

MM_NOCON

Die Funktion konnte eine Meldung über die Systemkonsole nicht generieren, wurde aber ansonsten erfolgreich ausgeführt.

Hinweise 

Eine oder mehrere Meldungskomponenten können systematisch aus der Meldung weggelassen werden, wenn der Nullwert der jeweiligen Komponente angegeben wird.
Die folgende Tabelle zeigt die Nullwerte und Bezeichner für die Argumente von fmtmsg().

Argument	Typ	Nullwert	Bezeichner
label	char*	(char*) NULL	MM_NULLLBL
severity	int	0	MM_NULLSEV
class	long	0L	MM_NULLMC
text	char*	(char*) NULL	MM_NULLTXT
action	char*	(char*) NULL	MM_NULLACT
tag	char*	(char*) NULL	MM_NULLTAG

Ein weiteres Mittel zum systematischen Weglassen einer Komponenten besteht im Auslassen der Schlüsselwörter der Komponenten bei der Definition der MSGVERB-Umgebungsvariablen.

Beispiel 1

fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "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 dann Beispiel 1 verwendet, so generiert fmtmsg():

ERROR: Falsche Syntax TO FIX: Siehe Handbuch 

Beispiel 3

Wird die Umgebungsvariable SEV_LEVEL wie folgt gesetzt:

SEV_LEVEL=note,5,NOTE

so liefert der folgende Aufruf von fmtmsg():

fmtmsg(MM_UTIL | MM_PRINT, "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 

Siehe auch

printf(), fmtmsg.h.