| blob | f47b6b456e63e9ec874a086448557b212f9085a3 |
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 +short+sa_family;+/* address family */
92 +char+sa_data[14];+/* space for an address */
93 }+
94 .TE
95 \fR
96 .)b
97 .sp 1
98 When viewed as an Internet address, it takes the form
99 .(b
100 \fC
101 .TS
102 tab(+);
103 l s s s.
104 struct sockaddr_in {
105 .T&
106 l l l l.
107 +short+sin_family;+/* address family */
108 +u_short+sin_port;+/* internet port */
109 +struct in_addr+sin_addr;+/* network addr A.B.C.D */
110 +char+sin_zero[8];+/* unused */
111 }
112 .TE
113 \fR
114 .)b
115 .sp 1
116 When viewed as an ISO address, it takes the form
117 .(b
118 \fC
119 .TS
120 tab(+);
121 l s s s.
122 struct sockaddr_iso {
123 .T&
124 l l l l.
125 +short+siso_family;+/* address family */
126 +u_short+siso_tsuffix;+/* transport suffix */
127 +struct iso_addr+siso_addr;+/* ISO NSAP addr */
128 +char+siso_zero[2];+/* unused */
129 }
130 .TE
131 \fR
132 .)b
133 The address described by a \fIsockaddr_iso\fR structure
134 is a TSAP-address (transport service access point address).
135 It is made of an NSAP-address (network service access point address)
136 and a TSAP selector (also called a transport suffix or
137 transport selector, hereafter called a TSEL).
138 The structure \fIsockaddr_iso\fR contains a 2-byte TSEL.
139 This is for compatibility with Internet addressing.
140 ARGO supports
141 TSELs of length 1-64 bytes.
142 TSELs of any length other than 2
143 are called \*(lqextended TSELs\*(rq.
144 They are described in detail in the section \fB\*(lqExtended TSELs\*(rq\fR.
145 If extended TSELs are not requested, 2-byte TSELs are used by default.
146 .pp
147 Refer to Chapter Five for more information about ISO NSAP-addresses.
148 .pp
149 The \fItype\fR parameter in the \fIsocket()\fR call
150 distinguishes
151 datagram protocols, stream protocols, sequenced
152 packet protocols, reliable datagram protocols, and
153 "raw" protocols (in other words, the absence of a transport protocol).
154 Unix provides manifest named constants for each of these types.
155 TP supports the sequenced packet protocol abstraction, to which
156 the manifest constant SOCK_SEQPACKET applies.
157 .pp
158 The \fIprotocol\fR
159 parameter is an integer that identifies the protocol to be used.
160 Unix provides a database of protocol names and their associated
161 protocol numbers.
162 Unix also provides user-level tools
163 for searching the database.
164 The tools take the form of library routines.
165 A protocol number for TP has been chosen
166 by the Internet NIC to allow TP to run in the Internet domain, and this
167 has been added to the Unix network protocol database.
168 The standard Internet database tools that serve TCP users
169 can
170 also serve user of TP
171 in the Internet domain, if the TP protocol number is added to the
172 proper Internet database file,
173 \fC/etc/protocols\fR.
174 This change must be made for TP to run in either the Internet or
175 in the ISO domain.
176 The ARGO package contains a set of tools and a database
177 for use with TP in the ISO domain.
178 This set of tools is described in the manual pages
179 \fIisodir(5)\fR and
180 \fIisodir(3)\fR.
181 .pp
182 When a socket is created, it is not given an address.
183 Since a socket cannot be reached by a remote entity unless it has an address,
184 the user must request that a socket be given an address by
185 using the \fIbind()\fR system call:
186 .(b
187 \fC
188 .TS
189 tab(+);
190 l s s s.
191 status = bind( s, addr, addrlen )
192 .T&
193 l l l.
194 +int+s;
195 +struct sockaddr+*addr;
196 +int+addrlen;
197 .TE
198 \fR
199 .)b
200 .pp
201 The address is expected to be in the format specified by the
202 \fIaf\fR parameter to the \fIsocket()\fR
203 call that yielded the socket descriptor \fIs\fR.
204 If the user
205 passes an address parameter with a zero-valued transport suffix,
206 the transport layer
207 assigns an unused 2-byte transport selector.
208 This is a 4.3 Unix convention; it is not part of any ISO standard.
209 .pp
210 The \fIconnect()\fR system call effects an active open.
211 It is used to establish a connection with an entity that is
212 passively waiting for connection requests, and whose
213 transport address is known.
214 .(b
215 \fC
216 .TS
217 tab(+);
218 l s s s.
219 status = connect( s, addr, addrlen )
220 .T&
221 l l l.
222 +int+s;
223 +struct sockaddr+*addr;
224 +int+addrlen;
225 .TE
226 \fR
227 .)b
228 .pp
229 The first parameter is a socket descriptor.
230 The \fIaddr\fR parameter is a transport address in the format
231 specified by the \fIaf\fR parameter to the \fIsocket()\fR
232 call that yielded the socket descriptor \fIs\fR.
233 .pp
234 A passive open is accomplished with two system calls,
235 \fIlisten()\fR followed by \fIaccept()\fR.
236 .(b
237 \fC
238 .TS
239 tab(+);
240 l s s s.
241 status = listen( s, queuelen )
242 .T&
243 l l l.
244 +int+s;
245 +int+queuelen;
246 .TE
247 \fR
248 .)b
249 .pp
250 The \fIqueuelen\fR argument specifies the maximum
251 number of pending connection
252 requests that will be queued for acceptance by this user.
253 Connections are then accepted by the
254 system call \fIaccept()\fR.
255 There is no way to refuse connections.
256 The functional equivalent of connection
257 refusal is accomplished by accepting a connection and immediately
258 disconnecting.
259 .(b
260 \fC
261 .TS
262 tab(+);
263 l s s s.
264 new_s = accept( s, addr, addrlen )
265 .T&
266 l l l.
267 +int+new_s, s;
268 +struct sockaddr+*addr;
269 +int+addrlen;
270 .TE
271 \fR
272 .)b
273 .pp
274 The \fIaccept()\fR call completes the connection
275 establishment. If a connection request from a prospective peer
276 is pending on the socket described by \fIs\fR, it is removed and
277 a new socket is created for use with this connection.
278 A socket descriptor for the new socket is returned by the
279 system call.
280 If no connection requests are pending, this call blocks.
281 If the \fIaccept()\fR call fails, -1 is returned.
282 The transport address of the entity requesting the connection
283 is returned in the \fIaddr\fR parameter, and the length
284 of the address is returned in the \fIaddrlen\fR parameter.
285 The address associated with the new socket is inherited
286 from the socket on which the \fIlisten()\fR and \fIaccept()\fR were performed.
287 .pp
288 It is possible for the \fIaccept()\fR call to be interrupted
289 by an asynchronous event such as the arrival of expedited
290 data.
291 When system calls are interrupted, Unix returns the value -1
292 to the caller and puts the constant
293 EINTR in the global variable \fIerrno\fR.
294 This can create problems with the system call \fIaccept()\fR.
295 In the case of incoming expedited data, the interruption does
296 not indicate a problem, but the data may have arrived before
297 the caller has received the new socket descriptor, which is the
298 socket descriptor on which the expedited data are to be received.
299 In order to prevent this problem from occurring, the caller must
300 prevent the issuance of asynchronous indications until the
301 \fIaccept()\fR
302 call has returned.
303 Asynchronous indications are discussed below, in
304 the section titled
305 "Indications from the transport layer to the transport user".
306 .pp
307 It is possible to discover the
308 address bound to a
309 socket with the
310 \fIgetsockname()\fR system call.
311 .(b
312 \fC
313 .TS
314 tab(+);
315 l s s s.
316 status = getsockname( s, addr, addrlen )
317 .T&
318 l l l.
319 +int+s;
320 +struct sockaddr+*addr;
321 +int+addrlen;
322 .TE
323 \fR
324 .)b
325 .pp
326 If the socket has a peer, that is, it is connected,
327 the system call
328 \fIgetpeername()\fR
329 is used to discover the peer's address.
330 .(b
331 \fC
332 .TS
333 tab(+);
334 l s s s.
335 status = getpeername( s, addr, addrlen )
336 .T&
337 l l l.
338 +int+s;
339 +struct sockaddr+*addr;
340 +int+addrlen;
341 .TE
342 \fR
343 .)b
344 .lp
345 The names returned by
346 \fIgetsockname()\fR and \fIgetpeername()\fR
347 do not contain extended TSELs.
348 Extended TSELs can be retrieved with
349 the \fIgetsockopt()\fR and
350 \fIsetsockopt()\fR system calls, described below.
351 .pp
352 Unix supports several protocol-independent options
353 and protocol-specific options
354 associated with sockets.
355 These options can be inspected and changed by using
356 the \fIgetsockopt()\fR and
357 \fIsetsockopt()\fR system calls.
358 .(b
359 \fC
360 .TS
361 tab(+);
362 l s s s.
363 status = getsockopt( s, level, option, value, valuelen )
364 .T&
365 l l l.
366 +int+s, level, option;
367 +char+*value;
368 +int+*valuelen;
369 .TE
370 \fR
371 .)b
372 .(b
373 \fC
374 .TS
375 tab(+);
376 l s s s.
377 status = setsockopt( s, level, option, value, valuelen )
378 .T&
379 l l l.
380 +int+s, level, option;
381 +char+*value;
382 +int+valuelen;
383 .TE
384 \fR
385 .)b
386 .pp
387 The \fIlevel\fR argument may indicate
388 either
389 that this option applies to sockets or that it applies to
390 a specific protocol.
391 The constants SOL_SOCKET, SOL_TRANSPORT, and SOL_NETWORK
392 are possible values for the \fIlevel\fR argument.
393 The \fIoption\fR argument is an integer that identifies
394 the option chosen.
395 .\" LIST THE OPTIONS HERE
396 The options available to TP users provide the
397 user with the ability to control various TP protocol options
398 including but not limited to
399 TP class, TPDU size negotiated, TPDU format used,
400 acknowledgment and retransmission strategies.
401 For a detail list of the options, see the manual page \fItp(4p)\fR.
402 .sh 1 "Extended TSELs"
403 .pp
404 ARGO supports TSELs
405 of length 1 byte - 64 bytes for sockets bound to addresses in the
406 AF_ISO address family.
407 The ARGO user program uses the
408 \fIgetsockopt()\fR
409 and
410 \fIsetsockopt()\fR
411 system calls to
412 discover and assign extended TSELs.
413 .pp
414 To create a socket with an extended TSEL,
415 the process
416 .ip \(bu 5
417 opens a socket with \fCsocket(AF_ISO, SOCK_SEQPACKET, ISOPROTO_TP)\fR
418 .ip \(bu 5
419 binds an NSAP-address to the socket with \fIbind()\fR.
420 The address bound may contain a 2-byte selector (\fIiso_tsuffix\fR).
421 .ip \(bu 5
422 uses \fIsetsockopt()\fR with the command TPOPT_MY_TSEL,
423 to assign a TSEL to the socket.
424 .ip \(bu 5
425 calls \fIlisten(), connect()\fR, or any other appopriate system calls
426 to use the socket as desired.
427 .lp
428 To connect to a transport entity that is bound to a TSAP-address with
429 an extended TSEL, the
430 process
431 .ip \(bu 5
432 opens a socket with \fCsocket(AF_ISO, SOCK_SEQPACKET, ISOPROTO_TP)\fR
433 .ip \(bu 5
434 uses \fIsetsockopt()\fR, with the command TPOPT_PEER_TSEL,
435 to assign a PEER TSEL to the socket.
436 This TSEL is used by the transport entity
437 for all subsequent connect requests made on this socket,
438 unless the peer TSEL is changed by another call to
439 \fIsetsockopt()\fR employing the command TPOPT_PEER_TSEL.
440 .lp
441 To discover the TSEL of the peer of a connected socket,
442 the process
443 .ip \(bu 5
444 uses \fIgetsockopt()\fR with the command TPOPT_PEER_TSEL.
445 .lp
446 To discover the TSEL of socket's own address,
447 the process
448 .ip \(bu 5
449 uses \fIgetsockopt()\fR with the command TPOPT_MY_TSEL.
450 .sh 1 "Data transfer"
451 .pp
452 The system calls provided by AOS for data transfer have
453 semantics that are unsuitable for TP,
454 and in fact they are seriously deficient for the correct
455 operation of any user program that uses out-of-band or expedited
456 data in any way except to cause the program to abort.
457 The problem lies in the manner in which the kernel
458 handles interrupted system calls.
459 The send and receive primitives
460 may be interrupted by signals.
461 A signal is the mechanism used to indicate
462 the presence of expedited data or out-of-band data.
463 If the send or receive primitive is interrupted before completion,
464 the user needs to know how many octets of data were sent or received.
465 The existing system call interface does not provide this
466 information, nor does it permit TP to provide
467 this information.
468 All forms of the existing interface
469 (\fIsend()\fR,
470 \fIrecv()\fR,
471 \fIsendmsg()\fR,
472 \fIrecvmsg()\fR,
473 \fIsendto()\fR,
474 \fIrecvfrom()\fR,
475 \fIwrite()\fR,
476 \fIread\fR,
477 \fIwritev()\fR,
478 and \fIreadv()\fR system calls)
479 return an octet count
480 when the system call completes, and return an error
481 indication (-1, \fIerrno\fR == EINTR) if the system call is interrupted.
482 To change the semantics
483 of these calls would create havoc with existing user-level software.
484 Instead two new system calls are provided to support data transfer.
485 (The existing interface may be used if the user does not need the additional
486 service provided by the new system calls.)
487 .pp
488 The two new system calls are patterned after
489 \fIreadv()\fR and \fIwritev()\fR,
490 the scatter-gather or "vectored"
491 versions of \fIread()\fR and \fIwrite()\fR.
492 .(b
493 \fC
494 .TS
495 tab(+);
496 l s s s.
497 cc = sendv( s, iov, iovlen, flags )
498 .T&
499 l l l.
500 +int+s:
501 +io_vector+iov;
502 +int+iovlen;
503 +unsigned int+*flags;
504 .TE
505 \fR
506 .)b
507 .(b
508 \fC
509 .TS
510 tab(+);
511 l s s s.
512 cc = recvv( s, iov, iovlen, flags )
513 .T&
514 l l l.
515 +int+s:
516 +io_vector+iov;
517 +int+iovlen;
518 +unsigned int+*flags;
519 .TE
520 \fR
521 .)b
522 .pp
523 The \fIiov\fR argument is an \fIio_vector\fR,
524 an array of pointers and lengths that
525 describe the areas from (or to) which the data will be gathered (or scattered).
526 The \fIiovlen\fR argument is an integer that tells how many parts are in
527 the io_vector.
528 The \fIflags\fR parameter serves several purposes.
529 The TP specification requires that TSDUs be unlimited in size.
530 System calls cannot pass unlimited amounts of data between the user
531 and the kernel, so
532 there cannot be a one-to-one correspondence between TSDUs and
533 system calls.
534 The \fIflags\fR
535 parameter is used to mark the end-of-TSDU on both sending and
536 receiving.
537 This way one TSDU can span several system calls.
538 When sending,
539 the user sets
540 this flag
541 to indicate that this request completes a TSDU.
542 When receiving,
543 TP sets this flag when
544 the end of a TSDU is reached.
545 In the latter case, the end of the data received by the transport user
546 with a given system call
547 coincides with the end of the TSDU
548 if
549 the TP has set the end-of-TSDU bit
550 in the \fIflags\fR parameter of the \fIrecv()\fR system call.
551 It is possible for the peer to send an empty TPDU with the end-of-TSDU
552 flag set, in which case the transport user
553 may receive zero octets with the end-of-TSDU flag set.
554 See the manual pages
555 \fIrecvv(2)\fR
556 and
557 \fIsendv(2)\fR
558 for details.
559 .pp
560 The \fIflags\fR parameter also serves to distinguish data transfer primitives
561 from expedited data transfer primitives.
562 The flag bit MSG_OOB is provided for "out of band data" in the
563 DoD Internet protocols. It is also used to provide the expedited data service
564 of the ISO protocols.
565 The transport layer will deliver one expedited datum (there will be a
566 one-to-one correspondence between expedited TSDUs and XPD TPDUs)
567 at a time.
568 The user must receive the datum before the transport
569 layer will accept more expedited data.
570 Each expedited datum my contain up to 16 octets.
571 .pp
572 .sh 1 "Disconnection"
573 .pp
574 The \fIclose\fR system call will disconnect any association
575 between two TP entities.
576 .(b
577 \fC
578 .TS
579 tab(+);
580 l s s s.
581 status = close( s )
582 .T&
583 l l l.
584 +int+s;
585 .TE
586 \fR
587 .)b
588 .pp
589 The argument \fIs\fR is a socket descriptor.
590 If a Unix user process terminates, Unix will close all files and
591 sockets associated with the process, which means all transport
592 connections associated with the process will be disconnected.
593 .sh 1 "Indications from the transport layer to the transport user"
594 .pp
595 While the above set of system calls allows you to establish
596 a connection, transfer data, and disconnect,
597 several elements of the transport service are not supported
598 by these system calls alone.
599 These system calls do not support
600 any way to indicate to the
601 to the transport user
602 the
603 presence of expedited data or
604 a disconnection initiated by the peer or by one of the
605 cooperating TP entities.
606 .pp
607 The Unix signal mechanism is used to provide these
608 service elements.
609 When an expedited data TSDU arrives, the TP interrupts
610 the user with a SIGURG signal ("urgent condition present on socket").
611 The user must have previously registered a procedure to handle
612 the signal by using the \fIsigvec()\fR system call or the
613 \fIsignal()\fR library routine provided for that purpose.
614 The signal handler takes the form
615 .(b
616 \fC
617 .TS
618 tab(+);
619 l s s s.
620 int sighandler( signal_number)
621 .T&
622 l l l.
623 +int+signal_number;
624 .TE
625 \fR
626 .)b
627 .pp
628 The \fIsignal_number\fR argument will be the well-known constant SIGURG.
629 There are two reasons for
630 the transport layer to issue
631 a SIGURG:
632 expedited data
633 are present or
634 disconnection was initiated by a transport entity or by the peer.
635 Should the user have more than one transport connection open,
636 another system call is used to determine to which socket(s)
637 the urgent condition applies.
638 This is the \fIselect()\fR system call, described below.
639 .pp
640 When the SIGURG indicates a disconnection, there may be
641 user data from the peer present.
642 TP
643 discards all queued normal data and expedited data.
644 It saves the disconnect data for the user to receive via the
645 \fIgetsockopt()\fR system call.
646 Unfortunately, the socket is already considered closed
647 by the kernel, so there is no way
648 for the user to read the incoming disconnect data, so receipt
649 of disconnect data is not supported.
650 .\"
651 .\"If the user does not receive the disconnect data before the
652 .\"reference timer expires, the data will be discarded and the
653 .\"socket will be closed.
654 .pp
655 Transport service users may use more than one transport
656 connection at a time.
657 The \fIselect()\fR system call facilitates this.
658 .(b
659 \fC
660 .TS
661 tab(+);
662 l s s s.
663 #include <sys/types.h>
664 +
665 nfound = select( num_to_scan, recvmask, sendmask,
666 +exceptmask, timeout )
667 .T&
668 l l l.
669 +int+nfound, num_to_scan;
670 +fd_set+*recvmask, *sendmask, *exceptmask;
671 +time+timeout;
672 .TE
673 \fR
674 .)b
675 .pp
676 This system call takes as parameters a set of masks
677 that specify a subset of the socket descriptors that are in
678 use by the user program.
679 \fISelect()\fR inspects the sockets to see if they have data
680 to be received, can service a send without blocking, or
681 have an exceptional condition pending, respectively.
682 The masks will be set upon return to indicate the socket descriptors
683 for which the respective conditions exist.
684 The \fInum_to_scan\fR argument limits the number of sockets that are
685 inspected.
686 The call will return within the amount of time given in the
687 \fItimeout\fR parameter, or, if the parameter is zero, \fIselect()\fR
688 will block indefinitely.
689 .\" FIGURE
690 .so figs/TS_primitives.nr
691 .pp
692 .CF
693 summarizes the mapping of the transport service primitives
694 to Unix facilities.