CONTENTS Title Page Copyright Page Preface 1 Introduction to Remote Procedure Calls 1.1 Overview 1.2 The RPC Model 1.3 RPC Procedure Versions 1.4 Using Portmapper to Determine the Destination Port Number of RPC Packets 1.4.1 Portmapper Notes for UCX 1.4.2 Displaying Registered RPC Servers 1.5 RPC Independence from Transport Protocol 1.6 External Data Representation (XDR) 1.7 Assigning Program Numbers 2 Writing RPC Applications with the RPCGEN Protocol Compiler 2.1 The RPCGEN Protocol Compiler 2.2 Simple Example: Using RPCGEN to Generate Client and Server RPC Code 2.2.1 RPC Protocol Specification File Describing Remote Procedure 2.2.2 Implementing the Procedure Declared in the Protocol Specification 2.2.3 The Client Program That Calls the Remote Procedure 2.2.4 Running RPCGEN 2.2.5 Compiling the Client and Server Programs 2.2.6 Copying the Server to a Remote System and Running It 2.3 Advanced Example: Using RPCGEN to Generate XDR Routines 2.3.1 The RPC Protocol Specification 2.3.2 Implementing the Procedure Declared in the Protocol Specification 2.3.3 The Client Program that Calls the Remote Procedure 2.3.4 Running RPCGEN 2.3.5 Compiling the File of XDR Routines 2.3.6 Compiling the Client and Server Programs 2.3.7 Copying the Server to a Remote System and Running It 2.4 Debugging Applications 2.5 The C Preprocessor 2.6 RPCGEN Programming 2.6.1 Network Types 2.6.2 User-Provided Define Statements 2.6.3 inetd Support 2.6.4 Dispatch Tables 2.7 Client Programming 2.7.1 Timeout Changes 2.7.2 Client Authentication 2.8 Server Programming 2.8.1 Handling Broadcasts 2.8.2 Passing Data to Server Procedures 2.9 RPC and XDR Languages 2.9.1 Definitions 2.9.2 Enumerations 2.9.3 Typedefs 2.9.4 Constants 2.9.5 Declarations 2.9.6 Structures 2.9.7 Unions 2.9.8 Programs 2.9.9 Special Cases RPCGEN 3 RPC Application Programming Interface 3.1 RPC Layers 3.2 Middle Layer of RPC 3.2.1 Using callrpc 3.2.2 Using registerrpc and svc_run 3.2.3 Using XDR Routines to Pass Arbitrary Data Types 3.2.4 User-Defined XDR Routines 3.2.5 XDR Serializing Defaults 3.3 Lowest Layer of RPC 3.3.1 The Server Side and the Lowest RPC Layer 3.3.2 The Client Side and the Lowest RPC Layer 3.3.3 Memory Allocation with XDR 3.4 Raw RPC 3.5 Miscellaneous RPC Features 3.5.1 Using Select on the Server Side 3.5.2 Broadcast RPC 3.5.3 Batching 3.6 Authentication of RPC Calls 3.6.1 The Client Side 3.6.2 The Server Side 3.7 Using the Internet Service Daemon (inetd) 3.8 Additional Examples 3.8.1 Program Versions on the Server Side 3.8.2 Program Versions on the Client Side 3.8.3 Using the TCP Transport 3.8.4 Callback Procedures 4 External Data Representation 4.1 Usefulness of XDR 4.1.1 A Canonical Standard 4.1.2 The XDR Library 4.2 XDR Library Primitives 4.2.1 Number and Single-Character Filters 4.2.2 Floating-Point Filters 4.2.3 Enumeration Filters 4.2.4 Possibility of No Data 4.2.5 Constructed Data Type Filters 4.2.5.1 Strings 4.2.5.2 Variable-Length Byte Arrays 4.2.5.3 Variable-Length Arrays of Arbitrary Data Elements 4.2.5.4 Fixed-Length Arrays of Arbitrary Data Elements 4.2.5.5 Opaque Data 4.2.5.6 Discriminated Unions 4.2.5.7 Pointers 4.2.6 Non-filter Primitives 4.3 XDR Operation Directions 4.4 XDR Stream Access 4.4.1 Standard I/O Streams 4.4.2 Memory Streams 4.4.3 Record (TCP/IP) Streams 4.4.4 XDR Stream Implementation 4.5 Advanced Topics 5 ONC RPC Client Routines auth_destroy authnone_create authunix_create authunix_create_default callrpc clnt_broadcast clnt_call clnt_control clnt_create clnt_create_vers clnt_destroy clnt_freeres clnt_geterr clnt_pcreateerror clnt_perrno clnt_perror clnt_spcreateerror clnt_sperrno clnt_sperror clntraw_create clnttcp_create clntudp_bufcreate clntudp_create get_myaddress get_myaddr_dest 6 ONC RPC Portmapper Routines pmap_getmaps pmap_getmaps_vms pmap_getport pmap_rmtcall pmap_set pmap_unset 7 ONC RPC Server Routines registerrpc seterr_reply svc_destroy svc_freeargs svc_getargs svc_getcaller svc_getreqset svc_register svc_run svc_sendreply svc_unregister svcerr_auth svcerr_decode svcerr_noproc svcerr_noprog svcerr_progvers svcerr_systemerr svcerr_weakauth svcraw_create svcfd_create svctcp_create svcudp_bufcreate svcudp_create xprt_register xprt_unregister _authenticate 8 XDR Routine Reference xdr_accepted_reply xdr_array xdr_authunix_parms xdr_bool xdr_bytes xdr_callhdr xdr_callmsg xdr_char xdr_double xdr_enum xdr_float xdr_free xdr_hyper xdr_int xdr_long xdr_opaque xdr_opaque_auth xdr_pmap xdr_pmap_vms xdr_pmaplist xdr_pmaplist_vms xdr_pointer xdr_reference xdr_rejected_reply xdr_replymsg xdr_short xdr_string xdr_u_char xdr_u_hyper xdr_u_int xdr_u_long xdr_u_short xdr_union xdr_vector xdr_void xdr_wrapstring xdrmem_create xdrrec_create xdrrec_endofrecord xdrrec_eof xdrrec_skiprecord xdrstdio_create A Acronyms EXAMPLES 2-1 Printing a Remote Message Without ONC RPC 2-2 RPC Protocol Specification File Simple Example 2-3 Remote Procedure Definition 2-4 Client Program that Calls the Remote Procedure 2-5 RPC Protocol Specification File-Advanced Example 2-6 Remote Procedure Implementation 2-7 Client Program that Calls the Server 2-8 Using the Percent Sign to Bypass Interpretation of a Line 3-1 Using callrpc 3-2 Remote Server Procedure 3-3 Using registerrpc in the Main Body of a Server Program 3-4 Server Program Using Lowest Layer of RPC 3-5 Using Lowest RPC Layer to Control Data Transport and Delivery 3-6 Debugging and Testing the Noncommunication Parts of an Application 3-7 Server Batching 3-8 Client Batching 3-9 Authentication on Server Side 3-10 C Procedure That Returns Two Different Data Types 3-11 Determining Server-Supported Versions and Creating Associated Client Handles 3-12 RPC Example that Uses TCP Protocol-XDR Routine 3-13 RPC Example that Uses TCP Protocol- Client 3-14 RPC Example that Uses TCP Protocol- Server 3-15 Client Usage of the gettransient Routine 3-16 Server Usage of the gettransient Routine 4-1 4-2 4-3 4-4 FIGURES 1-1 Basic Network Communication with Remote Procedure Call TABLES 1 Telephone and Direct Mail Orders 3-1 XDR Routines 5-1 ONC RPC Client Routines 6-1 ONC RPC Portmapper Routines 7-1 ONC RPC SERVER Routines 8-1 XDR Data Conversion Routines 8-2 XDR Stream Handling Routines A-1 Acronyms