1

LISP LIBRARY PACKAGES MANUAL
1

LISP LIBRARY PACKAGES MANUAL
TCP/IP
1

COMMUNICATIONS/NETWORK
1


TCP/IP
6

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.
2

TCP/IP Protocol Layers
1

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
1

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
1

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
1

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
1

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
1

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
1

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
1

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.
2

Interlisp-D Files
1

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, TCPNAMES, 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.
TCPNAMES 	
Implements translation of file name formats between operating system types
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, TCPHTE, and TCPCONFIG.  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-megabyte 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.
TCPCONFIG
Provides a function to carry on a configuration dialog when TCP/IP is first installed on a machine.  This file needs to be loaded only once, to produce the file {DSK}IP.INIT.  Thereafter, TCPCONFIG is needed only to reestablish or modify IP parameters.
TCPLLICMP, TCPLLAR, and TCPHTE are loaded automatically by TCPLLIP when necessary.  TCPLLIP is itself loaded by TCP or TCPUDP when necessary.  
2

A Primer on IP Networks
1

Before describing the individual services provided by the Interlisp-D TCP/IP package, we first discuss the structure of the Internet Protocol internetwork.  The internetwork is a collection of IP networks, a subset of which may communicate with each other.  Each network is assigned an IP address, which is composed of a network number and a host number.  No two hosts in the internetwork have the same network and host number combination; the composition of the network and host number for a particular host unambiguously identifies that host within the internetwork.
The ��address space'' of the internetwork is formed of the concatenated network and host numbers of its constituent hosts, and is 32 bits long.  This 32-bit address space is currently partitioned into three classes of network addresses, known as class-A, class-B, and class-C.  Class-A addresses consist of 7 bits of network number and 24 bits of host number.  Class-B addresses consist of 14 bits of network number and 16 bits of host number.  Finally, class-C addresses consist of 21 bits of network number and 8 bits of host number.  Thus, there may be 128 class-A networks, 16,384 class-B networks, and over two million class-C networks.  In addition, a single class-A network has the capacity to address over 16 million hosts, while a class-C network can address only 255 hosts.  The class to which a particular IP network belongs may be determined by examining the most significant bits of its address.  
Network number assignments are strictly controlled by a central authority (currently, the Information Sciences Institute of the University of Southern California).  Institutions requesting network assignments are given class-A, -B, or -C networks depending on their estimated eventual size (numbers of hosts). Sites without assigned network numbers may request an assigned number by contacting:
Joyce Reynolds
USC � Information Sciences Institute
4676 Admiralty Way
Marina del Rey, California  90292�6695
Phone: (213) 822�1511
ARPANET: JKREYNOLDS@USC-ISIF.ARPA
IP addresses are normally stored or exchanged as single 32-bit numbers.  The printed representation of an IP address takes the form W.X.Y.Z, where W through Z are the decimal values of each of the eight-bit bytes that constitute the address.  Class-A addresses are of the form N.H.H.H; class-B addresses are of the form N.N.H.H; and class-C addresses are of the form N.N.N.H, where N indicates a byte of the network number, and H indicates a byte of the host number.  For example, the address 36.47.0.12 is an address on network 36, a class-A network, and 192.10.200.1 is an address on net 192.10.200, a class-C address.
The Internet Protocol defines an address in which the host field contains all ones to be a broadcast address for its network.  Thus, the address 36.255.255.255 is the broadcast address on network 36, and 192.10.200.255 is the broadcast address on network 192.10.200.
To complete this discussion, we describe a final complication to the structure of the internetwork.  It is quite common for class-B networks to be partitioned into a set of smaller subnetworks, which are really class-C networks, but have the wrong network number to be recognized as class-C networks (just as common is partitioning a class-A network into many ��class-B'' subnetworks).  An implementation of TCP/IP that is not prepared to handle this ��violation'' of the IP standard will not be able to communicate with hosts on the same network but different subnetworks.  Fortunately, extending an IP implementation to support subnetworks is straightforward.   
We introduce into the discussion a parameter called the SUBNETMASK.  This mask is a 32-bit quantity, and resembles an IP  address.  The purpose of the mask is to enable a host to determine when a destination IP address is or is not on the same subnet as the sending host itself.  The SUBNETMASK has the following properties:
� The bitwise-AND of a source host's address (e.g., this machine) and the SUBNETMASK must be equal to the bitwise-AND of a destination host's address and the SUBNETMASK if and only if the two hosts are on the same subnetwork.
� The bitwise-AND of a source host's address and the SUBNETMASK must not be equal to the bitwise-AND of a destination host's address and the SUBNETMASK if and only if the two hosts are on different subnetworks. 
As an example, consider network 39.0.0.0.  This is a class-A network.  Suppose this network consists of a number of subnetworks; for example, subnetworks with numbers like 39.47.*.* and 39.9.*.*.  According to the IP specification, these subnetworks should really be one monolithic network, such that a host desiring to communicate with any other host whose address begins with 36... should have to take no special action with regards to routing packets to that host.  Let us assume that this is not the case.  The only way a machine has of telling which hosts are on different networks is to compare the masked version of the address with the masked version of its own address.
To continue the example further, assume the following:
� Host A has address 39.9.0.6.  Host A's SUBNETMASK is 39.255.0.0.
� Host B has address 39.9.0.7. Host B's SUBNETMASK is also 39.255.0.0.
� Host C has address 39.47.0.6.  Host C's SUBNETMASK is also 39.255.0.0.
When host A sends to host B, it compares its masked address with host B's masked address, and finds them equal:
39.9.0.6 AND 39.255.0.0 = 39.9.0.0;   39.9.0.7 AND 39.255.0.0 = 39.9.0.0
However, when host A sends to host C, it finds the masked comparison does not match:
39.9.0.6 AND 39.255.0.0 = 39.9.0.0;  39.47.0.6 AND 39.255.0.0 = 36.47.0.0
Class-A networks that are subdivided into ��class-B'' subnetworks have SUBNETMASKs that look like X.255.0.0, where X is the class-A network number.  Likewise, class-B networks subdivided into ��class-C'' subnetworks have SUBNETMASKs that look like X.Y.255.0, where X.Y is the class-B network number.  FInally, networks in which subnet routing is not in use have SUBNETMASKs identical to their network addresses; for example, if network 36 did not use subnet routing, its SUBNETMASK would be 36.0.0.0.
The definitive document on this approach to subnetwork routing is RFC940.
We now document each of the files in the TCP/IP package.
2

