FMTMSG

Section: Linux Programmer's Manual (3)
Updated: 2020-06-09
Index JM Home Page

名前

fmtmsg - 整形されたエラーメッセージを表示する

書式

#include <fmtmsg.h>

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

説明

この関数は、引数で記述されたメッセージを、 classification 引数で指定されたデバイス上に表示する。 stderr に書き出されるメッセージのフォーマットは、 MSGVERB 環境変数に依存する。

label 引数はメッセージの発生源を識別する。この文字列はコロンで区切られた 2 つの部分から構成されていなければならない。 1 つ目の部分は 10 文字以内でなければならず、 2 つ目の部分は 14 文字以内でなければならない。

text 引数にはエラー条件を記述する。

action 引数にはエラーから回復するために利用可能なステップを記述する。これが表示される場合、"TO FIX: " が前に付く。

tag 引数はより多くの情報を見つけるためのオンラインドキュメントへの参照である。これは label 値とユニークな識別番号を含んでいるべきである。

ダミー引数

各引数にはダミーの値を入れることができる。ダミーの classification 値 MM_NULLMC (0L) は出力を何も指定しない。そのため何も表示されない。ダミーの severity 値 NO_SEV (0) は重大度 (severity) が与えられていないことを表す。値 MM_NULLLBL, MM_NULLTXT, MM_NULLACT, MM_NULLTAG は ((char *) 0) と空文字列の別名であり、 MM_NULLSEV は NO_SEV の別名である。

classification 引数

classification 引数は 4 種類の情報を記述する値の和である。

最初の値は出力チャンネルを定義する。

MM_PRINT: stderr に出力する。
MM_CONSOLE: システムコンソールに出力する。
MM_PRINT | MM_CONSOLE: 両方に出力する。

2 番目の値はエラーの発生源である:

MM_HARD: ハードウェアエラーが起こった。
MM_FIRM: ファームウェアエラーが起こった。
MM_SOFT: ソフトウェアエラーが起こった。

3 番目の値は問題の検知を行ったものをエンコードする:

MM_APPL: アプリケーションによって検知された。
MM_UTIL: ユーティリティによって検知された。
MM_OPSYS: オペレーティングシステムによって検知された。

4 番目の値は問題の重大度を表す:

MM_RECOVER: 回復可能なエラーである。
MM_NRECOV: 回復不可能なエラーである。

severity 引数

severity 引数は以下の 1 つの値をとることができる。

MM_NOSEV: 重大度は表示されない。
MM_HALT: この値は HALT として表示される。
MM_ERROR: この値は ERROR として表示される。
MM_WARNING: この値は WARNING として表示される。
MM_INFO: この値は INFO として表示される。

数値の場合は 0 から 4 である。 addseverity(3) または環境変数 SEV_LEVEL を使うことにより、表示するレベルと文字列を更に追加できる。

返り値

関数は 4 つの値を返す:

MM_OK: 全てがうまくいった。
MM_NOTOK: 完全に失敗した。
MM_NOMSG: stderr に書き込むときにエラーが起こった。
MM_NOCON: コンソールに書き込むときにエラーが起こった。

環境変数

環境変数 MSGVERB ("message verbosity") は stderr への出力の一部を抑制するのに使うことができる。 (コンソールへの出力には影響しない。) この変数が定義されて、NULL でなく、コロンで区切られた有効なキーワードのリストである場合、キーワードに対応するメッセージの一部のみが表示される。有効なキーワードは "label", "severity", "text", "action", "tag" である。

環境変数 SEV_LEVEL は新しい重大度レベルを導入するのに使用できる。デフォルトでは、上記の 5 つの重大度レベルのみが利用可能である。他の数値の場合、 fmtmsg() は何も表示しない。 fmtmsg() を初めて呼び出す前に、ユーザーが SEV_LEVEL を

SEV_LEVEL=[description[:description[:...]]]

のような形式でプロセスの環境に設定すると、 fmtmsg() は (標準のレベル 0-4 に加えて) level に指定された値も受け付け、そのようなレベルの問題が発生すると指定された printstring を表示する。各 description は

severity-keyword,level,printstring

という形式である。

severity-keyword 部は fmtmsg() に使用されないが、存在しなければならない。 level 部は数値を文字列で表したものである。数値は 4 より大きい値でなければならない。この値は fmtmsg() の severity 引数で使用されなければならず、この重大度を選択する。前もって宣言された重大度を上書きすることはできない。 printstring は、この重大度のメッセージが fmtmsg() によって生成された場合に表示される文字列である。

バージョン

fmtmsg() は、バージョン 2.1 以降の glibc で提供されている。

属性

この節で使用されている用語の説明については、 attributes(7) を参照。

インターフェース	属性	値
fmtmsg()	Thread safety	glibc >= 2.16: MT-Safe glibc < 2.16: MT-Unsafe

glibc 2.16 より前のバージョンでは、 fmtmsg() 関数は、保護されていない静的な変数を使うため、スレッドセーフではない。

glibc 2.16 以降では、 fmtmsg() 関数はロックを使って静的な変数を保護しており、スレッドセーフである。

準拠

関数 fmtmsg() と addseverity(3) と環境変数 MSGVERB と SEV_LEVEL は System V に由来している。

関数 fmtmsg() と環境変数 MSGVERB は POSIX.1-2001 と POSIX.1-2008 に規定されている。

注意

System V と UnixWare の man ページには、「これらの関数は "pfmt() と addsev()" または "pfmt(), vpfmt(), lfmt(), vlfmt()" で置き換えられており、将来は削除される予定である」と書かれている。

例

#include <stdio.h> #include <stdlib.h> #include <fmtmsg.h>

int main(void) {
long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
int err;

    err = fmtmsg(class, "util-linux:mount", MM_ERROR,
                "unknown mount option", "See mount(8).",
                "util-linux:mount:017");
    switch (err) {
    case MM_OK:
      break;
    case MM_NOTOK:
        printf("Nothing printed\n");
        break;
    case MM_NOMSG:
        printf("Nothing printed to stderr\n");
        break;
    case MM_NOCON:
        printf("No console output\n");
        break;
    default:
        printf("Unknown error from fmtmsg()\n");
    }
    exit(EXIT_SUCCESS); }