rpcgen - an RPC protocol compiler
rpcgen [infile]
rpcgen [-Dname[=value]] [-I [-K seconds]] [-L] [-T] infile
rpcgen -c | -C | -h | -l | -m [-o outfile] [infile]
rpcgen -s transport [-o outfile] [infile]
Compiles into routines. Generates header and stub files
that can be used with ANSI C compilers. Headers generated
with this option can also be used with C++ compilers.
Defines a symbol name. Equivalent to the #define directive
in the source. If no value is given, name is defined as 1.
This option may be called more than once. Compiles into C
data-definitions (a header file) Compiles support for
inetd(8) in the server side stubs. Such servers can be
self started or can be started by inetd. When the server
is self-started, it backgrounds itself by default. A special
define symbol RPC_SVC_FG can be used to run the
server process in foreground, or alternately the user may
just compile it without the -I option. If there are no
pending client requests, the inetd servers exit after 120
seconds (default). The default can be changed with the -K
option. All the error messages for inetd servers are
always logged in with syslog(3). If the server was
started by inetd, specifies the time in seconds after
which the server should exit if there is no further activity.
This option is useful for customization. If seconds
is 0, the server exits after serving that given request.
If seconds is -1, the server hangs around for ever after
being started by inetd. This option is valid only with the
-I option. Compiles into client-side stubs. When the
servers are started in foreground, uses syslog() to log
the server errors instead of printing them on the standard
error. Compiles into server-side stubs, but does not generate
a main routine. This option is useful for doing
callback-routines and for people who need to write their
own main routine to do initialization. For inetd support,
they should be compiled with the -I option. In such cases,
it defines 2 global variables: _rpcpmstart and _rpcfdtype.
The value of _rpcpmstart should be 1 or 0 depending upon
whether it was started by inetd or not. The value of
_rpcfdtype should be SOCK_STREAM or SOCK_DGRAM depending
upon the type of the connection. Specifies the name of
the output file. If none is specified, standard output is
used (-c, -h, -l, -m, -s, and -t modes only). Compiles
into server-side stubs, using the given transport. The
supported transports are udp and tcp. This option may be
invoked more than once to compile a server that serves
multiple transports. For inetd support, they should be
compiled with the -I option. -t Compile into dispatch
table. Generate the code to support dispatch tables.
The options -c, -h, -l, -m, -s and -t are used exclusively
to generate a particular type of file, while the options
-D, -I, -L and -T are global and can be used with the
other options.
The rpcgen compiler is a tool that generates C code to
implement an protocol. The input to rpcgen is the (Remote
Procedure Call) Language, which is similar to C.
The rpcgen command is normally used as in the first synopsis
where it takes an input file and generates four output
files. If the infile is named proto.x, rpcgen will generate
a header file in <proto.h>, routines in proto_xdr.c,
server-side stubs in proto_svc.c, and client-side stubs in
proto_clnt.c.
The second synopsis provides special features which allow
for the creation of more sophisticated servers. These features
include support for dispatch tables, and user provided
#defines. The entries in the dispatch table contain:
pointers to the service routine corresponding to that procedure
a pointer to the input and output arguments the
size of these routines
A server can use the dispatch table to check authorization
and then to execute the service routine; a client library
may use it to deal with the details of storage management
and data conversion.
The other synopses are used when one wants to generate a
particular output file. Their usage is described in the
section below.
The C-preprocessor, cpp(1), is run on all input files
before they are actually interpreted by rpcgen, so all the
cpp directives are legal within an rpcgen input file. For
each type of output file, rpcgen defines a special cpp
symbol for use by the rpcgen programmer: Defined when compiling
into header files Defined when compiling into routines
Defined when compiling into server-side stubs
Defined when compiling into client-side stubs Defined when
compiling into dispatch tables
In addition, rpcgen does a little preprocessing of its
own. Any line beginning with `%' is passed directly into
the output file, uninterpreted by rpcgen.
You can customize some of your routines by leaving those
data types undefined. For every data type that is undefined,
rpcgen will assume that there exists a routine with
the name xdr_ prepended to the name of the undefined type.
Nesting is not supported. However, structures can be
declared at top-level, and their name used inside other
structures in order to achieve the same effect.
Name clashes can occur when using program definitions,
since the apparent scoping does not really apply. Most of
these can be avoided by giving unique names for programs,
versions, procedures and types.
The following example generates all the five files:
<prot.h>, prot_clnt.c, prot_svc.c, prot_xdr.c and
prot_tbl.i. The server error messages are logged, instead
of being sent to the standard error. rpcgen -LT prot.x
The following example generates <prot.h>, prot_clnt.c,
prot_xdr.c and prot_svc.c. The prot_svc.c supports server
invocation by inetd. If the server is started by inetd,
the server exits after 20 seconds of inactivity. example%
rpcgen -I -K 20 prot.x The following example sends the
header file (with support for dispatch tables) on the
standard output. example% rpcgen -hT prot.x The following
example sends the server side stubs file for the transport
tcp on the standard output. example% rpcgen -s tcp prot.x
Commands: cpp(1), inetd(8)
Functions: rpc(3)
rpcgen(1)
[ Back ] |
