idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 36 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** There are 58 instances of lines with control characters in the document. ** The abstract seems to contain references ([SCTP]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 953: '...In other words the user MAY be able to...' RFC 2119 keyword, line 972: '... MAY override 'RTO.Max'. This valu...' RFC 2119 keyword, line 1097: '...e MSG_EOR clear. The user MUST finish...' RFC 2119 keyword, line 2171: '...P implementation SHOULD restrict the a...' RFC 2119 keyword, line 2182: '...vileged port, it MAY be permitted to a...' (1 more instance...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 708 has weird spacing: '...n. The value...' == Line 720 has weird spacing: '...er send and ...' == Line 928 has weird spacing: '...g_level cms...' == Line 984 has weird spacing: '...g_level cms...' == Line 1476 has weird spacing: '... msghdr msg;...' == (3 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 19, 2001) is 8289 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC 2553' is mentioned on line 578, but not defined ** Obsolete undefined reference: RFC 2553 (Obsoleted by RFC 3493) -- Looks like a reference, but probably isn't: '0' on line 1367 -- Looks like a reference, but probably isn't: '1' on line 2523 == Unused Reference: 'STEVENS' is defined on line 2254, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 2292 (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2553 (Obsoleted by RFC 3493) ** Obsolete normative reference: RFC 2960 (ref. 'SCTP') (Obsoleted by RFC 4960) -- Duplicate reference: RFC2292, mentioned in 'STEVENS', was also mentioned in 'RFC2292'. ** Obsolete normative reference: RFC 2292 (ref. 'STEVENS') (Obsoleted by RFC 3542) Summary: 16 errors (**), 0 flaws (~~), 10 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group R. R. Stewart 2 INTERNET-DRAFT Cisco 3 Q. Xie 4 L Yarroll 5 Motorola 6 J. Wood 7 K. Poon 8 Sun Microsystems 9 K. Fujita 10 NEC 12 expires in six months July 19, 2001 14 Sockets API Extensions for SCTP 15 17 Status of This Memo 19 This document is an Internet-Draft and is in full conformance with 20 all provisions of Section 10 of [RFC2026]. Internet-Drafts are 21 working documents of the Internet Engineering Task Force (IETF), its 22 areas, and its working groups. Note that other groups may also 23 distribute working documents as Internet-Drafts. 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 Abstract 33 This document describes a mapping of the Stream Control Transmission 34 Protocol [SCTP] into a sockets API. The benefits of this mapping 35 include compatibility for TCP applications, access to new SCTP 36 features and a consolidated error and event notification scheme. 38 Table of Contents 40 1. Introduction............................................ 3 41 2. Conventions............................................. 4 42 2.1 Data Types............................................ 4 43 3. UDP-style Interface..................................... 4 44 3.1 Basic Operation....................................... 4 45 3.1.1 socket() - UDP Style Syntax...................... 5 46 3.1.2 bind() - UDP Style Syntax........................ 5 47 3.1.3 listen() - UDP Style Syntax...................... 6 48 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax....... 7 49 3.1.5 close() - UDP Style Syntax....................... 8 50 3.2 Implicit Association Setup............................ 8 51 3.3 Non-blocking mode..................................... 9 52 4. TCP-style Interface.....................................10 53 4.1 Basic Operation.......................................10 54 4.1.1 socket() - TCP Style Syntax........................11 55 4.1.2 bind() - TCP Style Syntax..........................11 56 4.1.3 listen() - TCP Style Syntax........................12 57 4.1.4 accept() - TCP Style Syntax........................12 58 4.1.5 connect() - TCP Style Syntax.......................12 59 4.1.6 close() - TCP Style Syntax.........................13 60 4.1.7 shutdown() - TCP Style Syntax......................13 61 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax.........14 62 4.1.9 getsockname() .....................................15 63 4.1.10 getpeername() ....................................15 64 5. Data Structures..........................................16 65 5.1 The msghdr and cmsghdr Structures......................16 66 5.2 SCTP msg_control Structures............................17 67 5.2.1 SCTP Initiation Structure (SCTP_INIT)...............18 68 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV).....19 69 5.3 SCTP Events and Notifications..........................20 70 5.3.1 SCTP Notification Structure.........................21 71 5.3.1.1 SCTP_ASSOC_CHANGE................................22 72 5.3.1.2 SCTP_PEER_ADDR_CHANGE............................23 73 5.3.1.3 SCTP_REMOTE_ERROR................................25 74 5.3.1.4 SCTP_SEND_FAILE..................................26 75 5.3.1.5 SCTP_SHUTDOWN_EVENT..............................27 76 5.4 Ancillary Data Considerations and Semantics...........27 77 5.4.1 Multiple Items and Ordering........................27 78 5.4.2 Accessing and Manipulating Ancillary Data..........28 79 5.4.3 Control Message Buffer Sizing......................28 80 6. Common Operations for Both Styles.......................29 81 6.1 send(), recv(), sendto(), recvfrom()..................29 82 6.2 setsockopt(), getsockopt()............................30 83 6.3 read() and write()....................................30 84 7. Socket Options..........................................30 85 7.1 Read / Write Options..................................31 86 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO)...31 87 7.1.2 Association Retransmission Parameter 88 (SCTP_ASSOCRTXINFO)................................32 89 7.1.3 Initialization Parameters (SCTP_INITMSG)...........32 90 7.1.4 SO_LINGER..........................................33 91 7.1.5 SO_NODELAY.........................................33 92 7.1.6 SO_RCVBUF..........................................33 93 7.1.7 SO_SNDBUF..........................................33 94 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE)...33 95 7.1.9 SCTP_SET_PRIMARY_ADDR..............................34 96 7.1.10 SCTP_SET_PEER_PRIMARY_ADDR........................34 97 7.2 Read-Only Options.....................................34 98 7.2.1 Association Status (SCTP_STATUS)...................34 99 7.3. Ancillary Data and Notification Interest Options.....35 100 8. New Interfaces..........................................36 101 8.1 sctp_bindx()..........................................36 102 8.2 Branched-off Association, sctp_peeloff()..............37 103 8.3 sctp_getpaddrs()......................................38 104 8.4 sctp_freepaddrs().....................................38 105 8.5 sctp_getladdrs()......................................38 106 8.6 sctp_freeladdrs().....................................39 107 8.7 sctp_opt_info().......................................39 108 8.7.1 Peer Address Parameters............................39 109 8.7.2 Peer Address Information...........................40 111 9. Security Considerations.................................41 112 10. Acknowledgements......................................41 113 11. Authors' Addresses....................................41 114 12. References............................................42 115 Appendix A: TCP-style Code Example.........................42 116 Appendix B: UDP-style Code Example.........................47 118 1. Introduction 120 The sockets API has provided a standard mapping of the Internet 121 Protocol suite to many operating systems. Both TCP [RFC793] and UDP 122 [RFC768] have benefited from this standard representation and access 123 method across many diverse platforms. SCTP is a new protocol that 124 provides many of the characteristics of TCP but also incorporates 125 semantics more akin to UDP. This document defines a method to map 126 the existing sockets API for use with SCTP, providing both a base 127 for access to new features and compatibility so that most existing 128 TCP applications can be migrated to SCTP with few (if any) changes. 130 There are three basic design objectives: 132 1) Maintain consistency with existing sockets APIs: 134 We define a sockets mapping for SCTP that is consistent with other 135 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 136 IPv6). 138 2) Support a UDP-style interface 140 This set of semantics is similar to that defined for conntionless 141 protocols, such as UDP. It is more efficient than a TCP-like 142 connection-oriented interface in terms of exploring the new features 143 of SCTP. 145 Note that SCTP is connection-oriented in nature, and it does not 146 support broadcast or multicast communications, as UDP does. 148 3) Support a TCP-style interface 150 This interface supports the same basic semantics as sockets for 151 connection-oriented protocols, such as TCP. 153 The purpose of defining this interface is to allow existing 154 applications built on connnection-oriented protocols be ported to 155 use SCTP with very little effort, and developers familiar with those 156 semantics can easily adapt to SCTP. 158 Extensions will be added to this mapping to provide mechanisms to 159 exploit new features of SCTP. 161 Goals 2 and 3 are not compatible, so in this document we define two 162 modes of mapping, namely the UDP-style mapping and the TCP-style 163 mapping. These two modes share some common data structures and 164 operations, but will require the use of two different programming 165 models. 167 A mechanism is defined to convert a UDP-style SCTP socket into a 168 TCP-style socket. 170 Some of the SCTP mechanisms cannot be adequately mapped to existing 171 socket interface. In some cases, it is more desirable to have new 172 interface instead of using exisitng socket calls. This document 173 also describes those new interface. 175 2. Conventions 177 2.1 Data Types 179 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 180 1003.1g are used: uintN_t means an unsigned integer of exactly N 181 bits (e.g., uint16_t). We also assume the argument data types from 182 1003.1g when possible (e.g., the final argument to setsockopt() is a 183 size_t value). Whenever buffer sizes are specified, the POSIX 184 1003.1 size_t data type is used. 186 3. UDP-style Interface 188 The UDP-style interface has the following characteristics: 190 A) Outbound association setup is implicit. 192 B) Messages are delivered in complete messages (with one notable 193 exception). 195 3.1 Basic Operation 197 A typical server in this model uses the following socket calls in 198 sequence to prepare an endpoint for servicing requests: 200 1. socket() 201 2. bind() 202 3. listen() 203 4. recvmsg() 204 5. sendmsg() 205 6. close() 207 A typical client uses the following calls in sequence to setup an 208 association with a server to request services: 210 1. socket() 211 2. sendmsg() 212 3. recvmsg() 213 4. close() 215 In this model, by default, all the associations connected to the 216 endpoint are represented with a single socket. 218 If the server or client wishes to branch an existing association off 219 to a separate socket, it is required to call sctp_peeloff() and in 220 the parameter specifies one of the transport addresses of the 221 association. The sctp_peeloff() call will return a new socket which 222 can then be used with recv() and send() functions for message 223 passing. See Section 8.2 for more on branched-off associations. 225 Once an association is branched off to a separate socket, it becomes 226 completely separated from the original socket. All subsequent 227 control and data operations to that association must be done through 228 the new socket. For example, the close operation on the original 229 socket will not terminate any associations that have been branched 230 off to a different socket. 232 We will discuss the UDP-style socket calls in more details in the 233 following subsections. 235 3.1.1 socket() - UDP Style Syntax 237 Applications use socket() to create a socket descriptor to represent 238 an SCTP endpoint. 240 The syntax is, 242 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 244 or, 246 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 248 Here, SOCK_SEQPACKET indicates the creation of a UDP-style socket. 250 The first form creates an endpoint which can use only IPv4 251 addresses, while, the second form creates an endpoint which can use 252 both IPv6 and IPv4 mapped addresses. 254 3.1.2 bind() - UDP Style Syntax 256 Applications use bind() to specify which local address the SCTP 257 endpoint should associate itself with. 259 An SCTP endpoint can be associated with multiple addresses. To do 260 this, sctp_bindx() is introduced in section 8.1 to help applications 261 do the job of associating multiple addresses. 263 These addresses associated with a socket are the eligible transport 264 addresses for the endpoint to send and receive data. The endpoint 265 will also present these addresses to its peers during the 266 association initialization process, see [SCTP]. 268 After calling bind() or sctp_bindx(), if the endpoint wishes to 269 accept new associations on the socket, it must call listen() (see 270 section 3.1.3). 272 The syntax of bind() is, 273 ret = bind(int sd, struct sockaddr *addr, int addrlen); 275 sd - the socket descriptor returned by socket(). 276 addr - the address structure (struct sockaddr_in or struct 277 sockaddr_in6 [RFC 2553]), 278 addrlen - the size of the address structure. 280 If sd is an IPv4 socket, the address passed must be an IPv4 address. 281 If the sd is an IPv6 socket, the address passed can either be an 282 IPv4 or an IPv6 address. 284 Applications cannot call bind() multiple times to associate multiple 285 addresses to an endpoint. After the first call to bind(), all 286 subsequent calls will return an error. 288 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 289 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 290 operating system will associate the endpoint with an optimal address 291 set of the available interfaces. 293 If a bind() or sctp_bindx() is not called prior to a sendmsg() call 294 that initiates a new association, the system picks an ephemeral port 295 and will choose an address set equivalent to binding with a wildcard 296 address. One of those addresses will be the primary address for the 297 association. This automatically enables the multihoming capability 298 of SCTP. 300 3.1.3 listen() - UDP Style Syntax 302 By default, new associations are not accepted for UDP style sockets. 303 An application uses listen() to mark a socket as being able to 304 accept new associations. The syntax is, 306 int listen(int socket, int backlog); 308 socket - the socket descriptor of the endpoint. 309 backlog - ignored for UDP-style sockets. 311 Note that UDP-style socket consumers do not need to call accept to 312 retrieve new associations. Calling accept() on a UDP-style socket 313 should return EOPNOTSUPP. Rather, new associations are accepted 314 automatically, and notifications of the new associations are 315 delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if these 316 notifications are enabled). Clients will typically not call listen, 317 so that they can be assured that the only associations on the socket 318 will be ones they actively initiated. Server or peer-to-peer 319 sockets, on the other hand, will always accept new associations, so 320 a well-written application using server UDP-style sockets must be 321 prepared to handle new associations from unwanted peers. 323 Also note that the SCTP_ASSOC_CHANGE event provides the association 324 ID for a new association, so if applications wish to use the 325 association ID as input to other socket calls, they should ensure 326 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 327 default). 329 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax 331 An application uses sendmsg() and recvmsg() call to transmit data to 332 and receive data from its peer. 334 ssize_t sendmsg(int socket, const struct msghdr *message, 335 int flags); 337 ssize_t recvmsg(int socket, struct msghdr *message, 338 int flags); 340 socket - the socket descriptor of the endpoint. 341 message - pointer to the msghdr structure which contains a single 342 user message and possibly some ancillary data. 344 See Section 5 for complete description of the data 345 structures. 347 flags - No new flags are defined for SCTP at this level. See 348 Section 5 for SCTP-specific flags used in the msghdr 349 structure. 351 As we will see in Section 5, along with the user data, the ancillary 352 data field is used to carry the sctp_sndrcvinfo and/or the 353 sctp_initmsg structures to perform various SCTP functions including 354 specifying options for sending each user message. Those options, 355 depending on whether sending or receiving, include stream number, 356 stream sequence number, TOS, various flags, context and payload 357 protocol Id, etc. 359 When sending user data with sendmsg(), the msg_name field in msghdr 360 structure will be filled with one of the transport addresses of the 361 intended receiver. If there is no association existing between the 362 sender and the intended receiver, the sender's SCTP stack will set 363 up a new association and then send the user data (see Section 3.2 364 for more on implicit association setup). 366 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 367 be delivered if that notification has been enabled, and no more data 368 can be sent to that association. Any attempt to send more data will 369 cause sendmsg() to return with an ESHUTDOWN error. Note that the 370 socket is still open for reading at this point so it is possible to 371 retrieve notifications. 373 When receiving a user message with recvmsg(), the msg_name field in 374 msghdr structure will be populated with the source transport address 375 of the user data. The caller of recvmsg() can use this address 376 information to determine to which association the received user 377 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 378 applications must use the peer transport address provided in the 379 msg_name field by recvmsg() to perform correlation to an 380 association, since they will not have the association ID. 382 If all data in a single message has been delivered, MSG_EOR will be 383 set in the msg_flags field of the msghdr structure (see section 384 5.1). 386 If the application does not provide enough buffer space to 387 completely receive a data message, MSG_EOR will not be set in 388 msg_flags. Successive reads will consume more of the same message 389 until the entire message has been delivered, and MSG_EOR will be 390 set. 392 If the SCTP stack is running low on buffers, it may partially 393 deliver a message. In this case, MSG_EOR will not be set, and more 394 calls to recvmsg() will be necessary to completely consume the 395 message. Only one message at a time can be partially delivered. 397 Note, if the socket is a branched-off socket that only represents 398 one association (see Section 3.1), the msg_name field is not used 399 when sending data (i.e., ignored by the SCTP stack). 401 3.1.5 close() - UDP Style Syntax 403 Applications use close() to perform graceful shutdown (as described 404 in Section 10.1 of [SCTP]) on ALL the associations currently 405 represented by a UDP-style socket. 407 The syntax is 409 ret = close(int sd); 411 sd - the socket descriptor of the associations to be closed. 413 To gracefully shutdown a specific association represented by the 414 UDP-style socket, an application should use the sendmsg() call, 415 passing no user data, but including the MSG_EOF flag in the 416 ancillary data (see Section 5.2.2). 418 If sd in the close() call is a branched-off socket representing only 419 one association, the shutdown is performed on that association only. 421 3.2 Implicit Association Setup 423 Once all bind() calls are complete on a UDP-style socket, the 424 application can begin sending and receiving data using the 425 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 426 through any explicit association setup procedures (i.e., no 427 connect() calls required). 429 Whenever sendmsg() or sendto() is called and the SCTP stack at the 430 sender finds that there is no association existing between the 431 sender and the intended receiver (identified by the address passed 432 either in the msg_name field of msghdr structure in the sendmsg() 433 call or the dest_addr field in the sendto() call), the SCTP stack 434 will automatically setup an association to the intended receiver. 436 Upon the successful association setup a COMMUNICATION_UP 437 notification will be dispatched to the socket at both the sender and 438 receiver side. This notification can be read by the recvmsg() system 439 call (see Section 3.1.3). 441 Note, if the SCTP stack at the sender side supports bundling, the 442 first user message may be bundled with the COOKIE ECHO message 443 [SCTP]. 445 When the SCTP stack sets up a new association implicitly, it first 446 consults the sctp_initmsg structure, which is passed along within 447 the ancillary data in the sendmsg() call (see Section 5.2.1 for 448 details of the data structures), for any special options to be used 449 on the new association. 451 If this information is not present in the sendmsg() call, or if the 452 implicit association setup is triggered by a sendto() call, the 453 default association initialization parameters will be used. These 454 default association parameters may be set with respective 455 setsockopt() calls or be left to the system defaults. 457 Implicit association setup cannot be initiated by send()/recv() 458 calls. 460 3.3 Non-blocking mode 462 Some SCTP users might want to avoid blocking when they call 463 socket interface function. 465 Whenever the user which want to avoid blocking must call select() 466 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and 467 check the socket status is writable or readable. If the socket 468 status isn't writeable or readable, the user should not call 469 sendmsg()/sendto() and recvmsg()/recvfrom(). 471 Once all bind() calls are complete on a UDP-style socket, the 472 application must set the non-blocking option by a fcntl() (such as 473 O_NONBLOCK). After which the sendmsg() function returns 474 immediately, and the success or failure of the data message (and 475 possible SCTP_INITMSG parameters) will be signalled by the 476 SCTP_ASSOC_CHANGE event with COMMUNICATION_UP or 477 CANT_START_ASSOC. If user data could not be sent (due to a 478 CANT_START_ASSOC), the sender will also receive a SCTP_SEND_FAILED 479 event. Those event(s) can be received by the user calling of 480 recvmsg(). A server (having called listen()) is also notified of an 481 association up event by the reception of a SCTP_ASSOC_CHANGE with 482 COMMUNICATION_UP via the calling of recvmsg() and possibly the 483 reception of the first data message. 485 In order to shutdown the association gracefully, the user must call 486 sendmsg() with no data and with the MSG_EOF flag set. The function 487 returns immediately, and completion of the graceful shutdown is 488 indicated by an SCTP_ASSOC_CHANGE notification of type 489 SHUTDOWN_COMPLETE (see section 5.3.1.1). 491 4. TCP-style Interface 493 The goal of this model is to follow as closely as possible the 494 current practice of using the sockets interface for a connection 495 oriented protocol, such as TCP. This model enables existing 496 applications using connection oriented protocols to be ported to 497 SCTP with very little effort. 499 Note that some new SCTP features and some new SCTP socket options 500 can only be utilized through the use of sendmsg() and recvmsg() 501 calls, see Section 4.1.8. 503 4.1 Basic Operation 505 A typical server in TCP-style model uses the following system call 506 sequence to prepare an SCTP endpoint for servicing requests: 508 1. socket() 509 2. bind() 510 3. listen() 511 4. accept() 513 The accept() call blocks until a new association is set up. It 514 returns with a new socket descriptor. The server then uses the new 515 socket descriptor to communicate with the client, using recv() and 516 send() calls to get requests and send back responses. 518 Then it calls 520 5. close() 522 to terminate the association. 524 A typical client uses the following system call sequence to setup an 525 association with a server to request services: 527 1. socket() 528 2. connect() 530 After returning from connect(), the client uses send() and recv() 531 calls to send out requests and receive responses from the server. 533 The client calls 535 3. close() 537 to terminate this association when done. 539 4.1.1 socket() - TCP Style Syntax 541 Applications calls socket() to create a socket descriptor to 542 represent an SCTP endpoint. 544 The syntax is: 546 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 548 or, 550 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 552 Here, SOCK_STREAM indicates the creation of a TCP-style socket. 554 The first form creates an endpoint which can use only IPv4 555 addresses, while the second form creates an endpoint which can use 556 both IPv6 and mapped IPv4 addresses. 558 4.1.2 bind() - TCP Style Syntax 560 Applications use bind() to pass an address to be associated with an 561 SCTP endpoint to the system. bind() allows only either a single 562 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 563 endpoint can be associated with multiple addresses. To do this, 564 sctp_bindx() is introduced in section 8.1 to help applications do 565 the job of associating multiple addresses. 567 These addresses associated with a socket are the eligible transport 568 addresses for the endpoint to send and receive data. The endpoint 569 will also present these addresses to its peers during the 570 association initialization process, see [SCTP]. 572 The syntax is: 574 int bind(int sd, struct sockaddr *addr, int addrlen); 576 sd - the socket descriptor returned by socket() call. 577 addr - the address structure (either struct sockaddr_in or struct 578 sockaddr_in6 defined in [RFC 2553]). 579 addrlen - the size of the address structure. 581 If sd is an IPv4 socket, the address passed must be an IPv4 address. 582 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 583 either be an IPv4 or an IPv6 address. 585 Applications cannot call bind() multiple times to associate multiple 586 addresses to the endpoint. After the first call to bind(), all 587 subsequent calls will return an error. 589 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 590 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 591 operating system will associate the endpoint with an optimal address 592 set of the available interfaces. 594 If a bind() or sctp_bindx() is not called prior to the connect() 595 call, the system picks an ephemeral port and will choose an address 596 set equivalant to binding with a wildcard address. One of those 597 addresses will be the primary address for the association. This 598 automatically enables the multihoming capability of SCTP. 600 The completion of this bind() process does not ready the SCTP 601 endpoint to accept inbound SCTP association requests. Until a 602 listen() system call, described below, is performed on the socket, 603 the SCTP endpoint will promptly reject an inbound SCTP INIT request 604 with an SCTP ABORT. 606 4.1.3 listen() - TCP Style Syntax 608 Applications use listen() to ready the SCTP endpoint for accepting 609 inbound associations. 611 The syntax is: 613 int listen(int sd, int backlog); 615 sd - the socket descriptor of the SCTP endpoint. 616 backlog - this specifies the max number of outstanding associations 617 allowed in the socket's accept queue. These are the 618 associations that have finished the four-way initiation 619 handshake (see Section 5 of [SCTP]) and are in the 620 ESTABLISHED state. 622 4.1.4 accept() - TCP Style Syntax 624 Applications use accept() call to remove an established SCTP 625 association from the accept queue of the endpoint. A new socket 626 descriptor will be returned from accept() to represent the newly 627 formed association. 629 The syntax is: 631 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 633 new_sd - the socket descriptor for the newly formed association. 634 sd - the listening socket descriptor. 635 addr - on return, will contain the primary address of the peer 636 endpoint. 637 addrlen - on return, will contain the size of addr. 639 4.1.5 connect() - TCP Style Syntax 641 Applications use connect() to initiate an association to a peer. 643 The syntax is 645 int connect(int sd, const struct sockaddr *addr, int addrlen); 647 sd - the socket descriptor of the endpoint. 648 addr - the peer's address. 649 addrlen - the size of the address. 651 This operation corresponds to the ASSOCIATE primitive described in 652 section 10.1 of [SCTP]. 654 By default, the new association created has only one outbound 655 stream. The SCTP_INITMSG option described in Section 7.1.3 should be 656 used before connecting to change the number of outbound streams. 658 If a bind() or sctp_bindx() is not called prior to the connect() 659 call, the system picks an ephemeral port and will choose an address 660 set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 661 and IPv6 socket respectively. One of those addresses will be the 662 primary address for the association. This automatically enables the 663 multihoming capability of SCTP. 665 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 666 during the association set up phase. If an application wants to do 667 this, it cannot use connect() call. Instead, it should use sendto() 668 or sendmsg() to initiate an association. If it uses sendto() and it 669 wants to change initialization behavior, it needs to use the 670 SCTP_INITMSG socket option before calling sendto(). Or it can use 671 SCTP_INIT type sendmsg() to initiate an association without doing 672 the setsockopt(). 674 SCTP does not support half close semantics. This means that unlike 675 T/TCP, MSG_EOF should not be set in the flags parameter when calling 676 sendto() or sendmsg() when the call is used to initiate a 677 connection. MSG_EOF is not an acceptable flag with SCTP socket. 679 4.1.6 close() - TCP Style Syntax 681 Applications use close() to gracefully close down an association. 683 The syntax is: 685 int close(int sd); 687 sd - the socket descriptor of the association to be closed. 689 After an application calls close() on a socket descriptor, no 690 further socket operations will suceed on that descriptor. 692 4.1.7 shutdown() - TCP Style Syntax 694 SCTP differs from TCP in that it does not have half closed 695 semantics. Hence the shutdown() call for SCTP is an approximation 696 of the TCP shutdown() call, and solves some different problems. 697 Full TCP-compatibility is not provided, so developers porting TCP 698 applications to SCTP may need to recode sections that use 699 shutdown(). (Note that it is possible to achieve the same results 700 as half close in SCTP using SCTP streams.) 702 The syntax is: 704 int shutdown(int socket, int how); 706 sd - the socket descriptor of the association to be closed. 708 how - Specifies the type of shutdown. The values are 709 as follows: 711 SHUT_RD 712 Disables further receive operations. No SCTP 713 protocol action is taken. 715 SHUT_WR 716 Disables further send operations, and initiates 717 the SCTP shutdown sequence. 719 SHUT_RDWR 720 Disables further send and receive operations 721 and initiates the SCTP shutdown sequence. 723 The major difference between SCTP and TCP shutdown() is that SCTP 724 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 725 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 726 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 727 the SCTP association while still leaving the socket descriptor open, 728 so that the caller can receive back any data SCTP was unable to 729 deliver (see section 5.3.1.4 for more information). 731 To perform the ABORT operation described in [SCTP] section 10.1, an 732 application can use the socket option SO_LINGER. It is described in 733 section 7.1.4. 735 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax 737 With a TCP-style socket, the application can also use sendmsg() and 738 recvmsg() to transmit data to and receive data from its peer. The 739 semantics is similar to those used in the UDP-style model (section 740 3.1.3), with the following differences: 742 1) When sending, the msg_name field in the msghdr is not used to 743 specify the intended receiver, rather it is used to indicate a 744 different peer address if the sender does not want to send the 745 message over the primary address of the receiver. If the transport 746 address given is not part of the current association, the data will 747 not be sent and a SCTP_SEND_FAILED event will be delivered to the 748 application if send failure events are enabled. 750 When receiving, if a message is not received from the primary 751 address, the SCTP stack will fill in the msg_name field on return so 752 that the application can retrieve the source address information of 753 the received message. 755 2) An application must use close() to gracefully shutdown an 756 association, or use SO_LINGER option with close() to abort an 757 association. It must not use the MSG_ABORT or MSG_EOF flag in 758 sendmsg(). The system returns an error if an application tries to 759 do so. 761 4.1.9 getsockname() 763 Applications use getsockname() to retrieve the locally-bound socket 764 address of the specified socket. The is especially useful if the 765 caller let SCTP chose a local port. This call is for TCP 766 compatibility, and is not multihomed. It does not work with 767 UDP-style sockets. See section 8.5 for a multihomed/UDP-sockets 768 version of the call. 770 The syntax is: 772 int getsockname(int socket, struct sockaddr *address, 773 socklen_t *len); 775 sd - the socket descriptor to be queried. 777 address - On return, one locally bound address (chosen by 778 the SCTP stack) is stored in this buffer. If the 779 socket is an IPv4 socket, the address will be IPv4. 780 If the socket is an IPv6 socket, the address will 781 be either an IPv6 or mapped IPv4 address. 783 len - The caller should set the length of address here. 784 On return, this is set to the length of the returned 785 address. 787 If the actual length of the address is greater than the length of 788 the supplied sockaddr structure, the stored address will be 789 truncated. 791 If the socket has not been bound to a local name, the value stored 792 in the object pointed to by address is unspecified. 794 4.1.10 getpeername() 796 Applications use getpeername() to retrieve the primary socket 797 address of the peer. This call is for TCP compatibility, and is not 798 multihomed.It does not work with UDP-style sockets. See section 8.3 799 for a multihomed/UDP-sockets version of the call. 801 The syntax is: 803 int getpeername(int socket, struct sockaddr *address, 804 socklen_t *len); 806 sd - the socket descriptor to be queried. 808 address - On return, the peer primary address is stored in 809 this buffer. If the socket is an IPv4 socket, the 810 address will be IPv4. If the socket is an IPv6 socket, 811 the address will be either an IPv6 or mapped IPv4 812 address. 814 len - The caller should set the length of address here. 815 On return, this is set to the length of the returned 816 address. 818 If the actual length of the address is greater than the length of 819 the supplied sockaddr structure, the stored address will be 820 truncated. 822 5. Data Structures 824 We discuss in this section important data structures which are 825 specific to SCTP and are used with sendmsg() and recvmsg() calls to 826 control SCTP endpoint operations and to access ancillary 827 information and notifications. 829 5.1 The msghdr and cmsghdr Structures 831 The msghdr structure used in the sendmsg() and recvmsg() calls, as 832 well as the ancillary data carried in the structure, is the key for 833 the application to set and get various control information from the 834 SCTP endpoint. 836 The msghdr and the related cmsghdr structures are defined and 837 discussed in details in [RFC2292]. Here we will cite their 838 definitions from [RFC2292]. 840 The msghdr structure: 842 struct msghdr { 843 void *msg_name; /* ptr to socket address structure */ 844 socklen_t msg_namelen; /* size of socket address structure */ 845 struct iovec *msg_iov; /* scatter/gather array */ 846 size_t msg_iovlen; /* # elements in msg_iov */ 847 void *msg_control; /* ancillary data */ 848 socklen_t msg_controllen; /* ancillary data buffer length */ 849 int msg_flags; /* flags on received message */ 850 }; 852 The cmsghdr structure: 854 struct cmsghdr { 855 socklen_t cmsg_len; /* #bytes, including this header */ 856 int cmsg_level; /* originating protocol */ 857 int cmsg_type; /* protocol-specific type */ 858 /* followed by unsigned char cmsg_data[]; */ 859 }; 861 In the msghdr structure, the usage of msg_name has been discussed in 862 previous sections (see Sections 3.1.3 and 4.1.8). 864 The scatter/gather buffers, or I/O vectors (pointed to by the 865 msg_iov field) are treated as a single SCTP data chunk, rather than 866 multiple chunks, for both sendmsg() and recvmsg(). 868 The msg_flags are not used when sending a message with sendmsg(). 870 If a notification has arrived, recvmsg() will return the 871 notification with the MSG_NOTIFICATION flag set in msg_flags. If the 872 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 873 section 5.3 for more information about notifications. 875 If all portions of a data frame or notification have been read, 876 recvmsg() will return with MSG_EOR set in msg_flags. 878 5.2 SCTP msg_control Structures 880 A key element of all SCTP-specific socket extensions is the use of 881 ancillary data to specify and access SCTP-specific data via the 882 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 883 Fine-grained control over initialization and sending parameters are 884 handled with ancillary data. 886 Each ancillary data item is preceeded by a struct cmsghdr (see 887 Section 5.1), which defines the function and purpose of the data 888 contained in in the cmsg_data[] member. 890 There are two kinds of ancillary data used by SCTP: initialization 891 data, and, header information (SNDRCV). Initialization data 892 (UDP-style only) sets protocol parameters for new associations. 893 Section 5.2.1 provides more details. Header information can set or 894 report parameters on individual messages in a stream. See section 895 5.2.2 for how to use SNDRCV ancillary data. 897 By default on a TCP-style socket, SCTP will pass no ancillary data; 898 on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and 899 SCTP_ASSOC_CHANGE information. Specific ancillary data items can be 900 enabled with socket options defined for SCTP; see section 7.3. 902 Note that all ancillary types are fixed length; see section 5.4 for 903 further discussion on this. These data structures use struct 904 sockaddr_storage (defined in [RFC2553]) as a portable, fixed length 905 address format. 907 Other protocols may also provide ancillary data to the socket layer 908 consumer. These ancillary data items from other protocols may 909 intermingle with SCTP data. For example, the IPv6 socket API 910 definitions ([RFC2292] and [RFC2553]) define a number of ancillary 911 data items. If a socket API consumer enables delivery of both SCTP 912 and IPv6 ancillary data, they both may appear in the same 913 msg_control buffer in any order. An application may thus need to 914 handle other types of ancillary data besides that passed by SCTP. 916 The sockets application must provide a buffer large enough to 917 accomodate all ancillary data provided via recvmsg(). If the buffer 918 is not large enough, the ancillary data will be truncated and the 919 msghdr's msg_flags will include MSG_CTRUNC. 921 5.2.1 SCTP Initiation Structure (SCTP_INIT) 923 This cmsghdr structure provides information for initializing new 924 SCTP associations with sendmsg(). The SCTP_INITMSG socket option 925 uses this same data structure. This structure is not used for 926 recvmsg(). 928 cmsg_level cmsg_type cmsg_data[] 929 ------------ ------------ ---------------------- 930 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 932 Here is the definition of the sctp_initmsg structure: 934 struct sctp_initmsg { 935 uint16_t sinit_num_ostreams; 936 uint16_t sinit_max_instreams; 937 uint16_t sinit_max_attempts; 938 uint16_t sinit_max_init_timeo; 939 }; 941 sinit_num_ostreams: 16 bits (unsigned integer) 943 This is an integer number representing the number of streams that 944 the application wishes to be able to send to. This number is 945 confirmed in the COMMUNICATION_UP notification and must be verified 946 since it is a negotiated number with the remote endpoint. The 947 default value of 0 indicates to use the endpoint default value. 949 sinit_max_instreams: 16 bits (unsigned integer) 951 This value represents the maximum number of inbound streams the 952 application is prepared to support. This value is bounded by the 953 actual implementation. In other words the user MAY be able to 954 support more streams than the Operating System. In such a case, the 955 Operating System limit overrides the value requested by the 956 user. The default value of 0 indicates to use the endpoint's default 957 value. 959 sinit_max_attempts: 16 bits (unsigned integer) 961 This integer specifies how many attempts the SCTP endpoint should 962 make at resending the INIT. This value overrides the system SCTP 963 'Max.Init.Retransmits' value. The default value of 0 indicates to 964 use the endpoint's default value. This is normally set to the 965 system's default 'Max.Init.Retransmit' value. 967 sinit_max_init_timeo: 16 bits (unsigned integer) 969 This value represents the largest Time-Out or RTO value to use in 970 attempting a INIT. Normally the 'RTO.Max' is used to limit the 971 doubling of the RTO upon timeout. For the INIT message this value 972 MAY override 'RTO.Max'. This value MUST NOT influence 'RTO.Max' 973 during data transmission and is only used to bound the initial setup 974 time. A default value of 0 indicates to use the endpoint's default 975 value. This is normally set to the system's 'RTO.Max' value (60 976 seconds). 978 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 980 This cmsghdr structure specifies SCTP options for sendmsg() and 981 describes SCTP header information about a received message through 982 recvmsg(). 984 cmsg_level cmsg_type cmsg_data[] 985 ------------ ------------ ---------------------- 986 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 988 Here is the defintion of sctp_sndrcvinfo: 990 struct sctp_sndrcvinfo { 991 uint16_t sinfo_stream; 992 uint16_t sinfo_ssn; 993 uint16_t sinfo_flags; 994 uint32_t sinfo_ppid; 995 uint32_t sinfo_context; 996 sctp_assoc_t sinfo_assoc_id; 997 }; 999 sinfo_stream: 16 bits (unsigned integer) 1001 For recvmsg() the SCTP stack places the message's stream number in 1002 this value. For sendmsg() this value holds the stream number that 1003 the application wishes to send this message to. If a sender 1004 specifies an invalid stream number an error indication is returned 1005 and the call fails. 1007 sinfo_ssn: 16 bits (unsigned integer) 1009 For recvmsg() this value contains the stream sequence number that 1010 the remote endpoint placed in the DATA chunk. For fragmented 1011 messages this is the same number for all deliveries of the message 1012 (if more than one recvmsg() is needed to read the message). The 1013 sendmsg() call will ignore this parameter. 1015 sinfo_ppid:32 bits (unsigned integer) 1017 This value in sendmsg() is an opaque unsigned value that is passed 1018 to the remote end in each user message. In recvmsg() this value is 1019 the same information that was passed by the upper layer in the peer 1020 application. Please note that byte order issues are NOT accounted 1021 for and this information is passed opaquely by the SCTP stack from 1022 one end to the other. 1024 sinfo_context:32 bits (unsigned integer) 1026 This value is an opaque 32 bit context datum that is used in the 1027 sendmsg() function. This value is passed back to the upper layer if 1028 a error occurs on the send of a message and is retrieved with each 1029 undelivered message (Note: if a endpoint has done multple sends, all 1030 of which fail, multiple different sinfo_context values will be 1031 returned. One with each user data message). 1033 sinfo_flags: 16 bits (unsigned integer) 1035 This field may contain any of the following flags and is composed of 1036 a bitwise OR of these values. 1038 recvmsg() flags: 1040 MSG_UNORDERED - This flag is present when the message was sent 1041 non-ordered. 1043 sendmsg() flags: 1045 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1046 message. If this flag is clear the datagram is 1047 considered an ordered send. 1049 MSG_ADDR_OVER - This flag, in the UDP model, requests the SCTP 1050 stack to override the primary destination address 1051 with the address found with the sendto/sendmsg 1052 call. 1054 MSG_ABORT - Setting this flag causes the specified association 1055 to abort by sending an ABORT message to the peer 1056 (UDP-style only). 1058 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1059 procedures on the specified association. Graceful 1060 shutdown assures that all data enqueued by both 1061 endpoints is successfully transmitted before closing 1062 the association (UDP-style only). 1064 sinfo_assoc_id: sizeof (sctp_assoc_t) 1066 The association handle field, sinfo_assoc_id, holds the identifier 1067 for the association announced in the COMMUNICATION_UP notification. 1068 All notifications for a given association have the same identifier. 1069 Ignored for TCP-style sockets. 1071 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1073 5.3 SCTP Events and Notifications 1075 An SCTP application may need to understand and process events and 1076 errors that happen on the SCTP stack. These events include network 1077 status changes, association startups, remote operational errors and 1078 undeliverable messages. All of these can be essential for the 1079 application. 1081 When an SCTP application layer does a recvmsg() the message read is 1082 normally a data message from a peer endpoint. If the application 1083 wishes to have the SCTP stack deliver notifications of non-data 1084 events, it sets the appropriate socket option for the notifications 1085 it wants. See section 7.3 for these socket options. When a 1086 notification arrives, recvmsg() returns the notification in the 1087 application-supplied data buffer via msg_iov, and sets 1088 MSG_NOTIFICATION in msg_flags. 1090 This section details the notification structures. Every 1091 notification structure carries some common fields which provides 1092 general information. 1094 A recvmsg() call will return only one notification at a time. Just 1095 as when reading normal data, it may return part of a notification if 1096 the msg_iov buffer is not large enough. If a single read is not 1097 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1098 reading the notification before subsequent data can arrive. 1100 5.3.1 SCTP Notification Structure 1102 The notification structure is defined as the union of all 1103 notification types. 1105 union sctp_notification { 1106 uint16_t sn_type; /* Notification type. */ 1107 struct sctp_assoc_change; 1108 struct sctp_paddr_change; 1109 struct sctp_remote_error; 1110 struct sctp_shutdown_event; 1111 }; 1113 sn_type: sizeof (uint16_t) 1115 The following table describes the SCTP notification and event types 1116 for the field sn_type. 1118 sn_type Description 1119 --------- --------------------------- 1121 SCTP_ASSOC_CHANGE This tag indicates that an 1122 association has either been 1123 opened or closed. Refer to 1124 5.3.1.1 for details. 1126 SCTP_PEER_ADDR_CHANGE This tag indicates that an 1127 address that is part of an existing 1128 association has experienced a 1129 change of state (e.g. a failure 1130 or return to service of the 1131 reachability of a endpoint 1132 via a specific transport 1133 address). Please see 5.3.1.2 1134 for data structure details. 1136 SCTP_REMOTE_ERROR The attached error message 1137 is an Operational Error received from 1138 the remote peer. It includes the complete 1139 TLV sent by the remote endpoint. 1140 See section 5.3.1.3 for the detailed format. 1142 SCTP_SEND_FAILED The attached datagram 1143 could not be sent to the remote endpoint. 1144 This structure includes the 1145 original SCTP_SNDRCVINFO 1146 that was used in sending this 1147 message i.e. this structure 1148 uses the sctp_sndrecvinfo per 1149 section 5.3.1.4. 1151 SCTP_SHUTDOWN_EVENT The peer has sent a SHUTDOWN. No further 1152 data should be sent on this socket. 1154 5.3.1.1 SCTP_ASSOC_CHANGE 1156 Communication notifications inform the ULP that an SCTP association 1157 has either begun or ended. The identifier for a new association is 1158 provided by this notificaion. The notification information has the 1159 following format: 1161 struct sctp_assoc_change { 1162 uint16_t sac_type; 1163 uint16_t sac_flags; 1164 uint32_t sac_length; 1165 uint16_t sac_state; 1166 uint16_t sac_error; 1167 uint16_t sac_outbound_streams; 1168 uint16_t sac_inbound_streams; 1169 sctp_assoc_t sac_assoc_id; 1170 }; 1172 sac_type: 1174 It should be SCTP_ASSOC_CHANGE. 1176 sac_flags: 16 bits (unsigned integer) 1178 Currently unused. 1180 sac_length: sizeof (uint32_t) 1182 This field is the total length of the notification data, including 1183 the notification header. 1185 sac_state: 32 bits (signed integer) 1187 This field holds one of a number of values that communicate the 1188 event that happened to the association. They include: 1190 Event Name Description 1191 ---------------- --------------- 1192 COMMUNICATION_UP A new association is now ready 1193 and data may be exchanged with this 1194 peer. 1196 COMMUNICATION_LOST The association has failed. The association 1197 is now in the closed state. If SEND FAILED 1198 notifications are turned on, a COMMUNICATION_LOST 1199 is followed by a series of SCTP_SEND_FAILED 1200 events, one for each outstanding message. 1202 RESTART SCTP has detected that the peer has restarted. 1204 SHUTDOWN_COMPLETE The association has gracefully closed. 1206 CANT_START_ASSOC The association failed to setup. If non blocking 1207 mode is set and data was sent (in the udp mode), 1208 a CANT_START_ASSOC is followed by a series of 1209 SCTP_SEND_FAILED events, one for each outstanding 1210 message. 1212 sac_error: 32 bits (signed integer) 1214 If the state was reached due to a error condition (e.g. 1215 COMMUNICATION_LOST) any relevant error information is available in 1216 this field. This corresponds to the protocol error codes defined in 1217 [SCTP]. 1219 sac_outbound_streams: 16 bits (unsigned integer) 1220 sac_inbound_streams: 16 bits (unsigned integer) 1222 The maximum number of streams allowed in each direction are 1223 available in sac_outbound_streams and sac_inbound streams. 1225 sac_assoc_id: sizeof (sctp_assoc_t) 1227 The association id field, holds the identifier for the association. 1228 All notifications for a given association have the same association 1229 identifier. For TCP style socket, this field is ignored. 1231 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1233 When a destination address on a multi-homed peer encounters a change 1234 an interface details event is sent. The information has the 1235 following structure: 1237 struct sctp_paddr_change{ 1238 uint16_t spc_type; 1239 uint16_t spc_flags; 1240 uint32_t spc_length; 1241 struct sockaddr_storage spc_aaddr; 1242 int spc_state; 1243 int spc_error; 1244 sctp_assoc_t spc_assoc_id; 1245 } 1247 spc_type: 1249 It should be SCTP_PEER_ADDR_CHANGE. 1251 spc_flags: 16 bits (unsigned integer) 1253 Currently unused. 1255 spc_length: sizeof (uint32_t) 1257 This field is the total length of the notification data, including 1258 the notification header. 1260 spc_aaddr: sizeof (struct sockaddr_storage) 1262 The affected address field, holds the remote peer's address that is 1263 encountering the change of state. 1265 spc_state: 32 bits (signed integer) 1267 This field holds one of a number of values that communicate the 1268 event that happened to the address. They include: 1270 Event Name Description 1271 ---------------- --------------- 1272 ADDRESS_AVAILABLE This address is now reachable. 1274 ADDRESS_UNREACHABLE The address specified can no 1275 longer be reached. Any data sent 1276 to this address is rerouted to an 1277 alternate until this address becomes 1278 reachable. 1280 ADDRESS_REMOVED The address is no longer part of 1281 the association. 1283 ADDRESS_ADDED The address is now part of the 1284 association. 1286 ADDRESS_MADE_PRIM This address has now been made 1287 to be the primary destination address. 1289 spc_error: 32 bits (signed integer) 1291 If the state was reached due to any error condition (e.g. 1292 ADDRESS_UNREACHABLE) any relevant error information is available in 1293 this field. 1295 spc_assoc_id: sizeof (sctp_assoc_t) 1297 The association id field, holds the identifier for the association. 1299 All notifications for a given association have the same association 1300 identifier. For TCP style socket, this field is ignored. 1302 5.3.1.3 SCTP_REMOTE_ERROR 1304 A remote peer may send an Operational Error message to its peer. 1305 This message indicates a variety of error conditions on an 1306 association. The entire error TLV as it appears on the wire is 1307 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1308 specification [SCTP] and any extensions for a list of possible 1309 error formats. SCTP error TLVs have the format: 1311 struct sctp_remote_error { 1312 uint16_t sre_type; 1313 uint16_t sre_flags; 1314 uint32_t sre_length; 1315 uint16_t sre_error; 1316 uint16_t sre_len; 1317 sctp_assoc_t sre_assoc_id; 1318 uint8_t sre_data[0]; 1319 }; 1321 sre_type: 1323 It should be SCTP_REMOTE_ERROR. 1325 sre_flags: 16 bits (unsigned integer) 1327 Currently unused. 1329 sre_length: sizeof (uint32_t) 1331 This field is the total length of the notification data, including 1332 the notification header. 1334 sre_error: 16 bits (unsigned integer) 1336 This value represents one of the Operational Error causes defined in 1337 the SCTP specification, in network byte order. 1339 sre_len: 16 bits (unsigned integer) 1341 This value represents the length of the operational error payload in 1342 plus the size of sre_error and sre_len in network byte order. 1344 sre_assoc_id: sizeof (sctp_assoc_t) 1346 The association id field, holds the identifier for the association. 1347 All notifications for a given association have the same association 1348 identifier. For TCP style socket, this field is ignored. 1350 sre_data: variable 1352 This contains the payload of the operational error as defined in the 1353 SCTP specification [SCTP] section 3.3.10. 1355 5.3.1.4 SCTP_SEND_FAILED 1357 If SCTP cannot deliver a message it may return the message as a 1358 notification. 1360 struct sctp_send_failed { 1361 uint16_t ssf_type; 1362 uint16_t ssf_flags; 1363 uint32_t ssf_length; 1364 uint32_t ssf_error; 1365 struct sctp_sndrcvinfo ssf_info; 1366 sctp_assoc_t ssf_assoc_id; 1367 uint8_t ssf_data[0]; 1368 }; 1370 ssf_type: 1372 It should be SCTP_SEND_FAILED. 1374 ssf_flags: 16 bits (unsigned integer) 1376 The flag value will take one of the following values 1378 SCTP_DATA_UNSENT - Indicates that the data was never put on 1379 the wire. 1381 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1382 Note that this does not necessarily mean that the 1383 data was (or was not) successfully delivered. 1385 ssf_length: sizeof (uint32_t) 1387 This field is the total length of the notification data, including 1388 the notification header. 1390 ssf_error: 16 bits (unsigned integer) 1392 This value represents the reason why the send failed, and if set, 1393 will be a SCTP protocol error code as defined in [SCTP] section 1394 3.3.10. 1396 ssf_info: sizeof (struct sctp_sndrcvinfo) 1398 The original send information associated with the undelivered 1399 message. 1401 ssf_assoc_id: sizeof (sctp_assoc_t) 1403 The association id field, sf_assoc_id, holds the identifier for the 1404 association. All notifications for a given association have the 1405 same association identifier. For TCP style socket, this field is 1406 ignored. 1408 ssf_data: variable length 1410 The undelivered message, exactly as delivered by the caller to the 1411 original send*() call. 1413 5.3.1.5 SCTP_SHUTDOWN_EVENT 1415 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1416 inform the application that it should cease sending data. 1418 struct sctp_shutdown_event { 1419 uint16_t sse_type; 1420 uint16_t sse_flags; 1421 uint32_t sse_length; 1422 sctp_assoc_t sse_assoc_id; 1423 }; 1425 sse_type 1427 It should be SCTP_SHUTDOWN_EVENT 1429 sse_flags: 16 bits (unsigned integer) 1431 Currently unused. 1433 sse_length: sizeof (uint32_t) 1435 This field is the total length of the notification data, including 1436 the notification header. 1438 sse_assoc_id: sizeof (sctp_assoc_t) 1440 The association id field, holds the identifier for the association. 1441 All notifications for a given association have the same association 1442 identifier. For TCP style socket, this field is ignored. 1444 5.4 Ancillary Data Considerations and Semantics 1446 Programming with ancillary socket data contains some subtleties and 1447 pitfalls, which are discussed below. 1449 5.4.1 Multiple Items and Ordering 1451 Multiple ancillary data items may be included in any call to 1452 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1453 items, or both. 1455 The ordering of ancillary data items (either by SCTP or another 1456 protocol) is not significant and is implementation-dependant, so 1457 applications must not depend on any ordering. 1459 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1460 msg_iov member. There can be only a single SCTP_SNDRCV info for 1461 each sendmsg() or recvmsg() call. 1463 5.4.2 Accessing and Manipulating Ancillary Data 1465 Applications can infer the presence of data or ancillary data by 1466 examining the msg_iovlen and msg_controllen msghdr members, 1467 respectively. 1469 Implementations may have different padding requirements for 1470 ancillary data, so portable applications should make use of the 1471 macros CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and 1472 CMSG_LEN. See [RFC2292] and your SCTP implementation's documentation 1473 for more information. Following is an example, from [RFC2292], 1474 demonstrating the use of these macros to access ancillary data: 1476 struct msghdr msg; 1477 struct cmsghdr *cmsgptr; 1479 /* fill in msg */ 1481 /* call recvmsg() */ 1483 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1484 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1485 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1486 u_char *ptr; 1488 ptr = CMSG_DATA(cmsgptr); 1489 /* process data pointed to by ptr */ 1490 } 1491 } 1493 5.4.3 Control Message Buffer Sizing 1495 The information conveyed via SCTP_SNDRCV events will often be 1496 fundamental to the correct and sane operation of the sockets 1497 application. This is particularly true of the UDP semantics, but 1498 also of the TCP semantics. For example, if an application needs to 1499 send and receive data on different SCTP streams, SCTP_SNDRCV events 1500 are indispensable. 1502 Given that some ancillary data is critical, and that multiple 1503 ancillary data items may appear in any order, applications should be 1504 carefully written to always provide a large enough buffer to contain 1505 all possible ancillary data that can be presented by recvmsg(). If 1506 the buffer is too small, and crucial data is truncated, it may pose 1507 a fatal error condition. 1509 Thus it is essential that applications be able to deterministically 1510 calculate the maximum required buffer size to pass to recvmsg(). One 1511 constraint imposed on this specification that makes this possible is 1512 that all ancillary data definitions are of a fixed length. One way 1513 to calculate the maximum required buffer size might be to take the 1514 sum the sizes of all enabled ancillary data item structures, as 1515 calculated by CMSG_SPACE. For example, if we enabled 1516 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC2292], we would calculate 1517 and allocate the buffer size as follows: 1519 size_t total; 1520 void *buf; 1522 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1523 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1525 buf = malloc(total); 1527 We could then use this buffer for msg_control on each call to 1528 recvmsg() and be assured that we would not lose any ancillary data 1529 to truncation. 1531 6. Common Operations for Both Styles 1533 6.1 send(), recv(), sendto(), recvfrom() 1535 Applications can use send() and sendto() to transmit data to the 1536 peer of an SCTP endpoint. recv() and recvfrom() can be used to 1537 receive data from the peer. 1539 The syntax is: 1541 ssize_t send(int sd, connst void *msg, size_t len, int flags); 1542 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1543 const struct sockaddr *to, int tolen); 1544 ssize_t recv(int sd, void *buf, size_t len, int flags); 1545 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1546 struct sockaddr *from, int *fromlen); 1548 sd - the socket descriptor of an SCTP endpoint. 1549 msg - the message to be sent. 1550 len - the size of the message or the size of buffer. 1551 to - one of the peer addresses of the association to be 1552 used to send the message. 1553 tolen - the size of the address. 1554 buf - the buffer to store a received message. 1555 from - the buffer to store the peer address used to send the 1556 received message. 1557 fromlen - the size of the from address 1558 flags - (described below). 1560 These calls give access to only basic SCTP protocol features. If 1561 either peer in the association uses multiple streams, or sends 1562 unordered data these calls will usually be inadequate, and may 1563 deliver the data in unpredictable ways. 1565 SCTP has the concept of multiple streams in one association. The 1566 above calls do not allow the caller to specify on which stream a 1567 message should be sent. The system uses stream 0 as the default 1568 stream for send() and sendto(). recv() and recvfrom() return data 1569 from any stream, but the caller can not distinguish the different 1570 streams. This may result in data seeming to arrive out of 1571 order. Similarly, if a data chunk is sent unordered, recv() and 1572 recvfrom() provide no indication. 1574 SCTP is message based. The msg buffer above in send() and sendto() 1575 is considered to be a single message. This means that if the caller 1576 wants to send a message which is composed by several buffers, the 1577 caller needs to combine them before calling send() or sendto(). 1578 Alternately, the caller can use sendmsg() to do that without 1579 combining them. recv() and recvfrom() cannot distinguish message 1580 boundaries. 1582 In receiving, if the buffer supplied is not large enough to hold a 1583 complete message, the receive call acts like a stream socket and 1584 returns as much data as will fit in the buffer. 1586 Note, the send and recv calls, when used in the UDP-style model, may 1587 only be used with branched off socket descriptors (see Section 8.2). 1589 6.2 setsockopt(), getsockopt() 1591 Applications use setsockopt() and getsockopt() to set or retrieve 1592 socket options. Socket options are used to change the default 1593 behavior of sockets calls. They are described in Section 7. 1595 The syntax is: 1597 ret = getsockopt(int sd, int level, int optname, void *optval, 1598 size_t *optlen); 1599 ret = setsockopt(int sd, int level, int optname, const void *optval, 1600 size_t optlen); 1602 sd - the socket descript. 1603 level - set to IPPROTO_SCTP for all SCTP options. 1604 optname - the option name. 1605 optval - the buffer to store the value of the option. 1606 optlen - the size of the buffer (or the length of the option 1607 returned). 1609 6.3 read() and write() 1611 Applications can use read() and write() to send and receive data to 1612 and from peer. They have the same semantics as send() and recv() 1613 except that the flags parameter cannot be used. 1615 Note, these calls, when used in the UDP-style model, may only be 1616 used with branched off socket descriptors (see Section 8.2). 1618 7. Socket Options 1620 The following sub-section describes various SCTP level socket 1621 options that are common to both models. SCTP associations can be 1622 multihomed. Therefore, certain option parameters include a 1623 sockaddr_storage structure to select which peer address the option 1624 should be applied to. 1626 For the UDP-style sockets, an sctp_assoc_t structure (association 1627 ID) is used to identify the the association instance that the 1628 operation affects. So it must be set when using this model. 1630 For the TCP-style sockets and branched off UDP-style sockets (see 1631 section 8.2) this association ID parameter is ignored. In the cases 1632 noted below where the parameter is ignored, an application can pass 1633 to the system a corresponding option structure similar to those 1634 described below but without the association ID parameter, which 1635 should be the last field of the option structure. This can make the 1636 option setting/getting operation more efficient. If an application 1637 does this, it should also specify an appropriate optlen value 1638 (i.e. sizeof (option parameter) - sizeof (struct sctp_assoc_t)). 1640 Note that socket or IP level options is set or retrieved per socket. 1641 This means that for UDP-style sockets, those options will be applied 1642 to all associations belonging to the socket. And for TCP-style 1643 model, those options will be applied to all peer addresses of the 1644 association controlled by the socket. Applications should be very 1645 careful in setting those options. 1647 7.1 Read / Write Options 1649 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1651 The protocol parameters used to initialize and bound retransmission 1652 timeout (RTO) are tunable. See [SCTP] for more information on how 1653 these parameters are used in RTO calculation. The peer address 1654 parameter is ignored for TCP style socket. 1656 The following structure is used to access and modify these 1657 parameters: 1659 struct sctp_rtoinfo { 1660 uint32_t srto_initial; 1661 uint32_t srto_max; 1662 uint32_t srto_min; 1663 sctp_assoc_t srto_assoc_id; 1664 }; 1666 srto_initial - This contains the initial RTO value. 1667 srto_max and srto_min - These contain the maximum and minumum bounds 1668 for all RTOs. 1669 srto_assoc_id - (UDP style socket) This is filled in the application, 1670 and identifies the association for this query. 1672 All parameters are time values, in milliseconds. A value of 0, when 1673 modifying the parameters, indicates that the current value should 1674 not be changed. 1676 To access or modify these parameters, the application should call 1677 getsockopt or setsockopt() respectively with the option name 1678 SCTP_RTOINFO. 1680 7.1.2 Association Retransmission Parameter (SCTP_ASSOCRTXINFO) 1682 The protocol parameter used to set the number of retransmissions 1683 sent before an association is considered unreachable. 1684 See [SCTP] for more information on how this parameter is used. The 1685 peer address parameter is ignored for TCP style socket. 1687 The following structure is used to access and modify this 1688 parameters: 1690 struct sctp_assocparams { 1691 uint16_t sasoc_asocmaxrxt; 1692 sctp_assoc_t sasoc_assoc_id; 1693 }; 1695 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 1696 to make for the association. 1697 sasoc_assoc_id - (UDP style socket) This is filled in the application, 1698 and identifies the association for this query. 1700 To access or modify these parameters, the application should call 1701 getsockopt or setsockopt() respectively with the option name 1702 SCTP_ASSOCRTXINFO. 1704 The maximum number of retransmissions before an address is 1705 considered unreachable is also tunable, but is address-specific, so 1706 it is covered in a seperate option. If an application attempts to 1707 set the value of the association maximum retransmission parameter to 1708 more than the sum of all maximum retransmission parameters, 1709 setsockopt() shall return an error. The reason for this, from 1710 [SCTP] section 8.2: 1712 Note: When configuring the SCTP endpoint, the user should avoid 1713 having the value of 'Association.Max.Retrans' larger than the 1714 summation of the 'Path.Max.Retrans' of all the destination addresses 1715 for the remote endpoint. Otherwise, all the destination addresses 1716 may become inactive while the endpoint still considers the peer 1717 endpoint reachable. 1719 7.1.3 Initialization Parameters (SCTP_INITMSG) 1721 Applications can specify protocol parameters for the default 1722 association intialization. The structure used to access and modify 1723 these parameters is defined in section 5.2.1. The option name 1724 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 1726 Setting initialization parameters is effective only on an 1727 unconnected socket (for UDP-style sockets only future associations 1728 are effected by the change). With TCP-style sockets, this option is 1729 inherited by sockets derived from a listener socket. 1731 7.1.4 SO_LINGER 1733 An application using the TCP-style socket can use this option to 1734 perform the SCTP ABORT primitive. The linger option structure is: 1736 struct linger { 1737 int l_onoff; /* option on/off */ 1738 int l_linger; /* linger time */ 1739 }; 1741 To enable the option, set l_onoff to 1. If the l_linger value is 1742 set to 0, calling close() is the same as the ABORT primitive. If 1743 the value is set to a negative value, the setsockopt() call will 1744 return an error. If the value is set to a positive value 1745 linger_time, the close() can be blocked for at most linger_time ms. 1746 If the graceful shutdown phase does not finish during this period, 1747 close() will return but the graceful shutdown phase continues in the 1748 system. 1750 7.1.5 SCTP_NODELAY 1752 Turn off any Nagle-like algorithm. This means that packets are 1753 generally sent as soon as possible and no unnecessary delays are 1754 introduced, at the cost of more packets in the network. Expects an 1755 integer boolean flag. 1757 7.1.6 SO_RCVBUF 1759 Sets receive buffer size. For SCTP TCP-style sockets, this controls 1760 the receiver window size. For UDP-style sockets, this controls the 1761 receiver window size for all associations bound to the socket 1762 descriptor used in the setsockopt() or getsockopt() call. The option 1763 applies to each association's window size seperately. Expects an 1764 integer. 1766 7.1.7 SO_SNDBUF 1768 Sets send buffer size. For SCTP TCP-style sockets, this controls the 1769 amount of data SCTP may have waiting in internal buffers to be 1770 sent. This option therefore bounds the maximum size of data that can 1771 be sent in a single send call. For UDP-style sockets, the effect is 1772 the same, except that it applies to all associations bound to the 1773 socket descriptor used in the setsockopt() or getsockopt() call. The 1774 option applies to each association's window size seperately. Expects 1775 an integer. 1777 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 1779 This socket option is applicable to the UDP-style socket only. When 1780 set it will cause associations that are idle for more than the 1781 specified number of seconds to automatically close. An association 1782 being idle is defined an association that has NOT sent or received 1783 user data. The special value of '0' indicates that no automatic 1784 close of any associations should be performed. The option expects 1785 an integer defining the number of seconds of idle time before 1786 an association is closed. 1788 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) 1790 Requests that the peer mark the enclosed address as the association 1791 primary. The enclosed address must be one of the association's 1792 locally bound addresses. The following structure is used to make a 1793 set primary request: 1795 struct sctp_setprim { 1796 struct sockaddr_storage ssp_addr; 1797 sctp_assoc_t ssp_assoc_id; 1798 }; 1800 ssp_addr The address to set as primary 1801 ssp_assoc_id (UDP style socket) This is filled in by the 1802 application, and identifies the association 1803 for this request. 1805 This functionality is optional. Implementations that do not support 1806 this functionality should return EOPNOTSUPP. 1808 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 1810 Requests that the local SCTP stack use the enclosed peer address as 1811 the association primary. The enclosed address must be one of the 1812 association peer's addresses. The following structure is used to 1813 make a set peer primary request: 1815 struct sctp_setpeerprim { 1816 struct sockaddr_storage sspp_addr; 1817 sctp_assoc_t sspp_assoc_id; 1818 }; 1820 sspp_addr The address to set as primary 1821 sspp_assoc_id (UDP style socket) This is filled in by the 1822 application, and identifies the association 1823 for this request. 1825 7.2 Read-Only Options 1827 7.2.1 Association Status (SCTP_STATUS) 1829 Applications can retrieve current status information about an 1830 association, including association state, peer receiver window size, 1831 number of unacked data chunks, and number of data chunks pending 1832 receipt. This information is read-only. The following structure is 1833 used to access this information: 1835 struct sctp_status { 1836 int32_t sstat_state; 1837 uint32_t sstat_rwnd; 1838 uint16_t sstat_unackdata; 1839 uint16_t sstat_penddata; 1840 struct sctp_paddrinfo sstat_primary; 1841 sctp_assoc_t sstat_assoc_id; 1842 }; 1844 sstat_state - This contains the association's current state one 1845 of the following values: 1847 SCTP_CLOSED 1848 SCTP_BOUND 1849 SCTP_LISTEN 1850 SCTP_COOKIE_WAIT 1851 SCTP_COOKIE_ECHOED 1852 SCTP_ESTABLISHED 1853 SCTP_SHUTDOWN_PENDING 1854 SCTP_SHUTDOWN_SENT 1855 SCTP_SHUTDOWN_RECEIVED 1856 SCTP_SHUTDOWN_ACK_SENT 1858 sstat_rwnd - This contains the association peer's current 1859 receiver window size. 1860 sstat_unackdata - This is the number of unacked data chunks. 1861 sstat_penddata - This is the number of data chunks pending receipt. 1862 sstat_primary - This is information on the current primary peer 1863 address. 1864 sstat_assoc_id - (UDP style socket) This holds the an identifier for the 1865 association. All notifications for a given association 1866 have the same association identifier. 1868 To access these status values, the application calls getsockopt() 1869 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 1870 ignored for TCP style socket. 1872 7.3. Ancillary Data and Notification Interest Options 1874 Applications can receive per-message ancillary information and 1875 notifications of certain SCTP events with recvmsg(). 1877 The following optional information is available to the application: 1879 1. SCTP_RECVDATAIOEVNT: Per-message information (i.e. stream number, 1880 TSN, SSN, etc. described in section 5.2.2) 1881 2. SCTP_RECVASSOCEVNT: (described in section 5.3.1.1) 1882 3. SCTP_RECVPADDREVNT: (described in section 5.3.1.2) 1883 4. SCTP_RECVPEERERR: (described in section 5.3.1.3) 1884 5. SCTP_RECVSENDFAILEVNT: (described in section 5.3.1.4) 1885 6. SCTP_RECVSHUTDOWNEVNT: (described in section 5.3.1.5); 1887 To receive any ancillary data or notifications, first the 1888 application registers it's interest by calling setsockopt() to turn 1889 on the corresponding flag: 1891 int on = 1; 1893 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, &on, sizeof(on)); 1894 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, &on, sizeof(on)); 1895 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, &on, sizeof(on)); 1896 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, &on, sizeof(on)); 1897 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, &on, sizeof(on)); 1898 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, &on, sizeof(on)); 1900 Note that for UDP-style SCTP sockets, the caller of recvmsg() 1901 receives ancillary data and notifications for ALL associations bound 1902 to the file descriptor. For TCP-style SCTP sockets, the caller 1903 receives ancillary data and notifications for only the single 1904 association bound to the file descriptor. 1906 By default a TCP-style socket has all options off. 1908 By default a UDP-style socket has SCTP_RECVDATAIOEVNT and 1909 SCTP_RECVASSOCEVNT on and all other options off. 1911 8. New Interfaces 1913 Depending on the system, the following interface can be implemented 1914 as a system call or library funtion. 1916 8.1 sctp_bindx() 1918 The syntax of sctp_bindx() is, 1920 int sctp_bindx(int sd, struct sockaddr_storage *addrs, int addrcnt, 1921 int flags); 1923 If sd is an IPv4 socket, the addresses passed must be IPv4 1924 addresses. If the sd is an IPv6 socket, the addresses passed can 1925 either be IPv4 or IPv6 addresses. 1927 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 1928 section 3.1.2 for this usage. 1930 addrs is a pointer to an array of one or more socket addresses. 1931 Each address is contained in a struct sockaddr_storage, so each 1932 address is a fixed length. The caller specifies the number of 1933 addresses in the array with addrcnt. 1935 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 1936 -1, and sets errno to the appropriate error code. 1938 For SCTP, the port given in each socket address must be the same, or 1939 sctp_bindx() will fail, setting errno to EINVAL. 1941 The flags parameter is formed from the bitwise OR of zero or more of 1942 the following currently defined flags: 1944 SCTP_BINDX_ADD_ADDR 1945 SCTP_BINDX_REM_ADDR 1947 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 1948 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the 1949 given addresses from the association. The two flags are mutually 1950 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 1951 caller may not remove all addresses from an association; 1952 sctp_bindx() will reject such an attempt with EINVAL. 1954 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 1955 additional addresses with an endpoint after calling bind(). Or use 1956 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 1957 socket is associated with so that no new association accepted will 1958 be associated with those addresses. 1960 Adding and removing addresses from a connected association is 1961 optional functionality. Implementations that do not support this 1962 functionality should return EOPNOTSUPP. 1964 8.2 Branched-off Association 1966 After an association is established on a UDP-style socket, the 1967 application may wish to branch off the association into a separate 1968 socket/file descriptor. 1970 This is particularly desirable when, for instance, the application 1971 wishes to have a number of sporadic message senders/receivers remain 1972 under the original UDP-style socket but branch off those 1973 associations carrying high volume data traffic into their own 1974 separate socket descriptors. 1976 The application uses sctp_peeloff() call to branch off an 1977 association into a separate socket (Note the semantics are somewhat 1978 changed from the traditional TCP-style accept() call). 1980 The syntax is: 1982 new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id, int *addrlen) 1984 new_sd - the new socket descriptor representing the branched-off 1985 association. 1987 sd - the original UDP-style socket descriptor returned from the 1988 socket() system call (see Section 3.1.1). 1990 assoc_id - the specified identifier of the association that is to be 1991 branched off to a separate file descriptor (Note, in a 1992 traditional TCP-style accept() call, this would be an out 1993 parameter, but for the UDP-style call, this is an in 1994 parameter). 1996 addrlen - an integer pointer to the size of the sockaddr structure 1997 addr (in a traditional TCP-style call, this would be a out 1998 parameter, but for the UDP-style call this is an in 1999 parameter). 2001 8.3 sctp_getpaddrs() 2003 sctp_getpaddrs() returns all peer addresses in an association. The 2004 syntax is, 2006 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2007 struct sockaddr_storage **addrs); 2009 On return, addrs will point to a dynamically allocated array of 2010 struct sockaddr_storages, one for each peer address. The caller 2011 should use sctp_freepaddrs() to free the memory. addrs must not be 2012 NULL. 2014 If sd is an IPv4 socket, the addresses returned will be all IPv4 2015 addresses. If sd is an IPv6 socket, the addresses returned can be a 2016 mix of IPv4 or IPv6 addresses. 2018 For UDP-style sockets, id specifies the association to query. For 2019 TCP-style sockets, id is ignored. 2021 On success, sctp_getpaddrs() returns the number of peer addresses in 2022 the association. If there is no association on this socket, 2023 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2024 an error occurs, sctp_getpaddrs() returns -1, and the value of 2025 *addrs is undefined. 2027 8.4 sctp_freepaddrs() 2029 sctp_freepaddrs() frees all resources allocated by 2030 sctp_getpaddrs(). Its syntax is, 2032 void sctp_freepaddrs(struct sockaddr_storage *addrs); 2034 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2036 8.5 sctp_getladdrs() 2038 sctp_getladdrs() returns all locally bound address on a socket. The 2039 syntax is, 2041 int sctp_getladdrs(int sock, sctp_assoc_t id, 2042 struct sockaddr_storage **ss); 2044 On return, addrs will point to a dynamically allocated array of 2045 struct sockaddr_storages, one for each local address. The caller 2046 should use sctp_freeladdrs() to free the memory. addrs must not be 2047 NULL. 2049 If sd is an IPv4 socket, the addresses returned will be all IPv4 2050 addresses. If sd is an IPv6 socket, the addresses returned can be a 2051 mix of IPv4 or IPv6 addresses. 2053 For UDP-style sockets, id specifies the association to query. For 2054 TCP-style sockets, id is ignored. 2056 On success, sctp_getladdrs() returns the number of local addresses 2057 bound to the socket. If the socket is unbound, sctp_getladdrs() 2058 returns 0, and the value of *addrs is undefined. If an error occurs, 2059 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2061 8.6 sctp_freeladdrs() 2063 sctp_freeladdrs() frees all resources allocated by 2064 sctp_getladdrs(). Its syntax is, 2066 void sctp_freeladdrs(struct sockaddr_storage *addrs); 2068 addrs is the array of peer addresses returned by sctp_getladdrs(). 2070 8.7 sctp_opt_info() 2072 getsockopt() is read-only, so a new interface is required when 2073 information must be passed both in to and out of the SCTP stack. The 2074 syntax for scpt_opt_info() is, 2076 int sctp_opt_info(int sd, sctp_assoc_t id, int opt, void *arg); 2078 For UDP-style sockets, id specifies the association to query. For 2079 TCP-style sockets, id is ignored. 2081 opt specifies which SCTP option to get or set. It can be one of the 2082 following: 2084 SCTP_SET_PEER_ADDR_PARAMS 2085 SCTP_GET_PEER_ADDR_PARAMS 2086 SCTP_GET_PEER_ADDR_INFO 2088 arg is an option-specific structure buffer provided by the caller. 2089 See 8.5 subsections for more information on these options and 2090 option-specific structures. 2092 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2093 sets errno to the appropriate error code. 2095 8.7.1 Peer Address Parameters 2097 Applications can enable or disable heartbeats for any peer address 2098 of an association, modify an address's heartbeat interval, force a 2099 heartbeat to be sent immediately, and adjust the address's maximum 2100 number of retransmissions sent before an address is considered 2101 unreachable. The following structure is used to access and modify an 2102 address's parameters: 2104 struct sctp_paddrparams { 2105 struct sockaddr_storage spp_address; 2106 uint32_t spp_hbinterval; 2107 uint16_t spp_pathmaxrxt; 2108 sctp_assoc_t spp_assoc_id; 2109 }; 2111 spp_address - This specifies which address is of interest. 2112 spp_hbinterval - This contains the value of the heartbeat interval, 2113 in milliseconds. A value of 0, when modifying the 2114 parameter, specifies that the heartbeat on this 2115 address should be disabled. A value of UINT32_MAX 2116 (4294967295), when modifying the parameter, 2117 specifies that a heartbeat should be sent 2118 immediately to the peer address, and the current 2119 interval should remain unchanged. 2120 spp_pathmaxrxt - This contains the maximum number of 2121 retransmissions before this address shall be 2122 considered unreachable. 2123 spp_assoc_id - (UDP style socket) This is filled in the application, 2124 and identifies the association for this query. 2126 To modify these parameters, the application should call 2127 sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. To get 2128 these parameters, the application should use 2129 SCTP_GET_PEER_ADDR_PARAMS. 2131 8.7.2 Peer Address Information 2133 Applications can retrieve information about a specific peer address 2134 of an association, including its reachability state, congestion 2135 window, and retransmission timer values. This information is 2136 read-only. The following structure is used to access this 2137 information: 2139 struct sctp_paddrinfo { 2140 struct sockaddr_storage spinfo_address; 2141 int32_t spinfo_state; 2142 uint32_t spinfo_cwnd; 2143 uint32_t spinfo_srtt; 2144 uint32_t spinfo_rto; 2145 sctp_assoc_t spinfo_assoc_id; 2146 }; 2148 spinfo_address - This is filled in the application, and contains 2149 the peer address of interest. 2151 On return from getsockopt(): 2153 spinfo_state - This contains the peer addresses's state (either 2154 SCTP_ACTIVE or SCTP_INACTIVE). 2155 spinfo_cwnd - This contains the peer addresses's current congestion 2156 window. 2157 spinfo_srtt - This contains the peer addresses's current smoothed 2158 round-trip time calculation in milliseconds. 2159 spinfo_rto - This contains the peer addresses's current 2160 retransmission timeout value in milliseconds. 2161 spinfo_assoc_id - (UDP style socket) This is filled in the application, 2162 and identifies the association for this query. 2164 To retrieve this information, use sctp_opt_info() with the 2165 SCTP_GET_PEER_ADDR_INFO options. 2167 9. Security Considerations 2169 Many TCP and UDP implementations reserve port numbers below 1024 for 2170 privileged users. If the target platform supports privileged users, 2171 the SCTP implementation SHOULD restrict the ability to call bind() 2172 or sctp_bindx() on these port numbers to privileged users. 2174 Similarly unprivelged users should not be able to set protocol 2175 parameters which could result in the congestion control algorithm 2176 being more agressive than permitted on the public Internet. These 2177 paramaters are: 2179 struct sctp_rtoinfo 2181 If an unprivileged user inherits a UDP-style socket with open 2182 associations on a privileged port, it MAY be permitted to accept new 2183 associations, but it SHOULD NOT be permitted to open new 2184 associations. This could be relevant for the r* family of 2185 protocols. 2187 10. Acknowledgements 2189 The authors wish to thank Mike Bartlett, Jon Berger, Renee Ravis, 2190 and many others on the TSVWG mailing list for contributing valuable 2191 comments. 2193 11. Authors' Addresses 2195 Randall R. Stewart Tel: +1-815-477-2127 2196 Cisco Systems, Inc. EMail: rrs@cisco.com 2197 Crystal Lake, IL 60012 2198 USA 2200 Qiaobing Xie Tel: +1-847-632-3028 2201 Motorola, Inc. EMail: qxie1@email.mot.com 2202 1501 W. Shure Drive, Room 2309 2203 Arlington Heights, IL 60004 2204 USA 2206 La Monte H.P. Yarroll NIC Handle: LY 2207 Motorola, Inc. EMail: piggy@acm.org 2208 1501 W. Shure Drive, IL27-2315 2209 Arlington Heights, IL 60004 2210 USA 2212 Jonathan Wood 2213 Sun Microsystems, Inc. Email: jonathan.wood@sun.com 2214 901 San Antonio Road 2215 Palo Alto, CA 94303 2216 USA 2218 Kacheong Poon 2219 Sun Microsystems, Inc. Email: kacheong.poon@sun.com 2220 901 San Antonio Road 2221 Palo Alto, CA 94303 2222 USA 2224 Ken Fujita Tel: +81-471-82-1131 2225 NEC Corporation Email: fken@cd.jp.nec.com 2226 1131, Hinode, Abiko 2227 Chiba, 270-1198 2228 Japan 2230 12. References 2232 [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2233 September 1981. 2235 [RFC768] Postel, J. (ed.), "User Datagram Protocol", STD 6, RFC 768, 2236 August 1980. 2238 [RFC1644] Braden, R., "T/TCP -- TCP Extensions for Transactions 2239 Functional Specification," RFC 1644, July 1994. 2241 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", 2242 RFC 2026, October 1996. 2244 [RFC2292] W.R. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 2245 RFC 2292, February 1998. 2247 [RFC2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens. "Basic Socket 2248 Interface Extensions for IPv6," RFC 2553, March 1999. 2250 [SCTP] R.R. Stewart, Q. Xie, K. Morneault, C. Sharp, H.J. Schwarzbauer, 2251 T. Taylor, I. Rytina, M. Kalla, L. Zhang, and, V. Paxson, 2252 "Stream Control Transmission Protocol," RFC2960, October 2000. 2254 [STEVENS] W.R. Stevens, M. Thomas, E. Nordmark, "Advanced Sockets API for 2255 IPv6," , December 1999 2256 (Work in progress) 2258 Appendix A: TCP-style Code Example 2260 The following code is a simple implementation of an echo server over 2261 SCTP. The example shows how to use some features of TCP-style IPv4 2262 SCTP sockets, including: 2264 o Opening, binding, and listening for new associations on a socket; 2265 o Enabling ancillary data 2266 o Enabling notifications 2267 o Using ancillary data with sendmsg() and recvmsg() 2268 o Using MSG_EOR to determine if an entire message has been read 2269 o Handling notifications 2271 static void 2272 handle_event(void *buf) 2273 { 2274 struct sctp_assoc_change *sac; 2275 struct sctp_send_failed *ssf; 2276 struct sctp_paddr_change *spc; 2277 struct sctp_remote_error *sre; 2278 union sctp_notification *snp; 2279 char addrbuf[INET6_ADDRSTRLEN]; 2280 const char *ap; 2281 struct sockaddr_in *sin; 2282 struct sockaddr_in6 *sin6; 2284 snp = buf; 2286 switch (snp->sn_type) { 2287 case SCTP_ASSOC_CHANGE: 2288 sac = &snp->sn_assoc_change; 2289 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2290 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2291 sac->sac_inbound_streams, sac->sac_outbound_streams); 2292 break; 2293 case SCTP_SEND_FAILED: 2294 ssf = &snp->sn_send_failed; 2295 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2296 ssf->ssf_error); 2297 break; 2298 case SCTP_PEER_ADDR_CHANGE: 2299 spc = &snp->sn_intf_change; 2300 if (spc->spc_addr.ss_family == AF_INET) { 2301 sin = (struct sockaddr_in *)&spc->spc_addr; 2302 ap = inet_ntop(AF_INET, &sin->sin_addr, addrbuf, 2303 INET6_ADDRSTRLEN); 2304 } else { 2305 sin6 = (struct sockaddr_in6 *)&spc->spc_addr; 2306 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, addrbuf, 2307 INET6_ADDRSTRLEN); 2308 } 2309 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2310 spc->spc_state, spc->spc_error); 2311 break; 2312 case SCTP_REMOTE_ERROR: 2313 sre = &snp->sn_remote_error; 2314 printf("^^^ remote_error: err=%hu len=%hu\n", 2315 ntohs(sre->sre_error), ntohs(sre->sre_len)); 2316 break; 2317 case SCTP_SHUTDOWN_EVENT: 2319 printf("^^^ shutdown event\n"); 2320 break; 2321 default: 2322 printf("unknown type: %hu\n", snp->sn_type); 2323 break; 2324 } 2325 } 2327 static void * 2328 sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2329 ssize_t *nrp, size_t cmsglen) 2330 { 2331 ssize_t nr = 0; 2332 struct iovec iov[1]; 2334 *nrp = 0; 2335 iov->iov_base = buf; 2336 msg->msg_iov = iov; 2337 msg->msg_iovlen = 1; 2339 for (;;) { 2340 msg->msg_flags = MSG_XPG4_2; 2341 msg->msg_iov->iov_len = *buflen; 2342 msg->msg_controllen = cmsglen; 2344 nr += recvmsg(fd, msg, 0); 2345 if (nr <= 0) { 2346 /* EOF or error */ 2347 *nrp = nr; 2348 return (NULL); 2349 } 2351 if ((msg->msg_flags & MSG_EOR) != 0) { 2352 *nrp = nr; 2353 return (buf); 2354 } 2356 /* Realloc the buffer? */ 2357 if (*buflen == nr) { 2358 buf = realloc(buf, *buflen * 2); 2359 if (buf == 0) { 2360 fprintf(stderr, "out of memory\n"); 2361 exit(1); 2362 } 2363 *buflen *= 2; 2364 } 2366 /* Set the next read offset */ 2367 iov->iov_base = (char *)buf + nr; 2368 iov->iov_len = *buflen - nr; 2370 } 2371 } 2372 static void 2373 echo(int fd, int socketModeUDP) 2374 { 2375 ssize_t nr; 2376 struct sctp_sndrcvinfo *sri; 2377 struct msghdr msg[1]; 2378 struct cmsghdr *cmsg; 2379 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 2380 char *buf; 2381 size_t buflen; 2382 struct iovec iov[1]; 2383 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 2385 /* Allocate the initial data buffer */ 2386 buflen = BUFLEN; 2387 if (!(buf = malloc(BUFLEN))) { 2388 fprintf(stderr, "out of memory\n"); 2389 exit(1); 2390 } 2392 /* Set up the msghdr structure for receiving */ 2393 memset(msg, 0, sizeof (*msg)); 2394 msg->msg_control = cbuf; 2395 msg->msg_controllen = cmsglen; 2396 msg->msg_flags = 0; 2397 cmsg = (struct cmsghdr *)cbuf; 2398 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 2400 /* Wait for something to echo */ 2401 while (buf = sctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 2403 /* Intercept notifications here */ 2404 if (msg->msg_flags & MSG_NOTIFICATION) { 2405 handle_event(buf); 2406 continue; 2407 } 2409 iov->iov_base = buf; 2410 iov->iov_len = nr; 2411 msg->msg_iov = iov; 2412 msg->msg_iovlen = 1; 2414 printf("got %u bytes on stream %hu:\n", nr, 2415 sri->sinfo_stream); 2416 write(0, buf, nr); 2418 /* Echo it back */ 2419 msg->msg_flags = MSG_XPG4_2; 2420 if (sendmsg(fd, msg, 0) < 0) { 2421 perror("sendmsg"); 2422 exit(1); 2423 } 2424 } 2425 if (nr < 0) { 2426 perror("recvmsg"); 2427 } 2428 if(socketModeUDP == 0) 2429 close(fd); 2430 } 2432 main() 2433 { 2434 int lfd, cfd; 2435 int onoff = 1; 2436 struct sockaddr_in sin[1]; 2438 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 2439 perror("socket"); 2440 exit(1); 2441 } 2443 sin->sin_family = AF_INET; 2444 sin->sin_port = htons(7); 2445 sin->sin_addr.s_addr = INADDR_ANY; 2446 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2447 perror("bind"); 2448 exit(1); 2449 } 2451 if (listen(lfd, 1) == -1) { 2452 perror("listen"); 2453 exit(1); 2454 } 2456 /* Wait for new associations */ 2457 for (;;) { 2458 if ((cfd = accept(lfd, NULL, 0)) == -1) { 2459 perror("accept"); 2460 exit(1); 2461 } 2463 /* Enable ancillary data */ 2464 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2465 &onoff, 4) < 0) { 2466 perror("setsockopt RECVDATAIOEVNT"); 2467 exit(1); 2468 } 2469 /* Enable notifications */ 2470 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, 2471 &onoff, 4) < 0) { 2472 perror("setsockopt SCTP_RECVASSOCEVNT"); 2473 exit(1); 2474 } 2475 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2476 &onoff, 4) < 0) { 2477 perror("setsockopt SCTP_RECVASSOCEVNT"); 2478 exit(1); 2480 } 2481 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2482 &onoff, 4) < 0) { 2483 perror("setsockopt SCTP_RECVPADDREVNT"); 2484 exit(1); 2485 } 2486 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2487 &onoff, 4) < 0) { 2488 perror("setsockopt SCTP_RECVPEERERR"); 2489 exit(1); 2490 } 2491 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2492 &onoff, 4) < 0) { 2493 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2494 exit(1); 2495 } 2497 /* Echo back any and all data */ 2498 echo(cfd,0); 2499 } 2500 } 2502 Appendix B: UDP-style Code Example 2504 The following code is a simple implementation of an echo server over 2505 SCTP. The example shows how to use some features of UDP-style IPv4 2506 SCTP sockets, including: 2508 o Opening and binding of a socket; 2509 o Enabling ancillary data 2510 o Enabling notifications 2511 o Using ancillary data with sendmsg() and recvmsg() 2512 o Using MSG_EOR to determine if an entire message has been read 2513 o Handling notifications 2515 Note most functions defined in Appendix A are reused in 2516 this example. 2518 main() 2519 { 2520 int fd; 2521 int onoff = 1; 2522 int idleTime = 2; 2523 struct sockaddr_in sin[1]; 2525 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 2526 perror("socket"); 2527 exit(1); 2528 } 2530 sin->sin_family = AF_INET; 2531 sin->sin_port = htons(7); 2532 sin->sin_addr.s_addr = INADDR_ANY; 2533 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2534 perror("bind"); 2535 exit(1); 2536 } 2538 /* Enable notifications */ 2540 /* SCTP_RECVASSOCEVNT and SCTP_RECVDATAIOEVNT are on by default */ 2542 /* if a send fails we want to know it */ 2543 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2544 &onoff, 4) < 0) { 2545 perror("setsockopt SCTP_RECVASSOCEVNT"); 2546 exit(1); 2547 } 2548 /* if a network address change or event transpires 2549 * we wish to know it 2550 */ 2551 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2552 &onoff, 4) < 0) { 2553 perror("setsockopt SCTP_RECVPADDREVNT"); 2554 exit(1); 2555 } 2556 /* We would like all error TLV's from the peer */ 2557 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2558 &onoff, 4) < 0) { 2559 perror("setsockopt SCTP_RECVPEERERR"); 2560 exit(1); 2561 } 2562 /* And of course we would like to know about shutdown's */ 2563 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2564 &onoff, 4) < 0) { 2565 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2566 exit(1); 2567 } 2568 /* Set associations to auto-close in 2 seconds of 2569 * inactivity 2570 */ 2571 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 2572 &idleTime, 4) < 0) { 2573 perror("setsockopt SCTP_AUTOCLOSE"); 2574 exit(1); 2575 } 2577 /* Allow new associations to be accepted */ 2578 if (listen(fd, 0) < 0) { 2579 perror("listen"); 2580 exit(1); 2581 } 2583 /* Wait for new associations */ 2584 while(1){ 2585 /* Echo back any and all data */ 2586 echo(fd,1); 2587 } 2588 }