The RPC call message has three unsigned fields that uniquely identify the procedure to be called:
remote program number
remote program version number
remote procedure number
Program numbers are administered by a central authority, as described in "Program Number Registration".
The first implementation of a program will most likely have version number 1. Because most new protocols evolve into better, stable, and mature protocols, a version field of the call message identifies the version of the protocol the caller is using. Version numbers make "speaking" old and new protocols through the same server process possible.
The procedure number identifies the procedure to be called. These numbers are documented in the individual program's protocol specification. For example, a file service's protocol specification may state that its procedure number 5 is "read" and procedure number 12 is "write."
Just as remote program protocols may change over several versions, the RPC message protocol itself may change. Therefore, the call message also has in it the RPC version number, which is always equal to 2 for the version of RPC described here.
The reply message to a request message has enough information to distinguish the following error conditions:
The remote implementation of RPC does not "speak" protocol version 2. The lowest and highest supported RPC version numbers are returned.
The remote program is not available on the remote system.
The remote program does not support the requested version number. The lowest and highest supported remote program version numbers are returned.
The requested procedure number does not exist. (This is usually a caller-side protocol or programming error.)
The parameters to the remote procedure appear to be garbage from the server's point of view. (Again, this is usually caused by a disagreement about the protocol between client and service.)
Provisions for authentication of caller to service and vice versa are provided as a part of the RPC protocol. The call message has two authentication fields, the credentials and verifier. The reply message has one authentication field, the response verifier. The RPC protocol specification defines all three fields to be the following opaque type:
enum auth_flavor { AUTH_NONE = 0, AUTH_SYS = 1, AUTH_SHORT = 2, AUTH_DES = 3, AUTH_KERB = 4 /* and more to be defined */ }; struct opaque_auth { enum auth_flavor; /* style of credentials */ caddr_t oa_base; /* address of more auth stuff */ u_int oa_length; /* not to exceed MAX_AUTH_BYTES */ };
An opaque_auth structure is an auth_flavor enumeration followed by bytes that are opaque to the RPC protocol implementation.
The interpretation and semantics of the data contained within the authentication fields are specified by individual, independent authentication protocol specifications. (See "Record-Marking Standard" for definitions of the various authentication protocols.)
If authentication parameters are rejected, the response message contains information stating why they are rejected.
Program numbers are distributed in groups of 0x20000000, as shown in Table B-1.
Table B-1 RPC Program Number Assignment
Program Numbers |
Description |
---|---|
00000000 - 1fffffff |
Defined by host |
20000000 - 3fffffff |
Defined by user |
60000000 - 7fffffff |
Reserved |
80000000 - 9fffffff |
Reserved |
a0000000 - bfffffff |
Reserved |
c0000000 - dfffffff |
Reserved |
e0000000 - ffffffff |
Reserved |
Sun Microsystems administers the first group of numbers, which should be identical for all customers. If a customer develops an application that might be of general interest, that application should be given an assigned number in the first range.
The second group of numbers is reserved for specific customer applications. This range is intended primarily for debugging new programs.
The third group is reserved for applications that generate program numbers dynamically.
The final groups are reserved for future use, and should not be used.
To register a protocol specification, send a request by email to rpc@sun.com, or write to: RPC Administrator Sun Microsystems 901 San Antonio Road Palo Alto, CA 94043
Please include a compilable rpcgen ".x" file describing your protocol. You will be given a unique program number in return.
The RPC program numbers and protocol specifications of standard RPC services can be found in the include files in /usr/include/rpcsvc. These services, however, constitute only a small subset of those that have been registered.
The intended use of this protocol is for calling remote procedures. That is, each call message is matched with a response message. However, the protocol itself is a message-passing protocol with which other (non-RPC) protocols can be implemented. Some of the non-RPC protocols supported by the RPC package are batching and broadcasting.
Batching allows a client to send an arbitrarily large sequence of call messages to a server; batching typically uses reliable byte stream protocols (like TCP) for its transport. In batching, the client never waits for a reply from the server, and the server does not send replies to batch requests. A sequence of batch calls is usually finished by a non-batch RPC call to flush the pipeline (with positive acknowledgment). For more information, see "Batching".
In broadcast RPC, the client sends a broadcast packet to the network and waits for numerous replies. Broadcast RPC uses connectionless, packet-based protocols (like UDP) as its transports. Servers that support broadcast protocols only respond when the request is successfully processed, and are silent in the face of errors. Broadcast RPC uses the rpcbind service to achieve its semantics. See "Broadcast RPC" and "rpcbind Protocol" for further information.
This section defines the RPC message protocol in the XDR data description language. The message is defined in a top-down style, as shown in Example B-1.
When RPC messages are passed on top of a byte stream transport (like TCP), it is necessary, or at least desirable, to delimit one message from another to detect and possibly recover from user protocol errors. This is called record marking (RM). One RPC message fits into one RM record.
A record is composed of one or more record fragments. A record fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of fragment data. The bytes encode an unsigned binary number; as with XDR integers, the byte order is the network byte order.
The header encodes two values:
A Boolean that specifies whether the fragment is the last fragment of the record (bit value 1 implies the fragment is the last fragment).
A 31-bit unsigned binary value that is the length in bytes of the fragment's data. The Boolean value is the highest-order bit of the header; the length is the 31 low-order bits. (This record specification is not in XDR standard form).