.\" @(#)rpcgen.1 1.35 93/06/02 SMI
.\" %FreeBSD: src/usr.bin/rpcgen/rpcgen.1,v 1.21 2004/07/02 22:22:30 ru Exp %
.\" Copyright 1985-1993 Sun Microsystems, Inc.
.\"
.\" $FreeBSD$
.Dd March 28, 1993
.Dt RPCGEN 1
.Os
.Sh 名称
.Nm rpcgen
.Nd RPC プロトコルコンパイラ
.Sh 書式
.Nm
.Ar infile
.Nm
.Op Fl a
.Op Fl b
.Op Fl C
.Oo
.Fl D Ns Ar name Ns Op Ar =value
.Oc
.Op Fl i Ar size
.Op Fl I Fl P Op Fl K Ar seconds
.Op Fl L
.Op Fl M
.Op Fl N
.Op Fl T
.Op Fl Y Ar pathname
.Ar infile
.Nm
.Oo
.Fl c |
.Fl h |
.Fl l |
.Fl m |
.Fl t |
.Fl \&Sc |
.Fl \&Ss |
.Fl \&Sm
.Oc
.Op Fl o Ar outfile
.Op Ar infile
.Nm
.Op Fl s Ar nettype
.Op Fl o Ar outfile
.Op Ar infile
.Nm
.Op Fl n Ar netid
.Op Fl o Ar outfile
.Op Ar infile
.\" .SH AVAILABILITY
.\" .LP
.\" SUNWcsu
.Sh 解説
.Nm
ユーティリティは、ある
.Tn RPC
プロトコルを実現する C コードを生成するツールです。
.Nm
への入力は、
.Tn RPC
言語 (遠隔手続き呼び出し言語; Remote Procedure Call Language) として知られる、
C 言語に類似した言語です。
.Pp
.Nm
ユーティリティは通常第 1 の書式で使用され、
1 つの入力ファイルから 4 つの出力ファイルを生成します。
.\" ↑原文では three output files となっているが、すぐ後ろで 4 つ列挙している。
.\" 原文の誤りと思われる。  97/06/08 J.Sakai
入力ファイル
.Ar infile
が
.Pa proto.x
であるとすると、
.Nm
はヘッダファイル
.Pa proto.h 、
XDR ルーチンファイル
.Pa proto_xdr.c 、
サーバ側スタブ
.Pa proto_svc.c 、
クライアント側スタブ
.Pa proto_clnt.c
を作成します。
.Fl T
オプションを指定すると、上記に加え、
.Tn RPC
ディスパッチテーブル
.Pa proto_tbl.i
も作成します。
.Pp
.Nm
ユーティリティはまた、特定アプリケーション向けにカスタマイズ可能な
クライアントおよびサーバのサンプルファイルも生成できます。
オプション
.Fl \&Sc ,
.Fl \&Ss ,
.Fl \&Sm
によってそれぞれ、サンプルのクライアント、サーバ、makefile を生成します。
オプション
.Fl a
を指定するとサンプルを含め全てのファイルを生成します。
入力ファイル
.Ar infile
が
.Pa proto.x
の場合、
クライアント側サンプルファイルは
.Pa proto_client.c
に、
サーバ側サンプルファイルは
.Pa proto_server.c
に、
そしてサンプル makefile は
.Pa makefile.proto
に書き出されます。
.Pp
オプション
.Fl I
が設定されている場合、
生成されたサーバは、ポートモニタ (例えば
.Xr inetd 8
) で起動することも、
それ自身で起動することもできます。
ポートモニタから起動される場合、
ファイル記述子
.Em 0
を引き渡すトランスポートのためだけの
サーバを生成します。
トランスポートの名前は環境変数
.Ev NLSPROVIDER
をセットすることで
指定可能です。
.Nm
で作成されたサーバが実行されると、
サーバは環境変数
.Ev NETPATH
で指定された全トランスポート用に
サーバハンドルを作成します。
.Ev NETPATH
が指定されていない場合は、ファイル
.Pa /etc/netconfig
に記述されている全ての可視トランスポート用にサーバハンドルを作成します。
注意:
トランスポートはコンパイル時ではなく実行時に選択されます。
サーバが自分で開始すると、
デフォルトでは自動的にバックグラウンド実行に移ります。
.Em RPC_SVC_FG
を定義することで、
サーバをフォアグラウンドで実行させることもできます。
.Pp
第二の書式は、更に洗練された
.Tn RPC
サーバを生成する特別な機能をもちます。
その特別な機能として、
ユーザが定義した
.Em #define
と
.Tn RPC
ディスパッチテーブル
のサポートがあります。
.Tn RPC
ディスパッチテーブルのエントリには以下のものがあります:
.Bl -bullet -offset indent -compact
.It
その手続きに対応するサービスルーチンへのポインタ
.It
入出力引数へのポインタ
.It
これらのルーチンのサイズ
.El
サーバはディスパッチテーブルを用いて認証チェックを行い、
それからサービスルーチンを実行することができます。
クライアントライブラリはそれを用いて、
記憶領域管理や XDR データ変換の詳細に対処することができます。
.Pp
上に示した他の 3 つの書式は、出力ファイルの全てではなく、
そのうちの特定のものだけを生成したい場合に用いられます。
.Nm
の使用例については下の
.Sx 使用例
のセクションを参照して下さい。
.Fl s
オプション付きで実行されると、
.Nm
は特定のトランスポートクラス用のサーバを生成します。
.Fl n
オプション付きで実行されると、
.Nm
は
.Ar netid
で指定されたトランスポート用サーバを生成します。
.Ar infile
が指定されない場合、
.Nm
は標準入力から入力を受け付けます。
.Pp
入力ファイルは、実際に
.Nm
に処理される前に、
C プリプロセッサ
.Em cc -E
で処理されます。
.Nm
は、出力ファイルの各タイプ毎に
.Nm
プログラマ向けの特別なプリプロセッサシンボルを定義します:
.Bl -tag -width indent
.It RPC_HDR
ヘッダをコンパイルする際に定義されます
.It RPC_XDR
XDR ルーチンをコンパイルする際に定義されます
.It RPC_SVC
サーバ側スタブをコンパイルする際に定義されます
.It RPC_CLNT
クライアント側スタブをコンパイルする際に定義されます
.It RPC_TBL
RPC ディスパッチテーブルをコンパイルする際に定義されます
.El
.Pp
.Dq %
で始まる行は全て、
.Nm
に解釈されることなく、
出力ファイルに直接引き継がれます。
C プリプロセッサのパス名を指定するには
.Fl Y
フラグを使用して下さい。
.Pp
.Ar infile
で参照される全てのデータ型に対し、
.Nm
は、そのデータ型名の前に
.Em xdr_
を付与した名前の
ルーチンが存在することを仮定します。
このルーチンが
.Tn RPC/XDR
ライブラリ中に存在しない場合は、
それを提供しなければなりません。
未定義データ型を提供することで
.Xr xdr 3
ルーチンをカスタマイズすることが可能です。
.Sh オプション
オプションは以下の通りです:
.Bl -tag -width indent
.It Fl a
サンプルファイルを含め、全てのファイルを生成します。
.It Fl b
従来互換モード。
以前のバージョンの OS のために、トランスポート固有の
.Tn RPC
コードを生成します。
.It Fl c
.Tn XDR
ルーチンをコンパイル出力します。
.It Fl C
.Tn ANSI
C コンパイラで使用できるヘッダおよびスタブファイルを生成します。
このオプションで生成したヘッダファイルは C++ プログラムでも使用できます。
.It Fl D Ns Ar name
.It Fl D Ns Ar name=value
.\".It Fl D Ns Ar name Ns Op Ar =value
シンボル
.Ar name
を定義します。
ソース中の
.Em #define
指示行と等価です。
.Ar value
が指定されない場合、
.Ar value
は
.Em 1
と定義されます。
このオプションは複数回の指定が可能です。
.It Fl h
C のデータ定義 (ヘッダファイル) をコンパイル出力します。
同時に
.Fl T
オプションを指定することで、
.Tn RPC
ディスパッチテーブルをサポートするヘッダファイルを生成できます。
.It Fl i Ar size
インラインコードを生成し始めるサイズを指定します。
最適化を行う際に用いられます。デフォルト値は 5 です。
.Pp
注:
.Fx
プラットホームでの以前の
.Nm
と互換性を保つため、デフォルト値は実際には 0 (つまり、
デフォルトではインラインコードは生成しない) となっています。
このデフォルト値を上書きするには明示的に 0 以外の値を
指定しなければなりません。
.It Fl I
サーバ側スタブにおける
.Xr inetd 8
サポートコードを生成します。
このようにして生成したサーバは、単独で起動することも、
.Xr inetd 8
から起動することもできます。
単独で起動した場合、デフォルトでは自らバックグラウンド動作に移ります。
特殊シンボル
.Em RPC_SVC_FG
を定義するか、
単に
.Fl I
オプションなしでコンパイルすると、
サーバプロセスはフォアグラウンドで動作します。
.Pp
クライアントからの未処理リクエストがなければ、
.Xr inetd 8
サーバは 120 秒 (デフォルト値) 経過の後、終了します。
このデフォルト値は
.Fl K
オプションにより変更できます。
.Xr inetd 8
サーバの全エラーメッセージは常に
.Xr syslog 3
によってログに残されます。
.Pp
注: ポートモニタと
.Xr inetd 8
から起動可能なサーバを作成するには、
他のシステムとは異なり、
.Fx
では本オプションが必要です。
.Pp
.It Fl K Ar seconds
デフォルトでは、
.Nm
を用いて作成され、ポートモニタから起動された
サービスは、リクエストを処理した後 120 秒待って終了します。
この時間は
.Fl K
オプションを用いて変更できます。
リクエスト処理が済むと直ちに終了するようなサーバを生成するには、
.Fl K Ar 0
と指定します。また、決して終了しないサーバを生成するには、
.Fl K Ar -1
として下さい。
.Pp
サーバをモニタする場合、
あるサービスリクエストに対して
.Em 常に
新しいプロセスを生成するようなポートモニタがあります。
そのようなモニタを用いてサーバを使用することがわかっている場合は、
サーバは処理完了後直ちに終了すべきです。
そのようなサーバを生成するには、
.Nm
は
.Fl K Ar 0
オプションとともに使用すべきです。
.It Fl l
クライアント側スタブをコンパイル出力します。
.It Fl L
サーバがフォアグラウンドで起動された場合、
サーバのエラーを記録するのに、標準エラー出力に出力する代わりに
.Xr syslog 3
を使用します。
.It Fl m
サーバ側スタブをコンパイル出力しますが、
.Qq main
ルーチンは生成しません。
コールバックルーチンのみを作成したり、初期化を行うために
独自の
.Qq main
ルーチンを必要とする場合に便利です。
.It Fl M
rpcgen が生成したコードとユーザが書いたコードの間で
引数や結果を受渡しするために、
マルチスレッド対応の (MT-safe な) スタブを生成します。
ユーザプログラム中でスレッドを使用する場合に有用です。
しかし関数
.Xr rpc_svc_calls 3
はまだ MT-safe にはなっていません。
つまり rpcgen が生成したサーバ側コードは MT-safe ではありません。
.It Fl N
手続きが複数の引数を持てるようにします。
これはまた、C 言語に大変似たパラメータ渡し方法を用います。
ですから遠隔手続きにある引数を渡す場合、
その引数へのポインタを渡す必要はなく、引数そのものを渡せます。
この動作は
.Nm
が生成したコードの以前の振る舞いとは異なっています。
以前との互換性を保つため、このオプションはデフォルトでは有効ではありません。
.It Fl n Ar netid
.Ar netid
で指定したトランスポート用のサーバ側スタブをコンパイル出力します。
netconfig データベースには
.Ar netid
用エントリが存在しなければなりません。
このオプションを複数回指定することで、
複数のトランスポートに対してサービスするサーバを作成することができます。
.It Fl o Ar outfile
出力ファイル名を指定します。
何も指定されなければ標準出力が用いられます
(
.Fl c ,
.Fl h ,
.Fl l ,
.Fl m ,
.Fl n ,
.Fl s ,
.Fl \&Sc ,
.Fl \&Sm ,
.Fl \&Ss ,
.Fl t
モード時のみ)。
.It Fl P
サーバ側のスタブにポートモニタサポートを組み込みます。
.Pp
注: モニタ可能なサーバを作成するには、
他のシステムとは異なり、
.Fx
では本オプションが必要です。
.Pp
.Fl I
オプションが指定された場合、
.Fl P
は自動的にオフになります。
.It Fl s Ar nettype
クラス
.Ar nettype
に属する全てのトランスポート用の
サーバ側スタブをコンパイル出力します。
サポートされているクラスは以下の通りです:
.Em netpath ,
.Em visible ,
.Em circuit_n ,
.Em circuit_v ,
.Em datagram_n ,
.Em datagram_v ,
.Em tcp ,
.Em udp
(これらのクラスの意味については
.Xr rpc 3
を参照して下さい)
このオプションは複数回指定できます。
注: トランスポートはコンパイル時ではなく実行時に選択されます。
.It Fl \&Sc
遠隔手続き呼び出しを用いるサンプルクライアントコードを生成します。
.It Fl \&Sm
アプリケーションをコンパイルする際に用いるサンプル
.Pa Makefile
を生成します。
.It Fl \&Ss
遠隔手続き呼び出しを用いるサンプルサーバコードを生成します。
.It Fl t
.Tn RPC
ディスパッチテーブルをコンパイル出力します。
.It Fl T
.Tn RPC
ディスパッチテーブルをサポートするコードを生成します。
.Pp
ある特定のタイプのファイルを生成するために、
以下のオプション
.Fl c ,
.Fl h ,
.Fl l ,
.Fl m ,
.Fl s ,
.Fl \&Sc ,
.Fl \&Sm ,
.Fl \&Ss ,
.Fl t
は排他的に使用されます。
他方、オプション
.Fl D
と
.Fl T
は大域的であり、他のオプションと組み合わせて使用できます。
.It Fl Y Ar pathname
.Nm
が C プリプロセッサを探し始めるディレクトリ名を指定します。
.El
.Sh 使用例
以下の例:
.Dl example% rpcgen -T prot.x
.Pp
は 5 種類のファイル:
.Pa prot.h ,
.Pa prot_clnt.c ,
.Pa prot_svc.c ,
.Pa prot_xdr.c ,
.Pa prot_tbl.i
の全てを生成します。
.Pp
次の例は C のデータ定義 (ヘッダ) を標準出力に出力します。
.Dl example% rpcgen -h prot.x
.Pp
.Fl D Ns Ar TEST
のテストバージョンを作成するため、
クラス
.Ar datagram_n
に属する全トランスポート用サーバ側スタブを標準出力に出力するには次のよ
うにします:
.Dl example% rpcgen -s datagram_n -DTEST prot.x
.Pp
.Ar netid
tcp
で指定されたトランスポート用のサーバ側スタブを作成するには次のようにし
ます:
.Dl example% rpcgen -n tcp -o prot_svc.c prot.x
.Sh 関連項目
.Xr cc 1 ,
.Xr rpc 3 ,
.Xr rpc_svc_calls 3 ,
.Xr syslog 3 ,
.Xr xdr 3 ,
.Xr inetd 8
.Rs
.%T NETP マニュアルの rpcgen の章
.Re