release/man3/fmtmsg.3

   1 .\"  Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\"
   3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   4 .\" Distributed under GPL
   5 .\" %%%LICENSE_END
   6 .\"
   7 .\"  adapted glibc info page
   8 .\"
   9 .\"  This should run as 'Guru Meditation' (amiga joke :)
  10 .\"  The function is quite complex and deserves an example
  11 .\"
  12 .\"  Polished, aeb, 2003-11-01
  13 .\"*******************************************************************
  14 .\"
  15 .\" This file was generated with po4a. Translate the source file.
  16 .\"
  17 .\"*******************************************************************
  18 .TH FMTMSG 3 2008\-06\-14 "" "Linux Programmer's Manual"
  19 .SH 名前
  20 fmtmsg \- 整形されたエラーメッセージを表示する
  21 .SH 書式
  22 .nf
  23 \fB#include <fmtmsg.h>\fP
  24 .sp
  25 \fBint fmtmsg(long \fP\fIclassification\fP\fB, const char *\fP\fIlabel\fP\fB,\fP
  26 .br
  27 \fB           int \fP\fIseverity\fP\fB, const char *\fP\fItext\fP\fB,\fP
  28 .br
  29 \fB           const char *\fP\fIaction\fP\fB, const char *\fP\fItag\fP\fB);\fP
  30 .fi
  31 .SH 説明
  32 この関数は、引き数で記述されたメッセージを、 \fIclassification\fP 引き数で指定されたデバイス上に表示する。 \fIstderr\fP
  33 に書き出されるメッセージのフォーマットは、 \fBMSGVERB\fP 環境変数に依存する。
  34 .LP
  35 \fIlabel\fP 引き数はメッセージの発生源を識別する。 この文字列はコロンで区切られた 2 つの部分から構成されていなければならない。 1
  36 つ目の部分は 10 文字以内でなければならず、 2 つ目の部分は 14 文字以内でなければならない。
  37 .LP
  38 \fItext\fP 引き数にはエラー条件を記述する。
  39 .LP
  40 \fIaction\fP 引き数にはエラーから回復するために利用可能なステップを記述する。 これが表示される場合、"TO FIX: " が前に付く。
  41 .LP
  42 \fItag\fP 引き数はより多くの情報を見つけるためのオンラインドキュメントへの参照である。 これは \fIlabel\fP
  43 値とユニークな識別番号を含んでいるべきである。
  44 .SS ダミー引き数
  45 各引き数にはダミーの値を入れることができる。 ダミーの \fIclassification\fP 値 \fBMM_NULLMC\fP (0L)
  46 は出力を何も指定しない。そのため何も表示されない。 ダミーの \fIseverity\fP 値 \fBNO_SEV\fP (0) は重大度 (severity)
  47 が与えられていないことを表す。 値 \fBMM_NULLLBL\fP, \fBMM_NULLTXT\fP, \fBMM_NULLACT\fP, \fBMM_NULLTAG\fP
  48 は \fI((char *) 0)\fP と空文字列の別名であり、 \fBMM_NULLSEV\fP は \fBNO_SEV\fP の別名である。
  49 .SS "classification 引き数"
  50 \fIclassification\fP 引き数は 4 種類の情報を記述する値の和である。
  51 .br
  52 .sp
  53 最初の値は出力チャンネルを定義する。
  54 .TP  12n
  55 \fBMM_PRINT\fP
  56 \fIstderr\fP に出力する。
  57 .TP
  58 \fBMM_CONSOLE\fP
  59 システムコンソールに出力する。
  60 .TP
  61 \fBMM_PRINT | MM_CONSOLE\fP
  62 両方に出力する。
  63 .PP
  64 2 番目の値はエラーの発生源である:
  65 .TP  12n
  66 \fBMM_HARD\fP
  67 ハードウェアエラーが起こった。
  68 .TP
  69 \fBMM_FIRM\fP
  70 ファームウェアエラーが起こった。
  71 .TP
  72 \fBMM_SOFT\fP
  73 ソフトウェアエラーが起こった。
  74 .PP
  75 3 番目の値は問題の検知を行ったものをエンコードする:
  76 .TP  12n
  77 \fBMM_APPL\fP
  78 アプリケーションによって検知された。
  79 .TP
  80 \fBMM_UTIL\fP
  81 ユーティリティによって検知された。
  82 .TP
  83 \fBMM_OPSYS\fP
  84 オペレーティングシステムによって検知された。
  85 .PP
  86 4 番目の値は問題の重大度を表す:
  87 .TP  12n
  88 \fBMM_RECOVER\fP
  89 回復可能なエラーである。
  90 .TP
  91 \fBMM_NRECOV\fP
  92 回復不可能なエラーである。
  93 .SS "severity 引き数"
  94 \fIseverity\fP 引き数は以下の 1 つの値をとることができる。
  95 .TP  12n
  96 \fBMM_NOSEV\fP
  97 重大度は表示されない。
  98 .TP
  99 \fBMM_HALT\fP
 100 この値は HALT として表示される。
 101 .TP
 102 \fBMM_ERROR\fP
 103 この値は ERROR として表示される。
 104 .TP
 105 \fBMM_WARNING\fP
 106 この値は WARNING として表示される。
 107 .TP
 108 \fBMM_INFO\fP
 109 この値は INFO として表示される。
 110 .PP
 111 数値の場合は 0 から 4 である。 \fBaddseverity\fP(3)  または環境変数 \fBSEV_LEVEL\fP
 112 を使うことにより、表示するレベルと文字列を更に追加できる。
 113 .SH 返り値
 114 関数は 4 つの値を返す:
 115 .TP  12n
 116 \fBMM_OK\fP
 117 全てがうまくいった。
 118 .TP
 119 \fBMM_NOTOK\fP
 120 完全に失敗した。
 121 .TP
 122 \fBMM_NOMSG\fP
 123 \fIstderr\fP に書き込むときにエラーが起こった。
 124 .TP
 125 \fBMM_NOCON\fP
 126 コンソールに書き込むときにエラーが起こった。
 127 .SH 環境変数
 128 環境変数 \fBMSGVERB\fP ("message verbosity") は \fIstderr\fP への出力の一部を抑制するのに使うことができる。
 129 (コンソールへの出力には影響しない。)  この変数が定義されて、NULL でなく、 コロンで区切られた有効なキーワードのリストである場合、
 130 キーワードに対応するメッセージの一部のみが表示される。 有効なキーワードは "label", "severity", "text", "action",
 131 "tag" である。
 132 .PP
 133 環境変数 \fBSEV_LEVEL\fP は新しい重大度レベルを導入するのに使用できる。 デフォルトでは、上記の 5 つの重大度レベルのみが利用可能である。
 134 他の数値の場合、 \fBfmtmsg\fP()  は何も表示しない。 \fBfmtmsg\fP()  を初めて呼び出す前に、ユーザが \fBSEV_LEVEL\fP を
 135 .sp
 136 .RS
 137 SEV_LEVEL=[description[:description[:...]]]
 138 .RE
 139 .sp
 140 のような形式でプロセスの環境に設定すると、 \fBfmtmsg\fP()  は (標準のレベル 0\-4 に加えて) level に指定された値も受け付け、
 141 そのようなレベルの問題が発生すると指定された printstring を表示する。 各 description は
 142 .sp
 143 .RS
 144 severity\-keyword,level,printstring
 145 .RE
 146 .sp
 147 という形式である。
 148 .LP
 149 severity\-keyword 部は \fBfmtmsg\fP()  に使用されないが、存在しなければならない。 level
 150 部は数値を文字列で表したものである。 数値は 4 より大きい値でなければならない。 この値は \fBfmtmsg\fP()  の severity
 151 引き数で使用されなければならず、この重大度を選択する。 前もって宣言された重大度を上書きすることはできない。 printstring は、
 152 この重大度のメッセージが \fBfmtmsg\fP()  によって生成された場合に表示される文字列である。
 153 .SH バージョン
 154 \fBfmtmsg\fP()  は、バージョン 2.1 以降の glibc で提供されている。
 155 .SH 準拠
 156 関数 \fBfmtmsg\fP()  と \fBaddseverity\fP(3)  と環境変数 \fBMSGVERB\fP と \fBSEV_LEVEL\fP は
 157 System V に由来している。 関数 \fBfmtmsg\fP()  と環境変数 \fBMSGVERB\fP は POSIX.1\-2001 に記述されている。
 158 .SH 注意
 159 System V と UnixWare の man ページには、 「これらの関数は "pfmt() と addsev()" または "pfmt(),
 160 vpfmt(), lfmt(), vlfmt()" で置き換えられており、 将来は削除される予定である」と書かれている。
 161 .SH 例
 162 .nf
 163 #include <stdio.h>
 164 #include <stdlib.h>
 165 #include <fmtmsg.h>
 166
 167 int
 168 main(void)
 169 {
 170     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 171     int err;
 172
 173     err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
 174                 "unknown mount option", "See mount(8).",
 175                 "util\-linux:mount:017");
 176     switch (err) {
 177     case MM_OK:
 178       break;
 179     case MM_NOTOK:
 180         printf("Nothing printed\en");
 181         break;
 182     case MM_NOMSG:
 183         printf("Nothing printed to stderr\en");
 184         break;
 185     case MM_NOCON:
 186         printf("No console output\en");
 187         break;
 188     default:
 189         printf("Unknown error from fmtmsg()\en");
 190     }
 191     exit(EXIT_SUCCESS);
 192 }
 193 .fi
 194 .PP
 195 出力は
 196 .nf
 197
 198     util\-linux:mount: ERROR: unknown mount option
 199     TO FIX: See mount(8).  util\-linux:mount:017
 200
 201 .fi
 202 のようになり、
 203 .nf
 204
 205     MSGVERB=text:action; export MSGVERB
 206
 207 .fi
 208 を実行すると、次のようになる。
 209 .nf
 210
 211     unknown mount option
 212     TO FIX: See mount(8).
 213 .fi
 214 .SH 関連項目
 215 \fBaddseverity\fP(3), \fBperror\fP(3)
 216 .SH この文書について
 217 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.51 の一部
 218 である。プロジェクトの説明とバグ報告に関する情報は
 219 http://www.kernel.org/doc/man\-pages/ に書かれている。