RPCGEN(1)

名称
rpcgen - RPC プロトコルコンパイラ

書式
rpcgen infile rpcgen [-a] [-b] [-C] [ -Dname[=value]] [-i size] [-I [-K seconds]] [-L] [-M] [-N] [-T] [-Y pathname] infile rpcgen [ -c | -h | -l | -m | -t | -’ | -Ss | -Sm] [-o outfile] [infile] rpcgen [-s nettype] [-o outfile] [infile] rpcgen [-n netid] [-o outfile] [infile]

解説
rpcgen は、ある RPC プロトコルを実現する C コードを生成するツールです。 rpcgen への入力は、 RPC 言語 (遠隔手続き呼び出し言語; Remote Procedure Call Language) として知られる、 C 言語に類似した言語です。

rpcgen は通常第 1 の書式で使用され、 1 つの入力ファイルから 4 つの出力ファイルを生成します。 入力ファイル infile が proto.x であるとすると、 rpcgen はヘッダファイル proto.h 、 XDR ルーチンファイル proto_xdr.c 、 サーバ側スタブ proto_svc.c 、 クライアント側スタブ proto_clnt.c を作成します。 -T オプションを指定すると、上記に加え、 RPC ディスパッチテーブル proto_tbl.i も作成します。

rpcgen はまた、特定アプリケーション向けにカスタマイズ可能な クライアントおよびサーバのサンプルファイルも生成できます。 オプション -’, -Ss, -Sm によってそれぞれ、サンプルのクライアント、サーバ、makefile を生成します。 オプション -a を指定するとサンプルを含め全てのファイルを生成します。 入力ファイル infile が proto.x の場合、 クライアント側サンプルファイルは proto_client.c に、 サーバ側サンプルファイルは proto_server.c に、 そしてサンプル makefile は makefile.proto に書き出されます。

生成されたサーバは、ポートモニタ (例えば inetd(8) ) で起動することも、 それ自身で起動することもできます。 ポートモニタから起動される場合、 ファイル記述子 0 を引き渡すトランスポートのためだけの サーバを生成します。 トランスポートの名前は環境変数 PM_TRANSPORT をセットすることで 指定しなければなりません。 rpcgen で作成されたサーバが実行されると、 サーバは環境変数 NETPATH で指定された全トランスポート用に サーバハンドルを作成します。 NETPATH が指定されていない場合は、ファイル /etc/netconfig に記述されている全ての可視トランスポート用にサーバハンドルを作成します。 注意: トランスポートはコンパイル時ではなく実行時に選択されます。 サーバが自分で開始すると、 デフォルトでは自動的にバックグラウンド実行に移ります。 RPC_SVC_FG を定義することで、 サーバをフォアグラウンドで実行させることもできます。

第二の書式は、更に洗練された RPC サーバを生成する特別な機能をもちます。 その特別な機能として、 ユーザが定義した #define と RPC ディスパッチテーブル のサポートがあります。 RPC ディスパッチテーブルのエントリには以下のものがあります:
•   その手続きに対応するサービスルーチンへのポインタ
•   入出力引数へのポインタ
•   これらのルーチンのサイズ
サーバはディスパッチテーブルを用いて認証チェックを行い、 それからサービスルーチンを実行することができます。 クライアントライブラリはそれを用いて、 記憶領域管理や XDR データ変換の詳細に対処することができます。

上に示した他の 3 つの書式は、出力ファイルの全てではなく、 そのうちの特定のものだけを生成したい場合に用いられます。 rpcgen の使用例については下の 使用例 のセクションを参照して下さい。 -s オプション付きで実行されると、 rpcgen は特定のトランスポートクラス用のサーバを生成します。 -n オプション付きで実行されると、 rpcgen は netid で指定されたトランスポート用サーバを生成します。 infile が指定されない場合、 rpcgen は標準入力から入力を受け付けます。

