1.\" Copyright (c) 1985, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)spp.4 8.2 (Berkeley) 04/19/94 7.\" 8.Dd 9.Dt SPP 4 10.Os BSD 4.3 11.Sh NAME 12.Nm spp 13.Nd Xerox Sequenced Packet Protocol 14.Sh SYNOPSIS 15.Fd #include <sys/socket.h> 16.Fd #include <netns/ns.h> 17.Fd #include <netns/sp.h> 18.Ft int 19.Fn socket AF_NS SOCK_STREAM 0 20.Ft int 21.Fn socket AF_NS SOCK_SEQPACKET 0 22.Sh DESCRIPTION 23The 24.Tn SPP 25protocol provides reliable, flow-controlled, two-way 26transmission of data. It is a byte-stream protocol used to 27support the 28.Dv SOCK_STREAM 29abstraction. 30.Tn SPP 31uses the standard 32.Tn NS Ns (tm) 33address formats. 34.Pp 35Sockets utilizing the 36.Tn SPP 37protocol are either 38.Dq active 39or 40.Dq passive . 41Active sockets initiate connections to passive 42sockets. By default 43.Tn SPP 44sockets are created active; to create a 45passive socket the 46.Xr listen 2 47system call must be used 48after binding the socket with the 49.Xr bind 2 50system call. Only 51passive sockets may use the 52.Xr accept 2 53call to accept incoming connections. Only active sockets may 54use the 55.Xr connect 2 56call to initiate connections. 57.Pp 58Passive sockets may 59.Dq underspecify 60their location to match 61incoming connection requests from multiple networks. This 62technique, termed 63.Dq wildcard addressing , 64allows a single 65server to provide service to clients on multiple networks. 66To create a socket which listens on all networks, the 67.Tn NS 68address of all zeroes must be bound. 69The 70.Tn SPP 71port may still be specified 72at this time; if the port is not specified the system will assign one. 73Once a connection has been established the socket's address is 74fixed by the peer entity's location. The address assigned the 75socket is the address associated with the network interface 76through which packets are being transmitted and received. Normally 77this address corresponds to the peer entity's network. 78.Pp 79If the 80.Dv SOCK_SEQPACKET 81socket type is specified, 82each packet received has the actual 12 byte sequenced packet header 83left for the user to inspect: 84.Bd -literal -offset indent 85struct sphdr { 86 u_char sp_cc; /* connection control */ 87#define SP_EM 0x10 /* end of message */ 88 u_char sp_dt; /* datastream type */ 89 u_short sp_sid; 90 u_short sp_did; 91 u_short sp_seq; 92 u_short sp_ack; 93 u_short sp_alo; 94}; 95.Ed 96.Pp 97This facilitates the implementation of higher level Xerox protocols 98which make use of the data stream type field and the end of message bit. 99Conversely, the user is required to supply a 12 byte header, 100the only part of which inspected is the data stream type and end of message 101fields. 102.Pp 103For either socket type, 104packets received with the Attention bit sent are interpreted as 105out of band data. Data sent with 106.Dq send(..., ..., ..., Dv MSG_OOB ) 107cause the attention bit to be set. 108.Sh DIAGNOSTICS 109A socket operation may fail with one of the following errors returned: 110.Bl -tag -width [EADDRNOTAVAIL] 111.It Bq Er EISCONN 112when trying to establish a connection on a socket which 113already has one; 114.It Bq Er ENOBUFS 115when the system runs out of memory for 116an internal data structure; 117.It Bq Er ETIMEDOUT 118when a connection was dropped 119due to excessive retransmissions; 120.It Bq Er ECONNRESET 121when the remote peer 122forces the connection to be closed; 123.It Bq Er ECONNREFUSED 124when the remote 125peer actively refuses connection establishment (usually because 126no process is listening to the port); 127.It Bq Er EADDRINUSE 128when an attempt 129is made to create a socket with a port which has already been 130allocated; 131.It Bq Er EADDRNOTAVAIL 132when an attempt is made to create a 133socket with a network address for which no network interface 134exists. 135.El 136.Sh SOCKET OPTIONS 137.Bl -tag -width SO_DEFAULT_HEADERS 138.It Dv SO_DEFAULT_HEADERS 139when set, this determines the data stream type and whether 140the end of message bit is to be set on every ensuing packet. 141.It Dv SO_MTU 142This specifies the maximum amount of user data in a single packet. 143The default is 576 bytes - sizeof(struct spidp). This quantity 144affects windowing \- increasing it without increasing the amount 145of buffering in the socket will lower the number of unread packets 146accepted. Anything larger than the default will not be forwarded 147by a bona fide 148.Tn XEROX 149product internetwork router. 150The data argument for the setsockopt call must be 151an unsigned short. 152.El 153.Sh SEE ALSO 154.Xr intro 4 , 155.Xr ns 4 156.Sh HISTORY 157The 158.Nm 159protocol appeared in 160.Bx 4.3 . 161.Sh BUGS 162There should be some way to reflect record boundaries in 163a stream. 164For stream mode, there should be an option to get the data stream type of 165the record the user process is about to receive. 166