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