BSD 4.4 Lite Share Sources

1 files changed, 722 insertions, 0 deletions

diff --git a/share/man/man4/tp.4 b/share/man/man4/tp.4
new file mode 100644
index 0000000..fdfd578
--- /dev/null
+++ b/share/man/man4/tp.4
@@ -0,0 +1,722 @@
+.\" Copyright (c) 1990, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)tp.4	8.4 (Berkeley) 4/19/94
+.\"
+.Dd April 19, 1994
+.Dt TP 4
+.Os
+.Sh NAME
+.Nm TP
+.Nd
+.Tn ISO
+Transport Protocol
+.Sh SYNOPSIS
+.Fd #include <sys/socket.h>
+.Fd #include <netiso/iso_errno.h>
+.Fd #include <netiso/tp_param.h>
+.Fd #include <netiso/tp_user.h>
+.Ft int
+.Fn socket "[AF_INET, AF_ISO]" SOCK_SEQPACKET 0
+.Sh DESCRIPTION
+.Pp
+The
+.Tn TP
+protocol provides reliable, flow-controlled, two-way
+transmission of data and record boundaries. 
+It is a byte-stream protocol and is accessed according to
+the
+.Dv SOCK_SEQPACKET
+abstraction.
+The
+.Tn TP
+protocol makes use of a standard
+.Tn ISO
+address format,
+including a Network Service Access Point, and a Transport Service Entity
+Selector.
+Subclass 4 may make use of the internet
+Internet address format.
+.Pp
+Sockets utilizing the tp protocol are either
+.Dq active
+or
+.Dq passive .
+Active sockets initiate connections to passive
+sockets.  By default
+.Tn TCP
+sockets are created active; to create a
+passive socket the
+.Xr listen 2
+system call must be used
+after binding the socket with the
+.Xr bind 2
+system call.  Only
+passive sockets may use the 
+.Xr accept 2
+call to accept incoming connections.  Only active sockets may
+use the
+.Xr connect 2
+call to initiate connections.
+.Pp
+Passive sockets may
+.Dq underspecify
+their location to match
+incoming connection requests from multiple networks.  This
+technique, termed
+.Dq wildcard addressing ,
+allows a single
+server to provide service to clients on multiple networks.
+To create a socket which listens on all networks, the
+.Tn NSAP
+portion
+of the bound address must be void (of length zero).
+The Transport Selector may still be specified
+at this time; if the port is not specified the system will assign one.
+Once a connection has been established the socket's address is
+fixed by the peer entity's location.   The address assigned the
+socket is the address associated with the network interface
+through which packets are being transmitted and received.
+.Pp
+The
+.Tn ISO
+Transport Protocol implemented for
+.Tn AOS R2
+at the University of Wisconsin - Madison,
+and modified for inclusion in the Berkeley Software Distribution,
+includes classes 0 and 4 
+of the
+.Tn ISO
+transport protocols
+as specified in
+the June 1986 version of
+.Tn IS
+8073.
+Class 4 of the protocol provides reliable, sequenced,
+flow-controlled, two-way
+transmission of data packets with an alternate stop-and-wait data path called
+the "expedited data" service.
+Class 0 is essentially a null transport protocol, which is used
+when the underlying network service provides reliable, sequenced,
+flow-controlled, two-way data transmission.
+Class 0 does not provide the expedited data service.
+The protocols are implemented as a single transport layer entity 
+that coexists with the Internet protocol suite.
+Class 0 may be used only in the
+.Tn ISO
+domain.
+Class 4 may be used in the Internet domain as well as in the
+.Tn ISO
+domain.
+.Pp
+Two system calls were modified from the previous
+release of the Berkeley Software Distribution
+to permit the support of the end-of-transport-service-data-unit
+.Pq Dv EOTSDU
+indication, and for the receipt and transmission of user
+connect, confirm, and disconnect data.
+See
+.Xr sendmsg 2
+and
+.Xr recvmsg 2 ,
+and further discussion
+below for the formats of the data in the ancillary data buffer.
+If the
+.Dv EOTSDU
+is not needed, the normal
+.Xr read 2 ,
+and
+.Xr write 2
+system calls may be used.
+.Pp
+Through the 
+.Xr getsockopt
+and
+.Xr setsockopt
+system calls,
+.Tn TP
+supports several options 
+to control such things as negotiable options
+in the protocol and protocol strategies.
+The options are defined in
+.Aq Pa netiso/tp_user.h ,
+and are described below.
+.Pp
+In the tables below,
+the options marked with a pound sign
+.Ql \&#
+may be used 
+with
+.Xr setsockopt
+after a connection is established.
+Others must be used before the connection
+is established, in other words,
+before calling
+.Xr connect
+or 
+.Xr accept .
+All options may be used 
+with
+.Xr getsockopt
+before or
+after a connection is established.
+.Bl -tag -width TPOPT_PSTATISTICS
+.It Dv TPOPT_CONN_DATA
+(char *) [none]
+.br
+Data to send on
+.Xr connect .
+The passive user may issue a
+.Xr getsockopt
+call to retrieve a connection request's user data,
+after having done the
+.Xr accept
+system call without implying confirmation of the connection.
+.Pp
+The data may also be retrieved by issuing a
+.Xr recvmsg
+request for ancillary data only,
+without implying confirmation of the connection.
+The returned
+.Va cmsghdr
+will contain
+.Dv SOL_TRANSPORT
+for the
+.Va csmg_level
+and
+.Dv TPOPT_CONN_DATA
+for
+.Va cmsg_type.
+.It Dv TPOPT_DISC_DATA \&#
+(char *) [none]
+.br
+Data to send on
+.Xr close .
+Disconnect data may be sent by the side initiating the close
+but not by the passive side ("passive" with respect to the closing
+of the connection), so there is no need to read disconnect data
+after calling
+.Xr close .
+This may be sent by a
+.Xr setsockopt
+system call, or by issuing a
+.Xr sendmsg
+request specifying ancillary data only.
+The user-provided
+.Va cmsghdr
+must contain
+.Dv SOL_TRANSPORT
+for
+.Va csmg_level
+and
+.Dv TPOPT_DISC_DATA
+for
+.Va cmsg_type .
+Sending of disconnect data will in of itself tear down (or reject)
+the connection.
+.It Dv TPOPT_CFRM_DATA \&#
+(char *) [none]
+.br
+Data to send when confirming a connection.
+This may also be sent by a 
+.Xr setsockopt
+system call, or by issuing a
+.Xr sendmsg
+request, as above.
+Sending of connect confirm data will cause the connection
+to be confirmed rather than rejected.
+.It Dv TPOPT_PERF_MEAS \&#
+Boolean.
+.br
+When
+.Xr true ,
+performance measurements will be kept
+for this connection.  
+When set before a connection is established, the
+active side will use a locally defined parameter on the
+connect request packet; if the peer is another
+.Tn ARGO
+implementation, this will cause performance measurement to be
+turned on 
+on the passive side as well.
+See
+.Xr tpperf 8 .
+.It Dv TPOPT_PSTATISTICS
+No associated value on input.
+On output,
+.Ar struct tp_pmeas .
+.Pp
+This command is used to read the performance statistics accumulated
+during a connection's lifetime.
+It can only be used with
+.Xr getsockopt .
+The structure it returns is described in
+.Aq Pa netiso/tp_stat.h .
+See
+.Xr tpperf 8 .
+.It Dv TPOPT_FLAGS
+unsigned integer. [0x0]
+.br
+This command can only be used with
+.Xr getsockopt .
+See the description of the flags below.
+.It Dv TPOPT_PARAMS
+.Ar struct tp_conn_param
+.br
+Used to get or set a group parameters for a connection.
+The
+.Ar struct tp_conn_param
+is the argument used with the
+.Xr getsockopt
+or
+.Xr setsockopt
+system call. 
+It is described in 
+.Aq Pa netiso/tp_user.h .
+.Pp
+The fields of the
+.Ar tp_conn_param
+structure are
+described below.
+.El
+.Pp
+.Em Values for TPOPT_PARAMS:
+.Bl -tag -width p_sendack_ticks
+.It Ar p_Nretrans
+nonzero short integer [1]
+.br
+Number of times a TPDU
+will be retransmitted before the
+local TP entity closes a connection.
+.It Ar p_dr_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks between retransmissions of disconnect request
+TPDUs.
+.It Ar p_dt_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks between retransmissions of data
+TPDUs.
+This parameter applies only to class 4.
+.It Ar p_cr_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks between retransmissions of connection request
+TPDUs.
+.It Ar p_cc_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks between retransmissions of connection confirm
+TPDUs.
+This parameter applies only to class 4.
+.It Ar p_x_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks between retransmissions of expedited data
+TPDUs.
+This parameter applies only to class 4.
+.It Ar p_sendack_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks that the local TP entity
+will wait before sending an acknowledgment for normal data
+(not applicable if the acknowledgement strategy is
+.Dv TPACK_EACH ) .
+This parameter applies only to class 4.
+.It Ar p_ref_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks for which a reference will
+be considered frozen after the connection to which
+it applied is closed.
+This parameter applies to classes 4 and 0 in the 
+.Tn ARGO
+implementation, despite the fact that
+the frozen reference function is required only for
+class 4.
+.It Ar p_inact_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks without an incoming packet from the peer after which 
+.Tn TP
+close the connection.
+This parameter applies only to class 4.
+.It Ar p_keepalive_ticks
+nonzero short integer [various]
+.br
+Number of clock ticks between acknowledgments that are sent
+to keep an inactive connection open (to prevent the peer's
+inactivity control function from closing the connection).
+This parameter applies only to class 4.
+.It Ar p_winsize
+short integer between 128 and 16384. [4096 bytes]
+.br
+The buffer space limits in bytes for incoming and outgoing data.
+There is no way to specify different limits for incoming and outgoing
+paths.
+The actual window size at any time
+during the lifetime of a connection
+is a function of the buffer size limit, the negotiated
+maximum TPDU
+size, and the 
+rate at which the user program receives data.
+This parameter applies only to class 4.
+.It Ar p_tpdusize
+unsigned char between 0x7 and 0xd. 
+[0xc for class 4] [0xb for class 0]
+.br
+Log 2 of the maximum TPDU size to be negotiated.
+The
+.Tn TP
+standard
+.Pf ( Tn ISO
+8473) gives an upper bound of 
+0xd for class 4 and 0xb for class 0.
+The
+.Tn ARGO
+implementation places upper bounds of
+0xc on class 4 and 0xb on class 0.
+.It Ar p_ack_strat
+.Dv TPACK_EACH
+or
+.Dv TPACK_WINDOW.
+.Bq Dv TPACK_WINDOW
+.br
+This parameter applies only to class 4.
+Two acknowledgment strategies are supported:
+.Pp
+.Dv TPACK_EACH means that each data TPDU
+is acknowledged
+with an AK TPDU.
+.Pp
+.Dv TPACK_WINDOW
+means that upon receipt of the packet that represents
+the high edge of the last window advertised, an AK TPDU is generated.
+.It Ar p_rx_strat
+4 bit mask
+.Bq Dv TPRX_USE_CW No \&|\  Dv TPRX_FASTSTART
+over
+connectionless network protocols]
+.Pf [ Dv TPRX_USE_CW
+over
+connection-oriented network protocols]
+.br
+This parameter applies only to class 4.
+The bit mask may include the following values:
+.Pp
+.Dv TPRX_EACH :
+When a retransmission timer expires, retransmit
+each packet in the send window rather than
+just the first unacknowledged packet.
+.Pp
+.Dv TPRX_USE_CW :
+Use a "congestion window" strategy borrowed
+from Van Jacobson's congestion window strategy for TCP.
+The congestion window size is set to one whenever
+a retransmission occurs.
+.Pp
+.Dv TPRX_FASTSTART :
+Begin sending the maximum amount of data permitted
+by the peer (subject to availability).
+The alternative is to start sending slowly by 
+pretending the peer's window is smaller than it is, and letting
+it slowly grow up to the peer window's real size.
+This is to smooth the effect of new connections on a congested network
+by preventing a transport connection from suddenly 
+overloading the network with a burst of packets.
+This strategy is also due to Van Jacobson.
+.It Ar p_class
+5 bit mask
+.Bq Dv TP_CLASS_4 No \&|\  Dv TP_CLASS_0
+.br
+Bit mask including one or both of the values
+.Dv TP_CLASS_4
+and
+.Dv TP_CLASS_0 .
+The higher class indicated is the preferred class.
+If only one class is indicated, negotiation will not occur
+during connection establishment.
+.It Ar p_xtd_format
+Boolean.
+[false]
+.br
+Boolean indicating that extended format is negotiated.
+This parameter applies only to class 4.
+.It Ar p_xpd_service
+Boolean.
+[true]
+.br
+Boolean indicating that 
+the expedited data transport service will be negotiated.
+This parameter applies only to class 4.
+.It Ar p_use_checksum
+Boolean.
+[true]
+.br
+Boolean indicating the the use of checksums will be negotiated.
+This parameter applies only to class 4.
+.It Ar p_use_nxpd
+Reserved for future use.
+.It Ar p_use_rcc
+Reserved for future use.
+.It Ar p_use_efc
+Reserved for future use.
+.It Ar p_no_disc_indications
+Boolean.
+[false]
+.Pp
+Boolean indicating that the local
+.Tn TP
+entity will not issue
+indications (signals) when a
+.Tn TP
+connection is disconnected.
+.It Ar p_dont_change_params
+Boolean.  [false]
+.br
+If
+.Em true
+the
+.Tn TP
+entity will not override
+any of the other values given in this structure.
+If the values cannot be used, the
+.Tn TP
+entity will drop, disconnect,
+or refuse to establish the connection to which this structure pertains.
+.It Ar p_netservice
+One of {
+.Dv ISO_CLNS ,
+.Dv ISO_CONS ,
+.Dv ISO_COSNS ,
+.Dv IN_CLNS } .
+.Pf [ Dv ISO_CLNS ]
+.br
+Indicates which network service is to be used.
+.Pp
+.Dv ISO_CLNS
+indicates the connectionless network service provided
+by CLNP 
+.Pf ( Tn ISO
+8473).
+.Pp
+.Dv ISO_CONS
+indicates the connection-oriented network service provided
+by X.25
+.Pf ( Tn ISO
+8208) and
+.Tn ISO
+8878.
+.Pp
+.Dv ISO_COSNS
+indicates the 
+connectionless network service running over a
+connection-oriented subnetwork service: CLNP 
+.Pf ( Tn ISO
+8473) over X.25
+.Pf ( Tn ISO
+8208).
+.Pp
+.Dv IN_CLNS
+indicates the 
+DARPA Internet connectionless network service provided by IP (RFC 791).
+.It Ar p_dummy
+Reserved for future use.
+.El
+.Pp
+The
+.Dv TPOPT_FLAGS
+option is used for obtaining
+various boolean-valued options.
+Its meaning is as follows.
+The bit numbering used is that of the RT PC, which means that bit
+0 is the most significant bit, while bit 8 is the least significant bit.
+.sp 1
+.Em Values for TPOPT_FLAGS:
+.Bl -tag -width Bitsx
+.It Sy Bits
+.Sy Description [Default]
+.It \&0
+.Dv TPFLAG_NLQOS_PDN :
+set when the quality of the 
+network service is
+similar to that of a public data network.
+.It \&1
+.Dv TPFLAG_PEER_ON_SAMENET :
+set when the peer
+.Tn TP
+entity
+is considered to be on the same network as the local
+.Tn TP
+entity.
+.It \&2
+Not used.
+.It \&3
+.Dv TPFLAG_XPD_PRES :
+set when expedited data are present
+[0]
+.It 4\&..7
+Reserved.
+.El
+.Sh ERROR VALUES
+.Pp
+The
+.Tn TP
+entity returns
+.Va errno
+error values as defined in
+.Aq Pa sys/errno.h
+and
+.Aq Pa netiso/iso_errno.h .
+User programs may print messages associated with these value by
+using an expanded version of
+.Xr perror
+found in the
+.Tn ISO
+library,
+.Pa libisodir.a .
+.Pp
+If the
+.Tn TP
+entity encounters asynchronous events
+that will cause a transport connection to be closed,
+such as
+timing out while retransmitting a connect request TPDU,
+or receiving a DR TPDU,
+the
+.Tn TP
+entity issues a
+.Dv SIGURG
+signal, indicating that
+disconnection has occurred.
+If the signal is issued during a 
+a system call, the system call may be interrupted,
+in which case the
+.Va errno
+value upon return from the system call is
+.Er EINTR.
+If the signal
+.Dv SIGURG
+is being handled by reading
+from the socket, and it was an
+.Xr accept 2
+that
+timed out, the read may result in
+.Er ENOTSOCK ,
+because the
+.Xr accept
+call had not yet returned a
+legitimate socket descriptor when the signal was handled.
+.Dv ETIMEDOUT
+(or a some other errno value appropriate to the
+type of error) is returned if
+.Dv SIGURG
+is blocked
+for the duration of the system call.
+A user program should take one of the following approaches:
+.Bl -tag -width Ds
+.It Block Dv SIGURG
+If the program is servicing
+only one connection, it can block or ignore
+.Dv SIGURG
+during connection 
+establishment.
+The advantage of this is that the
+.Va errno
+value
+returned is somewhat meaningful.
+The disadvantage of this is that
+if ignored, disconnection and expedited data indications could be
+missed.
+For some programs this is not a problem.
+.It Handle Dv SIGURG
+If the program is servicing more than one connection at a time
+or expedited data may arrive or both, the program may elect to
+service
+.Dv SIGURG .
+It can use the
+.Fn getsockopt ...TPOPT_FLAGS...
+system 
+call to see if the signal
+was due to the arrival of expedited data or due to a disconnection.
+In the latter case, 
+.Xr getsockopt
+will return
+.Er ENOTCONN .
+.El
+.Sh SEE ALSO
+.Xr tcp 4 ,
+.Xr netstat 1 ,
+.Xr iso 4 ,
+.Xr clnp 4 ,
+.Xr cltp 4 ,
+.Xr ifconfig 8 .
+.Sh BUGS
+The protocol definition of expedited data is slightly problematic,
+in a way that renders expedited data almost useless,
+if two or more packets of expedited data are send within
+time \(*e, where \(*e
+depends on the application.
+The problem is not of major significance since most applications
+do not use transport expedited data.
+The problem is this:
+the expedited data acknowledgment TPDU
+has no field for conveying
+credit, thus it is not possible for a
+.Tn TP
+entity to inform its peer
+that "I received your expedited data but have no room to receive more."
+The
+.Tn TP
+entity has the choice of acknowledging receipt of the
+XPD TPDU:
+.Bl -tag -width Ds
+.It "when the user receives the" XPD TSDU
+which may be a fairly long time,
+which may cause the sending
+.Tn TP
+entity to retransmit the packet,
+and possibly to close the connection after retransmission, or
+.It "when the" Tn TP No "entity receives it"
+so the sending entity does not retransmit or close the connection.
+If the sending user then tries to send more expedited data
+.Dq soon ,
+the expedited data will not be acknowledged (until the
+receiving user receives the first XPD TSDU).
+.El
+.Pp
+The
+.Tn ARGO
+implementation acknowledges XPD TPDUs
+immediately,
+in the hope that most users will not use expedited data frequently
+enough for this to be a problem.