EB ライブラリ

エラー処理

EB ライブラリの関数の呼び出しは、常に成功するとは限りません。たとえば、EB_Book オブジェクトを書籍に結びつける関数 eb_bind() には、引数として書籍のトップディレクトリを渡しますが、存在しないディレクトリを指定した場合、処理は失敗に終わります。

一般にこうした事象は、ユーザが誤ったパスを指定したときに起こりますが、メモリ不足のように、ユーザのミスが原因ではない失敗も起こりえます。

本章では、関数の呼び出しが失敗した場合の処理について説明します。

エラーコードとエラーメッセージ

EB ライブラリの関数の多くは、戻り値として EB_Error_Code 型の値を返します。処理が成功したときに返す値は EB_SUCCESS ですが、失敗したときはエラーの原因に応じて様々な値を返します。このため、EB ライブラリでは次のような EB_SUCCESS との比較処理がよく行われます。

EB_Error_Code error_code;

error_code = eb_bind(&book, "/mnt/cdrom");
if (error_code != EB_SUCCESS) {
    printf("eb_bind() failed\n");
    return;
}

エラーコードの値は、関数 eb_error_message() によってエラーメッセージに変換することもできます。こうすることで、エラーの原因をアプリケーションプログラムのユーザにもう少し分かりやすく伝えることができます。

error_code = eb_bind(&book, "/mnt/cdrom");
if (error_code != EB_SUCCESS) {
    printf("eb_bind() failed, %s\n",
        eb_error_message(error_code));
    return;
}

error_code が EB_ERR_TOO_LONG_FILENAME にセットされていれば、次のようなエラーメッセージが出力されます。

too long filename

あるいは、次のように日本語のメッセージかも知れません。

ファイル名が長すぎます

メッセージの国際化機能 (NLS) を無効にして EB ライブラリをコンパイルした場合は、常に英語のメッセージが返ります。有効にした場合は、ロケールの設定によってどちらの言語のメッセージが返るかが決まります。

本書ではプログラムを簡潔にするために、エラー処理は最低限しか行っていません。けれども一般のアプリケーションプログラムでは、関数の呼び出しが成功したかどうかを常にチェックし、処理が失敗した際はエラーメッセージを出力して、ユーザにエラーの原因を伝えるのが望ましいといえます。

エラーに対する寛容さ

EB_Book オブジェクトは、状態に関するパラメタをいくつか持っています。オブジェクトが CD-ROM 書籍に結び付いているかどうかも、こうしたパラメタのうちの一つです。

引数に EB_Book オブジェクトへのポインタを取る関数には、あらかじめオブジェクトの特定のパラメタがセットされていることを前提としているものもあります。たとえば、eb_path() は、オブジェクトが書籍に結び付いていることを前提としています。では、もしも書籍に結び付いていないオブジェクトを eb_path() に渡したらどうなるでしょうか。

EB_Book book;
EB_Error_Code error_code;
char path[EB_MAX_PATH_LENGTH + 1];

eb_initialize_library();
eb_initialize(&book);
error_code = eb_path(&book, path);    /* どうなる? */

この場合、eb_path() は EB_ERR_UNBOUND_BOOK を返します。 EB ライブラリの関数は、必要なパラメタがセットされていないオブジェクトを検知して拒絶します。

しかしながら、参照マニュアルで明示されている場合を除いて、EB ライブラリの関数は、与えられたポインタが NULL かどうかまでは調べません。次のようなことをすると、プログラムを異常終了させてしまいます。

eb_bind(NULL, "/mnt/cdrom");    /* 異常終了! */
eb_bind(&book, NULL);           /* これも異常終了! */

データ型の詳細

この節で説明しているデータ型を使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/error.h>

`EB_Error_Code` 型

データ型 EB_Error_Code は、EB ライブラリのエラーコードを表します。この型は符合付き整数型の別名として定義されていますので、2 つのコードを 2 項演算子 == と != で一致比較することができます。

EB ライブラリでは、全部で EB_NUMBER_OF_ERRORS 個のフックコードを定義しています。エラーコードの一覧については、次の節 (「エラーコードの一覧」を参照のこと) を参照して下さい。

