名称

ypclnt, yp_get_default_domain, yp_bind, yp_unbind, yp_match, yp_first, yp_next, yp_all, yp_order, yp_master, yperr_string, ypport_err −  イエローページのクライアントのインタフェース

形式

#include <rpcsvc/ypclnt.h>
yp_bind(indomain);
char ∗indomain;
void yp_unbind(indomain)
char ∗indomain;
yp_get_default_domain(outdomain);
char ∗∗outdomain;
yp_match(indomain, inmap, inkey, inkeylen, outval, outvallen)
char ∗indomain;
char ∗inmap;
char ∗inkey;
int inkeylen;
char ∗∗outval;
int ∗outvallen;
yp_first(indomain, inmap, outkey, outkeylen, outval, outvallen)
char ∗indomain;
char ∗inmap;
char ∗∗outkey;
int ∗outkeylen;
char ∗∗outval;
int ∗outvallen;
yp_next(indomain, inmap, inkey, inkeylen, outkey, outkeylen, outval, outvallen);
char ∗indomain;
char ∗inmap;
char ∗inkey;
int inkeylen;
char ∗∗outkey;
int ∗outkeylen;
char ∗∗outval;
int ∗outvallen;
yp_all(indomain, inmap, incallback);
char ∗indomain;
char ∗inmap;
struct ypall_callback incallback;
yp_order(indomain, inmap, outorder);
char ∗indomain;
char ∗inmap;
int ∗outorder;
yp_master(indomain, inmap, outname);
char ∗indomain;
char ∗inmap;
char ∗∗outname;
char ∗yperr_string(incode)
int incode;
ypprot_err(incode)
unsigned int incode;

解説

この関数パッケージは、 イエローページ（YP）ネットワークの自動照合サービスへのインタフェースを 提供します。 このパッケージは、 標準ライブラリ /lib/libc.a.  からロードできます。 イエローページの概要については、 ypfiles(5) および ypserv(8) を 参照してください。 これらには、 map および domain の定義、 および、 YP を 構成するさまざまなサーバ、 データベース、 およびコマンドの解説が含まれています。 入力パラメータ名はすべて in から始まります。 出力パラメータ名は out から始まります。 char ∗∗ 型の出力パラメータは、 初期化されない文字ポインタへのアドレスです。 メモリは、 malloc(3) を 使用して YPクライアントパッケージによって割り当てられ、 ユーザコードによる継続使用の必要性がなくなったときに、 解放することができます。 outkey および outval のそれぞれに対し、 NEWLINE および NULL を 含むものにそれぞれ追加の 2バイトのメモリが割り当てられますが、 これらの 2バイトは、 outkeylen または outvallen には反映されません。 indomain および inmap 文字列は、 ナル文字列であってはならず、 ナル終了していなければなりません。 文字数パラメータを 伴った文字列パラメータは、 ナルであってはなりませんが、 ナル文字列を ポイントしていてもかまいません。 このとき、 文字数パラメータがこれを 示します。 文字数つき文字列は、 ナル終了していなくてもかまいません。 このパッケージ中の int 型の関数はすべて、 正常に実行されると 0 を 返し、 それ以外のときは異常終了コード (YPERR_xxxx) を 返します。 異常終了コードについては、 下記の 診断 の項で説明されています。 YP自動照合呼び出しには、 最低、 マップ名とドメイン名が必要です。 クライアントプロセスは、 対象とするマップの名前を 知っているものと仮定されます。 クライアントプロセスは、 yp_get_default_domain() を 呼び出すことにより、 ノードのデフォルトドメインを 獲得し、 続く YP 呼び出しへの indomain パラメータとして、 返された outdomain を 使用します。 YPのサービスを 呼び出すためには、 クライアントプロセスは、 yp_bind を 使用して適切なドメインを 供給する YPサーバに“結合”されていなければなりません。 結合は、 YP自動照合関数が呼び出されると、 必ず自動的に行われるため、 ユーザコードで明確に行う必要はありません。 YPのサービスを 使用できない場合、 バックアップを 行おうとするプロセス（例えばローカルファイル）に対し、 yp_bind を 直接呼び出すことができます。 各結合は、 一個のクライアントプロセスのソケットディスクリプタを 割り当て（使い）、 各境界ドメインは、 一個のソケットディスクリプタを 要します。 しかし、 同一のドメインへの多重要求は、 同じディスクリプタを 使用します。 多重ドメインを アクセス中に明示的にソケットディスクリプタを 取り扱うプロセスに対するクライアントインタフェースには、 yp_unbind() を 使用できます。 yp_unbind() の呼び出しは、 ドメインを unbound し、 その結合に使用されていたプロセスごとおよびノードごとのすべてのリソースを 解放します。 RPC の異常終了が結合の使用に起因する場合、 そのドメインは、 自動的に連結を 解かれます。 その時点で、 ypbind が実行されており、 さらに次のいずれかの場合、 ypclnt レイヤは、 動作が正常終了するまで永久に再試行を 繰り返します。

