idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-02.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-04-25) 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 37 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** There are 68 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 954: '...In other words the user MAY be able to...' RFC 2119 keyword, line 973: '... MAY override 'RTO.Max'. This valu...' RFC 2119 keyword, line 1109: '...e MSG_EOR clear. The user MUST finish...' RFC 2119 keyword, line 2255: '...P implementation SHOULD restrict the a...' RFC 2119 keyword, line 2266: '...vileged port, it MAY be permitted to a...' (1 more instance...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 710 has weird spacing: '...n. The value...' == Line 722 has weird spacing: '...er send and ...' == Line 929 has weird spacing: '...g_level cms...' == Line 985 has weird spacing: '...g_level cms...' == Line 1542 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 (November 19, 2001) is 8193 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 579, but not defined ** Obsolete undefined reference: RFC 2553 (Obsoleted by RFC 3493) -- Looks like a reference, but probably isn't: '0' on line 1388 -- Looks like a reference, but probably isn't: '1' on line 2606 == Unused Reference: 'STEVENS' is defined on line 2338, 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 November 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........................10 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..........................21 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............................24 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.3.1.6 SCTP_ADAPTION_INDICATION.........................28 77 5.4 Ancillary Data Considerations and Semantics...........29 78 5.4.1 Multiple Items and Ordering........................29 79 5.4.2 Accessing and Manipulating Ancillary Data..........29 80 5.4.3 Control Message Buffer Sizing......................30 81 6. Common Operations for Both Styles.......................30 82 6.1 send(), recv(), sendto(), recvfrom()..................30 83 6.2 setsockopt(), getsockopt()............................31 84 6.3 read() and write()....................................32 85 7. Socket Options..........................................32 86 7.1 Read / Write Options..................................32 87 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO)...32 88 7.1.2 Association Retransmission Parameter 89 (SCTP_ASSOCRTXINFO)................................33 90 7.1.3 Initialization Parameters (SCTP_INITMSG)...........34 91 7.1.4 SO_LINGER..........................................34 92 7.1.5 SO_NODELAY.........................................34 93 7.1.6 SO_RCVBUF..........................................34 94 7.1.7 SO_SNDBUF..........................................35 95 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE)...35 96 7.1.9 SCTP_SET_PRIMARY_ADDR..............................35 97 7.1.10 SCTP_SET_PEER_PRIMARY_ADDR........................35 98 7.1.11 Set Adaption Layer Bits...........................36 99 7.2 Read-Only Options.....................................36 100 7.2.1 Association Status (SCTP_STATUS)...................36 101 7.3. Ancillary Data and Notification Interest Options.....37 102 8. New Interfaces..........................................38 103 8.1 sctp_bindx()..........................................38 104 8.2 Branched-off Association, sctp_peeloff()..............39 105 8.3 sctp_getpaddrs()......................................39 106 8.4 sctp_freepaddrs().....................................40 107 8.5 sctp_getladdrs()......................................40 108 8.6 sctp_freeladdrs().....................................40 109 8.7 sctp_opt_info().......................................41 110 8.7.1 Peer Address Parameters............................41 111 8.7.2 Peer Address Information...........................42 112 9. Security Considerations.................................42 113 10. Acknowledgements......................................43 114 11. Authors' Addresses....................................43 115 12. References............................................44 116 Appendix A: TCP-style Code Example.........................44 117 Appendix B: UDP-style Code Example.........................49 119 1. Introduction 121 The sockets API has provided a standard mapping of the Internet 122 Protocol suite to many operating systems. Both TCP [RFC793] and UDP 123 [RFC768] have benefited from this standard representation and access 124 method across many diverse platforms. SCTP is a new protocol that 125 provides many of the characteristics of TCP but also incorporates 126 semantics more akin to UDP. This document defines a method to map 127 the existing sockets API for use with SCTP, providing both a base 128 for access to new features and compatibility so that most existing 129 TCP applications can be migrated to SCTP with few (if any) changes. 131 There are three basic design objectives: 133 1) Maintain consistency with existing sockets APIs: 135 We define a sockets mapping for SCTP that is consistent with other 136 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 137 IPv6). 139 2) Support a UDP-style interface 141 This set of semantics is similar to that defined for conntionless 142 protocols, such as UDP. It is more efficient than a TCP-like 143 connection-oriented interface in terms of exploring the new features 144 of SCTP. 146 Note that SCTP is connection-oriented in nature, and it does not 147 support broadcast or multicast communications, as UDP does. 149 3) Support a TCP-style interface 151 This interface supports the same basic semantics as sockets for 152 connection-oriented protocols, such as TCP. 154 The purpose of defining this interface is to allow existing 155 applications built on connnection-oriented protocols be ported to 156 use SCTP with very little effort, and developers familiar with those 157 semantics can easily adapt to SCTP. 159 Extensions will be added to this mapping to provide mechanisms to 160 exploit new features of SCTP. 162 Goals 2 and 3 are not compatible, so in this document we define two 163 modes of mapping, namely the UDP-style mapping and the TCP-style 164 mapping. These two modes share some common data structures and 165 operations, but will require the use of two different programming 166 models. 168 A mechanism is defined to convert a UDP-style SCTP socket into a 169 TCP-style socket. 171 Some of the SCTP mechanisms cannot be adequately mapped to existing 172 socket interface. In some cases, it is more desirable to have new 173 interface instead of using exisitng socket calls. This document 174 also describes those new interface. 176 2. Conventions 178 2.1 Data Types 180 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 181 1003.1g are used: uintN_t means an unsigned integer of exactly N 182 bits (e.g., uint16_t). We also assume the argument data types from 183 1003.1g when possible (e.g., the final argument to setsockopt() is a 184 size_t value). Whenever buffer sizes are specified, the POSIX 185 1003.1 size_t data type is used. 187 3. UDP-style Interface 189 The UDP-style interface has the following characteristics: 191 A) Outbound association setup is implicit. 193 B) Messages are delivered in complete messages (with one notable 194 exception). 196 3.1 Basic Operation 198 A typical server in this model uses the following socket calls in 199 sequence to prepare an endpoint for servicing requests: 201 1. socket() 202 2. bind() 203 3. listen() 204 4. recvmsg() 205 5. sendmsg() 206 6. close() 208 A typical client uses the following calls in sequence to setup an 209 association with a server to request services: 211 1. socket() 212 2. sendmsg() 213 3. recvmsg() 214 4. close() 216 In this model, by default, all the associations connected to the 217 endpoint are represented with a single socket. 219 If the server or client wishes to branch an existing association off 220 to a separate socket, it is required to call sctp_peeloff() and in 221 the parameter specifies one of the transport addresses of the 222 association. The sctp_peeloff() call will return a new socket which 223 can then be used with recv() and send() functions for message 224 passing. See Section 8.2 for more on branched-off associations. 226 Once an association is branched off to a separate socket, it becomes 227 completely separated from the original socket. All subsequent 228 control and data operations to that association must be done through 229 the new socket. For example, the close operation on the original 230 socket will not terminate any associations that have been branched 231 off to a different socket. 233 We will discuss the UDP-style socket calls in more details in the 234 following subsections. 236 3.1.1 socket() - UDP Style Syntax 238 Applications use socket() to create a socket descriptor to represent 239 an SCTP endpoint. 241 The syntax is, 243 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 245 or, 247 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 249 Here, SOCK_SEQPACKET indicates the creation of a UDP-style socket. 251 The first form creates an endpoint which can use only IPv4 252 addresses, while, the second form creates an endpoint which can use 253 both IPv6 and IPv4 mapped addresses. 255 3.1.2 bind() - UDP Style Syntax 257 Applications use bind() to specify which local address the SCTP 258 endpoint should associate itself with. 260 An SCTP endpoint can be associated with multiple addresses. To do 261 this, sctp_bindx() is introduced in section 8.1 to help applications 262 do the job of associating multiple addresses. 264 These addresses associated with a socket are the eligible transport 265 addresses for the endpoint to send and receive data. The endpoint 266 will also present these addresses to its peers during the 267 association initialization process, see [SCTP]. 269 After calling bind() or sctp_bindx(), if the endpoint wishes to 270 accept new associations on the socket, it must call listen() (see 271 section 3.1.3). 273 The syntax of bind() is, 275 ret = bind(int sd, struct sockaddr *addr, int addrlen); 277 sd - the socket descriptor returned by socket(). 278 addr - the address structure (struct sockaddr_in or struct 279 sockaddr_in6 [RFC 2553]), 280 addrlen - the size of the address structure. 282 If sd is an IPv4 socket, the address passed must be an IPv4 address. 283 If the sd is an IPv6 socket, the address passed can either be an 284 IPv4 or an IPv6 address. 286 Applications cannot call bind() multiple times to associate multiple 287 addresses to an endpoint. After the first call to bind(), all 288 subsequent calls will return an error. 290 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 291 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 292 operating system will associate the endpoint with an optimal address 293 set of the available interfaces. 295 If a bind() or sctp_bindx() is not called prior to a sendmsg() call 296 that initiates a new association, the system picks an ephemeral port 297 and will choose an address set equivalent to binding with a wildcard 298 address. One of those addresses will be the primary address for the 299 association. This automatically enables the multihoming capability 300 of SCTP. 302 3.1.3 listen() - UDP Style Syntax 304 By default, new associations are not accepted for UDP style sockets. 305 An application uses listen() to mark a socket as being able to 306 accept new associations. The syntax is, 308 int listen(int socket, int backlog); 310 socket - the socket descriptor of the endpoint. 311 backlog - ignored for UDP-style sockets. 313 Note that UDP-style socket consumers do not need to call accept to 314 retrieve new associations. Calling accept() on a UDP-style socket 315 should return EOPNOTSUPP. Rather, new associations are accepted 316 automatically, and notifications of the new associations are 317 delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if these 318 notifications are enabled). Clients will typically not call listen, 319 so that they can be assured that the only associations on the socket 320 will be ones they actively initiated. Server or peer-to-peer 321 sockets, on the other hand, will always accept new associations, so 322 a well-written application using server UDP-style sockets must be 323 prepared to handle new associations from unwanted peers. 325 Also note that the SCTP_ASSOC_CHANGE event provides the association 326 ID for a new association, so if applications wish to use the 327 association ID as input to other socket calls, they should ensure 328 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 329 default). 331 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax 333 An application uses sendmsg() and recvmsg() call to transmit data to 334 and receive data from its peer. 336 ssize_t sendmsg(int socket, const struct msghdr *message, 337 int flags); 339 ssize_t recvmsg(int socket, struct msghdr *message, 340 int flags); 342 socket - the socket descriptor of the endpoint. 343 message - pointer to the msghdr structure which contains a single 344 user message and possibly some ancillary data. 346 See Section 5 for complete description of the data 347 structures. 349 flags - No new flags are defined for SCTP at this level. See 350 Section 5 for SCTP-specific flags used in the msghdr 351 structure. 353 As we will see in Section 5, along with the user data, the ancillary 354 data field is used to carry the sctp_sndrcvinfo and/or the 355 sctp_initmsg structures to perform various SCTP functions including 356 specifying options for sending each user message. Those options, 357 depending on whether sending or receiving, include stream number, 358 stream sequence number, TOS, various flags, context and payload 359 protocol Id, etc. 361 When sending user data with sendmsg(), the msg_name field in msghdr 362 structure will be filled with one of the transport addresses of the 363 intended receiver. If there is no association existing between the 364 sender and the intended receiver, the sender's SCTP stack will set 365 up a new association and then send the user data (see Section 3.2 366 for more on implicit association setup). 368 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 369 be delivered if that notification has been enabled, and no more data 370 can be sent to that association. Any attempt to send more data will 371 cause sendmsg() to return with an ESHUTDOWN error. Note that the 372 socket is still open for reading at this point so it is possible to 373 retrieve notifications. 375 When receiving a user message with recvmsg(), the msg_name field in 376 msghdr structure will be populated with the source transport address 377 of the user data. The caller of recvmsg() can use this address 378 information to determine to which association the received user 379 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 380 applications must use the peer transport address provided in the 381 msg_name field by recvmsg() to perform correlation to an 382 association, since they will not have the association ID. 384 If all data in a single message has been delivered, MSG_EOR will be 385 set in the msg_flags field of the msghdr structure (see section 386 5.1). 388 If the application does not provide enough buffer space to 389 completely receive a data message, MSG_EOR will not be set in 390 msg_flags. Successive reads will consume more of the same message 391 until the entire message has been delivered, and MSG_EOR will be 392 set. 394 If the SCTP stack is running low on buffers, it may partially 395 deliver a message. In this case, MSG_EOR will not be set, and more 396 calls to recvmsg() will be necessary to completely consume the 397 message. Only one message at a time can be partially delivered. 399 Note, if the socket is a branched-off socket that only represents 400 one association (see Section 3.1), the msg_name field is not used 401 when sending data (i.e., ignored by the SCTP stack). 403 3.1.5 close() - UDP Style Syntax 405 Applications use close() to perform graceful shutdown (as described 406 in Section 10.1 of [SCTP]) on ALL the associations currently 407 represented by a UDP-style socket. 409 The syntax is 411 ret = close(int sd); 413 sd - the socket descriptor of the associations to be closed. 415 To gracefully shutdown a specific association represented by the 416 UDP-style socket, an application should use the sendmsg() call, 417 passing no user data, but including the MSG_EOF flag in the 418 ancillary data (see Section 5.2.2). 420 If sd in the close() call is a branched-off socket representing only 421 one association, the shutdown is performed on that association only. 423 3.2 Implicit Association Setup 425 Once all bind() calls are complete on a UDP-style socket, the 426 application can begin sending and receiving data using the 427 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 428 through any explicit association setup procedures (i.e., no 429 connect() calls required). 431 Whenever sendmsg() or sendto() is called and the SCTP stack at the 432 sender finds that there is no association existing between the 433 sender and the intended receiver (identified by the address passed 434 either in the msg_name field of msghdr structure in the sendmsg() 435 call or the dest_addr field in the sendto() call), the SCTP stack 436 will automatically setup an association to the intended receiver. 438 Upon the successful association setup a COMMUNICATION_UP 439 notification will be dispatched to the socket at both the sender and 440 receiver side. This notification can be read by the recvmsg() system 441 call (see Section 3.1.3). 443 Note, if the SCTP stack at the sender side supports bundling, the 444 first user message may be bundled with the COOKIE ECHO message 445 [SCTP]. 447 When the SCTP stack sets up a new association implicitly, it first 448 consults the sctp_initmsg structure, which is passed along within 449 the ancillary data in the sendmsg() call (see Section 5.2.1 for 450 details of the data structures), for any special options to be used 451 on the new association. 453 If this information is not present in the sendmsg() call, or if the 454 implicit association setup is triggered by a sendto() call, the 455 default association initialization parameters will be used. These 456 default association parameters may be set with respective 457 setsockopt() calls or be left to the system defaults. 459 Implicit association setup cannot be initiated by send()/recv() 460 calls. 462 3.3 Non-blocking mode 464 Some SCTP users might want to avoid blocking when they call 465 socket interface function. 467 Whenever the user which want to avoid blocking must call select() 468 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and 469 check the socket status is writable or readable. If the socket 470 status isn't writeable or readable, the user should not call 471 sendmsg()/sendto() and recvmsg()/recvfrom(). 473 Once all bind() calls are complete on a UDP-style socket, the 474 application must set the non-blocking option by a fcntl() (such as 475 O_NONBLOCK). After which the sendmsg() function returns 476 immediately, and the success or failure of the data message (and 477 possible SCTP_INITMSG parameters) will be signalled by the 478 SCTP_ASSOC_CHANGE event with COMMUNICATION_UP or 479 CANT_START_ASSOC. If user data could not be sent (due to a 480 CANT_START_ASSOC), the sender will also receive a SCTP_SEND_FAILED 481 event. Those event(s) can be received by the user calling of 482 recvmsg(). A server (having called listen()) is also notified of an 483 association up event by the reception of a SCTP_ASSOC_CHANGE with 484 COMMUNICATION_UP via the calling of recvmsg() and possibly the 485 reception of the first data message. 487 In order to shutdown the association gracefully, the user must call 488 sendmsg() with no data and with the MSG_EOF flag set. The function 489 returns immediately, and completion of the graceful shutdown is 490 indicated by an SCTP_ASSOC_CHANGE notification of type 491 SHUTDOWN_COMPLETE (see section 5.3.1.1). 493 4. TCP-style Interface 495 The goal of this model is to follow as closely as possible the 496 current practice of using the sockets interface for a connection 497 oriented protocol, such as TCP. This model enables existing 498 applications using connection oriented protocols to be ported to 499 SCTP with very little effort. 501 Note that some new SCTP features and some new SCTP socket options 502 can only be utilized through the use of sendmsg() and recvmsg() 503 calls, see Section 4.1.8. 505 4.1 Basic Operation 507 A typical server in TCP-style model uses the following system call 508 sequence to prepare an SCTP endpoint for servicing requests: 510 1. socket() 511 2. bind() 512 3. listen() 513 4. accept() 515 The accept() call blocks until a new association is set up. It 516 returns with a new socket descriptor. The server then uses the new 517 socket descriptor to communicate with the client, using recv() and 518 send() calls to get requests and send back responses. 520 Then it calls 522 5. close() 524 to terminate the association. 526 A typical client uses the following system call sequence to setup an 527 association with a server to request services: 529 1. socket() 530 2. connect() 532 After returning from connect(), the client uses send() and recv() 533 calls to send out requests and receive responses from the server. 535 The client calls 537 3. close() 539 to terminate this association when done. 541 4.1.1 socket() - TCP Style Syntax 542 Applications calls socket() to create a socket descriptor to 543 represent an SCTP endpoint. 545 The syntax is: 547 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 549 or, 551 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 553 Here, SOCK_STREAM indicates the creation of a TCP-style socket. 555 The first form creates an endpoint which can use only IPv4 556 addresses, while the second form creates an endpoint which can use 557 both IPv6 and mapped IPv4 addresses. 559 4.1.2 bind() - TCP Style Syntax 561 Applications use bind() to pass an address to be associated with an 562 SCTP endpoint to the system. bind() allows only either a single 563 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 564 endpoint can be associated with multiple addresses. To do this, 565 sctp_bindx() is introduced in section 8.1 to help applications do 566 the job of associating multiple addresses. 568 These addresses associated with a socket are the eligible transport 569 addresses for the endpoint to send and receive data. The endpoint 570 will also present these addresses to its peers during the 571 association initialization process, see [SCTP]. 573 The syntax is: 575 int bind(int sd, struct sockaddr *addr, int addrlen); 577 sd - the socket descriptor returned by socket() call. 578 addr - the address structure (either struct sockaddr_in or struct 579 sockaddr_in6 defined in [RFC 2553]). 580 addrlen - the size of the address structure. 582 If sd is an IPv4 socket, the address passed must be an IPv4 address. 583 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 584 either be an IPv4 or an IPv6 address. 586 Applications cannot call bind() multiple times to associate multiple 587 addresses to the endpoint. After the first call to bind(), all 588 subsequent calls will return an error. 590 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 591 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 592 operating system will associate the endpoint with an optimal address 593 set of the available interfaces. 595 If a bind() or sctp_bindx() is not called prior to the connect() 596 call, the system picks an ephemeral port and will choose an address 597 set equivalant to binding with a wildcard address. One of those 598 addresses will be the primary address for the association. This 599 automatically enables the multihoming capability of SCTP. 601 The completion of this bind() process does not ready the SCTP 602 endpoint to accept inbound SCTP association requests. Until a 603 listen() system call, described below, is performed on the socket, 604 the SCTP endpoint will promptly reject an inbound SCTP INIT request 605 with an SCTP ABORT. 607 4.1.3 listen() - TCP Style Syntax 609 Applications use listen() to ready the SCTP endpoint for accepting 610 inbound associations. 612 The syntax is: 614 int listen(int sd, int backlog); 616 sd - the socket descriptor of the SCTP endpoint. 617 backlog - this specifies the max number of outstanding associations 618 allowed in the socket's accept queue. These are the 619 associations that have finished the four-way initiation 620 handshake (see Section 5 of [SCTP]) and are in the 621 ESTABLISHED state. Note, a backlog of '0' indicates 622 that the caller no longer wishes to receive new 623 associations. 625 4.1.4 accept() - TCP Style Syntax 627 Applications use accept() call to remove an established SCTP 628 association from the accept queue of the endpoint. A new socket 629 descriptor will be returned from accept() to represent the newly 630 formed association. 632 The syntax is: 634 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 636 new_sd - the socket descriptor for the newly formed association. 637 sd - the listening socket descriptor. 638 addr - on return, will contain the primary address of the peer 639 endpoint. 640 addrlen - on return, will contain the size of addr. 642 4.1.5 connect() - TCP Style Syntax 644 Applications use connect() to initiate an association to a peer. 646 The syntax is 648 int connect(int sd, const struct sockaddr *addr, int addrlen); 649 sd - the socket descriptor of the endpoint. 650 addr - the peer's address. 651 addrlen - the size of the address. 653 This operation corresponds to the ASSOCIATE primitive described in 654 section 10.1 of [SCTP]. 656 By default, the new association created has only one outbound 657 stream. The SCTP_INITMSG option described in Section 7.1.3 should be 658 used before connecting to change the number of outbound streams. 660 If a bind() or sctp_bindx() is not called prior to the connect() 661 call, the system picks an ephemeral port and will choose an address 662 set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 663 and IPv6 socket respectively. One of those addresses will be the 664 primary address for the association. This automatically enables the 665 multihoming capability of SCTP. 667 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 668 during the association set up phase. If an application wants to do 669 this, it cannot use connect() call. Instead, it should use sendto() 670 or sendmsg() to initiate an association. If it uses sendto() and it 671 wants to change initialization behavior, it needs to use the 672 SCTP_INITMSG socket option before calling sendto(). Or it can use 673 SCTP_INIT type sendmsg() to initiate an association without doing 674 the setsockopt(). 676 SCTP does not support half close semantics. This means that unlike 677 T/TCP, MSG_EOF should not be set in the flags parameter when calling 678 sendto() or sendmsg() when the call is used to initiate a 679 connection. MSG_EOF is not an acceptable flag with SCTP socket. 681 4.1.6 close() - TCP Style Syntax 683 Applications use close() to gracefully close down an association. 685 The syntax is: 687 int close(int sd); 689 sd - the socket descriptor of the association to be closed. 691 After an application calls close() on a socket descriptor, no 692 further socket operations will suceed on that descriptor. 694 4.1.7 shutdown() - TCP Style Syntax 696 SCTP differs from TCP in that it does not have half closed 697 semantics. Hence the shutdown() call for SCTP is an approximation 698 of the TCP shutdown() call, and solves some different problems. 699 Full TCP-compatibility is not provided, so developers porting TCP 700 applications to SCTP may need to recode sections that use 701 shutdown(). (Note that it is possible to achieve the same results 702 as half close in SCTP using SCTP streams.) 704 The syntax is: 706 int shutdown(int socket, int how); 708 sd - the socket descriptor of the association to be closed. 710 how - Specifies the type of shutdown. The values are 711 as follows: 713 SHUT_RD 714 Disables further receive operations. No SCTP 715 protocol action is taken. 717 SHUT_WR 718 Disables further send operations, and initiates 719 the SCTP shutdown sequence. 721 SHUT_RDWR 722 Disables further send and receive operations 723 and initiates the SCTP shutdown sequence. 725 The major difference between SCTP and TCP shutdown() is that SCTP 726 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 727 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 728 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 729 the SCTP association while still leaving the socket descriptor open, 730 so that the caller can receive back any data SCTP was unable to 731 deliver (see section 5.3.1.4 for more information). 733 To perform the ABORT operation described in [SCTP] section 10.1, an 734 application can use the socket option SO_LINGER. It is described in 735 section 7.1.4. 737 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax 739 With a TCP-style socket, the application can also use sendmsg() and 740 recvmsg() to transmit data to and receive data from its peer. The 741 semantics is similar to those used in the UDP-style model (section 742 3.1.3), with the following differences: 744 1) When sending, the msg_name field in the msghdr is not used to 745 specify the intended receiver, rather it is used to indicate a 746 different peer address if the sender does not want to send the 747 message over the primary address of the receiver. If the transport 748 address given is not part of the current association, the data will 749 not be sent and a SCTP_SEND_FAILED event will be delivered to the 750 application if send failure events are enabled. 752 When receiving, if a message is not received from the primary 753 address, the SCTP stack will fill in the msg_name field on return so 754 that the application can retrieve the source address information of 755 the received message. 757 2) An application must use close() to gracefully shutdown an 758 association, or use SO_LINGER option with close() to abort an 759 association. It must not use the MSG_ABORT or MSG_EOF flag in 760 sendmsg(). The system returns an error if an application tries to 761 do so. 763 4.1.9 getsockname() 765 Applications use getsockname() to retrieve the locally-bound socket 766 address of the specified socket. This is especially useful if the 767 caller let SCTP chose a local port. This call is for where the 768 endpoint is not multihomed. It does not work well with multi-homed 769 sockets. See section 8.5 for a multihomed version of the call. 771 The syntax is: 773 int getsockname(int socket, struct sockaddr *address, 774 socklen_t *len); 776 sd - the socket descriptor to be queried. 778 address - On return, one locally bound address (chosen by 779 the SCTP stack) is stored in this buffer. If the 780 socket is an IPv4 socket, the address will be IPv4. 781 If the socket is an IPv6 socket, the address will 782 be either an IPv6 or mapped IPv4 address. 784 len - The caller should set the length of address here. 785 On return, this is set to the length of the returned 786 address. 788 If the actual length of the address is greater than the length of 789 the supplied sockaddr structure, the stored address will be 790 truncated. 792 If the socket has not been bound to a local name, the value stored 793 in the object pointed to by address is unspecified. 795 4.1.10 getpeername() 797 Applications use getpeername() to retrieve the primary socket 798 address of the peer. This call is for TCP compatibility, and is not 799 multihomed.It does not work with UDP-style sockets. See section 8.3 800 for a multihomed/UDP-sockets version of the call. 802 The syntax is: 804 int getpeername(int socket, struct sockaddr *address, 805 socklen_t *len); 807 sd - the socket descriptor to be queried. 809 address - On return, the peer primary address is stored in 810 this buffer. If the socket is an IPv4 socket, the 811 address will be IPv4. If the socket is an IPv6 socket, 812 the address will be either an IPv6 or mapped IPv4 813 address. 815 len - The caller should set the length of address here. 816 On return, this is set to the length of the returned 817 address. 819 If the actual length of the address is greater than the length of 820 the supplied sockaddr structure, the stored address will be 821 truncated. 823 5. Data Structures 825 We discuss in this section important data structures which are 826 specific to SCTP and are used with sendmsg() and recvmsg() calls to 827 control SCTP endpoint operations and to access ancillary 828 information and notifications. 830 5.1 The msghdr and cmsghdr Structures 832 The msghdr structure used in the sendmsg() and recvmsg() calls, as 833 well as the ancillary data carried in the structure, is the key for 834 the application to set and get various control information from the 835 SCTP endpoint. 837 The msghdr and the related cmsghdr structures are defined and 838 discussed in details in [RFC2292]. Here we will cite their 839 definitions from [RFC2292]. 841 The msghdr structure: 843 struct msghdr { 844 void *msg_name; /* ptr to socket address structure */ 845 socklen_t msg_namelen; /* size of socket address structure */ 846 struct iovec *msg_iov; /* scatter/gather array */ 847 size_t msg_iovlen; /* # elements in msg_iov */ 848 void *msg_control; /* ancillary data */ 849 socklen_t msg_controllen; /* ancillary data buffer length */ 850 int msg_flags; /* flags on received message */ 851 }; 853 The cmsghdr structure: 855 struct cmsghdr { 856 socklen_t cmsg_len; /* #bytes, including this header */ 857 int cmsg_level; /* originating protocol */ 858 int cmsg_type; /* protocol-specific type */ 859 /* followed by unsigned char cmsg_data[]; */ 860 }; 862 In the msghdr structure, the usage of msg_name has been discussed in 863 previous sections (see Sections 3.1.3 and 4.1.8). 865 The scatter/gather buffers, or I/O vectors (pointed to by the 866 msg_iov field) are treated as a single SCTP data chunk, rather than 867 multiple chunks, for both sendmsg() and recvmsg(). 869 The msg_flags are not used when sending a message with sendmsg(). 871 If a notification has arrived, recvmsg() will return the 872 notification with the MSG_NOTIFICATION flag set in msg_flags. If the 873 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 874 section 5.3 for more information about notifications. 876 If all portions of a data frame or notification have been read, 877 recvmsg() will return with MSG_EOR set in msg_flags. 879 5.2 SCTP msg_control Structures 881 A key element of all SCTP-specific socket extensions is the use of 882 ancillary data to specify and access SCTP-specific data via the 883 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 884 Fine-grained control over initialization and sending parameters are 885 handled with ancillary data. 887 Each ancillary data item is preceeded by a struct cmsghdr (see 888 Section 5.1), which defines the function and purpose of the data 889 contained in in the cmsg_data[] member. 891 There are two kinds of ancillary data used by SCTP: initialization 892 data, and, header information (SNDRCV). Initialization data 893 (UDP-style only) sets protocol parameters for new associations. 894 Section 5.2.1 provides more details. Header information can set or 895 report parameters on individual messages in a stream. See section 896 5.2.2 for how to use SNDRCV ancillary data. 898 By default on a TCP-style socket, SCTP will pass no ancillary data; 899 on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and 900 SCTP_ASSOC_CHANGE information. Specific ancillary data items can be 901 enabled with socket options defined for SCTP; see section 7.3. 903 Note that all ancillary types are fixed length; see section 5.4 for 904 further discussion on this. These data structures use struct 905 sockaddr_storage (defined in [RFC2553]) as a portable, fixed length 906 address format. 908 Other protocols may also provide ancillary data to the socket layer 909 consumer. These ancillary data items from other protocols may 910 intermingle with SCTP data. For example, the IPv6 socket API 911 definitions ([RFC2292] and [RFC2553]) define a number of ancillary 912 data items. If a socket API consumer enables delivery of both SCTP 913 and IPv6 ancillary data, they both may appear in the same 914 msg_control buffer in any order. An application may thus need to 915 handle other types of ancillary data besides that passed by SCTP. 917 The sockets application must provide a buffer large enough to 918 accomodate all ancillary data provided via recvmsg(). If the buffer 919 is not large enough, the ancillary data will be truncated and the 920 msghdr's msg_flags will include MSG_CTRUNC. 922 5.2.1 SCTP Initiation Structure (SCTP_INIT) 924 This cmsghdr structure provides information for initializing new 925 SCTP associations with sendmsg(). The SCTP_INITMSG socket option 926 uses this same data structure. This structure is not used for 927 recvmsg(). 929 cmsg_level cmsg_type cmsg_data[] 930 ------------ ------------ ---------------------- 931 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 933 Here is the definition of the sctp_initmsg structure: 935 struct sctp_initmsg { 936 uint16_t sinit_num_ostreams; 937 uint16_t sinit_max_instreams; 938 uint16_t sinit_max_attempts; 939 uint16_t sinit_max_init_timeo; 940 }; 942 sinit_num_ostreams: 16 bits (unsigned integer) 944 This is an integer number representing the number of streams that 945 the application wishes to be able to send to. This number is 946 confirmed in the COMMUNICATION_UP notification and must be verified 947 since it is a negotiated number with the remote endpoint. The 948 default value of 0 indicates to use the endpoint default value. 950 sinit_max_instreams: 16 bits (unsigned integer) 952 This value represents the maximum number of inbound streams the 953 application is prepared to support. This value is bounded by the 954 actual implementation. In other words the user MAY be able to 955 support more streams than the Operating System. In such a case, the 956 Operating System limit overrides the value requested by the 957 user. The default value of 0 indicates to use the endpoint's default 958 value. 960 sinit_max_attempts: 16 bits (unsigned integer) 962 This integer specifies how many attempts the SCTP endpoint should 963 make at resending the INIT. This value overrides the system SCTP 964 'Max.Init.Retransmits' value. The default value of 0 indicates to 965 use the endpoint's default value. This is normally set to the 966 system's default 'Max.Init.Retransmit' value. 968 sinit_max_init_timeo: 16 bits (unsigned integer) 970 This value represents the largest Time-Out or RTO value to use in 971 attempting a INIT. Normally the 'RTO.Max' is used to limit the 972 doubling of the RTO upon timeout. For the INIT message this value 973 MAY override 'RTO.Max'. This value MUST NOT influence 'RTO.Max' 974 during data transmission and is only used to bound the initial setup 975 time. A default value of 0 indicates to use the endpoint's default 976 value. This is normally set to the system's 'RTO.Max' value (60 977 seconds). 979 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 981 This cmsghdr structure specifies SCTP options for sendmsg() and 982 describes SCTP header information about a received message through 983 recvmsg(). 985 cmsg_level cmsg_type cmsg_data[] 986 ------------ ------------ ---------------------- 987 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 989 Here is the defintion of sctp_sndrcvinfo: 991 struct sctp_sndrcvinfo { 992 uint16_t sinfo_stream; 993 uint16_t sinfo_ssn; 994 uint16_t sinfo_flags; 995 uint32_t sinfo_ppid; 996 uint32_t sinfo_context; 997 uint32_t sinfo_timetolive; 998 sctp_assoc_t sinfo_assoc_id; 999 }; 1001 sinfo_stream: 16 bits (unsigned integer) 1003 For recvmsg() the SCTP stack places the message's stream number in 1004 this value. For sendmsg() this value holds the stream number that 1005 the application wishes to send this message to. If a sender 1006 specifies an invalid stream number an error indication is returned 1007 and the call fails. 1009 sinfo_ssn: 16 bits (unsigned integer) 1011 For recvmsg() this value contains the stream sequence number that 1012 the remote endpoint placed in the DATA chunk. For fragmented 1013 messages this is the same number for all deliveries of the message 1014 (if more than one recvmsg() is needed to read the message). The 1015 sendmsg() call will ignore this parameter. 1017 sinfo_ppid: 32 bits (unsigned integer) 1019 This value in sendmsg() is an opaque unsigned value that is passed 1020 to the remote end in each user message. In recvmsg() this value is 1021 the same information that was passed by the upper layer in the peer 1022 application. Please note that byte order issues are NOT accounted 1023 for and this information is passed opaquely by the SCTP stack from 1024 one end to the other. 1026 sinfo_context: 32 bits (unsigned integer) 1028 This value is an opaque 32 bit context datum that is used in the 1029 sendmsg() function. This value is passed back to the upper layer if 1030 a error occurs on the send of a message and is retrieved with each 1031 undelivered message (Note: if a endpoint has done multple sends, all 1032 of which fail, multiple different sinfo_context values will be 1033 returned. One with each user data message). 1035 sinfo_flags: 16 bits (unsigned integer) 1037 This field may contain any of the following flags and is composed of 1038 a bitwise OR of these values. 1040 recvmsg() flags: 1042 MSG_UNORDERED - This flag is present when the message was sent 1043 non-ordered. 1045 sendmsg() flags: 1047 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1048 message. If this flag is clear the datagram is 1049 considered an ordered send. 1051 MSG_ADDR_OVER - This flag, in the UDP model, requests the SCTP 1052 stack to override the primary destination address 1053 with the address found with the sendto/sendmsg 1054 call. 1056 MSG_ABORT - Setting this flag causes the specified association 1057 to abort by sending an ABORT message to the peer 1058 (UDP-style only). 1060 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1061 procedures on the specified association. Graceful 1062 shutdown assures that all data enqueued by both 1063 endpoints is successfully transmitted before closing 1064 the association (UDP-style only). 1066 sinfo_timetolive: 32 bit (unsigned integer) 1068 For the sending side, this field contains the message time 1069 to live in milliseconds. The sending side wil expire the 1070 message within the specified time period if the message as 1071 not been sent to the peer within this time period. 1073 sinfo_assoc_id: sizeof (sctp_assoc_t) 1075 The association handle field, sinfo_assoc_id, holds the identifier 1076 for the association announced in the COMMUNICATION_UP notification. 1077 All notifications for a given association have the same identifier. 1078 Ignored for TCP-style sockets. 1080 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1082 5.3 SCTP Events and Notifications 1084 An SCTP application may need to understand and process events and 1085 errors that happen on the SCTP stack. These events include network 1086 status changes, association startups, remote operational errors and 1087 undeliverable messages. All of these can be essential for the 1088 application. 1090 When an SCTP application layer does a recvmsg() the message read is 1091 normally a data message from a peer endpoint. If the application 1092 wishes to have the SCTP stack deliver notifications of non-data 1093 events, it sets the appropriate socket option for the notifications 1094 it wants. See section 7.3 for these socket options. When a 1095 notification arrives, recvmsg() returns the notification in the 1096 application-supplied data buffer via msg_iov, and sets 1097 MSG_NOTIFICATION in msg_flags. 1099 Multiple notifications may be returned to a single recvmsg() 1100 call. 1102 This section details the notification structures. Every 1103 notification structure carries some common fields which provides 1104 general information. 1106 A recvmsg() call will return only one notification at a time. Just 1107 as when reading normal data, it may return part of a notification if 1108 the msg_iov buffer is not large enough. If a single read is not 1109 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1110 reading the notification before subsequent data can arrive. 1112 5.3.1 SCTP Notification Structure 1114 The notification structure is defined as the union of all 1115 notification types. 1117 union sctp_notification { 1118 struct { 1119 uint16_t sn_type; /* Notification type. */ 1120 uint16_t sn_flags; 1121 uint32_t sn_length; 1122 } h; 1123 struct sctp_assoc_change sn_assoc_change; 1124 struct sctp_paddr_change sn_padr_change; 1125 struct sctp_remote_error sn_remote_error; 1126 struct sctp_send_failed sn_send_failed; 1127 struct sctp_shutdown_event sn_shutdown_event; 1128 }; 1130 sn_type: 16 bits (unsigned integer) 1132 The following table describes the SCTP notification and event types 1133 for the field sn_type. 1135 sn_type Description 1136 --------- --------------------------- 1138 SCTP_ASSOC_CHANGE This tag indicates that an 1139 association has either been 1140 opened or closed. Refer to 1141 5.3.1.1 for details. 1143 SCTP_PEER_ADDR_CHANGE This tag indicates that an 1144 address that is part of an existing 1145 association has experienced a 1146 change of state (e.g. a failure 1147 or return to service of the 1148 reachability of a endpoint 1149 via a specific transport 1150 address). Please see 5.3.1.2 1151 for data structure details. 1153 SCTP_REMOTE_ERROR The attached error message 1154 is an Operational Error received from 1155 the remote peer. It includes the complete 1156 TLV sent by the remote endpoint. 1157 See section 5.3.1.3 for the detailed format. 1159 SCTP_SEND_FAILED The attached datagram 1160 could not be sent to the remote endpoint. 1161 This structure includes the 1162 original SCTP_SNDRCVINFO 1163 that was used in sending this 1164 message i.e. this structure 1165 uses the sctp_sndrecvinfo per 1166 section 5.3.1.4. 1168 SCTP_SHUTDOWN_EVENT The peer has sent a SHUTDOWN. No further 1169 data should be sent on this socket. 1171 All standard values for sn_type flags are greater than 2^15. 1172 Values from 2^15 and down are reserved. 1174 sn_flags: 16 bits (unsigned integer) 1176 These are notification-specific flags. 1178 sn_length: 32 bits (unsigned integer) 1180 This is the length of the whole sctp_notification structure 1181 including the sn_type, sn_flags, and sn_length fields. 1183 5.3.1.1 SCTP_ASSOC_CHANGE 1185 Communication notifications inform the ULP that an SCTP association 1186 has either begun or ended. The identifier for a new association is 1187 provided by this notificaion. The notification information has the 1188 following format: 1190 struct sctp_assoc_change { 1191 uint16_t sac_type; 1192 uint16_t sac_flags; 1193 uint32_t sac_length; 1194 uint16_t sac_state; 1195 uint16_t sac_error; 1196 uint16_t sac_outbound_streams; 1197 uint16_t sac_inbound_streams; 1198 sctp_assoc_t sac_assoc_id; 1199 }; 1201 sac_type: 1203 It should be SCTP_ASSOC_CHANGE. 1205 sac_flags: 16 bits (unsigned integer) 1207 Currently unused. 1209 sac_length: 32 bits (unsigned integer) 1211 This field is the total length of the notification data, including 1212 the notification header. 1214 sac_state: 32 bits (signed integer) 1216 This field holds one of a number of values that communicate the 1217 event that happened to the association. They include: 1219 Event Name Description 1220 ---------------- --------------- 1221 COMMUNICATION_UP A new association is now ready 1222 and data may be exchanged with this 1223 peer. 1225 COMMUNICATION_LOST The association has failed. The association 1226 is now in the closed state. If SEND FAILED 1227 notifications are turned on, a COMMUNICATION_LOST 1228 is followed by a series of SCTP_SEND_FAILED 1229 events, one for each outstanding message. 1231 RESTART SCTP has detected that the peer has restarted. 1233 SHUTDOWN_COMPLETE The association has gracefully closed. 1235 CANT_START_ASSOC The association failed to setup. If non blocking 1236 mode is set and data was sent (in the udp mode), 1237 a CANT_START_ASSOC is followed by a series of 1238 SCTP_SEND_FAILED events, one for each outstanding 1239 message. 1241 sac_error: 32 bits (signed integer) 1243 If the state was reached due to a error condition (e.g. 1244 COMMUNICATION_LOST) any relevant error information is available in 1245 this field. This corresponds to the protocol error codes defined in 1246 [SCTP]. 1248 sac_outbound_streams: 16 bits (unsigned integer) 1249 sac_inbound_streams: 16 bits (unsigned integer) 1251 The maximum number of streams allowed in each direction are 1252 available in sac_outbound_streams and sac_inbound streams. 1254 sac_assoc_id: sizeof (sctp_assoc_t) 1256 The association id field, holds the identifier for the association. 1257 All notifications for a given association have the same association 1258 identifier. For TCP style socket, this field is ignored. 1260 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1262 When a destination address on a multi-homed peer encounters a change 1263 an interface details event is sent. The information has the 1264 following structure: 1266 struct sctp_paddr_change { 1267 uint16_t spc_type; 1268 uint16_t spc_flags; 1269 uint32_t spc_length; 1270 struct sockaddr_storage spc_aaddr; 1271 int spc_state; 1272 int spc_error; 1273 sctp_assoc_t spc_assoc_id; 1274 } 1276 spc_type: 1278 It should be SCTP_PEER_ADDR_CHANGE. 1280 spc_flags: 16 bits (unsigned integer) 1282 Currently unused. 1284 spc_length: 32 bits (unsigned integer) 1286 This field is the total length of the notification data, including 1287 the notification header. 1289 spc_aaddr: sizeof (struct sockaddr_storage) 1291 The affected address field, holds the remote peer's address that is 1292 encountering the change of state. 1294 spc_state: 32 bits (signed integer) 1296 This field holds one of a number of values that communicate the 1297 event that happened to the address. They include: 1299 Event Name Description 1300 ---------------- --------------- 1301 ADDRESS_AVAILABLE This address is now reachable. 1303 ADDRESS_UNREACHABLE The address specified can no 1304 longer be reached. Any data sent 1305 to this address is rerouted to an 1306 alternate until this address becomes 1307 reachable. 1309 ADDRESS_REMOVED The address is no longer part of 1310 the association. 1312 ADDRESS_ADDED The address is now part of the 1313 association. 1315 ADDRESS_MADE_PRIM This address has now been made 1316 to be the primary destination address. 1318 spc_error: 32 bits (signed integer) 1320 If the state was reached due to any error condition (e.g. 1321 ADDRESS_UNREACHABLE) any relevant error information is available in 1322 this field. 1324 spc_assoc_id: sizeof (sctp_assoc_t) 1326 The association id field, holds the identifier for the association. 1327 All notifications for a given association have the same association 1328 identifier. For TCP style socket, this field is ignored. 1330 5.3.1.3 SCTP_REMOTE_ERROR 1332 A remote peer may send an Operational Error message to its peer. 1333 This message indicates a variety of error conditions on an 1334 association. The entire error TLV as it appears on the wire is 1335 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1336 specification [SCTP] and any extensions for a list of possible 1337 error formats. SCTP error TLVs have the format: 1339 struct sctp_remote_error { 1340 uint16_t sre_type; 1341 uint16_t sre_flags; 1342 uint32_t sre_length; 1343 uint16_t sre_error; 1344 sctp_assoc_t sre_assoc_id; 1345 uint8_t sre_data[0]; 1346 }; 1347 sre_type: 1349 It should be SCTP_REMOTE_ERROR. 1351 sre_flags: 16 bits (unsigned integer) 1353 Currently unused. 1355 sre_length: 32 bits (unsigned integer) 1357 This field is the total length of the notification data, including 1358 the notification header and the contents of sre_data. 1360 sre_error: 16 bits (unsigned integer) 1362 This value represents one of the Operational Error causes defined in 1363 the SCTP specification, in network byte order. 1365 sre_assoc_id: sizeof (sctp_assoc_t) 1367 The association id field, holds the identifier for the association. 1368 All notifications for a given association have the same association 1369 identifier. For TCP style socket, this field is ignored. 1371 sre_data: variable 1373 This contains the payload of the operational error as defined in the 1374 SCTP specification [SCTP] section 3.3.10. 1376 5.3.1.4 SCTP_SEND_FAILED 1378 If SCTP cannot deliver a message it may return the message as a 1379 notification. 1381 struct sctp_send_failed { 1382 uint16_t ssf_type; 1383 uint16_t ssf_flags; 1384 uint32_t ssf_length; 1385 uint32_t ssf_error; 1386 struct sctp_sndrcvinfo ssf_info; 1387 sctp_assoc_t ssf_assoc_id; 1388 uint8_t ssf_data[0]; 1389 }; 1391 ssf_type: 1393 It should be SCTP_SEND_FAILED. 1395 ssf_flags: 16 bits (unsigned integer) 1397 The flag value will take one of the following values 1399 SCTP_DATA_UNSENT - Indicates that the data was never put on 1400 the wire. 1402 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1403 Note that this does not necessarily mean that the 1404 data was (or was not) successfully delivered. 1406 ssf_length: 32 bits (unsigned integer) 1408 This field is the total length of the notification data, including 1409 the notification header and the payload in ssf_data. 1411 ssf_error: 16 bits (unsigned integer) 1413 This value represents the reason why the send failed, and if set, 1414 will be a SCTP protocol error code as defined in [SCTP] section 1415 3.3.10. 1417 ssf_info: sizeof (struct sctp_sndrcvinfo) 1419 The original send information associated with the undelivered 1420 message. 1422 ssf_assoc_id: sizeof (sctp_assoc_t) 1424 The association id field, sf_assoc_id, holds the identifier for the 1425 association. All notifications for a given association have the 1426 same association identifier. For TCP style socket, this field is 1427 ignored. 1429 ssf_data: variable length 1431 The undelivered message, exactly as delivered by the caller to the 1432 original send*() call. 1434 5.3.1.5 SCTP_SHUTDOWN_EVENT 1436 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1437 inform the application that it should cease sending data. 1439 struct sctp_shutdown_event { 1440 uint16_t sse_type; 1441 uint16_t sse_flags; 1442 uint32_t sse_length; 1443 uint16_t sse_flags; 1444 sctp_assoc_t sse_assoc_id; 1445 }; 1447 sse_type 1449 It should be SCTP_SHUTDOWN_EVENT 1451 sse_flags: 16 bits (unsigned integer) 1453 Currently unused. 1455 sse_length: 32 bits (unsigned integer) 1457 This field is the total length of the notification data, including 1458 the notification header. It will generally be 1459 sizeof (struct sctp_shutdown_event). 1461 sse_flags: 16 bits (unsigned integer) 1463 Currently unused. 1465 sse_assoc_id: sizeof (sctp_assoc_t) 1467 The association id field, holds the identifier for the association. 1468 All notifications for a given association have the same association 1469 identifier. For TCP style socket, this field is ignored. 1471 5.3.1.6 SCTP_ADAPTION_INDICATION 1473 When a peer sends a Adaption Layer Indication parameter , SCTP 1474 delivers this notification to inform the application 1475 that of the peers requested adaption layer. 1477 struct sctp_adaption_event { 1478 uint16_t sai_type; 1479 uint16_t sai_flags; 1480 uint32_t sai_length; 1481 uint32_t sai_adaptation_bits; 1482 sctp_assoc_t sse_assoc_id; 1483 }; 1485 sai_type 1487 It should be SCTP_ADAPTION_INDICATION 1489 sai_flags: 16 bits (unsigned integer) 1491 Currently unused. 1493 sai_length: 32 bits (unsigned integer) 1495 This field is the total length of the notification data, including 1496 the notification header. It will generally be 1497 sizeof (struct sctp_adaption_event). 1499 sai_adaption_bits: 32 bits (unsigned integer) 1501 This field holds the bit array sent by the peer in the 1502 adaption layer indication parameter. The bits are in 1503 network byte order. 1505 sai_assoc_id: sizeof (sctp_assoc_t) 1506 The association id field, holds the identifier for the association. 1507 All notifications for a given association have the same association 1508 identifier. For TCP style socket, this field is ignored. 1510 5.4 Ancillary Data Considerations and Semantics 1512 Programming with ancillary socket data contains some subtleties and 1513 pitfalls, which are discussed below. 1515 5.4.1 Multiple Items and Ordering 1517 Multiple ancillary data items may be included in any call to 1518 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1519 items, or both. 1521 The ordering of ancillary data items (either by SCTP or another 1522 protocol) is not significant and is implementation-dependant, so 1523 applications must not depend on any ordering. 1525 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1526 msg_iov member. There can be only a single SCTP_SNDRCV info for 1527 each sendmsg() or recvmsg() call. 1529 5.4.2 Accessing and Manipulating Ancillary Data 1531 Applications can infer the presence of data or ancillary data by 1532 examining the msg_iovlen and msg_controllen msghdr members, 1533 respectively. 1535 Implementations may have different padding requirements for 1536 ancillary data, so portable applications should make use of the 1537 macros CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and 1538 CMSG_LEN. See [RFC2292] and your SCTP implementation's documentation 1539 for more information. Following is an example, from [RFC2292], 1540 demonstrating the use of these macros to access ancillary data: 1542 struct msghdr msg; 1543 struct cmsghdr *cmsgptr; 1545 /* fill in msg */ 1547 /* call recvmsg() */ 1549 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1550 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1551 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1552 u_char *ptr; 1554 ptr = CMSG_DATA(cmsgptr); 1555 /* process data pointed to by ptr */ 1556 } 1557 } 1559 5.4.3 Control Message Buffer Sizing 1561 The information conveyed via SCTP_SNDRCV events will often be 1562 fundamental to the correct and sane operation of the sockets 1563 application. This is particularly true of the UDP semantics, but 1564 also of the TCP semantics. For example, if an application needs to 1565 send and receive data on different SCTP streams, SCTP_SNDRCV events 1566 are indispensable. 1568 Given that some ancillary data is critical, and that multiple 1569 ancillary data items may appear in any order, applications should be 1570 carefully written to always provide a large enough buffer to contain 1571 all possible ancillary data that can be presented by recvmsg(). If 1572 the buffer is too small, and crucial data is truncated, it may pose 1573 a fatal error condition. 1575 Thus it is essential that applications be able to deterministically 1576 calculate the maximum required buffer size to pass to recvmsg(). One 1577 constraint imposed on this specification that makes this possible is 1578 that all ancillary data definitions are of a fixed length. One way 1579 to calculate the maximum required buffer size might be to take the 1580 sum the sizes of all enabled ancillary data item structures, as 1581 calculated by CMSG_SPACE. For example, if we enabled 1582 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC2292], we would calculate 1583 and allocate the buffer size as follows: 1585 size_t total; 1586 void *buf; 1588 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1589 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1591 buf = malloc(total); 1593 We could then use this buffer for msg_control on each call to 1594 recvmsg() and be assured that we would not lose any ancillary data 1595 to truncation. 1597 6. Common Operations for Both Styles 1599 6.1 send(), recv(), sendto(), recvfrom() 1601 Applications can use send() and sendto() to transmit data to the 1602 peer of an SCTP endpoint. recv() and recvfrom() can be used to 1603 receive data from the peer. 1605 The syntax is: 1607 ssize_t send(int sd, connst void *msg, size_t len, int flags); 1608 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1609 const struct sockaddr *to, int tolen); 1610 ssize_t recv(int sd, void *buf, size_t len, int flags); 1611 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1612 struct sockaddr *from, int *fromlen); 1614 sd - the socket descriptor of an SCTP endpoint. 1615 msg - the message to be sent. 1616 len - the size of the message or the size of buffer. 1617 to - one of the peer addresses of the association to be 1618 used to send the message. 1619 tolen - the size of the address. 1620 buf - the buffer to store a received message. 1621 from - the buffer to store the peer address used to send the 1622 received message. 1623 fromlen - the size of the from address 1624 flags - (described below). 1626 These calls give access to only basic SCTP protocol features. If 1627 either peer in the association uses multiple streams, or sends 1628 unordered data these calls will usually be inadequate, and may 1629 deliver the data in unpredictable ways. 1631 SCTP has the concept of multiple streams in one association. The 1632 above calls do not allow the caller to specify on which stream a 1633 message should be sent. The system uses stream 0 as the default 1634 stream for send() and sendto(). recv() and recvfrom() return data 1635 from any stream, but the caller can not distinguish the different 1636 streams. This may result in data seeming to arrive out of 1637 order. Similarly, if a data chunk is sent unordered, recv() and 1638 recvfrom() provide no indication. 1640 SCTP is message based. The msg buffer above in send() and sendto() 1641 is considered to be a single message. This means that if the caller 1642 wants to send a message which is composed by several buffers, the 1643 caller needs to combine them before calling send() or sendto(). 1644 Alternately, the caller can use sendmsg() to do that without 1645 combining them. recv() and recvfrom() cannot distinguish message 1646 boundaries. 1648 In receiving, if the buffer supplied is not large enough to hold a 1649 complete message, the receive call acts like a stream socket and 1650 returns as much data as will fit in the buffer. 1652 Note, the send and recv calls, when used in the UDP-style model, may 1653 only be used with branched off socket descriptors (see Section 8.2). 1655 6.2 setsockopt(), getsockopt() 1657 Applications use setsockopt() and getsockopt() to set or retrieve 1658 socket options. Socket options are used to change the default 1659 behavior of sockets calls. They are described in Section 7. 1661 The syntax is: 1663 ret = getsockopt(int sd, int level, int optname, void *optval, 1664 size_t *optlen); 1665 ret = setsockopt(int sd, int level, int optname, const void *optval, 1666 size_t optlen); 1668 sd - the socket descript. 1669 level - set to IPPROTO_SCTP for all SCTP options. 1670 optname - the option name. 1671 optval - the buffer to store the value of the option. 1672 optlen - the size of the buffer (or the length of the option 1673 returned). 1675 6.3 read() and write() 1677 Applications can use read() and write() to send and receive data to 1678 and from peer. They have the same semantics as send() and recv() 1679 except that the flags parameter cannot be used. 1681 Note, these calls, when used in the UDP-style model, may only be 1682 used with branched off socket descriptors (see Section 8.2). 1684 7. Socket Options 1686 The following sub-section describes various SCTP level socket 1687 options that are common to both models. SCTP associations can be 1688 multihomed. Therefore, certain option parameters include a 1689 sockaddr_storage structure to select which peer address the option 1690 should be applied to. 1692 For the UDP-style sockets, an sctp_assoc_t structure (association 1693 ID) is used to identify the the association instance that the 1694 operation affects. So it must be set when using this model. 1696 For the TCP-style sockets and branched off UDP-style sockets (see 1697 section 8.2) this association ID parameter is ignored. In the cases 1698 noted below where the parameter is ignored, an application can pass 1699 to the system a corresponding option structure similar to those 1700 described below but without the association ID parameter, which 1701 should be the last field of the option structure. This can make the 1702 option setting/getting operation more efficient. If an application 1703 does this, it should also specify an appropriate optlen value 1704 (i.e. sizeof (option parameter) - sizeof (struct sctp_assoc_t)). 1706 Note that socket or IP level options is set or retrieved per socket. 1707 This means that for UDP-style sockets, those options will be applied 1708 to all associations belonging to the socket. And for TCP-style 1709 model, those options will be applied to all peer addresses of the 1710 association controlled by the socket. Applications should be very 1711 careful in setting those options. 1713 7.1 Read / Write Options 1715 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1717 The protocol parameters used to initialize and bound retransmission 1718 timeout (RTO) are tunable. See [SCTP] for more information on how 1719 these parameters are used in RTO calculation. The peer address 1720 parameter is ignored for TCP style socket. 1722 The following structure is used to access and modify these 1723 parameters: 1725 struct sctp_rtoinfo { 1726 uint32_t srto_initial; 1727 uint32_t srto_max; 1728 uint32_t srto_min; 1729 sctp_assoc_t srto_assoc_id; 1730 }; 1732 srto_initial - This contains the initial RTO value. 1733 srto_max and srto_min - These contain the maximum and minumum bounds 1734 for all RTOs. 1735 srto_assoc_id - (UDP style socket) This is filled in the application, 1736 and identifies the association for this query. If 1737 this parameter is missing (on a UDP style socket), 1738 then the change effects the entire endpoint. 1740 All parameters are time values, in milliseconds. A value of 0, when 1741 modifying the parameters, indicates that the current value should 1742 not be changed. 1744 To access or modify these parameters, the application should call 1745 getsockopt or setsockopt() respectively with the option name 1746 SCTP_RTOINFO. 1748 7.1.2 Association Retransmission Parameter (SCTP_ASSOCRTXINFO) 1750 The protocol parameter used to set the number of retransmissions 1751 sent before an association is considered unreachable. 1752 See [SCTP] for more information on how this parameter is used. The 1753 peer address parameter is ignored for TCP style socket. 1755 The following structure is used to access and modify this 1756 parameters: 1758 struct sctp_assocparams { 1759 uint16_t sasoc_asocmaxrxt; 1760 sctp_assoc_t sasoc_assoc_id; 1761 }; 1763 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 1764 to make for the association. 1765 sasoc_assoc_id - (UDP style socket) This is filled in the application, 1766 and identifies the association for this query. 1768 To access or modify these parameters, the application should call 1769 getsockopt or setsockopt() respectively with the option name 1770 SCTP_ASSOCRTXINFO. 1772 The maximum number of retransmissions before an address is 1773 considered unreachable is also tunable, but is address-specific, so 1774 it is covered in a seperate option. If an application attempts to 1775 set the value of the association maximum retransmission parameter to 1776 more than the sum of all maximum retransmission parameters, 1777 setsockopt() shall return an error. The reason for this, from 1778 [SCTP] section 8.2: 1780 Note: When configuring the SCTP endpoint, the user should avoid 1781 having the value of 'Association.Max.Retrans' larger than the 1782 summation of the 'Path.Max.Retrans' of all the destination addresses 1783 for the remote endpoint. Otherwise, all the destination addresses 1784 may become inactive while the endpoint still considers the peer 1785 endpoint reachable. 1787 7.1.3 Initialization Parameters (SCTP_INITMSG) 1789 Applications can specify protocol parameters for the default 1790 association intialization. The structure used to access and modify 1791 these parameters is defined in section 5.2.1. The option name 1792 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 1794 Setting initialization parameters is effective only on an 1795 unconnected socket (for UDP-style sockets only future associations 1796 are effected by the change). With TCP-style sockets, this option is 1797 inherited by sockets derived from a listener socket. 1799 7.1.4 SO_LINGER 1801 An application using the TCP-style socket can use this option to 1802 perform the SCTP ABORT primitive. The linger option structure is: 1804 struct linger { 1805 int l_onoff; /* option on/off */ 1806 int l_linger; /* linger time */ 1807 }; 1809 To enable the option, set l_onoff to 1. If the l_linger value is 1810 set to 0, calling close() is the same as the ABORT primitive. If 1811 the value is set to a negative value, the setsockopt() call will 1812 return an error. If the value is set to a positive value 1813 linger_time, the close() can be blocked for at most linger_time ms. 1814 If the graceful shutdown phase does not finish during this period, 1815 close() will return but the graceful shutdown phase continues in the 1816 system. 1818 7.1.5 SCTP_NODELAY 1820 Turn off any Nagle-like algorithm. This means that packets are 1821 generally sent as soon as possible and no unnecessary delays are 1822 introduced, at the cost of more packets in the network. Expects an 1823 integer boolean flag. 1825 7.1.6 SO_RCVBUF 1827 Sets receive buffer size. For SCTP TCP-style sockets, this controls 1828 the receiver window size. For UDP-style sockets, this controls the 1829 receiver window size for all associations bound to the socket 1830 descriptor used in the setsockopt() or getsockopt() call. The option 1831 applies to each association's window size seperately. Expects an 1832 integer. 1834 7.1.7 SO_SNDBUF 1836 Sets send buffer size. For SCTP TCP-style sockets, this controls the 1837 amount of data SCTP may have waiting in internal buffers to be 1838 sent. This option therefore bounds the maximum size of data that can 1839 be sent in a single send call. For UDP-style sockets, the effect is 1840 the same, except that it applies to all associations bound to the 1841 socket descriptor used in the setsockopt() or getsockopt() call. The 1842 option applies to each association's window size seperately. Expects 1843 an integer. 1845 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 1847 This socket option is applicable to the UDP-style socket only. When 1848 set it will cause associations that are idle for more than the 1849 specified number of seconds to automatically close. An association 1850 being idle is defined an association that has NOT sent or received 1851 user data. The special value of '0' indicates that no automatic 1852 close of any associations should be performed. The option expects 1853 an integer defining the number of seconds of idle time before 1854 an association is closed. 1856 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) 1858 Requests that the peer mark the enclosed address as the association 1859 primary. The enclosed address must be one of the association's 1860 locally bound addresses. The following structure is used to make a 1861 set primary request: 1863 struct sctp_setprim { 1864 struct sockaddr_storage ssp_addr; 1865 sctp_assoc_t ssp_assoc_id; 1866 }; 1868 ssp_addr The address to set as primary 1869 ssp_assoc_id (UDP style socket) This is filled in by the 1870 application, and identifies the association 1871 for this request. 1873 This functionality is optional. Implementations that do not support 1874 this functionality should return EOPNOTSUPP. 1876 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 1878 Requests that the local SCTP stack use the enclosed peer address as 1879 the association primary. The enclosed address must be one of the 1880 association peer's addresses. The following structure is used to 1881 make a set peer primary request: 1883 struct sctp_setpeerprim { 1884 struct sockaddr_storage sspp_addr; 1885 sctp_assoc_t sspp_assoc_id; 1886 }; 1888 sspp_addr The address to set as primary 1889 sspp_assoc_id (UDP style socket) This is filled in by the 1890 application, and identifies the association 1891 for this request. 1893 7.1.11 Set Adaption Layer Bits (SCTP_SET_ADAPTION_LAYER_BITS) 1895 Requests that the local endpoint set the indicated bits 1896 in its Adaption Layer Indication parameter for all future 1897 INIT and INIT-ACK exchanges. 1899 struct sctp_setadaption_bits { 1900 u_int32_t ssb_bit_array; 1901 } 1903 ssb_bit_array The adaption layer bits that will be included 1904 in any outgoing Adaption Layer Indication 1905 parameter. 1907 7.2 Read-Only Options 1909 7.2.1 Association Status (SCTP_STATUS) 1911 Applications can retrieve current status information about an 1912 association, including association state, peer receiver window size, 1913 number of unacked data chunks, and number of data chunks pending 1914 receipt. This information is read-only. The following structure is 1915 used to access this information: 1917 struct sctp_status { 1918 int32_t sstat_state; 1919 uint32_t sstat_rwnd; 1920 uint16_t sstat_unackdata; 1921 uint16_t sstat_penddata; 1922 struct sctp_paddrinfo sstat_primary; 1923 sctp_assoc_t sstat_assoc_id; 1924 }; 1926 sstat_state - This contains the association's current state one 1927 of the following values: 1929 SCTP_CLOSED 1930 SCTP_BOUND 1931 SCTP_LISTEN 1932 SCTP_COOKIE_WAIT 1933 SCTP_COOKIE_ECHOED 1934 SCTP_ESTABLISHED 1935 SCTP_SHUTDOWN_PENDING 1936 SCTP_SHUTDOWN_SENT 1937 SCTP_SHUTDOWN_RECEIVED 1938 SCTP_SHUTDOWN_ACK_SENT 1940 sstat_rwnd - This contains the association peer's current 1941 receiver window size. 1942 sstat_unackdata - This is the number of unacked data chunks. 1943 sstat_penddata - This is the number of data chunks pending receipt. 1944 sstat_primary - This is information on the current primary peer 1945 address. 1946 sstat_assoc_id - (UDP style socket) This holds the an identifier for the 1947 association. All notifications for a given association 1948 have the same association identifier. 1950 To access these status values, the application calls getsockopt() 1951 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 1952 ignored for TCP style socket. 1954 7.3. Ancillary Data and Notification Interest Options 1956 Applications can receive per-message ancillary information and 1957 notifications of certain SCTP events with recvmsg(). 1959 The following optional information is available to the application: 1961 1. SCTP_RECVDATAIOEVNT: Per-message information (i.e. stream number, 1962 TSN, SSN, etc. described in section 5.2.2) 1963 2. SCTP_RECVASSOCEVNT: (described in section 5.3.1.1) 1964 3. SCTP_RECVPADDREVNT: (described in section 5.3.1.2) 1965 4. SCTP_RECVPEERERR: (described in section 5.3.1.3) 1966 5. SCTP_RECVSENDFAILEVNT: (described in section 5.3.1.4) 1967 6. SCTP_RECVSHUTDOWNEVNT: (described in section 5.3.1.5) 1968 7. SCTP_ADAPTION_INDICATION: (described in section 5.3.1.6) 1970 To receive any ancillary data or notifications, first the 1971 application registers it's interest by calling setsockopt() to turn 1972 on the corresponding flag: 1974 int on = 1; 1976 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, &on, sizeof(on)); 1977 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, &on, sizeof(on)); 1978 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, &on, sizeof(on)); 1979 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, &on, sizeof(on)); 1980 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, &on, sizeof(on)); 1981 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, &on, sizeof(on)); 1982 setsockopt(fd, IPPROTO_SCTP, SCTP_ADAPTION_INDICATION, &on, sizeof(on)); 1984 Note that for UDP-style SCTP sockets, the caller of recvmsg() 1985 receives ancillary data and notifications for ALL associations bound 1986 to the file descriptor. For TCP-style SCTP sockets, the caller 1987 receives ancillary data and notifications for only the single 1988 association bound to the file descriptor. 1990 By default a TCP-style socket has all options off. 1992 By default a UDP-style socket has SCTP_RECVDATAIOEVNT and 1993 SCTP_RECVASSOCEVNT on and all other options off. 1995 8. New Interfaces 1997 Depending on the system, the following interface can be implemented 1998 as a system call or library funtion. 2000 8.1 sctp_bindx() 2002 The syntax of sctp_bindx() is, 2004 int sctp_bindx(int sd, struct sockaddr_storage *addrs, int addrcnt, 2005 int flags); 2007 If sd is an IPv4 socket, the addresses passed must be IPv4 2008 addresses. If the sd is an IPv6 socket, the addresses passed can 2009 either be IPv4 or IPv6 addresses. 2011 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2012 section 3.1.2 for this usage. 2014 addrs is a pointer to an array of one or more socket addresses. 2015 Each address is contained in a struct sockaddr_storage, so each 2016 address is a fixed length. The caller specifies the number of 2017 addresses in the array with addrcnt. 2019 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2020 -1, and sets errno to the appropriate error code. 2022 For SCTP, the port given in each socket address must be the same, or 2023 sctp_bindx() will fail, setting errno to EINVAL. 2025 The flags parameter is formed from the bitwise OR of zero or more of 2026 the following currently defined flags: 2028 SCTP_BINDX_ADD_ADDR 2029 SCTP_BINDX_REM_ADDR 2031 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2032 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the 2033 given addresses from the association. The two flags are mutually 2034 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 2035 caller may not remove all addresses from an association; 2036 sctp_bindx() will reject such an attempt with EINVAL. 2038 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2039 additional addresses with an endpoint after calling bind(). Or use 2040 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2041 socket is associated with so that no new association accepted will 2042 be associated with those addresses. 2044 Adding and removing addresses from a connected association is 2045 optional functionality. Implementations that do not support this 2046 functionality should return EOPNOTSUPP. 2048 8.2 Branched-off Association 2050 After an association is established on a UDP-style socket, the 2051 application may wish to branch off the association into a separate 2052 socket/file descriptor. 2054 This is particularly desirable when, for instance, the application 2055 wishes to have a number of sporadic message senders/receivers remain 2056 under the original UDP-style socket but branch off those 2057 associations carrying high volume data traffic into their own 2058 separate socket descriptors. 2060 The application uses sctp_peeloff() call to branch off an 2061 association into a separate socket (Note the semantics are somewhat 2062 changed from the traditional TCP-style accept() call). 2064 The syntax is: 2066 new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id, int *addrlen) 2068 new_sd - the new socket descriptor representing the branched-off 2069 association. 2071 sd - the original UDP-style socket descriptor returned from the 2072 socket() system call (see Section 3.1.1). 2074 assoc_id - the specified identifier of the association that is to be 2075 branched off to a separate file descriptor (Note, in a 2076 traditional TCP-style accept() call, this would be an out 2077 parameter, but for the UDP-style call, this is an in 2078 parameter). 2080 addrlen - an integer pointer to the size of the sockaddr structure 2081 addr (in a traditional TCP-style call, this would be a out 2082 parameter, but for the UDP-style call this is an in 2083 parameter). 2085 8.3 sctp_getpaddrs() 2087 sctp_getpaddrs() returns all peer addresses in an association. The 2088 syntax is, 2090 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2091 struct sockaddr_storage **addrs); 2093 On return, addrs will point to a dynamically allocated array of 2094 struct sockaddr_storages, one for each peer address. The caller 2095 should use sctp_freepaddrs() to free the memory. addrs must not be 2096 NULL. 2098 If sd is an IPv4 socket, the addresses returned will be all IPv4 2099 addresses. If sd is an IPv6 socket, the addresses returned can be a 2100 mix of IPv4 or IPv6 addresses. 2102 For UDP-style sockets, id specifies the association to query. For 2103 TCP-style sockets, id is ignored. 2105 On success, sctp_getpaddrs() returns the number of peer addresses in 2106 the association. If there is no association on this socket, 2107 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2108 an error occurs, sctp_getpaddrs() returns -1, and the value of 2109 *addrs is undefined. 2111 8.4 sctp_freepaddrs() 2113 sctp_freepaddrs() frees all resources allocated by 2114 sctp_getpaddrs(). Its syntax is, 2116 void sctp_freepaddrs(struct sockaddr_storage *addrs); 2118 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2120 8.5 sctp_getladdrs() 2122 sctp_getladdrs() returns all locally bound address on a socket. The 2123 syntax is, 2125 int sctp_getladdrs(int sock, sctp_assoc_t id, 2126 struct sockaddr_storage **ss); 2128 On return, addrs will point to a dynamically allocated array of 2129 struct sockaddr_storages, one for each local address. The caller 2130 should use sctp_freeladdrs() to free the memory. addrs must not be 2131 NULL. 2133 If sd is an IPv4 socket, the addresses returned will be all IPv4 2134 addresses. If sd is an IPv6 socket, the addresses returned can be a 2135 mix of IPv4 or IPv6 addresses. 2137 For UDP-style sockets, id specifies the association to query. For 2138 TCP-style sockets, id is ignored. 2140 On success, sctp_getladdrs() returns the number of local addresses 2141 bound to the socket. If the socket is unbound, sctp_getladdrs() 2142 returns 0, and the value of *addrs is undefined. If an error occurs, 2143 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2145 8.6 sctp_freeladdrs() 2147 sctp_freeladdrs() frees all resources allocated by 2148 sctp_getladdrs(). Its syntax is, 2150 void sctp_freeladdrs(struct sockaddr_storage *addrs); 2151 addrs is the array of peer addresses returned by sctp_getladdrs(). 2153 8.7 sctp_opt_info() 2155 getsockopt() is read-only, so a new interface is required when 2156 information must be passed both in to and out of the SCTP stack. The 2157 syntax for scpt_opt_info() is, 2159 int sctp_opt_info(int sd, sctp_assoc_t id, int opt, void *arg); 2161 For UDP-style sockets, id specifies the association to query. For 2162 TCP-style sockets, id is ignored. 2164 opt specifies which SCTP option to get or set. It can be one of the 2165 following: 2167 SCTP_SET_PEER_ADDR_PARAMS 2168 SCTP_GET_PEER_ADDR_PARAMS 2169 SCTP_GET_PEER_ADDR_INFO 2171 arg is an option-specific structure buffer provided by the caller. 2172 See 8.5 subsections for more information on these options and 2173 option-specific structures. 2175 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2176 sets errno to the appropriate error code. 2178 8.7.1 Peer Address Parameters 2180 Applications can enable or disable heartbeats for any peer address 2181 of an association, modify an address's heartbeat interval, force a 2182 heartbeat to be sent immediately, and adjust the address's maximum 2183 number of retransmissions sent before an address is considered 2184 unreachable. The following structure is used to access and modify an 2185 address's parameters: 2187 struct sctp_paddrparams { 2188 struct sockaddr_storage spp_address; 2189 uint32_t spp_hbinterval; 2190 uint16_t spp_pathmaxrxt; 2191 sctp_assoc_t spp_assoc_id; 2192 }; 2194 spp_address - This specifies which address is of interest. 2195 spp_hbinterval - This contains the value of the heartbeat interval, 2196 in milliseconds. A value of 0, when modifying the 2197 parameter, specifies that the heartbeat on this 2198 address should be disabled. A value of UINT32_MAX 2199 (4294967295), when modifying the parameter, 2200 specifies that a heartbeat should be sent 2201 immediately to the peer address, and the current 2202 interval should remain unchanged. 2204 spp_pathmaxrxt - This contains the maximum number of 2205 retransmissions before this address shall be 2206 considered unreachable. 2207 spp_assoc_id - (UDP style socket) This is filled in the application, 2208 and identifies the association for this query. 2210 To modify these parameters, the application should call 2211 sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. To get 2212 these parameters, the application should use 2213 SCTP_GET_PEER_ADDR_PARAMS. 2215 8.7.2 Peer Address Information 2217 Applications can retrieve information about a specific peer address 2218 of an association, including its reachability state, congestion 2219 window, and retransmission timer values. This information is 2220 read-only. The following structure is used to access this 2221 information: 2223 struct sctp_paddrinfo { 2224 struct sockaddr_storage spinfo_address; 2225 int32_t spinfo_state; 2226 uint32_t spinfo_cwnd; 2227 uint32_t spinfo_srtt; 2228 uint32_t spinfo_rto; 2229 sctp_assoc_t spinfo_assoc_id; 2230 }; 2232 spinfo_address - This is filled in the application, and contains 2233 the peer address of interest. 2235 On return from getsockopt(): 2237 spinfo_state - This contains the peer addresses's state (either 2238 SCTP_ACTIVE or SCTP_INACTIVE). 2239 spinfo_cwnd - This contains the peer addresses's current congestion 2240 window. 2241 spinfo_srtt - This contains the peer addresses's current smoothed 2242 round-trip time calculation in milliseconds. 2243 spinfo_rto - This contains the peer addresses's current 2244 retransmission timeout value in milliseconds. 2245 spinfo_assoc_id - (UDP style socket) This is filled in the application, 2246 and identifies the association for this query. 2248 To retrieve this information, use sctp_opt_info() with the 2249 SCTP_GET_PEER_ADDR_INFO options. 2251 9. Security Considerations 2253 Many TCP and UDP implementations reserve port numbers below 1024 for 2254 privileged users. If the target platform supports privileged users, 2255 the SCTP implementation SHOULD restrict the ability to call bind() 2256 or sctp_bindx() on these port numbers to privileged users. 2258 Similarly unprivelged users should not be able to set protocol 2259 parameters which could result in the congestion control algorithm 2260 being more agressive than permitted on the public Internet. These 2261 paramaters are: 2263 struct sctp_rtoinfo 2265 If an unprivileged user inherits a UDP-style socket with open 2266 associations on a privileged port, it MAY be permitted to accept new 2267 associations, but it SHOULD NOT be permitted to open new 2268 associations. This could be relevant for the r* family of 2269 protocols. 2271 10. Acknowledgements 2273 The authors wish to thank Mike Bartlett, Jon Berger, Renee Ravis, 2274 and many others on the TSVWG mailing list for contributing valuable 2275 comments. 2277 11. Authors' Addresses 2279 Randall R. Stewart Tel: +1-815-477-2127 2280 Cisco Systems, Inc. EMail: rrs@cisco.com 2281 Crystal Lake, IL 60012 2282 USA 2284 Qiaobing Xie Tel: +1-847-632-3028 2285 Motorola, Inc. EMail: qxie1@email.mot.com 2286 1501 W. Shure Drive, Room 2309 2287 Arlington Heights, IL 60004 2288 USA 2290 La Monte H.P. Yarroll NIC Handle: LY 2291 Motorola, Inc. EMail: piggy@acm.org 2292 1501 W. Shure Drive, IL27-2315 2293 Arlington Heights, IL 60004 2294 USA 2296 Jonathan Wood 2297 Sun Microsystems, Inc. Email: jonathan.wood@sun.com 2298 901 San Antonio Road 2299 Palo Alto, CA 94303 2300 USA 2302 Kacheong Poon 2303 Sun Microsystems, Inc. Email: kacheong.poon@sun.com 2304 901 San Antonio Road 2305 Palo Alto, CA 94303 2306 USA 2308 Ken Fujita Tel: +81-471-82-1131 2309 NEC Corporation Email: fken@cd.jp.nec.com 2310 1131, Hinode, Abiko 2311 Chiba, 270-1198 2312 Japan 2314 12. References 2316 [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2317 September 1981. 2319 [RFC768] Postel, J. (ed.), "User Datagram Protocol", STD 6, RFC 768, 2320 August 1980. 2322 [RFC1644] Braden, R., "T/TCP -- TCP Extensions for Transactions 2323 Functional Specification," RFC 1644, July 1994. 2325 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", 2326 RFC 2026, October 1996. 2328 [RFC2292] W.R. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 2329 RFC 2292, February 1998. 2331 [RFC2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens. "Basic Socket 2332 Interface Extensions for IPv6," RFC 2553, March 1999. 2334 [SCTP] R.R. Stewart, Q. Xie, K. Morneault, C. Sharp, H.J. Schwarzbauer, 2335 T. Taylor, I. Rytina, M. Kalla, L. Zhang, and, V. Paxson, 2336 "Stream Control Transmission Protocol," RFC2960, October 2000. 2338 [STEVENS] W.R. Stevens, M. Thomas, E. Nordmark, "Advanced Sockets API for 2339 IPv6," , December 1999 2340 (Work in progress) 2342 Appendix A: TCP-style Code Example 2344 The following code is a simple implementation of an echo server over 2345 SCTP. The example shows how to use some features of TCP-style IPv4 2346 SCTP sockets, including: 2348 o Opening, binding, and listening for new associations on a socket; 2349 o Enabling ancillary data 2350 o Enabling notifications 2351 o Using ancillary data with sendmsg() and recvmsg() 2352 o Using MSG_EOR to determine if an entire message has been read 2353 o Handling notifications 2355 static void 2356 handle_event(void *buf) 2357 { 2358 struct sctp_assoc_change *sac; 2359 struct sctp_send_failed *ssf; 2360 struct sctp_paddr_change *spc; 2361 struct sctp_remote_error *sre; 2362 union sctp_notification *snp; 2363 char addrbuf[INET6_ADDRSTRLEN]; 2364 const char *ap; 2365 struct sockaddr_in *sin; 2366 struct sockaddr_in6 *sin6; 2368 snp = buf; 2370 switch (snp->sn_type) { 2371 case SCTP_ASSOC_CHANGE: 2372 sac = &snp->sn_assoc_change; 2373 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2374 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2375 sac->sac_inbound_streams, sac->sac_outbound_streams); 2376 break; 2377 case SCTP_SEND_FAILED: 2378 ssf = &snp->sn_send_failed; 2379 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2380 ssf->ssf_error); 2381 break; 2382 case SCTP_PEER_ADDR_CHANGE: 2383 spc = &snp->sn_intf_change; 2384 if (spc->spc_addr.ss_family == AF_INET) { 2385 sin = (struct sockaddr_in *)&spc->spc_addr; 2386 ap = inet_ntop(AF_INET, &sin->sin_addr, addrbuf, 2387 INET6_ADDRSTRLEN); 2388 } else { 2389 sin6 = (struct sockaddr_in6 *)&spc->spc_addr; 2390 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, addrbuf, 2391 INET6_ADDRSTRLEN); 2392 } 2393 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2394 spc->spc_state, spc->spc_error); 2395 break; 2396 case SCTP_REMOTE_ERROR: 2397 sre = &snp->sn_remote_error; 2398 printf("^^^ remote_error: err=%hu len=%hu\n", 2399 ntohs(sre->sre_error), ntohs(sre->sre_len)); 2400 break; 2401 case SCTP_SHUTDOWN_EVENT: 2402 printf("^^^ shutdown event\n"); 2403 break; 2404 default: 2405 printf("unknown type: %hu\n", snp->sn_type); 2406 break; 2407 } 2408 } 2410 static void * 2411 sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2412 ssize_t *nrp, size_t cmsglen) 2413 { 2414 ssize_t nr = 0; 2415 struct iovec iov[1]; 2416 *nrp = 0; 2417 iov->iov_base = buf; 2418 msg->msg_iov = iov; 2419 msg->msg_iovlen = 1; 2421 for (;;) { 2422 msg->msg_flags = MSG_XPG4_2; 2423 msg->msg_iov->iov_len = *buflen; 2424 msg->msg_controllen = cmsglen; 2426 nr += recvmsg(fd, msg, 0); 2427 if (nr <= 0) { 2428 /* EOF or error */ 2429 *nrp = nr; 2430 return (NULL); 2431 } 2433 if ((msg->msg_flags & MSG_EOR) != 0) { 2434 *nrp = nr; 2435 return (buf); 2436 } 2438 /* Realloc the buffer? */ 2439 if (*buflen == nr) { 2440 buf = realloc(buf, *buflen * 2); 2441 if (buf == 0) { 2442 fprintf(stderr, "out of memory\n"); 2443 exit(1); 2444 } 2445 *buflen *= 2; 2446 } 2448 /* Set the next read offset */ 2449 iov->iov_base = (char *)buf + nr; 2450 iov->iov_len = *buflen - nr; 2452 } 2453 } 2455 static void 2456 echo(int fd, int socketModeUDP) 2457 { 2458 ssize_t nr; 2459 struct sctp_sndrcvinfo *sri; 2460 struct msghdr msg[1]; 2461 struct cmsghdr *cmsg; 2462 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 2463 char *buf; 2464 size_t buflen; 2465 struct iovec iov[1]; 2466 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 2468 /* Allocate the initial data buffer */ 2469 buflen = BUFLEN; 2470 if (!(buf = malloc(BUFLEN))) { 2471 fprintf(stderr, "out of memory\n"); 2472 exit(1); 2473 } 2475 /* Set up the msghdr structure for receiving */ 2476 memset(msg, 0, sizeof (*msg)); 2477 msg->msg_control = cbuf; 2478 msg->msg_controllen = cmsglen; 2479 msg->msg_flags = 0; 2480 cmsg = (struct cmsghdr *)cbuf; 2481 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 2483 /* Wait for something to echo */ 2484 while (buf = sctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 2486 /* Intercept notifications here */ 2487 if (msg->msg_flags & MSG_NOTIFICATION) { 2488 handle_event(buf); 2489 continue; 2490 } 2492 iov->iov_base = buf; 2493 iov->iov_len = nr; 2494 msg->msg_iov = iov; 2495 msg->msg_iovlen = 1; 2497 printf("got %u bytes on stream %hu:\n", nr, 2498 sri->sinfo_stream); 2499 write(0, buf, nr); 2501 /* Echo it back */ 2502 msg->msg_flags = MSG_XPG4_2; 2503 if (sendmsg(fd, msg, 0) < 0) { 2504 perror("sendmsg"); 2505 exit(1); 2506 } 2507 } 2509 if (nr < 0) { 2510 perror("recvmsg"); 2511 } 2512 if(socketModeUDP == 0) 2513 close(fd); 2514 } 2516 main() 2517 { 2518 int lfd, cfd; 2519 int onoff = 1; 2520 struct sockaddr_in sin[1]; 2522 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 2523 perror("socket"); 2524 exit(1); 2525 } 2527 sin->sin_family = AF_INET; 2528 sin->sin_port = htons(7); 2529 sin->sin_addr.s_addr = INADDR_ANY; 2530 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2531 perror("bind"); 2532 exit(1); 2533 } 2535 if (listen(lfd, 1) == -1) { 2536 perror("listen"); 2537 exit(1); 2538 } 2540 /* Wait for new associations */ 2541 for (;;) { 2542 if ((cfd = accept(lfd, NULL, 0)) == -1) { 2543 perror("accept"); 2544 exit(1); 2545 } 2547 /* Enable ancillary data */ 2548 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2549 &onoff, 4) < 0) { 2550 perror("setsockopt RECVDATAIOEVNT"); 2551 exit(1); 2552 } 2553 /* Enable notifications */ 2554 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, 2555 &onoff, 4) < 0) { 2556 perror("setsockopt SCTP_RECVASSOCEVNT"); 2557 exit(1); 2558 } 2559 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2560 &onoff, 4) < 0) { 2561 perror("setsockopt SCTP_RECVASSOCEVNT"); 2562 exit(1); 2563 } 2564 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2565 &onoff, 4) < 0) { 2566 perror("setsockopt SCTP_RECVPADDREVNT"); 2567 exit(1); 2568 } 2569 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2570 &onoff, 4) < 0) { 2571 perror("setsockopt SCTP_RECVPEERERR"); 2572 exit(1); 2573 } 2574 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2575 &onoff, 4) < 0) { 2576 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2577 exit(1); 2578 } 2580 /* Echo back any and all data */ 2581 echo(cfd,0); 2582 } 2583 } 2585 Appendix B: UDP-style Code Example 2587 The following code is a simple implementation of an echo server over 2588 SCTP. The example shows how to use some features of UDP-style IPv4 2589 SCTP sockets, including: 2591 o Opening and binding of a socket; 2592 o Enabling ancillary data 2593 o Enabling notifications 2594 o Using ancillary data with sendmsg() and recvmsg() 2595 o Using MSG_EOR to determine if an entire message has been read 2596 o Handling notifications 2598 Note most functions defined in Appendix A are reused in 2599 this example. 2601 main() 2602 { 2603 int fd; 2604 int onoff = 1; 2605 int idleTime = 2; 2606 struct sockaddr_in sin[1]; 2608 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 2609 perror("socket"); 2610 exit(1); 2611 } 2613 sin->sin_family = AF_INET; 2614 sin->sin_port = htons(7); 2615 sin->sin_addr.s_addr = INADDR_ANY; 2616 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2617 perror("bind"); 2618 exit(1); 2619 } 2621 /* Enable notifications */ 2623 /* SCTP_RECVASSOCEVNT and SCTP_RECVDATAIOEVNT are on by default */ 2625 /* if a send fails we want to know it */ 2626 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2627 &onoff, 4) < 0) { 2628 perror("setsockopt SCTP_RECVASSOCEVNT"); 2629 exit(1); 2630 } 2631 /* if a network address change or event transpires 2632 * we wish to know it 2633 */ 2634 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2635 &onoff, 4) < 0) { 2636 perror("setsockopt SCTP_RECVPADDREVNT"); 2637 exit(1); 2638 } 2639 /* We would like all error TLV's from the peer */ 2640 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2641 &onoff, 4) < 0) { 2642 perror("setsockopt SCTP_RECVPEERERR"); 2643 exit(1); 2644 } 2645 /* And of course we would like to know about shutdown's */ 2646 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2647 &onoff, 4) < 0) { 2648 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2649 exit(1); 2650 } 2651 /* Set associations to auto-close in 2 seconds of 2652 * inactivity 2653 */ 2654 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 2655 &idleTime, 4) < 0) { 2656 perror("setsockopt SCTP_AUTOCLOSE"); 2657 exit(1); 2658 } 2660 /* Allow new associations to be accepted */ 2661 if (listen(fd, 0) < 0) { 2662 perror("listen"); 2663 exit(1); 2664 } 2666 /* Wait for new associations */ 2667 while(1){ 2668 /* Echo back any and all data */ 2669 echo(fd,1); 2670 } 2671 }