EN JA
RPC_CLNT_CREATE(3)
RPC_CLNT_CREATE(3) FreeBSD Library Functions Manual RPC_CLNT_CREATE(3)

名称

rpc_clnt_create, clnt_control, clnt_create, clnt_create_timed, clnt_create_vers, clnt_create_vers_timed, clnt_destroy, clnt_dg_create, clnt_pcreateerror, clnt_raw_create, clnt_spcreateerror, clnt_tli_create, clnt_tp_create, clnt_tp_create_timed, clnt_vc_create, rpc_createerrCLIENT ハンドルの作成と操作を処理するためのライブラリルーチン

ライブラリ

Standard C Library (libc, -lc)

書式

#include < rpc/rpc.h>

bool_t
clnt_control( CLIENT *clnt, const u_int req, char *info);

CLIENT *
clnt_create( const char * host, const rpcprog_t prognum, const rpcvers_t versnum, const char *nettype);

CLIENT *
clnt_create_timed( const char * host, const rpcprog_t prognum, const rpcvers_t versnum, const char *nettype, const struct timeval *timeout);

CLIENT *
clnt_create_vers( const char * host, const rpcprog_t prognum, rpcvers_t *vers_outp, const rpcvers_t vers_low, const rpcvers_t vers_high, const char *nettype);

CLIENT *
clnt_create_vers_timed( const char * host, const rpcprog_t prognum, rpcvers_t *vers_outp, const rpcvers_t vers_low, const rpcvers_t vers_high, const char *nettype, const struct timeval *timeout);

void
clnt_destroy( CLIENT *clnt);

CLIENT *
clnt_dg_create( const int fildes, const struct netbuf *svcaddr, const rpcprog_t prognum, const rpcvers_t versnum, const u_int sendsz, const u_int recvsz);

void
clnt_pcreateerror( const char *s);

char *
clnt_spcreateerror( const char *s);

CLIENT *
clnt_raw_create( const rpcprog_t prognum, const rpcvers_t versnum);

CLIENT *
clnt_tli_create( const int fildes, const struct netconfig *netconf, struct netbuf *svcaddr, const rpcprog_t prognum, const rpcvers_t versnum, const u_int sendsz, const u_int recvsz);

CLIENT *
clnt_tp_create( const char * host, const rpcprog_t prognum, const rpcvers_t versnum, const struct netconfig *netconf);

CLIENT *
clnt_tp_create_timed( const char * host, const rpcprog_t prognum, const rpcvers_t versnum, const struct netconfig *netconf, const struct timeval *timeout);

CLIENT *
clnt_vc_create( const int fildes, const struct netbuf *svcaddr, const rpcprog_t prognum, const rpcvers_t versnum, u_int sendsz, u_int recvsz);

解説

RPC ライブラリルーチンは、C 言語プログラムでネットワークを越えて他のマシンでプロシージャ呼び出しできるようにします。まず最初に、 CLIENT ハンドルが作成され、次に、クライアントは、要求をサーバに送るためにプロシージャを呼び出します。要求を受信する次第に、サーバは、要求されたサービスを実行するためにディスパッチルーチンを呼び出して、次に、応答を送信します。

ルーチン

clnt_control()
クライアントオブジェクトに関する様々な情報を変更するか、または検索する関数マクロ。 req 引数は、操作のタイプを示し、 info は、情報へのポインタです。コネクションレスとコネクション指向の転送のために、 req のサポートされた値とそれらの引数タイプ、およびそれらが行うことは、次の通りです:
CLSET_TIMEOUT struct timeval * 合計のタイムアウトを設定
CLGET_TIMEOUT struct timeval * 合計のタイムアウトを取得

注: 利用者が clnt_control() を使用してタイムアウトを設定するなら、 clnt_call() によって渡されたタイムアウト引数は、すべてのその後の呼び出しで無視されます。

注: 利用者がタイムアウト値を 0 に設定するなら、 clnt_control() は、直ちに、エラー ( RPC_TIMEDOUT) を返します。バッチ呼び出しのためにタイムアウト引数を 0 に設定します。

CLGET_SVC_ADDR struct netbuf * サーバアドレスを取得
CLGET_FD int * ハンドルから fd を取得
CLSET_FD_CLOSE void 破壊時に fd をクローズ
CLSET_FD_NCLOSE void 破壊時に fd をクローズしない
CLGET_VERS uint32_t * RPC プログラムバージョンを取得
CLSET_VERS uint32_t * RPC プログラムバージョンを設定
CLGET_XID uint32_t * 前の呼び出しの XID を取得
CLSET_XID uint32_t * 次の呼び出しの XID を設定

コネクションレスな転送だけで、次の操作は、有効です:

CLSET_RETRY_TIMEOUT struct timeval * 再試行タイムアウトを設定
CLGET_RETRY_TIMEOUT struct timeval * 再試行タイムアウトを取得
CLSET_CONNECT int * connect(2) を使用

