rpcgen(1)rpcgen(1)NAMErpcgen - an RPC protocol compiler
SYNOPSISrpcgen [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]
OPTIONS
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 customiza‐
tion. 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. Com‐
piles into client-side stubs. When the servers are started in fore‐
ground, 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-rou‐
tines 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. Gen‐
erate 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.
DESCRIPTION
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>, rou‐
tines 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 cre‐
ation of more sophisticated servers. These features include support for
dispatch tables, and user provided #defines. The entries in the dis‐
patch 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, uninter‐
preted 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.
RESTRICTIONS
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 appar‐
ent scoping does not really apply. Most of these can be avoided by giv‐
ing unique names for programs, versions, procedures and types.
EXAMPLES
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. rpc‐
gen -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
SEE ALSO
Commands: cpp(1), inetd(8)
Functions: rpc(3)rpcgen(1)
