RPCETC\README.TXT

Overview:

This directory (and the other directories whose names begin with RPC...)
contain an implementation of Sun's RPC for PC/TCP socket libraries under
DOS, built with Microsoft C 5.1.  Some Unix-specific parts have been
eliminated to save space, but otherwise we did as little modification as
possible to the Sun RPC implementation they make available in source form.

We're obviously responsible for bugs relating to the port itself; if you
report them to us, we may be able to fix them in a later release.  Bugs
or problems with their roots in the fact that DOS is not Unix may be hard
to deal with effectively.


Installation:

The Sun build procedure (outlined in their readme file) won't work.
We have changed the directory structure considerably.  Because of
this, the Sun "Roadmap" is also wrong.  Ours is as follows:

	SRC\RPCETC	Sun's /etc, with TAR files of their /man, /doc
			and /demo directories.

	SRC\RPCGEN	The RPCGEN XDR compiler source and makefile.

	SRC\RPCLIB	Sun's /rpc, the RPC library source and .H files.

	SRC\RPCSVC	The RPC service definitions

The file BUILDRPC.BAT, in this directory, will install the .H files in
..\..\INCLUDE, build the small-model RPC library and install it in
..\..\NETMSC5.1, and build the RPCGEN XDR compiler, and install it in
..\..\BIN.  Look over the make files for procedures to build other
memory models.  The make files are intended for use with a Unix-compatible
MAKE utility.  We've tested them with PolyMake v2.0.

This directory also contains three .TAR files, which you can copy up
one directory level and extract with the PC/TCP TAR utility (if you don't
have it, FTP the files to a Unix system in binary mode and use the Unix
'tar' utility): DEMO.TAR contains the Sun demonstration programs, MAN.TAR
contains the Sun manual pages for Unix, and DOC.TAR contains Unix 'nroff'
source for the printed documentation.

The 'rstat' utility Sun distributed in the RPCSVC directory is very
Unix- specific; it won't run on DOS.  The RPC servers ('portmap',
etc.) run as foreground programs, type 'q' to exit.  We recommend
using 'rpcinfo', in the RPCETC directory, to determine if the
installation has completed correctly.


Differences between DOS and Unix RPC:

The most conspicuous difference is that the function svc_run() will now
return, if the user types 'q'.  This was done to avoid a re-boot, and
to let servers clean up better than the default provided by DOS and MSC.
If you don't like it, look at RPCLIB\S_RUN.C, implement something you
do like, and tell us about it.

C and sockets on DOS have visible differences from the Unix
originals.  In summary:

 o The C types 'int' and 'unsigned int' are only 16 bits wide.

 o C function pointers and data pointers may be either 16 or 32 bits,
   depending on the memory models, and they may be different sizes.

 o The "high-level" I/O calls (fputs(), fscanf(), etc.) will not work
   on sockets.

 o Sockets aren't inherited by child processes.

 o The PC's inherent byte-ordering is *not* the same as the networks, so
   functions like ntohs() are required (on a 68000-based machine, you can
   get away without them).

For more information, read the PC/TCP Socket Library documentation on
this issue.

jbvb 19-Dec-89

---------------------------------------------------------------------------
The Sun Microsystems README file follows:
-----------------------------------------------------------------------------

RPCSRC 3.9 11/30/87

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.

If you wish to report bugs found in this release, send mail to:

Portable NFS
Sun Microsystems, Inc
MS 12-33
2550 Garcia Avenue
Mountain View, CA  94043

or send Email to nfsnet@sun.com (the Internet) or sun!nfsnet (Usenet).

ROADMAP

The directory hierarchy is as follows:

    demo/       Various demonstration services
    demo/dir        Remote directory lister
    demo/msg        Remote console message delivery service
    demo/sort       Remote sort service

    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.

    rpc/        The RPC and XDR library (formerly rpclib).  SEE BELOW
                FOR BUGFIX TO 4.2BSD COMPILER.

    rpcgen/     The RPC Language compiler (for .x files)

    rpcsvc/     Service definition files for various services and the
                server procedures for the Remote Status service.

BUILD INSTRUCTIONS

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 directory), in turn building the entire
release.

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.

The rpcsvc directory will install its files in the directory
/usr/include/rpcsvc.  The Remote Status service (rstat) 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 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.
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
(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
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 declartion 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

The previous release was RPCSRC 3.2.  As with all previous releases,
this release is based directly on files from Sun Microsystem's
implementation.

New Documentation

1)  New manual pages are provided for the XDR and RPC library
    routines.
2)  Revised versions are provided of the "RPC Programmer's Manual,"
    the "XDR Protocol Specification," and the "RPC Protocol
    Specification."
3)  Three new manuals are provided: "RPCGEN Programmer's Manual,"
    "XDR Technical Notes," and the "NFS Protocol Specification."

New Demonstration Services

4)  The demo directory contains two services used as examples in the
    "RPCGEN Programmer's Manual": msg and dir.
5)  A "sort service" is also provided in RPCL format (.x). This
    service is identical to the "toy" service in RPCSRC 3.2, however
    it is now built with RPCGEN.

New Functionality

6)  rpcgen has been extensively improved.  It now provides client
    stubs in addition to server stubs.  New conventions are used for
    naming procedures to make it easier to convert a non-RPC service
    into an RPC-based service.  The RPC Language (RPCL) has been
    changed slightly (particularly with the specification of variable
    length arrays).  Constants can be defined, and rpcgen now uses
    the C Pre-Processor.  See the "RPCGEN Programmer's manual" for
    details.
7)  rpcinfo can now send broadcast calls to services.

Service Definitions

8)  Service definition files (in RPCGEN format) are now included
    for certain RPC services.  THESE SERVICE DEFINITIONS ARE FOR
    INFORMATION ONLY.  No guarantee is made of their accuracy or
    suitability for any particular purpose.
9)  The Remote Status (rstat) service is supplied.  This service is
    used by perfmeter on Sun workstations to display the server's
    load average, cpu utilization and other information.  This service
    is compatible with 4.2BSD and 4.3BSD only.  No client is supplied.
    (see rpcsvc/rstat.x)
