174462Salfred$FreeBSD$ 21901Swollman 374462SalfredPLEASE READ THE DISCLAIMER FILE. DO NOT CALL THE SUN MICROSYSTEMS SUPPORT 474462SalfredLINE WITH QUESTIONS ON THIS RELEASE. THEY CANNOT ANSWER QUESTIONS ABOUT THIS 574462SalfredUNSUPPORTED SOURCE RELEASE. 61901Swollman 774462SalfredTIRPCSRC 2.3 29 Aug 1994 81901Swollman 974462SalfredThis distribution contains SunSoft's implementation of transport-independent 1074462SalfredRPC (TI-RPC), External Data Representation (XDR), and various utilities and 1174462Salfreddocumentation. These libraries and programs form the base of Open Network 1274462SalfredComputing (ONC), and are derived directly from the Solaris 2.3 source. 131901Swollman 1474462SalfredPrevious releases of RPC Source based on SunOS 4.x were ported to 4.2BSD and 1574462Salfredused Sockets as the transport interface. These versions were 1674462Salfredtransport-specific RPC (TS-RPC). 171901Swollman 1874462SalfredTI-RPC is an enhanced version of TS-RPC that requires the UNIX System V 1974462SalfredTransport Layer Interface (TLI) or an equivalent X/Open Transport Interface 2074462Salfred(XTI). TI-RPC is on-the-wire compatible with the TS-RPC, which is supported 2174462Salfredby almost 70 vendors on all major operating systems. TS-RPC source code 2274462Salfred(RPCSRC 4.0) remains available from several internet sites. 231901Swollman 2474462SalfredThis release is a native source release, that is, it is compatible for 2574462Salfredbuilding on Solaris 2.3. This release was built on Solaris 2.3 using SunPro 2674462SalfredSPARCompiler 2.0.1. 271901Swollman 2874462SalfredSolaris 2.3 is based on System V, Release 4 (SVR4), and while this release 2974462Salfredshould be mostly compatible with other SVR4 systems, some Solaris facilities 3074462Salfredthat are assumed may not be available. In particular, this release uses the 3174462SalfredMakefile format supported by SparcCompiler 2.0.1. Second, the Secure RPC 3274462Salfredroutines use the Solaris Name Service Switch to access public-key credential 3374462Salfreddatabases. This code will need to be ported if your system does not support 3474462Salfredthe Name Service Switch. Finally, this release uses the synchronization 3574462Salfredinterfaces of UI Threads to make certain interfaces thread-safe. These 3674462Salfredinterfaces are found in libthread in Solaris 2.3 and later. 371901Swollman 3874462SalfredApplications linked with this release's librpc must link with the United 3974462SalfredStates domestic version of libcrypt in order to resolve the cbc_crypt() and 4074462Salfredecb_crypt() functions. These routines are used with Secure RPC however all 4174462SalfredRPC programs that link with this release's librpc will need to link with the 4274462Salfreddomestic libcrypt. Note that the Solaris 2.3 Encryption Kit is only available 4374462Salfredwithin the United States. (PLEASE NOTE: The RPC implementation found in 4474462SalfredSolaris 2.3's libnsl does *not* have this requirement; linking with libcrypt 4574462Salfredis only a requirement for the TIRPCSRC 2.3 version of librpc.) 461901Swollman 471901Swollman 4874462SalfredDOCUMENTATION NOTE 491901Swollman 5074462SalfredThe documentation found in the doc directory are derived from the Solaris 2.3 5174462SalfredNetwork Interfaces Programming Guide. A small number of compile examples are 5274462Salfredgiven, and these use libnsl to link in the RPC library. This release builds 5374462Salfredthe RPC library as librpc. To use this release's librpc, use the link command 5474462Salfred"-lrpc -lnsl -lcrypt". This links the application with TIRPCSRC 2.3's librpc 5574462Salfredfor RPC routines, Solaris's libnsl for other networking functions, and 5674462Salfredlibcrypt for the cbc_crypt() and ecb_crypt functions. 571901Swollman 581901Swollman 5974462SalfredWHY IS THIS RELEASE BEING DONE? 601901Swollman 6174462SalfredThis release is being distributed to make the Sun implementation of the ONC 6274462Salfredtechnologies available for reference and porting to non-Solaris platforms. 6374462SalfredThe current release is a native source distribution, and provides services 6474462Salfredthat are already available on Solaris 2.3 (such as the RPC headers, the RPC 6574462Salfredlibrary in libnsl, rpcbind, rpcinfo, etc.). It is not our intention to 6674462Salfredreplace these services. See the DISCLAIMER for further information about the 6774462Salfredlegal status of this release. 681901Swollman 691901Swollman 7074462SalfredWHAT'S NEW IN THIS RELEASE: TIRPCSRC 2.3 711901Swollman 7274462SalfredThe previous release was TIRPCSRC 2.0. 731901Swollman 7474462Salfred1. This release is based on Solaris 2.3. The previous release was 7574462Salfred based on Solaris 2.0. This release contains a siginificant number of 7674462Salfred bug fixes and other enhancements over TIRPCSRC 2.0. 771901Swollman 7874462Salfred2. The RPC library is thread safe for all client-side interfaces 7974462Salfred (clnt_create, clnt_call, etc.). The server-side interfaces 8074462Salfred (svc_create, svc_run, etc.) are not thread safe in this release. The 8174462Salfred server-side interfaces will be made thread safe in the next release of 8274462Salfred TIRPCSRC. Please see the manual pages for details about which 8374462Salfred interfaces are thread safe. 841901Swollman 8574462Salfred3. As part of the work to make the RPC library thread-safe, rpcgen has 8674462Salfred been enhanced to generate thread-safe RPC stubs (the -M option). Note 8774462Salfred that this modifies the call-signature for the stub functions; the 8874462Salfred procedure calling the RPC stub must now pass to the stub a pointer to 8974462Salfred an allocated structure where results will be placed by the stub. See 9074462Salfred the rpcgen manual page and the rpcgen Programming Guide for details. 911901Swollman 9274462Salfred4. The Remote Asynchronous Calls (RAC) library is now included. RAC was 9374462Salfred first introduced in TIRPCSRC 1.0, and was bundled with librpc. It is 9474462Salfred now a separate library. The asynchronous call model that RAC provides 9574462Salfred can be achieved by using threads for making client-side RPC calls. 9674462Salfred The ONC Technology group recommends using threads (where possible) to 9774462Salfred achieve asynchrony rather than RAC. See the rpc_rac(3n) manual page 9874462Salfred for details. 991901Swollman 1001901Swollman 10174462SalfredROADMAP 1021901Swollman 10374462SalfredThe directory hierarchy is as follows: 1041901Swollman 10574462Salfred cmd/ Utilities 10674462Salfred cmd/rpcgen The RPC Language compiler (for .x files) 10774462Salfred cmd/rpcbind The RPC bindery and portmapper 10874462Salfred cmd/rpcinfo RPC bindery query utility 10974462Salfred cmd/keyserv The Secure RPC keyserver 11074462Salfred cmd/demo Some simple ONC demo services 1111901Swollman 11274462Salfred doc/ Postscript versions of ONC documentation 1131901Swollman 11474462Salfred head/ Header files 11574462Salfred head/rpcsvc RPCL (.x) specifications for various ONC services, and 11674462Salfred header files. 1171901Swollman 11874462Salfred lib/ Libraries 11974462Salfred lib/librpc The RPC and XDR library 12074462Salfred lib/librac The Remote Asynchronous Calls (RAC) library 1211901Swollman 12274462Salfred man/ Manual pages for the RPC library and utilities. 1231901Swollman 12474462Salfred uts/common/rpc RPC header files 1251901Swollman 1261901Swollman 1271901Swollman 12874462SalfredBUILD INSTRUCTIONS 1291901Swollman 13074462SalfredPrior to building the release, you must define the SRC environment variable 13174462Salfredto be the path to the top-level Makefile. For example, if /usr/src/tirpcsrc 13274462Salfredis where to top-level Makefile is located, execute this command prior to 13374462Salfredbuilding the release: 1341901Swollman 13574462Salfred setenv SRC /usr/src/tirpcsrc (csh) 13674462Salfredor 13774462Salfred SRC=/usr/src/tirpcsrc; export SRC (sh) 1381901Swollman 13974462SalfredThe sources in the lib directory depend on header files installed from head 14074462Salfredand uts/common/rpc, and the programs in the cmd directory depend on libraries 14174462Salfredfrom lib. Therefore, you should do a "make install" to build the release. 1421901Swollman 14374462SalfredThe top-level Makefile builds the release. The "ROOT" macro defines where the 14474462Salfredheaders and libraries are installed. The default for ROOT is "/proto". You 14574462Salfredmay change this by either modifiying Makefile.master, or issuing the build 14674462Salfredcommand with a new definition for ROOT: 1471901Swollman 14874462Salfred make install ROOT=/opt/onc 1491901Swollman 15074462SalfredYou will of course need write privileges for the destination directory. 15174462SalfredThe headers, libraries and executables will be built and installed under the 15274462SalfredROOT. 1531901Swollman 1541901Swollman 15574462SalfredThe demonstration services in the demo directory are not built by the 15674462Salfredtop-level "make install" command. To build these, cd to the cmd/demo 15774462Salfreddirectory and enter "make". The four services will be built. 15874462SalfredRPCGEN MUST BE INSTALLED in a path that make can find. To run the 15974462Salfredservices, rpcbind must be running, then invoke the service 16074462Salfred(you probably will want to put it in the background). rpcinfo can be 16174462Salfredused to check that the service succeeded in getting registered with 16274462Salfredrpcbind, and to ping the service (see rpcinfo's man page). You can 16374462Salfredthen use the corresponding client program to exercise the service. 1641901Swollman 1651901Swollman 16674462SalfredBUILDING ONC APPLICATIONS 1671901Swollman 16874462SalfredSee the Makefiles in the demonstration services for examples of building 16974462SalfredONC applications with this release. The $(ROOT)/usr/include directory 17074462Salfredmust be included in the compiler header file search path (-I), and the 17174462Salfred$(ROOT)/usr/lib directory must be included in the linker library file search 17274462Salfredpath (-L). Also, to run executables built dynamically, the shared library 17374462Salfredsearch path (LD_LIBRARY_PATH) must also include $(ROOT)/usr/lib. In addition 17474462Salfredto linking in this release's librpc (via -lrpc), you must also link with 17574462SalfredSolaris's libnsl (-lnsl) and the US domestic version of libcrypt (-lcrypt). 1761901Swollman 177