Programming with Remote Procedure Calls (RPC)

Using port monitors

An RPC server can be started from port monitors such as inetd(1Mtcp) and listen(1M). These port monitors listen for requests for the services and spawn servers in response to those requests. The forked server process is passed file descriptor 0, on which the request has been accepted. For inetd, after the server has serviced the request, it may exit immediately or wait a given interval of time for another service request to come in.

NOTE: For listen, a service may exit (after servicing a single request) or poll file descriptor 0 (waiting for additional requests). The listener must be administered to expect the correct behavior for each of its services. listen will always spawn a new process rather than give a request to a waiting server process.

The following routine can be used to create a service:

   transp = svc_tli_create(0, nconf, NULL, 0, 0)

nconf is the netconfig structure of the transport on which the request came in.

Because the port monitors have already registered the service with rpcbind, there is no need for the service to register itself. Nevertheless, it must call svc_reg:

   svc_reg(transp, PROGNUM, VERSNUM, dispatch, NULL)

The netconfig structure here is NULL.

NOTE: Programmers should study rpcgen-generated server stubs to better see the sequence in which these routines are called.

For connection-oriented transports, the following routine provides a lower level interface:

   transp = svc_fd_create(0, recvsize, sendsize);

The file descriptor passed here is 0. The user may set the value of recvsize or sendsize to any appropriate buffer size. If they use a 0 in either case, a system default size will be chosen. This routine should be used by application servers that do not do any listening of their own, that is, servers that simply do their job and return.

Using inetd

The format of entries in /etc/inetd.conf for RPC services is as follows:

   rpc_prog/vers socket_type rpcproto flags uid pathname args

Here:

rpc_prog: is the symbolic name of the program as it appears in rpc(4tcp).
vers: is the version number
socket_type: is one of dgram for connectionless transport, or stream for virtual circuit transport
proto: is transport protocol, such as udp or tcp and must correspond to the specified socket_type (for example, udp for dgram, and tcp for stream)
flags: is one of wait or nowait
uid: is a user ID that must exist in /etc/passwd
pathname: is the full pathname of the server daemon
args: are arguments to be passed to the daemon when it is invoked

For example:

   mountd dgram rpc/udp wait root /usr/sbin/rpc.mountd rpc.mount

For more information, see inetd.conf(4tcp).

Using the listener

We will assume here that the reader already knows the details of setting up the listener process and of using pmadm. The following shows how to use pmadm to add RPC services:

   pmadm -a -p pm_tag -s svctag -i id -v ver \
      -m "`nlsadmin -c command -D -R prog:vers`"

Here -a means add a service, -p pm_tag specifies a tag associated with the port monitor providing access to the service, -s svctag is the server's identifying code, -i id is the /etc/passwd user ID assigned to service svctag, -v ver is the version number for the port monitor's database file and -m specifies the nlsadmin command for invoking the service. nlsadmin may have additional arguments. For example, to add version 1 of a remote program server named rusersd the pmadm command might be:

pmadm -a -p tcp -s rusers -i root -v `nlsadmin -V` \
-m "`nlsadmin -c /usr/lib/netsvc/rusers/rpc.rusersd \
-D -R 100002:1`"

Here, the command is given root permissions, and is made available over TCP transports. If the service is to be a daemon process, the -c command must be replaced by a -p pipe where pipe is a FIFO or named STREAM.

NOTE: Because of the complexity of the arguments and options that can follow the pmadm -a invocation, it may be convenient to use a command script to add RPC services.

After adding a service, the listener must be reinitialized before the service will be available. This is accomplished by forcing the listener to re-read its database, as follows (note that rpcbind must be running):

sacadm -x -p pmtag

For additional information, see ``The Service Access Facility'' and the listen(1M), pmadm(1M), and sacadm(1M) manual pages.