rpcgen(1)

NAME

rpcgen − an RPC protocol compiler

SYNOPSIS

rpcgen infile
rpcgen -h [-o outfile] [infile]
rpcgen -c [-o outfile] [infile]
rpcgen -s transport [-u] [-o outfile] [infile]
rpcgen -l [-o outfile] [infile]
rpcgen -m [-o outfile] [infile]
rpcgen [ -D name[ =value ]] [-u] [-I [-K seconds]] [-L] [-T] infile

DESCRIPTION

rpcgen is a tool that generates C code to implement an RPC protocol. The input to rpcgen is a language similar to C known as RPC (Remote Procedure Call) Language. Information about RPC Language syntax is available in Power Programming with RPC.

rpcgen is normally used in the first synopsis shown above where it takes an input file and generates five output files. If the infile is named proto.x, rpcgen generates a header file in proto.h, XDR routines in proto_xdr.c, server-side stubs in proto_svc.c, and client-side stubs in proto_clnt.c, and RPC dispatch table in proto_tbl.i.

The synopsis forms requiring -h, -c, -s, -l, or -m are used when only a particular output file is needed. Their usage is described in the Options section below.

The RPC dispatch table is intended for use of more sophisticated RPC servers. The entries in the RPC 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 XDR data conversion.

The input file is processed by cpp before being interpreted by rpcgen (see cpp(1)), meaning that all standard cpp directives are available for use in an rpcgen input file. Preprocessing by cpp is done for each output file created. For each type of output file, rpcgen defines a special cpp symbol for use by the rpcgen programmer:

RPC_HDR defined when compiling into header files

RPC_XDR defined when compiling into XDR routines

RPC_SVC defined when compiling into server-side stubs

RPC_CLNT defined when compiling into client-side stubs

RPC_TBL defined when compiling into dispatch tables

In addition, rpcgen does preprocessing of its own. Any line beginning with % is passed directly into the output file, uninterpreted by rpcgen. By using the cpp symbols mentioned above, you can pass text into a specific output file.

To provide customized XDR routines for customized data types, you can declare data objects to be of a data type that is undefined to rpcgen. rpcgen passes them through to the .h file it creates. You are responsible for providing the definition of such data types in user-supplied files. For every data type that is undefined, rpcgen assumes that there exists a routine with the name xdr_ prefixed to the name of the undefined type.

Options

rpcgen recognizes the following options and command-line arguments:

-c Compile into XDR routines.

-h Compile into C data-definitions (a header file)

-l Compile into client-side stubs.

-s transport Compile into server-side stubs, using the specified transport. The supported transports are udp and tcp. This option can be invoked more than once so as to compile a server that serves multiple transports. If rpcgen is called without options, the server-side code that is generated can serve both udp and tcp transports.

-m Compile into server-side stubs, but do not produce a main() routine. This option is useful if you want to supply your own main() .

-o outfile Specify the name of the output file. If none is specified, standard output is used (-c, -h, -l, -m, and -s modes only).

-u When the server-side stub is produced, additional code to handle signals is generated. On reception of a signal, this signal handler code unmaps the server program from the port mapper before the server terminates. This code is added only if a main() routine is produced in the server-side stub. The -u option must not be specified with the -c, -h, -l, or -m options.

-Dname[=value] Define a symbol. Equivalent to the #define directive in the source. If no value is given, value is defined as 1.

-I Compile support for inetd(1M) in the server side stubs. Such servers can be self-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 the user may simply compile without the -I option.

-K seconds By default, services created using rpcgen and invoked through port monitors wait 120 seconds after servicing a request before exiting. That interval can be changed using the -K flag. To create a server that exits immediately upon servicing a request, use -K 0. To create a server that never exits, the appropriate argument is -K -1.

-L When the servers are started in foreground, use syslog(3) to log the server errors instead of printing them on the standard error.

-T Generate the code to support RPC dispatch tables.

The following signals are trapped: SIGHUP, SIGINT, SIGQUIT, and SIGTERM.

EXAMPLES

The following example generates all five output files: prot.h, prot_clnt.c, prot_svc.c, prot_xdr.c, and prot_tbl.i.

rpcgen -T prot.x

The following example generates prot.h, prot_xdr.c, prot_clnt.c, and the server stub prot_svc.c, which supports the server started by inetd(1M).

rpcgen -I prot.x

The following example sends the C data-definitions (header) to the standard output.

rpcgen -h prot.x

To create the server side stubs for the tcp protocol and send the output to prot_svc.c, use

rpcgen -s tcp -o prot_svc.c prot.x

WARNINGS

Nesting of structures is not supported. Instead, structures can be declared at the top-level and their names used inside other structures 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.

AUTHOR

rpcgen was developed by Sun Microsystems, Inc. and HP.

Museum