a)クライアントプロセスが適切なドメインに対するサーバを 結合できない場合

b)サーバへの RPC 要求が受け入れられなかった場合 エラーが RPC に関係しない場合、 ypbind が実行されていない場合、 または、 結合された ypserv プロセスが応答（成功または失敗）を 返した場合、 ypclnt レイヤは、 エラーコードまたは正常終了コードとその結果を 返し、 制御を ユーザコードに戻します。 yp_match は、 渡されたキーに関連する値を 返します。 このキーは、 明示されなければなりません。 パターンマッチングは使用できません。 yp_first は、 指定ドメイン中の指定のマップから最初のキー値のペアを 返します。 yp_next() は、 指定のマップ中の次のキー値のペアを 返します。 inkey パラメータは、 最初の yp_first() の呼び出し（2番目のキー値のペアを得る）から返された outkey、 または、 yp_next() のn番目の呼び出し（n+2番目のキー値のペアを得る）から返された outkey です。 最初、2番目 .... という概念は、 処理中の YPマップの構造特有のものです。 この検索順序は、 もともとの（YPでない）データベース中の順序や、 キー、 値、 またはキー値ペアの番号順とは関連がありません。 この順序付けによって保証されることは、 特定のマップ上で yp_first() が呼び出され、 その後、 同一サーバの同一マップ上で yp_next() が、 YPERR_NOMORE で異常終了するまで繰り返し呼び出された場合、 データベース中のすべてのエントリが一度ずつ参照されることです。 さらに、 同一サーバの同一マップ上で同一の一連の操作が行われる場合、 そのエントリは、 同一の順序で参照されます。 クライアントの実行中、 過重なサーバロードや、 サーバの異常終了によってドメインの結合が一度切れ、 再び（おそらく異なるサーバに）結合されることがあり得ます。 これにより、 クライアントが特定のエントリを 2度参照したり、 参照を 行わないエントリができるなど、 参照順序の規則が破られることがあります。 このアプローチは、 参照作業途中でクライアントにエラーメッセージが返されるのを 防ぐためのものです。 次に、 マップ中のすべてのエントリを 参照するための解決法について説明します。 yp_all は、 TCP を 使用して（UDPを使用する、このパッケージの他の関数とは異なる）、 1つの要求でサーバからクライアントにマップ全体を 転送します。 1つの RPC 要求と応答で、 すべての転送が行われます。 yp_all は、 他の YP手続きと同様に使用することができます。 マップの識別は通常の方法で行われ、 マップ中の各キー値ペアを 処理するために呼び出される関数の名前が与えられます。 yp_all の呼び出しからのリターンは、 処理が完了したとき（正常、異常を問わず）、 または、 “foreach” がキー値のペアの参照の中止を 決定したときにのみ行われます。 yp_all への 3番目のパラメータを 以下に示します。

        struct ypall_callback ∗incallback {
                int (∗foreach)();
                char ∗data;
        };

