nis_db(3N)

名称

nis_db, db_initialize, db_create_table, db_destroy_table, db_first_entry, db_next_entry, db_reset_next_entry, db_list_entries, db_remove_entry, db_add_entry, db_table_exists, db_unload_table, db_checkpoint, db_standby, db_free_result ― NIS+ データベースアクセス関数

構文

cc [ flag... ] file... -lnisdb -lnsl [ library... ]

#include <rpcsvc/nis.h>
#include <rpcsvc/nis_db.h>

bool db_initialize(const char *dictionary_pathname);

db_status db_create_table(const char *table_name,
const table_obj *table);

db_status db_destroy_table(const char *table_name);

db_result *db_first_entry(const char *table_name,
const int numattrs,
const nis_attr *attrs);

db_result *db_next_entry(const char *table_name,
const db_next_desc *next_handle);

db_result *db_reset_next_entry(const char *table_name,
const db_next_desc *next_handle);

db_result *db_list_entries(const char *table_name,
const int numattrs,
const nis_attr *attrs);

db_result *db_remove_entry(const char *table_name,
const int numattrs,
const nis_attr *attrs);

db_result *db_add_entry(const char *table_name,
const int numattrs,
const nis_attr *attrs,
const entry_obj *entry);

db_status db_table_exists(const char *table_name);

db_status db_unload_table(const char *table_name);

db_status db_checkpoint(const char *table_name);

db_status db_standby(const char *table_name );

void db_free_result(db_result *);

説明

これらの関数は、NIS+ サーバーと基底のデータベース間のインタフェースを記述します。これらは共用ライブラリ /usr/lib/libnisdb.so に定義されています。

インタフェースは完全なリレーショナルデータベースを簡潔なサブセットにしたもので、NIS+ サーバーデーモンが必要とする項目だけを提供します。データベースを置き換える場合は、インタフェースルーチンを確実に一致させるようにしなければなりません。また、渡されるオブジェクトが、使用中のデータベースの内部的な制限を超えていないことを確認するのはデータベースの責任です。

データベースのパフォーマンスがサーバーのパフォーマンスに直接影響します。 NIS+ で提供されている省略時の情報ベースは SSM (Structured Storage Manager) です。これは NIS+ 用に調整されたメモリベースのデータベースです。

NIS+ クライアントがこれらのルーチンを呼び出してはなりません。 NIS+ クライアントは、 nis_tables(3N) に説明されている NIS+ テーブルの API を使用します。

ルーチンは <rpcsvc/nis.h> に定義されている table_obj、entry_obj 、および nis_attr の各構造体だけを使用します。NIS+ ディレクトリ自体がサービスデーモンによってテーブルに保存されます。このテーブルには、オブジェクトの名前が入った検索可能なカラムと、バイナリの XDR データが入った検索不可能なカラムがあります。 NIS+ サーバーはネーム空間のディレクトリ参照要求をテーブル検索に変換します。このような要求に応えて検索するテーブルには、目的のディレクトリ名と同じ名前が入っています。

DB アクセスルーチンで戻される構造体の定義は、以下の通りです。

enum db_status {DB_SUCCESS, DB_NOTFOUND, DB_NOTUNIQUE, DB_BADTABLE,
    DB_BADQUERY, DB_BADOBJECT, DB_MEMORY_LIMIT, DB_STORAGE_LIMIT,
    DB_INTERNAL_ERROR };
struct db_result {
    db_status       status;                 /* Result status */
    db_next_desc    nextinfo;               /* descriptor */
    struct {
                u_int       objects_len;
                entry_obj   *objects_val;
     } objects;            /* A variable list of objects */
     long    ticks;        /* execution time in microseconds */
};

NIS+ オブジェクトについての詳細は、 nis_objects(3N) を参照してください。

db_next_entry() と db_reset_next_entry() のオペークハンドルとして構造体 db_next_desc を使用する必要があります。

db_first_entry で使用されている nis_attr 構造体と、その他の関連する関数の定義は以下の通りです。

struct nis_attr {
    char    *zattr_ndx;
    struct {
                 u_int   zattr_val_len;
                 char    *zattr_val_val;
     } zattr_val;
};

zattr_ndx は属性の名前です。 zattr_val_len は、属性 zattr_val_val の値です。

db_result では、 status 変数に戻された結果が DB_SUCCESS であるときに限って、 objects 配列の中にオブジェクトが入ります。構造体を作成するためのメモリが不十分な場合は、 db_result 構造体を指すポインタではなく、ヌルポインタが戻されます。

データベースとの対話に先だって db_initialize() が呼び出されます。この関数は、データベースのカタログ情報が入ったファイルまたはカタログ情報を入れるファイルのパス名を引き数として受け付けます。

db_create_table() は、指定されたテーブル名とテーブルオブジェクトを使用して新しいテーブルを作成します。テーブルを正しく作成したときは TRUE が戻り、作成できなかったときは FALSE が戻ります。

db_destroy_table() は、指定された名前のテーブルを消去します。消去が正しく行われたときは TRUE が戻り、正しく行われなかったときは FALSE が戻ります。

db_first_entry() は、指定されたテーブルの中で、指定された属性を満たす最初のエントリのコピーを戻します。属性を指定していないと、テーブルの先頭のエントリが戻されます。 attrs は nis_attr 構造体の配列で、要素の数は numattrs です。戻される構造体 db_result には、 db_next_entry() または db_reset_next_entry() の引き数として使用される構造体 db_next_desc が入っています。 db_next_desc はオペークハンドルとしてのみ使用します。 db_free_result() を使用すると、戻された db_result 構造体を解放することができます。

