xref: /freebsd/lib/libc/rpc/README (revision 8ddb146abcdf061be9f2c0db7e391697dafad85c)
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 significant 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