書式

int (*XSetErrorHandler(handler))()

      int (*handler)(Display *, XErrorEvent *)

XGetErrorText(display, code, buffer_return, length)

      Display *display;

      int code;

      char *buffer_return;

      int length;

char *XDisplayName(string)

      char *string;

int (*XSetIOErrorHandler(handler))()

      int (*handler)(Display *);

XGetErrorDatabaseText(display, name, message, default_string, buffer_return, length)

      Display *display;

      char *name, *message;

      char *default_string;

      char *buffer_return;

      int length;

引き数

buffer_return

エラー記述が返される。

code

エラー記述を得ようとするエラーコードを指定する。

default_string

データベースで none になっている場合のデフォルトのエラーメッセージを 指定する。

display

X サーバへの接続を指定する。

handler

プログラムで与えるエラーハンドラを指定する。

length

バッファのサイズを指定する。

message

エラーメッセージのタイプを指定する。

name

アプリケーションの名前を指定する。

string

文字列を指定する。

説明

Xlib は普通、エラーを受け取ったときに必ずプログラムが 与えたエラーハンドラを呼び出す。 ただし、 OpenFont, LookupColor, AllocNamedColor プロトコルリクエストからの BadName エラーや プロトコルリクエストからの BadFont エラーに対してはエラーハンドラは呼び出されない。 一般的にはこれらのエラーは、手続きインタフェースを通してプログラムに返 される。 この状態は致命的ではないと考えられるので、エラーハンドラから復帰するこ とは認められる。 この返り値は無視される。 しかし、エラーハンドラはディスプレイに対してプロトコルリクエストを生成 したり入力イベントを求めたりする関数を(直接的にも間接的にも)呼び出して はならない。 このような場合、直前のエラーハンドラが返される。

関数 XGetErrorText は、指定したエラーコードを説明する文字列(NULL で終端する)を指定した バッファにコピーする。 返される文字列は、現在のロケールのエンコーディングになっている。 Xlib の拡張により独自のエラーコードやエラー文字列が定義されるかもしれ ないので、エラーの説明を得るためにはこの関数を使うことが推奨されている。

関数 XDisplayName は XOpenDisplay が使おうとするディスプレイの名前を返す。 NULL 文字列が指定された場合には XDisplayName はディスプレイについての環境変数を調べ、 XOpenDisplay が使おうとするディスプレイの名前を返す。 この関数を使うことにより、最初の接続の試みが失敗した時に、プログラムが どのディスプレイを開こうとしていたのかをユーザに知らせることが容易になる。

XSetIOErrorHandler は致命的な I/O エラーのハンドラを設定する。 システムコールレベルのエラー(例えば、サーバへの接続が失われた)が発生し た場合に、Xlib はユーザが与えたエラーハンドラを呼び出す。 これは致命的な状態と考えられるので、呼び出されたルーチンからは復帰すべ きではない。 I/O エラーハンドラから復帰させても、クライアントプロセスは終了する。

直前のエラーハンドラが返される点に注意すること。

関数 XGetErrorDatabaseText は、エラーメッセージのデータベースからメッセージ(あるいはデフォルトの メッセージ)を返す。 このメッセージは NULL で終端する。 Xlib はこの関数を内部的に使ってエラーメッセージを見つける。 引き数 default_string 内のテキストは現在のロケールのエンコーディングであ り、引き数 buffer_return に格納されるテキストも現在のロケールの エンコーディングであることが前提となる。

引き数 name は普通はアプリケーションの名前にすべきである。 引き数 message では必要なメッセージのタイプを示すべきである。 name と message のエンコーディングがホストポータブル文字エンコーディング でない場合、実行結果は実装依存である。 Xlib は予め定義された 3 つの ``アプリケーション名'' を使って エラーを報告する。 これらの名前においては、大文字と小文字は区別される。

XProtoError

プロトコルエラー番号は、引き数 message に対する文字列として使用される。

XlibMessage

これらは、ライブラリが内部的に使うメッセージ文字列である。

XRequest

コアプロトコルリクエストの場合は、 メジャーリクエストプロトコル番号が引き数 message に対して使われる。 拡張リクエストの場合は、拡張名( InitExtension で与えられる )、ピリオド(.)、 マイナーリクエストプロトコル番号の 3 つを並べたものが 引き数 message に対して使用される。 エラーデータベースで文字列が見つからない場合には、default_string が引き数 buffer に返される。