入力ファイルは、実際に rpcgen に処理される前に、 C プリプロセッサ cc -E で処理されます。 rpcgen は、出力ファイルの各タイプ毎に rpcgen プログラマ向けの特別なプリプロセッサシンボルを定義します:

RPC_HDR
    ヘッダをコンパイルする際に定義されます

RPC_XDR
    XDR ルーチンをコンパイルする際に定義されます

RPC_SVC
    サーバ側スタブをコンパイルする際に定義されます

RPC_CLNT
    クライアント側スタブをコンパイルする際に定義されます

RPC_TBL
    RPC ディスパッチテーブルをコンパイルする際に定義されます

“%” で始まる行は全て、 rpcgen に解釈されることなく、 出力ファイルに直接引き継がれます。 C プリプロセッサのパス名を指定するには -Y フラグを使用して下さい。

infile で参照される全てのデータ型に対し、 rpcgen は、そのデータ型名の前に xdr_ を付与した名前の ルーチンが存在することを仮定します。 このルーチンが RPC/XDR ライブラリ中に存在しない場合は、 それを提供しなければなりません。 未定義データ型を提供することで xdr(3) ルーチンをカスタマイズすることが可能です。

オプション
オプションは以下の通りです:

-a  サンプルファイルを含め、全てのファイルを生成します。

-b  従来互換モード。 以前のバージョンの OS のために、トランスポート固有の RPC コードを生成します。

    注: FreeBSD ではこの互換フラグはデフォルトで有効になっています。 FreeBSD は以前の ONC RPC ライブラリのみサポートしているからです。

-c  XDR ルーチンをコンパイル出力します。

-C  ANSI C コンパイラで使用できるヘッダおよびスタブファイルを生成します。 このオプションで生成したヘッダファイルは C++ プログラムでも使用できます。

-Dname

-Dname=value
    シンボル name を定義します。 ソース中の #define 指示行と等価です。 value が指定されない場合、 value は 1 と定義されます。 このオプションは複数回の指定が可能です。

-h  C のデータ定義 (ヘッダファイル) をコンパイル出力します。 同時に -T オプションを指定することで、 RPC ディスパッチテーブルをサポートするヘッダファイルを生成できます。

-i size
    インラインコードを生成し始めるサイズを指定します。 最適化を行う際に用いられます。デフォルト値は 5 です。

    注: FreeBSD プラットホームでの以前の rpcgen と互換性を保つため、デフォルト値は実際には 0 (つまり、 デフォルトではインラインコードは生成しない) となっています。 このデフォルト値を上書きするには明示的にゼロ以外の値を 指定しなければなりません。

-I  サーバ側スタブにおける inetd(8) サポートコードを生成します。 このようにして生成したサーバは、単独で起動することも、 inetd から起動することもできます。 単独で起動した場合、デフォルトでは自らバックグラウンド動作に移ります。 特殊シンボル RPC_SVC_FG を定義するか、 単に -I オプションなしでコンパイルすると、 サーバプロセスはフォアグラウンドで動作します。

    クライアントからの未処理リクエストがなければ、 inetd サーバは 120 秒 (デフォルト値) 経過の後、終了します。 このデフォルト値は -K オプションにより変更できます。 inetd サーバの全エラーメッセージは常に syslog(3) によってログに残されます。

-K seconds
    デフォルトでは、 rpcgen を用いて作成され、ポートモニタから起動された サービスは、リクエストを処理した後 120 秒待って終了します。 この時間は -K オプションを用いて変更できます。 リクエスト処理が済むと直ちに終了するようなサーバを生成するには、 -K 0 と指定します。また、決して終了しないサーバを生成するには、 -K -1 として下さい。

    サーバをモニタする場合、 あるサービスリクエストに対して 常に 新しいプロセスを生成するようなポートモニタがあります。 そのようなモニタを用いてサーバを使用することがわかっている場合は、 サーバは処理完了後直ちに終了すべきです。 そのようなサーバを生成するには、 rpcgen は -K 0 オプションとともに使用すべきです。

