Compile-Time MT Auto Mode

MT Auto mode enables RPC servers to automatically use Solaris threads to process client requests concurrently. Use the -A option to generate RPC code in MT Auto mode. The -A option also has the effect of turning on the -M option, so -M does not need to be explicitly specified. The -M option is necessary because any code that is generated has to be multithread safe.

The section Chapter 7, Multithreaded RPC Programming contains further discussion on multithreaded RPC. See also "MT Auto Mode".

An example of an Auto mode program generated by rpcgen follows in the rpcgen protocol file time.x. A string is passed to the remote procedure, which prints the string and returns its length to the client.

Example 3-21 MT Auto Mode: time.x

		program TIMEPROG {
			version TIMEVERS {
				unsigned int TIMEGET(void) = 1;
				void TIMESET(unsigned) = 2;
			} = 1;
		} = 0x20000044;

The MT-safe stubs are generated with the rpcgen -A time.x command.

When the -A option is used, the generated server code contains instructions for enabling MT Auto mode for the server.

Note - When compiling a server that uses MT Auto mode, you must link in the threads library. To do so, specify the -lthread option in the compile command.

Compile-Time TI-RPC or TS-RPC Library Selection

In older SunOS releases, rpcgen created stubs that used the socket functions. With the current SunOS release, you can use either the transport-independent RPC (TI-RPC) or the transport-specific socket (TS-RPC) routines. These routines provides backward compatibility with previous releases. The default uses the TI-RPC interfaces. The -b flag tells rpcgen to create TS-RPC variant source code as its output.

Compile-Time ANSI C-compliant Code

rpcgen can also produce output that is compatible with ANSI C. This feature is selected with the -C compile flag and is most often used with the -N flag, described in "Compile-Time C-style Mode".

The add.x example of the server template is generated by the rpcgen -N -C -Ss -o add_server_template.c add.x command:

Note that on the C++ 3.0 server, remote procedure names require an _svc suffix. In the following example, the add.x template and the -C compile flag produce the client side add_1 and the server stub add_1_svc.

Example 3-22 rpcgen ANSI C Server Template

/*
 * This is a template. Use it to
 * develop your own functions.
 */
#include <c_varieties.h>
#include "add.h"
 
int *
add_1_svc(int arg1, int arg2,
					struct svc_req *rqstp)
{
	static int result;
	/*
	 * insert server code here
	 */
	return(&result);
}

This output conforms to the syntax requirements and structure of ANSI C. The header files that are generated when this option is invoked can be used with ANSI C or with C++.

Compile-Time xdr_inline() Count

rpcgen tries to generate more efficient code by using xdr_inline() when possible (see the xdr_admin(3NSL) man page). When a structure contains elements that xdr_inline() can be used on (for example integer(), long(), bool()), the relevant portion of the structure is packed with xdr_inline(). A default of five or more packed elements in sequence causes inline code to be generated. You can change this default with the -i flag. The rpcgen -i 3 test.x command causes rpcgen to start generating inline code after three qualifying elements are found in sequence. The rpcgen -i 0 test.x command prevents any inline code from being generated.

In most situations, you do not need to use the -i flag. The _xdr.c stub is the only file affected by this feature.

rpcgen Programming Techniques

This section suggests some common RPC and rpcgen programming techniques.

Table 3-4 RPC Programming Techniques

Network Types/Transport Selection

rpcgen takes optional arguments that enable a programmer to specify desired network types or specific network identifiers. For details of network selection, see Programming Interfaces Guide.

The -s flag creates a server that responds to requests on the specified type of transport. For example, the command rpcgen -s datagram_n prot.x writes a server to standard output that responds to any of the connectionless transports specified in the NETPATH environment variable, or in /etc/netconfig, if NETPATH is not defined. A command line can contain multiple -s flags and their network types.

Similarly, the -n flag creates a server that responds only to requests from the transport specified by a single network identifier.

Note - Be careful using servers created by rpcgen with the -n flag. Network identifiers are host specific, so the resulting server might not run as expected on other hosts.

Command-Line Define Statements

You can define C-preprocessing symbols and assign values to them from the command line. Command-line define statements can be used to generate conditional debugging code when the DEBUG symbol is defined. For example:

$ rpcgen -DDEBUG proto.x

Server Response to Broadcast Calls

When a procedure has been called through broadcast RPC and cannot provide a useful response, the server should send no reply to the client, thus reducing network traffic. To prevent the server from replying, a remote procedure can return NULL as its result. The server code generated by rpcgen detects this return and sends no reply.

The following code example is a procedure that replies only if it reaches an NFS server.

Example 3-23 NFS Server Response to Broadcast Calls

void *
reply_if_nfsserver()
{
	char notnull; /*only here so we can
						 *use its address
						 */

	if( access( "/etc/dfs/sharetab",
						F_OK ) < 0 ) {
		/* prevent RPC from replying */
		return( (void *) NULL );
	}
	/* assign notnull a non-null value
 * then RPC sends a reply
 */
	return( (void *) &notnull );
}

A procedure must return a non-NULL pointer when it is appropriate for RPC library routines to send a reply.

In the example, if the procedure reply_if_nfsserver() is defined to return nonvoid values, the return value &notnull should point to a static variable.

Port Monitor Support

Port monitors such as inetd and listen can monitor network addresses for specified RPC services. When a request arrives for a particular service, the port monitor spawns a server process. After the call has been serviced, the server can exit. This technique conserves system resources. The main server function generated by rpcgen allows invocation by inetd. See "Using inetd " for details.

Services might wait for a specified interval after completing a service request, in case another request follows. If no call arrives in the specified time, the server exits, and some port monitors, like inetd, continue to monitor for the server. If a later request for the service occurs, the port monitor gives the request to a waiting server process (if any), rather than spawning a new process.

Note - When monitoring for a server, some port monitors, like listen(), always spawn a new process in response to a service request. If a server is used with such a monitor, the server should exit immediately on completion.

By default, services created using rpcgen wait for 120 seconds after servicing a request before exiting. You can change the interval with the -K flag. In the following example, the server waits for 20 seconds before exiting. To create a server that exits immediately, you can use zero value for the interval period.

rpcgen -K 20 proto.x

rpcgen -K 0 proto.x

To create a server that never exits, the value is -K -1.

For more information on port monitors, see Appendix F, Writing a Port Monitor With the Service Access Facility (SAF).