rpcgen Programming Guide

This section introduces the rpcgen tool and provides a tutorial with code examples and usage of the available compile-time flags. See Glossary for the definition of the terms used in this chapter.

The topics covered in this chapter include:

• "SunOS 9 Software Environment Features"

• "rpcgen Tutorial"

• "Compile-Time Flags"

• "rpcgen Programming Techniques"

What Is rpcgen?

The rpcgen tool generates remote program interface modules. It compiles source code written in the RPC language. The RPC language is similar in syntax and structure to C. The rpcgen tool produces one or more C language source modules, which are then compiled by a C compiler.

The default output of rpcgen is:

• A header file of definitions common to the server and the client

• A set of XDR routines that translate each data type defined in the header file

• A stub program for the server

• A stub program for the client

rpcgen can optionally generate:

• Various transports

• A timeout for servers

• Server stubs that are multithread safe

• Server stubs that are not main programs

• C-style arguments passing ANSI C-compliant code

• An RPC dispatch table that checks authorizations and invokes service routines

rpcgen significantly reduces the development time that would otherwise be spent developing low-level routines. Handwritten routines link easily with the rpcgen output. For a discussion of RPC programming without rpcgen, see Chapter 4, Programmer's Interface to RPC.

SunOS 9 Software Environment Features

This section lists the features found in the current rpcgen code generator.

• SunOS Template Generation: rpcgen generates client-side, server-side, and makefile templates. See "Compile-Time Client and Server Templates" for the list of options.

• SunOS C-style Mode: rpcgen has two compilation modes, C-style and default. In C-style mode arguments can be passed by value, instead of as pointers to a structure. It also supports passing multiple arguments. The default mode is the same as in previous releases. See "Compile-Time C-style Mode" for the example code for both modes.

• SunOS Multithread-Safe Code: rpcgen generates MT-safe code for use in a threaded environment. By default, the code generated by rpcgen is not MT safe. See "Compile-Time MT-Safe Code" for the description and example code.

• SunOS Multithread Auto Mode: rpcgen generates MT-safe server stubs that operate in the MT Auto mode. See "Compile-Time MT Auto Mode" for the definition and example code.

• SunOS Library Selection: rpcgen uses library calls for either TS-RPC or TI-RPC. See "Compile-Time TI-RPC or TS-RPC Library Selection".

• SunOS ANSI C-compliant Code: The output generated by rpcgen conforms to ANSI C standards. See "Compile-Time ANSI C-compliant Code".

rpcgen Tutorial

rpcgen provides programmers a direct way to write distributed applications. Server procedures can be written in any language that observes procedure-calling conventions. These procedures are linked with the server stub produced by rpcgen to form an executable server program. Client procedures are written and linked in the same way.

This section presents some basic rpcgen programming examples. Refer also to the rpcgen(1) man page.

Converting Local Procedures to Remote Procedures

Assume that an application runs on a single computer and you want to convert it to run in a "distributed" manner on a network. This example shows the stepwise conversion of this program that writes a message to the system console. The following code example shows the original program.

Example 3-1 Single Process Version of printmesg.c

/* printmsg.c: print a message on the console */

#include <stdio.h>
 
main(argc, argv)
	int argc;
	char *argv[];
{
	char *message;
 
	if (argc != 2) {
fprintf(stderr, "usage: %s <message>\n",
					argv[0]);
		exit(1);
	}
	message = argv[1];
	if (!printmessage(message)) {
		fprintf(stderr,"%s: couldn't print your
					message\n",argv[0]);
	exit(1);
	}
	printf("Message Delivered!\n");
	exit(0);
}
 /* Print a message to the console.
 * Return a boolean indicating whether
 * the message was actually printed. */
 printmessage(msg)
	char *msg;
{
	FILE *f;
 	f = fopen("/dev/console", "w");
	if (f == (FILE *)NULL) {
		return (0);
	}
	fprintf(f, "%s\n", msg);
	fclose(f);
	return(1);}