RPC(3) FreeBSD ライブラリ関数マニュアル RPC(3)
名称
rpc − リモートプロシージャコール用ライブラリルーチン |
ライブラリ
標準 C ライブラリ (libc, −lc) |
書式
#include <rpc/rpc.h> 関数の説明については 解説を参照してください。 |
解説
このルーチンでは、C プログラムを使用して、ネットワークを通して別のマシン でプロシージャ呼び出しを実行できます。まずクライアントがプロシージャを呼 び出し、データパケットをサーバに送信します。パケットを受け取ったサーバ は、ディスパッチルーチンを呼び出し、要求されたサービスを実行してから応答 を送り返します。最後に、プロシージャ呼び出しがクライアントに戻ります。 Secure RPC (DES 認証) に使用するルーチンについては、 rpc_secure(3) で説明 します。 Secure RPC は DES 暗号化が使用できる場合にのみ使用できます。 |
void
auth_destroy(AUTH *auth) auth に関連する認証情報を破壊するマクロです。一般的に、破壊にはプ ライベートデータ構造の解放も含まれます。 auth_destroy() を呼び出 した後で auth を使用した結果は不定になります。 AUTH * 各リモートプロシージャコールで使用できない認証情報を渡す RPC 認証 ハンドルを作成して戻します。 RPC は、この認証をデフォルトで使用し ます。 AUTH * 認証情報を含む RPC UNIX 認証ハンドルを作成して戻します。パラメー タ host は、情報を作成するマシンの名前です。 uid は、ユーザのユー ザ ID です。 gid は、ユーザの現行グループ ID です。 len と aup_gids は、ユーザが属するグループの配列を表します。あるユーザに なりすますことが容易です。 AUTH * 適切なパラメータで authunix_create() を呼び出します。 callrpc(char *host, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out) マシン host で prognum, versnum, procnum に関連するリモートプロ シージャを呼び出します。パラメータ in は、プロシージャの引数アド レスで、 out は結果を配置するアドレスです。 inproc は、プロシー ジャのパラメータをデコードするために使用し、 outproc は、プロシー ジャの結果をデコードするために使用します。このルーチンは、問題が なければ 0 を戻し、問題がある場合は、 enum clnt_stat を整数にキャ ストした値を戻します。エラーステータスをメッセージに変換するに は、ルーチン clnt_perrno() が便利です。 警告: このルーチンでリモートプロシージャを呼び出す場合は、 UDP/IP がトランスポート層として使用されます。制限事項については、 clntudp_create() を参照してください。このルーチンを使用した場合、 タイムアウトや認証は制御できません。 enum clnt_stat ローカルで接続されているすべてのブロードキャストネットに呼び出し メッセージがブロードキャストされることを除けば、 callrpc() と同じ です。このルーチンは、応答を受け取るたびに、以下の形式の eachresult() を呼び出します。 bool_t eachresult(caddr_t out, struct sockaddr_in *addr) out は、リモートプロシージャの出力がデコードされることを除けば、 clnt_broadcast() に渡される out と同じです。 addr は、結果を送信 するマシンのアドレスを指します。 eachresult() が 0 を戻す場合、 clnt_broadcast() は次の応答を待ちます。 0 を戻さない場合は、適切 なステータスで戻ります。 警告: ブロードキャストソケットのサイズは、データリンクの最大転送 単位に制限されています。イーサネットの場合、この値は 1500 バイト です。 |
enum clnt_stat
clnt_call(CLIENT *clnt, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out, struct timeval tout) clnt_create() などの RPC クライアント作成ルーチンで入手した、クラ イアントハンドル clnt に関連するリモートプロシージャ procnum を呼 び出すマクロです。パラメータ in はプロシージャの引数のアドレス で、 out は結果を配置するアドレスです。 inproc はプロシージャのパ ラメータのデコードに使用し、 outproc はプロシージャの結果のデコー ドに使用します。 tout は、結果が戻るまでの時間です。 void clnt_destroy(CLIENT *clnt) クライアントの RPC ハンドルを破壊するマクロです。通常の場合、破壊 には、 clnt も含めたプライベートデータ構造の解放も含まれます。 clnt_destroy() を呼び出した後で clnt を使用した結果は不定になりま す。 RPC ライブラリが関連ソケットを開いた場合はそれも閉じます。関 連ソケットを開いていない場合、ソケットは開いたまま残ります。 CLIENT * 一般的なクライアント作成ルーチンです。 host は、サーバが配置され ているリモートホストの名前を指定します。 proto は、使用する転送プ ロトコルの種類を指定します。このフィールドで現在サポートされてい る値は、 "udp" と "tcp" です。タイムアウトはデフォルトが設定され ていますが、 clnt_control() を使用して修正できます。 警告: UDP の使用には短所があります。 UDP ベースの RPC メッセージ は、 8 キロバイトのエンコード済みデータまでしか維持できないので、 大きな引数を取るプロシージャや、大きな結果を戻すプロシージャでは 使用できません。 bool_t クライアントオブジェクトのさまざまな情報の変更や取り出しを行うマ クロです。 req はオペレーションのタイプを指定し、 info は情報のポ インタです。 UDP と TCP の両方でサポートされている req の値、引数 タイプ、実行内容は以下の通りです。 CLSET_TIMEOUT |
struct timeval 総タイムアウトの設定
CLGET_TIMEOUT 注意: タイムアウトを clnt_control() で設定すると、 clnt_call() に 渡されるタイムアウトパラメータは、後のすべての呼び出しで無視され ます。 CLGET_SERVER_ADDR |
struct sockaddr_in get server’s address
以下のオペレーションは UDP のみで有効です。 CLSET_RETRY_TIMEOUT |
struct timeval 再試行タイムアウトの設定
CLGET_RETRY_TIMEOUT 再試行タイムアウトは、サーバが応答してから要求を再送することを UDP RPC が待機する時間です。 |
bool_t clnt_freeres(CLIENT *clnt, xdrproc_t outproc, char *out)
RPC/XDR システムが RPC 呼び出しの結果をデコードする場合に割り振っ たデータを解放するマクロです。パラメータ out は結果のアドレスで、 outproc は結果を記述する XDR ルーチンです。このルーチンは、結果が 問題なく解放された場合は 1 を戻し、問題が発生した場合は 0 を戻し ます。 void クライアントハンドルのエラー構造を、アドレス errp の構造体にコ ピーするマクロです。 void クライアント RPC ハンドルを作成できない理由を表すメッセージを標準 エラーに出力します。メッセージの最初には、文字列 s とコロンが付き ます。これは、 clnt_create(), clntraw_create(), clnttcp_create(), clntudp_create() のいずれかがエラーとなった場合に使用します。 void stat が示す条件に対応するメッセージを標準エラーに出力します。 callrpc() の後で使用してください。 void clnt_perror(CLIENT *clnt, char *s) RPC 呼び出しがエラーになった理由を示すメッセージを標準エラーに出 力します。 clnt は、呼び出しの実行に使用したハンドルです。メッ セージ最初には、文字列 s とコロンが付きます。 clnt_call() の後で 使用してください。 char * 標準エラーに出力する代わりに文字列を戻すことを除けば、 clnt_pcreateerror() と同じです。 バグ: 各呼び出しで上書きされた静的データのポインタを戻します。 char * clnt_perrno() と同じ引数を取りますが、 RPC 呼び出しがエラーになっ た理由を示すメッセージを標準エラーに送信する代わりに、メッセージ を含む文字列のポインタを戻します。文字列は改行 (‘\n’) で終わりま す。 プログラムに標準エラーがない場合 (サーバとして実行しているプログ ラムには標準エラーがないことが多い)、またはメッセージを printf() で出力する必要がない場合、あるいは clnt_perrno() がサポートするも の以外のメッセージフォーマットを使用する場合は、 clnt_perrno() の 代わりに clnt_sperrno() を使用します。 注意: clnt_sperror() と clnt_spcreaterror() とは異なり、 clnt_sperrno() は静的データのポインタを戻しますが、結果は各呼び出 しで上書きされません。 char * clnt_sperrno() と同じように、標準エラーに出力せずに文字列を戻すこ とを除けば、 clnt_perror() と同じです。 バグ: 各呼び出しで上書きされた静的データのポインタを戻します。 CLIENT * リモートプログラム prognum バージョン versnum のトイ RPC クライア ントを作成します。サービスにメッセージを渡す実際のトランスポート は、プロセスのアドレススペース内にあるバッファなので、対応する RPC サーバは同じアドレススペースに存在する必要があります。 svcraw_create() を参照してください。これにより、 RPC のシミュレー ション、およびラウンドトリップタイムなど、 RPC オーバヘッドの取得 をカーネルの干渉なしに実行できます。このルーチンは、エラーが発生 すると NULL を戻します。 CLIENT * リモートプログラム prognum バージョン versnum の RPC クライアント を作成します。クライアントは、トランスポートとして TCP/IP を使用 します。リモートプログラムは、インターネットアドレス addr にあり ます。 addr−>sin_port が 0 である場合は、リモートプログラムが注意 を向ける実際のポートに設定されます ( portmap(8) サービスはこの情 報で調べられます)。パラメータ sockp はソケットです。このパラメー タが RPC_ANYSOCK である場合、このルーチンは新しいソケットを開いて sockp を設定します。 TCP ベースの RPC はバッファによる I/O を使用 するので、ユーザはパラメータ sendsz と recvsz で送信バッファと受 信バッファのサイズを指定できます。値を 0 にすると、適切なデフォル トが選択されます。このルーチンは、エラーになると NULL を戻しま す。 CLIENT * リモートプログラム prognum バージョン versnum の RPC クライアント を作成します。クライアントは、トランスポートとして UDP/IP を使用 します。リモートプログラムは、インターネットアドレス addr にあり ます。 addr−>sin_port が 0 である場合は、リモートプログラムが注意 を向ける実際のポートに設定されます (リモート portmap(8) サービス は、この情報で調べられます)。パラメータ sockp はソケットです。こ のパラメータが RPC_ANYSOCK である場合、このルーチンは新しいソケッ トを開いて sockp を設定します。 UDP トランスポートは、応答を受け 取るまで、または呼び出しがタイムアウトになるまで、 wait 時間間隔 で呼び出しメッセージを再送信します。呼び出しがタイムアウトとなる 時間は、で指定します。 警告: UDP ベースの RPC メッセージは、 8 キロバイトのエンコード済 みデータまでしか維持できないので、大きな引数を取るプロシージャや 大きな結果を戻すプロシージャでは使用できません。 CLIENT * リモートプログラム prognum バージョン versnum の RPC クライアント を作成します。クライアントは、トランスポートとして UDP/IP を使用 します。リモートプログラムは、インターネットアドレス addr にあり ます。 addr−>sin_port が 0 である場合は、リモートプログラムが注意 を向ける実際のポートに設定されます (リモート portmap(8) サービス は、この情報で調べられます)。パラメータ sockp はソケットです。こ のパラメータが RPC_ANYSOCK である場合、このルーチンは新しいソケッ トを開いて sockp を設定します。 UDP トランスポートは、応答を受け 取るまで、または呼び出しがタイムアウトになるまで wait 時間間隔で 呼び出しメッセージを再送信します。呼び出しがタイムアウトになる時 間は、 clnt_call() で指定します。 ユーザは、 UDP ベースの RPC メッセージの送受信を行う、最大パケッ トサイズを指定できます。 int /etc/hosts を処理するライブラリルーチンを参考にせず、マシンの IP アドレスを addr に入れます。ポート番号は、常に htons(PMAPPORT) に 設定されます。問題がない場合は 0 を戻し、問題がある場合は 0 以外 を戻します。 struct pmaplist * portmap(8) サービスのユーザインタフェースで、 IP アドレス addr に あるホストの RPC プログラムとポートの現行のマッピングのリストを戻 します。このルーチンは NULL を戻すことがあります。コマンド ‘‘rpcinfo −p’’ はこのルーチンを使用します。 u_short portmap(8) サービスのユーザインタフェースで、プログラム番号 prognum バージョン versnum をサポートするサービスを待ち、 protocol に関連する転送プロトコルを表すポート番号を戻します。 protocol の値は、ほとんどの場合 IPPROTO_UDP か IPPROTO_TCP です。 マッピングが存在しない場合、または RPC システムがリモート portmap(8) サービスと接触できない場合、戻り値は 0 になります。後 者の場合、 rpc_createerr には RPC ステータスが入ります。 enum clnt_stat portmap(8) サービスのユーザインタフェースで、 IP アドレス addr の ホストのプロシージャを RPC 呼び出しにするように、そのホストの portmap(8) に命令します。プロシージャで問題が発生しない場合、パラ メータ portp はプログラムのポート番号に修正されます。その他のパラ メータについては、 callrpc() と clnt_call() を参照してください。 このプロシージャは、 ‘‘ping’’ 以外で使用することはありません。 clnt_broadcast() も参照してください。 bool_t pmap_set(u_long prognum, u_long versnum, u_long protocol, u_short port) portmap(8) サービスのユーザインタフェースで、 (prognum, versnum, protocol) の 3 つ、およびマシンの portmap(8) サービスでの port の 間にマッピングを確立します。 protocol の値は、ほとんどの場合 IPPROTO_UDP か IPPROTO_TCP. です。このルーチンは問題がないと 1 を戻し、問題がある場合は 0 を戻します。これは、 svc_register() で 自動的に実行されます。 bool_t pmap_unset(u_long prognum, u_long versnum) portmap(8) サービスのユーザインタフェースで、 (prognum, versnum, *) の 3 つ、および portmap(8) サービスでの port の間に存在する マッピングをすべて破壊します。このルーチンは、問題がなければ 1 を 戻し、問題がある場合は 0 を戻します。 bool_t RPC サービスパッケージでプロシージャ procname を登録します。プロ グラム prognum バージョン versnum プロシージャ procnum が要求され ると、パラメータのポインタで procname が呼び出されます。 progname は、静的結果のポインタを戻します。 inproc はパラメータのデコード に使用され、 outproc は結果のエンコードに使用されます。このルーチ ンは、登録で問題が発生しなければ 0 を戻し、問題が発生したら −1 を 戻します。 警告: この形式で登録されたリモートプロシージャは、 UDP/IP トラン スポートでアクセスされます。制限事項については svcudp_create() を 参照してください。 struct rpc_createerr rpc_createerr; エラーになった RPC クライアント作成ルーチンで値が設定されるグロー バル変数です。エラーの原因を出力するには、ルーチン clnt_pcreateerror() を使用します。 bool_t svc_destroy(SVCXPRT * xprt) RPC サービス転送ハンドル xprt を破壊するマクロです。一般的に破壊 処理には、 xprt も含むプライベートデータ構造の解放も含まれます。 このルーチンを呼び出した後で xprt を使用した結果は不定となりま す。 fd_set svc_fdset; RPC サービスサイドの読み込みファイル記述子ビットマスクを表すグ ローバル変数です。 select(2) システムコールのテンプレートパラメー タとして最適です。サービスの設計者が svc_run() を呼び出さず、非同 期のイベント処理を行う場合のみに重要です。この変数は読み込み専用 ですが (アドレスを select(2) に渡しませんが)、 svc_getreqset() か 作成ルーチンを呼び出した後で変更できます。 FD_SETSIZE, を越える記 述子の制限がプロセスにある場合、この変数は FD_SETSIZE 記述子でし か使用できないことに注意してください。 int svc_fds; svc_fdset に似ていますが、32 個の記述子に制限されています。このイ ンタフェースは svc_fdset で置き換えられました。 bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in) RPC/XDR システムが svc_getargs() を使用して引数をサービスプロシー ジャにデコードした場合に割り振ったデータを解放するマクロです。こ のルーチンは、結果が問題なく解放されると 1 を戻し、問題が発生した 場合は 0 を戻します。 bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in) RPC サービス転送ハンドル xprt RPC 要求の引数をデコードするマクロ です。パラメータ in は、引数を配置する場所のアドレスです。 inproc は、引数をデコードする XDR ルーチンです。このルーチンは、デコード で問題が発生しなければ 1 を戻し、問題が発生した場合は 0 を戻しま す。 struct sockaddr_in * RPC サービス転送ハンドル xprt に関連するプロシージャの呼び出し側 のネットワークアドレスを入手する確実な方法です。 void svc_getreqset(fd_set *rdfds) このルーチンは、サービスの設計者が svc_run() を呼び出さず、独自の 非同期イベント処理を実現する場合にのみ重要です。 RPC 要求が RPC ソケットに到着したと select(2) システムコールが判断した場合に呼び 出されます。 rdfds は、作成された読み込み記述子ビットマスクです。 このルーチンは、 rdfds の値に関連したすべてのソケットサービスを受 けた場合に戻ります。 void svc_getreq(int rdfds) svc_getreqset(), に似ていますが、32 個の記述子に制限されていま す。このインタフェースは svc_getreqset() で置き換えられました。 bool_t prognum と versnum をサービスディスパッチプロシージャ dispatch() に関連付けます。 protocol が 0 である場合、サービスは portmap(8) サービスで登録されません。 protocol が 0 以外である場合、 (prognum, versnum, protocol) の 3 つと xprt−>xp_port のマッピング がローカル portmap(8) サービスで確立されます (一般的に protocol は 0 か IPPROTO_UDP か IPPROTO_TCP です)。プロシージャ dispatch() の形式は以下の通りです。 bool_t() dispatch(struct svc_req *request, SVCXPRT *xprt) svc_register() ルーチンは、問題がなければ 1 を戻し、問題がある場 合は 0 を戻します。 |
svc_run()
このルーチンは戻りません。 RPC 要求の到着を待ち、到着すると svc_getreq() を使用して適切なサービスプロシージャを呼び出します。 通常の場合、このプロシージャは、 select(2) システムコールが戻るの を待ちます。 bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out) RPC サービスのディスパッチルーチンで呼び出され、リモートプロシー ジャコールの結果を送信します。パラメータ xprt は要求の関連転送ハ ンドルです。 outproc は、結果のエンコードに使用する XDR ルーチン です。 out は結果のアドレスです。このルーチンは、問題がなければ 1 を戻し、問題がある場合は 0 を戻します。 void (prognum, versnum) の 2 つとディスパッチルーチンのマッピング、お よび (prognum, versnum, *) の 3 つとポート番号のマッチングをすべ て削除します。 void 認証エラーのために、リモートプロシージャコールの実行を拒否する サービスディスパッチルーチンが呼び出します。 void パラメータを問題なくデコードできないサービスディスパッチルーチン が呼び出します。 svc_getargs() も参照してください。 void 呼び出し側が要求したプロシージャ番号を実現しないサービスディス パッチルーチンが呼び出します。 void 目的のプログラムが RPC パッケージで登録されていない場合に呼び出さ れます。サービスの設計者には、通常の場合このルーチンは必要ありま せん。 void プログラムの目的のバージョンが RPC パッケージで登録されていない場 合に呼び出されます。サービスの設計者には、通常の場合このルーチン は必要ありません。 void サービスディスパッチルーチンが、特定プロトコルでカバーされていな いシステムエラーを検出した場合に呼び出します。たとえばサービスが 記憶域を割り振れない場合は、このルーチンが呼び出されます。 void 認証パラメータが足りないために、リモートプロシージャコールの実行 を拒否するサービスディスパッチルーチンが呼び出します。このルーチ ンは、 svcerr_auth(xprt, AUTH_TOOWEAK) を呼び出します。 SVCXPRT * ポインタを戻すためのトイ RPC クライアントを作成します。実際のトラ ンスポートは、プロセスのアドレススペース内にあるバッファなので、 対応する RPC クライアントは同じアドレススペースに存在する必要があ ります。 clntraw_create() を参照してください。このルーチンによ り、 RPC のシミュレーション、およびラウンドトリップタイムなど、 RPC オーバヘッドの取得をカーネルの干渉なしに実行できます。この ルーチンは、エラーが発生すると NULL を戻します。 SVCXPRT * ポインタを戻す、 TCP/IP ベースの RPC サービストランスポートを作成 します。トランスポートにはソケット sock が関連します。ソケットが RPC_ANYSOCK である場合は、新しいソケットが作成されます。ソケット がローカル TCP ポートに結合していない場合、このルーチンはソケット を任意のポートに結合します。処理が終わると、 xprt−>xp_sock はトラ ンスポートのソケット記述子になり、 xprt−>xp_port はトランスポート のポート番号になります。このルーチンは、エラーが発生すると NULL を戻します。 TCP ベースの RPC はバッファによる I/O を使用するの で、ユーザはバッファサイズを指定できます。値を 0 にすると、適切な デフォルトが選択されます。 SVCXPRT * 開いている記述子の最上位にサービスを作成します。一般的にこの記述 子は、 TCP などのストリームプロトコルの接続済みソケットです。 sendsize と recvsize は、送信バッファと受信バッファのサイズを指定 します。このサイズが 0 である場合は、適切なデフォルトが選択されま す。 SVCXPRT * ポインタを戻す UDP/IP ベースの RPC サービストランスポートを作成し ます。トランスポートにはソケット sock が関連します。ソケットが RPC_ANYSOCK である場合は、新しいソケットが作成されます。ソケット がローカル UDP ポートに結合していない場合、このルーチンはソケット を任意のポートに結合します。処理が終わると、 xprt−>xp_sock はトラ ンスポートのソケット記述子になり、 xprt−>xp_port はトランスポート のポート番号になります。このルーチンは、エラーが発生すると NULL を戻します。 これにより、ユーザは、 UDP ベースの送信 RPC メッセージと受信メッ セージの最大パケットサイズを指定できます。 bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *ar) RPC 応答メッセージのエンコードに使用します。このルーチンでは、 RPC パッケージを使用せずに、 RPC スタイルのメッセージを作成する場 合に便利です。 bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *aupp) UNIX 証明書の記述に使用します。このルーチンは、 RPC 認証パッケー ジを使用せずに、証明書を作成する場合に便利です。 void RPC コールヘッダメッセージの記述に使用します。このルーチンでは、 RPC パッケージを使用せずに、 RPC スタイルのメッセージを作成する場 合に便利です。 bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsg) RPC コールメッセージの記述に使用します。このルーチンは、 RPC パッ ケージを使用せずに、 RPC スタイルのメッセージを作成する場合に便利 です。 bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *ap) RPC 認証情報メッセージの記述に使用します。このルーチンでは、 RPC パッケージを使用せずに、 RPC スタイルのメッセージを作成する場合に 便利です。 struct pmap; さまざまな portmap(8) プロシージャのパラメータの記述に外部的に使 用します。このルーチンは、 pmap_*() インタフェースを使用せずに、 このパラメータを作成する場合に便利です。 bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rp) ポートマッピングのリストの記述に外部的に使用します。このルーチン は、 pmap_*() インタフェースを使用せずに、このパラメータを作成す る場合に便利です。 bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rr) RPC 応答メッセージの記述に使用します。このルーチンは RPC パッケー ジを使用せずに、 RPC スタイルのメッセージを作成する場合に便利で す。 bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsg) RPC 応答メッセージの記述に使用します。このルーチンは RPC パッケー ジを使用せずに、 RPC スタイルのメッセージを作成する場合に便利で す。 void RPC サービストランスポートハンドルが作成されたら、 RPC サービス パッケージで登録する必要があります。このルーチンは、グローバル変 数 svc_fds を修正します。サービスの設計者には、通常の場合このルー チンは必要ありません。 void RPC サービストランスポートハンドルを破壊する前には、 RPC サービス パッケージで登録を解除する必要があります。このルーチンは、グロー バル変数 svc_fds を修正します。サービスの設計者には、通常の場合こ のルーチンは必要ありません。 関連項目 |
Remote Procedure Calls: Protocol Specification. Remote Procedure Call Programming Guide. rpcgen Programming Guide. RPC: Remote Procedure Call Protocol Specification, Sun Microsystems,Inc., USC-ISI, RFC1050. FreeBSD 10.0 February 16, 1988 FreeBSD 10.0