関数 foreach は、 次のように呼び出されます。

        foreach(instatus, inkey, inkeylen, inval, invallen, indata);
        int instatus;
        char ∗inkey;
        int inkeylen;
        char ∗inval;
        int invalllen;
        char ∗indata;

パラメータ instatus は、 <rpcsvc/yp_prot.h> — 中で定義されたリターンステータス値の 1つを 持ちます。 これは、 YP_TRUE またはエラーコードです。 （YPプロトコルエラーコードを ypclnt レイヤエラーコードに 変換する関数については、 ypprot_err を参照してください。） キーおよび値パラメータは、 前述の形式の項で定義されているものとは多少異なります。 第一に、 inkey および inval パラメータによってポイントされるメモリは、 yp_all 専用のもので、 新しいキー値のペアが出現するたびに書き換えられます。 メモリの内容の利用方法は、 関数 foreach に任されていますが、 これは、 メモリ自体を 独占することはありません。 関数 foreach に与えられたキーおよび値のオブジェクトは、 サーバのマップ中のものと同一の形を しています。 これらがマップ中で改行終了またはナル終了していないとき、 これらはここにも存在しません。 indata パラメータは、 yp_all に渡された incallback->data 要素の内容です。 コールバック構造体の要素 data は、 関数 foreach とメインラインのコード間の状態の情報を 共有するために使用できます。 この使用は任意であり、 YPクライアントパッケージのどの部分も、 その内容を調べません。 — これを 利用するか否かはユーザに任せられます。 関数 foreach は、 ブール型です。 これは、 渡された後続のキー値のペアのために再度の呼び出しを 要求する場合には 0 を、 キー値のペアの流れを 停止したい場合には 0 以外を 返します。 foreach が 0 以外の値を 返した場合には、 再度の呼び出しは行われません。 このとき、 yp_all の関数値は 0 になります。 yp_order は、 マップに関する順序番号を 返します。 yp_master は、 マップに関するマスタYPサーバのマシン名を 返します。 yperr_string は、 エラーメッセージ文字列へのポインタを 返します。 この文字列は、 ナル終了し、 ピリオドや改行を 含みません。 ypprot_err は、 YPプロトコルエラーコードを 入力として受け取り、 ypclnt レイヤエラーコードを 返します。 この値は、 順に、 yperr_string への入力として使用できます。

関連ファイル

/usr/include/rpcsvc/ypclnt.h
/usr/include/rpcsvc/yp_prot.h

関連事項

ypfiles(5), ypserv(8)

診断

整数型の関数は、 要求された動作が正常終了した場合は 0 を、 異常終了の場合には下記のエラーのうち 1つを 返します。

#define YPERR_BADARGS1/∗ 関数への引数が違う∗/
#define YPERR_RPC2/∗ RPCのエラー − ドメインが結合されていない∗/
#define YPERR_DOMAIN3/∗ このドメイン上のサーバに結合できない∗/
#define YPERR_MAP4/∗ サーバのドメイン中にそのようなマップが存在しない∗/
#define YPERR_KEY5/∗ マップ中にそのようなキーが存在しない∗/
#define YPERR_YPERR6/∗ 内部 YPサーバまたはクライアントエラー∗/
#define YPERR_RESRC7/∗ リソースの割り当てができない∗/
#define YPERR_NOMORE8/∗ マップデータベース中に残りのレコードがない∗/
#define YPERR_PMAP9/∗ ポートマッパとの通信ができない∗/
#define YPERR_YPBIND10/∗ ypbind との通信ができない∗/
#define YPERR_YPSERV11/∗ ypserv との通信ができない∗/
#define YPERR_NODOM12/∗ ローカルドメイン名が設定されていない∗/

NEWS-OSRelease 3.3