1 2PLEASE READ THE DISCLAIMER FILE. DO NOT CALL THE SUN MICROSYSTEMS SUPPORT 3LINE WITH QUESTIONS ON THIS RELEASE. THEY CANNOT ANSWER QUESTIONS ABOUT THIS 4UNSUPPORTED SOURCE RELEASE. 5 6TIRPCSRC 2.3 29 Aug 1994 7 8This distribution contains SunSoft's implementation of transport-independent 9RPC (TI-RPC), External Data Representation (XDR), and various utilities and 10documentation. These libraries and programs form the base of Open Network 11Computing (ONC), and are derived directly from the Solaris 2.3 source. 12 13Previous releases of RPC Source based on SunOS 4.x were ported to 4.2BSD and 14used Sockets as the transport interface. These versions were 15transport-specific RPC (TS-RPC). 16 17TI-RPC is an enhanced version of TS-RPC that requires the UNIX System V 18Transport Layer Interface (TLI) or an equivalent X/Open Transport Interface 19(XTI). TI-RPC is on-the-wire compatible with the TS-RPC, which is supported 20by almost 70 vendors on all major operating systems. TS-RPC source code 21(RPCSRC 4.0) remains available from several internet sites. 22 23This release is a native source release, that is, it is compatible for 24building on Solaris 2.3. This release was built on Solaris 2.3 using SunPro 25SPARCompiler 2.0.1. 26 27Solaris 2.3 is based on System V, Release 4 (SVR4), and while this release 28should be mostly compatible with other SVR4 systems, some Solaris facilities 29that are assumed may not be available. In particular, this release uses the 30Makefile format supported by SparcCompiler 2.0.1. Second, the Secure RPC 31routines use the Solaris Name Service Switch to access public-key credential 32databases. This code will need to be ported if your system does not support 33the Name Service Switch. Finally, this release uses the synchronization 34interfaces of UI Threads to make certain interfaces thread-safe. These 35interfaces are found in libthread in Solaris 2.3 and later. 36 37Applications linked with this release's librpc must link with the United 38States domestic version of libcrypt in order to resolve the cbc_crypt() and 39ecb_crypt() functions. These routines are used with Secure RPC however all 40RPC programs that link with this release's librpc will need to link with the 41domestic libcrypt. Note that the Solaris 2.3 Encryption Kit is only available 42within the United States. (PLEASE NOTE: The RPC implementation found in 43Solaris 2.3's libnsl does *not* have this requirement; linking with libcrypt 44is only a requirement for the TIRPCSRC 2.3 version of librpc.) 45 46 47DOCUMENTATION NOTE 48 49The documentation found in the doc directory are derived from the Solaris 2.3 50Network Interfaces Programming Guide. A small number of compile examples are 51given, and these use libnsl to link in the RPC library. This release builds 52the RPC library as librpc. To use this release's librpc, use the link command 53"-lrpc -lnsl -lcrypt". This links the application with TIRPCSRC 2.3's librpc 54for RPC routines, Solaris's libnsl for other networking functions, and 55libcrypt for the cbc_crypt() and ecb_crypt functions. 56 57 58WHY IS THIS RELEASE BEING DONE? 59 60This release is being distributed to make the Sun implementation of the ONC 61technologies available for reference and porting to non-Solaris platforms. 62The current release is a native source distribution, and provides services 63that are already available on Solaris 2.3 (such as the RPC headers, the RPC 64library in libnsl, rpcbind, rpcinfo, etc.). It is not our intention to 65replace these services. See the DISCLAIMER for further information about the 66legal status of this release. 67 68 69WHAT'S NEW IN THIS RELEASE: TIRPCSRC 2.3 70 71The previous release was TIRPCSRC 2.0. 72 731. This release is based on Solaris 2.3. The previous release was 74 based on Solaris 2.0. This release contains a significant number of 75 bug fixes and other enhancements over TIRPCSRC 2.0. 76 772. The RPC library is thread safe for all client-side interfaces 78 (clnt_create, clnt_call, etc.). The server-side interfaces 79 (svc_create, svc_run, etc.) are not thread safe in this release. The 80 server-side interfaces will be made thread safe in the next release of 81 TIRPCSRC. Please see the manual pages for details about which 82 interfaces are thread safe. 83 843. As part of the work to make the RPC library thread-safe, rpcgen has 85 been enhanced to generate thread-safe RPC stubs (the -M option). Note 86 that this modifies the call-signature for the stub functions; the 87 procedure calling the RPC stub must now pass to the stub a pointer to 88 an allocated structure where results will be placed by the stub. See 89 the rpcgen manual page and the rpcgen Programming Guide for details. 90 914. The Remote Asynchronous Calls (RAC) library is now included. RAC was 92 first introduced in TIRPCSRC 1.0, and was bundled with librpc. It is 93 now a separate library. The asynchronous call model that RAC provides 94 can be achieved by using threads for making client-side RPC calls. 95 The ONC Technology group recommends using threads (where possible) to 96 achieve asynchrony rather than RAC. See the rpc_rac(3n) manual page 97 for details. 98 99 100ROADMAP 101 102The directory hierarchy is as follows: 103 104 cmd/ Utilities 105 cmd/rpcgen The RPC Language compiler (for .x files) 106 cmd/rpcbind The RPC bindery and portmapper 107 cmd/rpcinfo RPC bindery query utility 108 cmd/keyserv The Secure RPC keyserver 109 cmd/demo Some simple ONC demo services 110 111 doc/ Postscript versions of ONC documentation 112 113 head/ Header files 114 head/rpcsvc RPCL (.x) specifications for various ONC services, and 115 header files. 116 117 lib/ Libraries 118 lib/librpc The RPC and XDR library 119 lib/librac The Remote Asynchronous Calls (RAC) library 120 121 man/ Manual pages for the RPC library and utilities. 122 123 uts/common/rpc RPC header files 124 125 126 127BUILD INSTRUCTIONS 128 129Prior to building the release, you must define the SRC environment variable 130to be the path to the top-level Makefile. For example, if /usr/src/tirpcsrc 131is where to top-level Makefile is located, execute this command prior to 132building the release: 133 134 setenv SRC /usr/src/tirpcsrc (csh) 135or 136 SRC=/usr/src/tirpcsrc; export SRC (sh) 137 138The sources in the lib directory depend on header files installed from head 139and uts/common/rpc, and the programs in the cmd directory depend on libraries 140from lib. Therefore, you should do a "make install" to build the release. 141 142The top-level Makefile builds the release. The "ROOT" macro defines where the 143headers and libraries are installed. The default for ROOT is "/proto". You 144may change this by either modifiying Makefile.master, or issuing the build 145command with a new definition for ROOT: 146 147 make install ROOT=/opt/onc 148 149You will of course need write privileges for the destination directory. 150The headers, libraries and executables will be built and installed under the 151ROOT. 152 153 154The demonstration services in the demo directory are not built by the 155top-level "make install" command. To build these, cd to the cmd/demo 156directory and enter "make". The four services will be built. 157RPCGEN MUST BE INSTALLED in a path that make can find. To run the 158services, rpcbind must be running, then invoke the service 159(you probably will want to put it in the background). rpcinfo can be 160used to check that the service succeeded in getting registered with 161rpcbind, and to ping the service (see rpcinfo's man page). You can 162then use the corresponding client program to exercise the service. 163 164 165BUILDING ONC APPLICATIONS 166 167See the Makefiles in the demonstration services for examples of building 168ONC applications with this release. The $(ROOT)/usr/include directory 169must be included in the compiler header file search path (-I), and the 170$(ROOT)/usr/lib directory must be included in the linker library file search 171path (-L). Also, to run executables built dynamically, the shared library 172search path (LD_LIBRARY_PATH) must also include $(ROOT)/usr/lib. In addition 173to linking in this release's librpc (via -lrpc), you must also link with 174Solaris's libnsl (-lnsl) and the US domestic version of libcrypt (-lcrypt). 175 176