XEROX 	Lisp Library Packages
2

4
1

1

TCP/IP
1
4
4

4


This document describes the Interlisp-D implementation of the Transport Control Protocol/Internet Protocol (TCP/IP) suite of networking protocols.  These protocols were developed under the auspices of the Department of Defense for the purpose of standardizing communication mechanisms within such Department of Defense networks as the ARPANET.  The entire protocol family is documented in a collection of working papers known as Requests for Comments (RFCs).  Users with access to the ARPANET may retrieve any RFC from host SRI-NIC.ARPA with the file transfer protocol (FTP) anonymous log-in option.  RFCs are stored under <RFC>RFCnnn.TXT, where nnn is replaced by the number of the particular RFC.  
We will refer to appropriate RFC numbers throughout this document as we introduce new protocols.   Installation instructions are to be found at the end of this document.
TCP/IP PROTOCOL LAYERS
The TCP/IP family consists of four principal protocol layers:  the link layer, the internet layer, the transport layer, and the application layer.
The Link Layer
The physical link layer, the medium for transferring packets between hosts, is assumed to be any medium capable of transporting packetized data between hosts.  Common link layers in this family include the Ethernet and the ARPANET.
The Address Resolution (AR) Protocol is supplied to enable hosts to map between internet addresses and link layer medium addresses.  For example, the internet layer IP protocol (see below) uses a 32-bit combined unique host and network address; the host address field is of variable size and depends on the pattern encoded in the high-order bits of the address.  On the other hand, the (10 MB) Ethernet uses a fixed-size 48-bit unique host address.  The Address Resolution Protocol, documented in RFC826, allows hosts to dynamically discover the link layer address equivalents of other internet hosts.
The Internet Layer
The internet layer is responsible for routing packets between hosts.  Unlike the link layer, the internet layer is capable of moving packets between hosts that are not connected to the same network.  The term IP in TCP/IP refers to the Internet Protocol, the protocol that performs this task in the TCP/IP family.  IP is documented in RFC791.   IP is not assumed to be error-free; packets may be lost or duplicated while moving through the internet.  It is the responsibility of the transport layer (see below) to guarantee perfect delivery should the client require it.
IP also depends on an associated protocol called the Internet Control Message Protocol (ICMP). ICMP is responsible for handling exceptional conditions that arise between hosts using IP.  Such conditions include the inability to deliver packets, errors in packet formats, etc.  ICMP is documented in RFC792.
The Transport  Layer
The transport layer is responsible for assuring error-free, duplicate-free, sequenced delivery of packets between communicating processes.  The most common transport layer is TCP, the ``Transport Control Protocol.''  TCP maintains the appearance of a perfect byte stream between processes.  TCP is documented in RFC793. 
An unreliable transport layer called the User Datagram Protocol (UDP) is also documented.  UDP allows for packet exchange between communicating processes, but makes no attempt to guarantee delivery, suppress duplication, etc.  Clients of UDP must provide their own error-recovery mechanisms if necessary.  UDP is documented in RFC768.
The Application Layer
A large number of applications currently exists in the TCP/IP family.  The most common applications are file transfer, virtual terminal interaction, and mail delivery.
File Transfer
Two principal file transfer applications are in use:  FTP, based on TCP and documented in RFC765, and TFTP (the ``Trivial File Transfer Protocol''), based on UDP and documented in RFC783.  Both are implemented in Interlisp-D, and we shall discuss each at greater length later in this document.
Virtual  Terminal Interaction
The TELNET protocol, documented in RFC854, specifies the protocol for virtual terminal interaction between a user and a remote system.  The Interlisp-D Chat system will use the TELNET protocol to connect to TCP-only hosts.
Mail Delivery
The Simple Mail Transfer Protocol (SMTP) enables the delivery of mail between system elements using TCP.  It is not currently implemented in Interlisp-D.  SMTP is documented in RFC821.
INTERLISP-D FILES
The files that implement the TCP/IP protocol suite are divided into two classes: those that implement low-level functionality, normally not of interest to general users, and those that implement higher-level functionality for user programs (either application or transport layer protocols).  All files reside in the Lisp Library directory.
The higher-level functions reside in the files TCP, TCPDEBUG, TCPFTP, TCPCHAT, TCPPUDP, and TCPFTP.  The contents of each file are described briefly below.
TCP	The TCP layer.  Implements TCP streams, based on the buffered TCP device (e.g., BIN runs in microcode).
TCPDEBUG	Contains routines to help debug TCP and TCP-based applications.
TCPFTP	Contains the TCP-based file transfer protocol.  Creates a new virtual I/O device, allowing transparent filing operations with TCP-only hosts.
TCPCHAT	Implements the TELNET protocol for the Chat system.
TCPUDP	Contains the UDP layer.
TCPTFTP	Implements the TFTP protocol.  Creates a buffered TFTP device to allow efficient bulk transfer between hosts.
The low-level functions reside in the files TCPLLIP, TCPLLICMP, TCPLLAR, and TCPHTE.  The contents of each file are described briefly below. 
TCPLLIP	Implements the IP layer. 
TCPLLICMP	Implements ICMP for IP.
TCPLLAR	Implements AR for the 3- and 10-MB Ethernets.
TCPHTE	Implements the functionality necessary to parse RFC810-style HOSTS.TXT files.  This allows name to address translation within the Interlisp-D host, as there is currently no satisfactory network-accessible service to perform this task.
TCPLLICMP, TCPLLAR, and TCPHTE are loaded automatically by TCPLLIP when necessary.  TCPLLIP is itself loaded by TCP or TCPUDP when necessary.  An additional file, TCPCONFIG, contains code that configures the TCP/IP package whenever it is first loaded onto an individual workstation.  We now document each of the files in the TCP/IP package.
TCP
TCP implements the transport control protocol for Interlisp-D.  After TCP is loaded, Interlisp-D supports a TCP stream capable of bidirectional I/O to a remote system element.  The following functions are intended for use by applications programs.
(TCP.OPEN DST.HOST DST.PORT SRC.PORT MODE ACCESS NOERRORFLG)	[Function]
opens a TCP stream to DST.PORT on DST.HOST from SRC.PORT.  DST.HOST can be a host name, an IP host address in text format (such as 192.10.200.1), or the 32-bit integer representation of an IP host address as returned by the function DODIP.HOSTP (which is documented below under TCPLLIP).
DST.PORT is a 16-bit number representing a TCP port open in LISTENING mode on the remote system.  SRC.PORT is also a 16-bit number, but may be supplied as NIL to obtain a defaulted unique local port number.
MODE is either ACTIVE, meaning to act as initiator of the connection, or PASSIVE, meaning to wait for a remote system element to initiate the connection.
ACCESS is either INPUT, OUTPUT, or APPEND (OUTPUT and APPEND are treated in the same manner). 
If NOERRORFLG is non-NIL, TCP.OPEN will return NIL if the connection fails; otherwise, TCP.OPEN will call ERROR to signal failure.
If TCP.OPEN succeeds, it returns a STREAM open as specified by ACCESS.  The generic operations BIN, BOUT, PEEKBIN, BINS, BOUTS, READP, EOFP,  OPENP, GETFILEPTR, FORCEOUTPUT, and CLOSEF may be performed on streams opened for suitable access.
(TCP.OTHER.STREAM STREAM)	[Function]
returns the STREAM open in the other direction with respect to STREAM (e.g., if STREAM is open for INPUT, TCP.OTHER.STREAM returns a STREAM open for OUTPUT, and vice versa).
(TCP.URGENT.EVENT STREAM)	[Function]
returns an event upon which a user process may wait for URGENT data to arrive on STREAM. 
(TCP.URGENTP STREAM)	[Function]
returns T if STREAM is currently reading URGENT data.
(TCP.URGENT.MARK STREAM)	[Function]
marks the current point in STREAM as the end of URGENT data.  STREAM must be open for OUTPUT.
(TCP.CLOSE.SENDER STREAM)	[Function]
closes the output side of STREAM.  STREAM may be either the INPUT or OUTPUT stream for the connection.  This function differs from CLOSEF in that the INPUT side of the connection is not closed (although the remote system element may close the connection once the local output side of the connection is closed).
(TCP.STOP)	[Function]
disables the TCP protocol, closing all open TCP streams.
(\TCP.INIT)	[Function]
(re)initializes the TCP package.
\TCP.DEFAULT.RECEIVE.WINDOW	[Variable]
is the default number of bytes allowed outstanding from the remote system.  It is initially 2,000.
\TCP.DEFAULT.USER.TIMEOUT	[Variable]
is the default number of milliseconds a remote system element is allowed to remain silent before the TCP connection is declared broken.  It is initially 60,000.
TCPDEBUG
TCPDEBUG implements tracing and test functions used to debug TCP and TCP-based applications.  The following functions may be of interest to applications programmers.
(TCPTRACE)	[Function]
opens a trace window and attaches a menu to the window's top.  The menu entries represent state changes or data elements to be traced; each entry is a toggle.  Buttoning the toggle once will activate the trace of the particular element and will gray-over the entry; buttoning a second time will deactivate the tracing and ungray the menu item.  The following data elements/transitions may be displayed:  Contents, Incoming, Outgoing, Checksums, Time, and Transitions.
Contents 	Displays a line's worth of packet contents.  The Incoming or Outgoing switch must be on.
Incoming	Displays incoming data.
Outgoing	Displays outgoing data.
Checksums	Displays checksums for each TCP segment.
Time	Displays the time interval since the last action on the connection.
Transitions	Displays state transitions on the TCP state machine.
(PPTCB TCB FILE)		[Function]
prints the state of a TCP connection.  PPTCB is normally the INFO function for the process that monitors a connection; thus, buttoning INFO in the process status window will cause a window to pop up containing a report on the status of the associated connection.
(TCP.ECHOTEST HOST NLINES)	[Function]
opens a TCP connection to the TCP echo port on HOST and sends NLINES of random text.  The echo responses are displayed in a window.  If NLINES is NIL, the echo test will run forever.
(TCP.ECHO.SERVER PORT)	[Function]
starts a TCP echo server on PORT (defaults to the TCP echo port).  It is usually more useful to start the echo server as a process by doing (ADD.PROCESS '(TCP.ECHO.SERVER PORT)).
(TCP.SINK.SERVER PORT)	[Function]
starts a TCP sink server on PORT (defaults to the TCP sink port).  Any data sent to this port will be acknowledged and discarded.  As with the TCP echo server, it is usually more useful to start this server as an independent process.
(TCP.FAUCET HOST PORT NLINES)	[Function]
If HOST is non-NIL, this function opens a connection to PORT on HOST and sends NLINES of text (the default is to send lines of text forever).  PORT defaults to the TCP sink port.  If HOST is NIL, this function waits for a remote system to connect to the TCP faucet port and then sends out NLINES of random text.
TCPFTP
TCPFTP implements a virtual I/O device that performs Interlisp-D filing operations transparently using the RFC765 FTP protocol.  The standard filing operations of reading, writing, renaming, deleting, and directory enumeration are supported by the TCPFTP device.  However, neither random access filing nor GETFILEINFO are supported, as there is no protocol specification for performing these operations on files.   Interlisp-D operations such as RECOMPILE will not work when files are stored on TCPFTP file servers.
Once TCPFTP is loaded, filing operations should be transparent to users; no additional initialization need be performed.  There is, however, one important global variable:
TCP.DEFAULTFILETYPE	[Variable]
The TCPFTP protocol provides no mechanism for determining the type of a file about to be retrieved.  The Interlisp-D TCPFTP package uses the value of TCP.DEFAULTFILETYPE to decide between binary and text file transfer in the absence of additional information.  The file type is usually known in the case of output operations (e.g., COPYFILE or MAKEFILE to a file server).  However, in the case of COPYFILE from a file server, the value of this variable must be used.  The initial value of TCP.DEFAULTFILETYPE is BINARY; however, users may preset its value in their INIT.LISP files prior to loading TCP/IP.
The following functions are available for debugging broken file server connections.
(FTPDEBUG FLG)	[Function]
If FLG is T, this function opens a scrolling trace window that displays FTP commands as they are issued.  PUPFTP commands will also be displayed in this window (the window is the value of FTPDEBUGLOG).
(\TCP.BYE HOST)	[Function]
breaks an FTP connection to HOST.
(\TCPFTP.INIT)	[Function]
(re)initializes the TCPFTP package.  
TCPCHAT
TCPCHAT implements the TELNET protocol for virtual terminal I/O between Interlisp-D and a remote system.  Once loaded into Interlisp, the standard Chat system will use TCP TELNET to communicate with hosts that are believed to support the protocol.  No user-callable functions reside in this package, although the following variables may be of interest.
TCPCHAT.TELNET.TTY.TYPES	[Variable]
is an association list that maps internal names of Chat terminal emulators to official terminal names as specified in RFC884, the TELNET Terminal Type Option.  This allows TCPCHAT to set the user's terminal type automatically when a connection is established.
TCPCHAT.TRACEFLG	[Variable]
If this variable is non-NIL, TELNET negotiations will be printed to TCPCHAT.TRACEFILE (see below).  This is sometimes useful in debugging negotiation problems.
TCPCHAT.TRACEFILE	[Variable]
TELNET negotiations are printed to this file if TCPCHAT.TRACEFLG is non-NIL.
TCPUDP
UDP implements the User Datagram Protocol.  The following functions are meant to be called by client applications.
(UDP.INIT)	[Function]
initializes the UDP package.  This function is normally called when UDP is loaded and should not need to be called again under normal circumstances.
(UDP.STOP)	[Function]
disables the UDP package, closing any open UDP sockets.
(UDP.OPEN.SOCKET SKT# IFCLASH)	[Function]
opens a socket for UDP operations.  SKT#, if supplied, is a 16-bit number and will default to a number between 1,000 and 65,535.  IFCLASH specifies what to do if the requested socket is already open and is handled as in OPENPUPSOCKET and OPENNSOCKET (see the Interlisp Reference Manual).  It returns an instance of an IPSOCKET.
(UDP.CLOSE.SOCKET IPSOCKET NOERRORFLG)	[Function]
closes an open IPSOCKET.  If IPSOCKET  is not an open socket and NOERRORFLG is NIL, an error will occur; otherwise, NIL is returned if the socket is not active, and T is returned if the socket is active.  Any remaining packets on the socket's input queue are discarded when this function is called.
(UDP.SOCKET.EVENT IPSOCKET)	[Function]
returns an event that a process may use to wait for packet arrival on IPSOCKET.
(UDP.SOCKET.NUMBER IPSOCKET)	[Function]
returns the socket number of IPSOCKET.
(UDP.GET IPSOCKET WAIT)	[Function]
returns the next packet waiting on IPSOCKET.  If no packets are waiting, does one of the following based on the value of WAIT.
NIL	Returns immediately.
T	Waits forever for a packet to arrive.
A FIXP	Waits up to WAIT milliseconds for a packet to arrive and returns NIL if none arrived during that time.
Thus, this function is like GETPUP and GETXIP.
(UDP.SETUP UDP DESTHOST DESTSOCKET ID IPSOCKET REQUEUE)	[Function]
initializes a fresh packet (as returned from \ALLOCATE.ETHERPACKET).  The packet will be sent to DESTSOCKET on DESTHOST.  ID is a number to be placed in the IP header ID field (zero is fine).  REQUEUE specifies what to do with the packet after it is sent; NIL (the default) means no special treatment; FREE means to release the packet and return it to the free packet queue; any instance of a SYSQUEUE will cause the packet to be queued on the tail of the specified queue.
UDP.SETUP initializes all IP and UDP fields and sets the packet up as being a minimum-length UDP packet.
(UDP.SEND IPSOCKET UDP)	[Function]
sends UDP, a UDP-formatted packet, out from IPSOCKET.
(UDP.EXCHANGE IPSOCKET OUTUDP TIMEOUT)	[Function]
sends OUTUDP out from IPSOCKET and waits TIMEOUT milliseconds for a response; returns NIL if no response came in during the specified interval, or the packet that did come in during that time.
Clears the socket's input packet queue before waiting for a packet to arrive.
(UDP.APPEND.BYTE UDP BYTE)	[Function]
appends BYTE to the UDP data portion of UDP and increments the UDP and IP length fields by one.
(UDP.APPEND.WORD UDP WORD)	[Function]
appends WORD to the UDP data portion of UDP and increments the UDP and IP length fields by two.
(UDP.APPEND.CELL UDP CELL)	[Function]
appends CELL to the UDP data portion of UDP and increments the UDP and IP length fields by four.
(UDP.APPEND.STRING UDP STRING)	[Function]
appends STRING to the UDP data portion of UDP and increments the UDP and IP length fields by the length STRING.
TCPTFTP
TFTP implements the Trivial File Transfer Protocol.  This protocol is useful for transferring unimportant files rapidly (for example, between workstations and printers).  The following user-callable functions exist.
(TFTP.PUT FROM TO PARAMETERS)	[Function]
sends a file to a TFTP host.  FROM may refer to any accessible file; TO must refer to a file accessible via TFTP.  No attempt is currently made to translate between Interlisp file name syntax and remote system file name syntax for TO; for example, if TO resides on a Unix host, it would take a syntax like {HOST}/DIRECTORY/SUBDIRECTORY/FILENAME.
PARAMETERS is currently a list of parameters in the same format used by OPENFILE in MACHINE.DEPENDENT.PARAMETERS; for example ((EOLCONVENTION 1)  (TYPE TEXT)).
(TFTP.GET FROM TO PARAMETERS)	[Function]
gets a file from a TFTP host.  FROM must be a file accessible by TFTP; TO may be any file.  The file name syntax caveats for FROM are the same as for TO in TFTP.PUT.  PARAMETERS is also as in TFTP.PUT.
(TFTP.SERVER LOGSTREAM)	[Function]
starts a TFTP server process.  LOGSTREAM may be left NIL, causing a new window to appear when the TFTP server is first invoked.  Remote systems that support TFTP clients may store or retrieve files through any Interlisp-D workstation running the TFTP server.  The full Interlisp-D syntax for file names is supported; thus, requests to store files whose names include hosts will result in the Interlisp workstation's transparently storing the files on the designated hosts.
For users with applications requiring explicit control over the transfer of data using TFTP, the following functions exist.
(\TFTP.OPENFILE FILENAME ACCESS RECOG PARAMETERS)	[Function]
returns a STREAM to open for ACCESS on FILENAME.  PARAMETERS is the usual format; TYPE is the only recognized parameter (BINARY opens a stream in octet format; TEXT (the default) opens a stream in NETASCII format�see RFC783).
BIN, BOUT, READP, EOFP, etc., may be used on this stream.  Note that the stream is not RANDACCESSP.
(\TFTP.CLOSEFILE STREAM)	[Function]
closes the open stream.  This is normally useful for streams open for OUTPUT; for INPUT streams, end-of-file will occur eventually.
TCPLLIP
For users planning implementations on top of IP, the following low-level functions are available.  We document here only three categories of functions: IP socket access, IP packet building, and IP packet sending.  Other functions should not be of interest to IP clients.
(\IPINIT)	[Function]
reinitializes the IP world; e.g., after some catastrophe.
(STOPIP)	[Function]
disables IP.
(DODIP.HOSTP NAME)	[Function]
If NAME is an integer, NAME is returned unaltered.  If NAME is a text format IP host address (such as 192.10.200.1), DODIP.HOSTP returns its integer representation.  If NAME is a string or atom name, DODIP.HOSTP attempts to convert NAME to its IP host address integer value, using information supplied in the HOSTS.TXT file (see TCPHTE, below).  If NAME is unknown, DODIP.HOSTP returns NIL; if NAME is known, it is cached with its corresponding address so that the function IPHOSTNAME may be used later to convert the address back to a name.
(IPHOSTNAME IPADDRESS)	[Function]
tries to convert IPADDRESS to a host name.  If IPADDRESS has no known name, it is converted to the text representation of an IP address (e.g., 192.10.200.1).
(IPTRACE MODE)	[Function]
turns on tracing of IP activity.  This function is like PUPTRACE and XIPTRACE, which are documented in the Interlisp Reference Manual.  MODE may be one of T, NIL, or PEEK.  If MODE is NIL, IP tracing is disabled.  If MODE is T, verbose IP tracing is enabled.  If MODE is PEEK, concise IP tracing is enabled.  If MODE is either T or PEEK, the user is prompted for a window into which trace output will be printed.
(\IP.ADD.PROTOCOL PROTOCOL SOCKETCOMPAREFN NOSOCKETFN INPUTFN ICMPFN)	[Function]
defines a new IP-based protocol.  The lowest-level IP functions maintain a list of active protocols and perform packet delivery based on the existence of open sockets for protocols of received packet types.
PROTOCOL is a protocol number, a number between 1 and 255.  The following protocols are defined and should not be disturbed.
TCP	6
ICMP	1
UDP	17
SOCKETCOMPAREFN is a function with two arguments, an IP packet that has just been received and an open IPSOCKET.  This function should return NIL if the packet does not belong to the supplied socket, or T if it does.  The function will typically be interested in the IPSOCKET field of the IPSOCKET.
NOSOCKETFN is a function with one argument, an IP packet that has just been received.  Its purpose is to handle received packets for which no socket can be found.  If NOSOCKETFN is NIL, the default function, \IP.DEFAULT.NOSOCKETFN, will be used; this function simply returns an ICMP message indicating the socket is unreachable.
INPUTFN is a function with two arguments, a received IP packet and an open IPSOCKET.  The INPUTFN is supposed to handle reception of packets when their destination socket has been found.  If INPUTFN is NIL, the default function, \IP.DEFAULT.INPUTFN, will be supplied. This function does the following:
�  Enqueues the received packet on the IPSQUEUE field of the IPSOCKET if the current queue length (stored in the IPSQUEUELENGTH field) is less than the allocated length (stored in the IPSQUEUEALLOC field).
�  Increments the IPSQUEUELENGTH field.
�  Notifies the event stored in the IPSEVENT field.
ICMPFN is a function with two arguments and is called when an ICMP packet referring to the protocol is received.  The first argument is a pointer to the received ICMP packet.  The second argument is a pointer that may be used as if pointed to the original outgoing packet included in the ICMP data.  This allows the protocol functions to parse the data in the ICMP packet to determine which socket sent the offending packet.  The ICMPFN must never attempt to deallocate the packet identified by the second argument; however, it is quite permissible (and expected) that the ICMPFN will release the packet identified by the first argument.  The default ICMPFN simply releases the packet identified by the first argument.
\IP.ADD.PROTOCOL returns an IPSOCKET datum, which represents the active protocol; it is not in fact a useful IPSOCKET and may be safely ignored.
(\IP.DELETE.PROTOCOL PROTOCOL)	[Function]
deactivates a protocol with protocol number PROTOCOL.  Any open sockets are closed.
(\IP.OPEN.SOCKET PROTOCOL SOCKET NOERRORFLG SOCKETCOMPAREFN NOSOCKETFN INPUTFN)	[Function]
attempts to open an IPSOCKET for protocol PROTOCOL.  SOCKET is the identifying information for this socket; this quantity will be EQUAL-compared with other sockets open on PROTOCOL.  Should a match be found, an error will occur unless NOERRORFLG is T, in which case the existing socket will be returned.
SOCKETCOMPAREFN, NOSOCKETFN, and INPUTFN may be supplied to override the functions specified when the protocol was defined; they are not normally useful, however.
(\IP.CLOSE.SOCKET SOCKET PROTOCOL NOERRORFLG)	[Function]
closes a socket open on PROTOCOL.  SOCKET is the same quantity passed to \IP.OPEN.SOCKET; it is currently not an instance of an IPSOCKET.  If NOERRORFLG is T, an error will not occur if the socket is not found.
The following functions are useful for placing bytes into IP packets (as allocated by \ALLOCATE.ETHERPACKET).  Note that most applications will probably want to define a block record to overlay the data portion of an IP packet.  Here is an example of such a block record (users who are developing new IP-based protocols will need to load EXPORTS.ALL from the Lisp Library package directory).

(ACCESSFNS UDP ((UDPBASE (\IPDATABASE DATUM)))
	(BLOCKRECORD UDPBASE  ((UDPSOURCEPORT WORD)
 				      (UDPDESTPORT WORD) 
				      (UDPLENGTH WORD)
				      (UDPCHECKSUM WORD))) 
	(ACCESSFNS UDP ((UDPCONTENTS (\ADDBASE (\IPDATABASE DATUM) 
					                        (FOLDHI \UDPOVLEN
						                                     BYTESPERWORD))))))
(\IP.APPEND.BYTE IP BYTE INHEADER)	[Function]
appends BYTE to the IP data portion of IP and increments the IP length field by one.  If INHEADER is T, the IPHEADERLENGTH field is appropriately incremented so that the bytes appear to have been appended to the options portion of the IP header.  There must not be any data bytes in the data portion of the packet if this function is to work correctly.
(\IP.APPEND.WORD IP WORD INHEADER)	[Function]
appends WORD to the IP data portion of IP and increments the IP length field by two.  INHEADER is as in \IP.APPEND.BYTE.
(\IP.APPEND.CELL IP CELL INHEADER)	[Function]
appends CELL to the IP data portion of IP and increments the IP length field by four.  INHEADER is as in \IP.APPEND.BYTE.
(\IP.APPEND.STRING IP STRING)	[Function]
appends STRING to the IP data portion of IP and increments the IP length field by the length STRING.
Finally, we document the functions used to transmit IP packets.
(\IP.SETUPIP IP DESTHOST ID SOCKET REQUEUE)	[Function]
initializes IP.  This function should be called just after IP is obtained from \ALLOCATE.ETHERPACKET; if this is not done, the append functions above will fail.
DESTHOST is the 32-bit IP address to which this packet will be sent.  ID is an arbitrary 16-bit quantity that will become the IPID field of the packet.  SOCKET is the open IPSOCKET from which the packet will be sent.  REQUEUE defaults to FREE and controls the disposition of the packet after transmission (see the Interlisp Reference Manual for the documentation of SETUPPUP or FILLINXIP).
(\IP.TRANSMIT IP)	[Function]
tries to send IP.  Performs IP checksum algorithm prior to sending.  Returns NIL if successful, else returns a status indication, such as NoRouting or AlreadyQueued.  This function is like SENDPUP and SENDXIP, except that no socket argument is required.
TCPHTE
HTE provides functions for parsing HOSTS.TXT files as documented by RFC810.  This file is loaded automatically by LLIP and is used by \IPINIT to read in the initial file, HOSTS.TXT.  The following variable and function may be of interest:
HOSTS.TEXT.DIRECTORIES	[Variable]
is the search path for the file HOSTS.TXT.  This variable is initialized to NIL; thus  the search path to be used is by default DIRECTORIES.   
(\HTE.READ.FILE FILE WANTEDTYPES)	[Function]
reads a HOSTS.TXT file.  WANTEDTYPES is a list of types drawn from the set {HOST, NET, GATEWAY}, to be read from the file; types not specified in WANTEDTYPES are ignored.  WANTEDTYPES defaults to (HOST).  
INSTALLING TCP/IP
To install TCP/IP, place the files from the TCP/IP distribution in the Lisp Library directory.  Create a HOSTS.TXT file containing entries for the TCP/IP hosts needed by the user community and place a copy of the file on the local disk of each workstation that will be running TCP/IP.  The following is a sample HOSTS.TXT file:

; DoD Internet Host Table
;  6-Apr-84
;
; Changes, corrections, comments or questions to
; (HOSTMASTER@SRI-NIC)
;
; The format of this file is documented in RFC 810, "DoD Internet
; Host Table Specification", which is available on-line at SRI-NIC
; as the file
;              [SRI-NIC]<RFC>RFC810.TXT
; It may be retrieved via FTP using username ANONYMOUS with
; any password.
;
; NOTE CAREFULLY: RFC 810 has been slightly revised since the 
; original
; version was written.  In particular, the version printed in the
; "Internet Protocol Transition Notebook" does not document the
; added "machine type" field (between the host-name and system-name
; fields).
;
; The format for entries is:
;
; NET : NET-ADDR : NETNAME :
; GATEWAY : ADDR, ADDR : NAME : CPUTYPE : OPSYS : PROTOCOLS :
; HOST : ADDR, ALTERNATE-ADDR (if any): HOSTNAME,NICKNAME : CPUTYPE :
;   OPSYS : PROTOCOLS :
;
; Where:
;;  ADDR = internet address in decimal, e.g., 26.0.0.73
;;  CPUTYPE = machine type (PDP-11/70, VAX-11/780, FOONLY-F3, C/30,
;;                          etc.)
;;  OPSYS = operating system (UNIX, TOPS20, TENEX, ITS, etc.)
;;  PROTOCOLS = transport/service (TCP/TELNET,TCP/FTP, etc.)
;;  : (colon) = field delimiter
;;  :: (2 colons) = null field

HOST: 36.9.0.9 : VAX-A! : VAX-11/750 : UNIX : TCP/TELNET,TCP/FTP :
HOST: 36.9.0.30 : 1108-A : XEROX-1108 : INTERLISP : :

This file defines two hosts, a VAX-11/750 host called VAX-A! and an 1108 host called 1108-A.  Note that if any host is accessible via another network protocol (e.g., PUP or NS), you may desire to call the host an unambiguous name when it is accessed via TCP.  You can do this by giving it such an unambiguous name in the HOSTS.TXT file (in this case, we've appended an exclamation point).  Should you need to reinstall this file while the workstation is running (for example, after creating a newer version), call the function \HTE.READ.FILE (documented in the section covering TCPHTE) with the new file name as its only argument.
Next, load the file TCPCONFIG.DCOM and call the function TCP.CONFIGURE with no arguments.  You will be shown the current configuration parameters and be asked if they are acceptable.  Type ``N.''  You will then be prompted for each of the configuration parameters.  The following is a sample typescript from a TCP configuration session.  Underlined text was typed by the user.

88_TCP.CONFIGURE]
Here is the current configuration:
HOSTNAME            NIL
HTE.FILE            NIL
DEFAULT.GATEWAY     NIL
LOCAL.NETWORKS      NIL
LOCAL.ADDRESSES     NIL
Are you satisfied with the current configuration? no
In the following dialogue, you will be presented with the current value for a
configuration parameter, and then be given a chance to enter a new value. 
Simply type <CR> to default to the current value.

HOSTNAME            NIL
Please enter this host's name: BEETHOVEN

HTE.FILE            NIL
Please enter the name of a HOSTS.TXT file.  If you have no HOSTS.TXT file,
type a carriage return.
...{DSK}<LISPFILES>HOSTS.TXT

DEFAULT.GATEWAY     NIL
Please enter the IP address of the default gateway for this host.  If you have
no gateway, just type a carriage return: 
...192.10.200.254

LOCAL.NETWORKS      NIL
Please enter the network number for this host's 10MB network, in the form
36.0.0.0: 
...192.10.200.0

LOCAL.ADDRESSES     NIL
Please enter this host's IP address on the 10MB network, in the form
36.9.0.9: 
...192.10.200.5

Here is the current configuration:
HOSTNAME            BEETHOVEN
HTE.FILE            {DSK}<LISPFILES>HOSTS.TXT
DEFAULT.GATEWAY     192.10.200.254
LOCAL.NETWORKS      ("192.10.200.0" . 10)
LOCAL.ADDRESSES     "192.10.200.5"

Are you satisfied with the current configuration? Yes
{DSK}<LISPFILES>IP.INIT;1
89_
When you tell TCP.CONFIGURE that you are satisfied with the current configuration, a file called IP.INIT is written to the local disk.  This file must remain on the workstation and must not be copied to other workstations.  You must perform the TCP.CONFIGURE step individually on each workstation, but you need to perform it only once.  As long as there is an IP.INIT file on the workstation, the TCP/IP packet will be configured automatically whenever it is loaded or initialized.
Once the software is installed on the appropriate directory, simply performing a LOAD operation on any of the application files (e.g., TCPFTP, TCPCHAT, TFTP, etc.) should load the remaining necessary files and initialize the software.
(LIST ((PAGE NIL (STARTINGPAGE# 133.1) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE BOO) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY HELVETICA OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE BOO) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 SIZE 10 FAMILY HELVETICA OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (282 42 72 36) NIL) (HEADING NIL (HEADINGTYPE BOO) (84 744 444 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL)))))
*
T0`
�`
�

T8$$
�$Hl��8
�$Hl��8
�$Hl��&
/`
�`
�
,
�

�
&��
8,��
8
4
&��
8,��
8

�
:
�

�
PAGEHEADINGBOOGACHA
�GACHA
MODERN
�MODERN
MODERN

MODERNMODERN
MODERN	HELVETICA
	HELVETICA
	HELVETICALOGO





HRULE.GETFN
MODERN

HRULE.GETFN
MODERN
HRULE.GETFN

HRULE.GETFN
MODERN

	
HRULE.GETFN
MODERN
HRULE.GETFN
HRULE.GETFN

HRULE.GETFN
MODERN

w4�	
��Z

&
3
A
O

�
&
�

�

T�
lI�<v�""6�
U�
1
�Ze�X
v?�
?
X
Q


#

�~9!'c%�	�
�c!!3IA

/D)
�
�
1:$f
�^T

�

&

a$
�M
s�8
"Zy+
�
F
	

#N
(
W/+
a
E
i


#



�N
5
5
6

;
�

#�6	



�

$4

	
	
�| 

V.d
�

:


n;q)�	
		f	
k
$%*-a#

�u

�
�S^h�(4
��H>�
, =
*q7
;
	z



A!
;
�
/- =/>

0


-
.	
2@

-d>Q;X2
�
�"�
(4

H

1BC(<?B@D>F	8D">= 
C6
�

�
y


#2

NK2
	


K


O*


J


E


#.#*#
2

�$
%��l3z