rpcgen

An RPC protocol compiler

Syntax:

rpcgen infile

rpcgen -a|-c|-h|-l|-m|-Sc|-Ss [-o outfile] [infile]
       [-C] [-D macro[=value]] [-L] [-K secs]

rpcgen -s transport [-o outfile] [infile]

Options:

-a

Generate all the files including sample code for client and server side.

-C

Generate ANSI C code. This option also generates code that could be compiled with the C++ compiler.

-c

Compile into XDR routines.

-D macro[=value]

Define a macro. It is equivalent to the #define directive in the source. If no value is given, value defaults to 1. This option may be specified more than once.

-h

Compile into C data definitions (a header file).

-K secs

Terminate after secs seconds of idleness. The default is 120 seconds. -K 0 means exit immediately upon servicing a request (useful if the server is started by inetd). -K -1 disables the idle timer, so the server never exits.

-L

Use syslog() for error reporting. In order to capture the log messages, you need to have syslogd running.

-l

("el") Compile into client-side stubs.

-m

Compile into server-side stubs, but don't generate a main routine. You should find this useful for doing callback routines or for when you need to write your own main routine to do initialization.

-o outfile

Use this output file. If you don't specify a file, rpcgen uses the standard output (-c, -h, -l, -m, -Sc, -Ss, and -s modes only).

-s transport

Compile into server-side stubs, using this transport. The compiler supports the transports udp and tcp (default is udp). You can invoke this option more than once to compile a server that serves multiple transports. The transports are chosen at run time and not at compile time.

-Sc

Generate client-side sample code to show the use of remote procedure and how to bind the server before calling the client-side stubs generated by rpcgen.

-Ss

Generate skeleton code for the remote procedure on the server side. You need to fill in the actual code for the remote procedures.

infile

Use this input file. If you don't specify an input file in the -c, -h, -l, -m, and -s modes, rpcgen uses the standard input.

Description:

The rpcgen compiler generates C code to implement an RPC protocol. The input rpcgen takes is a C-like language known as Remote Procedure Call Language. For more information about this language, we recommend Power Programming with RPC by John Bloomer, O'Reilly & Associates, 1992. ISBN: 0937175773.

You normally use rpcgen in its first form, where it takes an input file and generates four output files. For example, if you specify an infile called proto.x, then rpcgen generates:

• a header file in proto.h
• XDR routines in proto_xdr.c
• server-side stubs in proto_svc.c
• client-side stubs in proto_clnt.c

When you use the -Sc option, it generates sample code to illustrate how to use remote procedures on the client side. This code is created in proto_client.c. When you use the -Ss option, it generates sample server code to illustrate how to write remote procedures. This code is created in proto_server.c.

You use the other syntax forms when you want to generate only one of these output files.

Once you create a server, it can be started by the port monitors (for example, inetd or listen) or by itself. When it is started by a port monitor, it creates servers only for the transport for which the file descriptor 0 was passed. The name of the transport must be specified by setting up the environmental variable PM_TRANSPORT. When the server, generated by rpcgen, is executed, it creates server handles for all the transports specified in the NETPATH environment variable, or if it is unset, it creates server handles for all the visible transports from the /etc/netconfig file.

You use the other syntax forms when you want to generate only one of these output files. When rpcgen is executed with the -s option, it creates servers for that particular class of transports. When executed with the -n option, it creates a server for the transport specified by netid. If infile is not specified, rpcgen accepts the standard input.

The C compiler is used to preprocess all input files before they're actually interpreted by rpcgen, so all the preprocessor directives are legal within an rpcgen input file. For each type of output file, rpcgen defines a special symbol for your use:

In addition, rpcgen does some preprocessing of its own. It leaves any line beginning with a % uninterpreted and passes the line directly into the output file.

You can customize some of your XDR routines by leaving associated data types undefined. For every data type you leave undefined, rpcgen assumes a routine exists whose name starts with xdr_ and ends with the name of the undefined type.

Caveats:

The compiler doesn't support nesting. You can achieve the same effect, however, by declaring structures at the top level and using their names inside other structures.

When you use program definitions, name clashes can occur since the apparent scoping doesn't apply. You can avoid most of these clashes by assigning unique names to programs, versions, procedures, and types.

The server code generated with the -n option refers to the transport indicated by netid, and hence is very site specific.

See also:

rpcbind, rpcinfo, syslogd

syslog() in the Library Reference