Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
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);
}
出力は
util-linux:mount: ERROR: unknown mount option
TO FIX: See mount(8). util-linux:mount:017
のようになり、
MSGVERB=text:action; export MSGVERB
を実行すると、次のようになる。
unknown mount option
TO FIX: See mount(8).
関連項目
addseverity(3), perror(3)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。
2020-06-09 FMTMSG(3)