Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all bug

名前

       fmtmsg - 整形されたエラーメッセージを表示する

書式

       #include <fmtmsg.h>

       int fmtmsg(long classification, const char *label,
                  int severity, const char *text,
                  const char *action, const char *tag);

説明

       この関数は、引数で記述されたメッセージを、 classification 引数で指定されたデバイス上に表示
       する。 stderr に書き出されるメッセージのフォーマットは、 MSGVERB 環境変数に依存する。

       label 引数はメッセージの発生源を識別する。 この文字列はコロンで区切られた 2 つの部分から構
       成されていなければならない。  1  つ目の部分は 10 文字以内でなければならず、 2 つ目の部分は
       14 文字以内でなければならない。

       text 引数にはエラー条件を記述する。

       action  引数にはエラーから回復するために利用可能なステップを記述する。  これが表示される場
       合、"TO FIX: " が前に付く。

       tag    引数はより多くの情報を見つけるためのオンラインドキュメントへの参照である。   これは
       label 値とユニークな識別番号を含んでいるべきである。

   ダミー引数
       各引数にはダミーの値を入れることができる。 ダミーの classificationMM_NULLMC (0L)  は出
       力を何も指定しない。そのため何も表示されない。  ダミーの  severityNO_SEV (0) は重大度
       (severity)   が与えられていないことを表す。   値   MM_NULLLBL,   MM_NULLTXT,   MM_NULLACT,
       MM_NULLTAG((char *) 0) と空文字列の別名であり、 MM_NULLSEVNO_SEV の別名である。

   classification 引数
       classification 引数は 4 種類の情報を記述する値の和である。

       最初の値は出力チャンネルを定義する。

       MM_PRINT    stderr に出力する。

       MM_CONSOLE  システムコンソールに出力する。

       MM_PRINT | MM_CONSOLE
                   両方に出力する。

       2 番目の値はエラーの発生源である:

       MM_HARD     ハードウェアエラーが起こった。

       MM_FIRM     ファームウェアエラーが起こった。

       MM_SOFT     ソフトウェアエラーが起こった。

       3 番目の値は問題の検知を行ったものをエンコードする:

       MM_APPL     アプリケーションによって検知された。

       MM_UTIL     ユーティリティによって検知された。

       MM_OPSYS    オペレーティングシステムによって検知された。

       4 番目の値は問題の重大度を表す:

       MM_RECOVER  回復可能なエラーである。

       MM_NRECOV   回復不可能なエラーである。

   severity 引数
       severity 引数は以下の 1 つの値をとることができる。

       MM_NOSEV    重大度は表示されない。

       MM_HALT     この値は HALT として表示される。

       MM_ERROR    この値は ERROR として表示される。

       MM_WARNING  この値は WARNING として表示される。

       MM_INFO     この値は INFO として表示される。

       数値の場合は  0  から  4  である。 addseverity(3)  または環境変数 SEV_LEVEL を使うことによ
       り、表示するレベルと文字列を更に追加できる。

返り値

       関数は 4 つの値を返す:

       MM_OK       全てがうまくいった。

       MM_NOTOK    完全に失敗した。

       MM_NOMSG    stderr に書き込むときにエラーが起こった。

       MM_NOCON    コンソールに書き込むときにエラーが起こった。

環境変数

       環境変数 MSGVERB ("message verbosity") は stderr  への出力の一部を抑制するのに使うことがで
       きる。  (コンソールへの出力には影響しない。)  この変数が定義されて、NULL でなく、 コロンで
       区切られた有効なキーワードのリストである場合、  キーワードに対応するメッセージの一部のみが
       表示される。 有効なキーワードは "label", "severity", "text", "action", "tag" である。

       環境変数 SEV_LEVEL は新しい重大度レベルを導入するのに使用できる。 デフォルトでは、上記の 5
       つの重大度レベルのみが利用可能である。   他の数値の場合、   fmtmsg()    は何も表示しない。
       fmtmsg()  を初めて呼び出す前に、ユーザーが SEV_LEVEL を

              SEV_LEVEL=[description[:description[:...]]]

       のような形式でプロセスの環境に設定すると、  fmtmsg()  は (標準のレベル 0–4 に加えて) level
       に指定された値も受け付け、 そのようなレベルの問題が発生すると指定された printstring を表示
       する。 各 description は

              severity-keyword,level,printstring

       という形式である。

       severity-keyword  部は fmtmsg()  に使用されないが、存在しなければならない。 level 部は数値
       を文字列で表したものである。 数値は 4 より大きい値でなければならない。  この値は  fmtmsg()
       の  severity 引数で使用されなければならず、この重大度を選択する。 前もって宣言された重大度
       を上書きすることはできない。 printstring は、 この重大度のメッセージが fmtmsg()   によって
       生成された場合に表示される文字列である。

バージョン

       fmtmsg()  は、バージョン 2.1 以降の glibc で提供されている。

属性

       この節で使用されている用語の説明については、 attributes(7) を参照。

       ┌─────────────────┬───────────────┬─────────────────────────┐
       │インターフェース属性                      │
       ├─────────────────┼───────────────┼─────────────────────────┤
       │fmtmsg()         │ Thread safety │ glibc >= 2.16: MT-Safe  │
       │                 │               │ glibc < 2.16: MT-Unsafe │
       └─────────────────┴───────────────┴─────────────────────────┘
       glibc  2.16  より前のバージョンでは、 fmtmsg() 関数は、 保護されていない静的な変数を使うた
       め、 スレッドセーフではない。

       glibc 2.16 以降では、 fmtmsg() 関数はロックを使って静的な変数を保護しており、 スレッドセー
       フである。

準拠

       関数 fmtmsg()  と addseverity(3)  と環境変数 MSGVERBSEV_LEVEL は System V に由来してい
       る。

       関数 fmtmsg() と環境変数 MSGVERB は POSIX.1-2001 と POSIX.1-2008 に規定されている。

注意

       System V と UnixWare の man ページには、  「これらの関数は  "pfmt()  と  addsev()"  または
       "pfmt(), vpfmt(), lfmt(), vlfmt()" で置き換えられており、 将来は削除される予定である」と書
       かれている。

       #include <stdio.h>
       #include <stdlib.h>
       #include <fmtmsg.h>

       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\n");
               break;
           case MM_NOMSG:
               printf("Nothing printed to stderr\n");
               break;
           case MM_NOCON:
               printf("No console output\n");
               break;
           default:
               printf("Unknown error from fmtmsg()\n");
           }
           exit(EXIT_SUCCESS);
       }

       出力は

           util-linux:mount: ERROR: unknown mount option
           TO FIX: See mount(8).  util-linux:mount:017

       のようになり、

           MSGVERB=text:action; export MSGVERB

       を実行すると、次のようになる。

           unknown mount option
           TO FIX: See mount(8).

関連項目

       addseverity(3), perror(3)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
       説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。

                                            2020-06-09                                  FMTMSG(3)