lib/libc/rpc/README

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