[unix-history] / share / man / man4 / spp.4

.\" Copyright (c) 1985, 1991 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.
.\"
.\"     @(#)spp.4	1.5 (Berkeley) 3/28/91
.\"
.Dd March 28, 1991
.Dt SPP 4
.Os BSD 4.3
.Sh NAME
.Nm spp
.Nd Xerox Sequenced Packet Protocol
.Sh SYNOPSIS
.Fd #include <sys/socket.h>
.Fd #include <netns/ns.h>
.Fd #include <netns/sp.h>
.Ft int
.Fn socket AF_NS SOCK_STREAM 0
.Ft int
.Fn socket AF_NS SOCK_SEQPACKET 0
.Sh DESCRIPTION
The
.Tn SPP
protocol provides reliable, flow-controlled, two-way
transmission of data.  It is a byte-stream protocol used to
support the
.Dv SOCK_STREAM
abstraction.
.Tn SPP
uses the standard
.Tn NS Ns (tm)
address formats.
.Pp
Sockets utilizing the
.Tn SPP
protocol are either
.Dq active
or
.Dq passive .
Active sockets initiate connections to passive
sockets.  By default
.Tn SPP
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 NS
address of all zeroes must be bound.
The
.Tn SPP
port 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.  Normally
this address corresponds to the peer entity's network.
.Pp
If the
.Dv SOCK_SEQPACKET
socket type is specified,
each packet received has the actual 12 byte sequenced packet header
left for the user to inspect:
.Bd -literal -offset indent
struct sphdr {
	u_char		sp_cc;	/* connection control */
#define	SP_EM	0x10		/* end of message */
	u_char		sp_dt;	/* datastream type */
	u_short		sp_sid;
	u_short		sp_did;
	u_short		sp_seq;
	u_short		sp_ack;
	u_short		sp_alo;
};
.Ed
.Pp
This facilitates the implementation of higher level Xerox protocols
which make use of the data stream type field and the end of message bit.
Conversely, the user is required to supply a 12 byte header,
the only part of which inspected is the data stream type and end of message
fields.
.Pp
For either socket type,
packets received with the Attention bit sent are interpreted as
out of band data.  Data sent with
.Dq send(..., ..., ..., Dv MSG_OOB )
cause the attention bit to be set.
.Sh DIAGNOSTICS
A socket operation may fail with one of the following errors returned:
.Bl -tag -width [EADDRNOTAVAIL]
.It Bq Er EISCONN
when trying to establish a connection on a socket which
already has one;
.It Bq Er ENOBUFS
when the system runs out of memory for
an internal data structure;
.It Bq Er ETIMEDOUT
when a connection was dropped
due to excessive retransmissions;
.It Bq Er ECONNRESET
when the remote peer
forces the connection to be closed;
.It Bq Er ECONNREFUSED
when the remote
peer actively refuses connection establishment (usually because
no process is listening to the port);
.It Bq Er EADDRINUSE
when an attempt
is made to create a socket with a port which has already been
allocated;
.It Bq Er EADDRNOTAVAIL
when an attempt is made to create a 
socket with a network address for which no network interface
exists.
.El
.Sh SOCKET OPTIONS
.Bl -tag -width SO_DEFAULT_HEADERS
.It Dv SO_DEFAULT_HEADERS
when set, this determines the data stream type and whether
the end of message bit is to be set on every ensuing packet.
.It Dv SO_MTU
This specifies the maximum ammount of user data in a single packet.
The default is 576 bytes - sizeof(struct spidp).  This quantity
affects windowing \- increasing it without increasing the amount
of buffering in the socket will lower the number of unread packets
accepted.  Anything larger than the default will not be forwarded
by a bona fide
.Tn XEROX
product internetwork router.
The data argument for the setsockopt call must be
an unsigned short.
.El
.Sh SEE ALSO
.Xr intro 4 ,
.Xr ns 4
.Sh HISTORY
The
.Nm
protocol appeared in
.Bx 4.3 .
.Sh BUGS
There should be some way to reflect record boundaries in
a stream.
For stream mode, there should be an option to get the data stream type of
the record the user process is about to receive.
Commit	Line	Data
15637ed4 RG	1	.\" Copyright (c) 1985, 1991 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)spp.4 1.5 (Berkeley) 3/28/91
	33	.\"
	34	.Dd March 28, 1991
	35	.Dt SPP 4
	36	.Os BSD 4.3
	37	.Sh NAME
	38	.Nm spp
	39	.Nd Xerox Sequenced Packet Protocol
	40	.Sh SYNOPSIS
	41	.Fd #include <sys/socket.h>
	42	.Fd #include <netns/ns.h>
	43	.Fd #include <netns/sp.h>
	44	.Ft int
	45	.Fn socket AF_NS SOCK_STREAM 0
	46	.Ft int
	47	.Fn socket AF_NS SOCK_SEQPACKET 0
	48	.Sh DESCRIPTION
	49	The
	50	.Tn SPP
	51	protocol provides reliable, flow-controlled, two-way
	52	transmission of data. It is a byte-stream protocol used to
	53	support the
	54	.Dv SOCK_STREAM
	55	abstraction.
	56	.Tn SPP
	57	uses the standard
	58	.Tn NS Ns (tm)
	59	address formats.
	60	.Pp
	61	Sockets utilizing the
	62	.Tn SPP
	63	protocol are either
	64	.Dq active