TCP
1

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
1

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
1

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 are, however, two important global variables:
TCPFTP.DEFAULT.FILETYPES	[Variable]
This variable is an association list, keyed by common extensions of file names, and contains appropriate file types (e.g., TEXT or BINARY) for such files.  The TCPFTP protocol provides no mechanism for determining the type of a file about to be retrieved. 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 TCPFTP package has to infer the file type from other knowledge.  The package tries to match the extension of the file name with an entry on the list TCPFTP.DEFAULT.FILETYPES.  If it finds a match, it uses the value of the entry in the list as the file type of the file; if it doesn't find a match, it uses the value of TCP.DEFAULTFILETYPE (described below) for the file type of the file.
TCP.DEFAULTFILETYPE	[Variable]
If no matching extension is found for the file being opened, the TCPFTP package uses the value of TCP.DEFAULTFILETYPE as the file type of the remote file.  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.  
TCPNAMES
1

The TCPNAMES package provides a set of functions for translating between the file-naming conventions of different operating systems.  This is needed by the TCPFTP package in order for it to convert between Interlisp-D formation file names and foreign operating systems' format file names.  Users need not be concerned with the details of this package, but the following functions may be of interest to applications writers.
(REPACKFILENAME.STRING NAME FOROSTYPE)	[Function]
NAME is a file name in some operating system's format.  FOROSTYPE is the name of an operating system.  REPACKFILENAME.STRING attempts to translate NAME into a format acceptable to the operating system named by FOROSTYPE.  NAME may be a string or atom; the function always returns a string.  Currently acceptable operating system types are: INTERLISP, IFS, TOPS-20 (also TOPS20), UNIX, VMS, MS-DOS, and SYMBOLICS-3600.
The correspondence between the target operating system type and the file name translation function is maintained in an extensible hash table.
(\REPACKFILENAME.NEW.TRANSLATION
                                                 OSTYPE FUNCTION)	[Function]
