| blob | e0307c53620bb18346b729180688ece3552a09e5 |
1 .\" $NetBSD$
2 .\"
3 .NC "Transport Service Interface"
4 .sh 1 "General"
5 .pp
6 It is assumed that the reader is acquainted with the
7 set of system calls and library routines that
8 compose the
9 Berkeley
10 Unix interprocess communication service (IPC).
11 To every extent possible
12 the ARGO transport service is provided by the same IPC mechanisms
13 that support
14 the transport-level services
15 included in the
16 AOS distribution.
17 In some instances, the interface
18 provided by AOS does not support
19 the services required by ISO 8073,
20 so system calls were added to support these services.
21 It is felt that this is superior to modifying
22 existing system calls, in order to avoid the
23 recoding of existing Unix utilities.
24 .pp
25 What follows is a description of the system calls
26 that are used to provide the transport service.
27 According to Unix custom,
28 the return value of a system call is 0
29 if the call succeeds and -1 if
30 the call fails for any reason.
31 In the latter case,
32 the global variable
33 \fIerrno\fR contains more information
34 about the error that caused the failure.
35 In the descriptions of all the system calls for which
36 this custom is followed,
37 the return value is named
38 \fIstatus\fR.
39 .sh 1 "Connection establishment"
40 .pp
41 Establishing a TP connection is similar to
42 establishing a connection using any other
43 transport protocol supported by Unix.
44 The same system calls are used, and the passive open
45 is required.
46 Some of the parameters to the system calls differ.
47 .pp
48 The following call creates a communication endpoint called a
49 \fIsocket\fR.
50 It returns
51 a positive integer called a
52 \fIsocket descriptor\fR,
53 which
54 will be a parameter in all communication primitives.
55 .(b
56 \fC
57 .TS
58 tab(+);
59 l s s s.
60 s = socket( af, type, protocol )
61 .T&
62 l l l.
63 +int+s,af,type,protocol;
64 .TE
65 \fR
66 .)b
67 .pp
68 The \fIaf\fR parameter describes the format of addresses
69 used in this communication.
70 Existing formats include AF_INET (DoD Internet addresses),
71 AF_PUP (Xerox PUP-I Internet addresses), and AF_UNIX
72 (addresses are Unix file names, for intra-machine IPC only).
73 TP runs in either the Internet domain or the ISO domain (AF_ISO).
74 When using the Internet domain, the network layer is the DoD Internet IP
75 with Internet-style addresses. The ISO domain uses the ISO
76 network service and ISO-style addresses\**.
77 .(f
78 \**ISO/DP 8348/DAD2 Addendum to the Network
79 Service Definition Covering Network Layer Addressing.
80 .)f
81 Regardless of the address family used, an address takes the
82 general form,
83 .(b
84 \fC
85 .TS
86 tab(+);
87 l s s s.
88 struct sockaddr {
89 .T&
90 l l l l.
91 +u_char+sa_len;+/* length of sockaddr */
92 +u_char+sa_family;+/* address family */
93 +char+sa_data[14];+/* space for an address */
94 }+
95 .TE
96 \fR
97 .)b
98 .lp
99 .i
100 A sockaddr is no longer required to be precisely 16 bytes long.
101 The allocation of 14 bytes for sa_data is intended for backwards
102 compatibility.
103 .r
104 .sp 1
105 When viewed as an Internet address, it takes the form
106 .(b
107 \fC
108 .TS
109 tab(+);
110 l s s s.
111 struct sockaddr_in {
112 .T&
113 l l l l.
114 +u_char+sin_len;+/* address length */
115 +u_char+sin_family;+/* address family */
116 +u_short+sin_port;+/* internet port */
117 +struct in_addr+sin_addr;+/* network addr A.B.C.D */
118 +char+sin_zero[8];+/* unused */
119 }
120 .TE
121 \fR
122 .)b
123 .sp 1
124 When viewed as an ISO address, as supplied by the
125 university of wisconsin, it takes the form
126 .(b
127 \fC
128 .TS
129 tab(+);
130 l s s s.
131 struct sockaddr_iso {
132 .T&
133 l l l l.
134 +u_char+siso_len;+/* address length */
135 +u_char+siso_family;+/* address family */
136 +u_short+siso_tsuffix;+/* transport suffix */
137 +struct iso_addr+siso_addr;+/* ISO NSAP addr */
138 +char+siso_zero[2];+/* unused */
139 }
140 .TE
141 \fR
142 .)b
143 The address described by a \fIsockaddr_iso\fR structure
144 is a TSAP-address (transport service access point address).
145 It is made of an NSAP-address (network service access point address)
146 and a TSAP selector (also called a transport suffix or
147 transport selector, hereafter called a TSEL).
148 The structure \fIsockaddr_iso\fR contains a 2-byte TSEL.
149 This is for compatibility with Internet addressing.
150 ARGO supports
151 TSELs of length 1-64 bytes.
152 TSELs of any length other than 2
153 are called \*(lqextended TSELs\*(rq.
154 They are described in detail in the section \fB\*(lqExtended TSELs\*(rq\fR.
155 If extended TSELs are not requested, 2-byte TSELs are used by default.
156 .pp
157 Refer to Chapter Five for more information about ISO NSAP-addresses.
158 .pp
159 .i
160 It is our intent at Berkeley to revamp the sockaddr_iso
161 to use a more natural and uniform model, for ISO addresses.
162 We cannot guarantee this modification to be complete by the
163 time we are ready to have something for NIST to test.
164 We hope to remove this notion of extended TSEL's as soon as
165 possible, certainly by formal beta testing of 4.4.
166 .r
167 Since sockaddr can be 108 bytes long without breaking anything
168 in the current Berkeley kernel, we should be able to eliminate
169 extended TSEL's entirely by
170 providing a sockaddr_iso along the lines of:
171 .(b
172 \fC
173 .TS
174 tab(+);
175 l s s s.
176 struct sockaddr_iso {
177 .T&
178 l l l l.
179 +u_char+siso_len;+/* address length */
180 +u_char+siso_family;+/* address family */
181 +u_char+siso_slen;+/* session suffix length */
182 +u_char+siso_tlen;+/* transport suffix length */
183 +u_char+siso_nlen;+/* nsap length */
184 +char+siso_data[22];+/* minimum nsap + tsel */
185 }
186 .TE
187 \fR
188 .)b
189 .pp
190 The \fItype\fR parameter in the \fIsocket()\fR call
191 distinguishes
192 datagram protocols, stream protocols, sequenced
193 packet protocols, reliable datagram protocols, and
194 "raw" protocols (in other words, the absence of a transport protocol).
195 Unix provides manifest named constants for each of these types.
196 TP supports the sequenced packet protocol abstraction, to which
197 the manifest constant SOCK_SEQPACKET applies.
198 .pp
199 The \fIprotocol\fR
200 parameter is an integer that identifies the protocol to be used.
201 Unix provides a database of protocol names and their associated
202 protocol numbers.
203 Unix also provides user-level tools
204 for searching the database.
205 The tools take the form of library routines.
206 A protocol number for TP has been chosen
207 by the Internet NIC to allow TP to run in the Internet domain, and this
208 has been added to the Unix network protocol database.
209 The standard Internet database tools that serve TCP users
210 can
211 also serve user of TP
212 in the Internet domain, if the TP protocol number is added to the
213 proper Internet database file,
214 \fC/etc/protocols\fR.
215 This change must be made for TP to run in either the Internet or
216 in the ISO domain.
217 The ARGO package contains a set of tools and a database
218 for use with TP in the ISO domain.
219 This set of tools is described in the manual pages
220 \fIisodir(5)\fR and
221 \fIisodir(3)\fR.
222 .pp
223 When a socket is created, it is not given an address.
224 Since a socket cannot be reached by a remote entity unless it has an address,
225 the user must request that a socket be given an address by
226 using the \fIbind()\fR system call:
227 .(b
228 \fC
229 .TS
230 tab(+);
231 l s s s.
232 status = bind( s, addr, addrlen )
233 .T&
234 l l l.
235 +int+s;
236 +struct sockaddr+*addr;
237 +int+addrlen;
238 .TE
239 \fR
240 .)b
241 .pp
242 The address is expected to be in the format specified by the
243 \fIaf\fR parameter to the \fIsocket()\fR
244 call that yielded the socket descriptor \fIs\fR.
245 If the user
246 passes an address parameter with a zero-valued transport suffix,
247 the transport layer
248 assigns an unused 2-byte transport selector.
249 This is a 4.3 Unix convention; it is not part of any ISO standard.
250 .pp
251 The \fIconnect()\fR system call effects an active open.
252 It is used to establish a connection with an entity that is
253 passively waiting for connection requests, and whose
254 transport address is known.
255 .(b
256 \fC
257 .TS
258 tab(+);
259 l s s s.
260 status = connect( s, addr, addrlen )
261 .T&
262 l l l.
263 +int+s;
264 +struct sockaddr+*addr;
265 +int+addrlen;
266 .TE
267 \fR
268 .)b
269 .pp
270 The first parameter is a socket descriptor.
271 The \fIaddr\fR parameter is a transport address in the format
272 specified by the \fIaf\fR parameter to the \fIsocket()\fR
273 call that yielded the socket descriptor \fIs\fR.
274 .pp
275 A passive open is accomplished with two system calls,
276 \fIlisten()\fR followed by \fIaccept()\fR.
277 .(b
278 \fC
279 .TS
280 tab(+);
281 l s s s.
282 status = listen( s, queuelen )
283 .T&
284 l l l.
285 +int+s;
286 +int+queuelen;
287 .TE
288 \fR
289 .)b
290 .pp
291 The \fIqueuelen\fR argument specifies the maximum
292 number of pending connection
293 requests that will be queued for acceptance by this user.
294 Connections are then accepted by the
295 system call \fIaccept()\fR.
296 There is no way to refuse connections.
297 The functional equivalent of connection
298 refusal is accomplished by accepting a connection and immediately
299 disconnecting.
300 .(b
301 \fC
302 .TS
303 tab(+);
304 l s s s.
305 new_s = accept( s, addr, addrlen )
306 .T&
307 l l l.
308 +int+new_s, s;
309 +struct sockaddr+*addr;
310 +int+addrlen;
311 .TE
312 \fR
313 .)b
314 .pp
315 The \fIaccept()\fR call completes the connection
316 establishment. If a connection request from a prospective peer
317 is pending on the socket described by \fIs\fR, it is removed and
318 a new socket is created for use with this connection.
319 A socket descriptor for the new socket is returned by the
320 system call.
321 If no connection requests are pending, this call blocks.
322 If the \fIaccept()\fR call fails, -1 is returned.
323 The transport address of the entity requesting the connection
324 is returned in the \fIaddr\fR parameter, and the length
325 of the address is returned in the \fIaddrlen\fR parameter.
326 The address associated with the new socket is inherited
327 from the socket on which the \fIlisten()\fR and \fIaccept()\fR were performed.
328 .pp
329 It is possible for the \fIaccept()\fR call to be interrupted
330 by an asynchronous event such as the arrival of expedited
331 data.
332 When system calls are interrupted, Unix returns the value -1
333 to the caller and puts the constant
334 EINTR in the global variable \fIerrno\fR.
335 This can create problems with the system call \fIaccept()\fR.
336 In the case of incoming expedited data, the interruption does
337 not indicate a problem, but the data may have arrived before
338 the caller has received the new socket descriptor, which is the
339 socket descriptor on which the expedited data are to be received.
340 In order to prevent this problem from occurring, the caller must
341 prevent the issuance of asynchronous indications until the
342 \fIaccept()\fR
343 call has returned.
344 Asynchronous indications are discussed below, in
345 the section titled
346 "Indications from the transport layer to the transport user".
347 .pp
348 It is possible to discover the
349 address bound to a
350 socket with the
351 \fIgetsockname()\fR system call.
352 .(b
353 \fC
354 .TS
355 tab(+);
356 l s s s.
357 status = getsockname( s, addr, addrlen )
358 .T&
359 l l l.
360 +int+s;
361 +struct sockaddr+*addr;
362 +int+addrlen;
363 .TE
364 \fR
365 .)b
366 .pp
367 If the socket has a peer, that is, it is connected,
368 the system call
369 \fIgetpeername()\fR
370 is used to discover the peer's address.
371 .(b
372 \fC
373 .TS
374 tab(+);
375 l s s s.
376 status = getpeername( s, addr, addrlen )
377 .T&
378 l l l.
379 +int+s;
380 +struct sockaddr+*addr;
381 +int+addrlen;
382 .TE
383 \fR
384 .)b
385 .lp
386 The names returned by
387 \fIgetsockname()\fR and \fIgetpeername()\fR
388 do not contain extended TSELs.
389 Extended TSELs can be retrieved with
390 the \fIgetsockopt()\fR and
391 \fIsetsockopt()\fR system calls, described below.
392 .pp
393 Unix supports several protocol-independent options
394 and protocol-specific options
395 associated with sockets.
396 These options can be inspected and changed by using
397 the \fIgetsockopt()\fR and
398 \fIsetsockopt()\fR system calls.
399 .(b
400 \fC
401 .TS
402 tab(+);
403 l s s s.
404 status = getsockopt( s, level, option, value, valuelen )
405 .T&
406 l l l.
407 +int+s, level, option;
408 +char+*value;
409 +int+*valuelen;
410 .TE
411 \fR
412 .)b
413 .(b
414 \fC
415 .TS
416 tab(+);
417 l s s s.
418 status = setsockopt( s, level, option, value, valuelen )
419 .T&
420 l l l.
421 +int+s, level, option;
422 +char+*value;
423 +int+valuelen;
424 .TE
425 \fR
426 .)b
427 .pp
428 The \fIlevel\fR argument may indicate
429 either
430 that this option applies to sockets or that it applies to
431 a specific protocol.
432 The constants SOL_SOCKET, SOL_TRANSPORT, and SOL_NETWORK
433 are possible values for the \fIlevel\fR argument.
434 The \fIoption\fR argument is an integer that identifies
435 the option chosen.
436 .\" LIST THE OPTIONS HERE
437 The options available to TP users provide the
438 user with the ability to control various TP protocol options
439 including but not limited to
440 TP class, TPDU size negotiated, TPDU format used,
441 acknowledgment and retransmission strategies.
442 For a detail list of the options, see the manual page \fItp(4p)\fR.
443 .sh 1 "Extended TSELs"
444 .pp
445 ARGO supports TSELs
446 of length 1 byte - 64 bytes for sockets bound to addresses in the
447 AF_ISO address family.
448 The ARGO user program uses the
449 \fIgetsockopt()\fR
450 and
451 \fIsetsockopt()\fR
452 system calls to
453 discover and assign extended TSELs.
454 .pp
455 To create a socket with an extended TSEL,
456 the process
457 .ip \(bu 5
458 opens a socket with \fCsocket(AF_ISO, SOCK_SEQPACKET, ISOPROTO_TP)\fR
459 .ip \(bu 5
460 binds an NSAP-address to the socket with \fIbind()\fR.
461 The address bound may contain a 2-byte selector (\fIiso_tsuffix\fR).
462 .ip \(bu 5
463 uses \fIsetsockopt()\fR with the command TPOPT_MY_TSEL,
464 to assign a TSEL to the socket.
465 .ip \(bu 5
466 calls \fIlisten(), connect()\fR, or any other appopriate system calls
467 to use the socket as desired.
468 .lp
469 To connect to a transport entity that is bound to a TSAP-address with
470 an extended TSEL, the
471 process
472 .ip \(bu 5
473 opens a socket with \fCsocket(AF_ISO, SOCK_SEQPACKET, ISOPROTO_TP)\fR
474 .ip \(bu 5
475 uses \fIsetsockopt()\fR, with the command TPOPT_PEER_TSEL,
476 to assign a PEER TSEL to the socket.
477 This TSEL is used by the transport entity
478 for all subsequent connect requests made on this socket,
479 unless the peer TSEL is changed by another call to
480 \fIsetsockopt()\fR employing the command TPOPT_PEER_TSEL.
481 .lp
482 To discover the TSEL of the peer of a connected socket,
483 the process
484 .ip \(bu 5
485 uses \fIgetsockopt()\fR with the command TPOPT_PEER_TSEL.
486 .lp
487 To discover the TSEL of socket's own address,
488 the process
489 .ip \(bu 5
490 uses \fIgetsockopt()\fR with the command TPOPT_MY_TSEL.
491 .sh 1 "Data transfer"
492 .pp
493 Earlier BSD-based systems have provided system calls for data transfer
494 having bugs and semantics that are problematic for TP.
495 These should be correct as presented in the test system.
496 The problem was in the manner in which the kernel
497 handled interrupted system calls.
498 The send and receive primitives
499 may be interrupted by signals.
500 A signal is the mechanism used to indicate
501 the presence of expedited data or out-of-band data.
502 If the send primitive as interrupted before completion,
503 the user could not determine how many octets of data were sent.
504 All forms of the existing interface
505 (\fIsend()\fR,
506 \fIrecv()\fR,
507 \fIsendmsg()\fR,
508 \fIrecvmsg()\fR,
509 \fIsendto()\fR,
510 \fIrecvfrom()\fR,
511 \fIwrite()\fR,
512 \fIread\fR,
513 \fIwritev()\fR,
514 and \fIreadv()\fR system calls)
515 return an octet count
516 when the system call completes, and to return a short count
517 if the system call is interrupted.
518 .pp
519 The system calls sendmsg and recvmsg
520 have been revised to make them more convenient for receipt of
521 out of band data.
522 .(b
523 \fC
524 .TS
525 tab(+);
526 l s s s.
527 cc = sendmsg( s, msg, flags )
528 .T&
529 l l l.
530 +int+s;
531 +istruct msghdr+msg;
532 +unsigned int+flags;
533 .TE
534 \fR
535 .)b
536 .(b
537 \fC
538 .TS
539 tab(+);
540 l s s s.
541 cc = recvmsg( s, msg, flags )
542 .T&
543 l l l.
544 +int+s;
545 +istruct msghdr+msg;
546 +unsigned int+flags;
547 .TE
548 \fR
549 .)b
550 .pp
551 The reader should now consult the manual page for recvmsg
552 for an explanation of the elements of the msghdr structure,
553 and how the calls may be used to glean user-connection-request data.
554 .pp
555 The \fIflags\fR parameter serves several purposes.
556 The TP specification requires that TSDUs be unlimited in size.
557 System calls cannot pass unlimited amounts of data between the user
558 and the kernel, so
559 there cannot be a one-to-one correspondence between TSDUs and
560 system calls.
561 The \fIflags\fR
562 parameter is used to mark the end-of-TSDU on sending data.
563 When receiving,
564 TP sets this bit
565 in the flags element of the msghdr structure
566 when the end of a TSDU is consumed.
567 This way one TSDU can span several system calls.
568 It is possible for the peer to send an empty TPDU with the end-of-TSDU
569 flag set, in which case the transport user
570 may receive zero octets with the end-of-TSDU flag set.
571 .pp
572 The \fIflags\fR parameter also serves to distinguish data transfer primitives
573 from expedited data transfer primitives.
574 The flag bit MSG_OOB is provided for "out of band data" in the
575 DoD Internet protocols. It is also used to provide the expedited data service
576 of the ISO protocols.
577 The transport layer will deliver one expedited datum (there will be a
578 one-to-one correspondence between expedited TSDUs and XPD TPDUs)
579 at a time.
580 The user must receive the datum before the transport
581 layer will accept more expedited data.
582 Each expedited datum my contain up to 16 octets.
583 .pp
584 .sh 1 "Disconnection"
585 .pp
586 The \fIclose\fR system call will disconnect any association
587 between two TP entities.
588 .(b
589 \fC
590 .TS
591 tab(+);
592 l s s s.
593 status = close( s )
594 .T&
595 l l l.
596 +int+s;
597 .TE
598 \fR
599 .)b
600 .pp
601 The argument \fIs\fR is a socket descriptor.
602 If a Unix user process terminates, Unix will close all files and
603 sockets associated with the process, which means all transport
604 connections associated with the process will be disconnected.
605 .sh 1 "Indications from the transport layer to the transport user"
606 .pp
607 The above set of system calls allows you to establish
608 a connection, transfer data, and disconnect.
609 The
610 presence or reception of expedited data is indicated
611 by TP setting the MSG_OOB bit in the flags element of the msg structure.
612 A disconnection initiated by the peer or by one of the
613 cooperating TP entities can be signalled by a control message,
614 although we have not yet implemented this.
615 .pp
616 The Unix signal mechanism may be used to provide these
617 service elements, as well.
618 When an expedited data TSDU arrives, the TP may interrupt
619 the user with a SIGURG signal ("urgent condition present on socket").
620 The user must have previously registered a procedure to handle
621 the signal by using the \fIsigvec()\fR system call or the
622 \fIsignal()\fR library routine provided for that purpose.
623 The signal handler takes the form
624 .(b
625 \fC
626 .TS
627 tab(+);
628 l s s s.
629 int sighandler( signal_number)
630 .T&
631 l l l.
632 +int+signal_number;
633 .TE
634 \fR
635 .)b
636 .pp
637 The \fIsignal_number\fR argument will be the well-known constant SIGURG.
638 There are two reasons for
639 the transport layer to issue
640 a SIGURG:
641 expedited data
642 are present or
643 disconnection was initiated by a transport entity or by the peer.
644 Should the user have more than one transport connection open,
645 another system call is used to determine to which socket(s)
646 the urgent condition applies.
647 This is the \fIselect()\fR system call, described below.
648 .pp
649 When the SIGURG indicates a disconnection, there may be
650 user data from the peer present.
651 TP saves the disconnect data for the user to receive via the
652 \fIgetsockopt()\fR system call, or through the
653 .IR recvmsg ()
654 ancillary data mechanism.
655 .\"
656 .\"If the user does not receive the disconnect data before the
657 .\"reference timer expires, the data will be discarded and the
658 .\"socket will be closed.
659 .pp
660 Transport service users may use more than one transport
661 connection at a time.
662 The \fIselect()\fR system call facilitates this.
663 .(b
664 \fC
665 .TS
666 tab(+);
667 l s s s.
668 #include <sys/types.h>
669 +
670 nfound = select( num_to_scan, recvmask, sendmask,
671 +exceptmask, timeout )
672 .T&
673 l l l.
674 +int+nfound, num_to_scan;
675 +fd_set+*recvmask, *sendmask, *exceptmask;
676 +time+timeout;
677 .TE
678 \fR
679 .)b
680 .pp
681 This system call takes as parameters a set of masks
682 that specify a subset of the socket descriptors that are in
683 use by the user program.
684 \fISelect()\fR inspects the sockets to see if they have data
685 to be received, can service a send without blocking, or
686 have an exceptional condition pending, respectively.
687 The masks will be set upon return to indicate the socket descriptors
688 for which the respective conditions exist.
689 The \fInum_to_scan\fR argument limits the number of sockets that are
690 inspected.
691 The call will return within the amount of time given in the
692 \fItimeout\fR parameter, or, if the parameter is zero, \fIselect()\fR
693 will block indefinitely.
694 .\" FIGURE
695 .so ../wisc/figs/TS_primitives.nr
696 .pp
697 .CF
698 summarizes the mapping of the transport service primitives
699 to Unix facilities.