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 .\" Japanese Version Copyright (c) 2004 Yuichi SATO
  11 .\"         all rights reserved.
  12 .\" Translated Sat Jul 24 20:19:54 JST 2004
  13 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  14 .\"
  15 .TH FMTMSG 3 2008-06-14 "" "Linux Programmer's Manual"
  16 .\"O .SH NAME
  17 .SH 名前
  18 .\"O fmtmsg \- print formatted error messages
  19 fmtmsg \- 整形されたエラーメッセージを表示する
  20 .\"O .SH SYNOPSIS
  21 .SH 書式
  22 .nf
  23 .B #include <fmtmsg.h>
  24 .sp
  25 .BI "int fmtmsg(long " classification ", const char *" label ,
  26 .br
  27 .BI "           int " severity ", const char *" text ,
  28 .br
  29 .BI "           const char *" action ", const char *" tag );
  30 .fi
  31 .\"O .SH DESCRIPTION
  32 .SH 説明
  33 .\"O This function displays a message described by its arguments on the device(s)
  34 .\"O specified in the
  35 .\"O .I classification
  36 .\"O argument.
  37 .\"O For messages written to
  38 .\"O .IR stderr ,
  39 .\"O the format depends on the
  40 .\"O .B MSGVERB
  41 .\"O environment variable.
  42 この関数は、引き数で記述されたメッセージを、
  43 .I classification
  44 引き数で指定されたデバイス上に表示する。
  45 .I stderr
  46 に書き出されるメッセージのフォーマットは、
  47 .B MSGVERB
  48 環境変数に依存する。
  49 .LP
  50 .\"O The
  51 .\"O .I label
  52 .\"O argument identifies the source of the message.
  53 .\"O The string must consist
  54 .\"O of two colon separated parts where the first part has not more
  55 .\"O than 10 and the second part not more than 14 characters.
  56 .I label
  57 引き数はメッセージの発生源を識別する。
  58 この文字列はコロンで区切られた 2 つの部分から構成されていなければならない。
  59 1 つ目の部分は 10 文字以内でなければならず、
  60 2 つ目の部分は 14 文字以内でなければならない。
  61 .LP
  62 .\"O The
  63 .\"O .I text
  64 .\"O argument describes the condition of the error.
  65 .I text
  66 引き数にはエラー条件を記述する。
  67 .LP
  68 .\"O The
  69 .\"O .I action
  70 .\"O argument describes possible steps to recover from the error.
  71 .\"O If it is printed, it is prefixed by "TO FIX: ".
  72 .I action
  73 引き数にはエラーから回復するために利用可能なステップを記述する。
  74 これが表示される場合、"TO FIX: " が前に付く。
  75 .LP
  76 .\"O The
  77 .\"O .I tag
  78 .\"O argument is a reference to the online documentation where more
  79 .\"O information can be found.
  80 .\"O It should contain the
  81 .\"O .I label
  82 .\"O value and a unique identification number.
  83 .I tag
  84 引き数はより多くの情報を見つけるためのオンラインドキュメントへの参照である。
  85 これは
  86 .I label
  87 値とユニークな識別番号を含んでいるべきである。
  88 .\"O .SS "Dummy arguments"
  89 .SS ダミー引き数
  90 .\"O Each of the arguments can have a dummy value.
  91 .\"O The dummy classification value
  92 .\"O .B MM_NULLMC
  93 .\"O (0L) does not specify any output, so nothing is printed.
  94 各引き数にはダミーの値を入れることができる。
  95 ダミーの
  96 .I classification
  97 値
  98 .B MM_NULLMC
  99 (0L) は出力を何も指定しない。そのため何も表示されない。
 100 .\"O The dummy severity value
 101 .\"O .B NO_SEV
 102 .\"O (0) says that no severity is supplied.
 103 ダミーの
 104 .I severity
 105 値
 106 .B NO_SEV
 107 (0) は重大度 (severity) が与えられていないことを表す。
 108 .\"O The values
 109 .\"O .BR MM_NULLLBL ,
 110 .\"O .BR MM_NULLTXT ,
 111 .\"O .BR MM_NULLACT ,
 112 .\"O .B MM_NULLTAG
 113 .\"O are synonyms for
 114 .\"O .IR "((char *) 0)" ,
 115 .\"O the empty string, and
 116 .\"O .B MM_NULLSEV
 117 .\"O is a synonym for
 118 .\"O .BR NO_SEV .
 119 値
 120 .BR MM_NULLLBL ,
 121 .BR MM_NULLTXT ,
 122 .BR MM_NULLACT ,
 123 .B MM_NULLTAG
 124 は
 125 .I "((char *) 0)"
 126 と空文字列の別名であり、
 127 .B MM_NULLSEV
 128 は
 129 .B NO_SEV
 130 の別名である。
 131 .\"O .SS "The classification argument"
 132 .SS "classification 引き数"
 133 .\"O The
 134 .\"O .I classification
 135 .\"O argument is the sum of values describing 4 types of information.
 136 .I classification
 137 引き数は 4 種類の情報を記述する値の和である。
 138 .br
 139 .sp
 140 .\"O The first value defines the output channel.
 141 最初の値は出力チャンネルを定義する。
 142 .TP 12n
 143 .B MM_PRINT
 144 .\"O Output to
 145 .\"O .IR stderr .
 146 .I stderr
 147 に出力する。
 148 .TP
 149 .B MM_CONSOLE
 150 .\"O Output to the system console.
 151 システムコンソールに出力する。
 152 .TP
 153 .B "MM_PRINT | MM_CONSOLE"
 154 .\"O Output to both.
 155 両方に出力する。
 156 .PP
 157 .\"O The second value is the source of the error:
 158 2 番目の値はエラーの発生源である:
 159 .TP 12n
 160 .B MM_HARD
 161 .\"O A hardware error occurred.
 162 ハードウェアエラーが起こった。
 163 .TP
 164 .B MM_FIRM
 165 .\"O A firmware error occurred.
 166 ファームウェアエラーが起こった。
 167 .TP
 168 .B MM_SOFT
 169 .\"O A software error occurred.
 170 ソフトウェアエラーが起こった。
 171 .PP
 172 .\"O The third value encodes the detector of the problem:
 173 3 番目の値は問題の検知を行ったものをエンコードする:
 174 .TP 12n
 175 .B MM_APPL
 176 .\"O It is detected by an application.
 177 アプリケーションによって検知された。
 178 .TP
 179 .B MM_UTIL
 180 .\"O It is detected by a utility.
 181 ユーティリティによって検知された。
 182 .TP
 183 .B MM_OPSYS
 184 .\"O It is detected by the operating system.
 185 オペレーティングシステムによって検知された。
 186 .PP
 187 .\"O The fourth value shows the severity of the incident:
 188 4 番目の値は問題の重大度を表す:
 189 .TP 12n
 190 .B MM_RECOVER
 191 .\"O It is a recoverable error.
 192 回復可能なエラーである。
 193 .TP
 194 .B MM_NRECOV
 195 .\"O It is a nonrecoverable error.
 196 回復不可能なエラーである。
 197 .\"O .SS "The severity argument"
 198 .SS "severity 引き数"
 199 .\"O The
 200 .\"O .I severity
 201 .\"O argument can take one of the following values:
 202 .I severity
 203 引き数は以下の 1 つの値をとることができる。
 204 .TP 12n
 205 .B MM_NOSEV
 206 .\"O No severity is printed.
 207 重大度は表示されない。
 208 .TP
 209 .B MM_HALT
 210 .\"O This value is printed as HALT.
 211 この値は HALT として表示される。
 212 .TP
 213 .B MM_ERROR
 214 .\"O This value is printed as ERROR.
 215 この値は ERROR として表示される。
 216 .TP
 217 .B MM_WARNING
 218 .\"O This value is printed as WARNING.
 219 この値は WARNING として表示される。
 220 .TP
 221 .B MM_INFO
 222 .\"O This value is printed as INFO.
 223 この値は INFO として表示される。
 224 .PP
 225 .\"O The numeric values are between 0 and 4.
 226 .\"O Using
 227 .\"O .BR addseverity (3)
 228 .\"O or the environment variable
 229 .\"O .B SEV_LEVEL
 230 .\"O you can add more levels and strings to print.
 231 数値の場合は 0 から 4 である。
 232 .BR addseverity (3)
 233 または環境変数
 234 .B SEV_LEVEL
 235 を使うことにより、表示するレベルと文字列を更に追加できる。
 236 .\"O .SH "RETURN VALUE"
 237 .SH 返り値
 238 .\"O The function can return 4 values:
 239 関数は 4 つの値を返す:
 240 .TP 12n
 241 .B MM_OK
 242 .\"O Everything went smooth.
 243 全てがうまくいった。
 244 .TP
 245 .B MM_NOTOK
 246 .\"O Complete failure.
 247 完全に失敗した。
 248 .TP
 249 .B MM_NOMSG
 250 .\"O Error writing to
 251 .\"O .IR stderr .
 252 .I stderr
 253 に書き込むときにエラーが起こった。
 254 .TP
 255 .B MM_NOCON
 256 .\"O Error writing to the console.
 257 コンソールに書き込むときにエラーが起こった。
 258 .\"O .SH ENVIRONMENT
 259 .SH 環境変数
 260 .\"O The environment variable
 261 .\"O .B MSGVERB
 262 .\"O ("message verbosity") can be used to suppress parts of
 263 .\"O the output to
 264 .\"O .IR stderr .
 265 環境変数
 266 .B MSGVERB
 267 ("message verbosity") は
 268 .I stderr
 269 への出力の一部を抑制するのに使うことができる。
 270 .\"O (It does not influence output to the console.)
 271 (コンソールへの出力には影響しない。)
 272 .\"O When this variable is defined, is non-NULL, and is a colon-separated
 273 .\"O list of valid keywords, then only the parts of the message corresponding
 274 .\"O to these keywords is printed.
 275 この変数が定義されて、NULL でなく、
 276 コロンで区切られた有効なキーワードのリストである場合、
 277 キーワードに対応するメッセージの一部のみが表示される。
 278 .\"O Valid keywords are "label", "severity", "text", "action" and "tag".
 279 有効なキーワードは "label", "severity", "text", "action", "tag" である。
 280 .PP
 281 .\"O The environment variable
 282 .\"O .B SEV_LEVEL
 283 .\"O can be used to introduce new severity levels.
 284 環境変数
 285 .B SEV_LEVEL
 286 は新しい重大度レベルを導入するのに使用できる。
 287 .\"O By default, only the five severity levels described
 288 .\"O above are available.
 289 .\"O Any other numeric value would make
 290 .\"O .BR fmtmsg ()
 291 .\"O print nothing.
 292 デフォルトでは、上記の 5 つの重大度レベルのみが利用可能である。
 293 他の数値の場合、
 294 .BR fmtmsg ()
 295 は何も表示しない。
 296 .\"O If the user puts
 297 .\"O .B SEV_LEVEL
 298 .\"O with a format like
 299 .\"O .sp
 300 .\"O .RS
 301 .\"O SEV_LEVEL=[description[:description[:...]]]
 302 .\"O .RE
 303 .\"O .sp
 304 .\"O in the environment of the process before the first call to
 305 .\"O .BR fmtmsg (),
 306 .\"O where each description is of the form
 307 .\"O .sp
 308 .\"O .RS
 309 .\"O severity-keyword,level,printstring
 310 .\"O .RE
 311 .\"O .sp
 312 .\"O then
 313 .\"O .BR fmtmsg ()
 314 .\"O will also accept the indicated values for the level (in addition to
 315 .\"O the standard levels 0-4), and use the indicated printstring when
 316 .\"O such a level occurs.
 317 .BR fmtmsg ()
 318 を初めて呼び出す前に、ユーザが
 319 .B SEV_LEVEL
 320 を
 321 .sp
 322 .RS
 323 SEV_LEVEL=[description[:description[:...]]]
 324 .RE
 325 .sp
 326 のような形式でプロセスの環境に設定すると、
 327 .BR fmtmsg ()
 328 は (標準のレベル 0-4 に加えて) level に指定された値も受け付け、
 329 そのようなレベルの問題が発生すると指定された printstring を表示する。
 330 各 description は
 331 .sp
 332 .RS
 333 severity-keyword,level,printstring
 334 .RE
 335 .sp
 336 という形式である。
 337 .LP
 338 .\"O The severity-keyword part is not used by
 339 .\"O .BR fmtmsg ()
 340 .\"O but it has to be present.
 341 severity-keyword 部は
 342 .BR fmtmsg ()
 343 に使用されないが、存在しなければならない。
 344 .\"O The level part is a string representation of a number.
 345 level 部は数値を文字列で表したものである。
 346 .\"O The numeric value must be a number greater than 4.
 347 数値は 4 より大きい値でなければならない。
 348 .\"O This value must be used in the severity argument of
 349 .\"O .BR fmtmsg ()
 350 .\"O to select this class.
 351 .\"O It is not possible to overwrite
 352 .\"O any of the predefined classes.
 353 .\"O The printstring
 354 .\"O is the string printed when a message of this class is processed by
 355 .\"O .BR fmtmsg ().
 356 この値は
 357 .BR fmtmsg ()
 358 の severity 引き数で使用されなければならず、この重大度を選択する。
 359 前もって宣言された重大度を上書きすることはできない。
 360 printstring は、
 361 この重大度のメッセージが
 362 .BR fmtmsg ()
 363 によって生成された場合に表示される文字列である。
 364 .\"O .SH VERSIONS
 365 .SH バージョン
 366 .\"O .BR fmtmsg ()
 367 .\"O is provided in glibc since version 2.1.
 368 .BR fmtmsg ()
 369 は、バージョン 2.1 以降の glibc で提供されている。
 370 .\"O .SH "CONFORMING TO"
 371 .SH 準拠
 372 .\"O The functions
 373 .\"O .BR fmtmsg ()
 374 .\"O and
 375 .\"O .BR addseverity (3),
 376 .\"O and environment variables
 377 .\"O .B MSGVERB
 378 .\"O and
 379 .\"O .B SEV_LEVEL
 380 .\"O come from System V.
 381 関数
 382 .BR fmtmsg ()
 383 と
 384 .BR addseverity (3)
 385 と環境変数
 386 .B MSGVERB
 387 と
 388 .B SEV_LEVEL
 389 は System V に由来している。
 390 .\"O The function
 391 .\"O .BR fmtmsg ()
 392 .\"O and the environment variable
 393 .\"O .B MSGVERB
 394 .\"O are described in POSIX.1-2001.
 395 関数
 396 .BR fmtmsg ()
 397 と環境変数
 398 .B MSGVERB
 399 は POSIX.1-2001 に記述されている。
 400 .\"O .SH NOTES
 401 .SH 注意
 402 .\"O System V and UnixWare man pages tell us that these functions
 403 .\"O have been replaced by "pfmt() and addsev()" or by "pfmt(),
 404 .\"O vpfmt(), lfmt(), and vlfmt()", and will be removed later.
 405 System V と UnixWare の man ページには、
 406 「これらの関数は "pfmt() と addsev()"
 407 または "pfmt(), vpfmt(), lfmt(), vlfmt()" で置き換えられており、
 408 将来は削除される予定である」と書かれている。
 409 .\"O .SH EXAMPLE
 410 .SH 例
 411 .nf
 412 #include <stdio.h>
 413 #include <stdlib.h>
 414 #include <fmtmsg.h>
 415
 416 int
 417 main(void)
 418 {
 419     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 420     int err;
 421
 422     err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
 423                 "unknown mount option", "See mount(8).",
 424                 "util\-linux:mount:017");
 425     switch (err) {
 426     case MM_OK:
 427       break;
 428     case MM_NOTOK:
 429         printf("Nothing printed\en");
 430         break;
 431     case MM_NOMSG:
 432         printf("Nothing printed to stderr\en");
 433         break;
 434     case MM_NOCON:
 435         printf("No console output\en");
 436         break;
 437     default:
 438         printf("Unknown error from fmtmsg()\en");
 439     }
 440     exit(EXIT_SUCCESS);
 441 }
 442 .fi
 443 .PP
 444 .\"O The output should be:
 445 出力は
 446 .nf
 447
 448     util\-linux:mount: ERROR: unknown mount option
 449     TO FIX: See mount(8).  util\-linux:mount:017
 450
 451 .fi
 452 .\"O and after
 453 のようになり、
 454 .nf
 455
 456     MSGVERB=text:action; export MSGVERB
 457
 458 .fi
 459 .\"O the output becomes:
 460 を実行した後では
 461 .nf
 462
 463     unknown mount option
 464     TO FIX: See mount(8).
 465
 466 .fi
 467 となる。
 468 .\"O .SH "SEE ALSO"
 469 .SH 関連項目
 470 .BR addseverity (3),
 471 .BR perror (3)