エラーコードの一覧

この節で説明しているエラーコードを使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/error.h>

定数 `EB_ERR_MEMORY_EXHAUSTED`

EB ライブラリが malloc() を呼び出したが、NULL が返ってきた。

定数 `EB_ERR_TOO_LONG_FILE_NAME`

与えられた書籍のパス名が長すぎる。

定数 `EB_ERR_BAD_DIR_NAME`

ディレクトリ名が不正である。 (EB ライブラリの内部処理用なので、このエラーコードがアプリケーションプログラムに返ることはありません。)

定数 `EB_ERR_FAIL_READ_CATAPP`

EB ライブラリが、appendix のカタログファイルを読み込むことに失敗した。

定数 `EB_ERR_FAIL_READ_APP`

EB ライブラリが、appendix のメインファイルを読み込むことに失敗した。

定数 `EB_ERR_UNEXP_CAT`

EB ライブラリが、書籍のカタログファイル内で、期待とは異なるデータ列を見つけた。

定数 `EB_ERR_UNEXP_CATAPP`

EB ライブラリが、appendix のカタログファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNEXP_APP`

EB ライブラリが、appendix のメインファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNEXP_BINARY`

EB ライブラリが、書籍のバイナリデータファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNBOUND_BOOK`

呼び出された EB ライブラリの関数は、書籍に結び付けられた EB_Book オブジェクトを引数にとるが、与えられたオブジェクトは書籍に結び付けられていなかった。

定数 `EB_ERR_UNBOUND_APP`

呼び出された EB ライブラリの関数は、appendix に結び付けられた EB_Appendix オブジェクトを引数にとるが、与えられたオブジェクトは appendix に結び付けられていなかった。

定数 `EB_ERR_NO_CUR_SUB`

呼び出された関数は、副本が選択されている EB_Book オブジェクトを引数としてとるが、与えられたオブジェクトでは選択されていなかった。

定数 `EB_ERR_NO_CUR_APPSUB`

呼び出された関数は、副本が選択されている EB_Appendix オブジェクトを引数にとるが、与えられたオブジェクトでは選択されていなかった。

定数 `EB_ERR_NO_CUR_FONT`

呼び出された関数は、外字が選択されている EB_Book オブジェクトを引数にとるが、与えられたオブジェクトでは選択されていなかった。

定数 `EB_ERR_NO_CUR_BINARY`

呼び出された関数は、バイナリデータの読み込み要求をセットしている EB_Book オブジェクトを引数にとるが、与えられたオブジェクトではセットされていなかった。

定数 `EB_ERR_NO_SUCH_SUB`

EB_Book オブジェクトと副本コードが関数に与えられたが、 EB_Book オブジェクトに結び付けられている書籍は、その副本コードに一致する副本を持っていない。

定数 `EB_ERR_NO_SUCH_APPSUB`

EB_Appendix オブジェクトと副本コードが関数に与えられたが、 EB_Appendix オブジェクトに結び付けられている appendix は、その副本コードに一致する副本を持っていない。

定数 `EB_ERR_NO_SUCH_FONT`

EB_Book オブジェクトと外字の縦のサイズが関数に与えられたが、 EB_Book オブジェクトに結びつけられていた書籍で選択中の副本は、そのサイズの外字を持っていない。

定数 `EB_ERR_NO_SUCH_CHAR_BMP`

EB_Book オブジェクトと文字番号が関数に与えられたが、 EB_Book オブジェクトに結び付けられていた書籍で選択中の副本は、その番号の外字のビットマップデータを持っていない。

定数 `EB_ERR_NO_SUCH_CHAR_TEXT`

EB_Appendix オブジェクトと文字番号が関数に与えられたが、 EB_Appendix オブジェクトに結び付けられている appendix で選択中の副本は、その番号の外字の代替文字列を持っていない。

定数 `EB_ERR_DIFF_CONTENT`

アプリケーションプログラムからテキストデータの取得を要求されたが、指定されたテキストデータの種類が、前回リクエストされたときと一致していない。

定数 `EB_ERR_NO_PREV_SEARCH`

eb_hit_list() が呼び出されたが、アプリケーションプログラムから前もって検索のリクエストがなされていない。

定数 `EB_ERR_NO_SUCH_MULTI_ID`

EB_Book オブジェクトと複合検索コードが関数に渡されたが、結び付けられた書籍で選択中の副本は、そのコードに一致する複合検索を持っていない。

定数 `EB_ERR_NO_SUCH_ENTRY_ID`

EB_Book オブジェクトと複合検索エントリコードが関数に渡されたが、結び付けられた書籍で選択中の副本は、そのエントリコードに一致する複合検索エントリを持っていない。

定数 `EB_ERR_TOO_MANY_WORDS`

アプリケーションプログラムから条件検索もしくは複合検索の検索をリクエストされたが、検索語の個数が多すぎる。

定数 `EB_ERR_NO_WORD`

アプリケーションプログラムから条件検索もしくは複合検索の検索をリクエストされたが、検索語がすべて空である。

定数 `EB_ERR_NO_CANDIDATES`

eb_multi_entry_candidates() が呼び出されたが、指定された複合検索エントリは、検索語の候補一覧データを持っていない。

定数 `EB_ERR_END_OF_CONTENT`

eb_forward_text() あるいは eb_backward_text() で本文の頭出しを行おうとしたが、すでに本文の末尾ないし先頭に達していて、それ以上先に進むことができなかった。

定数 `EB_ERR_NO_PREV_SEEK`

あらかじめ eb_seek_text() でシークを行っていない状態で、テキストデータの読み込みや頭出しを行おうとした。

定数 `EB_ERR_EBNET_FAIL_CONNECT`

遠隔ホストへのアクセスを試みたが、サーバ (EBNETD) に接続できなかった。

定数 `EB_ERR_EBNET_SERVER_BUSY`

遠隔ホストへの接続を行ったが、書籍にアクセスしているクライアントの数がすでに上限に達しているため、その書籍を利用できなかった。

定数 `EB_ERR_EBNET_NO_PERMISSION`

遠隔ホストへの接続を行ったが、その書籍への利用権限がないため、サーバからアクセスを拒否された。

定数 `EB_ERR_UNBOUND_BOOKLIST`

呼び出された EB ライブラリの関数は、遠隔ホストに結び付けられた EB_BookList オブジェクトを引数にとるが、与えられたオブジェクトは遠隔ホストに結び付けられていなかった。

定数 `EB_ERR_NO_SUCH_BOOK`

EB_BookList オブジェクトと書籍の要素番号を関数に渡されたが、 EB_BookList に結び付けられた遠隔ホスト上には、その要素番号に該当する書籍は存在しない。

関数の詳細

この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで下さい。

#include <eb/error.h>

`const char *eb_error_string (EB_Error_Code error_code)`

関数 eb_error_string() は、エラーコード error_code を文字列に変換したものを返します。文字列の文字コードは、ASCII になります。たとえば、エラーコード値 EB_SUCCESS を渡すと文字列 "EB_SUCCESS" を返します。未知のエラーコードを渡したときは、"EB_ERR_UNKNOWN" を返します。

`const char *eb_error_message (EB_Error_Code error_code)`

関数 eb_error_message() は、エラーコード error_code に対応したメッセージを文字列にして返します。関数の返すメッセージは、英語か日本語になります。

国際化機能を有効にして EB ライブラリをコンパイルしていない場合は、常に英語のメッセージを返します。このときのメッセージの文字コードは、ASCII になります。

メッセージの国際化機能 (NLS) を有効にして EB ライブラリをコンパイルした場合は、ロケールの設定に応じてどちらの言語のメッセージを返すのかが決まります。また、GNU gettext バージョン 0.36 以降では iconv() と連携することにより、メッセージの文字コードもロケールに応じて変化します。 gettext が iconv() との連携を行わなければ、英語のメッセージは ASCII、日本語のメッセージは日本語 EUC になります。この関数の呼び出しによって、gettext のテキストドメインの設定は変化しません。

未知のエラーコードを渡したときに返すメッセージは、英語では "unknown error"、日本語では "未知のエラーです" になります。

[前へ] [次へ] [目次]