This function adds a new file name translation function for a new operating system type.  The function must be a LAMBDA-NOSPREAD function, and must be prepared to receive either a single property-list format argument, such as would be returned by UNPACKFILENAME, or an arbitrary number of arguments in property-list format.  
File names in the above format will be passed to the translation function adhering to the conventions of many operating systems; the function must recognize the operating system type and produce the desired output format, which must be a string.
\REPACKFILENAME.OSTYPE.TABLE	[Variable]
This variable is the hash table that stores the correspondence between operating system types and translation functions.
TCPCHAT
1

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]
This 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
1

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-D 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 	FIXPWaits 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
1

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 .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
1

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-D 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-D 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
1

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
1

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
SUBNETMASK          NIL
Please enter the subnet address mask for this host's 10MB network, in the form

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:
SUBNETMASK          "192.10.200.0"
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.
[This page intentionally left blank](LIST ((PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC  ) STARTINGPAGE# 219) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC  )) (270 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 618) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD LEFT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (54 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGV) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE VERSOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (270 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL)))))+,
�
�
T:��
�$Hl��:��
�$Hl��:��
�$Hl��:00
�Tx���,�
T/F


�

T/<<
�


�

T/��
�


�

T/BB
�


�

T/��
�

�

T,��
�
T2��
�`
�

T/
�



�

T2
�
`
�

T2
�
`
�

T=��
���

8
\
�
.��
�

h:��
�$Hl��1��
�

�
,
�

T,
�

T.��
�
�/��
�

�

T.��
�

�
/��
�

�

T.��
�

�
1��
�`
�
1��
�`
�
/
�


�

T/
�2


�

T/
�


�

T.��
�

�
.��
�

�
/��
�


�

T/��
�

�

TB
�


�
PAGEHEADING	VERSOHEADB
�

�
PAGEHEADING	RECTOHEADA
�



�
PAGEHEADINGFOOTINGVA
�




�
PAGEHEADINGFOOTINGR:$$
�$Hl��(
.
�

�
	MODERNMODERNGACHA
�GACHA
MODERN
MODERN

MODERNMODERN
	HELVETICA
(
HRULE.GETFN
MODERN

('
HRULE.GETFN
MODERN

'&&
HRULE.GETFN
MODERN

%%
HRULE.GETFN
MODERN
$#
HRULE.GETFN
MODERN
"w4!�
HRULE.GETFN
MODERN

 
 
HRULE.GETFN
MODERN

"� 
HRULE.GETFN
MODERN
"�!Z
HRULE.GETFN
MODERN
!&!
3 
HRULE.GETFN
MODERN
!
A!
O 
HRULE.GETFN
MODERN
!� 
HRULE.GETFN
MODERN

!
& 
HRULE.GETFN
MODERN

!� 
HRULE.GETFN
MODERN

!�

HRULE.GETFN
MODERN

 
 
HRULE.GETFN
MODERN

"
T!�	h
@�
K
	4

	n!�		4�

�!�
HRULE.GETFN
MODERN

 
 
HRULE.GETFN
MODERN

"9!�!
�%'"!m!
!�!
E!�
!Et	!�!7!C!G!I!p!I!U!J!
�!J!9
HRULE.GETFN
MODERN

 
 
HRULE.GETFN
MODERN

"�
!(
!�!Ze!�!X!
v!?�
!?
X
Q


#

�~9!'c%�	 
HRULE.GETFN
MODERN
"�
�Y




)
D

5
!

/D)
�
�
1:$f 
HRULE.GETFN
MODERN
"�$-
&!T

�

&	 
HRULE.GETFN
MODERN
"
�
4	R;	��!1


F�(y 
HRULE.GETFN
MODERN
"
a$
�M 
HRULE.GETFN
MODERN
"s�8
"Zy+
�
F
	

#N
(W!/-
!a
E
!i


#



�N
5
5
6

; 
HRULE.GETFN
MODERN
"�

#�6!
�

$4

	
	
�|.

V.d
�
HRULE.GETFN
MODERN
"
:


n;q)�	
		f	
k
$%*-a
E
+
�u!
!
�
�!S^h!�!(!4!
��H>!�
, D9
*q7
;
	z



A!
;
�
/
2	A	/LDO

0


-
.	
2@

-d>Q;X2
� 
HRULE.GETFN
MODERN
"�"�
(4
 
HRULE.GETFN
MODERN
"
H+
	1BC(<?B@D>F	8D">= 
C6!�

�!
y*

#2
�2)
	
)
K
)
O*
)
J
O)
E
)
##.#*#
2
!�$
%!�
$��	z