-l  クライアント側スタブをコンパイル出力します。

-L  サーバがフォアグラウンドで起動された場合、 サーバのエラーを記録するのに、標準エラー出力に出力する代わりに syslog(3) を使用します。

-m  サーバ側スタブをコンパイル出力しますが、 "main" ルーチンは生成しません。 コールバックルーチンのみを作成したり、初期化を行うために 独自の "main" ルーチンを必要とする場合に便利です。

-M  rpcgen が生成したコードとユーザが書いたコードの間で 引数や結果を受渡しするために、 マルチスレッド対応の (MT-safe な) スタブを生成します。 ユーザプログラム中でスレッドを使用する場合に有用です。 しかし関数 rpc_svc_calls(3) はまだ MT-safe にはなっていません。 つまり rpcgen が生成したサーバ側コードは MT-safe ではありません。

-N  手続きが複数の引数を持てるようにします。 これはまた、C 言語に大変似たパラメータ渡し方法を用います。 ですから遠隔手続きにある引数を渡す場合、 その引数へのポインタを渡す必要はなく、引数そのものを渡せます。 この動作は rpcgen が生成したコードの以前の振る舞いとは異なっています。 以前との互換性を保つため、このオプションはデフォルトでは有効ではありません。

-n netid
    netid で指定したトランスポート用のサーバ側スタブをコンパイル出力します。 netconfig データベースには netid 用エントリが存在しなければなりません。 このオプションを複数回指定することで、 複数のトランスポートに対してサービスするサーバを作成することができます。

-o outfile
    出力ファイル名を指定します。 何も指定されなければ標準出力が用いられます ( -c, -h, -l, -m, -n, -s, -’, -Sm, -Ss, -t モード時のみ)。

-s nettype
    クラス nettype に属する全てのトランスポート用の サーバ側スタブをコンパイル出力します。 サポートされているクラスは以下の通りです: netpath, visible, circuit_n, circuit_v, datagram_n, datagram_v, tcp, udp (これらのクラスの意味については rpc(3) を参照して下さい) このオプションは複数回指定できます。 注: トランスポートはコンパイル時ではなく実行時に選択されます。

-’  遠隔手続き呼び出しを用いるサンプルクライアントコードを生成します。

-Sm アプリケーションをコンパイルする際に用いるサンプル Makefile を生成します。

-Ss 遠隔手続き呼び出しを用いるサンプルサーバコードを生成します。

-t  RPC ディスパッチテーブルをコンパイル出力します。

-T  RPC ディスパッチテーブルをサポートするコードを生成します。

    ある特定のタイプのファイルを生成するために、 以下のオプション -c, -h, -l, -m, -s, -’, -Sm, -Ss, -t は排他的に使用されます。 他方、オプション -D と -T は大域的であり、他のオプションと組み合わせて使用できます。

-Y pathname
    rpcgen が C プリプロセッサを探し始めるディレクトリ名を指定します。

使用例
以下の例:
    example% rpcgen -T prot.x

は 5 種類のファイル: prot.h, prot_clnt.c, prot_svc.c, prot_xdr.c, prot_tbl.i の全てを生成します。

次の例は C のデータ定義 (ヘッダ) を標準出力に出力します。
    example% rpcgen -h prot.x

-DTEST のテストバージョンを作成するため、 クラス datagram_n に属する全トランスポート用サーバ側スタブを標準出力に出力するには次のよ うにします:
    example% rpcgen -s datagram_n -DTEST prot.x

netid tcp で指定されたトランスポート用のサーバ側スタブを作成するには次のようにし ます:
    example% rpcgen -n tcp -o prot_svc.c prot.x

関連項目
cc(1), rpc(3), syslog(3), inetd(8) NETP マニュアルの rpcgen の章.