名称

fmtmsg — 詳細な診断メッセージを表示する

ライブラリ

Standard C Library (libc, -lc)

書式

#include < fmtmsg.h>

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

解説

fmtmsg() 関数は、 stderr および/または、システムコンソールに、供給された引数に基づく詳細な診断メッセージを表示します。

classification 引数は、それぞれの以下の分類グループから 0 または明白な定数の 1 つのビット毎の包括的な論理和 (OR) です。 Output 分類グループは、 MM_PRINT と MM_CONSOLE の両方が指定されるときからの例外です。

Output

MM_PRINT

出力は、 stderr に行われるべきです。

MM_CONSOLE

出力は、システムコンソールに行われるべきです。

状態のソース (メジャ)

MM_HARD

状態のソースは、関連するハードウェアです。

MM_SOFT

状態のソースは、関連するソフトウェアです。

MM_FIRM

状態のソースは、関連するファームウェアです。

状態のソース (マイナ)

MM_APPL

状態は、アプリケーションレベルで検出されました。

MM_UTIL

状態は、ユーティリティレベルで検出されました。

MM_OPSYS

状態は、オペレーティングシステムレベルで検出されました。

Status

MM_RECOVER

アプリケーションは、状態から復旧することができます。

MM_NRECOV

アプリケーションは、状態から復旧することができません。

代わりに、 MM_NULLMC の明白な定数は、分類を指定しないようにするために使用されます。

label 引数は、メッセージのソースを示します。それは、コロン (‘ :’) によって分離された 2 つのフィールドから成ります。最初のフィールドは、最大 10 バイトを指定でき、 2 番目のフィールドは、最大 14 バイトを指定できます。 MM_NULLLBL の明白な定数は、ラベルなしを指定するために使用されます。

severity 引数は、状態の重要性を識別します。次の明白な定数の 1 つは、この引数に使用されるべきです。

MM_HALT

アプリケーションは、重大な障害に直面し、停止します。

MM_ERROR

アプリケーションは、障害を検出しました。

MM_WARNING

アプリケーションは、問題を表すかもしれない、普通でない状態を検出しました。

MM_INFO

アプリケーションは、エラーでない状態に関する情報を提供します。

MM_NOSEV

厳しいレベルが供給されません。

text 引数は、メッセージを引き起こしたエラー状態を詳しく述べます。この文字列のサイズに制限はありません。 MM_NULLTXT の明白な定数は、テキストなしを指定するために使用されます。

action 引数は、エラー復旧のプロセスがどのように始まるべきであるかを詳しく述べます。出力のときに、 fmtmsg() は、 action 引数の始めに“ TO FIX:”を前に置きます。 MM_NULLACT の明白な定数は、動作なしを指定するために使用されます。

tag 引数は、メッセージのためのオンライン文書を参照すべきです。通常、これは、 label とユニークな識別番号を含んでいます。タグの例は、“ BSD:ls:168”です。 MM_NULLTAG の明白な定数は、タグなしを指定するために使用されます。

戻り値

fmtmsg() 関数は、成功すれば、 MM_OK、 stderr への出力が失敗したのを示す MM_NOMSG、システムコンソールへの出力が失敗したのを示す MM_NOCON、 stderr への出力とシステムコンソールの失敗を示す MM_NOTOK を返します。

環境変数

MSGVERB (メッセージ冗長) 環境変数は、 stderr へ出力する fmtmsg() への引数とどのような順序かを指定します。 MSGVERB は、識別子のリストを分離するコロン (‘ :’) であるべきです。有効な識別子は: label, severity, text, action, と tag です。無効の識別子を指定するか、または不正に分離するなら、デフォルトメッセージの冗長と順序が使用されます。デフォルトの順序は、“ label:severity:text:action:tag”の値のための MSGVERB と同等です。

使用例

次のコードは:

fmtmsg(MM_UTIL | MM_PRINT, "BSD:ls", MM_ERROR, 
    "illegal option -- z", "refer to manual", "BSD:ls:001");

次のように:

BSD:ls: ERROR: illegal option -- z 
TO FIX: refer to manual BSD:ls:001

stderr に出力されます。

同じコードは、“ text:severity:action:tag”に設定された MSGVERB で次のように発生されます:

illegal option -- z: ERROR 
TO FIX: refer to manual BSD:ls:001

関連項目

err(3), exit(3), strerror(3)

規格

fmtmsg() 関数は、 IEEE Std 1003.1-2001 (“POSIX.1”) に適合しています。

歴史

fmtmsg() 関数は、 FreeBSD 5.0 ではじめて登場しました。

バグ

classification 引数のための MM_NULLMC の指定は、指定された出力なしで fmtmsg() が何も役に立つことができないので、ほとんど意味がありません。

システムコンソールに出力する fmtmsg() のためには、実効ユーザは、 /dev/console に書き込むために適切なパーミッションがなければなりません。これは、ほとんどのシステムで、実効ユーザが root でないなら fmtmsg() が MM_NOCON を返すことを意味します。