ERROR(3)

名前
error, error_at_line, error_message_count, error_one_per_line, error_print_progname - glibc のエラー書き出し関数

書式
#include <error.h>

void error(int status, int errnum, const char *format, ...);

void error_at_line(int status, int errnum, const char *filename,
                   unsigned int linenum, const char *format, ...);

extern unsigned int error_message_count;

extern int error_one_per_line;

extern void (*error_print_progname) (void);

説明
error() は汎用的なエラー出力関数である。 この関数は標準出力 (stdout) をフラッシュしてから、情報を標準エラー出力 (stderr) に出力する。 出力される情報は、プログラム名、コロン、スペース、 printf(3) 形式の フォーマット文字列 format で指定されたメッセージである。 errnum が 0 以外の場合、 2 つ目のコロンとスペースの後に strerror(errnum) で指定された文字列も出力される。 format で必要な引数は、引数リストの format の後ろに続けて指定する必要がある。出力は改行文字で終端される。

error() で出力されるプログラム名は、大域変数 program_invocation_name(3) の値である。 program_invocation_name の初期値は main() の argv[0] の値と等しい。この変数の値は変更可能であり、変更すると error() の出力が変わる。

status が 0 以外の場合、 error() は exit(3) を呼び出して、指定された終了ステータスでプログラムを終了させる。

error_at_line() 関数は、引数 filename と linenum が追加されている以外は error() と同じである。 生成される出力は error() と同様だが、プログラム名の後に コロン、 filename の値、コロン、 linenum の値が出力される点が異なる。

プリプロセッサの値 __LINE__ と __FILE__ は、 error_at_line() を呼び出すときに役に立つが、その他のプリプロセッサの値も使うことができる。例えば、これらの引数で入力ファイルにおける位置を参照することもできる。

大域変数 error_one_per_line が 0 以外に設定されている場合、 filename と linenum の値が両方とも等しい一連の error_at_line() の呼び出しは、 1 つの (最初の) メッセージの出力にまとめられる。

大域変数 error_message_count は、 error() と error_at_line() で出力されたメッセージの数を表す。

大域変数 error_print_progname に 関数のアドレスが割り当てられている場合 (つまり NULL ではない場合)、 メッセージの前にプログラム名とコロンを書き出すのではなく、この関数を呼び出す。この関数は、適切な文字列を標準エラー出力 (stderr) に書き出さなければならない。

属性
この節で使用されている用語の説明については、 attributes(7) を参照。
インターフェース | 属性 | 値
error() | Thread safety | MT-Safe locale
error_at_line() | Thread safety | MT-Unsafe race: error_at_line/error_one_per_line locale

内部変数 error_one_per_line に (同期の仕組みなしで) アクセスが行われる (ただし、この変数は一度使用された int なので、十分安全であろう)。 error_one_per_line が 0 以外に設定されている場合、最後に表示したファイル名と行番号を保持するのに使用される (ユーザーに公開されない) 内部静的変数にアクセスが行われ、同期なしで変更される。この変更は、アトミックではなく、キャンセルが無効化される前にも発生する。そのため、これら 2 つの変数のうち 1 つだけが変更された後でも割り込まれることがある。それ以外は、 error_at_line() は error とほぼ同じである。

準拠
これらの関数と変数は GNU による拡張であり、 移植性を考えたプログラムでは使用すべきではない。

関連項目
err(3), errno(3), exit(3), perror(3), program_invocation_name(3), strerror(3)

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