draft/man3/fmtmsg.3

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