diff options
Diffstat (limited to 'lib/libc/rpc/README')
| -rw-r--r-- | lib/libc/rpc/README | 361 |
1 files changed, 152 insertions, 209 deletions
diff --git a/lib/libc/rpc/README b/lib/libc/rpc/README index ad9d70f..c915fad 100644 --- a/lib/libc/rpc/README +++ b/lib/libc/rpc/README @@ -1,233 +1,176 @@ -RPCSRC 4.0 7/11/89 +$FreeBSD$ + +PLEASE READ THE DISCLAIMER FILE. DO NOT CALL THE SUN MICROSYSTEMS SUPPORT +LINE WITH QUESTIONS ON THIS RELEASE. THEY CANNOT ANSWER QUESTIONS ABOUT THIS +UNSUPPORTED SOURCE RELEASE. + +TIRPCSRC 2.3 29 Aug 1994 + +This distribution contains SunSoft's implementation of transport-independent +RPC (TI-RPC), External Data Representation (XDR), and various utilities and +documentation. These libraries and programs form the base of Open Network +Computing (ONC), and are derived directly from the Solaris 2.3 source. + +Previous releases of RPC Source based on SunOS 4.x were ported to 4.2BSD and +used Sockets as the transport interface. These versions were +transport-specific RPC (TS-RPC). + +TI-RPC is an enhanced version of TS-RPC that requires the UNIX System V +Transport Layer Interface (TLI) or an equivalent X/Open Transport Interface +(XTI). TI-RPC is on-the-wire compatible with the TS-RPC, which is supported +by almost 70 vendors on all major operating systems. TS-RPC source code +(RPCSRC 4.0) remains available from several internet sites. + +This release is a native source release, that is, it is compatible for +building on Solaris 2.3. This release was built on Solaris 2.3 using SunPro +SPARCompiler 2.0.1. + +Solaris 2.3 is based on System V, Release 4 (SVR4), and while this release +should be mostly compatible with other SVR4 systems, some Solaris facilities +that are assumed may not be available. In particular, this release uses the +Makefile format supported by SparcCompiler 2.0.1. Second, the Secure RPC +routines use the Solaris Name Service Switch to access public-key credential +databases. This code will need to be ported if your system does not support +the Name Service Switch. Finally, this release uses the synchronization +interfaces of UI Threads to make certain interfaces thread-safe. These +interfaces are found in libthread in Solaris 2.3 and later. + +Applications linked with this release's librpc must link with the United +States domestic version of libcrypt in order to resolve the cbc_crypt() and +ecb_crypt() functions. These routines are used with Secure RPC however all +RPC programs that link with this release's librpc will need to link with the +domestic libcrypt. Note that the Solaris 2.3 Encryption Kit is only available +within the United States. (PLEASE NOTE: The RPC implementation found in +Solaris 2.3's libnsl does *not* have this requirement; linking with libcrypt +is only a requirement for the TIRPCSRC 2.3 version of librpc.) + + +DOCUMENTATION NOTE + +The documentation found in the doc directory are derived from the Solaris 2.3 +Network Interfaces Programming Guide. A small number of compile examples are +given, and these use libnsl to link in the RPC library. This release builds +the RPC library as librpc. To use this release's librpc, use the link command +"-lrpc -lnsl -lcrypt". This links the application with TIRPCSRC 2.3's librpc +for RPC routines, Solaris's libnsl for other networking functions, and +libcrypt for the cbc_crypt() and ecb_crypt functions. + + +WHY IS THIS RELEASE BEING DONE? + +This release is being distributed to make the Sun implementation of the ONC +technologies available for reference and porting to non-Solaris platforms. +The current release is a native source distribution, and provides services +that are already available on Solaris 2.3 (such as the RPC headers, the RPC +library in libnsl, rpcbind, rpcinfo, etc.). It is not our intention to +replace these services. See the DISCLAIMER for further information about the +legal status of this release. + + +WHAT'S NEW IN THIS RELEASE: TIRPCSRC 2.3 + +The previous release was TIRPCSRC 2.0. + +1. This release is based on Solaris 2.3. The previous release was + based on Solaris 2.0. This release contains a siginificant number of + bug fixes and other enhancements over TIRPCSRC 2.0. + +2. The RPC library is thread safe for all client-side interfaces + (clnt_create, clnt_call, etc.). The server-side interfaces + (svc_create, svc_run, etc.) are not thread safe in this release. The + server-side interfaces will be made thread safe in the next release of + TIRPCSRC. Please see the manual pages for details about which + interfaces are thread safe. + +3. As part of the work to make the RPC library thread-safe, rpcgen has + been enhanced to generate thread-safe RPC stubs (the -M option). Note + that this modifies the call-signature for the stub functions; the + procedure calling the RPC stub must now pass to the stub a pointer to + an allocated structure where results will be placed by the stub. See + the rpcgen manual page and the rpcgen Programming Guide for details. + +4. The Remote Asynchronous Calls (RAC) library is now included. RAC was + first introduced in TIRPCSRC 1.0, and was bundled with librpc. It is + now a separate library. The asynchronous call model that RAC provides + can be achieved by using threads for making client-side RPC calls. + The ONC Technology group recommends using threads (where possible) to + achieve asynchrony rather than RAC. See the rpc_rac(3n) manual page + for details. -This distribution contains Sun Microsystem's implementation of the -RPC and XDR protocols and is compatible with 4.2BSD and 4.3BSD. Also -included is complete documentation, utilities, RPC service -specification files, and demonstration services in the format used by -the RPC protocol compiler (rpcgen). See WHAT'S NEW below for -details. -NOTE ABOUT SECURE RPC: +ROADMAP -This release of RPCSRC contains most of the code needed to implement -Secure RPC (see "DES Authentication" in the RPC Protocol Specification, -doc/rpc.rfc.ms). Due to legal considerations, we are unable to -distribute an implementation of DES, the Data Encryption Standard, which -Secure RPC requires. For this reason, all of the files, documentation, and -programs associated with Secure RPC have been placed into a separate -directory, secure_rpc. The RPC library contained in the main body of this -release *DOES NOT* support Secure RPC. See secure_rpc/README for more -details. (A DES library was posted in Volume 18 of comp.sources.unix.) +The directory hierarchy is as follows: -If you wish to report bugs found in this release, send mail to: + cmd/ Utilities + cmd/rpcgen The RPC Language compiler (for .x files) + cmd/rpcbind The RPC bindery and portmapper + cmd/rpcinfo RPC bindery query utility + cmd/keyserv The Secure RPC keyserver + cmd/demo Some simple ONC demo services -Portable ONC/NFS -Sun Microsystems, Inc -MS 12-33 -2550 Garcia Avenue -Mountain View, CA 94043 + doc/ Postscript versions of ONC documentation -or send Email to nfsnet@sun.com (the Internet) or sun!nfsnet (Usenet). + head/ Header files + head/rpcsvc RPCL (.x) specifications for various ONC services, and + header files. -ROADMAP + lib/ Libraries + lib/librpc The RPC and XDR library + lib/librac The Remote Asynchronous Calls (RAC) library -The directory hierarchy is as follows: + man/ Manual pages for the RPC library and utilities. - demo/ Various demonstration services - demo/dir Remote directory lister - demo/msg Remote console message delivery service - demo/sort Remote sort service + uts/common/rpc RPC header files - doc/ Documentation for RPC, XDR and NFS in "-ms" format. - etc/ Utilities (rpcinfo and portmap). portmap must be - started by root before any other RPC network services are - used. SEE BELOW FOR BUGFIX TO 4.3BSD COMPILER. - man/ Manual pages for RPC library, rpcgen, and utilities. +BUILD INSTRUCTIONS - rpc/ The RPC and XDR library. SEE BELOW - FOR BUGFIX TO 4.2BSD COMPILER. +Prior to building the release, you must define the SRC environment variable +to be the path to the top-level Makefile. For example, if /usr/src/tirpcsrc +is where to top-level Makefile is located, execute this command prior to +building the release: - rpcgen/ The RPC Language compiler (for .x files) + setenv SRC /usr/src/tirpcsrc (csh) +or + SRC=/usr/src/tirpcsrc; export SRC (sh) - rpcsvc/ Service definition files for various services and the - server and client code for the Remote Status service. +The sources in the lib directory depend on header files installed from head +and uts/common/rpc, and the programs in the cmd directory depend on libraries +from lib. Therefore, you should do a "make install" to build the release. - secure_rpc/ The files in this directory are used to build a version of - the RPC library with DES Authentication. See the README - file in that directory for more details. +The top-level Makefile builds the release. The "ROOT" macro defines where the +headers and libraries are installed. The default for ROOT is "/proto". You +may change this by either modifiying Makefile.master, or issuing the build +command with a new definition for ROOT: -BUILD INSTRUCTIONS + make install ROOT=/opt/onc + +You will of course need write privileges for the destination directory. +The headers, libraries and executables will be built and installed under the +ROOT. -Makefiles can be found in all directories except for man. The -Makefile in the top directory will cause these others to be invoked -(except for in the doc, man and demo directories), in turn building the -entire release. - -WARNING! THE DEFAULT INSTALLATION PROCEDURES WILL INSTALL FILES -IN /usr/include, /usr/lib, /usr/bin and /etc. - -The master RPC include file, rpc/rpc.h, is used by all programs and -routines that use RPC. It includes other RPC and system include files -needed by the RPC system. PLEASE NOTE: If your system has NFS, it -may have been based on Sun's NFS Source. The include files installed -by this package may duplicate include files you will find on your NFS -system. The RPCSRC 4.0 include files are upwardly compatible to all -NFS Source include files as of the date of this distribution (not -including any new definitions or declarations added by your system -vendor). HOWEVER: Please read the comments towards the end of -rpc/rpc.h regarding rpc/netdb.h. You may need to uncomment the -inclusion of that file if the structures it defines are already -defined by your system's include files. - -After making any compiler fixes that are needed (see below), at -the top directory, type: - - make install - -For all installations, the Makefile macro DESTDIR is prepended to the -installation path. It is defined to be null in the Makefiles, so -installations are relative to root. (You will probably need root -privileges for installing the files under the default path.) To -install the files under some other tree (e.g., /usr/local), use the -command: - - make install DESTDIR=/usr/local - -This will place the include files in /usr/local/usr/include, the RPC -library in /usr/local/usr/lib, rpcgen in /usr/local/usr/bin, and the -utilities in /usr/local/etc. You'll have to edit the Makefiles or -install the files by hand if you want to do anything other than this -kind of relocation of the installation tree. - -The RPC library will be built and installed first. By default it is -installed in /usr/lib as "librpclib.a". The directory -/usr/include/rpc will also be created, and several header files will -be installed there. ALL RPC SERVICES INCLUDE THESE HEADER FILES. - -The programs in etc/ link in routines from librpclib.a. If you change -where it is installed, be sure to edit etc/'s Makefile to reflect this. -These programs are installed in /etc. PORTMAP MUST BE RUNNING ON -YOUR SYSTEM BEFORE YOU START ANY OTHER RPC SERVICE. - -rpcgen is installed in /usr/bin. This program is required to build -the demonstration services in demo and the rstat client and server in -rpcsvc/. - -The rpcsvc/ directory will install its files in the directory -/usr/include/rpcsvc. The Remote Status service (rstat_svc) will be -compiled and installed in /etc. If you wish to make this service -available, you should either start this service when needed or have -it started at boot time by invoking it in your /etc/rc.local script. -(Be sure that portmap is started first!) Sun has modified its -version of inetd to automatically start RPC services. (Use "make -LIB=" when building rstat on a Sun Workstation.) The Remote Status -client (rstat) will be installed in /usr/bin. This program queries -the rstat_svc on a remote host and prints a system status summary -similar to the one printed by "uptime". - -The documentation is not built during the "make install" command. -Typing "make" in the doc directory will cause all of the manuals to -be formatted using nroff into a single file. We have had a report -that certain "troff" equivalents have trouble processing the full -manual. If you have trouble, try building the manuals individually -(see the Makefile). The demonstration services in the demo directory are not built by the -top-level "make install" command. To build these, cd to the demo -directory and enter "make". The three services will be built. +top-level "make install" command. To build these, cd to the cmd/demo +directory and enter "make". The four services will be built. RPCGEN MUST BE INSTALLED in a path that make can find. To run the -services, start the portmap program as root and invoke the service +services, rpcbind must be running, then invoke the service (you probably will want to put it in the background). rpcinfo can be used to check that the service succeeded in getting registered with -portmap, and to ping the service (see rpcinfo's man page). You can +rpcbind, and to ping the service (see rpcinfo's man page). You can then use the corresponding client program to exercise the service. -To build these services on a Sun workstation, you must prevent the -Makefile from trying to link the RPC library (as these routines are -already a part of Sun's libc). Use: "make LIB=". - -BUGFIX FOR 4.3BSD COMPILER - -The use of a 'void *' declaration for one of the arguments in -the reply_proc() procedure in etc/rpcinfo.c will trigger a bug -in the 4.3BSD compiler. The bug is fixed by the following change to -the compiler file mip/manifest.h: - -*** manifest.h.r1.1 Thu Apr 30 13:52:25 1987 ---- manifest.h.r1.2 Mon Nov 23 18:58:17 1987 -*************** -*** 21,27 **** - /* - * Bogus type values - */ -! #define TNULL PTR /* pointer to UNDEF */ - #define TVOID FTN /* function returning UNDEF (for void) */ - - /* ---- 21,27 ---- - /* - * Bogus type values - */ -! #define TNULL INCREF(MOETY) /* pointer to MOETY -- impossible type */ - #define TVOID FTN /* function returning UNDEF (for void) */ - - /* - -If you cannot fix your compiler, change the declaration in reply_proc() -from 'void *' to 'char *'. - -BUGFIX FOR 4.2BSD COMPILER - -Unpatched 4.2BSD compilers complain about valid C. You can make old -compilers happy by changing some voids to ints. However, the fix to -the 4.2 VAX compiler is as follows (to mip/trees.c): - -*** trees.c.r1.1 Mon May 11 13:47:58 1987 ---- trees.c.r1.2 Wed Jul 2 18:28:52 1986 -*************** -*** 1247,1253 **** - if(o==CAST && mt1==0)return(TYPL+TYMATCH); - if( mt12 & MDBI ) return( TYPL+LVAL+TYMATCH ); - else if( (mt1&MENU)||(mt2&MENU) ) return( LVAL+NCVT+TYPL+PTMATCH+PUN ); -! else if( mt12 == 0 ) break; - else if( mt1 & MPTR ) return( LVAL+PTMATCH+PUN ); - else if( mt12 & MPTI ) return( TYPL+LVAL+TYMATCH+PUN ); - break; ---- 1261,1269 ---- - if(o==CAST && mt1==0)return(TYPL+TYMATCH); - if( mt12 & MDBI ) return( TYPL+LVAL+TYMATCH ); - else if( (mt1&MENU)||(mt2&MENU) ) return( LVAL+NCVT+TYPL+PTMATCH+PUN ); -! /* if right is TVOID and looks like a CALL, is not ok */ -! else if (mt2 == 0 && (p->in.right->in.op == CALL || p->in.right->in.op == UNARY CALL)) -! break; - else if( mt1 & MPTR ) return( LVAL+PTMATCH+PUN ); - else if( mt12 & MPTI ) return( TYPL+LVAL+TYMATCH+PUN ); - break; - -WHAT'S NEW IN THIS RELEASE: RPCSRC 4.0 - -The previous release was RPCSRC 3.9. As with all previous releases, -this release is based directly on files from Sun Microsystem's -implementation. - -Upgrade from RPCSRC 3.9 - -1) RPCSRC 4.0 upgrades RPCSRC 3.9. Improvements from SunOS 4.0 have - been integrated into this release. - -Secure RPC (in the secure_rpc/ directory) - -2) DES Authentication routines and programs are provided. -3) A new manual, "Secure NFS" is provided, which describes Secure RPC - and Secure NFS. -4) Skeleton routines and manual pages are provided which describe the - DES encryption procedures required by Secure RPC. HOWEVER, NO DES - ROUTINE IS PROVIDED. - -New Functionality - -5) rpcinfo can now be used to de-register services from the portmapper - which may have terminated abnormally. -6) A new client, rstat, is provided which queries the rstat_svc and - prints a status line similar to the one displayed by "uptime". + + +BUILDING ONC APPLICATIONS + +See the Makefiles in the demonstration services for examples of building +ONC applications with this release. The $(ROOT)/usr/include directory +must be included in the compiler header file search path (-I), and the +$(ROOT)/usr/lib directory must be included in the linker library file search +path (-L). Also, to run executables built dynamically, the shared library +search path (LD_LIBRARY_PATH) must also include $(ROOT)/usr/lib. In addition +to linking in this release's librpc (via -lrpc), you must also link with +Solaris's libnsl (-lnsl) and the US domestic version of libcrypt (-lcrypt). + |
