XSetIOErrorHandler(3) デフォルトのエラーハンドラ

Other Alias

XSetErrorHandler, XGetErrorText, XDisplayName, XGetErrorDatabaseText

書式

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 の拡張により独自のエラーコードやエラー文字列が定義されるかもしれ ないので、エラーの説明を得るためにはこの関数を使うことが推奨されている。

関数 XDisplayNameXOpenDisplay が使おうとするディスプレイの名前を返す。 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 に返される。