名称
nis_tables, nis_list, nis_add_entry, nis_remove_entry,
nis_modify_entry, nis_first_entry, nis_next_entry ― NIS+ テーブル関数
構文
cc [ flag... ] file... -lnsl [ library... ]
#include <rpcsvc/nis.h>
nis_result *nis_list(const nis_name name,
const u_long flags,
int (*callback)(const nis_name table_name,
const nis_object *object,
const void *userdata),
const void *userdata));
nis_result *nis_add_entry(const nis_name table_name,
const nis_object *object,
const u_long flags);
nis_result *nis_remove_entry(const nis_name name,
const nis_object *object,
const u_long flags);
nis_result *nis_modify_entry(const nis_name name,
const nis_object *object,
const u_long flags);
nis_result *nis_first_entry(const nis_name table_name);
nis_result *nis_next_entry(const nis_name table_name,
const netobj *cookie);
void nis_freeresult(nis_result *result);
説明
これらの関数を使用して、NIS+ テーブルの検索と変更を行います。 nis_list() を使用して、NIS+
ネーム空間にあるテーブルを検索します。 nis_first_entry() と nis_next_entry() を使用して、テーブルのエントリを
1 つずつ列挙します。 nis_add_entry() 、 nis_remove_entry() 、および nis_modify_entry() を使用して、テーブルに保存されている情報を変更します。 nis_freeresult() を使用して、 nis_result 構造体に関連するメモリを解放します。
テーブル内のエントリは、NIS+ インデックス名で指示します。
インデックス名は、検索基準とテーブルオブジェクトを表す単純 NIS+
名で構成された複合名です。 検索基準は、一連のカラム名と、それに対応する値を大かっこ
`[]' で囲んで指定します。インデックス名の指定方法は以下の通りです。
[ colname=value, ... ],tablename
リスト関数の nis_list() は、 name パラメータの値にインデックス名を受け付けます。 ここで、 EXPAND_NAME フラグ
(以下に説明) を設定していない限り、 tablename は NIS+ の完全修飾名でなければなりません。
2 番目のパラメータ flags は、関数が種々の状態に対応する方法を定義します。
このパラメータの値は、以下に示すフラグを論理式 OR で結合して作成します。
| FOLLOW_LINKS | | name に指定されたテーブルを解決した結果が リンク 型オブジェクト ( nis_objects(3N) を参照) となった場合に、このフラグはクライアントライブラリがそのリンクに従ってそのオブジェクトで検索を行うよう指示します。このフラグを設定していないときに、解決された名前がリンク型であると、エラー NIS_NOTSEARCHABLE が戻されます。 |
| FOLLOW_PATH | | このフラグは、当該テーブル内でエントリが見つからない場合に、テーブルオブジェクトに指定されているパスに従ってリスト操作を行うよう指示します。
以下の ALL_RESULTS フラグと一緒に使用すると、検索の結果を問わずテーブルオブジェクトに指定されているパスに従うようになります。
上の FOLLOW_LINKS フラグと一緒に使用すると、パスに指定されているリンク型のテーブルがポイントするテーブルを見つけ出すまで、リンクが続けられます。
サーバを使用できないために、パス内のテーブルに達することができない場合、操作の結果は論理正常終了または論理異常終了のどちらかとなり、パス中のすべてのテーブルが検索されたわけではないことが示されます。
パス中の名前が無効であったり、実在しないオブジェクトであったりすると、その名前は無視されます。 |
| HARD_LOOKUP | | このフラグは、明確な結果が戻されるまで ( NIS_NOTFOUND など)、指定したテーブルのあるサーバと接続を続行するよう指示します。 |
| ALL_RESULTS | | このフラグは、必ず FOLLOW_PATH およびコールバック関数と一緒に使用します。
このフラグを指定すると、パス中のすべてのテーブルが強制的に検索されます。 name に検索基準を指定していないと (すべてのエントリが戻される)、このフラグによってパス中のすべてのテーブルのすべてのエントリが戻されます。 |
| NO_CACHE | | このフラグを指定すると、クライアントライブラリはどのクライアントオブジェクトのキャッシュもバイパスし、マスターサーバまたは指定のテーブルのレプリカサーバから直接情報を得ます。 |
| MASTER_ONLY | | このフラグは NO_CACHE よりも強力で、クライアントライブラリは特定のテーブルのマスターサーバ のみ から情報を得ます。 これによって、情報が最新のものであることが保証されます。
ただし、大規模のネットワークではマスターサーバに直接接続することでパフォーマンスの低下を引き起こします。 HARD_LOOKUP フラグと一緒に使用すると、マスターサーバが起動して使用できるようになるまで、リスト操作は開始されません。 |
| EXPAND_NAME | | このフラグを指定すると、クライアントライブラリは nis_getnames() ( nis_local_names(3N) を参照) を呼び出し、環境変数 NIS_PATH を用いて部分修飾名を拡張します。 |
| RETURN_RESULT | | 操作が正常終了したときに戻されるオブジェクトのコピーが nis_result 構造体に入ります。 |
nis_list() の 3 つ目のパラメータ callback はオプションのポインタで、 検索によって戻された エントリ 型のオブジェクトを処理する関数を指します。
このポインタが NULL であると、検索基準と一致するすべてのエントリは nis_result 構造体に戻されます。そうでない場合は、 1 つのエントリが戻されるたびに指定された関数が呼び出されます。
この関数は、他にもオブジェクトが必要なときに 0 を戻し、オブジェクトが必要でないときには 1 を戻します。4 つ目のパラメータ userdata は、戻されたエントリオブジェクトとともにコールバック関数に渡されます。
クライアントは、コールバック関数がエントリを処理する上で必要な状態情報またはその他の関連情報を、このポインタを使用して渡すことができます。
nis_add_entry() は、 NIS+ オブジェクトを
NIS+ table_name に追加します。 追加操作が異常終了したときの対処方法を指定するには、 flags パラメータを使用します。 デフォルト ( flags = 0) では、追加対象のエントリが既にテーブルにあると、そのまま異常終了となります。 ADD_OVERWRITE フラグを指定すると、オブジェクトが既にあるときには既存オブジェクトが上書き
(変更操作) され 、ないときには新しいエントリが追加されます。 ADD_OVERWRITE フラグを指定したときに、クライアントに既存オブジェクトを変更する権限がない場合は、この関数はエラー NIS_PERMISSION で異常終了します。
RETURN_RESULT フラグを指定すると、サーバは操作が正常終了したときに結果のオブジェクトのコピーを戻します。
nis_remove_entry() は指定されたエントリを table_name に指定されたテーブルまたは一連のエントリから削除します。
パラメータ object がヌル以外の場合は、エントリのキャッシュコピーをポイントするものと想定されます。
削除を開始しようとしたときに、削除対象のオブジェクトが object でポイントされているキャッシュオブジェクトと同じではないと、操作は NIS_NOTSAMEOBJ のエラーで異常終了します。
この関数でオブジェクトを渡す場合は、エントリ内の値から検索基準を作成できるので、
name で検索基準を省略してもかまいません。ただし、オブジェクトを渡さない場合は、 name パラメータの中に検索基準を含める必要があります。
flags 変数がヌルのときに、検索基準がエントリを一意に識別していない場合は、 NIS_NOTUNIQUE のエラーが戻り、操作は打ち切られます。
flags パラメータに REM_MULTIPLE を指定し、オブジェクトそれぞれに対して削除の権限が与えられている場合は、検索基準と一致するすべてのオブジェクトが削除されます。
検索基準がヌルのときに REM_MULTIPLE フラグを指定すると、テーブル中のすべてのエントリが削除されることに注意してください。
nis_modify_entry() は、 name で指定されたオブジェクトを変更します。 EN_MODIFIED フラグを設定し、パラメータ object は各カラムに新しい情報が入っているエントリをポイントしていなければなりません。
これらのカラムの内容が、テーブルに保存されているエントリ内の対応するカラムの内容と置き換えられます。
変更操作が正常終了するためには、渡されるエントリは変更されるカラムと同じカラム数、同じ型、および有効なデータになっていなければなりません。
flags パラメーターにフラグ MOD_SAMEOBJ を指定すると、 object でポイントされているオブジェクトは本来のオブジェクトのキャッシュコピーであるとみなされます。
渡されたオブジェクトの OID が、サーバーによりフェッチされたオブジェクトの
OID と違っている場合、 NIS_NOTSAMEOBJ のエラーにより操作は異常終了します。
これは、オブジェクトが変更されている場合に、クライアントがオブジェクトを書き込む前に異常終了する単純な読み取り/変更/書き込みプロトコルを実現するときに使用できます。
フラグ RETURN_RESULT を指定すると、サーバは操作が正常終了したときに結果のオブジェクトのコピーを戻します。
nis_first_entry() は、テーブルからエントリを
1 つずつフェッチします。 この操作モードは非常に非効率的であるので、できる限りコールバックを使用するようにします。
対象とするエントリが入ったテーブルを name で指定します。name に検索基準があっても、無視されます。 呼び出し側は、nis_result 構造体内の cookie の値をローカルの記憶領域にコピーし、 nis_next_entry() への引き数として渡すようにする必要があります。
nis_next_entry() は、 table_name で指定されたテーブルから次のエントリを取り出します。
この場合、エントリが戻される順序は保証されません。 さらに、 nis_next_entry() の呼び出しと呼び出しの間にテーブルの更新された場合は、
追加または変更されたエントリがクライアントで検出されるかどうかも保証されません。
次のエントリとして戻されるはずだったエントリがテーブルから削除された場合は、 NIS_CHAINBROKEN のエラーが戻されます。
マルチスレッドの使用法
| Thread
Safe: | | Yes |
| Cancel Safe: | | Yes |
| Fork Safe: | | No |
| Async-cancel Safe: |
| | | No |
| Async-signal Safe: |
| | | No |
これらの関数は、マルチスレッド環境で支障なく呼び出すことができます。
これらの関数は、キャンセルポイントの関数を呼び出した時点でキャンセルポイントになります。
マルチスレッド環境では fork() の後および exec() の前で、子プロセスからこれらの関数を呼び出すことは安全ではありません。
非同期キャンセル、または、非同期シグナルをサポートするマルチスレッドアプリケーションでこれらの関数は呼び出さないようにしてください。
戻り値
関数は、 nis_result 型の構造体を指すポインタを戻します。
struct nis_result {
nis_error status;
struct {
u_int objects_len;
nis_object *objects_val;
} objects;
netobj cookie;
u_long zticks;
u_long dticks;
u_long aticks;
u_long cticks;
};
status メンバーには操作のエラーステータスが入ります。 エラーを説明するテキストメッセージを得るには、 nis_sperrno() 関数
( nis_error(3N) を参照)
を呼び出します。
objects 構造体には 2 つのメンバーが含まれています。
1 つは objects_val で、 nis_object 構造体の配列です。もう 1 つは objects_len で、配列内のセル数を示します。 これらのオブジェクトを解放するには nis_freeresult() ( nis_names(3N) を参照) を呼び出します。
オブジェクトをいくつか保持したい場合は、 nis_clone_object() 関数でコピーしてから
オブジェクトを nis_destroy_object() 関数 ( nis_server(3N) を参照) で解放します。
さまざまな単位時間 (ティック) は、要求に対する処理時間 (マイクロ秒単位)
の明細を含みます。 これらの時間明細を使用することによって、高速にアクセスできるようデータの編成方法を調整したり、別の実装方法のデータベースと比較したり
( nis_db(3N) を参照) できます。
| zticks | | NIS+ サービス自体にかかった時間。 サーバが要求を受信した時点から返答を送信するまでの時間です。 |
| dticks | | データベースのバックエンドでかかった時間。 データベースへ呼び出しを開始してから結果が戻るまでの時間です。
要求でデータベースを複数回呼び出す場合は、その呼び出しすべてにかかった時間の合計です。 |
| aticks | | 「アクセラレータ」またはキャッシュにかかった時間。
要求を解決するために必要なサーバの位置を見つけ出す時間も含まれます。 |
| cticks | | 要求にかかった合計時間。 このクロックは、クライアントライブラリに入った時点で開始し、結果が戻った時点で停止します。
この値から他の時間の合計を差し引くと、NIS+ 要求を生成するためのローカルオーバヘッドを得ることができます。 |
zticks の値から dticks の値を差し引くと、サービスコード自体にかかった時間となります。 cticks の値から zticks の値と aticks の値の合計を差し引くと、クライアントライブラリ自体にかかった時間となります。
注 : 時間はすべてマイクロ秒で測定されます。
エラー
クライアントライブラリから種々のエラーや診断が戻ります。一般的なものを以下に説明します。
| NIS_BADATTRIBUTE |
| | | 属性の名前がテーブル内の指定のカラムと合致しません。または属性に値がありません。 |
| NIS_BADNAME | | 関数に渡された名前は有効な NIS+ 名ではありません。 |
| NIS_BADREQUEST | | クライアントライブラリに渡された構造体の内部に問題が検出されました。 |
| NIS_CACHEEXPIRED |
| | | 戻されたエントリは 期限切れ のオブジェクトキャッシュからのものです。 有効期間値はゼロになっており、エントリは変更されている可能性があります。
フラグ NO_CACHE を参照関数に渡すと、期限の切れていないオブジェクトのコピーを得る操作が行われます。 |
| NIS_CBERROR | | サーバがクライアントを呼び戻している間に、サーバで
RPC エラーが発生しました。 その時点でトランザクションは打ち切られ、送信されていないデータは破棄されます。 |
| NIS_CBRESULTS | | 要求は正常終了していますが、エントリはすべてコールバック関数に送られているので、この結果には含まれません。 |
| NIS_FOREIGNNS | | 名前を完全に解決できません。 関数に渡された名前が
NIS+ 名前ツリーの外側にあるネーム空間で解決されると、このエラーと一緒に ディレクトリ 型の
NIS+ オブジェクトが戻されます。戻されるオブジェクトにはネーム空間の型と、そのネーム空間内のサーバの接続情報が入っています。 |
| NIS_INVALIDOBJ | | object でポイントされているオブジェクトは、指定のテーブルの有効な
NIS+ エントリオブジェクトではありません。 テーブル内の対応するカラムとカラム数が一致していない場合や、データ型
(バイナリやテキストなど) が異なっている場合に発生します。 |
| NIS_LINKNAMEERROR |
| | | 渡された名前は リンク 型のオブジェクトとして解決されましたが、オブジェクトの内容が無効な名前をポイントしています。 |
| NIS_MODFAIL | | 何らかの理由で変更が異常終了しました。 |
| NIS_NAMEEXISTS | | 既に存在する名前を追加しようとしました。 名前を追加するには、まず既存の名前を削除してから新しい名前を追加するか、既存のオブジェクトを変更します。 |
| NIS_NAMEUNREACHABLE |
| | | このソフトエラーは、指定のテーブルオブジェクトの目的のディレクトリのサーバに到達できないことを示します。
この状態は、ネットワークパーティションまたはサーバがクラッシュしたときに発生することがあります。もう一度操作してみると、正常に動作することがあります。 HARD_LOOKUP フラグを参照してください。 |
| NIS_NOCALLBACK | | サーバがユーザーのマシン上のコールバックサービスに接続できません。そのため、データは一切戻されません。 |
| NIS_NOMEMORY | | 通常は、致命的な結果となります。 サービスでヒープスペースが不足していることを意味します。 |
| NIS_NOSUCHNAME | | このハードエラーは、テーブルオブジェクトには指定されたディレクトリがないことを示します。
このエラーは、当該テーブルに機能するサーバの親サーバが、テーブルの入っているディレクトリに関する情報を持っていないときに発生します。 |
| NIS_NOSUCHTABLE | | 指定のテーブルがありません。 |
| NIS_NOT_ME | | サーバに要求が出されましたが、そのサーバは指定された名前に対して機能しません。
通常、このようなことは起こりませんが、サーバの組み込み位置メカニズムを使用していない場合に、ユーザー独自のメカニズムが壊れているときに発生することがあります。 |
| NIS_NOTFOUND | | テーブル内のどのエントリも検索基準と一致しません。
検索基準がヌル (すべてのエントリを戻す) のときにこの結果となった場合は、テーブルが空なので、 nis_remove() を呼び出して削除してください。 FOLLOW_PATH フラグを設定した場合は、このエラーはパス中のどのテーブルにも検索基準と一致するエントリがないことを示します。 |
| NIS_NOTMASTER | | 指定の名前に機能するサーバに対して変更要求が出されましたが、このサーバはマスターサーバではありません。
これは、ディレクトリオブジェクトを変更したときに、新しいマスターサーバを指定した場合に発生します。 /var/nis/NIS_SHARED_DIRCACHE ファイルにディレクトリオブジェクトのキャッシュコピーを持つクライアントは、キャッシュマネージャを再開始して
( nis_cachemgr -i を使用) このキャッシュをフラッシュする必要があります。 |
| NIS_NOTSAMEOBJ | | 削除対象のオブジェクトが要求で渡されたオブジェクトと同じではないので、ネーム空間からオブジェクトを削除する操作が打ち切られました。 |
| NIS_NOTSEARCHABLE |
| | | テーブル名が NIS+ オブジェクトへと解決されましたが、これは検索不可能です。 |
| NIS_PARTIAL | | この結果は NIS_NOTFOUND とよく似ています。ただし、要求は正常終了しており、解決されたエントリがないことを意味します。
この状態が発生した場合、サーバはエントリではなく、テーブルオブジェクトのコピーを戻します。そのため、クライアントはパスを処理するか、他のローカルポリシーを実施できるようになります。 |
| NIS_RPCERROR | | これは致命的なエラーであり、何らかの形で RPC サブシステムが異常終了したことを示します。
通常は、RPC 要求が異常終了した理由を示す syslog(3C) メッセージがあるはずです。 |
| NIS_S_NOTFOUND | | 指定のエントリがテーブル内にありません。ただし、パス中のテーブルをすべて検索できたわけではないので、テーブルのどれかにエントリがある可能性も残っています。 |
| NIS_S_SUCCESS | | 要求は正常終了していますが、検索パス中の 1 つのテーブルが検索できなかったので、結果は、そのテーブルをアクセスできた場合のものと違っている可能性があります。 |
| NIS_SUCCESS | | 要求は正常終了しました。 |
| NIS_SYSTEMERROR | | 要求を処理しようとしたときに、何らかの汎用システムエラーが発生しました。 syslog(3C) のレコードをチェックし、サーバからのエラーメッセージを調べてください。 |
| NIS_TOOMANYATTRS |
| | | サーバに渡された検索基準の属性の数が、テーブルの検索可能なカラム数より多くなっています。 |
| NIS_TRYAGAIN | | 接続されているサーバがビジーで、ユーザーからの要求を取り扱うことができません。 add_entry() 、 remove_entry() 、 modify_entry() では、マスターサーバが内部状態を更新中のときにこのエラーが戻されます。
また、 nis_list() 関数でコールバックを指定したとき、サーバがコールバックを扱うためのリソースを十分に持っていないと、 nis_list() に戻されることがあります。 |
| NIS_TYPEMISMATCH |
| | | テーブルに対してエントリの追加または変更をしようとしましたが、渡されたエントリの型がテーブルの型と違っています。 |
多言語化対応
環境変数
| NIS_PATH | | この変数を設定していると、フラグ EXPAND_NAME を指定した場合に nis_list() でこの変数が検索パスとして使用されます。 |
警告
フラグ HARD_LOOKUP によってネットワークパーティションでアプリケーションが無限にブロックされることがあるので、このフラグを使用する際には十分な注意が必要です。
警告
HP-UX 11i Version 2 は、NIS+ がサポートされる最後の HP-UX
リリースです。
NIS+ の代わりに LDAP を推奨します。 HP は、LDAP に基づく業界標準のネームサービスを完全にサポートします。
注意
フラグ FOLLOW_PATH を指定したときに使用されるパスは、
検索される 最初 のテーブルにあるパスです。 その後に検索されるテーブルにあるパスの値は無視されます。
ネームサービスをアクセスする関数をリストのコールバック内から呼び出してもかまいません。
ただし、それ自体がコールバックを使用する関数や、コールバックのある nis_list() をリストのコールバック関数内から呼び出すことは、現在のところサポートされていません。
現在のところ、 nis_first_entry() と nis_next_entry() がマスターサーバのみから答えを得る方法はありません。
印刷用画面へ 