65	or
66	.Dq passive .
67	Active sockets initiate connections to passive
68	sockets. By default
69	.Tn SPP
70	sockets are created active; to create a
71	passive socket the
72	.Xr listen 2
73	system call must be used
74	after binding the socket with the
75	.Xr bind 2
76	system call. Only
77	passive sockets may use the
78	.Xr accept 2
79	call to accept incoming connections. Only active sockets may
80	use the
81	.Xr connect 2
82	call to initiate connections.
83	.Pp
84	Passive sockets may
85	.Dq underspecify
86	their location to match
87	incoming connection requests from multiple networks. This
88	technique, termed
89	.Dq wildcard addressing ,
90	allows a single
91	server to provide service to clients on multiple networks.
92	To create a socket which listens on all networks, the
93	.Tn NS
94	address of all zeroes must be bound.
95	The
96	.Tn SPP
97	port may still be specified
98	at this time; if the port is not specified the system will assign one.
99	Once a connection has been established the socket's address is
100	fixed by the peer entity's location. The address assigned the
101	socket is the address associated with the network interface
102	through which packets are being transmitted and received. Normally
103	this address corresponds to the peer entity's network.
104	.Pp
105	If the
106	.Dv SOCK_SEQPACKET
107	socket type is specified,
108	each packet received has the actual 12 byte sequenced packet header
109	left for the user to inspect:
110	.Bd -literal -offset indent
111	struct sphdr {
112	u_char sp_cc; /* connection control */
113	#define SP_EM 0x10 /* end of message */
114	u_char sp_dt; /* datastream type */
115	u_short sp_sid;
116	u_short sp_did;
117	u_short sp_seq;
118	u_short sp_ack;
119	u_short sp_alo;
120	};
121	.Ed
122	.Pp
123	This facilitates the implementation of higher level Xerox protocols
124	which make use of the data stream type field and the end of message bit.
125	Conversely, the user is required to supply a 12 byte header,
126	the only part of which inspected is the data stream type and end of message
127	fields.
128	.Pp
129	For either socket type,
130	packets received with the Attention bit sent are interpreted as
131	out of band data. Data sent with
132	.Dq send(..., ..., ..., Dv MSG_OOB )
133	cause the attention bit to be set.
134	.Sh DIAGNOSTICS
135	A socket operation may fail with one of the following errors returned:
136	.Bl -tag -width [EADDRNOTAVAIL]
137	.It Bq Er EISCONN
138	when trying to establish a connection on a socket which
139	already has one;
140	.It Bq Er ENOBUFS
141	when the system runs out of memory for
142	an internal data structure;
143	.It Bq Er ETIMEDOUT
144	when a connection was dropped
145	due to excessive retransmissions;
146	.It Bq Er ECONNRESET
147	when the remote peer
148	forces the connection to be closed;
149	.It Bq Er ECONNREFUSED
150	when the remote
151	peer actively refuses connection establishment (usually because
152	no process is listening to the port);
153	.It Bq Er EADDRINUSE
154	when an attempt
155	is made to create a socket with a port which has already been
156	allocated;
157	.It Bq Er EADDRNOTAVAIL
158	when an attempt is made to create a
159	socket with a network address for which no network interface
160	exists.
161	.El
162	.Sh SOCKET OPTIONS
163	.Bl -tag -width SO_DEFAULT_HEADERS
164	.It Dv SO_DEFAULT_HEADERS
165	when set, this determines the data stream type and whether
166	the end of message bit is to be set on every ensuing packet.
167	.It Dv SO_MTU
168	This specifies the maximum ammount of user data in a single packet.
169	The default is 576 bytes - sizeof(struct spidp). This quantity
170	affects windowing \- increasing it without increasing the amount
171	of buffering in the socket will lower the number of unread packets
172	accepted. Anything larger than the default will not be forwarded
173	by a bona fide
174	.Tn XEROX
175	product internetwork router.
176	The data argument for the setsockopt call must be
177	an unsigned short.
178	.El
179	.Sh SEE ALSO
180	.Xr intro 4 ,
181	.Xr ns 4
182	.Sh HISTORY
183	The
184	.Nm
185	protocol appeared in
186	.Bx 4.3 .
187	.Sh BUGS
188	There should be some way to reflect record boundaries in
189	a stream.
190	For stream mode, there should be an option to get the data stream type of
191	the record the user process is about to receive.