| blob | 596c3ad9547c5dcffaf6c2c0f5824ae095c23cb1 |
1 .\" $NetBSD: tp.4,v 1.16 2003/08/07 10:31:04 agc Exp $
2 .\"
3 .\" Copyright (c) 1990, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)tp.4 8.4 (Berkeley) 4/19/94
31 .\"
32 .Dd April 19, 1994
33 .Dt TP 4
34 .Os
35 .Sh NAME
36 .Nm tp
37 .Nd
38 .Tn ISO
39 Transport Protocol
40 .Sh SYNOPSIS
41 .In sys/socket.h
42 .In netiso/iso_errno.h
43 .In netiso/tp_param.h
44 .In netiso/tp_user.h
45 .Ft int
46 .Fn socket "[AF_INET, AF_ISO]" SOCK_SEQPACKET 0
47 .Sh DESCRIPTION
48 The
49 .Tn TP
50 protocol provides reliable, flow-controlled, two-way
51 transmission of data and record boundaries.
52 It is a byte-stream protocol and is accessed according to
53 the
54 .Dv SOCK_SEQPACKET
55 abstraction.
56 The
57 .Tn TP
58 protocol makes use of a standard
59 .Tn ISO
60 address format,
61 including a Network Service Access Point, and a Transport Service Entity
62 Selector.
63 Subclass 4 may make use of the
64 Internet address format.
65 .Pp
66 Sockets using the TP protocol are either
67 .Dq active
68 or
69 .Dq passive .
70 Active sockets initiate connections to passive
71 sockets. By default
72 .Tn TCP
73 sockets are created active; to create a
74 passive socket the
75 .Xr listen 2
76 system call must be used
77 after binding the socket with the
78 .Xr bind 2
79 system call. Only
80 passive sockets may use the
81 .Xr accept 2
82 call to accept incoming connections. Only active sockets may
83 use the
84 .Xr connect 2
85 call to initiate connections.
86 .Pp
87 Passive sockets may
88 .Dq underspecify
89 their location to match
90 incoming connection requests from multiple networks. This
91 technique, termed
92 .Dq wildcard addressing ,
93 allows a single
94 server to provide service to clients on multiple networks.
95 To create a socket which listens on all networks, the
96 .Tn NSAP
97 portion
98 of the bound address must be void (of length zero).
99 The Transport Selector may still be specified
100 at this time; if the port is not specified the system will assign one.
101 Once a connection has been established the socket's address is
102 fixed by the peer entity's location. The address assigned the
103 socket is the address associated with the network interface
104 through which packets are being transmitted and received.
105 .Pp
106 The
107 .Tn ISO
108 Transport Protocol implemented for
109 .Tn AOS R2
110 at the University of Wisconsin - Madison,
111 and modified for inclusion in the Berkeley Software Distribution,
112 includes classes 0 and 4
113 of the
114 .Tn ISO
115 transport protocols
116 as specified in
117 the June 1986 version of
118 .Tn IS
119 8073.
120 Class 4 of the protocol provides reliable, sequenced,
121 flow-controlled, two-way
122 transmission of data packets with an alternative stop-and-wait data path called
123 the "expedited data" service.
124 Class 0 is essentially a null transport protocol, which is used
125 when the underlying network service provides reliable, sequenced,
126 flow-controlled, two-way data transmission.
127 Class 0 does not provide the expedited data service.
128 The protocols are implemented as a single transport layer entity
129 that coexists with the Internet protocol suite.
130 Class 0 may be used only in the
131 .Tn ISO
132 domain.
133 Class 4 may be used in the Internet domain as well as in the
134 .Tn ISO
135 domain.
136 .Pp
137 Two system calls were modified from the previous
138 release of the Berkeley Software Distribution
139 to permit the support of the end-of-transport-service-data-unit
140 .Pq Dv EOTSDU
141 indication, and for the receipt and transmission of user
142 connect, confirm, and disconnect data.
143 See
144 .Xr sendmsg 2
145 and
146 .Xr recvmsg 2 ,
147 and further discussion
148 below for the formats of the data in the ancillary data buffer.
149 If the
150 .Dv EOTSDU
151 is not needed, the normal
152 .Xr read 2
153 and
154 .Xr write 2
155 system calls may be used.
156 .Pp
157 Through the
158 .Xr getsockopt 2
159 and
160 .Xr setsockopt 2
161 system calls,
162 .Tn TP
163 supports several options
164 to control such things as negotiable options
165 in the protocol and protocol strategies.
166 The options are defined in
167 .Aq Pa netiso/tp_user.h ,
168 and are described below.
169 .Pp
170 In the tables below,
171 the options marked with a pound sign
172 .Ql \&#
173 may be used with
174 .Xr setsockopt 2
175 after a connection is established.
176 Others must be used before the connection is established, in other
177 words, before calling
178 .Xr connect 2
179 or
180 .Xr accept 2 .
181 All options may be used
182 with
183 .Xr getsockopt 2
184 before or after a connection is established.
185 .Bl -tag -width TPOPT_PSTATISTICS
186 .It Dv TPOPT_CONN_DATA
187 (char *) [none]
188 .br
189 Data to send on
190 .Xr connect 2 .
191 The passive user may issue a
192 .Xr getsockopt 2
193 call to retrieve a connection request's user data,
194 after having done the
195 .Xr accept 2
196 system call without implying confirmation of the connection.
197 .Pp
198 The data may also be retrieved by issuing a
199 .Xr recvmsg 2
200 request for ancillary data only,
201 without implying confirmation of the connection.
202 The returned
203 .Va cmsghdr
204 will contain
205 .Dv SOL_TRANSPORT
206 for the
207 .Va csmg_level
208 and
209 .Dv TPOPT_CONN_DATA
210 for
211 .Va cmsg_type .
212 .It Dv TPOPT_DISC_DATA \&#
213 (char *) [none]
214 .br
215 Data to send on
216 .Xr close 2 .
217 Disconnect data may be sent by the side initiating the close
218 but not by the passive side ("passive" with respect to the closing
219 of the connection), so there is no need to read disconnect data
220 after calling
221 .Xr close 2 .
222 This may be sent by a
223 .Xr setsockopt 2
224 system call, or by issuing a
225 .Xr sendmsg 2
226 request specifying ancillary data only.
227 The user-provided
228 .Va cmsghdr
229 must contain
230 .Dv SOL_TRANSPORT
231 for
232 .Va csmg_level
233 and
234 .Dv TPOPT_DISC_DATA
235 for
236 .Va cmsg_type .
237 Sending of disconnect data will in of itself tear down (or reject)
238 the connection.
239 .It Dv TPOPT_CFRM_DATA \&#
240 (char *) [none]
241 .br
242 Data to send when confirming a connection.
243 This may also be sent by a
244 .Xr setsockopt 2
245 system call, or by issuing a
246 .Xr sendmsg 2
247 request, as above.
248 Sending of connect confirm data will cause the connection
249 to be confirmed rather than rejected.
250 .It Dv TPOPT_PERF_MEAS \&#
251 Boolean.
252 .br
253 When true,
254 performance measurements will be kept
255 for this connection.
256 When set before a connection is established, the
257 active side will use a locally defined parameter on the
258 connect request packet; if the peer is another
259 .Tn ARGO
260 implementation, this will cause performance measurement to be
261 turned on
262 on the passive side as well.
263 .\" See
264 .\" .Xr tpperf 8 .
265 .It Dv TPOPT_PSTATISTICS
266 No associated value on input.
267 On output,
268 .Ar struct tp_pmeas .
269 .Pp
270 This command is used to read the performance statistics accumulated
271 during a connection's lifetime.
272 It can only be used with
273 .Xr getsockopt 2 .
274 The structure it returns is described in
275 .Aq Pa netiso/tp_stat.h .
276 .\" See
277 .\" .Xr tpperf 8 .
278 .It Dv TPOPT_FLAGS
279 unsigned integer. [0x0]
280 .br
281 This command can only be used with
282 .Xr getsockopt 2 .
283 See the description of the flags below.
284 .It Dv TPOPT_PARAMS
285 .Ar struct tp_conn_param
286 .br
287 Used to get or set a group parameters for a connection.
288 The
289 .Ar struct tp_conn_param
290 is the argument used with the
291 .Xr getsockopt 2
292 or
293 .Xr setsockopt 2
294 system call.
295 It is described in
296 .Aq Pa netiso/tp_user.h .
297 .Pp
298 The fields of the
299 .Ar tp_conn_param
300 structure are
301 described below.
302 .El
303 .Pp
304 .Em Values for TPOPT_PARAMS :
305 .Bl -tag -width p_sendack_ticks
306 .It Ar p_Nretrans
307 nonzero short integer [1]
308 .br
309 Number of times a TPDU
310 will be retransmitted before the
311 local TP entity closes a connection.
312 .It Ar p_dr_ticks
313 nonzero short integer [various]
314 .br
315 Number of clock ticks between retransmissions of disconnect request
316 TPDUs.
317 .It Ar p_dt_ticks
318 nonzero short integer [various]
319 .br
320 Number of clock ticks between retransmissions of data
321 TPDUs.
322 This parameter applies only to class 4.
323 .It Ar p_cr_ticks
324 nonzero short integer [various]
325 .br
326 Number of clock ticks between retransmissions of connection request
327 TPDUs.
328 .It Ar p_cc_ticks
329 nonzero short integer [various]
330 .br
331 Number of clock ticks between retransmissions of connection confirm
332 TPDUs.
333 This parameter applies only to class 4.
334 .It Ar p_x_ticks
335 nonzero short integer [various]
336 .br
337 Number of clock ticks between retransmissions of expedited data
338 TPDUs.
339 This parameter applies only to class 4.
340 .It Ar p_sendack_ticks
341 nonzero short integer [various]
342 .br
343 Number of clock ticks that the local TP entity
344 will wait before sending an acknowledgment for normal data
345 (not applicable if the acknowledgement strategy is
346 .Dv TPACK_EACH ) .
347 This parameter applies only to class 4.
348 .It Ar p_ref_ticks
349 nonzero short integer [various]
350 .br
351 Number of clock ticks for which a reference will
352 be considered frozen after the connection to which
353 it applied is closed.
354 This parameter applies to classes 4 and 0 in the
355 .Tn ARGO
356 implementation, despite the fact that
357 the frozen reference function is required only for
358 class 4.
359 .It Ar p_inact_ticks
360 nonzero short integer [various]
361 .br
362 Number of clock ticks without an incoming packet from the peer after which
363 .Tn TP
364 close the connection.
365 This parameter applies only to class 4.
366 .It Ar p_keepalive_ticks
367 nonzero short integer [various]
368 .br
369 Number of clock ticks between acknowledgments that are sent
370 to keep an inactive connection open (to prevent the peer's
371 inactivity control function from closing the connection).
372 This parameter applies only to class 4.
373 .It Ar p_winsize
374 short integer between 128 and 16384. [4096 bytes]
375 .br
376 The buffer space limits in bytes for incoming and outgoing data.
377 There is no way to specify different limits for incoming and outgoing
378 paths.
379 The actual window size at any time
380 during the lifetime of a connection
381 is a function of the buffer size limit, the negotiated
382 maximum TPDU
383 size, and the
384 rate at which the user program receives data.
385 This parameter applies only to class 4.
386 .It Ar p_tpdusize
387 unsigned char between 0x7 and 0xd.
388 [0xc for class 4] [0xb for class 0]
389 .br
390 Log 2 of the maximum TPDU size to be negotiated.
391 The
392 .Tn TP
393 standard
394 .Pf ( Tn ISO
395 8473) gives an upper bound of
396 0xd for class 4 and 0xb for class 0.
397 The
398 .Tn ARGO
399 implementation places upper bounds of
400 0xc on class 4 and 0xb on class 0.
401 .It Ar p_ack_strat
402 .Dv TPACK_EACH
403 or
404 .Dv TPACK_WINDOW .
405 .Bq Dv TPACK_WINDOW
406 .br
407 This parameter applies only to class 4.
408 Two acknowledgment strategies are supported:
409 .Pp
410 .Dv TPACK_EACH means that each data TPDU
411 is acknowledged
412 with an AK TPDU.
413 .Pp
414 .Dv TPACK_WINDOW
415 means that upon receipt of the packet that represents
416 the high edge of the last window advertised, an AK TPDU is generated.
417 .It Ar p_rx_strat
418 4 bit mask
419 .Bq Dv TPRX_USE_CW No \&|\ Dv TPRX_FASTSTART
420 over
421 connectionless network protocols]
422 .Pf [ Dv TPRX_USE_CW
423 over
424 connection-oriented network protocols]
425 .br
426 This parameter applies only to class 4.
427 The bit mask may include the following values:
428 .Pp
429 .Dv TPRX_EACH :
430 When a retransmission timer expires, retransmit
431 each packet in the send window rather than
432 just the first unacknowledged packet.
433 .Pp
434 .Dv TPRX_USE_CW :
435 Use a "congestion window" strategy borrowed
436 from Van Jacobson's congestion window strategy for TCP.
437 The congestion window size is set to one whenever
438 a retransmission occurs.
439 .Pp
440 .Dv TPRX_FASTSTART :
441 Begin sending the maximum amount of data permitted
442 by the peer (subject to availability).
443 The alternative is to start sending slowly by
444 pretending the peer's window is smaller than it is, and letting
445 it slowly grow up to the peer window's real size.
446 This is to smooth the effect of new connections on a congested network
447 by preventing a transport connection from suddenly
448 overloading the network with a burst of packets.
449 This strategy is also due to Van Jacobson.
450 .It Ar p_class
451 5 bit mask
452 .Bq Dv TP_CLASS_4 No \&|\ Dv TP_CLASS_0
453 .br
454 Bit mask including one or both of the values
455 .Dv TP_CLASS_4
456 and
457 .Dv TP_CLASS_0 .
458 The higher class indicated is the preferred class.
459 If only one class is indicated, negotiation will not occur
460 during connection establishment.
461 .It Ar p_xtd_format
462 Boolean.
463 [false]
464 .br
465 Boolean indicating that extended format is negotiated.
466 This parameter applies only to class 4.
467 .It Ar p_xpd_service
468 Boolean.
469 [true]
470 .br
471 Boolean indicating that
472 the expedited data transport service will be negotiated.
473 This parameter applies only to class 4.
474 .It Ar p_use_checksum
475 Boolean.
476 [true]
477 .br
478 Boolean indicating the use of checksums will be negotiated.
479 This parameter applies only to class 4.
480 .It Ar p_use_nxpd
481 Reserved for future use.
482 .It Ar p_use_rcc
483 Reserved for future use.
484 .It Ar p_use_efc
485 Reserved for future use.
486 .It Ar p_no_disc_indications
487 Boolean.
488 [false]
489 .Pp
490 Boolean indicating that the local
491 .Tn TP
492 entity will not issue
493 indications (signals) when a
494 .Tn TP
495 connection is disconnected.
496 .It Ar p_dont_change_params
497 Boolean. [false]
498 .br
499 If
500 .Em true
501 the
502 .Tn TP
503 entity will not override
504 any of the other values given in this structure.
505 If the values cannot be used, the
506 .Tn TP
507 entity will drop, disconnect,
508 or refuse to establish the connection to which this structure pertains.
509 .It Ar p_netservice
510 One of {
511 .Dv ISO_CLNS ,
512 .Dv ISO_CONS ,
513 .Dv ISO_COSNS ,
514 .Dv IN_CLNS } .
515 .Pf [ Dv ISO_CLNS ]
516 .br
517 Indicates which network service is to be used.
518 .Pp
519 .Dv ISO_CLNS
520 indicates the connectionless network service provided
521 by CLNP
522 .Pf ( Tn ISO
523 8473).
524 .Pp
525 .Dv ISO_CONS
526 indicates the connection-oriented network service provided
527 by X.25
528 .Pf ( Tn ISO
529 8208) and
530 .Tn ISO
531 8878.
532 .Pp
533 .Dv ISO_COSNS
534 indicates the
535 connectionless network service running over a
536 connection-oriented subnetwork service: CLNP
537 .Pf ( Tn ISO
538 8473) over X.25
539 .Pf ( Tn ISO
540 8208).
541 .Pp
542 .Dv IN_CLNS
543 indicates the
544 DARPA Internet connectionless network service provided by IP (RFC 791).
545 .It Ar p_dummy
546 Reserved for future use.
547 .El
548 .Pp
549 The
550 .Dv TPOPT_FLAGS
551 option is used for obtaining
552 various boolean-valued options.
553 Its meaning is as follows.
554 The bit numbering used is that of the RT PC, which means that bit
555 0 is the most significant bit, while bit 8 is the least significant bit.
556 .sp 1
557 .Em Values for TPOPT_FLAGS :
558 .Bl -tag -width Bitsx
559 .It Sy Bits
560 .Sy Description [Default]
561 .It \&0
562 .Dv TPFLAG_NLQOS_PDN :
563 set when the quality of the
564 network service is
565 similar to that of a public data network.
566 .It \&1
567 .Dv TPFLAG_PEER_ON_SAMENET :
568 set when the peer
569 .Tn TP
570 entity
571 is considered to be on the same network as the local
572 .Tn TP
573 entity.
574 .It \&2
575 Not used.
576 .It \&3
577 .Dv TPFLAG_XPD_PRES :
578 set when expedited data are present
579 [0]
580 .It 4\&..7
581 Reserved.
582 .El
583 .Sh ERRORS
584 The
585 .Tn TP
586 entity returns
587 .Va errno
588 error values as defined in
589 .Aq Pa sys/errno.h
590 and
591 .Aq Pa netiso/iso_errno.h .
592 .\" User programs may print messages associated with these value by
593 .\" using an expanded version of
594 .\" .Xr perror 3
595 .\" found in the
596 .\" .Tn ISO
597 .\" library,
598 .\" .Pa libisodir.a .
599 .Pp
600 If the
601 .Tn TP
602 entity encounters asynchronous events
603 that will cause a transport connection to be closed,
604 such as
605 timing out while retransmitting a connect request TPDU,
606 or receiving a DR TPDU,
607 the
608 .Tn TP
609 entity issues a
610 .Dv SIGURG
611 signal, indicating that
612 disconnection has occurred.
613 If the signal is issued during a system call, the system call
614 may be interrupted, in which case the
615 .Va errno
616 value upon return from the system call is
617 .Er EINTR .
618 If the signal
619 .Dv SIGURG
620 is being handled by reading
621 from the socket, and it was an
622 .Xr accept 2
623 that
624 timed out, the read may result in
625 .Er ENOTSOCK ,
626 because the
627 .Xr accept 2
628 call had not yet returned a
629 legitimate socket descriptor when the signal was handled.
630 .Dv ETIMEDOUT
631 (or a some other errno value appropriate to the
632 type of error) is returned if
633 .Dv SIGURG
634 is blocked
635 for the duration of the system call.
636 A user program should take one of the following approaches:
637 .Bl -tag -width Ds
638 .It Block Dv SIGURG
639 If the program is servicing
640 only one connection, it can block or ignore
641 .Dv SIGURG
642 during connection
643 establishment.
644 The advantage of this is that the
645 .Va errno
646 value
647 returned is somewhat meaningful.
648 The disadvantage of this is that
649 if ignored, disconnection and expedited data indications could be
650 missed.
651 For some programs this is not a problem.
652 .It Handle Dv SIGURG
653 If the program is servicing more than one connection at a time
654 or expedited data may arrive or both, the program may elect to
655 service
656 .Dv SIGURG .
657 It can use the
658 .Fn getsockopt ...TPOPT_FLAGS...
659 system call to see if the signal
660 was due to the arrival of expedited data or due to a disconnection.
661 In the latter case,
662 .Xr getsockopt 2
663 will return
664 .Er ENOTCONN .
665 .El
666 .Sh SEE ALSO
667 .Xr netstat 1 ,
668 .Xr clnp 4 ,
669 .Xr cltp 4 ,
670 .Xr iso 4 ,
671 .Xr tcp 4 ,
672 .Xr ifconfig 8
673 .Sh BUGS
674 The protocol definition of expedited data is slightly problematic,
675 in a way that renders expedited data almost useless,
676 if two or more packets of expedited data are sent within
677 time epsilon, where epsilon depends on the application.
678 The problem is not of major significance since most applications
679 do not use transport expedited data.
680 The problem is this: the expedited data acknowledgment TPDU has
681 no field for conveying credit, thus it is not possible for a
682 .Tn TP
683 entity to inform its peer
684 that "I received your expedited data but have no room to receive more."
685 The
686 .Tn TP
687 entity has the choice of acknowledging receipt of the
688 XPD TPDU:
689 .Bl -tag -width Ds
690 .It "when the user receives the" XPD TSDU
691 which may be a fairly long time, which may cause the sending
692 .Tn TP
693 entity to retransmit the packet,
694 and possibly to close the connection after retransmission, or
695 .It "when the" Tn TP No "entity receives it"
696 so the sending entity does not retransmit or close the connection.
697 If the sending user then tries to send more expedited data
698 .Dq soon ,
699 the expedited data will not be acknowledged (until the
700 receiving user receives the first XPD TSDU).
701 .El
702 .Pp
703 The
704 .Tn ARGO
705 implementation acknowledges XPD TPDUs immediately, in the hope that
706 most users will not use expedited data frequently enough for this
707 to be a problem.