.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) .\" Distributed under GPL .\" adapted glibc info page .\" .\" This should run as 'Guru Meditation' (amiga joke :) .\" The function is quite complex and deserves an example .\" .\" Polished, aeb, 2003-11-01 .\" .\" Japanese Version Copyright (c) 2004 Yuichi SATO .\" all rights reserved. .\" Translated Sat Jul 24 20:19:54 JST 2004 .\" by Yuichi SATO .\" .TH FMTMSG 3 2008-06-14 "" "Linux Programmer's Manual" .SH 名前 fmtmsg \- 整形されたエラーメッセージを表示する .SH 書式 .nf .B #include .sp .BI "int fmtmsg(long " classification ", const char *" label , .br .BI " int " severity ", const char *" text , .br .BI " const char *" action ", const char *" tag ); .fi .SH 説明 この関数は、引き数で記述されたメッセージを、 .I classification 引き数で指定されたデバイス上に表示する。 .I stderr に書き出されるメッセージのフォーマットは、 .B MSGVERB 環境変数に依存する。 .LP .I label 引き数はメッセージの発生源を識別する。 この文字列はコロンで区切られた 2 つの部分から構成されていなければならない。 1 つ目の部分は 10 文字以内でなければならず、 2 つ目の部分は 14 文字以内でなければならない。 .LP .I text 引き数にはエラー条件を記述する。 .LP .I action 引き数にはエラーから回復するために利用可能なステップを記述する。 これが表示される場合、"TO FIX: " が前に付く。 .LP .I tag 引き数はより多くの情報を見つけるためのオンラインドキュメントへの参照である。 これは .I label 値とユニークな識別番号を含んでいるべきである。 .SS ダミー引き数 各引き数にはダミーの値を入れることができる。 ダミーの .I classification 値 .B MM_NULLMC (0L) は出力を何も指定しない。そのため何も表示されない。 ダミーの .I severity 値 .B NO_SEV (0) は重大度 (severity) が与えられていないことを表す。 値 .BR MM_NULLLBL , .BR MM_NULLTXT , .BR MM_NULLACT , .B MM_NULLTAG は .I "((char *) 0)" と空文字列の別名であり、 .B MM_NULLSEV は .B NO_SEV の別名である。 .SS "classification 引き数" .I classification 引き数は 4 種類の情報を記述する値の和である。 .br .sp 最初の値は出力チャンネルを定義する。 .TP 12n .B MM_PRINT .I stderr に出力する。 .TP .B MM_CONSOLE システムコンソールに出力する。 .TP .B "MM_PRINT | MM_CONSOLE" 両方に出力する。 .PP 2 番目の値はエラーの発生源である: .TP 12n .B MM_HARD ハードウェアエラーが起こった。 .TP .B MM_FIRM ファームウェアエラーが起こった。 .TP .B MM_SOFT ソフトウェアエラーが起こった。 .PP 3 番目の値は問題の検知を行ったものをエンコードする: .TP 12n .B MM_APPL アプリケーションによって検知された。 .TP .B MM_UTIL ユーティリティによって検知された。 .TP .B MM_OPSYS オペレーティングシステムによって検知された。 .PP 4 番目の値は問題の重大度を表す: .TP 12n .B MM_RECOVER 回復可能なエラーである。 .TP .B MM_NRECOV 回復不可能なエラーである。 .SS "severity 引き数" .I severity 引き数は以下の 1 つの値をとることができる。 .TP 12n .B MM_NOSEV 重大度は表示されない。 .TP .B MM_HALT この値は HALT として表示される。 .TP .B MM_ERROR この値は ERROR として表示される。 .TP .B MM_WARNING この値は WARNING として表示される。 .TP .B MM_INFO この値は INFO として表示される。 .PP 数値の場合は 0 から 4 である。 .BR addseverity (3) または環境変数 .B SEV_LEVEL を使うことにより、表示するレベルと文字列を更に追加できる。 .SH 返り値 関数は 4 つの値を返す: .TP 12n .B MM_OK 全てがうまくいった。 .TP .B MM_NOTOK 完全に失敗した。 .TP .B MM_NOMSG .I stderr に書き込むときにエラーが起こった。 .TP .B MM_NOCON コンソールに書き込むときにエラーが起こった。 .SH 環境変数 環境変数 .B MSGVERB ("message verbosity") は .I stderr への出力の一部を抑制するのに使うことができる。 (コンソールへの出力には影響しない。) この変数が定義されて、NULL でなく、 コロンで区切られた有効なキーワードのリストである場合、 キーワードに対応するメッセージの一部のみが表示される。 有効なキーワードは "label", "severity", "text", "action", "tag" である。 .PP 環境変数 .B SEV_LEVEL は新しい重大度レベルを導入するのに使用できる。 デフォルトでは、上記の 5 つの重大度レベルのみが利用可能である。 他の数値の場合、 .BR fmtmsg () は何も表示しない。 .BR fmtmsg () を初めて呼び出す前に、ユーザが .B SEV_LEVEL を .sp .RS SEV_LEVEL=[description[:description[:...]]] .RE .sp のような形式でプロセスの環境に設定すると、 .BR fmtmsg () は (標準のレベル 0-4 に加えて) level に指定された値も受け付け、 そのようなレベルの問題が発生すると指定された printstring を表示する。 各 description は .sp .RS severity-keyword,level,printstring .RE .sp という形式である。 .LP severity-keyword 部は .BR fmtmsg () に使用されないが、存在しなければならない。 level 部は数値を文字列で表したものである。 数値は 4 より大きい値でなければならない。 この値は .BR fmtmsg () の severity 引き数で使用されなければならず、この重大度を選択する。 前もって宣言された重大度を上書きすることはできない。 printstring は、 この重大度のメッセージが .BR fmtmsg () によって生成された場合に表示される文字列である。 .SH バージョン .BR fmtmsg () は、バージョン 2.1 以降の glibc で提供されている。 .SH 準拠 関数 .BR fmtmsg () と .BR addseverity (3) と環境変数 .B MSGVERB と .B SEV_LEVEL は System V に由来している。 関数 .BR fmtmsg () と環境変数 .B MSGVERB は POSIX.1-2001 に記述されている。 .SH 注意 System V と UnixWare の man ページには、 「これらの関数は "pfmt() と addsev()" または "pfmt(), vpfmt(), lfmt(), vlfmt()" で置き換えられており、 将来は削除される予定である」と書かれている。 .SH 例 .nf #include #include #include 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\en"); break; case MM_NOMSG: printf("Nothing printed to stderr\en"); break; case MM_NOCON: printf("No console output\en"); break; default: printf("Unknown error from fmtmsg()\en"); } exit(EXIT_SUCCESS); } .fi .PP 出力は .nf util\-linux:mount: ERROR: unknown mount option TO FIX: See mount(8). util\-linux:mount:017 .fi のようになり、 .nf MSGVERB=text:action; export MSGVERB .fi を実行した後では .nf unknown mount option TO FIX: See mount(8). .fi となる。 .SH 関連項目 .BR addseverity (3), .BR perror (3)