draft/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 2013\-06\-21 "" "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 Each of the arguments can have a dummy value.  The dummy classification
  46 value \fBMM_NULLMC\fP (0L) does not specify any output, so nothing is printed.
  47 The dummy severity value \fBNO_SEV\fP (0) says that no severity is supplied.
  48 The values \fBMM_NULLLBL\fP, \fBMM_NULLTXT\fP, \fBMM_NULLACT\fP, \fBMM_NULLTAG\fP are
  49 synonyms for \fI((char\ *)\ 0)\fP, the empty string, and \fBMM_NULLSEV\fP is a
  50 synonym for \fBNO_SEV\fP.
  51 .SS "classification 引き数"
  52 \fIclassification\fP 引き数は 4 種類の情報を記述する値の和である。
  53 .br
  54 .sp
  55 最初の値は出力チャンネルを定義する。
  56 .TP  12n
  57 \fBMM_PRINT\fP
  58 \fIstderr\fP に出力する。
  59 .TP
  60 \fBMM_CONSOLE\fP
  61 システムコンソールに出力する。
  62 .TP
  63 \fBMM_PRINT | MM_CONSOLE\fP
  64 両方に出力する。
  65 .PP
  66 2 番目の値はエラーの発生源である:
  67 .TP  12n
  68 \fBMM_HARD\fP
  69 ハードウェアエラーが起こった。
  70 .TP
  71 \fBMM_FIRM\fP
  72 ファームウェアエラーが起こった。
  73 .TP
  74 \fBMM_SOFT\fP
  75 ソフトウェアエラーが起こった。
  76 .PP
  77 3 番目の値は問題の検知を行ったものをエンコードする:
  78 .TP  12n
  79 \fBMM_APPL\fP
  80 アプリケーションによって検知された。
  81 .TP
  82 \fBMM_UTIL\fP
  83 ユーティリティによって検知された。
  84 .TP
  85 \fBMM_OPSYS\fP
  86 オペレーティングシステムによって検知された。
  87 .PP
  88 4 番目の値は問題の重大度を表す:
  89 .TP  12n
  90 \fBMM_RECOVER\fP
  91 回復可能なエラーである。
  92 .TP
  93 \fBMM_NRECOV\fP
  94 回復不可能なエラーである。
  95 .SS "severity 引き数"
  96 \fIseverity\fP 引き数は以下の 1 つの値をとることができる。
  97 .TP  12n
  98 \fBMM_NOSEV\fP
  99 重大度は表示されない。
 100 .TP
 101 \fBMM_HALT\fP
 102 この値は HALT として表示される。
 103 .TP
 104 \fBMM_ERROR\fP
 105 この値は ERROR として表示される。
 106 .TP
 107 \fBMM_WARNING\fP
 108 この値は WARNING として表示される。
 109 .TP
 110 \fBMM_INFO\fP
 111 この値は INFO として表示される。
 112 .PP
 113 数値の場合は 0 から 4 である。 \fBaddseverity\fP(3)  または環境変数 \fBSEV_LEVEL\fP
 114 を使うことにより、表示するレベルと文字列を更に追加できる。
 115 .SH 返り値
 116 関数は 4 つの値を返す:
 117 .TP  12n
 118 \fBMM_OK\fP
 119 全てがうまくいった。
 120 .TP
 121 \fBMM_NOTOK\fP
 122 完全に失敗した。
 123 .TP
 124 \fBMM_NOMSG\fP
 125 \fIstderr\fP に書き込むときにエラーが起こった。
 126 .TP
 127 \fBMM_NOCON\fP
 128 コンソールに書き込むときにエラーが起こった。
 129 .SH 環境変数
 130 環境変数 \fBMSGVERB\fP ("message verbosity") は \fIstderr\fP への出力の一部を抑制するのに使うことができる。
 131 (コンソールへの出力には影響しない。)  この変数が定義されて、NULL でなく、 コロンで区切られた有効なキーワードのリストである場合、
 132 キーワードに対応するメッセージの一部のみが表示される。 有効なキーワードは "label", "severity", "text", "action",
 133 "tag" である。
 134 .PP
 135 環境変数 \fBSEV_LEVEL\fP は新しい重大度レベルを導入するのに使用できる。 デフォルトでは、上記の 5 つの重大度レベルのみが利用可能である。
 136 他の数値の場合、 \fBfmtmsg\fP()  は何も表示しない。 \fBfmtmsg\fP()  を初めて呼び出す前に、ユーザが \fBSEV_LEVEL\fP を
 137 .sp
 138 .RS
 139 SEV_LEVEL=[description[:description[:...]]]
 140 .RE
 141 .sp
 142 のような形式でプロセスの環境に設定すると、 \fBfmtmsg\fP()  は (標準のレベル 0\-4 に加えて) level に指定された値も受け付け、
 143 そのようなレベルの問題が発生すると指定された printstring を表示する。 各 description は
 144 .sp
 145 .RS
 146 severity\-keyword,level,printstring
 147 .RE
 148 .sp
 149 という形式である。
 150 .LP
 151 severity\-keyword 部は \fBfmtmsg\fP()  に使用されないが、存在しなければならない。 level
 152 部は数値を文字列で表したものである。 数値は 4 より大きい値でなければならない。 この値は \fBfmtmsg\fP()  の severity
 153 引き数で使用されなければならず、この重大度を選択する。 前もって宣言された重大度を上書きすることはできない。 printstring は、
 154 この重大度のメッセージが \fBfmtmsg\fP()  によって生成された場合に表示される文字列である。
 155 .SH バージョン
 156 \fBfmtmsg\fP()  は、バージョン 2.1 以降の glibc で提供されている。
 157 .SH ATTRIBUTES
 158 .SS "Multithreading (see pthreads(7))"
 159 Before glibc 2.16, the \fBfmtmsg\fP()  function uses a static variable that is
 160 not protected, so it is not thread\-safe.
 161
 162 .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
 163 Since glibc 2.16, the \fBfmtmsg\fP()  function uses a lock to protect the
 164 static variable, so it is thread\-safe.
 165 .SH 準拠
 166 関数 \fBfmtmsg\fP()  と \fBaddseverity\fP(3)  と環境変数 \fBMSGVERB\fP と \fBSEV_LEVEL\fP は
 167 System V に由来している。 関数 \fBfmtmsg\fP()  と環境変数 \fBMSGVERB\fP は POSIX.1\-2001 に記述されている。
 168 .SH 注意
 169 System V と UnixWare の man ページには、 「これらの関数は "pfmt() と addsev()" または "pfmt(),
 170 vpfmt(), lfmt(), vlfmt()" で置き換えられており、 将来は削除される予定である」と書かれている。
 171 .SH 例
 172 .nf
 173 #include <stdio.h>
 174 #include <stdlib.h>
 175 #include <fmtmsg.h>
 176
 177 int
 178 main(void)
 179 {
 180     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 181     int err;
 182
 183     err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
 184                 "unknown mount option", "See mount(8).",
 185                 "util\-linux:mount:017");
 186     switch (err) {
 187     case MM_OK:
 188       break;
 189     case MM_NOTOK:
 190         printf("Nothing printed\en");
 191         break;
 192     case MM_NOMSG:
 193         printf("Nothing printed to stderr\en");
 194         break;
 195     case MM_NOCON:
 196         printf("No console output\en");
 197         break;
 198     default:
 199         printf("Unknown error from fmtmsg()\en");
 200     }
 201     exit(EXIT_SUCCESS);
 202 }
 203 .fi
 204 .PP
 205 出力は
 206 .nf
 207
 208     util\-linux:mount: ERROR: unknown mount option
 209     TO FIX: See mount(8).  util\-linux:mount:017
 210
 211 .fi
 212 のようになり、
 213 .nf
 214
 215     MSGVERB=text:action; export MSGVERB
 216
 217 .fi
 218 を実行すると、次のようになる。
 219 .nf
 220
 221     unknown mount option
 222     TO FIX: See mount(8).
 223 .fi
 224 .SH 関連項目
 225 \fBaddseverity\fP(3), \fBperror\fP(3)
 226 .SH この文書について
 227 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 228 である。プロジェクトの説明とバグ報告に関する情報は
 229 http://www.kernel.org/doc/man\-pages/ に書かれている。