BSD 4.4 Lite Share Sources

8 files changed, 1654 insertions, 0 deletions

diff --git a/share/doc/iso/ucb/addr.nr b/share/doc/iso/ucb/addr.nr
new file mode 100644
index 0000000..57eff30
--- /dev/null
+++ b/share/doc/iso/ucb/addr.nr
@@ -0,0 +1,155 @@
+.NC "NSAP Addresses & Routing"
+.sh 1 "OSI Address Formats"
+.pp
+ARGO supports an ISO address family, AF_ISO, in addition to the
+DoD Internet address family, AF_INET.
+Addresses in the family AF_ISO 
+take the form described by ISO 8348/DAD2, which is an addendum to the
+OSI network service standard that describes network layer addressing.
+.sh 2 "ISO 8348/DAD2 Tutorial"
+.pp
+.\" FIGURE
+.\".so figs/osi_addr.nr
+.so ../wisc/figs/addrfmt.nr
+.CF
+shows the
+format of an OSI NSAP-address.
+The address has two major parts: the initial domain part
+(IDP) and the domain specific part (DSP). The IDP is further divided into
+two parts: the authority and format identifier (AFI) and the
+initial domain identifier (IDI). The AFI specifies the format of the
+IDI, the authority responsible for allocating values of the IDI, and
+the syntax of the DSP. The IDI specifies the network addressing domain
+from which DSP values are allocated, and the authority responsible for
+allocating DSP values.
+.sh 2 "Supported Formats"
+.pp
+ARGO supports three types of ISO NSAP-addresses:
+one type with AFI 37(hex) and two types with AFI 47(hex).
+.sh 3 "AFI 37"
+.pp
+This value of the AFI defines the IDI to be an X.121 address or DTE
+address. 
+The DTE address is encoded in binary coded decimal.  
+The DSP syntax is binary.
+This form is intended to be used when communicating 
+across a public data network (PDN). 
+The ARGO software and documentation
+refer to this type of NSAP-address as a
+\*(lqtype 37.\*(rq
+address.
+.sh 3 "AFI 47"
+.pp
+The value of 47 for the AFI defines the IDI to be a 4 digit International
+Code Designator (ICD) allocated according to ISO 6523. 
+ARGO support two
+ICD values.
+.sh 4 "ICD 0004"
+.pp
+The ICD value of 0004 is assigned to OSINET,
+an experimental OSI network overseen by 
+National Institute of Science and Technology.\**
+.(f
+\** formerly the National Bureau of Standards
+.)f
+When this style of NSAP-address
+is used, 
+the DSP is divided into four parts: an organization identifier (2 bytes),
+a subnet identifier (2 bytes), 
+an SNPA-part (4-8 bytes), and
+an NSAP selector (1 byte). 
+The use of these fields is defined by the OSINET steering committee.
+This type of address is known as an
+\*(lqOSINET\*(rq
+address.
+.sh 4 "ICD 0006"
+.pp
+The ICD value of 0006 is assigned to the Department of Defense (DoD).
+In ARGO, NSAP-addresses with an ICD value of 0006 
+are of the format defined in RFC 986, a proposal for embedding DARPA Internet
+addresses within an OSI NSAP-address. 
+In this case, the DSP takes the form:
+version (1 byte), DARPA Internet Address (4 bytes), upper layer protocol
+identifier (1 byte).
+This is called an
+\*(lqrfc986\*(rq
+address.
+.sh 1 "Internal Representation"
+.pp
+Internally, an NSAP address takes the form
+.(b
+\fC
+.TS
+tab(+);
+l s s s s.
+struct iso_addr {
+.T&
+l l l l l.
++u_char+isoa_afi;+/* authority &
++++format id */
++union+{+ 
+++struct addr_37+addr_37;+/* x.121 */
+++struct addr_osinet+addr_osinet;+/* OSINET */
+++struct addr_rfc986+addr_rfc986;+/* Internet*/
++}+isoa_u;
++u_char+isoa_len;+/* length */
+}
+.TE
+\fR
+.)b
+The field \fIisoa_afi\fR contains the AFI for the address. 
+The union
+\fIisoa_u\fR contains the remainder of the address. 
+The length of the entire address (the AFI, IDI, and DSP) is 
+stored in \fIisoa_len\fR.
+.sh 1 "Network Layer Routing"
+.pp
+Routing at the network layer is performed by the 
+routing procedure \fIrtalloc()\fR as described in Chapter 5. 
+\fIRtalloc()\fR was designed for used in the DoD Internet
+domain.
+An unfortunate
+effect of this is that routing decisions are based upon either the
+entire NSAP address or the network portion of the address. 
+The problem is defining the network portion of an NSAP address. 
+The location and extent of the 
+network portion of an NSAP address depends on the
+style of NSAP address. 
+This decision is made by the function \fIiso_netof()\fR.
+.sh 2 "Network Portion of Type 37 Addresses"
+.pp
+There is no network portion of an X.121 address. 
+In ARGO, the network portion of a type 37 address 
+is defined to be just the AFI. 
+The obvious consequence of this is that all type 37 addresses will 
+match all other type 37 addresses
+in a network-portion comparison.
+.sh 2 "Network Portion of OSINET Addresses"
+.pp
+The network portion of an OSINET address is the organization identifier and
+the subnet identifier.
+.sh 2 "Network Portion of RFC986 Addresses"
+.pp
+The network portion of an RFC986 address is the network portion of the
+embedded DARPA Internet address. 
+ARGO does not support subnetting, a method of subdividing Internet addresses.
+.sh 1 "NSAP Address / Subnetwork Point of Attachment Mapping"
+.pp
+In order to transmit a packet on a real subnetwork, the destination
+NSAP address
+must be mapped to an SNPA address. 
+An SNPA address is the real, "hardware" address
+of a system on a network. 
+This address corresponds to the 6 byte Ethernet or Token Ring
+Adapter address, 
+or to the DTE address, which may be up to 7 bytes
+long (14 decimal digits).
+.pp
+A table, \fIsnpa_cache\fR is kept in the kernel which contains the 
+translation between NSAP-addresses and SNPA-addresses. 
+This table is used by \fIiso_snparesolve()\fR whenever a 
+datagram must be dispatched.
+The table is maintained by the the ISO ES-IS protocol entity.
+Entries can be added and deleted
+by the user program \fIclnlutil(8)\fR and
+by the CONS entity.
diff --git a/share/doc/iso/ucb/def.nr b/share/doc/iso/ucb/def.nr
new file mode 100644
index 0000000..9d8e8b8
--- /dev/null
+++ b/share/doc/iso/ucb/def.nr
@@ -0,0 +1,144 @@
+.NC "Definitions"
+.sh 1 "General Terms"
+.ip "Kernel" 5
+The source code or binary module for the Acis Operating System 
+(also know as AOS and IBM/4.3).
+.ip "User process" 5
+An instance of a program that is 
+running in unprivileged mode, in the unprivileged address space 
+commonly know as "user address space", in other words, not
+part of the kernel.
+.ip "IPC" 5
+Interprocess communication, the mechanism by which two different
+user processes send messages to each other.
+.ip "Unix, AOS" 5
+ACIS Operating System, the special testing release of Berkeley Unix 4.4BSD.
+.ip "PCB, pcb" 5
+Protocol control block.  Each instance of a protocol machine
+keeps status information, addresses, and in some cases queues
+in a pcb for each connection or socket.
+.ip "Domain" 5
+In the Berkeley Unix environment, a domain is an abstract entity which
+comprises a network architecture, addressing scheme, address format, 
+network protocols, and transport protocols.
+.sh 1 "Transport Layer Terms"
+.ip "ISO 8073"
+ISO Draft International Standard 8073, Transport Protocol Specification
+.ip "TP" 5 
+The collection of transport
+classes that have been implemented in ARGO, classes 0 and 4.
+Also means the ARGO implementation of TP. 
+.ip "TP 0" 5 
+Transport class 0.
+.ip "TP 4" 5 
+Transport class 4.
+.ip "Transport entity" 5
+Software or hardware that implements the elements of procedure
+described in ISO 8073.
+.ip "Transport user" 5
+User process that make use of the services
+provided by a transport entity.
+.ip "Transport service interface" 5
+The syntax and semantics of the set of procedures, functions, and system calls
+that are invoked by a transport user, 
+through which the services of the transport entity are delivered.
+.ip "TPDU" 5
+Transport protocol data unit, a packet that is
+passed from one transport entity to another.
+.ip "TSDU" 5
+Transport service data unit, the logical unit of data that is
+passed from a transport entity to a transport user, or from
+a transport user to a transport entity.
+.ip "CR TPDU" 5
+Connection request TPDU. 
+.ip "CC TPDU" 5
+Connection confirm TPDU.
+.ip "DR TPDU" 5
+Disconnect request TPDU.
+.ip "DC TPDU" 5
+Disconnect confirm TPDU.
+.ip "DT TPDU" 5
+Normal data TPDU.
+.ip "XPD TPDU" 5
+Expedited data TPDU.
+.ip "AK TPDU" 5
+Normal data acknowledgment TPDU.
+.ip "XAK TPDU" 5
+Expedited data acknowledgment TPDU.
+.ip "ER TPDU" 5
+Error TPDU.
+.sh 1 "Network Layer Terms"
+.ip "ISO 8473"
+ISO Draft International Standard 8473, connectionless network protocol.
+.ip "CONS"
+Connection Oriented Network Service.
+.ip "COSNS"
+Connection Oriented Sub-Network Service.
+.ip "CLNS"
+Connectionless Network Service.
+.ip "CLNP"
+Connectionless Network Protocol, or ISO 8473.
+.ip "Network Entity"
+Software or hardware that implements the elements of procedure described
+in ISO 8473.
+.ip "Network Service User"
+Software components that make use of the services provided by a network
+entity.
+.ip "Network Service Provider"
+Software components that provide the services of a network entity.
+.ip "NSAP"
+Network Service Access Point. The point at which the OSI network service
+is made available to the network service user by the network service
+provider.
+.ip "NSAP address"
+Information that the network service provider needs to identify an
+NSAP. The source and destination address fields of a CLNP packet
+are NSAP addresses.
+.ip "ES"
+End system. A system running the complete suite of OSI protocols which can
+act as an end point for communication.
+.ip "IS"
+Intermediate system. A system running the OSI layers 1, 2, and 3 which
+can act only a packet router.
+.ip "SNPA"
+The Subnetwork Point of Attachement is the point where a \fIreal\fR 
+end or intermediate system is attached to a \fIreal\fR subnetwork.
+.ip "SNPA address"
+Information that a \fIreal\fR subnetwork need to identify a \fIreal\fR end 
+or intermediate system. This is commonly referred to as the hardware address.
+.ip "NPDU"
+Network Protocol Data Unit. The unit of data which is exchanged between
+network entities.
+.ip "DT NPDU"
+Normal data NPDU.
+.ip "ER NPDU"
+Error report NPDU.
+.ip "Initial NPDU"
+A NPDU carrying the whole of the user data from an N-UNITDATA request.
+.ip "Derived NPDU"
+a NPDU whose field ar identical to those of an initial NPDU, except that it
+carries only a segment of the user data from an N-UNITDATA request.
+.ip "Segment"
+A distinct unit of data consisting of part or all of the user data provided
+in the N-UNITDATA request and delivered in the N-UNITDATA indication.
+.ip "Segmentation"
+The act of generation two or more derived NPDUs from an initial or derived
+NPDU.
+.ip "Fragment"
+A DoD Internet Protocol term with the same meaning as "segment". Used
+synonymously with "segment."
+.ip "Fragmentation"
+A DoD Internet Protocol term with the same meaning as "segmentation". Used
+synonymously with "segmentation."
+.ip "Reassembly"
+The act of regenerating an initial NPDU from two ore more derived NPDUs.
+.ip "MTU"
+Maximum transmission unit.  The maximum size of a packet that can be
+transmitted on a medium or through a protocol.
+For example, the MTU of the TP protocol is 8192 bytes, the MTU
+of and Ethernet device is 1500 bytes, and the MTU of the OSI Network
+service is 512 bytes.
+.ip "Network interface"
+The device used to attach a computer to a network, for example,
+an Ethernet adapter, or a Token Ring adapter.
+This terminology is inherited from BSD Unix.
diff --git a/share/doc/iso/ucb/intro.nr b/share/doc/iso/ucb/intro.nr
new file mode 100644
index 0000000..196b7ae
--- /dev/null
+++ b/share/doc/iso/ucb/intro.nr
@@ -0,0 +1,72 @@
+.NC "Introduction"
+.sh 1 "Introduction"
+.pp
+This document describes the usage of the ISO
+transport and network layers written for the ACIS Operating System,
+the IBM ACIS port of Berkeley 4.3 Unix\**
+.(f
+\** Unix is a registered trademark of AT&T.
+.)f
+for the IBM RT PC,
+hereafter called AOS, as modified by UC Berkeley.
+This document describes work in progress and is an extremely
+hasty job of editing an earlier document written by colleagues
+at the university of Wisconsin.
+It is to be regarded as an emergency manual prepared for testers
+at NIST and should not be redistributed further.
+As such, there are philosophical
+statements that Berkeley fundamentally disagrees with, which
+we do not presently have the time to rip out.
+Collectively, this work is called the Wisconsin ARGO kernel. 
+The ARGO kernel supports the 
+the connection-oriented ISO transport service (COTS), the
+ISO connectionless network service (CLNS)
+and a
+connection-oriented network service (CONS).
+The COTS is provided by the ISO transport protocol TP,
+ISO 8073 Revised.
+The CLNS is provided by the connectionless network protocol,
+ISO 8473.
+The CONS is provided by the X.25 protocols.
+The ARGO implementation of the CONS is not a complete
+ISO CONS, but contains enough of the CONS to support
+the COTS and the CLNS (in the latter case, the CONS can be
+viewed as a subnetwork service).
+.pp
+The purposes of this document are
+.ip "1) "
+to describe the transport service and the software interface
+between the user and provider of this service,
+.ip "2) "
+to describe the network service and the software interface it
+provides.
+.pp
+It is assumed that the reader is familiar with the \fBC\fR
+programming language,
+with Unix conventions, and with the ISO specifications listed in Appendix A.
+.sh 1 "Organization"
+.pp
+This document is composed of several chapters.
+Chapter One contains this introduction. Chapter Two presents a
+definition of terms and phrases used throughout the document.
+Chapter Three describes the transport service interface, which is
+the interface between the transport protocol implementation software and the transport user software.
+Chapter Four describes the network service interface, and the interface
+above and below the network layer.
+Chapter Five explains the format of an OSI address.
+Chapter Six describes the
+the architecture of the interprocess communication support in the 
+kernel, which to a large degree mandates
+the design of a protocol implementation for a 4.3 Unix kernel.
+.\" Appendix A is a list of the applicable ISO standards.
+.\" The manual pages relevant to the transport and network layers
+.\" are included as Appendix B.
+.pp
+Several conventions are followed in this document.
+All procedure names and system call names are followed
+by a pair of parentheses, for example,
+.i read ().
+References to manual pages consist of the name of the
+manual page, followed by the section in which
+the man page is found:
+.i read (2).
diff --git a/share/doc/iso/ucb/ipc.nr b/share/doc/iso/ucb/ipc.nr
new file mode 100644
index 0000000..6944970
--- /dev/null
+++ b/share/doc/iso/ucb/ipc.nr
@@ -0,0 +1,331 @@
+.NC "The Design of Unix IPC"
+.sh 1 "General"
+.pp
+The ARGO implementation of 
+TP and CLNP was designed to fit into the AOS
+kernel
+as easily as possible.
+All the standard protocol hooks are used.
+To understand the design, it is useful to have
+read 
+Leffler, Joy, and Fabry:
+\*(lq4.2 BSD Networking Implementation Notes\*(rq July 1983.
+This section describes the
+design of the IPC support in the AOS kernel.
+.sh 1 "Functional Unit Overview"
+.pp
+The 
+AOS
+kernel
+is a monolithic program of considerable size and complexity.
+The code can be separated into parts of distinct function,
+but there are no kernel processes per se.
+The kernel code is either executed on behalf of a user
+process, in which case the kernel was entered by a system call, 
+or it is executed on behalf of a hardware or software interrupt.
+The following sections describe briefly the major functional units 
+of the kernel.
+.\" FIGURE
+.so ../wisc/figs/func_units.nr
+.CF
+shows the arrangement of these kernel units and 
+their interactions.
+.sh 2 "The file system."
+.pp
+.sh 2 "Virtual memory support."
+.pp
+This includes protection, swapping, paging, and
+text sharing.
+.sh 2  "Blocked device drivers (disks, tapes)."
+.pp
+All these drivers share some minor functional units,
+such as buffer management and bus support
+for the various types of busses on the machine.
+.sh 2 "Interprocess communication (IPC)."
+.pp
+This includes 
+support for various protocols, 
+buffer management, and a standard interface for inter-protocol
+communication.
+.sh 2 "Network interface drivers." 
+.pp
+These drivers are closely tied to the IPC support. 
+They use the IPC's buffer management unit rather
+than the buffers used by the blocked device drivers.
+The interface between these drivers and the rest of the kernel 
+differs from the interface used by the blocked devices.
+.sh 2 "Tty driver" 
+.pp
+This is terminal support, including the user interface
+and the device drivers.
+.sh 2 "System call interface." 
+.pp
+This handles signals, traps, and system calls.
+.sh 2 "Clock." 
+.pp
+The clock is used in various forms by many
+other units.
+.sh 2 "User process support (the rest)." 
+.pp
+This includes support for accounting, process creation, 
+control, scheduling, and destruction.
+.pp
+.sh 2 "IPC"
+.pp
+The major functional unit that supports IPC
+can be divided into the following smaller functional
+units.
+.sh 3 "Buffer management." 
+.pp
+All protocols share a pool of buffers called \fImbufs\fR.
+The internal structure has changed considerably since 4.3:
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+struct mbuf {
+.T&
+l l l l.
++struct mbuf+*m_next;+/* next buffer in chain */
++struct mbuf+*m_act;+/* link in 2-d structure */
++u_long+m_len;+/* amount of data */
++char *+m_data;+/* location of data */
++short+m_type;+/* type of data */
++short+m_flags;+/* note if EOR, Packet HDR, Ext. stored */
++++/* If packet header add: */
+int+m_pkthdr.len;+/* total packet length */
+struct ifnet+*m_pkthdr.recvif;+/* rcv interface*/
++++/* If external storage add: */
++char +*m_ext.ext_buf;+/* start of buffer */
++void+(*m_ext.ext_free)();+/* free routine if not the usual */
++u_int+m_ext.ext_size;+/* size of buffer, for ext_free */
++++/* For non external */
++char+m_dat[depending];+/* done by unions, etc. */
+};
+.TE
+\fR
+.)b
+.pp
+There are two forms of mbufs - with and without external storage.
+Small ones are 128 octets in 4.4BSD.
+The data in these mbufs are located
+in the mbuf structure itself.
+Large mbufs, called \fIclusters\fR, are page-sized
+and page-aligned.
+They may be \*(lqcopied\*(rq by multiply mapping the pages they occupy.
+They consist of a page of memory plus a small mbuf structure 
+whose fields are used
+to link clusters into chains, but whose \fIm_dat\fR array is 
+not used.
+The \fIm_data\fR field of the structure 
+is a pointer to the active data in all cases.
+The remainder of the description in the argo document
+is generally obsolete, and I am merely deleting the
+rest of it at this point.
+.sh 3 "Routing." 
+.pp
+Routing decisions in the kernel are made by the procedure \fIrtalloc()\fR.
+This procedure will scan the kernel routing tables (stored in mbufs)
+looking for a route.
+The argo document here also is quite obsolete.
+We know keep a tree structure routing table,
+and do matching under masks.
+The structure for the routing entry contains tree related
+stuff pointers (parent, l-r child for internal nodes, mask and address
+for external nodes), and may be completely revised again
+to make use of patricia trees.
+.pp
+If a route is not found, then a default route is used (if present). 
+.pp
+If a route is found, the entity which called \fIrtalloc()\fR can use information
+from the \fIrtentry\fR structure to dispatch the datagram. Specifically, the
+datagram is queued on the interface identified by the interface 
+pointer \fIrt_ifp\fR.
+.sh 3 "Socket code." 
+.pp
+This is the protocol-independent part of the IPC support.
+Each communication endpoint (which may or may not be associated
+with a connection) is represented by the following structure:
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+struct socket {
+.T&
+l l l l.
++short+so_type;+/* type, e.g. SOCK_DGRAM  */
++short+so_options;+/* from socket call */
++short+so_linger;+/* time to linger @ close */
++short+so_state;+/* internal state flags */
++caddr_t+so_pcb;+/* network layer pcb */
++struct protosw+*so_proto;+/* protocol handle */
++struct socket+*so_head;+/* ptr to accept socket */
++struct socket+*so_q0;+/* queue of partial connX */
++short+so_q0len;+/* # partials on so_q0 */
++struct socket+*so_q;+/* queue of incoming connX */
++short+so_qlen;+/* # connections on so_q */
++short+so_qlimit;+/* max # queued connX */
++struct sockbuf+{
+++short+sb_cc;+/* actual chars in buffer */
+++short+sb_hiwat;+/* max actual char count */
+++short+sb_mbcnt;+/* chars of mbufs used */
+++short+sb_mbmax;+/* max chars of mbufs to use */
+++short+sb_lowat;+/* low water mark (not used yet) */
+++short+sb_timeo;+/* timeout (not used ) */
+++struct mbuf+*sb_mb;+/* the mbuf chain */
+++struct proc+*sb_sel;+/* process selecting */
+++short+sb_flags;+/* flags, see below */
++} so_rcv, so_snd;
++short+so_timeo;+/* connection timeout */
++u_short+so_error;+/* error affecting connX */
++short+so_oobmark;+/* oob mark (TCP only) */
++short+so_pgrp;+/* pgrp for signals */
+}
+.TE
+\fR
+.)b
+.pp
+The socket code maintains a pair of queues for each socket,
+\fIso_rcv\fR and \fIso_snd\fR.
+Each queue is associated with a count of the number of characters
+in the queue, the maximum number of characters allowed to be put
+in the queue, some status information (\fIsb_flags\fR), and
+several unused fields.
+For a send operation, data are copied from the user's address space
+into chains of mbufs.
+This is done by the socket module, which then calls the underlying
+transport protocol module to place the data
+on the send queue. 
+This is generally done by 
+appending to the chain beginning at \fIsb_mb\fR.
+The socket module copies data from the \fIso_rcv\fR queue
+to the user's address space to effect a receive operation.
+The underlying transport layer is expected to have put incoming
+data into \fIso_rcv\fR by calling procedures in this module.
+.in -5
+.sh 3 "Transport protocol management."
+.pp
+All protocols and address types must be \*(lqregistered\*(rq in a
+common way in order to use the IPC user interface.
+Each protocol must have an entry in a protocol switch table.
+Each entry takes the form:
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+struct protosw {
+.T&
+l l l l.
++short+pr_type;+/* socket type used for */
++short+pr_family;+/* protocol family */
++short+pr_protocol;+/* protocol # from the database */
++short+pr_flags;+/* status information */
++++/* protocol-protocol hooks */
++int+(*pr_input)();+/* input (from below) */
++int+(*pr_output)();+/* output (from above) */
++int+(*pr_ctlinput)();+/* control input */
++int+(*pr_ctloutput)();+/* control output */
++++/* user-protocol hook */
++int+(*pr_usrreq)();+/* user request: see list below */
++++/* utility hooks */
++int+(*pr_init)();+/* initialization hook */
++int+(*pr_fasttimo)();+/* fast timeout (200ms) */
++int+(*pr_slowtimo)();+/* slow timeout (500ms) */
++int+(*pr_drain)();+/* free some space (not used) */
+}
+.TE
+\fR
+.)b
+.pp
+Associated with each protocol are the types of socket
+abstractions supported by the protocol (\fIpr_type\fR), the
+format of the addresses used by the protocol (\fIpr_family\fR),
+the routines to be called to perform
+a standard set of protocol functions (\fIpr_input\fR,...,\fIpr_drain\fR),
+and some status information (\fIpr_flags\fR).
+The field pr_flags keeps such information as
+SS_ISCONNECTED (this socket has a peer),
+SS_ISCONNECTING	(this socket is in the process of establishing
+a connection),
+SS_ISDISCONNECTING (this socket is in the process of being disconnected),
+SS_CANTSENDMORE (this socket is half-closed and cannot send),
+SS_CANTRCVMORE (this socket is half-closed and cannot receive).
+There are some flags that are specific to the TCP concept
+of out-of-band data.
+A flag SS_OOBAVAIL was added for the ARGO implementation, to support
+the TP concept of out-of-band data (expedited data).
+.sh 3 "Network Interface Drivers" 
+.pp
+The drivers for the devices attaching a Unix machine to a network
+medium share a common interface to the protocol
+software.
+There is a common data structure for managing queues,
+not surprisingly, a chain of mbufs.
+There is a set of macros that are used to enqueue and
+dequeue mbuf chains at high priority.
+A driver 
+delivers an indication to a protocol entity when
+an incoming packet has been placed on a queue by 
+issuing a
+software
+interrupt.
+.sh 3 "Support for individual protocols." 
+.pp
+Each protocol is written as a separate functional unit.
+Because all protocols share the clock and the mbuf pool, they
+are not entirely insulated from each other.
+The details of TP are described in a section that
+follows.
+.\"*****************************************************
+.\" FIGURE
+.so ../wisc/figs/unix_ipc.nr
+.pp
+.CF
+shows the arrangement of the IPC  support.
+.pp
+The AOS
+IPC was designed for DoD Internet protocols, all of
+which run over DoD IP.
+The assumptions that DoD Internet is the domain
+and that DoD IP is the network layer 
+appear in the code and data structures in numerous places.
+An example is that the transport protocols all directly call
+IP routines.
+There are no hooks in the data structures through
+which the transport layer can choose a network level protocol.
+Another example is that headers are assumed to
+fit in one small mbuf (112 bytes for data in AOS).
+Another example is this:
+It is assumed in many places that buffer space is managed
+in units of characters or octets.
+The user data are copied from user address space into the kernel mbufs
+amorphously
+by the socket code, a protocol-independent part of the kernel.
+This is fine for a stream protocol, but it means that a
+packet protocol, in order to \*(lqpacketize\*(rq the data,
+must perform a memory-to-memory copy
+that might have been avoided had the protocol layer done the original
+copy from user address space.
+Furthermore, protocols that count credit in terms of packets or
+buffers rather than characters do not work efficiently because
+the computation of buffer space is not in the protocol module,
+but rather it is in the socket code module.
+This list of examples is not complete.
+.pp
+To summarize, adding a new transport protocol to the kernel consists of
+adding entries to the tables in the protocol management
+unit, 
+modifying the network interface driver(s) to recognize
+new network protocol identifiers, 
+adding the
+new system calls to the kernel and to the user library,
+and
+adding code modules for each of the protocols,
+and correcting deficiencies in the socket code,
+where the assumptions made about the nature of 
+transport protocols do not apply. 
+.i
+(Touchy touchy, aren't we!?! -- Sklower)
diff --git a/share/doc/iso/ucb/macros.nr b/share/doc/iso/ucb/macros.nr
new file mode 100644
index 0000000..88ec2d3
--- /dev/null
+++ b/share/doc/iso/ucb/macros.nr
@@ -0,0 +1,50 @@
+.\"	
+.\" Macro to initialize chapter macros
+.\"	
+.de IC
+.nr CN 0 1
+..
+.\"	
+.\" Macro to begin new chapter
+.\"	
+.de NC
+.he 'ARGO user\'s Guide, Berkeley Hack Job''Chapter \\n+(CN'
+.bp
+.sh 0 "_" 1 1 1 1 1 1
+.sz +2
+.(l C
+CHAPTER \\n(CN
+
+\fB\\$1\fR
+.)l
+.sp 1
+.(x
+Chapter \\n(CN     \\$1
+.)x
+.sz -2
+..
+.\"	
+.\"	Figure conventions:
+.\"	1) do .so of figure source - figure reg incremented here
+.\"	2) make references to figure via CF
+.\"	
+.\"	
+.\"	Macro to initialize figure register
+.\"	
+.de IF
+.nr FG 0 1
+..
+.\"	
+.\"	Macro for current figure number
+.\"	
+.de CF
+Figure \\n(FG
+..
+.\"
+.\"	Define this macro to include section headings in table of contents
+.\"
+.de $0
+.(x
+Section \\$2 \\$1
+.)x
+..
diff --git a/share/doc/iso/ucb/net_serv.nr b/share/doc/iso/ucb/net_serv.nr
new file mode 100644
index 0000000..c24eebd
--- /dev/null
+++ b/share/doc/iso/ucb/net_serv.nr
@@ -0,0 +1,163 @@
+.NC "Network Service Interface"
+.sh 1 "Connectionless Network Service"
+.pp
+This section describes the interface to the ISO connectionless network service.
+There are really two interfaces to the CLNS: the internal interface
+and the IPC interface.
+The internal interface is based on
+procedure calls. It is used only within the kernel. The IPC interface
+allows a user process to access the CLNS directly. This is used only
+for testing and debugging purposes.
+.sh 2 "Primitives"
+.pp
+The CLNS is, by definition, connectionless. Therefore, there are no 
+primitives associated with connection establishment or connection release.
+There is one primitive associated with data transfer: N-UNITDATA.
+The parameters to a N-UNITDATA request are: source NSAP address,
+destination NSAP address, quality of service, and user data. 
+The parameters of a N-UNITDATA indication are identical to those of the
+request.
+In this implementation, the quality of service parameter is not supported.
+.sh 2 "Internal Interface"
+.pp
+Within the kernel, an N-UNITDATA request is effected by the procedure
+\fIclnp_output()\fR:
+.(b
+\fC
+.TS
+tab(+);
+l s s.
+clnp_output(m0, isop, datalen, flags)
+.T&
+l l l.
+ +struct mbuf+*m0;+/* data */
+ +struct isopcb+*isop;+/* ISO protocol control block */
+ +int+datalen;+
+ +int+flags;+/* flags */
+.TE
+\fR
+.)b
+This procedure will construct a DT NPDU, route it, and transmit it on
+the appropriate subnetwork. \fIM0\fR is an mbuf chain containing the 
+user data portion of the N-UNITDATA request. \fIIsopcb\fR is the iso protocol
+control block previously allocated. \fIClnp_output\fR will use the following
+fields: \fIisop_laddr\fR, isop_faddr, isop_route, isop_options,
+isop_optindex, \fI and \fRisop_clnpcache\fR.
+\fIDatalen\fR specifies the number of bytes of user data.
+The \fIflags\fR parameter will be discussed in a subsequent chapter.
+.pp
+A N-UNITDATA indication occurs when a DT NPDU arrives. The indication is
+generated by calling the appropriate upper layer protocol input routine. 
+In the case of TP, the procedure \fItpclnp_input()\fR is called:
+.(b
+\fC
+.TS
+tab(+);
+l s s.
+tpclnp_input(m, src, dst, len)
+.T&
+l l l.
+ +struct mbuf+*m;+/* DT NPDU */
+ +struct iso_addr+*src;+/* source of packet */
+ +struct iso_addr+*dst;+/* destination of packet */
+ +int+len;+/* length of clnp header */
+.TE
+\fR
+.)b
+\fIM\fR contains the entire DT NPDU packet. \fILen\fR indicates the size
+of the CLNP header. In other words, the user data of the DT NPDU begins
+\fIlen\fR bytes into \fIm\fR. \fISrc\fR and \fIdst\fR indicate the
+source and destination NSAP addresses of the packet.
+.sh 3 "CLNP/Subnetwork Interface"
+.pp
+The design of the interface between the subnetwork and the CLNP is 
+determined by the design of the Unix network interface drivers. CLNP
+follows the conventional mechanisms for exchanging packets with a network
+interface. See the section on Network Interface Drivers in Chapter Five
+for more information on these conventions.
+.sh 2 "IPC (\*(lqRaw\*(rq) Interface"
+.pp
+The IPC interface to the CLNS allows direct (called \*(lqraw\*(rq) 
+access to CLNP. 
+This interface is intended for testing and debugging only. 
+Its use results in the
+transmission of CLNP datagrams with nonstandard identification fields.
+These raw packets may be rejected by a system not employing the same
+convention. See the section on network implementation for more information
+about the conventions.
+.pp
+In order to gain access to the raw interface
+a \fIsocket\fR, with address family AF_ISO and type SOCK_RAW must be created.
+With this socket in hand,
+the system calls \fIsendto()\fR and \fIrecvfrom()\fR can be used to 
+transmit and receive raw CLNP datagrams. 
+.sh 3 "Sending raw datagrams"
+.pp
+The format of the \fIsendto()\fR system call is:
+.(b
+\fC
+.TS
+tab(+);
+l s s.
+cc = sendto(s, msg, len, flags, to, tolen)
+.T&
+l l l.
+int+cc,s;
+char+*msg;
+int+len,flags;
+struct sockaddr+*to;
+int+to;
+.TE
+\fR
+.)b
+\f\fIS\fR is the socket previously created. \fIMsg\fR is a pointer to
+the data for the NPDU. CLNP will prepend a header to this data before
+transmission. \fILen\fR specifies the number of bytes of data. The
+\fIflags\fR parameter is unused and should be zero. \fITo\fR specifies the
+NSAP address to be used as the destination address. The size (in bytes)
+of \fIto\fR is given in \fItolen\fR. CLNP will automatically insert
+the source address based upon the route taken by the packet. The number of
+user data bytes transmitted is returned as \fIcc\fR. See \fIsendto(2)\fR
+for more information on this system call.
+.sh 3 "Receiving raw datagrams"
+.pp
+The format of the \fIrecvfrom()\fR system call is:
+.(b
+\fC
+.TS
+tab(+);
+l s s.
+cc = recvfrom(s, buf, len, flags, from, fromlen)
+.T&
+l l l.
+int+cc,s;
+char+*buf;
+int+len,flags;
+struct sockaddr+*from;
+int+*fromlen;
+.TE
+\fR
+.)b
+When used with a CLNP raw socket \fIs\fR, \fIrecvfrom()\fR will read a 
+NPDU from the CLNS. If no packet is available, the call will block.
+\fIBuf\fR specifies a buffer of \fIlen\fR bytes into which the NPDU will
+be read. The entire packet, including the header, will be read into the
+buffer. The \fIflags\fR parameter is unused, and should be zero. If 
+\fIfrom\fR is non-zero, the source address of the NPDU is filled in.
+\fIFromlen\fR is a value-result parameter, initialized to the size of
+the buffer associated with \fIfrom\fR, and modified on return to
+indicate the actual size of the address stored there. The total number
+of bytes received (header and data) is returned as \fIcc\fR.
+See \fIrecvfrom(2)\fR for more information about this system call.
+.sh 1 "Connection Oriented Network Service"
+.pp
+The ARGO Connection Oriented Network Service (CONS) is not a complete
+implementation of the
+OSI network service.
+It is that subset of the OSI network service that is used
+by ARGO Transport and by ARGO CLNP.
+.\" FIGURE
+.so ../wisc/figs/NS_primitives.nr
+.pp
+.CF
+shows which CONS service elements are provided.
diff --git a/share/doc/iso/ucb/program.nr b/share/doc/iso/ucb/program.nr
new file mode 100644
index 0000000..a431661
--- /dev/null
+++ b/share/doc/iso/ucb/program.nr
@@ -0,0 +1,42 @@
+.\"$Header: program.nr,v 1.1 88/12/05 18:10:57 nhall Exp $
+.\"$Source: /usr/argo/doc/kernel/RCS/program.nr,v $
+.\"
+.\"
+.\" FONT CONVENTIONS
+.\"
+.\" \fIprocedure()\fR
+.\" \fIsyscall()\fR
+.\" \fImanpage(3)\fR
+.\" \fIdata_structure_name\fR
+.\" \fC/file/or/directory/name\fR
+.\" \fC
+.\"    section of code
+.\" \fR
+.\"
+.\"
+.\" LOOK FOR ALL CASES OF 'writing' (as in, "at this writing")
+.\" to be sure you've updated everything before distributing this!
+.\"
+.\"This file uses -me and tbl macros.
+.so macros.nr
+.\" .pn 1
+.IC
+.IF
+.\" .(l C
+.\" .sz 16
+.\" Berkeley's Hack at the first 6 chapters of
+.\" Wisconsin ARGO 1.0 Kernel Programmer's Guide for
+.\" Academic Operating Systems 4.3
+.\" .sz 8
+.\" .)l
+.he 'ARGO 1.0 Berkeley Revision User\'s Guide'''
+.fo '%''December 9, 1988'
+.\" .bp
+.so intro.nr
+.so def.nr
+.so trans_serv.nr
+.so net_serv.nr
+.so ipc.nr
+.so addr.nr
+.bp
+.xp
diff --git a/share/doc/iso/ucb/trans_serv.nr b/share/doc/iso/ucb/trans_serv.nr
new file mode 100644
index 0000000..2f6d156
--- /dev/null
+++ b/share/doc/iso/ucb/trans_serv.nr
@@ -0,0 +1,697 @@
+.NC "Transport Service Interface"
+.sh 1 "General"
+.pp
+It is assumed that the reader is acquainted with the
+set of system calls and library routines that
+compose the
+Berkeley
+Unix interprocess communication service (IPC).
+To every extent possible 
+the ARGO transport service is provided by the same IPC mechanisms
+that support
+the transport-level services 
+included in the
+AOS distribution.
+In some instances, the interface
+provided by AOS does not support
+the services required by ISO 8073,
+so system calls were added to support these services.
+It is felt that this is superior to modifying
+existing system calls, in order to avoid the
+recoding of existing Unix utilities. 
+.pp
+What follows is a description of the system calls
+that are used to provide the transport service.
+According to Unix custom,
+the return value of a system call is 0
+if the call succeeds and -1 if
+the call fails for any reason.
+In the latter case,
+the global variable
+\fIerrno\fR contains more information
+about the error that caused the failure.
+In the descriptions of all the system calls for which
+this custom is followed,
+the return value is named
+\fIstatus\fR.
+.sh 1 "Connection establishment"
+.pp
+Establishing a TP connection is similar to
+establishing a connection using any other
+transport protocol supported by Unix.
+The same system calls are used, and the passive open
+is required.  
+Some of the parameters to the system calls differ. 
+.pp
+The following call creates a communication endpoint called a
+\fIsocket\fR.
+It returns
+a positive integer called a
+\fIsocket descriptor\fR, 
+which
+will be a parameter in all communication primitives.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+s = socket( af, type, protocol )
+.T&
+l l l.
+ +int+s,af,type,protocol;
+.TE
+\fR
+.)b
+.pp
+The \fIaf\fR parameter describes the format of addresses
+used in this communication.
+Existing formats include AF_INET (DoD Internet addresses), 
+AF_PUP (Xerox PUP-I Internet addresses), and AF_UNIX
+(addresses are Unix file names, for intra-machine IPC only).
+TP runs in either the Internet domain or the ISO domain (AF_ISO).
+When using the Internet domain, the network layer is the DoD Internet IP 
+with Internet-style addresses. The ISO domain uses the ISO
+network service and ISO-style addresses\**.
+.(f
+\**ISO/DP 8348/DAD2 Addendum to the Network
+Service Definition Covering Network Layer Addressing.
+.)f
+Regardless of the address family used, an address takes the
+general form,
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+struct sockaddr {
+.T&
+l l l l.
+ +u_char+sa_len;+/* length of sockaddr */
+ +u_char+sa_family;+/* address family */
+ +char+sa_data[14];+/* space for an address */
+}+
+.TE
+\fR
+.)b
+.lp
+.i
+A sockaddr is no longer required to be precisely 16 bytes long.
+The allocation of 14 bytes for sa_data is intended for backwards
+compatibility.
+.r
+.sp 1
+When viewed as an Internet address, it takes the form
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+struct sockaddr_in {
+.T&
+l l l l.
+ +u_char+sin_len;+/* address length */
+ +u_char+sin_family;+/* address family */
+ +u_short+sin_port;+/* internet port */
+ +struct in_addr+sin_addr;+/* network addr A.B.C.D */
+ +char+sin_zero[8];+/* unused */
+}
+.TE
+\fR
+.)b
+.sp 1
+When viewed as an ISO address, as supplied by the
+university of wisconsin, it takes the form
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+struct sockaddr_iso {
+.T&
+l l l l.
+ +u_char+siso_len;+/* address length */
+ +u_char+siso_family;+/* address family */
+ +u_short+siso_tsuffix;+/* transport suffix */
+ +struct iso_addr+siso_addr;+/* ISO NSAP addr */
+ +char+siso_zero[2];+/* unused */
+}
+.TE
+\fR
+.)b
+The address described by a \fIsockaddr_iso\fR structure
+is a TSAP-address (transport service access point address).
+It is made of an NSAP-address (network service access point address)
+and a TSAP selector (also called a transport suffix or
+transport selector, hereafter called a TSEL).
+The structure \fIsockaddr_iso\fR contains a 2-byte TSEL.
+This is for compatibility with Internet addressing.
+ARGO supports
+TSELs of length 1-64 bytes.
+TSELs of any length other than 2
+are called \*(lqextended TSELs\*(rq.
+They are described in detail in the section \fB\*(lqExtended TSELs\*(rq\fR.
+If extended TSELs are not requested, 2-byte TSELs are used by default.
+.pp
+Refer to Chapter Five for more information about ISO NSAP-addresses.
+.pp
+.i
+It is our intent at Berkeley to revamp the sockaddr_iso
+to use a more natural and uniform model, for ISO addresses.
+We cannot guarantee this modification to be complete by the
+time we are ready to have something for NIST to test.
+We hope to remove this notion of extended TSEL's as soon as
+possible, certainly by formal beta testing of 4.4.
+.r
+Since sockaddr can be 108 bytes long without breaking anything
+in the current Berkeley kernel, we should be able to eliminate
+extended TSEL's entirely by
+providing a sockaddr_iso along the lines of:
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+struct sockaddr_iso {
+.T&
+l l l l.
+ +u_char+siso_len;+/* address length */
+ +u_char+siso_family;+/* address family */
+ +u_char+siso_slen;+/* session suffix length */
+ +u_char+siso_tlen;+/* transport suffix length */
+ +u_char+siso_nlen;+/* nsap length */
+ +char+siso_data[22];+/* minimum nsap + tsel */
+}
+.TE
+\fR
+.)b
+.pp
+The \fItype\fR parameter in the \fIsocket()\fR call
+distinguishes 
+datagram protocols, stream protocols, sequenced
+packet protocols, reliable datagram protocols, and
+"raw" protocols (in other words, the absence of a transport protocol).
+Unix provides manifest named constants for each of these types.
+TP supports the sequenced packet protocol abstraction, to which
+the manifest constant SOCK_SEQPACKET applies.
+.pp
+The \fIprotocol\fR
+parameter is an integer that identifies the protocol to be used.
+Unix provides a database of protocol names  and their associated
+protocol numbers.
+Unix also provides user-level tools
+for searching the database.
+The tools take the form of library routines.
+A protocol number for TP has been chosen
+by the Internet NIC to allow TP to run in the Internet domain, and this
+has been added to the Unix network protocol database.
+The standard Internet database tools that serve TCP users
+can
+also serve user of TP
+in the Internet domain, if the TP protocol number is added to the
+proper Internet database file, 
+\fC/etc/protocols\fR.
+This change must be made for TP to run in either the Internet or
+in the ISO domain.
+The ARGO package contains a set of tools and a database
+for use with TP in the ISO domain.
+This set of tools is described in the manual pages
+\fIisodir(5)\fR and
+\fIisodir(3)\fR.
+.pp
+When a socket is created, it is not given an address.
+Since a socket cannot be reached by a remote entity unless it has an address, 
+the user must request that a socket be given an address by
+using the \fIbind()\fR system call:
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = bind( s, addr, addrlen )
+.T&
+l l l.
+ +int+s;
+ +struct sockaddr+*addr;
+ +int+addrlen;
+.TE
+\fR
+.)b
+.pp
+The address is expected to be in the format specified by the
+\fIaf\fR parameter to the \fIsocket()\fR
+call that yielded the socket descriptor \fIs\fR.
+If the user 
+passes an address parameter with a zero-valued transport suffix,
+the transport layer 
+assigns an unused 2-byte transport selector.
+This is a 4.3 Unix convention; it is not part of any ISO standard.
+.pp
+The \fIconnect()\fR system call effects an active open.
+It is used to establish a connection with an entity that is
+passively waiting for connection requests, and whose
+transport address is known.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = connect( s, addr, addrlen )
+.T&
+l l l.
+ +int+s;
+ +struct sockaddr+*addr;
+ +int+addrlen;
+.TE
+\fR
+.)b
+.pp
+The first parameter is a socket descriptor.
+The \fIaddr\fR parameter is a transport address in the format
+specified by the \fIaf\fR parameter to the \fIsocket()\fR
+call that yielded the socket descriptor \fIs\fR.
+.pp
+A passive open is accomplished with two system calls,
+\fIlisten()\fR followed by \fIaccept()\fR.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = listen( s, queuelen )
+.T&
+l l l.
+ +int+s;
+ +int+queuelen;
+.TE
+\fR
+.)b
+.pp
+The \fIqueuelen\fR argument specifies the maximum
+number of pending connection
+requests that will be queued for acceptance by this user.
+Connections are then accepted by the
+system call \fIaccept()\fR.  
+There is no way to refuse connections.
+The functional equivalent of connection
+refusal is accomplished by accepting a connection and immediately
+disconnecting.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+new_s = accept( s, addr, addrlen )
+.T&
+l l l.
+ +int+new_s, s;
+ +struct sockaddr+*addr;
+ +int+addrlen;
+.TE
+\fR
+.)b
+.pp
+The \fIaccept()\fR call completes the connection
+establishment. If a connection request from a prospective peer
+is pending on the socket described by \fIs\fR, it is removed and
+a new socket is created for use with this connection.
+A socket descriptor for the new socket is returned by the
+system call.
+If no connection requests are pending, this call blocks.
+If the \fIaccept()\fR call fails, -1 is returned.
+The transport address of the entity requesting the connection
+is returned in the \fIaddr\fR parameter, and the length
+of the address is returned in the \fIaddrlen\fR parameter.
+The address associated with the new socket is inherited
+from the socket on which the \fIlisten()\fR and \fIaccept()\fR were performed.
+.pp
+It is possible for the \fIaccept()\fR call to be interrupted
+by an asynchronous event such as the arrival of expedited
+data.
+When system calls are interrupted, Unix returns the value -1
+to the caller and puts the constant
+EINTR in the global variable \fIerrno\fR.
+This can create problems with the system call \fIaccept()\fR.
+In the case of incoming expedited data, the interruption does
+not indicate a problem, but the data may have arrived before
+the caller has received the new socket descriptor, which is the
+socket descriptor on which the expedited data are to be received.
+In order to prevent this problem from occurring, the caller must
+prevent the issuance of asynchronous indications until the
+\fIaccept()\fR
+call has returned.
+Asynchronous indications are discussed below, in 
+the section titled
+"Indications from the transport layer to the transport user".
+.pp
+It is possible to discover the 
+address bound to a 
+socket with the 
+\fIgetsockname()\fR system call.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = getsockname( s, addr, addrlen )
+.T&
+l l l.
+ +int+s;
+ +struct sockaddr+*addr;
+ +int+addrlen;
+.TE
+\fR
+.)b
+.pp
+If the socket has a peer, that is, it is connected,
+the system call
+\fIgetpeername()\fR
+is used to discover the peer's address.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = getpeername( s, addr, addrlen )
+.T&
+l l l.
+ +int+s;
+ +struct sockaddr+*addr;
+ +int+addrlen;
+.TE
+\fR
+.)b
+.lp
+The names returned by 
+\fIgetsockname()\fR and \fIgetpeername()\fR 
+do not contain extended TSELs.
+Extended TSELs can be retrieved with 
+the \fIgetsockopt()\fR and 
+\fIsetsockopt()\fR system calls, described below.
+.pp
+Unix supports several protocol-independent options
+and protocol-specific options
+associated with sockets.
+These options can be inspected and changed by using
+the \fIgetsockopt()\fR and 
+\fIsetsockopt()\fR system calls.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = getsockopt( s, level, option, value, valuelen )
+.T&
+l l l.
+ +int+s, level, option;
+ +char+*value;
+ +int+*valuelen;
+.TE
+\fR
+.)b
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = setsockopt( s, level, option, value, valuelen )
+.T&
+l l l.
+ +int+s, level, option;
+ +char+*value;
+ +int+valuelen;
+.TE
+\fR
+.)b
+.pp
+The \fIlevel\fR argument may indicate
+either
+that this option applies to sockets or that it applies to
+a specific protocol.
+The constants SOL_SOCKET, SOL_TRANSPORT, and SOL_NETWORK
+are possible values for the \fIlevel\fR argument.
+The \fIoption\fR argument is an integer that identifies
+the option chosen.
+.\" LIST THE OPTIONS HERE
+The options available to TP users provide the 
+user with the ability to control various TP protocol options
+including but not limited to
+TP class, TPDU size negotiated, TPDU format used,
+acknowledgment and retransmission strategies.
+For a detail list of the options, see the manual page \fItp(4p)\fR.
+.sh 1 "Extended TSELs"
+.pp
+ARGO supports TSELs
+of length 1 byte - 64 bytes for sockets bound to addresses in the
+AF_ISO address family.
+The ARGO user program uses the
+\fIgetsockopt()\fR
+and 
+\fIsetsockopt()\fR
+system calls to 
+discover and assign extended TSELs.
+.pp
+To create a socket with an extended TSEL,
+the process 
+.ip \(bu 5
+opens a socket with \fCsocket(AF_ISO, SOCK_SEQPACKET, ISOPROTO_TP)\fR
+.ip \(bu 5
+binds an NSAP-address to the socket with \fIbind()\fR.
+The address bound may contain a 2-byte selector (\fIiso_tsuffix\fR).
+.ip \(bu 5
+uses \fIsetsockopt()\fR with the command TPOPT_MY_TSEL,
+to assign a TSEL to the socket.
+.ip \(bu 5
+calls \fIlisten(), connect()\fR, or any other appopriate system calls
+to use the socket as desired.
+.lp
+To connect to a transport entity that is bound to a TSAP-address with
+an extended TSEL, the
+process 
+.ip \(bu 5
+opens a socket with \fCsocket(AF_ISO, SOCK_SEQPACKET, ISOPROTO_TP)\fR
+.ip \(bu 5
+uses \fIsetsockopt()\fR, with the command TPOPT_PEER_TSEL,
+to assign a PEER TSEL to the socket.
+This TSEL is used by the transport entity 
+for all subsequent connect requests made on this socket, 
+unless the peer TSEL is changed by another call to
+\fIsetsockopt()\fR employing the command TPOPT_PEER_TSEL.
+.lp
+To discover the TSEL of the peer of a connected socket,
+the process 
+.ip \(bu 5
+uses \fIgetsockopt()\fR with the command TPOPT_PEER_TSEL.
+.lp
+To discover the TSEL of socket's own address,
+the process 
+.ip \(bu 5
+uses \fIgetsockopt()\fR with the command TPOPT_MY_TSEL.
+.sh 1 "Data transfer"
+.pp
+Earlier BSD-based systems have provided system calls for data transfer
+having bugs and semantics that are problematic for TP.
+These should be correct as presented in the test system.
+The problem was in the manner in which the kernel
+handled interrupted system calls.
+The send and receive primitives
+may be interrupted by signals.
+A signal is the mechanism used to indicate
+the presence of expedited data or out-of-band data.
+If the send primitive as interrupted before completion,
+the user could not determine how many octets of data were sent.
+All forms of the existing interface 
+(\fIsend()\fR, 
+\fIrecv()\fR, 
+\fIsendmsg()\fR, 
+\fIrecvmsg()\fR, 
+\fIsendto()\fR, 
+\fIrecvfrom()\fR, 
+\fIwrite()\fR, 
+\fIread\fR, 
+\fIwritev()\fR, 
+and \fIreadv()\fR system calls)
+return an octet count
+when the system call completes, and to return a short count
+if the system call is interrupted. 
+.pp
+The system calls sendmsg and recvmsg 
+have been revised to make them more convenient for receipt of
+out of band data.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+cc = sendmsg( s, msg, flags )
+.T&
+l l l.
+ +int+s;
+ +istruct msghdr+msg;
+ +unsigned int+flags;
+.TE
+\fR
+.)b
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+cc = recvmsg( s, msg, flags )
+.T&
+l l l.
+ +int+s;
+ +istruct msghdr+msg;
+ +unsigned int+flags;
+.TE
+\fR
+.)b
+.pp
+The reader should now consult the manual page for recvmsg
+for an explanation of the elements of the msghdr structure,
+and how the calls may be used to glean user-connection-request data.
+.pp
+The \fIflags\fR parameter serves several purposes.
+The TP specification requires that TSDUs be unlimited in size.
+System calls cannot pass unlimited amounts of data between the user
+and the kernel, so
+there cannot be a one-to-one correspondence between TSDUs and
+system calls. 
+The \fIflags\fR
+parameter is used to mark the end-of-TSDU on sending data.
+When receiving, 
+TP sets this bit 
+in the flags element of the msghdr structure
+when the end of a TSDU is consumed.
+This way one TSDU can span several system calls.
+It is possible for the peer to send an empty TPDU with the end-of-TSDU
+flag set, in which case the transport user
+may receive zero octets with the end-of-TSDU flag set.
+.pp
+The \fIflags\fR parameter also serves to distinguish data transfer primitives
+from expedited data transfer primitives.
+The flag bit MSG_OOB is provided for "out of band data" in the
+DoD Internet protocols.  It is also used to provide the expedited data service
+of the ISO protocols.
+The transport layer will deliver one expedited datum (there will be a
+one-to-one correspondence between expedited TSDUs and XPD TPDUs)
+at a time.  
+The user must receive the datum before the transport
+layer will accept more expedited data.
+Each expedited datum my contain up to 16 octets.
+.pp
+.sh 1 "Disconnection"
+.pp
+The \fIclose\fR system call will disconnect any association
+between two TP entities.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+status = close( s )
+.T&
+l l l.
+ +int+s;
+.TE
+\fR
+.)b
+.pp
+The argument \fIs\fR is a socket descriptor.
+If a Unix user process terminates, Unix will close all files and
+sockets associated with the process, which means all transport
+connections associated with the process will be disconnected.
+.sh 1 "Indications from the transport layer to the transport user"
+.pp
+The above set of system calls allows you to establish
+a connection, transfer data, and disconnect. 
+The
+presence or reception of expedited data is indicated
+by TP setting the MSG_OOB bit in the flags element of the msg structure.
+A disconnection initiated by the peer or by one of the
+cooperating TP entities can be signalled by a control message,
+although we have not yet implemented this.
+.pp
+The Unix signal mechanism may be used to provide these
+service elements, as well.
+When an expedited data TSDU arrives, the TP may interrupt
+the user with a SIGURG signal ("urgent condition present on socket").
+The user must have previously registered a procedure to handle
+the signal by using the \fIsigvec()\fR system call or the
+\fIsignal()\fR library routine provided for that purpose.
+The signal handler takes the form
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+int  sighandler( signal_number)
+.T&
+l l l.
+ +int+signal_number;
+.TE
+\fR
+.)b
+.pp
+The \fIsignal_number\fR argument will be the well-known constant SIGURG.
+There are two reasons for 
+the transport layer to issue
+a SIGURG:  
+expedited data
+are present or
+disconnection was initiated by a transport entity or by the peer.
+Should the user have more than one transport connection open,
+another system call is used to determine to which socket(s)
+the urgent condition applies.
+This is the \fIselect()\fR system call, described below.
+.pp
+When the SIGURG indicates a disconnection, there may be
+user data from the peer present.
+TP saves the disconnect data for the user to receive via the
+\fIgetsockopt()\fR system call, or through the
+.IR recvmsg ()
+ancillary data mechanism.
+.\"
+.\"If the user does not receive the disconnect data before the
+.\"reference timer expires, the data will be discarded and the
+.\"socket will be closed.
+.pp
+Transport service users may use more than one transport
+connection at a time.
+The \fIselect()\fR system call facilitates this.
+.(b
+\fC
+.TS
+tab(+);
+l s s s.
+#include <sys/types.h>
++
+nfound = select( num_to_scan, recvmask, sendmask, 
++exceptmask, timeout )
+.T&
+l l l.
+ +int+nfound, num_to_scan;
+ +fd_set+*recvmask, *sendmask, *exceptmask;
+ +time+timeout;
+.TE
+\fR
+.)b
+.pp
+This system call takes as parameters a set of masks 
+that specify a subset of the socket descriptors that are in
+use by the user program.
+\fISelect()\fR inspects the sockets to see if they have data
+to be received, can service a send without blocking, or
+have an exceptional condition pending, respectively.
+The masks will be set upon return to indicate the socket descriptors
+for which the respective conditions exist.
+The \fInum_to_scan\fR argument limits the number of sockets that are
+inspected.
+The call will return within the amount of time given in the
+\fItimeout\fR parameter, or, if the parameter is zero, \fIselect()\fR
+will block indefinitely.
+.\" FIGURE
+.so ../wisc/figs/TS_primitives.nr
+.pp
+.CF
+summarizes the mapping of the transport service primitives
+to Unix facilities.