再試行タイムアウトは、要求を再送する前に応答するサーバのために RPC が待つ時間です。 clnt_control() 関数は、成功すれば TRUE を返し、失敗すれば FALSE を返します。

clnt_create()
プログラム prognum とバージョン versnum のための一般的なクライアント作成ルーチン。 host 引数は、サーバが位置しているリモートホストの名前を識別します。 nettype 引数は、使用する転送プロトコルのクラスを識別します。転送は、 NETPATH 環境変数で左から右の順序で試みられか、 netconfig データベースで上位から下位の順序で試みられます。 clnt_create() 関数は、 NETPATH 環境変数と netconfig データベースから利用可能な nettype クラスのすべての転送を試みて、最初に成功したものを選びます。デフォルトのタイムアウトは、 clnt_control() を使用して設定して、変更することができます。失敗するなら、このルーチンは、 NULL を返します。 clnt_pcreateerror() ルーチンは、失敗の理由を印刷 (表示) するために使用することができます。

注: clnt_create() は、たとえ clnt_create() に供給された特定のバージョン番号が rpcbind(8) サービスで登録されていなくても、有効なクライアントハンドルを返します。このミスマッチは、後で ( rpc_clnt_calls(3) 参照) clnt_call() によって発見されます。

clnt_create_timed()
一般的なクライアント作成ルーチンは、 clnt_create() と同様ですが、また、試みられるそれぞれの転送クラスに許された最大の時間を指定する追加引数 timeout があります。そのほかの点では、すべて、 clnt_create_timed() 呼び出しは、ちょうど clnt_create() 呼び出しのように振る舞います。
clnt_create_vers()
一般的なクライアント作成ルーチンは、 clnt_create() と同様ですが、またバージョンの有用性をチェックします。 host 引数は、サーバが位置しているリモートホストの名前を識別します。 nettype 引数は、使用する転送プロトコルのクラスを識別します。ルーチンが成功したなら、サーバによってサポートされる vers_lowvers_high の間の最も高いバージョンのために作成されたクライアントハンドルを返します。 vers_outp 引数は、この値に設定されます。すなわち、成功して返った後は、 vers_low <= *vers_outp <= vers_high となります。 vers_lowvers_high の間のバージョンがサーバによってサポートされないなら、ルーチンは、失敗して、 NULL を返します。デフォルトのタイムアウトは、 clnt_control() を使用して設定して、変更することができます。失敗するなら、このルーチンは、 NULL を返します。 clnt_pcreateerror() ルーチンは、失敗の理由を印刷 (表示) するために使用することができます。注: clnt_create() は、たとえ clnt_create() に供給された特定のバージョン番号が rpcbind(8) サービスで登録されていなくても、有効なクライアントハンドルを返します。このミスマッチは、後で ( rpc_clnt_calls(3) 参照) clnt_call() によって発見されます。しかしながら、 clnt_create_vers() は、供給された範囲中のバージョンがサーバによってサポートされる場合にだけ、利用者のためにこれを行って、有効なハンドルを返します。
clnt_create_vers_timed()
一般的なクライアント作成ルーチンは、 clnt_create_vers() と同様ですが、また、試みられるそれぞれの転送クラスに許された最大の時間を指定する追加引数 timeout があります。そのほかの点では、すべて、 clnt_create_vers_timed() 呼び出しは、ちょうど clnt_create_vers() 呼び出しのように振る舞います。
clnt_destroy()
クライアントの RPC ハンドルを破壊する関数マクロ。通常、破壊は、 clnt 自体を含むプライベートデータ構造体の割り付け解放を呼び出します。 clnt の使用は、 clnt_destroy() を呼び出した後で、未定義です。 RPC ライブラリが関連ファイル記述子をオープンしたか、または CLSET_FD_CLOSEclnt_control() を使用して設定されたなら、ファイル記述子は、クローズされます。呼び出し側は、関連 AUTH 構造体 ( rpc_clnt_auth(3) 参照) を破壊するために、 ( clnt_destroy() の呼び出しの前に) auth_destroy( clnt->cl_auth) を呼び出すべきです。
clnt_dg_create()
このルーチンは、リモートプログラム prognum とバージョン versnum のために RPC クライアントを作成します。クライアントは、コネクションレスの転送を使用します。リモートプログラムは、アドレス svcaddr に位置しています。 fildes 引数は、オープンしてバインドされたファイル記述子です。このルーチンは、応答が受信されるか、タイムアウト呼び出しまで、 15 秒の間隔で呼び出しメッセージに応答します。タイムアウトへの呼び出しのための合計時間は、 clnt_call() ( rpc_clnt_calls(3)clnt_call() 参照) によって指定されます。再試行タイムアウトと合計タイムアウトの期間は、 clnt_control() を使用して変更することができます。ユーザは、送信サイズと受信バッファを引数 sendszrecvsz で指定できます。値を 0 にすると適切なデフォルトを選択します。失敗するなら、このルーチンは、 NULL を返します。
clnt_pcreateerror()
なぜクライアント RPC ハンドルが作成することができなかったかを示すメッセージを標準エラーに印刷 (表示) します。メッセージに文字列 s とコロンを先頭に付けて、改行を後ろに追加します。
clnt_spcreateerror()
標準エラーに印刷する代わりに文字列を返すことを除いて、 clnt_pcreateerror() に似ています。この場合、改行をメッセージに追加しません。警告: 各呼び出しのときに上書きされるバッファへのポインタを返します。
clnt_raw_create()
このルーチンは、リモートプログラム prognum とバージョン versnum のために RPC クライアントハンドルを作成します。メッセージをサービスに渡すために使用される転送は、プロセスのアドレス空間中のバッファであるので、対応する RPC サーバは、同じアドレス空間に存続するべきです。 ( rpc_svc_create(3)svc_raw_create() を参照してください)。これは、少しのカーネルまたはネットワーク干渉なしで、ラウンドトリップ時間などのように、 RPC のシミュレーションと RPC オーバヘッドの測定を可能とします。失敗するなら、このルーチンは、 NULL を返します。 clnt_raw_create() 関数は、 svc_raw_create() の後で呼び出されるべきです。
clnt_tli_create()
このルーチンは、リモートプログラム prognum とバージョン versnum のために RPC クライアントハンドルを作成します。リモートプログラムは、アドレス svcaddr に位置しています。 svcaddrNULL であり、それがコネクション (接続) 指向であるなら、ファイル記述子は、接続されていると仮定されます。コネクションレス転送において、 svcaddrNULL であるなら、 RPC_UNKNOWNADDR エラーが設定されます。 fildes 引数は、オープンされ、バインドされ、接続されているファイル記述子です。 RPC_ANYFD であるなら、それは、 netconf によって指定された転送でのファイル記述子をオープンします。 fildesRPC_ANYFD であり、 netconfNULL であるなら、 RPC_UNKNOWNPROTO エラーが設定されます。 fildes がバインドされていないなら、記述子をバインドすることを試みます。ユーザは、バッファのサイズを引数 sendszrecvsz で指定できます。値を 0 にすると適切なデフォルトを選択します。 (コネクション (接続) 指向、または、コネクションレスの) 転送のタイプに応じて、 clnt_tli_create() は、適切なクライアント作成ルーチンを呼び出します。失敗するなら、このルーチンは、 NULL を返します。 clnt_pcreateerror() ルーチンは、失敗の理由を印刷 (表示) するために使用することができます。リモート rpcbind サービス ( rpcbind(8) 参照) は、リモートサービスのアドレスを参照しません。
clnt_tp_create()
clnt_tp_create() が netconf を通して指定された転送の 1 つを試みることを除いて、 clnt_create() に似ています。 clnt_tp_create() 関数は、プログラム prognum バージョン、 versnumnetconf によって指定された転送のためのクライアントハンドルを作成します。デフォルトのオプションが設定されます、それは、 clnt_control() 呼び出しを使用することで変更することができます。ホスト host でのリモート rpcbind サービスは、リモートサービスのアドレスで参照されます。失敗するなら、このルーチンは、 NULL を返します。 clnt_pcreateerror() ルーチンは、失敗の理由を印刷 (表示) するために使用することができます。
clnt_tp_create_timed()
clnt_tp_create_timed() には、作成の試みを成功するために許された最大の時間を指定する特別の引数 timeout があることを除いて、 clnt_tp_create() に似ています。そのほかの点では、すべて、 clnt_tp_create_timed() 呼び出しは、ちょうど clnt_tp_create() 呼び出しのように振る舞います。
clnt_vc_create()
このルーチンは、リモートプログラム prognum とバージョン versnum のために RPC クライアントを作成します。クライアントは、コネクション (接続) 指向の転送を使用します。リモートプログラムは、アドレス svcaddr に位置しています。 fildes 引数は、オープンされ、バインドされたファイル記述子です。ユーザは、送信サイズと受信バッファを引数 sendszrecvsz で指定できます。値を 0 にすると適切なデフォルトを選択します。失敗するなら、このルーチンは、 NULL を返します。アドレス svcaddr は、 NULL であるべきでなく、リモートプログラムの実際のアドレスを指すべきです。 clnt_vc_create() 関数は、この情報のためのリモート rpcbind サービスを参照しません。
struct rpc_createerr rpc_createerr;
任意の RPC クライアントハンドル作成ルーチンで設定された値がある失敗したグローバル変数です。それは、失敗の理由を印刷 (表示) するためにルーチン clnt_pcreateerror() で使用されます。
May 7, 1993 FreeBSD