名称

com_err, com_err_va, error_message, error_table_name, init_error_table, set_com_err_hook, reset_com_err_hook, add_to_error_table, initialize_error_table_r free_error_table, com_right — 共通エラー表示ライブラリ

ライブラリ

共通エラーライブラリ (libcom_err, -lcom_err)

書式

#include <stdio.h>
#include <stdarg.h>
#include <com_err.h>
#include "XXX_err.h"

typedef void (*errf)(const char *, long, const char *, ...);
void
com_err( const char *whoami, long code, const char *format, ...);

void
com_err_va( const char *whoami, long code, const char *format, ...);

const char *
error_message( long code);

const char *
error_table_name( int num);

int
init_error_table( const char **msgs, long base, int count);

errf
set_com_err_hook( errf func);

errf
reset_com_err_hook( );

void
add_to_error_table( struct et_list *new_table);

void
initialize_error_table_r( struct et_list **et_list, const char **msgs, int base, long count);

void
free_error_table( struct et_list *);

const char *
com_right( struct et_list *list, long, code");

解説

com_err ライブラリは、アプリケーションソフトウェアパッケージのためのエラーコードと記述を定義しアクセスするための共通のエラー報告メカニズムを提供しています。エラーの記述は、テーブルに定義され、エラーコードは、テーブルをインデックス付けするために使用されます。エラーテーブル、記述とエラーコードは、 compile_et(1) を使用して生成されます。

エラーテーブルは、ヘッダファイルに定義された、その初期化関数を呼び出すことによって、 com_err ライブラリで登録されます。初期化関数は、 initialize_<name>_error_table() として一般的に定義されます、ここで name は、エラーテーブルの名前です。

ライブラリのスレッドセーフなバージョンが必要とされるなら、 initialize_error_table_r() の内部的な呼び出しである initialize_<name>_error_table_r() が代わりに使用されます。

エラーコードを含むあらゆる変数は、 <name>_error_number と宣言されるべきです、ここで name は、エラーテーブルの名前です。

関数

次の関数が、アプリケーション開発者に利用可能です:

com_err( whoami, code, format, ...)

プログラム名に続いて、 code から生成されるエラーメッセージと printf(3) format (書式) 文字列とあらゆる続く引数を使用して生成される文字列を指定するべきである、 whoami 文字列からなる標準エラーにエラーメッセージを表示します。 format が NULL であるなら、書式化されたメッセージは、印刷 (表示) されません。引数 format は、省略されません。

com_err_va( whoami, code, format, va_list args)

このルーチンは、より高いレベルの可変長引数の関数 (可変個数の員数を受け付ける関数) によって使用される、 com_err() と等価な、インタフェースを提供します。

error_message( code)

code に結び付けられた文字列エラーメッセージを返します。 code が未知のエラーテーブルに結び付けられているなら、または code が既知のエラーテーブルに結び付けられているが、テーブルにないなら、形式 `Unknown code XXXX NN' の文字列が返されます、ここで、XXXX は、そのエラーコードによって暗示されるエラーテーブル番号で実行される圧縮を逆にすることによって生成されるエラーテーブル名で、NN は、その基本となる値からのオフセットです。

このルーチンは、必要なときに、使用できますが、その使用は、 com_err() が使用不可能にする状況で残されるべきです。

com_right() は、ちょうど com_err のようなエラー文字列を返しますが、スレッドセーフな方法です。

error_table_name( num)

マシン独立のエラーテーブル番号 num をエラーテーブル名に変換します。

init_error_table( msgs, base, count)

長さ count の msgs の文字列エラーメッセージの配列がある内部のエラーテーブルを初期化します。エラーコードは、 base から増加するように割り当てられます。この関数は、 compile_et(1) で生成されていないカスタムエラーテーブルがあるエラー報告メカニズムを使用するために役に立ちます。このルーチンは、必要なときに、使用できますが、その使用は、制限されるべきです。

initialize_error_table_r() は、 init_error_table() と同じ方法で et_list を初期化しますが、スレッドセーフな方法です。

set_com_err_hook( func)

com_err() の代わりに動的となるルーチン func を可能にするために com_err ライブラリにフック (hook) を提供します。 set_com_err_hook() が呼び出された後に、 com_err() への呼び出しは、新しいフックルーチンへの呼び出しへ変わります。この関数は、 syslog(3) を呼び出すルーチンを使用するデーモンで、またはダイアログボックスをポップアップするウィンドウシステムのアプリケーションで使用されることを目的としています。

reset_com_err_hook( )

set_com_err_hook() で設定されるフックをオフにします。

add_to_error_table( new_table)

内部のエラーテーブルに new_table のエラーテーブル、そのメッセージ文字列とエラーコードを追加します。

使用例

次は、 compile_et(1) で定義されたテーブルを使用する一例です:

 #include <stdio.h> 
 #include <stdarg.h> 
 #include <syslog.h> 
 
 #include "test_err.h" 
 
 void 
 hook(const char *whoami, long code, 
  const char *format, va_list args) 
 { 
  char buffer[BUFSIZ]; 
  static int initialized = 0; 
 
  if (!initialized) { 
   openlog(whoami, LOG_NOWAIT, LOG_DAEMON); 
   initialized = 1; 
  } 
  vsprintf(buffer, format, args); 
  syslog(LOG_ERR, "%s %s", error_message(code), buffer); 
 } 
 
 int 
 main(int argc, char *argv[]) 
 { 
  char *whoami = argv[0]; 
 
  initialize_test_error_table(); 
  com_err(whoami, TEST_INVAL, "before hook"); 
  set_com_err_hook(hook); 
  com_err(whoami, TEST_IO, "after hook"); 
  return (0); 
 }

関連項目

compile_et(1)