db_next_entry() は、 next_handle で指示された次のエントリのコピーを戻します。最初に db_first_entry() を呼び出し、続いて一連の db_next_entry() を呼び出すことによって、テーブル全体のエントリや、 db_first_entry() に指定した属性を満たすエントリを得ることができます。 db_free_result() を使用すると、戻された db_result 構造体を解放することができます。

db_reset_next_entry() は、 next_handle で指示されているように db_first_entry()/db_next_entry() シーケンスを終了し、このシーケンスを維持するためのすべてのリソースを解放します。 db_reset_next_entry() を呼び出した後で、同じ next_handle を使用して db_next_entry() を呼び出しても、正しく処理されず DB_BADQUERY が戻されます。 db_free_result() を使用すると、戻された db_result 構造体を解放することができます。

db_list_entries() は、指定された属性を満たすエントリのコピーを戻します。 db_free_result() を使用すると、戻された db_result 構造体を解放することができます。 attrs は nis_attr 構造体の配列で、要素数は numattrs です。

db_remove_entry() は、指定された属性を満たすエントリをすべて削除します。 db_free_result() を使用すると、戻された db_result 構造体を解放することができます。 attrs は nis_attr 構造体の配列で、要素数は numattrs です。

db_add_entry() は、指定されたオブジェクトのコピーを指定されたテーブルに追加し、指定された属性が指示するオブジェクトを置き換えます。属性が複数のオブジェクトを示す場合は、 DB_NOTUNIQUE が戻されます。属性でオブジェクトが指示されていない場合は、単にオブジェクトが追加されます。 attrs は nis_attr 構造体の配列で、要素数は numattrs です。 db_free_result() を使用すると、戻された db_result 構造体を解放することができます。

db_table_exists() を使用すると、NIS+ サービスはテーブルがあるかどうかを効率的に検出できるようになります。この関数を使用すると、クライアントに対する応答時間が増え、サーバーの負荷が少なくなります。

サービスは db_unload_table() を使用して、現在使用されていないテーブルのアンロードやアクティブ解除を行います。サービスはテーブルのアクセス状況を内部的に記録しておき、一定期間アクセスされていないテーブルをアンロードします。あまりアクセスされていないテーブルをアンロードすることによって、サービスはシステムリソースを最少に抑え、効率的に操作できるようにします。

db_checkpoint() は、さらに効率的になるようテーブルの内容を編成し直します。データベースの種類に応じてチェックポイントの意味が違っていることがあります。チェックポイントがテーブルの論理的な内容に影響を及ぼすことはなく、チェックポイント後であっても、操作と照会は以前と同じ結果となるはずです。例えば、ログベースのシステムでは、チェックポイントは、前回のチェックポイント以降に蓄積した更新のログエントリをテーブルに組み込むことを意味します。

db_free_result() は、このマンページに掲載している db_result 構造体を戻す各種関数で割り当てられたスペースを解放します。

db_standby() は、データベースマネージャの通知呼び出しです。この呼び出しは、アクティビティの速度が低下したときに、ファイル記述子などの不要なリソースを解放するようデータベースに通知します。

マルチスレッドの使用法

Thread Safe:		No
Cancel Safe:		No
Fork Safe:		No
Async-cancel Safe:
		No
Async-signal Safe:
		No

これらの関数は、マルチスレッド環境で支障なく呼び出すことはできません。

プログラミング

このライブラリの大半のルーチンは NIS+ 名 を使用して、ユーザーが希望するオブジェクトを識別します。 1 つのサーバーはいくつものネーム空間に対して機能し、ドメイン名を比較することによって要求されたオブジェクトを区別するので、名前は、データベースに渡される前に標準形にしておく必要があります。

診断

`DB_SUCCESS`		照会または操作が正しく終了し、ステータスが戻されています。
`DB_NOTFOUND`		名前、または引き数に指定されているエントリがありません。
`DB_NOTUNIQUE`		テーブルからエントリを削除しようとしましたが、指定がユニークではありません。
`DB_BADQUERY`		データベースにサブミットされた照会が無効です (例えば、存在していないフィールドを指定しているなど)。
`DB_BADTABLE`		テーブルが破壊されています。
`DB_BADOBJECT`		オブジェクトのフィールドが追加対象のテーブルのフィールドと合っていません。
`DB_MEMORY_LIMIT`		メモリ不足のために、要求された操作を完了できません。
`DB_STORAGE_LIMIT`
		ファイルの記憶領域不足のために、要求された操作を完了できません。
`DB_INTERNAL_ERROR`
		要求された操作の実行途中で内部エラーが検出されました (プログラミングエラーまたは回復不能な例外)。

警告

HP-UX 11i Version 2 は、NIS+ がサポートされる最後の HP-UX リリースです。

NIS+ の代わりに LDAP を推奨します。 HP は、LDAP に基づく業界標準のネームサービスを完全にサポートします。

参照

rpc.nisd(1M), nis_objects(3N), nisfiles(4)

nis_db(3N)

テクニカルドキュメント

≫ 目次

≫ 索引

名称

構文

説明

マルチスレッドの使用法

プログラミング

診断

警告

参照

nis_db(3N)

テクニカル ドキュメント

≫ 目次

≫ 索引

名称

構文

説明

マルチスレッドの使用法

プログラミング

診断

警告

参照

テクニカルドキュメント