ONC+ Remote Procedure Call (RPC) for MCP/AS
Installation and Programming Guide
MCP 12.0
imagine it. done.
MCP/AS
ONC+ Remote Procedure Call (RPC) for MCP/AS
Installation and Programming Guide
MCP 12.0
direct, special, or consequential damages.
You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used.
The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions.
Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses.
Installation and Programming Guide MCP 12.0 Installation and Programming Guide MCP 12.0 8600 2383–103 8600 2383–103
Section 1.
What is ONC+ Remote Procedure Call (RPC)?
Documentation Updates... 1–1 ONC+ RPC... 1–1 RPCGEN... 1–2
Section 2.
Installing the ONC+ RPC Software
Overview ... 2–1 Files... 2–2 Task 1: Copy Files and Install Support Library ... 2–3 Task 2: Register ONC+ RPC as a DSS Provider... 2–5 Task 3: Update the USERDATAFILE ... 2–6
Section 3.
Introduction to Remote Procedure Call (RPC)
Overview ... 3–1 RPC Versions and Numbers ... 3–3 Network Selection ... 3–4 Transport Selection... 3–5 The rpcbind Facility ... 3–6 Address Registration ... 3–6 RPCINFO Command... 3–7 Lower RPC Levels ... 3–7 External Data Representation (XDR) ... 3–8
Section 4.
RPC Programming for C Programming
Interfaces
Overview ... 4–1 RPC Programming in C ... 4–1 Simplified Interface ... 4–2 rpc_call( ) Routine ... 4–3 rpc_reg( ) Routine ... 4–3Examples ... 4–19 Advanced RPC Programming Techniques ... 4–21 rpc_poll( ) on the Server Side ... 4–21 Batching ... 4–22 Authentication ... 4–26 Server Versions ... 4–29 Client Versions... 4–32 Connection-Oriented Transports ... 4–33 Memory Allocation with XDR ... 4–36 Debugging RPC... 4–37 C Application Programming Interfaces ... 4–38 rpc... 4–38 rpc_clnt_auth ... 4–42 rpc_clnt_calls... 4–43 rpc_clnt_create ... 4–46 rpc_rac ... 4–50 rpc_svc_calls ... 4–52 rpc_svc_create ... 4–54 rpc_svc_err... 4–56 rpc_svc_reg ... 4–57 rpcbind... 4–58 xdr_complex ... 4–59 xdr_simple ... 4–61 RPCGEN Programming... 4–63 RPC Language Reference ... 4–64 Preprocessing Directives ... 4–64 Definitions ... 4–66 Enumerations... 4–66 Constants... 4–67 Typedefs ... 4–67 Declarations... 4–67 Simple Declarations ... 4–67 Fixed-Length Array Declarations... 4–68 Variable-Length Array Declarations .. 4–68 Pointer Declarations... 4–68 Structures ... 4–69 Unions... 4–69 Programs ... 4–70 Special Cases... 4–71 Booleans ... 4–71 Strings ... 4–71 Opaque Data... 4–72 Voids ... 4–72 RPCGEN Argument Options ... 4–72 RPCGEN Input Files... 4–74 RPCGEN Output File... 4–75 Running RPCGEN... 4–76 An RPCGEN Tutorial... 4–77
Converting Local Procedures into Remote Procedures ... 4–77 Generating XDR Routines with RPCGEN . 4–83
Debugging RPCGEN ... 4–91 Binding a Host Program to C Portal Routines .... 4–92
Section 5.
RPC Programming for ALGOL Programming
Interfaces
Library Entry Points ... 5–1 The Client_Status Result Type ... 5–2 Attribute Handling... 5–4 Client Interfaces for Writing RPC Attributes ... 5–4 Client Interfaces for Reading RPC Attributes ... 5–5 Server Interfaces for Writing RPC Attributes ... 5–5 Server Interfaces for Reading RPC Attributes ... 5–5 ALGOL DEFINEs for Building the Attribute
Structures ... 5–6 Attribute Value Structure... 5–8 Attribute Inquiry Structure ... 5–9 ONC RPC Library Entry Points ... 5–9 Server Entry Points ... 5–9 Client Entry Points ... 5–13 Encoding and Decoding Procedures... 5–19
Section 6.
Using the ONC+ RPCSUPPORT Operator
Interface (OI)
DEBUG Command... 6–1 DUMP Command ... 6–3 RPCINFO Command ... 6–3 VERSION Command ... 6–9
Appendix A.
RPC Live Code Examples for the C and
ALGOL Programming Languages
Code Examples for C ...A–1 Code Examples for ALGOL ...A–18 Client Example...A–18 Server Example ...A–23
Appendix B.
Understanding Railroad Diagrams
Railroad Diagram Concepts ...B–1 Paths...B–1 Constants and Variables...B–2
User-Selected Item ... B–4 Loop ... B–5 Bridge ... B–5 Following the Paths of a Railroad Diagram ... B–6 Railroad Diagram Examples with Sample Input ... B–7
Figures
Tables
4–1. RPCGEN Argument Options... 4–73 4–2. UNIX to A Series RPCGEN File Name Differences... 4–75 5–1. Client_Status Result Values... 5–3 B–1. Elements of a Railroad Diagram ...B–2
Examples
4–1. "Hand-Coding" Registration Server... 4–5 4–2. xdr_simple Routine ... 4–6 4–3. xdr_varintarr Syntax Use... 4–7 4–4. xdr_reference Syntax Use... 4–9 4–5. time_prot.h Header File... 4–11 4–6. Trivial Date Service: Client Side... 4–12 4–7. Time Server... 4–14 4–8. Client Side of the Time Service... 4–16 4–9. Greenwich Time Service ... 4–17 4–10. Client RPC Handle Structure ... 4–19 4–11. Client’s Authentication Handle ... 4–20 4–12. Server Transport Handle... 4–20 4–13. Unbatched Client... 4–23 4–14. Batched Client ... 4–24 4–15. Batched Server ... 4–25 4–16. AUTH_SYS Credential Structure ... 4–28 4–17. Authentication Server ... 4–29 4–18. Server Handle for Two Versions of Single Routine... 4–30 4–4– Server to Use Either Version... 4–31 4–20. Versions on Client Side ... 4–33 4–21. Remote Copy: Two-Way XDR Routine ... 4–34 4–22. Remote Copy: Client Routines ... 4–35 4–23. Remote Copy: Server Routines ... 4–36 4–24. Single-process version of PRINTMSG/C ... 4–78 4–25. RPC Version of PRINTMSG/C... 4–79 4–26. Remote Version of PRINTMSG/C... 4–81 4–27. RPCL Protocol Description File: DIR/X ... 4–83 4–28. Server DIR_PROC/C ... 4–85 4–29. Client-side Implementation of rls.c ... 4–87 A–1. Code Example for RPCL Protocol Description File: DIR/X ...A–2 A–2. Code Example for Header File Produced by RPCGEN ...A–3 A–3. Code Example for XDR/C Produced by RPCGEN...A–5 A–4. Code Example for CLNT/C Produced by RPCGEN...A–5 A–5. Code Example for CLIENT/C Produced by RPCGEN ...A–7 A–6. Code Example for SVC/C Produced by RPCGEN...A–9 A–7. Code Example for SERVER/C Produced by RPCGEN ...A–10 A–8. Code Example for DIRSEARCH/H...A–11
Programming Guide
Purpose
The ONC+ Remote Procedure Call (RPC) for A Series Installation and Programming Guide introduces the ONC+ RPC for A Series product, provides installation procedures, and describes how to write C and ALGOL language applications based on RPC.
Scope
Open Network Computing Plus (ONC+) is a family of distributed services, which provide an environment for heterogeneous distributed computing.
Sun Microsystems first introduced ONC+ technology in 1985. Since then, the technology has evolved into a de facto standard for distributed computing. It is available on many different platforms, including the UNIX and Microsoft Windows operating systems environments. ONC+ RPC for A Series enables a program to call procedures on remote systems over a Transmission Control Protocol/Internet Protocol (TCP/IP) network. ONC+ RPC isolates a program completely from the network transport, which enables the program to call remote procedures by using syntax similar to the syntax used to call local procedures. The A Series application can operate as either a client or a server, or as both a client and server.
This guide describes how to install and write programs using the ONC+ RPC for A Series software.
Audience
This guide is written for A Series users responsible for installing the ONC+ RPC software or designing application programs based on ONC+ RPC technology.
Prerequisites
How to Use This Installation and Programming
Guide
This guide includes step-by-step instructions on installing the ONC+ RPC for A Series software. If you are the person installing the software, it is recommended that you read Section 2 and Section 6.
Also included is information on programming with RPCGEN and ONC+ RPC.
In this guide, whenever the term RPC is used, it refers to ONC+ RPC. If the term remote procedure call is used, it refers to the general concept of a remote procedure call.
Also, whenever you see a term in bold within a paragraph, for example rusers, it refers to programming syntax.
Organization
This guide consists of the following sections and appendixes. In addition, an index appears at the end of this guide.
Section 1. What is ONC+ Remote Procedure Call (RPC)?
This section defines the ONC+ RPC product.
Section 2. Installing the ONC+ RPC Software
This section identifies the ONC+ RPC files and tells you how to install the product.
Section 3. Introduction to Remote Procedure Call (RPC)
This section describes the basic model of RPC and its use in developing distributed applications.
Section 4. RPC Programming for C Programming Interfaces
This section describes the use of network applications using remote procedure calls. It also provides a reference to C application programming interfaces, and describes the RPCGEN stub compiler.
Section 5. RPC Programming for ALGOL Programming Interfaces
This section provides the defines, entry points, and attribute structures necessary to use RPC with the ALGOL programming language.
Section 6. Using the ONC+ RPCSUPPORT Operator Interface (OI)
Appendix A. RPC Live Code Examples for the C and ALGOL Programming Languages
This appendix contains RPC code examples for the C programming language of a complete directory search program and the job deck that compiles and binds it. It also provides an ALGOL programming example.
Appendix B. Understanding Railroad Diagrams
This appendix explains the use of railroad diagrams in this guide.
Related Product Information
Unless otherwise stated, all documents referred to in this publication are MCP/AS documents. The titles have been shortened for increased usability and ease of reading.
The following documents are included with the software release documentation and provide general reference information:
• The Glossary includes definitions of terms used in this document.
• The Documentation Road Map is a pictorial representation of the Product Information (PI) library. You follow paths through the road map based on tasks you want to perform. The paths lead to the documents you need for those tasks. The Road Map is available on the PI Library CD-ROM. If you know what you want to do, but don’t know where to find the information, start with the Documentation Road Map.
• The Information Availability List (IAL) lists all user documents, online help, and HTML files in the library. The list is sorted by title and by part number.
The following documents provide information that is directly related to the primary subject of this publication.
The following documents provide information that is directly related to the primary subject of this publication.
ALGOL Programming Reference Manual, Volume 1: Basic Implementation
This manual describes the basic features of the Extended ALGOL programming language. This manual is written for programmers who are familiar with programming concepts.
Binder Programming Reference Manual
This manual describes the functions and applications of the Binder, an efficiency tool that reduces the need to recompile an entire program when only a portion of the program has been modified. This manual is written for programmers who are familiar with programming language concepts and terms.
C Programming Reference Manual, Volume 2: Headers and Functions
This manual describes the C headers in detail, and the functions, macros, and types defined in those headers. This manual is written for systems and applications programmers.
C Test and Debug System (TADS) Programming Reference Manual
This manual describes the commands and procedures for using C TADS, an interactive tool for testing and debugging C programs and libraries. This manual is written for programmers who are familiar with the general concepts of C programming and debugging.
What is ONC+ Remote Procedure Call
(RPC)?
ONC+ RPC for A Series is a product comprised of ONC+ RPC and the RPC Generator utility (RPCGEN).
Documentation Updates
This document contains all the information that was available at the time of publication. Changes identified after the release of this document are included in problem list entry (PLE) 18575973. To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site:
http://www.support.unisys.com/all/ple/18575973
Note: If you are not logged into the Product Support site, you will be asked to do so.
ONC+ RPC
Open Network Computing Plus (ONC+) is a family of distributed services, which provide an environment for heterogeneous distributed computing.
Sun Microsystems first introduced ONC+ technology in 1985. Since then, the technology has evolved into a de facto standard for distributed computing. It is available on many different platforms, including the UNIX and Microsoft Windows operating systems.
ONC+ RPC for A Series enables a program to call procedures on remote systems over a Transmission Control Protocol/ Internet Protocol (TCP/IP) network. ONC+ RPC isolates a program completely from the network transport, enabling the program to call remote procedures using syntax similar to the syntax used to call local procedures.
ONC+ RPC for A Series includes RPCGEN, which helps distributed application developers write C applications based on RPC.
Client
Within the ONC+ RPC environment, a client initiates a request to a server.
Server
Within the ONC+ RPC environment, a server responds back to the client.
RPCGEN
RPCGEN is a stub compiler that takes a program written in the RPC language and produces output files containing C source code. RPCGEN is used to speed the development of RPC programs.
Installing the ONC+ RPC Software
This section identifies the files that you need for ONC+ RPC, and includes the information you need to install the files and update the USERDATAFILE.Overview
You can install ONC+ RPC by using the Simple Installation (SI) program or you can perform all of the steps manually. This section gives you the information you need to install ONC+ RPC either by using SI or manually.
Installation Tasks
1. Copy the files and install the support library.
2. Install the distributed systems service (DSS) software. 3. Update the USERDATAFILE.
Files
The following information lists the files that you must have installed before you begin, the files that it is recommended that you install, and the ONC+ RPC files you must install.
Before you begin
Ensure that you have the following software already installed:
• NETWORKSUPPORT library, version 42.1 or later
• TCPIPSUPPORT, version 32.0 or later
Recommended Files
It is strongly recommended that you install the Domain Name Service (DNS) for A Series (the Resolver DSS). If DNS is not installed, the use of host or domain names is not supported in the interfaces. That is, remote locations must be identified by an IP address.
More Information
Refer to the Distributed Systems Service (DSS) Operations Guide for more information about the Resolver DSS.
ONC+ RPC Files
To install and run ONC+ RPC, some files should already be present on your system and some files are installed as part of the ONC+ installation. The following files should already be present on your system:
• SYSTEM/CC, SSR 42.1 or later
• SYSTEM/CPREP, SSR 42.1 or later
• SYSTEM/SLICESUPPORT, SSR 42.1 or later
• SYSTEM/BINDER, SSR 42.1 or later
The following files are installed as part of the ONC+ installation:
• SYMBOL/ONC/RPC/H
• SYSTEM/ONC/RPCPORTAL/C
• SYSTEM/ONC/RPCPORTAL/C2L
• OBJECT/RPCGEN
Task 1: Copy Files and Install Support Library
You can copy the ONC+ RPC files and install the support library by using the Simple Installation (SI) program or you can perform these procedures manually.
Using SI
The SI program enables you to copy files and access the appropriate libraries automatically, and install the ONC+ RPC software.
Use the sequence of screens shown in the following table if you are using SI to install ONC+ RPC. Use an ODT or a COMS control-capable station to access the screens.
Screen Command
MARC UTIL in the "Choice" field. As an alternative, from the CANDE screen you can enter the following command to take you directly to the SIMPLEINSTALL HOME screen:
U $SYSTEM/SIMPLEINSTALL
UTIL SI in the "Choice" field
SIMPLEINSTALL HOME
INSTALL in the "Choice" field (other fields already default to appropriate values).
INSTALL ONC in the "Software product name" field. Also, place an X in the "Select additional categories to copy/install" field.
FILES Place an X in the "All" category of the "Generation Data" field (in addition to selections you have already made in other fields).
After you have transmitted the information from the FILES screen, a series of files is listed that you can use to develop products using ONC+ RPC.
More Information
Manually
This table explains the steps necessary to install ONC+ RPC. Use an ODT or a COMS control-capable station.
Step Action
1 Enter the COPY command. Example:
COPY *SYMBOL/ONC/RPC/H, *SYSTEM/ONC/=, *OBJECT/RPCGEN FROM TAPE TO MYPACK
Result:
The appropriate ONC+ RPC files are copied from the release media to the host system. Tape name can vary based on release media. Some systems receive the release media on CD-ROM only.
2 Enter the SL (Support Library) command. Example:
SL ONCRPCSUPPORT = *SYSTEM/ONC/RPCSUPPORT ON MYPACK : TRUSTED, LINKCLASS = 1, ONEONLY
Result:
Task 2: Register ONC+ RPC as a DSS Provider
After you copy the files and install the support library, you must register ONC+ RPC as a DSS provider.Step Action
1 Enter the ADD ENDPOINT command. Example:
NA REG ADD ENDPOINT ONCRPCBIND FILENAME = ONCRPCBIND, MYNAME = "111", PUBLIC = TRUE
Result:
The rpcbind endpoint is defined.
2 Enter the ADD DSS command. Example:
NA REG ADD DSS ONCRPC INIT = TRUE, CLASS = OTHER, RECOVERY = TRUE, ENDPOINT = ONCRPCBIND Result: ONC+ RPC DSS is defined.
3 Enter the ADD PROVIDER command. Example:
NA REG ADD PROVIDER ONCRPCSUPPORT SL = ONCRPCSUPPORT,
TYPE = NMSL,
INTERFACE = MESSAGE, DSS = ONCRPC
Result:
ONC+ RPC support provider is defined. NMSL is NONMONITOREDSUPPORTLIBRARY.
4 Enter the command to initialize ONCRPC. Example:
If you want to check that ONC+ RPC is correctly installed, you can use the RPCINFO command to query a remote host. Refer to Section 6, “Using the ONC+ RPCSUPPORT Operator Interface (OI),” for more information about the command.
Task 3: Update the USERDATAFILE
Before you can run ONC+ RPC, you must update the USERDATAFILE.
If you are a . . . Then . . .
Client and you want to use
AUTH_SYS_DEFA ULT
You must include a UID attribute when defining your usercode in the USERDATAFILE.
Server For every client from the same or another host, you must include a remote *USERID entry in the USERDATAFILE.
For every host from which you are going to accept a client request, enter the following command in MAKEUSER:
+ RU *NOUSERID OF <hostname> LOCALALIAS =<valid usercode>
It is recommended that the valid usercode that you specify have minimum privileges.
You must include this step even if you are going to run both the client and the server on the same host.
Client and Server You must perform all the actions listed in this table.
More Information
Refer to the Security Administration Guide for more information about the USERDATAFILE, the UID attribute, MAKEUSER, and authentication.
Next Step
Introduction to Remote Procedure Call
(RPC)
Remote Procedure Call (RPC) is a high-level network applications model. RPC is analogous to a function call. Like a function call, when an RPC is made, the calling arguments are passed to the remote procedure and the caller waits for a response to be returned from the remote procedure. By using RPC, programmers of distributed applications avoid the details of the interface with the network. The transport independence of RPC isolates the application from the physical and logical elements of the data communications mechanism and allows the application to use a variety of transports.
Overview
RPC enables network applications to use procedure calls that hide the details of the underlying networking mechanism. RPC is a logical client-to-server communications system that specifically supports network applications. RPC runs on TCP or UDP. Generic facilities, such as rpcbind, associate network services with universal network addresses.
In Figure 3–1, the client makes a procedure call that sends a request to the server and blocks. When the request arrives, the server calls a dispatch routine that performs the requested service, and sends the reply to the client. The client continues processing.
Host A client program client continues service daemon invoke service service executes request completed call service return answer RPC call return reply Host B
Figure 3–1. Network Communication with RPC
RPC programs follow the client/server model. RPC programs provide network services to callers without requiring any awareness of the underlying network. For example, a program can call
rusers( ), a routine in the librpcsvc library that returns the number of users on a remote host. The
caller is not explicitly aware of using the network. The call to rusers( ) is as simple as a call to a standard system service call like malloc.
This guide addresses the C and ALGOL interfaces to RPC. The guide describes the use of RPC to communicate between processes on different hosts. RPC works as well to communicate between processes on a single host.
The following list includes the key components and leading characteristics of RPC:
Component Characteristics
RPC Program Number Version Number Procedure Number
RPC uses ordered sets of program number, program version, and procedure number to uniquely identify procedures that can be called by means of RPC. Network Selection You can write programs to run on a specific transport
or transport type, or to operate on a system- or user-chosen transport.
rpcbind Facility rpcbind associates network services with universal network addresses
Lower RPC Levels The lower levels of RPC allow greater control of RPC communications.
External Data Representation (XDR)
Data transmitted between RPC clients and servers is encoded in XDR format.
RPC Versions and Numbers
Each RPC procedure is uniquely identified by a program number, version number, and procedure number.
The program number identifies a group of related remote procedures, each of which has a different procedure number. Each program also has a version number, so when a change is made to a remote service (such as adding a new procedure), a new program number does not have to be assigned. Changes in a program—such as adding a new procedure, changing the arguments or return value of a procedure, or changing the side-effects of the procedure—require that the version number be changed.
For information on how to assign a program number to an RPC program, see the UNIX System V Release 4.0 Programmer's Guide: Networking Interfaces.
Network Selection
Network selection enables users and applications to dynamically select a transport from those available. It uses two mechanisms: the transports supported by the ONCRPC DSS and the environmental variable NETPATH. NETPATH is optional and enables a user to specify a transport or selection of transports from those supported by ONCRPC.
NETPATH is a task attribute. Its format is a simple ordered list of network identifiers separated by colons (:). An example is: udp:tcp.
By setting NETPATH, the user specifies the order in which the application tries the available transports. If NETPATH is not set, RPC defaults to all supported transports.
An application can ignore a user’s NETPATH and set its own transport-selection order. The ability to make a predetermined choice of transport is a convenience to the developer but is not
mandatory.
RPC divides selectable transports into the following types:
Type Explanation
netpath Choose from those transports specified in the NETPATH task attribute. If NETPATH is not set, the system defaults to all supported transports. If no other value is specified, netpath is used.
visible Same as selecting netpath.
circuit_v Same as visible, but restricted to connection-oriented transports. datagram_v Same as visible, but restricted to connectionless transports. circuit_n Choose the connection-oriented transports in the order defined in
NETPATH.
datagram_n Choose the connectionless transports in the order defined in NETPATH.
udp Specify Internet User Datagram Protocol (UDP). tcp Specify Internet Transmission Control Protocol (TCP).
These mechanisms allow a fine degree of control over network selection: a user can specify a preferred transport, and if it can, an application uses it. If the specified transport is inappropriate, the application automatically tries others with the right characteristics.
Transport Selection
A distributed application must use a standard interface to the transport services if it is to be portable to different protocols. Transport selection services provide an interface that allows an application to select which protocols to use. This makes an application protocol- and medium-independent.
Transport selection makes it easy for a client application to try each available transport until it establishes communication with a server. Transport selection enables server applications to accept requests on multiple transports, and so communicate over a number of protocols. Both clients and servers can try transports in either the order specified by the local default sequence or in an order that you specify.
Choosing from the available transports is the responsibility of the application. The transport selection mechanism makes that selection uniform and simple.
RPC services are supported on both TCP and UDP transports. The selection of the transport depends on the requirements of the application.
TCP, a circuit-oriented transport, is the transport of choice if the application has any of the following characteristics:
• The application can tolerate or amortize the higher cost of connection setup compared to datagram transports.
• Calls to the procedures can change the state of the procedure or of associated data.
• The size of either the arguments or the results exceed the maximum size of a datagram packet. UDP, a datagram transport, is the transport of choice if the application has all the following characteristics:
• Calls to the procedures do not change the state of the procedure or of associated data.
• The size of both arguments and results is smaller than the transport packet size.
• The server is required to handle hundreds of clients. A datagram server does not keep any state data on clients, so it can potentially handle many clients. A circuit-oriented server keeps state data on each open client connection, so the number of clients is limited by the host resources.
How Transport Selection Works
The transport selection component is built around the following:
• The transports supported by ONC RPC
• Optional use of the NETPATH task attribute
The NETPATH task attribute is set by the user; it contains an ordered list of transport identifiers.
NETPATH Task Attribute
An application usually uses the default transport search path set by the system administrator to locate an available transport. However, when a user wants to influence the choices made by an application, the application can modify the interface by using the task attribute NETPATH. These routines access only the transports specified in the NETPATH.
The value of the NETPATH task attribute is a list of transport IDs separated by a colon (:).
The rpcbind Facility
Transport services do not provide address-lookup services. They provide only message transfer across a network.
A client program needs a way to obtain the address of its server program. This service is performed by rpcbind.
RPC makes no assumption about the structure of a network address. RPC translates universal addresses into local transport addresses by using routines specific to the transport.
rpcbind provides the following operations:
• Add a registration.
• Delete a registration.
• Get address of a specified program number, version number, and transport.
• Get the complete registration list.
• Perform a remote call for a client.
• Return the time.
Address Registration
Because rpcbind maps RPC services to their addresses, its address must be known. The name-to-address translation routines of all transports must reserve a known name-to-address for rpcbind. For example, in the Internet domain, rpcbind has the “well known” port number 111 on both TCP and UDP. When rpcbind is started, it registers its location on each of the transports supported by the host. rpcbind is the only RPC service that must have a known address.
For each supported transport, rpcbind registers the addresses of RPC services and makes the addresses available to clients. A service makes its address available to clients by registering the address with the rpcbind daemon. The address of the service is then available to rpcinfo and to programs using library routines named in rpcbind. No client or server can assume the network address of rpcbind.
Client and server programs and client and server hosts are usually distinct, but they need not be. A server program can also be a client program. When one server calls another rpcbind server, it makes the call as a client.
To find a remote program’s address, a client sends an RPC message to a host’s rpcbind daemon. If the service is on the host, the daemon returns the address in an RPC reply message. The client program can then send RPC messages to the server’s address. (A client program can minimize its calls to rpcbind by storing the network addresses of recently called remote programs.)
The RPCBPROC_CALLIT procedure of rpcbind enables a client to make a remote procedure call without knowing the address of the server. The client passes the target procedure’s program number, version number, procedure number, and calling arguments in an RPC call message. rpcbind looks up the target procedure’s address in the address map and sends an RPC call message, including the arguments received from the client, to the target procedure. When the target procedure returns results, RPCBPROC_CALLIT passes them to the client program. It also returns the target procedure’s universal address so that the client can later call it directly. RPCBPROC_CALLIT is available only for UDP for this SSR.
The RPC library provides an interface to all rpcbind procedures. Some of the RPC library procedures also call rpcbind automatically for client and server programs. For details, see Appendix C, “Remote Procedure Call (RPC) Standard: Protocol Specification.”
RPCINFO Command
RPCINFO is a utility that reports current RPC information registered with rpcbind. RPCINFO reports the universal addresses and the transports for all registered RPC services on a specified host. It can call a specific version of a specific program on a specific host and report whether a response is received. For details about the command, see Section 6, “Using the ONC+
RPCSUPPORT Operator Interface.”
Lower RPC Levels
You can use the RPC services at a number of levels, as described in Section 4, “RPC Programming for C Programming Interfaces.” Understanding the lower levels of RPC is helpful but not
necessary when you use RPCGEN to generate your RPC applications. For more information about RPCGEN, see Section 4.
External Data Representation (XDR)
For RPC to function on a variety of system architectures, it requires a standard data representation. RPC uses External Data Representation (XDR). XDR is a machine-independent data description and encoding protocol. Using XDR, RPC can handle arbitrary data structures, regardless of the byte orders or structure layout conventions of different hosts. For a detailed discussion of XDR, see the UNIX System V Release 4.0 Programmer's Guide: Networking Interfaces.
RPC Programming for C Programming
Interfaces
Overview
This section describes the following topics:
• RPC programming in C. This topic includes details about writing network applications using remote procedure calls and the RPC mechanisms usually hidden by the RPCGEN stub compiler.
• C application programming interfaces. This topic includes an alphabetical reference of categories of C application programming interfaces.
• RPCGEN programming. This topic includes details about C programming using the RPCGEN stub compiler.
In this section, whenever the term RPC is used, it refers to ONC+ RPC.
RPC Programming in C
RPC Levels
RPC has a multiple-level application interface to its services. These levels require you to write more interface code depending on the degree of control that you want over the multiple levels of underlying protocol.
Simplified Interface
The simplified interface (the highest level) is very simple, but limits control of the underlying communications mechanisms. Program development at this level can be rapid, and is directly supported by the RPCGEN compiler. For most applications, RPCGEN and its facilities are sufficient.
• Top level • Intermediate level • Expert level • Bottom level
Simplified Interface
IntroductionThe simplified interface is the highest level of RPC. It is the easiest level to use because it requires the use of only the basic RPC routines. The following information describes how to use a number of functions that hide all details of the RPC package.
Basic Routines
The simplified interface library routines provide direct access to the RPC facilities for programs that do not require fine levels of control.
Use the basic routines to make remote procedure calls to routines on other machines, and to specify the type of transport to use. The routines at this level are used for most applications.
Use . . . To . . .
rpc_reg( ) Register a procedure as an RPC program on all transports of the specified nettype. (Not supported in this SSR.)
rpc_call( ) Call the specified procedure on the specified remote host.
rpc_broadcast( ) Broadcast a call message across all transports of the specified type. (Not supported in this SSR.)
Some RPC services are not available as C functions, but they are available as RPC programs. “Registration,” later in this section, describes these easy-to-use services, and how to create new services that are equally simple to use.
Data types passed to and received from remote procedures can be any of a set of predefined types, or can be programmer-defined types. “Passing Arbitrary Data Types,” later in this section, explains how to declare and use these types.
rpc_call( ) Routine
Parametersrpc_call( ) has nine parameters:
Parameter Description
1 Name of the remote server machine.
2, 3, 4 Program, version, and procedure numbers; which together identify the remote procedure to be called.
5, 6 XDR translator to encode the argument and an argument to be passed to the remote procedure.
7, 8 XDR translator to decode the result returned by the remote procedure and a pointer to where the result is to be stored.
9 nettype specifier.
Structures and Data Types
Multiple arguments and results are handled by collecting them in structures. If rpc_call( ) finishes successfully, it returns RPC_SUCCESS. The return codes (of type enum clnt_stat) are in
<rpc.h>.
Since data types might be represented differently on different machines, rpc_call( ) needs both the type of, and a pointer to, the RPC argument (similarly for the result).
If rpc_call( ) receives no answer within a certain time period, it returns an error code. Adjusting the number of retries requires use of the lower levels of the RPC library.
rpc_reg( ) Routine
IntroductionThis routine is not supported in this SSR.
Server procedures and functions are registered with rpcbind to make them accessible to clients. A server registers all the RPC calls it handles, then blocks to wait for requests.
Arguments
Use rpc_reg( ) to register a C program as a specific program, version, and procedure. rpc_reg( ) has seven calling arguments:
Arguments Description
1, 2, 3 Program, version, and procedure numbers of the remote procedure to be registered (unsigned long).
4 Points to a string containing the name of the function that implements the remote procedure.
5 Points to the XDR translator that processes the calling argument (or argument structure) of the program.
6 Points to the XDR translator that processes the return value (or structure) of the program.
7 Specifies the desired nettype.
Registration
The procedure is registered for each transport of the specified type. If the type parameter is
(char *) NULL, the procedure is registered for all transports specified in NETPATH.
After registering the local procedure, the server program’s main procedure calls svc_run( ), the RPC library’s remote procedure dispatcher. This function invokes service procedures in response to RPC call messages. (Because the svc_run( ) routine is used at all levels of programming, it does not belong to any particular level of RPC programming.) The dispatcher in rpc_reg( ) takes care of decoding remote procedure arguments and encoding results, using the XDR filters specified when the remote procedure was registered.
rpc_reg( ) can be called as many times as it is needed to register different programs, versions, and
Example
You can sometimes implement faster or more compact code than RPCGEN. RPCGEN handles the generic code-generation cases. The following program is an example of a hand-coded registration routine. It registers a single procedure and enters svc_run( ) to service requests:
$SET SEARCH = "SYMBOL/ONC/=" #include <stdio.h>
#include <rpc.h> void *rusers(void); main()
{
if(rpc_reg(RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM, rusers, xdr_void, xdr_u_long, "visible") == -1) {
fprintf(stderr, "Couldn't Register\n"); exit(1);
}
svc_run(); /* Never returns */
fprintf(stderr, "Error: svc_run returned!\n"); xit(1);
}
Example 4–1. "Hand-Coding" Registration Server
Passing Arbitrary Data Types
IntroductionRPC handles arbitrary data structures, regardless of the byte orders or structure layout conventions of different machines, by always converting them to a standard transfer format called External Data Representation (XDR) before sending them over the transport. The conversion from a machine representation to XDR is called serializing, and the reverse process is called deserializing.
The translator arguments of rpc_call( ) and rpc_reg( ) can specify an XDR primitive procedure, like xdr_u_long( ), or a programmer-supplied routine that processes a complete argument
structure. Argument processing routines must take only two arguments: a pointer to the result and a pointer to the XDR handle.
XDR Service Routines
XDR services include these primitive type routines:
xdr_int( ) xdr_u_int( ) xdr_enum( )
xdr_long( ) xdr_u_long( ) xdr_bool( )
xdr_short( ) xdr_u_short( ) xdr_wrapstring( )
xdr_char( ) xdr_u_char( ) xdr_void( )
xdr_float( ) xdr_double( )
The nonprimitive xdr_string, which takes more than two parameters, can be called from
xdr_wrapstring( ).
An XDR routine returns nonzero (a C TRUE) if it finishes successfully, and zero otherwise.
Example
For an example of a programmer-supplied routine, the following structure contains the calling arguments of a procedure:
struct simple { int a; short b; } simple;
The XDR routine, xdr_simple( ), uses the following routine to translate the argument structure:
#include <rpc.h> #include "simple.h" bool_t
xdr_simple(XDR * xdrsp, struct simple * simplep) { if (!xdr_int(xdrsp, &simplep->a)) return (FALSE); if (!xdr_short(xdrsp, &simplep->b)) return (FALSE); return (TRUE); }
An equivalent routine can be generated automatically by RPCGEN.
A complete description of XDR is provided in the UNIX System V Release 4.0 Programmer's Guide: Networking Interfaces.
Prefabricated Building Blocks
In addition to the primitives listed previously, there are the following prefabricated building blocks: xdr_array( ) xdr_bytes( ) xdr_opaque( ) xdr_pointer( ) xdr_reference( ) xdr_string( ) xdr_union( ) xdr_vector( ) Example
For example, to send a variable-sized array of integers, the array is packaged in a structure containing the array and its length:
struct varintarr { int *data; int arrlnth; } arr;
Translate the array with xdr_varintarr( ):
bool_t
xdr_varintarr(XDR *xdrsp,struct varintarr * arrp) {
return(xdr_array(xdrsp, (caddr_t)&arrp->data,
(u_int *)&arrp->arrlnth, MAXLEN, sizeof(int), xdr_int)); }
xdr_array( )
The following lists the arguments of xdr_array( ):
• The XDR handle
• A pointer to the array
• A pointer to the size of the array
• The maximum array size
• The size of each array element
• A pointer to the XDR routine to translate each array element If the size of the array is known in advance, use xdr_vector( ):
int intarr[SIZE]; bool_t
xdr_intarr(XDR *xdrsp,int intarr[]) {
return (xdr_vector(xdrsp, intarr, SIZE, sizeof(int), xdr_int)); }
XDR converts quantities to 4-byte multiples when serializing. For arrays of characters, each character occupies 32 bits. xdr_bytes( ) packs characters. It has four parameters similar to the first four parameters of xdr_array( ).
Null-terminated strings are translated by xdr_string( ). It is like xdr_bytes( ) with no length parameter. On serializing, it gets the string length from strlen( ). On deserializing, it creates a null-terminated string.
Example
Example 4–4 calls the built-in functions xdr_string( ) and xdr_reference( ), which translate pointers to pass a string and struct simple, from the previous examples:
struct finalexample { char *string;
struct simple *simplep; } finalexample;
bool_t
xdr_finalexample(XDR *xdrsp,struct finalexample * finalp) {
if( !xdr_string(xdrsp, &finalp->string, MAXSTRLEN)) return (FALSE);
if( !xdr_reference( xdrsp, &finalp->simplep, sizeof(struct simple), xdr_simple )) return (FALSE);
return (TRUE); }
Example 4–4. xdr_reference Syntax Use
Note that xdr_simple( ) could have been called here instead of xdr_reference( ).
Lower Levels
Introduction
The simplified interface takes care of almost as many details as RPCGEN. This is done by choosing defaults for almost everything, including the transport protocol. This section shows how to control RPC details by using lower levels of the RPC library.
Use lower levels of RPC to:
• Select the transport protocol, which can be done at the simplified interface level only through the NETPATH task attribute.
• Allocate and free memory while serializing or deserializing with XDR routines; there is no way to do so at the simplified interface level.
Routines
clnt_destroy( ) clnt_pcreateerror( ) clnt_perrno( ) clnt_perror( ) rac_send( ) rac_drop( ) rac_recv( ) svc_destroy( )
Top Level
IntroductionAt the top level, the interface is still simple, but the program must either create a client handle before making a call or create a server handle before receiving calls. Like the routines in the simplified interface, these routines require a nettype argument that specifies the type or types of transport.
At the top level, the application can specify the type of transport to use but not the individual transport. This level differs from the simplified interface in that the application creates its own transport handles, in both the client and server.
Routines
The top level has two routines:
Use . . . To . . .
clnt_create( ) Create a generic client routine. The program tells
clnt_create( ) where the server is located and the type
of transport to use.
svc_create( ) Create server handles for all transports of the specified nettype. The program tells svc_create( ) which dispatch function to use.
Writing code to the simplified interface and the top level is less complex than writing code for the lower interface levels.
Transport Classes
Both the top level and simplified interfaces use a nettype to define the class of transport. Client programs select the transport, and their efficiency varies depending on the nettype. Server programs might have to listen on multiple transports, and so they use more system resources. In both cases, efficiency can be improved by careful assignment to the NETPATH task attribute.
If you want the application to run on all transports, use this interface.
Client
Assume the following header file:
/* time_prot.h */ #include <rpc.h> struct timev { int second; int minute; int hour; };
typedef struct timev timev; bool_t xdr_timev();
#define TIME_PROG ((u_long)0x40000001) #define TIME_VERS ((u_long)1)
#define TIME_GET ((u_long)1)
Example 4–6 shows the client side of a trivial date service using top-level service routines. The transport type is specified as an invocation argument of the program:
#include <stdlib.h> #include <stdio.h> #include "time_prot.h" #define TOTAL (30) /*
* Caller of trivial date service * usage: calltime hostname */
main(int argc, char * argv[] ) {
struct timeval time_out; CLIENT *client;
enum clnt_stat stat; struct timev timev; char *nettype;
if( argc != 2 && argc != 3 ) {
fprintf( stderr,"usage:%s host[nettype]\n",argv[0] ); exit(1);
}
if( argc == 2 )
nettype = "netpath"; /* Default */ else
nettype = argv[2];
client = clnt_create(argv[1], TIME_PROG, TIME_VERS, nettype); if( client == (CLIENT *) NULL ) {
clnt_pcreateerror("Couldn't create client"); exit(1);
}
timeout.tv_sec = TOTAL; timeout.tv_usec = 0;
stat = clnt_call( client, TIME_GET, (xdrproc_t)xdr_void, (void *)NULL, (xdrproc_t)xdr_timev, (void *)&timev, time_out );
if( stat != RPC_SUCCESS ) {
clnt_perror( client, "Call failed" ); exit(1);
}
printf( "%s: %02d:%02d:%02d GMT\n", nettype, timev.hour, timev.minute, timev.second );
(void) clnt_destroy( client ); exit(0);
}
If nettype is not specified in the invocation of the program, the string “netpath” is substituted. When RPC library routines encounter this string, they substitute the value of the NETPATH task attribute.
If the client handle cannot be created, display the reason for the failure with clnt_pcreateerror( ) , or get the error status by reading the contents of the global variable rpc_createerr.
After the client handle is created, clnt_call( ) is used to make the remote call. The following are the arguments for clnt_call( ):
• The remote procedure number
• An XDR filter for the input argument
• The argument pointer
• An XDR filter for the result
• The result pointer
• The time-out period of the call
The program has no arguments, so xdr_void( ) is specified. Clean up by calling clnt_destroy( ).
Server
Example 4–7 shows a top-level implementation of a server for the trivial date service:
#include <stdlib.h> #include <stdio.h> #include <rpc.h> #include "time_prot.h"
static void time_prog(struct svc_req, SVCXPORT *); main(int argc, char *argv[])
{
int transpnum; char *nettype; if( argc > 2 ) {
fprintf( stderr, "usage: %s [nettype]\n", argv[0] ); exit(1);
}
nettype ); exit(1); } svc_run(); } /*
* The server dispatch function */
static void
time_prog(struct svc_req *rqstp, SVCXPRT *transp ) {
struct timev rslt; time_t thetime;
switch( rqstp->rq_proc ) { case NULLPROC:
svc_sendreply( transp, (xdrproc_t)xdr_void,(void *) NULL ); return; case TIME_GET: break; default: svcerr_noproc( transp ); return; }
thetime = time( (time_t *) 0 ); rslt.second = thetime % 60; thetime /= 60;
rslt.minute = thetime % 60; thetime /= 60;
rslt.hour = thetime % 24;
if(! svc_sendreply( transp, xdr_timev, (void *)&rslt )) { svcerr_systemerr( transp );
} }
Example 4–7. Time Server
svc_create( ) returns the number of transports on which it created server handles. time_prog( ) is
the service function called by svc_run( ) when a request specifies its program and version numbers. The server returns the results to the client through svc_sendreply( ).
When RPCGEN is used to generate the dispatch function, svc_sendreply( ) is called after the procedure returns, so rslt (in this example) must be declared static in the actual procedure.
svc_sendreply( ) is called from inside the dispatch function, so rslt is not declared static.
In this example, the remote procedure takes no arguments. When arguments must be passed, the following calls fetch, deserialize (XDR decode), and free the arguments.:
svc_getargs( SVCXPRT_handle, XDR_filter, (void *)argument_pointer); svc_freeargs( SVCXPRT_handle, XDR_filter, (void *)argument_pointer );
Intermediate Level
IntroductionAt the intermediate level, the application directly chooses the transport to use.
Routines
The intermediate level interface of RPC enables you to control details. Programs written at these lower levels are more complicated but run more efficiently. The intermediate level enables you to specify the transport to use.
Use . . . To . . .
clnt_tp_create( ) Create a client handle for the specified transport. svc_tp_create( ) Create a server handle for the specified transport.
Client
Example 4–8 shows the client side of the time service from “Top Level” in the beginning of this section, written at the intermediate level of RPC. In this example, the user must name the transport over which the call is made on the command line:
#include <stdlib.h> #include <stdio.h> #include <rpc.h> #include "time_prot.h" #define TOTAL (30)
main(int argc, char *argv[] ) int argc;
char *argv[]; {
CLIENT *client;
struct netconfig *nconf; char *netid;
/* Declarations from previous example */
if( argc != 3 ) {fprintf( stderr, "usage: %s host netid/n", argv[0] );exit(1);}
netid = argv[2];
nconf = (struct netconfig *)
malloc (sizeof (struct netconfig)); nconf->nc.netid = netid;
client = clnt_tp_create( argv[1], TIME_PROG, TIME_VERS, nconf ); if( client == (CLIENT *) NULL ) {
clnt_pcreateerror( "Could not create client" ); exit(1);
}
/* Same as previous example after this point */ }
Example 4–8. Client Side of the Time Service
Server
Example 4–9 shows the corresponding server. The command line that starts the service must specify the transport over which the service is provided.
/*
* This program supplies Greenwich mean time to the client * that invokes it. The call format is: server netid */
#include <stdlib.h> #include <stdio.h> #include <rpc.h> #include "time_prot.h"
static void time_prog(struct svc_req*, SVCXPRT *); main(int argc, char *argv[] )
{
SVCXPRT *transp;
struct netconfig *nconf; if( argc != 2 ) {
fprintf( stderr, "usage: %s netid\n", argv[0] ); exit(1);
}
nconf = (struct netconfig *)
malloc (sizeof (struct netconfig)); nconf->nc.netid = netid;
transp = svc_tp_create( time_prog, TIME_PROG, TIME_VERS, nconf ); if( transp == (SVCXPRT *) NULL ) {
fprintf( stderr, "%s: cannot create %s service\n", argv[0], argv[1] ); exit(1) } svc_run(); } static
void time_prog(struct svc_req * rqstp,SVCXPRT *transp ) {
/* Code identical to Top Level version */ }
Expert Level
At the expert level, network selection is done the same way as it is at the intermediate level. The only difference is in the increased level of control that the application has over the details of the
CLIENT and SVCXPRT handles. These examples illustrate this control, which is exercised by
using the clnt_tli_create( ) and svc_tli_create( ) routines.
Routines
The expert level contains a larger set of routines with which to specify transport-related parameters. It includes the following routines:
Use . . . To . . .
clnt_tli_create( ) Create a client handle for the specified transport.
svc_tli_create( ) Create a server handle for the specified transport. rpcb_getaddr( ) Call rpcbind to get the transport addresses of
specified RPC service.
svc_reg( ) Add an association between an RPC service program and a network address.
svc_unreg( ) Delete an association set by svc_reg.
Client
clnt_tli_create( ) is used to create a client handle and to do the following:
• Specify the transport to use
• Pass the server’s address to the client
• Specify the send and receive buffer size
After the client handle has been created, you can modify it by using calls to clnt_control( ).
Server
It uses svc_tli_create( ).
svc_tli_create( ) is used when the application needs a fine degree of control, particularly to do the
following tasks:
• Specify the transport to use.
• Pass the user’s bind address.
• Set the send and receive buffer sizes.
Bottom Level
The bottom-level interface to RPC enables the application to control all options. You rarely use these low-level routines.
Routines
The bottom level contains routines used for full control of transport options. It consists of the following routines:
Use . . . To . . .
clnt_dg_create( ) Create an RPC client handle for the specified remote program, using a connectionless transport.
svc_dg_create( ) Create an RPC server handle, using a connectionless transport.
clnt_vc_create( ) Create an RPC client handle for the specified remote program, using a connection-oriented transport.
svc_vc_create( ) Create an RPC server handle, using a connection-oriented transport.
Examples
The following examples are for reference only and can be changed.
Client RPC Handle Structure
Example 4–10 shows the client RPC handle, defined in <rpc.h>. Low-level implementations must provide and initialize one handle for each connection:
typedef struct {
AUTH *cl_auth; /* authenticator */ struct clnt_ops {
enum clnt_stat (*cl_call)(); /* call remote procedure */ void (*cl_abort)(); /* abort a call */
void (*cl_geterr)(); /* get specific error code */ bool_t (*cl_freeres)(); /* frees results */
void (*cl_destroy)(); /* destroy this structure */ bool_t (*cl_control)(); /* the ioctl() of rpc */ } *cl_ops;
caddrt_t cl_private; /* private stuff */ char *cl_netid; /* *l
char *cl_tp; /* */ } CLIENT;
Client Authentication Handle Structure
The first field of the client-side handle is an authentication structure, defined in <rpc.h>. By default, it is set to AUTH_NONE. A client program must initialize cl_auth appropriately, as shown in Example 4–11.
typedef struct {
struct opaque_auth ah_cred; struct opaque_auth ah_verf; union des_block ah_key; struct auth_ops {
void (*ah_nextverf)();
int (*ah_marshal)(); /* nextverf & serialize */ int (*ah_validate)(); /* validate varifier */ int (*ah_refresh)(); /* refresh credentials */ void (*ah_destroy)(); /* destroy this structure */ } *ah_ops;
caddr_t ah_private; } AUTH;
Example 4–11. Client’s Authentication Handle
In the AUTH structure, ah_cred contains the caller’s credentials, and ah_verf contains the data to verify the credentials. (See “Authentication” later in this section for details.)
Server Transport Handle Structure
Example 4–12 shows the server transport handle.
typedef struct { int xp_fd; struct xp_ops {
bool_t (*xp_recv)(); /* receive incoming requests */ enum xprt_stat (*xp_stat)(); /* get transport status */
bool_t (*xp_getargs)(); /* get arguments */ bool_t (*xp_reply)(); /* send reply */ bool_t (*xp_sendreply)();
bool_t (*xp_freeargs)(); /* free mem alloc for args */ void (*xp_destroy)(); /* destroy this struct */ } *xp_ops;
caddr_t xp_p1; /* private: for use by svc ops */ } SVCXPRT;
The following table explains the fields used in the preceding example:
Field Explanation
xp_fd The port file service attribute.
xp_ltaddr The server’s own bind address.
The rest of the fields are initialized by the bottom-level server routines svc_dg_create( ) and
svc_vc_create( ).
Advanced RPC Programming Techniques
This section addresses areas of occasional interest to programmers using the lower level interfaces of the RPC package. The topics are:
• rpc_poll( ) on the server side. If calling svc_run( ) is not feasible, a server can call the dispatcher directly.
• Batching. Performance can be improved by batching a series of calls.
• Authentication. Two methods in common use are described.
• Server versions. Programs with multiple versions must be assigned consecutively.
• Client versions. Clients can accommodate different hosts running different versions of RPC servers
• Connection-oriented transports. An XDR procedure can behave differently on serialization than it does on deserialization when a connection-oriented transport is used.
• Memory allocation with XDR. XDR routines normally free automatically allocated memory.
rpc_poll( ) on the Server Side
A process that services RPC requests and performs some other activity cannot always call
svc_run( ). If the other activity periodically updates a data structure, the process can set a SIGALRM signal before calling svc_run( ). This allows the signal handler to process the data
structure and return control to svc_run( ) when done.
Batching
RPC is designed so that clients send a call message and wait for servers to reply to the call. This implies that a client is blocked while the server processes the call, which is inefficient when the client does not need to have each message acknowledged.
RPC batching enables clients to process asynchronously. RPC messages can be placed in a pipeline of calls to a server. Batching requires that
• The server does not respond to any intermediate message.
• The pipeline of calls is transported on a reliable transport, such as TCP.
• The XDR routine for result in the calls must be NULL.
• The timeout for the RPC call must be zero.
Because the server does not respond to each call, the client can send new calls in parallel, with the server processing previous calls. The transport can buffer many call messages and send them to the server in one write( ) system call. This process decreases interprocess communication overhead and the total time of a series of calls. The client should end with a nonbatched call to flush the pipeline.
Example 4–13 shows the unbatched version of the client. It scans the character array, buf, for delimited strings and sends each string to the server.
#include <stdlib.h> #include <stdio.h> #include <rpc.h> #include "windows.h"
main(int argc, char **argv ) {
struct timeval total_timeout; register CLIENT *client; enum clnt_stat clnt_stat; char buf[1000], *s = buf;
if(( client = clnt_create( argv[1], WINDOWPROG, WINDOWVERS, "circuit_v" )) == (CLIENT *) NULL ) {
clnt_pcreateerror( "clnt_create" ); exit(1);
}
total_timeout.tv_sec = 20; total_timeout.tv_usec = 0;
while( scanf( "%s", s ) != EOF ) {
if( clnt_call( client, RENDERSTRING, (xdrproc_t)xdr_wrapstring, (void *)&s,
(xdrproc_t)xdr_void, (void *) NULL, total_timeout ) != RPC_SUCCESS) { clnt_perror( client, "rpc" ); exit(1); } } clnt_destroy( client ); exit(0); }
Example 4–14 shows the batched version of the client. It does not wait after each string is sent to the server. It waits only for an ending response from the server.
#include <stdlib.h> #include <stdio.h> #include <rpc.h> #include "windows.h"
main(int argc,char **argv ) {
struct timeval total_timeout; register CLIENT *client; enum clnt_stat clnt_stat; char buf[1000], *s = buf;
if(( client = clnt_create( argv[1], WINDOWPROG, WINDOWVERS, "circuit_v" )) == (CLIENT *) NULL ) {
clnt_pcreateerror( "clnt_create" ); exit(1);
}
timerclear( &total_timeout ); while( scanf( "%s", s ) != EOF )
clnt_call( client, RENDERSTRING_BATCHED, (xdrproc_t)xdr_wrapstring, (void *)&s, (xdrproc_t)xdr_void, (caddr_t) NULL, total_timeout ); /* Now flush the pipeline */
total_timeout.tv_sec = 20;
clnt_stat = clnt_call( client, NULLPROC, (xdrproc_t)xdr_void,
(void *) NULL, (xdrproc_t)xdr_void, (void *) NULL, total_timeout ); if( clnt_stat != RPC_SUCCESS ) {
clnt_perror( client, "rpc" ); exit(1); } clnt_destroy( client ); exit(0); }
Example 4–15 shows the dispatch portion of the batched server.
#include <stdio.h> #include <rpc.h> #include "windows.h" void
windowdispatch(struct svc_req *rqstp,SVCXPRT *transp ) {
char *s = NULL;
switch( rqstp->rq_proc ) { case NULLPROC:
if( !svc_sendreply( transp, (xdrproc_t)xdr_void, (void *)NULL )) fprintf( stderr, "can't reply to RPC call\n" );
return;
case RENDERSTRING:
if( !svc_getargs( transp, (xdrproc_t)xdr_wrapstring, (void *)&s )) { fprintf( stderr, "can't decode arguments\n" );
/* Tell caller an error occurred */ svcerr_decode( transp );
break; }
/* Code here to render the string s */
if( !svc_sendreply( transp, xdr_void, (void *) NULL )) fprintf( stderr, "can't reply to RPC call\n" ); break;
case RENDERSTRING_BATCHED:
if( !svc_getargs( transp, (xdrproc_t)xdr_wrapstring, (void *)&s )) { fprintf( stderr, "can't decode arguments\n" );
/* Be silent in the face of protocol errors */ break;
}
/* Code here to render string s, but send no reply! */ break;
default:
svcerr_noproc( transp ); return;
}
/* Now free string allocated while decoding arguments */ svc_freeargs( transp, xdr_wrapstring, (void *)&s ); }
Because the server sends no message, the clients are not notified of failures. Use the clnt_call routine in conjunction with the clnt_control routine to provide batching and “instant response.”
Batching Performance
To illustrate the benefits of batching, the samples in Example 4–13, Example 4–14, and Example 4–15 are completed to render the lines in a 25144-line file. The rendering service simply deletes the lines. The batched version of the application is four times as fast as the unbatched version.
Authentication
In all the preceding examples in this section, the caller has not identified itself to the server, and the server has not required identification of the caller. Some network services, such as a network file system, require caller identification.
Just as different transports can be used when you are creating RPC clients and servers, you can associate different “flavors” of authentication with RPC clients. The default authentication flavor,
AUTH_NONE ( ), does no authentication.
Refer to the Security Administration Guide for more information on authentication and security for RPC.
In addition to AUTH_NONE, RPC supports the following authentication flavors:
Use . . . As . . .
AUTH_SYS An authentication flavor based on UNIX operating system process permissions authentication.
AUTH_SHORT An alternate flavor of AUTH_SYS used by some servers for efficiency. Client programs using the AUTH_SYS
authentication can receive AUTH_SHORT response verifiers from some servers. See Appendix C, “Remote Procedure Calls (RPC) Standard: Protocol Specification” for details.
AUTH_KERB Kerberos authentication style. (Not supported by A Series.)
AUTH_DES An authentication flavor based on DES encryptions techniques. (Not supported by A Series.)
A caller creates a new RPC client handle in the following example:
clnt = clnt_create(host, prognum, versnum, nettype);
The appropriate client-creation routine then sets the associated authentication handle to
clnt->cl_auth = authnone_create();
If you create a new instance of authentication, you must destroy the previous authentication instance with the following syntax to conserve memory:
On the server side, the RPC package passes to the service-dispatch routine a request that has an arbitrary authentication style associated with it. The request handle passed to a service-dispatch routine contains the structure rq_cred. It is opaque, except for one field: the flavor of the authentication credentials.
/*
* Authentication data */
struct opaque_auth {
enum_t oa_flavor; /* style of credentials */ caddr_t oa_base; /* address of more auth stuff */ u_int oa_length; /* not to exceed MAX_AUTH_BYTES */ };
The RPC package guarantees the following to the service-dispatch routine:
• The rq_cred field is well formed. So, you can check rq_cred.oa_flavor to get the flavor of authentication. You can al
