idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-00.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-26) 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 == The page length should not exceed 58 lines per page, but there was 2 longer pages, the longest (page 3) being 60 lines 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 33 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** There are 71 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 818: '...In other words the user MAY be able to...' RFC 2119 keyword, line 837: '... MAY override 'RTO.Max'. This valu...' RFC 2119 keyword, line 969: '...e MSG_EOR clear. The user MUST finish...' RFC 2119 keyword, line 1992: '...P implementation SHOULD restrict the a...' RFC 2119 keyword, line 2003: '...vileged port, it MAY be permitted to a...' (1 more instance...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 793 has weird spacing: '...g_level cms...' == Line 849 has weird spacing: '...g_level cms...' == Line 1358 has weird spacing: '... msghdr msg;...' == Line 1489 has weird spacing: '...ngth of the o...' == Line 1621 has weird spacing: '... struct linge...' == (1 more instance...) -- 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 (June 1, 2001) is 8365 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: 'TCP' is mentioned on line 112, but not defined == Missing Reference: 'UDP' is mentioned on line 113, but not defined == Missing Reference: 'RFC 2553' is mentioned on line 541, but not defined ** Obsolete undefined reference: RFC 2553 (Obsoleted by RFC 3493) -- Looks like a reference, but probably isn't: '0' on line 1251 -- Looks like a reference, but probably isn't: '1' on line 2336 == Unused Reference: 'STEVENS' is defined on line 2063, but no explicit reference was found in the text ** 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: 15 errors (**), 0 flaws (~~), 13 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 June 1, 2001 14 SCTP Sockets Mapping 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 sendmsg() and recvmsg() - UDP Style Syntax....... 6 48 3.1.4 close() - UDP Style Syntax....................... 7 49 3.2 Implicit Association Setup............................ 8 50 3.3 Non-blocking mode..................................... 8 51 4. TCP-style Interface..................................... 9 52 4.1 Basic Operation....................................... 9 53 4.1.1 socket() - TCP Style Syntax........................10 54 4.1.2 bind() - TCP Style Syntax..........................10 55 4.1.3 listen() - TCP Style Syntax........................11 56 4.1.4 accept() - TCP Style Syntax........................11 57 4.1.5 connect() - TCP Style Syntax.......................12 58 4.1.6 close() - TCP Style Syntax.........................12 59 4.1.7 shutdown() - TCP Style Syntax......................12 60 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax.........13 61 5. Data Structures..........................................13 62 5.1 The msghdr and cmsghdr Structures......................13 63 5.2 SCTP msg_control Structures............................14 64 5.2.1 SCTP Initiation Structure (SCTP_INIT)...............15 65 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV).....16 66 5.3 SCTP Events and Notifications..........................18 67 5.3.1 SCTP Notification Structure.........................18 68 5.3.1.1 SCTP_ASSOC_CHANGE................................19 69 5.3.1.2 SCTP_PEER_ADDR_CHANGE............................21 70 5.3.1.3 SCTP_REMOTE_ERROR................................22 71 5.3.1.4 SCTP_SEND_FAILE..................................23 72 5.3.1.5 SCTP_SHUTDOWN_EVENT..............................24 73 5.4 Ancillary Data Considerations and Semantics...........25 74 5.4.1 Multiple Items and Ordering........................25 75 5.4.2 Accessing and Manipulating Ancillary Data..........25 76 5.4.3 Control Message Buffer Sizing......................26 77 6. Common Operations for Both Styles.......................27 78 6.1 send(), recv(), sendto(), recvfrom()..................27 79 6.2 setsockopt(), getsockopt()............................28 80 6.3 read() and write()....................................28 81 7. Socket Options..........................................28 82 7.1 Read / Write Options..................................29 83 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO)...29 84 7.1.2 Association Retransmission Parameter 85 (SCTP_ASSOCRTXINFO)................................29 86 7.1.3 Initialization Parameters (SCTP_INITMSG)...........30 87 7.1.4 SO_LINGER..........................................30 88 7.1.5 SO_NODELAY.........................................31 89 7.1.6 SO_RCVBUF..........................................31 90 7.1.7 SO_SNDBUF..........................................31 91 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE)...31 92 7.2 Read-Only Options.....................................31 93 7.2.1 Association Status (SCTP_STATUS)...................31 94 7.3. Ancillary Data Interest Options.....................32 95 8. New Interface...........................................33 96 8.1 sctp_bindx()..........................................33 97 8.2 Branched-off Association, sctp_peeloff()..............34 98 8.3 sctp_getpaddrs()......................................35 99 8.4 sctp_freepaddrs().....................................35 100 8.5 sctp_opt_info().......................................35 101 8.5.1 Peer Address Parameters............................36 102 8.5.2 Peer Address Information...........................37 103 9. Security Considerations.................................37 104 10. Authors' Addresses....................................38 105 11. References............................................38 106 Appendix A: TCP-style Code Example.........................39 107 Appendix B: UDP-style Code Example.........................43 109 1. Introduction 111 The sockets API has provided a standard mapping of the Internet 112 Protocol suite to many operating systems. Both TCP [TCP] and UDP 113 [UDP] have benefited from this standard representation and access 114 method across many diverse platforms. SCTP is a new protocol that 115 provides many of the characteristics of TCP but also incorporates 116 semantics more akin to UDP. This document defines a method to map 117 the existing sockets API for use with SCTP, providing both a base 118 for access to new features and compatibility so that most existing 119 TCP applications can be migrated to SCTP with few (if any) changes. 121 There are three basic design objectives: 123 1) Maintain consistency with existing sockets APIs: 125 We define a sockets mapping for SCTP that is consistent with other 126 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 127 IPv6). 129 2) Support a UDP-style interface 131 This set of semantics is similar to that defined for conntionless 132 protocols, such as UDP. It is more efficient than a TCP-like 133 connection-oriented interface in terms of exploring the new features 134 of SCTP. 136 Note that SCTP is connection-oriented in nature, and it does not 137 support broadcast or multicast communications, as UDP does. 139 3) Support a TCP-style interface 141 This interface supports the same basic semantics as sockets for 142 connection-oriented protocols, such as TCP. 144 The purpose of defining this interface is to allow existing 145 applications built on connnection-oriented protocols be ported to 146 use SCTP with very little effort, and developers familiar with those 147 semantics can easily adapt to SCTP. 149 Extensions will be added to this mapping to provide mechanisms to 150 exploit new features of SCTP. 152 Goals 2 and 3 are not compatible, so in this document we define two 153 modes of mapping, namely the UDP-style mapping and the TCP-style 154 mapping. These two modes share some common data structures and 155 operations, but will require the use of two different programming 156 models. 158 A mechanism is defined to convert a UDP-style SCTP socket into a 159 TCP-style socket. 161 Some of the SCTP mechanisms cannot be adequately mapped to existing 162 socket interface. In some cases, it is more desirable to have new 163 interface instead of using exisitng socket calls. This document 164 also describes those new interface. 166 2. Conventions 168 2.1 Data Types 170 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 171 1003.1g are used: uintN_t means an unsigned integer of exactly N 172 bits (e.g., uint16_t). We also assume the argument data types from 173 1003.1g when possible (e.g., the final argument to setsockopt() is a 174 size_t value). Whenever buffer sizes are specified, the POSIX 175 1003.1 size_t data type is used. 177 3. UDP-style Interface 179 The UDP-style interface has the following characteristics: 181 A) Outbound association setup is implicit. 183 B) Messages are delivered in complete messages (with one notable 184 exception). 186 C) New inbound associations are accepted automatically. 188 3.1 Basic Operation 190 A typical server in this model uses the following socket calls in 191 sequence to prepare an endpoint for servicing requests: 193 1. socket() 194 2. bind() 195 3. setsocketopt() 196 4. recvmsg() 197 5. sendmsg() 198 6. close() 200 A typical client uses the following calls in sequence to setup an 201 association with a server to request services: 203 1. socket() 204 2. sendmsg() 205 3. recvmsg() 206 4. close() 208 In this model, by default, all the associations connected to the 209 endpoint are represented with a single socket. 211 If the server or client wishes to branch an existing association off 212 to a separate socket, it is required to call sctp_peeloff() and in 213 the parameter specifies one of the transport addresses of the 214 association. The sctp_peeloff() call will return a new socket which 215 can then be used with recv() and send() functions for message 216 passing. See Section 8.2 for more on branched-off associations. 218 Once an association is branched off to a separate socket, it becomes 219 completely separated from the original socket. All subsequent 220 control and data operations to that association must be done through 221 the new socket. For example, the close operation on the original 222 socket will not terminate any associations that have been branched 223 off to a different socket. 225 We will discuss the UDP-style socket calls in more details in the 226 following subsections. 228 3.1.1 socket() - UDP Style Syntax 230 Applications use socket() to create a socket descriptor to represent 231 an SCTP endpoint. 233 The syntax is, 235 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 237 or, 239 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 241 Here, SOCK_SEQPACKET indicates the creation of a UDP-style socket. 243 The first form creates an endpoint which can use only IPv4 244 addresses, while, the second form creates an endpoint which can use 245 both IPv6 and IPv4 mapped addresses. 247 3.1.2 bind() - UDP Style Syntax 249 Applications use bind() to specify which local address the SCTP 250 endpoint should associate itself with as the primary address. 252 An SCTP endpoint can be associated with multiple addresses. To do 253 this, sctp_bindx() is introduced in section 8.1 to help applications 254 do the job of associating multiple addresses. 256 These addresses associated with a socket are the eligible transport 257 addresses for the endpoint to send and receive data. The endpoint 258 will also present these addresses to its peers during the 259 association initialization process, see [SCTP]. 261 After calling bind() or sctp_bindx(), if the endpoint wishes to 262 accept new assocations on the socket, it must enable the 263 SCTP_ASSOC_CHANGE socket option (see section 5.3.1.1). Then the 264 SCTP endpoint will accept all SCTP INIT requests passing the 265 COMMUNICATION_UP notification to the endpoint upon reception of a 266 valid associaition (i.e. the receipt of a valid COOKIE ECHO). 268 The syntax of bind() is, 270 ret = bind(int sd, struct sockaddr *addr, int addrlen); 272 sd - the socket descriptor returned by socket(). 274 addr - the address structure (struct sockaddr_in or struct 275 sockaddr_in6 [RFC 2553]), 276 addrlen - the size of the address structure. 278 If sd is an IPv4 socket, the address passed must be an IPv4 address. 279 If the sd is an IPv6 socket, the address passed can either be an 280 IPv4 or an IPv6 address. 282 Applications cannot call bind() multiple times to associate multiple 283 addresses to an endpoint. After the first call to bind(), all 284 subsequent call will return an error. 286 If addr is specified as INADDR_ANY for an IPv4 or IPv6 socket, or as 287 IN6ADDR_ANY for an IPv6 socket (normally used by server 288 applications), the operating system will associates the endpoint 289 with the optimal subset of available local interfaces. 291 If a bind() or sctp_bindx() is not called prior to the connect() 292 call, the system picks an ephemeral port and will choose an address 293 set equivalant to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 294 and IPv6 socket respectively. One of those addresses will be the 295 primary address for the association. This automatically enables the 296 multihoming capability of SCTP. 298 3.1.3 sendmsg() and recvmsg() - UDP Style Syntax 300 An application uses sendmsg() and recvmsg() call to transmit data to 301 and receive data from its peer. 303 ssize_t sendmsg(int socket, const struct msghdr *message, 304 int flags); 306 ssize_t recvmsg(int socket, struct msghdr *message, 307 int flags); 309 socket - the socket descriptor of the endpoint. 310 message - pointer to the msghdr structure which contains a single 311 user message and possibly some ancillary data. 313 See Section 5 for complete description of the data 314 structures. 316 flags - No new flags are defined for SCTP at this level. See 317 Section 5 for SCTP-specific flags used in the msghdr 318 structure. 320 As we will see in Section 5, along with the user data, the ancillary 321 data field is used to carry the sctp_sndrcvinfo and/or the 322 sctp_initmsg structures to perform various SCTP functions including 323 specifying options for sending each user message. Those options, 324 depending on whether sending or receiving, include stream number, 325 stream sequence number, TOS, various flags, context and payload 326 protocol Id, etc. 328 When sending user data with sendmsg(), the msg_name field in msghdr 329 structure will be filled with one of the transport addresses of the 330 intended receiver. If there is no association existing between the 331 sender and the intended receiver, the sender's SCTP stack will set 332 up a new association and then send the user data (see Section 3.2 333 for more on implicit association setup). 335 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 336 be delivered if that notification has been enabled, and no more data 337 can be sent to that association. Any attempt to send more data will 338 cause sendmsg() to return with an ESHUTDOWN error. Note that the 339 socket is still open for reading at this point so it is possible to 340 retrieve notifications. 342 When receiving a user message with recvmsg(), the msg_name field in 343 msghdr structure will be populated with the source transport address 344 of the user data. The caller of recvmsg() can use this address 345 information to determine to which association the received user 346 message belongs. 348 If all data in a single message has been delivered, MSG_EOR will be 349 set in the msg_flags field of the msghdr structure (see section 350 5.1). 352 If the application does not provide enough buffer space to 353 completely receive a data message, MSG_EOR will not be set in 354 msg_flags. Successive reads will consume more of the same message 355 until the entire message has been delievered, and MSG_EOR will be 356 set. 358 If the SCTP stack is running low on buffers, it may partially 359 deliver a message. In this case, MSG_EOR will not be set, and more 360 calls to recvmsg() will be necessary to completely consume the 361 message. Only one message at a time can be partially delivered. 363 Note, if the socket is a branched-off socket that only represents 364 one association (see Section 3.1), the msg_name field is not used 365 when sending data (i.e., ignored by the SCTP stack). 367 3.1.4 close() - UDP Style Syntax 369 Applications use close() to perform graceful shutdown (as described 370 in Section 10.1 of [SCTP]) on ALL the associations currently 371 represented by a UDP-style socket. 373 The syntax is 375 ret = close(int sd); 377 sd - the socket descriptor of the associations to be closed. 379 To gracefully shutdown a specific association represented by the 380 UDP-style socket, an application should use the sendmsg() call, 381 passing no user data, but including the appropriate flag in the 382 ancillary data (see Section 5.2.2). 384 If sd in the close() call is a branched-off socket representing only 385 one association, the shutdown is performed on that association only. 387 3.2 Implicit Association Setup 389 Once all bind() calls are complete on a UDP-style socket, the 390 application can begin sending and receiving data using the 391 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 392 through any explicit association setup procedures (i.e., no 393 connect() calls required). 395 Whenever sendmsg() or sendto() is called and the SCTP stack at the 396 sender finds that there is no association existing between the 397 sender and the intended receiver (identified by the address passed 398 either in the msg_name field of msghdr structure in the sendmsg() 399 call or the dest_addr field in the sendto() call), the SCTP stack 400 will automatically setup an association to the intended receiver. 402 Upon the successful association setup a COMMUNICATION_UP 403 notification will be dispatched to the socket at both the sender and 404 receiver side. This notification can be read by the recvmsg() system 405 call (see Section 3.1.3). 407 Note, if the SCTP stack at the sender side supports bundling, the 408 first user message may be bundled with the COOKIE ECHO message 409 [SCTP]. 411 When the SCTP stack sets up a new association implicitly, it first 412 consults the sctp_initmsg structure, which is passed along within 413 the ancillary data in the sendmsg() call (see Section 5.2.1 for 414 details of the data structures), for any special options to be used 415 on the new association. 417 If this information is not present in the sendmsg() call, or if the 418 implicit association setup is triggered by a sendto() call, the 419 default association initialization parameters will be used. These 420 default association parameters may be set with respective 421 setsockopt() calls or be left to the system defaults. 423 Implicit association setup cannot be initiated by send()/recv() 424 calls. 426 3.3 Non-blocking mode 428 Some SCTP user might want to avoid blocking when they call 429 socket interface function. 431 Whenever the user which want to avoid blocking must call select() 432 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and 433 check the socket status is writable or readable. If the socket 434 status isn't writeable or readable, the user should not call 435 sendmsg()/sendto() and recvmsg()/recvfrom(). 437 Once all bind() calls are complete on a UDP-style socket, the 438 application must set the non-blocking option by a fcntl() (such as 439 O_NONBLOCK). After which the sendmsg() function returns 440 immediately, and the success or fault of the data message (and 441 possible SCTP_INITMSG parameters) will be notified by 442 SCTP_ASSOC_CHANGE with COMMUNICATION_UP or CANT_START_ASSOC. If user 443 data was sent and failed (due to a CANT_START_ASOC), the sender will 444 also recieve a SCTP_SEND_FAILED event. Those event(s) can be 445 received by the user calling of recvmsg(). The server side user is 446 also notified of an association up event by the reception of a 447 SCTP_ASSOC_CHANGE with COMMUNICATION_UP via the calling of 448 recvmsg() and possibly the reception of the first data message. 450 When the user want to graceful shutdown the association, the user 451 must call sendmsg() and send SHUTDOWN. The function returns 452 immediately, and the success of the SHUTDOWN is notified by 453 SCTP_ASSOC_CHANGE with SHUTDOWN_COMPLETE calling recvmsg(). 455 4. TCP-style Interface 457 The goal of this model is to follow as closely as possible the 458 current practice of using the sockets interface for a connection 459 oriented protocol, such as TCP. This model enables existing 460 applications using connection oriented protocols to be ported to 461 SCTP with very little effort. 463 Note that some new SCTP features and some new SCTP socket options 464 can only be utilized through the use of sendmsg() and recvmsg() 465 calls, see Section 4.1.8. 467 4.1 Basic Operation 469 A typical server in TCP-style model uses the following system call 470 sequence to prepare an SCTP endpoint for servicing requests: 472 1. socket() 473 2. bind() 474 3. listen() 475 4. accept() 477 The accept() call blocks until a new assocation is set up. It 478 returns with a new socket descriptor. The server then uses the new 479 socket descriptor to communicate with the client, using recv() and 480 send() calls to get requests and send back responses. 482 Then it calls 484 5. close() 486 to terminate the association. 488 A typical client uses the following system call sequence to setup an 489 association with a server to request services: 491 1. socket() 492 2. connect() 494 After returning from connect(), the client uses send() and recv() 495 calls to send out requests and receive responses from the server. 497 The client calls 499 3. close() 501 to terminate this association when done. 503 4.1.1 socket() - TCP Style Syntax 505 Applications calls socket() to create a socket descriptor to 506 represent an SCTP endpoint. 508 The syntax is: 510 sd = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 512 or, 514 sd = socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 516 Here, SOCK_STREAM indicates the creation of a TCP-style socket. 518 The first form creates an endpoint which can use only IPv4 519 addresses, while the second form creates an endpoint which can use 520 both IPv6 and mapped IPv4 addresses. 522 4.1.2 bind() - TCP Style Syntax 524 Applications use bind() to pass the primary address assoicated with 525 an SCTP endpoint to the system. An SCTP endpoint can be associated 526 with multiple addresses. To do this, sctp_bindx() is introduced in 527 section 8.1 to help applications do the job of associating multiple 528 addresses. 530 These addresses associated with a socket are the eligible transport 531 addresses for the endpoint to send and receive data. The endpoint 532 will also present these addresses to its peers during the 533 association initialization process, see [SCTP]. 535 The syntax is: 537 ret = bind(int sd, struct sockaddr *addr, int addrlen); 539 sd - the socket descriptor returned by socket() call. 540 addr - the address structure (either struct sockaddr_in or struct 541 sockaddr_in6 defined in [RFC 2553]). 542 addrlen - the size of the address structure. 544 If sd is an IPv4 socket, the address passed must be an IPv4 address. 545 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 546 either be an IPv4 or an IPv6 address. 548 Applications cannot call bind() multiple times to associate multiple 549 addresses to the endpoint. After the first call to bind(), all 550 subsequent calls will return an error. 552 If addr is specified as INADDR_ANY for an IPv4 or IPv6 socket, or as 553 IN6ADDR_ANY for an IPv6 socket (normally used by server 554 applications), the operating system will associate the endpoint with 555 an optimal address set of the available interfaces. 557 The completion of this bind() process does not ready the SCTP 558 endpoint to accept inbound SCTP association requests. Until a 559 listen() system call, described below, is performed on the socket, 560 the SCTP endpoint will promptly reject an inbound SCTP INIT request 561 with an SCTP ABORT. 563 4.1.3 listen() - TCP Style Syntax 565 Applications use listen() to ready the SCTP endpoint for accepting 566 inbound associations. 568 The syntax is: 570 ret = listen(int sd, int backlog); 572 sd - the socket descriptor of the SCTP endpoint. 573 backlog - this specifies the max number of outstanding associations 574 allowed in the socket's accept queue. These are the 575 associations that have finished the four-way initiation 576 handshake (see Section 5 of [SCTP]) and are in the 577 ESTABLISHED state. 579 4.1.4 accept() - TCP Style Syntax 581 Applications use accept() call to remove an established SCTP 582 assocation from the accept queue of the endpoint. A new socket 583 descriptor will be returned from accept() to represent the newly 584 formed association. 586 The syntax is: 588 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 590 new_sd - the socket descriptor for the newly formed association. 591 sd - the listening socket descriptor. 592 addr - on return, will contain the primary address of the peer 593 endpoint. 594 addrlen - on return, will contain the size of addr. 596 4.1.5 connect() - TCP Style Syntax 598 Applications use connect() to initiate an association to a peer. 600 The syntax is 602 ret = connect(int sd, const struct sockaddr *addr, int addrlen); 604 sd - the socket descriptor of the endpoint. 605 addr - the peer's address. 606 addrlen - the size of the address. 608 This operation corresponds to the ASSOCIATE primitive described in 609 section 10.1 of [SCTP]. 611 By default, the new association created has only one outbound 612 stream. The SCTP_INITMSG option described in Section 7.1.4 should be 613 used before connecting to change the number of outbound streams. 615 If a bind() or sctp_bindx() is not called prior to the connect() 616 call, the system picks an ephemeral port and will choose an address 617 set equivalant to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 618 and IPv6 socket respectively. One of those addresses will be the 619 primary address for the association. This automatically enables the 620 multihoming capability of SCTP. 622 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 623 during the association set up phase. If an application wants to do 624 this, it cannot use connect() call. Instead, it should use sendto() 625 or sendmsg() to initiate an assocation. If it uses sendto() and it 626 wants to change initialization behavior, it needs to use the 627 SCTP_INITMSG socket option before calling sendto(). Or it can use 628 SCTP_INIT type sendmsg() to initiate an association without doing 629 the setsockopt(). 631 SCTP does not support half close semantics. This means that unlike 632 T/TCP, MSG_EOF should not be set in the flags parameter when calling 633 sendto() or sendmsg() when the call is used to initiate a 634 connection. MSG_EOF is not an acceptable flag with SCTP socket. 636 4.1.6 close() - TCP Style Syntax 638 Applications use close() to gracefully close down an association. 640 The syntax is: 642 ret = close(int sd); 644 sd - the socket descriptor of the association to be closed. 646 After an application calls close() on a socket descriptor, no 647 further socket operations will suceed on that descriptor. 649 4.1.7 shutdown() - TCP Style Syntax 651 The socket call shutdown() does not have any meaning with an SCTP 652 socket because SCTP does not have a half closed semantics. Calling 653 shutdown() on an SCTP socket will return an error. 655 To perform the ABORT operation described in [SCTP] section 10.1, an 656 application can use the socket option SO_LINGER. It is described in 657 section 7.1.6. 659 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax 661 With a TCP-style socket, the application can also use sendmsg() and 662 recvmsg() to transmit data to and receive data from its peer. The 663 semantics is similar to those used in the UDP-style model (section 664 3.1.3), with the following differences: 666 1) When sending, the msg_name field in the msghdr is not used to 667 specify the intended receiver, rather it is used to indicate a 668 different peer address if the sender does not want to send the 669 message over the primary address of the receiver. If the transport 670 address given is not part of the current association, the data will 671 not be sent and a SCTP_SEND_FAILED event will be delivered to the 672 application if send failure events are enabled. 674 When receiving, if a message is not received from the primary 675 address, the SCTP stack will fill in the msg_name field on return so 676 that the application can retrieve the source address information of 677 the received message. 679 2) An application must use close() to gracefully shutdown an 680 assocication, or use SO_LINGER option with close() to abort an 681 asssociation. It must not use the MSG_ABORT or MSG_EOF flag in 682 sendmsg(). The system returns an error if an application tries to 683 do so. 685 5. Data Structures 687 We discuss in this section important data structures which are 688 specific to SCTP and are used with sendmsg() and recvmsg() calls to 689 control SCTP endpoint operations and to access ancillary 690 information. 692 5.1 The msghdr and cmsghdr Structures 694 The msghdr structure used in the sendmsg() and recvmsg() calls, as 695 well as the ancillary data carried in the structure, is the key for 696 the application to set and get various control information from the 697 SCTP endpoint. 699 The msghdr and the related cmsghdr structures are defined and 700 discussed in details in [RFC2292]. Here we will cite their 701 definitions from [RFC2292]. 703 The msghdr structure: 705 struct msghdr { 706 void *msg_name; /* ptr to socket address structure */ 707 socklen_t msg_namelen; /* size of socket address structure */ 708 struct iovec *msg_iov; /* scatter/gather array */ 709 size_t msg_iovlen; /* # elements in msg_iov */ 710 void *msg_control; /* ancillary data */ 711 socklen_t msg_controllen; /* ancillary data buffer length */ 712 int msg_flags; /* flags on received message */ 713 }; 715 The cmsghdr structure: 717 struct cmsghdr { 718 socklen_t cmsg_len; /* #bytes, including this header */ 719 int cmsg_level; /* originating protocol */ 720 int cmsg_type; /* protocol-specific type */ 721 /* followed by unsigned char cmsg_data[]; */ 722 }; 724 In the msghdr structure, the usage of msg_name has been discussed in 725 previous sections (see Sections 3.1.3 and 4.1.8). 727 The scatter/gather buffers, or I/O vectors (pointed to by the 728 msg_iov field) are treated as a single SCTP data chunk, rather than 729 multiple chunks, for both sendmsg() and recvmsg(). 731 The msg_flags are not used when sending a message with sendmsg(). 733 If a notification has arrived, recvmsg() will return the 734 notification with the MSG_NOTIFICATION flag set in msg_flags. If the 735 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 736 section 5.3 for more information about notifications. 738 If all portions of a data frame or notification have been read, 739 recvmsg() will return with MSG_EOR set in msg_flags. 741 5.2 SCTP msg_control Structures 743 A key element of all SCTP-specific socket extensions is the use of 744 ancillary data to specify and access SCTP-specific data via the 745 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 746 Fine-grained control over initialization and sending parameters are 747 handled with ancillary data. 749 Each ancillary data item is preceeded by a struct cmsghdr (see 750 Section 5.1), which defines the function and purpose of the data 751 contained in in the cmsg_data[] member. 753 There are two kinds of ancillary data: initialization data, and, 754 header information (SNDRCV). Initialization data (UDP-style only) 755 sets protocol parameters for new associations. Section 5.2.1 756 provides more details. Header information can set or report 757 parameters on individual messages in a stream. See section 5.2.2 758 for how to use SNDRCV ancillary data. 760 By default on a TCP-style socket, SCTP will pass no ancillary data; 761 on a UDP-style socket, SCTP will only pass SCTP_SNDRCV information. 762 Specific ancillary data items can be enabled with socket options 763 defined for SCTP; see section 7.3. Note in particular that for 764 UDP-style sockets, new associations will not be accepted by 765 default. See section 5.2.1 for more information. 767 Note that all ancillary types are fixed length; see section 5.4 for 768 further discussion on this. These data structures use struct 769 sockaddr_storage (defined in [RFC2553]) as a portable, fixed length 770 address format. 772 Other protocols may also provide ancillary data to the socket layer 773 consumer. These ancillary data items from other protocols may 774 intermingle with SCTP data. For example, the IPv6 socket API 775 definitions ([RFC2292] and [RFC2553]) define a number of ancillary 776 data items. If a socket API consumer enables delivery of both SCTP 777 and IPv6 ancillary data, they both may appear in the same 778 msg_control buffer in any order. An application may thus need to 779 handle other types of ancillary data besides that passed by SCTP. 781 The sockets application must provide a buffer large enough to 782 accomodate all ancillary data provided via recvmsg(). If the buffer 783 is not large enough, the ancillary data will be truncated and the 784 msghdr's msg_flags will include MSG_CTRUNC. 786 5.2.1 SCTP Initiation Structure (SCTP_INIT) 788 This cmsghdr structure provides information for initializing new 789 SCTP associations with sendmsg(). The SCTP_INITMSG socket option 790 uses this same data structure. This structure is not used for 791 recvmsg(). 793 cmsg_level cmsg_type cmsg_data[] 794 ------------ ------------ ---------------------- 795 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 797 Here is the definition of the sctp_initmsg structure: 799 struct sctp_initmsg { 800 uint16_t sinit_num_ostreams; 801 uint16_t sinit_max_instreams; 802 uint16_t sinit_max_attempts; 803 uint16_t sinit_max_init_timeo; 804 }; 806 sinit_num_ostreams: 16 bits (unsigned integer) 808 This is an integer number representing the number of streams that 809 the application wishes to be able to send to. This number is 810 confirmed in the COMMUNICATION_UP notification and must be verified 811 since it is a negotiated number with the remote endpoint. The 812 default value of 0 indicates to use the endpoint default value. 814 sinit_max_instreams: 16 bits (unsigned integer) 816 This value represents the maximum number of inbound streams the 817 application is prepared to support. This value is bounded by the 818 actual implementation. In other words the user MAY be able to 819 support more streams than the Operating System. In such a case, the 820 Operating System limit overrides the value requested by the 821 user. The default value of 0 indicates to use the endpoint's default 822 value. 824 sinit_max_attempts: 16 bits (unsigned integer) 826 This integer specifies how many attempts the SCTP endpoint should 827 make at resending the INIT. This value overrides the system SCTP 828 'Max.Init.Retransmits' value. The default value of 0 indicates to 829 use the endpoint's default value. This is normally set to the 830 system's default 'Max.Init.Retransmit' value. 832 sinit_max_init_timeo: 16 bits (unsigned integer) 834 This value represents the largest Time-Out or RTO value to use in 835 attempting a INIT. Normally the 'RTO.Max' is used to limit the 836 doubling of the RTO upon timeout. For the INIT message this value 837 MAY override 'RTO.Max'. This value MUST NOT influence 'RTO.Max' 838 during data transmission and is only used to bound the initial setup 839 time. A default value of 0 indicates to use the endpoint's default 840 value. This is normally set to the system's 'RTO.Max' value (60 841 seconds). 843 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 845 This cmsghdr structure specifies SCTP options for sendmsg() and 846 describes SCTP header information about a received message through 847 recvmsg(). 849 cmsg_level cmsg_type cmsg_data[] 850 ------------ ------------ ---------------------- 851 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 853 Here is the defintion of sctp_sndrcvinfo: 855 struct sctp_sndrcvinfo { 856 uint16_t sinfo_stream; 857 uint16_t sinfo_ssn; 858 uint16_t sinfo_flags; 859 uint32_t sinfo_ppid; 860 uint32_t sinfo_context; 861 uint8_t sinfo_dscp; 862 sctp_assoc_t sinfo_assoc_id; 863 }; 865 sinfo_stream: 16 bits (unsigned integer) 867 For recvmsg() the SCTP stack places the message's stream number in 868 this value. For sendmsg() this value holds the stream number that 869 the application wishes to send this message to. If a sender 870 specifies an invalid stream number an error indication is returned 871 and the call fails. 873 sinfo_ssn: 16 bits (unsigned integer) 875 For recvmsg() this value contains the stream sequence number that 876 the remote endpoint placed in the DATA chunk. For fragmented 877 messages this is the same number for all deliveries of the message 878 (if more than one recvmsg() is needed to read the message). The 879 sendmsg() call will ignore this parameter. 881 sinfo_ppid:32 bits (unsigned integer) 883 This value in sendmsg() is an opaque unsigned value that is passed 884 to the remote end in each user message. In recvmsg() this value is 885 the same information that was passed by the upper layer in the peer 886 application. Please note that byte order issues are NOT accounted 887 for and this information is passed opaquely by the SCTP stack from 888 one end to the other. 890 sinfo_context:32 bits (unsigned integer) 892 This value is an opaque 32 bit context datum that is used in the 893 sendmsg() function. This value is passed back to the upper layer if 894 a error occurs on the send of a message and is retrieved with each 895 unsent message (Note: if a endpoint has done multple sends, all of 896 which fail, multiple different sinfo_context values will be 897 returned. One with each user data message). 899 sinfo_flags: 16 bits (unsigned integer) 901 This field may contain any of the following flags and is composed of 902 a bitwise OR of these values. 904 recvmsg() flags: 906 MSG_UNORDERED - This flag is present when the message was sent 907 non-ordered. 909 sendmsg() flags: 911 MSG_UNORDERED - This flag requests the un-ordered delivery of the 912 message. If this flag is clear the datagram is 913 considered an ordered send. 915 MSG_ADDR_OVER - This flag, in the UDP model, requests the SCTP 916 stack to override the primary destination address 917 with the address found with the sendto/sendmsg 918 call. 920 MSG_ABORT - Setting this flag causes the specified association 921 to abort by sending an ABORT message to the peer 922 (UDP-style only). 924 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 925 procedures which assure that all data enqueued by 926 both endpoints are successfully transmitted before 927 closing the association (UDP-style only). 929 sinfo_dscp: 8 bits (unsigned integer) 931 This field is available to change the DSCP value in the outbound IP 932 packet (hence it is used only from sendmsg()). The default value of 933 this field is 0. Note only 6 bits of this byte are used, the upper 2 934 bits are not part of the DS field. Any setting within these upper 2 935 bits is ignored. 937 sinfo_assoc_id: sizeof (sctp_assoc_t) 939 The association handle field, sinfo_assoc_id, holds the identifier 940 for the association announced in the COMMUNICATION_UP notification. 941 All notifications for a given association have the same identifier. 943 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 945 5.3 SCTP Events and Notifications 947 An SCTP application may need to understand and process events and 948 errors that happen on the SCTP stack. These events include network 949 status changes, association startups, remote operational errors and 950 undeliverable messages. All of these can be essential for the 951 application. 953 When an SCTP application layer does a recvmsg() the message read is 954 normally a data message from a peer endpoint. If the application 955 wishes to have the SCTP stack deliver notifications of non-data 956 events, it sets the appropriate socket option for the notifications 957 it wants. See section 7.3 for these socket options. When a 958 notification arrives, recvmsg() returns the notification in the 959 application-supplied data buffer via msg_iov, and sets 960 MSG_NOTIFICATION in msg_flags. 962 This section details the notification structures. Every 963 notification structure carries some common fields which provides 964 general information. 966 A recvmsg() call will return only one notification at a time. Just 967 as when reading normal data, it may return part of a notification if 968 the msg_iov buffer is not large enough. If a single read is not 969 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 970 reading the notification before subsequent data can arrive. 972 5.3.1 SCTP Notification Structure 974 The notification structure is defined as the union of all 975 notification types. 977 union sctp_notification { 978 uint16_t sn_type; /* Notification type. */ 979 struct sctp_assoc_change; 980 struct sctp_paddr_change; 981 struct sctp_remote_error; 982 struct sctp_shutdown_event; 983 }; 985 sn_type: sizeof (uint16_t) 987 The following table describes the SCTP notification and event types 988 for the field sn_type. 990 sn_type Description 991 --------- --------------------------- 993 SCTP_ASSOC_CHANGE This tag indicates that an 994 association has either been 995 opened or closed. Refer to 996 5.3.1.1 for details. 998 SCTP_PEER_ADDR_CHANGE This tag indicates that an 999 address that is part of an existing 1000 association has experienced a 1001 change of state (e.g. a failure 1002 or return to service of the 1003 reachability of a endpoint 1004 via a specific transport 1005 address). Please see 5.3.1.2 1006 for data structure details. 1008 SCTP_REMOTE_ERROR The attached error message 1009 is an Operational Error received from 1010 the remote peer. It includes the complete 1011 TLV sent by the remote endpoint. 1012 See section 5.3.1.3 for the detailed format. 1014 SCTP_SEND_FAILED The attached datagram 1015 could not be sent to the remote endpoint. 1016 This structure includes the 1017 original SCTP_SNDRCVINFO 1018 that was used in sending this 1019 message i.e. this structure 1020 uses the sctp_sndrecvinfo per 1021 section 5.3.1.4. 1023 SCTP_SHUTDOWN_EVENT The peer has sent a SHUTDOWN. No further 1024 data should be sent on this socket. 1026 5.3.1.1 SCTP_ASSOC_CHANGE 1028 Communication notifications inform the ULP that an SCTP association 1029 has either begun or ended. The identifier for the new association 1030 resides in the sctp_notification structure in the cmsg_data 1031 ancillary data. The notification information has the following 1032 format: 1034 struct sctp_assoc_change { 1035 uint16_t sac_type; 1036 uint16_t sac_flags; 1037 uint32_t sac_length; 1038 sctp_assoc_t sac_assoc_id; 1039 uint16_t sac_state; 1040 uint16_t sac_error; 1041 uint16_t sac_outbound_streams; 1042 uint16_t sac_inbound_streams; 1043 }; 1045 sac_type: 1047 It should be SCTP_ASSOC_CHANGE. 1049 sac_flags: 16 bits (unsigned integer) 1051 Currently unused. 1053 sac_length: sizeof (uint32_t) 1055 This field is the total length of the notification data, including 1056 the notification header. 1058 sac_assoc_id: sizeof (sctp_assoc_t) 1060 The association id field, holds the identifier for the association. 1061 All notifications for a given association have the same association 1062 identifier. For TCP style socket, this field is ignored. 1064 sac_state: 32 bits (signed integer) 1066 This field holds one of a number of values that communicate the 1067 event that happened to the association. They include: 1069 Event Name Description 1070 ---------------- --------------- 1071 COMMUNICATION_UP A new association is now ready 1072 and data may be exchanged with this 1073 peer. 1075 COMMUNICATION_LOST The association has failed. The association 1076 is now in the closed state. If SEND FAILED 1077 notifications are turned on, a COMMUNICATION_LOST 1078 is followed by a series of SCTP_SEND_FAILED 1079 events, one for each outstanding message. 1081 RESTART SCTP has detected that the peer has restarted. 1083 SHUTDOWN_COMPLETE The association has gracefully closed. 1085 CANT_START_ASSOC The association failed to setup. If non blocking 1086 mode is set and data was sent (in the udp mode), 1087 a CANT_START_ASSOC is followed by a series of 1088 SCTP_SEND_FAILED events, one for each outstanding 1089 message. 1091 sac_error: 32 bits (signed integer) 1093 If the state was reached due to a error condition (e.g. 1094 COMMUNICATION_LOST) any relevant error information is available in 1095 this field. This corresponds to the protocol error codes defined in 1096 [SCTP]. 1098 sac_outbound_streams: 16 bits (unsigned integer) 1099 sac_inbound_streams: 16 bits (unsigned integer) 1101 The maximum number of streams allowed in each directtion are 1102 available in sac_outbound_streams and sac_inbound streams. 1104 An application must enable this notification with setsockopt (see 1105 section 7.3) before any new associations will be accepted on a 1106 UDP-style socket. This is the mechanism by which a server (or peer 1107 application that wishes to accept new associations) instructs the 1108 SCTP stack to accept new associations on a socket. Clients (i.e. 1109 applications on which only active opens are made) can leave this 1110 ancillary data item off; they will then be assured that the only 1111 associations on the socket will be ones they actively initiated. 1112 Server or peer to peer sockets, on the other hand, will always 1113 accept new associations, so a well-written application using server 1114 UDP-style sockets must be prepared to handle new associations from 1115 unwanted peers. 1117 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1119 When a destination address on a multi-homed peer encounters a change 1120 an interface details event is sent. The information has the 1121 following structure: 1123 struct sctp_paddr_change{ 1124 uint16_t spc_type; 1125 uint16_t spc_flags; 1126 uint32_t spc_length; 1127 sctp_assoc_t spc_assoc_id; 1128 struct sockaddr_storage spc_aaddr; 1129 int spc_state; 1130 int spc_error; 1131 } 1133 spc_type: 1135 It should be SCTP_PEER_ADDR_CHANGE. 1137 spc_flags: 16 bits (unsigned integer) 1138 Currently unused. 1140 spc_length: sizeof (uint32_t) 1142 This field is the total length of the notification data, including 1143 the notification header. 1145 spc_assoc_id: sizeof (sctp_assoc_t) 1147 The association id field, holds the identifier for the association. 1148 All notifications for a given association have the same association 1149 identifier. For TCP style socket, this field is ignored. 1151 spc_aaddr: sizeof (struct sockaddr_storage) 1153 The affected address field, holds the remote peer's address that is 1154 encountering the change of state. 1156 spc_state: 32 bits (signed integer) 1158 This field holds one of a number of values that communicate the 1159 event that happened to the address. They include: 1161 Event Name Description 1162 ---------------- --------------- 1163 ADDRESS_AVAILABLE This address is now reachable. 1165 ADDRESS_UNREACHABLE The address specified can no 1166 longer be reached. Any data sent 1167 to this address is rerouted to an 1168 alternate until this address becomes 1169 reachable. 1171 ADDRESS_REMOVED The address is no longer part of 1172 the association. 1174 ADDRESS_ADDED The address is now part of the 1175 association. 1177 ADDRESS_MADE_PRIM This address has now been made 1178 to be the primary destination address. 1180 spc_error: 32 bits (signed integer) 1182 If the state was reached due to any error condition (e.g. 1183 ADDRESS_UNREACHABLE) any relevant error information is available in 1184 this field. 1186 5.3.1.3 SCTP_REMOTE_ERROR 1188 A remote peer may send an Operational Error message to its peer. 1189 This message indicates a variety of error conditions on an 1190 association. The entire error TLV as it appears on the wire is 1191 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1192 specification [SCTP] and any extensions for a list of possible 1193 error formats. SCTP error TLVs have the format: 1195 struct sctp_remote_error { 1196 uint16_t sre_type; 1197 uint16_t sre_flags; 1198 uint32_t sre_length; 1199 sctp_assoc_t sre_assoc_id; 1200 uint16_t sre_error; 1201 uint16_t sre_len; 1202 uint8_t sre_data[0]; 1203 }; 1205 sre_type: 1207 It should be SCTP_REMOTE_ERROR. 1209 sre_flags: 16 bits (unsigned integer) 1211 Currently unused. 1213 sre_length: sizeof (uint32_t) 1215 This field is the total length of the notification data, including 1216 the notification header. 1218 sre_assoc_id: sizeof (sctp_assoc_t) 1220 The association id field, holds the identifier for the association. 1221 All notifications for a given association have the same association 1222 identifier. For TCP style socket, this field is ignored. 1224 sre_error: 16 bits (unsigned integer) 1226 This value represents one of the Operational Error causes defined in 1227 the SCTP specification, in network byte order. 1229 sre_len: 16 bits (unsigned integer) 1231 This value represents the length of the operational error payload in 1232 plus the size of sre_error and sre_len in network byte order. 1234 sre_data: variable 1236 This contains the payload of the operational error as defined in the 1237 SCTP specification [SCTP] section 3.3.10. 1239 5.3.1.4 SCTP_SEND_FAILED 1241 If SCTP cannot deliver a message it may return the message as a 1242 notification. 1244 struct sctp_send_failed { 1245 uint16_t ssf_type; 1246 uint16_t ssf_flags; 1247 uint32_t ssf_length; 1248 sctp_assoc_t ssf_assoc_id; 1249 uint32_t ssf_error; 1250 struct sctp_sndrcvinfo ssf_info; 1251 uint8_t ssf_data[0]; 1252 }; 1254 ssf_type: 1256 It should be SCTP_SEND_FAILED. 1258 ssf_flags: 16 bits (unsigned integer) 1260 The flag value will take one of the following values 1262 SCTP_DATA_INQUEUE - When this flag is indicated the 1263 data was never attempted to be 1264 sent. I.e. it was never assigned 1265 a TSN and sent onto the wire. 1267 SCTP_DATA_INTMIT - When this flag is indicated the 1268 data WAS assigned a TSN and sent 1269 at least once but never acknowleded. 1271 ssf_length: sizeof (uint32_t) 1273 This field is the total length of the notification data, including 1274 the notification header. 1276 ssf_assoc_id: sizeof (sctp_assoc_t) 1278 The association id field, sf_assoc_id, holds the identifier for the 1279 association. All notifications for a given association have the 1280 same association identifier. For TCP style socket, this field is 1281 ignored. 1283 ssf_error: 16 bits (unsigned integer) 1285 This value represents the reason why the send fails. 1287 ssf_info: sizeof (struct sctp_sndrcvinfo) 1289 The original send information associated with the unsent message. 1291 ssf_data: variable 1293 The unsent message. 1295 5.3.1.5 SCTP_SHUTDOWN_EVENT 1297 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1298 inform the application that it should cease sending data. 1300 struct sctp_shutdown_event { 1301 uint16_t sse_type; 1302 uint16_t sse_flags; 1303 uint32_t sse_length; 1304 sctp_assoc_t sse_assoc_id; 1305 }; 1307 sse_type 1309 It should be SCTP_SEND_FAILED. 1311 sse_flags: 16 bits (unsigned integer) 1313 Currently unused. 1315 sse_length: sizeof (uint32_t) 1317 This field is the total length of the notification data, including 1318 the notification header. 1320 sse_assoc_id: sizeof (sctp_assoc_t) 1322 The association id field, holds the identifier for the association. 1323 All notifications for a given association have the same association 1324 identifier. For TCP style socket, this field is ignored. 1326 5.4 Ancillary Data Considerations and Semantics 1328 Programming with ancillary socket data contains some subtleties and 1329 pitfalls, which are discussed below. 1331 5.4.1 Multiple Items and Ordering 1333 Multiple ancillary data items may be included in any call to 1334 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1335 items, or both. 1337 The ordering of ancillary data items (either by SCTP or another 1338 protocol) is not significant and is implementation-dependant, so 1339 applications must not depend on any ordering. 1341 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1342 msg_iov member. There can be only a single SCTP_SNDRCV info for 1343 each sendmsg() or recvmsg() call. 1345 5.4.2 Accessing and Manipulating Ancillary Data 1347 Applications can infer the presence of data or ancillary data by 1348 examining the msg_iovlen and msg_controllen msghdr members, 1349 respectively. 1351 Implementations may have different padding requirements for 1352 ancillary data, so portable applications should make use of the 1353 macros CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and 1354 CMSG_LEN. See [RFC2292] and your SCTP implementation's documentation 1355 for more information. Following is an example, from [RFC2292], 1356 demonstrating the use of these macros to access ancillary data: 1358 struct msghdr msg; 1359 struct cmsghdr *cmsgptr; 1361 /* fill in msg */ 1363 /* call recvmsg() */ 1365 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1366 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1367 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1368 u_char *ptr; 1370 ptr = CMSG_DATA(cmsgptr); 1371 /* process data pointed to by ptr */ 1372 } 1373 } 1375 5.4.3 Control Message Buffer Sizing 1377 The information conveyed via SCTP_SNDRCV events will often be 1378 fundamental to the correct and sane operation of the sockets 1379 application. This is particularly true of the UDP semantics, but 1380 also of the TCP semantics. For example, if an application needs to 1381 send and receive data on different SCTP streams, SCTP_SNDRCV events 1382 are indispensable. 1384 Given that some ancillary data is critical, and that multiple 1385 ancillary data items may appear in any order, applications should be 1386 carefully written to always provide a large enough buffer to contain 1387 all possible ancillary data that can be presented by recvmsg(). If 1388 the buffer is too small, and crucial data is truncated, it may pose 1389 a fatal error condition. 1391 Thus it is essential that applications be able to deterministically 1392 calculate the maximum required buffer size to pass to recvmsg(). One 1393 constraint imposed on this specification that makes this possible is 1394 that all ancillary data definitions are of a fixed length. One way 1395 to calculate the maximum required buffer size might be to take the 1396 sum the sizes of all enabled ancillary data item structures, as 1397 calculated by CMSG_SPACE. For example, if we enabled 1398 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC2292], we would calculate 1399 and allocate the buffer size as follows: 1401 size_t total; 1402 void *buf; 1404 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1405 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1407 buf = malloc(total); 1409 We could then use this buffer for msg_control on each call to 1410 recvmsg() and be assured that we would not lose any ancillary data 1411 to truncation. 1413 6. Common Operations for Both Styles 1415 6.1 send(), recv(), sendto(), recvfrom() 1417 Applications can use send() and sendto() to transmit data to the 1418 peer of an SCTP endpoint. recv() and recvfrom() can be used to 1419 receive data from the peer. 1421 The syntax is: 1423 ssize_t send(int sd, connst void *msg, size_t len, int flags); 1424 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1425 const struct sockaddr *to, int tolen); 1426 ssize_t recv(int sd, void *buf, size_t len, int flags); 1427 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1428 struct sockaddr *from, int *fromlen); 1430 sd - the socket descriptor of an SCTP endpoint. 1431 msg - the message to be sent. 1432 len - the size of the message or the size of buffer. 1433 to - one of the peer addresses of the association to be 1434 used to send the message. 1435 tolen - the size of the address. 1436 buf - the buffer to store a received message. 1437 from - the buffer to store the peer address used to send the 1438 received message. 1439 fromlen - the size of the from address 1440 flags - (described below). 1442 These calls give access to only basic SCTP protocol features. If 1443 either peer in the association uses multiple streams, or sends 1444 unordered data these calls will usually be inadequate, and may 1445 deliver the data in unpredictable ways. 1447 SCTP has the concept of multiple streams in one association. The 1448 above calls do not allow the caller to specify on which stream a 1449 message should be sent. The system uses stream 0 as the default 1450 stream for send() and sendto(). recv() and recvfrom() return data 1451 from any stream, but the caller can not distinguish the different 1452 streams. This may result in data seeming to arrive out of 1453 order. Similarly, if a data chunk is sent unordered, recv() and 1454 recvfrom() provide no indication. 1456 SCTP is message based. The msg buffer above in send() and sendto() 1457 is considered to be a single message. This means that if the caller 1458 wants to send a message which is composed by several buffers, the 1459 caller needs to combine them before calling send() or sendto(). 1460 Alternately, the caller can use sendmsg() to do that without 1461 combining them. recv() and recvfrom() cannot distinguish message 1462 boundries. 1464 In receiving, if the buffer supplied is not large enough to hold a 1465 complete messaage, the receive call acts like a stream socket and 1466 returns as much data as will fit in the buffer. 1468 Note, the send and recv calls, when used in the UDP-style model, may 1469 only be used with "peeled off" or high bandwidth socket descriptors 1470 (see Section 8.2). 1472 6.2 setsockopt(), getsockopt() 1474 Applications use setsockopt() and getsockopt() to set or retrieve 1475 socket options. Socket options are used to change the default 1476 behavior of sockets calls. They are described in Section 7. 1478 The syntax is: 1480 ret = getsockopt(int sd, int level, int optname, void *optval, 1481 size_t *optlen); 1482 ret = setsockopt(int sd, int level, int optname, const void *optval, 1483 size_t optlen); 1485 sd - the socket descript. 1486 level - set to IPPROTO_SCTP for all SCTP options. 1487 optname - the option name. 1488 optval - the buffer to store the value of the option. 1489 optlen - the size of the buffer (or the length of the option 1490 returned). 1492 6.3 read() and write() 1494 Applications can use read() and write() to send and receive data to 1495 and from peer. They have the same semantics as send() and recv() 1496 except that the flags parameter cannot be used. 1498 Note, these calls, when used in the UDP-style model, may only be 1499 used with high bandwidth socket descriptors (see Section 8.2). 1501 7. Socket Options 1503 The following sub-section describes various SCTP level socket 1504 options that are common to both models. SCTP associations can be 1505 multihomed. Therefore, certain option parameters include a 1506 sockaddr_storage structure to select which peer address the option 1507 should be applied to. 1509 For the datagram model, an sctp_assoc_t structure (association ID) 1510 is used to identify the the association instance that the operation 1511 affects. So it must be set when using this model. 1513 For the connnection oriented model and high bandwidth datagram 1514 sockets (see section 8.2) this association ID parameter is ignored. 1516 In the cases noted below where the parameter is ignored, an 1517 application can pass to the system a corresponding option structure 1518 similar to those described below but without the association ID 1519 parameter, which should be the last field of the option structure. 1520 This can make the option setting/getting operation more efficient. 1521 If an application does this, it should also specify an appropriate 1522 optlen value (i.e. sizeof (option parameter) - sizeof (struct 1523 sctp_assoc_t)). 1525 Note that socket or IP level options is set or retrieved per socket. 1526 This means that for datagram model, those options will be applied to 1527 all associations belonging to the socket. And for TCP-style model, 1528 those options will be applied to all peer addresses of the 1529 association controlled by the socket. Applications should be very 1530 careful in setting those options. 1532 7.1 Read / Write Options 1534 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1536 The protocol parameters used to initialize and bound retransmission 1537 timeout (RTO) are tunable. See [SCTP] for more information on how 1538 these parameters are used in RTO calculation. The peer address 1539 parameter is ignored for TCP style socket. 1541 The following structure is used to access and modify these 1542 parameters: 1544 struct sctp_rtoinfo { 1545 uint32_t srto_initial; 1546 uint32_t srto_max; 1547 uint32_t srto_min; 1548 sctp_assoc_t srto_assoc_id; 1549 }; 1551 srto_initial - This contains the initial RTO value. 1552 srto_max and srto_min - These contain the maximum and minumum bounds 1553 for all RTOs. 1554 srto_assoc_id - (UDP style socket) This is filled in the application, 1555 and identifies the association for this query. 1557 All parameters are time values, in milliseconds. A value of 0, when 1558 modifying the parameters, indicates that the current value should 1559 not be changed. 1561 To access or modify these parameters, the application should call 1562 getsockopt or setsockopt() respectively with the option name 1563 SCTP_RTOINFO. 1565 7.1.2 Association Retransmission Parameter (SCTP_ASSOCRTXINFO) 1567 The protocol parameter used to set the number of retransmissions 1568 sent before an association is considered unreachable. 1569 See [SCTP] for more information on how this parameter is used. The 1570 peer address parameter is ignored for TCP style socket. 1572 The following structure is used to access and modify this 1573 parameters: 1575 struct sctp_assocparams { 1576 uint16_t sasoc_asocmaxrxt; 1577 sctp_assoc_t sasoc_assoc_id; 1578 }; 1580 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 1581 to make for the association. 1582 sasoc_assoc_id - (UDP style socket) This is filled in the application, 1583 and identifies the association for this query. 1585 To access or modify these parameters, the application should call 1586 gesockopt or setsockopt() respectively with the option name 1587 SCTP_ASSOCRTXINFO. 1589 The maximum number of retransmissions before an address is 1590 considered unreachable is also tunable, but is address-specific, so 1591 it is covered in a seperate option. If an application attempts to 1592 set the value of the association maximum retransmission parameter to 1593 more than the sum of all maximum retransmission parameters, 1594 setsockopt() shall return an error. The reason for this, from 1595 [SCTP] section 8.2: 1597 Note: When configuring the SCTP endpoint, the user should avoid 1598 having the value of 'Association.Max.Retrans' larger than the 1599 summation of the 'Path.Max.Retrans' of all the destination addresses 1600 for the remote endpoint. Otherwise, all the destination addresses 1601 may become inactive while the endpoint still considers the peer 1602 endpoint reachable. 1604 7.1.3 Initialization Parameters (SCTP_INITMSG) 1606 Applications can specify protocol parameters for the default 1607 association intialization. The structure used to access and modify 1608 these parameters is defined in section 5.2.1. The option name 1609 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 1611 Setting initialization parameters is effective only on an 1612 unconnected socket (for the datagram model only future associations 1613 are effected by the change). This option is inherited by sockets 1614 derived from a listener socket. 1616 7.1.4 SO_LINGER 1618 An application using the TCP-style socket can use this option to 1619 perform the SCTP ABORT primitive. The linger option structure is: 1621 struct linger { 1622 int l_onoff; /* option on/off */ 1623 int l_linger; /* linger time */ 1625 }; 1627 To enable the option, set l_onoff to 1. If the l_linger value is 1628 set to 0, calling close() is the same as the ABORT primitive. If 1629 the value is set to a negative value, the setsockopt() call will 1630 return an error. If the value is set to a positive value 1631 linger_time, the close() can be blocked for at most linger_time ms. 1632 If the graceful shutdown phase does not finish during this period, 1633 close() will return but the graceful shutdown phase continues in the 1634 system. 1636 7.1.5 SCTP_NODELAY 1638 Turn off any Nagle-like algorithm. This means that packets are 1639 generally sent as soon as possible and no unnecessary delays are 1640 introduced, at the cost of more packets in the network. Expects an 1641 integer boolean flag. 1643 7.1.6 SO_RCVBUF 1645 Sets receive buffer size. For SCTP TCP-style sockets, this controls 1646 the receiver window size. For UDP-style sockets, this controls the 1647 receiver window size for all associations bound to the socket 1648 descriptor used in the setsockopt() or getsockopt() call. The option 1649 applies to each association's window size seperately. Expects an 1650 integer boolean flag. 1652 7.1.7 SO_SNDBUF 1654 Sets send buffer size. For SCTP TCP-style sockets, this controls the 1655 amount of data SCTP may have waiting in internal buffers to be 1656 sent. This option therefore bounds the maximum size of data that can 1657 be sent in a single send call. For UDP-style sockets, the effect is 1658 the same, except that it applies to all associations bound to the 1659 socket descriptor used in the setsockopt() or getsockopt() call. The 1660 option applies to each association's window size seperately. Expects 1661 an integer boolean flag. 1663 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 1665 This socket option is applicable to the UDP-style socket only. When 1666 set it will cause associations that are idle for more than the 1667 specified number of seconds to automatically close. An association 1668 being idle is defined an association that has NOT sent or recieved 1669 user data. The special value of '0' indicates that no automatic 1670 close of any associations should be performed. The option expects 1671 an integer defining the number of seconds of idle time before 1672 an associatin is closed. 1674 7.2 Read-Only Options 1676 7.2.1 Association Status (SCTP_STATUS) 1678 Applications can retrieve current status information about an 1679 association, including association state, peer receiver window size, 1680 number of unacked data chunks, and number of data chunks pending 1681 receipt. This information is read-only. The following structure is 1682 used to access this information: 1684 struct sctp_status { 1685 int32_t sstat_state; 1686 uint32_t sstat_rwnd; 1687 uint16_t sstat_unackdata; 1688 uint16_t sstat_penddata; 1689 struct sctp_paddrinfo sstat_primary; 1690 sctp_assoc_t sstat_assoc_id; 1691 }; 1693 sstat_state - This contains the association's current state one 1694 of the following values: 1696 SCTP_CLOSED 1697 SCTP_BOUND 1698 SCTP_LISTEN 1699 SCTP_COOKIE_WAIT 1700 SCTP_COOKIE_ECHOED 1701 SCTP_ESTABLISHED 1702 SCTP_SHUTDOWN_PENDING 1703 SCTP_SHUTDOWN_SENT 1704 SCTP_SHUTDOWN_RECEIVED 1705 SCTP_SHUTDOWN_ACK_SENT 1707 sstat_rwnd - This contains the association peer's current 1708 receiver window size. 1709 sstat_unackdata - This is the number of unacked data chunks. 1710 sstat_penddata - This is the number of data chunks pending receipt. 1711 sstat_primary - This is information on the current primary peer 1712 address. 1713 sstat_assoc_id - (UDP style socket) This holds the an identifier for the 1714 association. All notifications for a given association 1715 have the same association identifier. 1717 To access these status values, the application calls getsockopt() 1718 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 1719 ignored for TCP style socket. 1721 7.3. Ancillary Data Interest Options 1723 Applications can receive notifications of certain SCTP events and 1724 per-message information as ancillary data with recvmsg(). 1726 The following optional information is available to the application: 1728 1. SCTP_RECVDATAIOEVNT: Per-message information (i.e. stream number, 1729 TSN, SSN, etc. described in section 5.2.2) 1730 2. SCTP_RECVASSOCEVNT: (described in section 5.3.1.1) 1731 3. SCTP_RECVPADDREVNT: (described in section 5.3.1.2) 1732 4. SCTP_RECVPEERERR: (described in section 5.3.1.3) 1733 5. SCTP_RECVSENDFAILEVNT: (described in section 5.3.1.4) 1734 6. SCTP_RECVSHUTDOWNEVNT: (described in section 5.3.1.5); 1736 To receive any ancillary data, first the application registers it's 1737 interest by calling setsockopt() to turn on the corresponding flag: 1739 int on = 1; 1741 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, &on, sizeof(on)); 1742 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, &on, sizeof(on)); 1743 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, &on, sizeof(on)); 1744 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, &on, sizeof(on)); 1745 setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, &on, sizeof(on)); 1747 Note that for UDP-style SCTP sockets, the caller of recvmsg() 1748 receives ancillary data for ALL associations bound to the file 1749 descriptor. For TCP-style SCTP sockets, the caller receives 1750 ancillary data for only the single association bound to the file 1751 descriptor. 1753 By default a TCP-style socket has all options off. 1755 By default a UDP-style socket has SCTP_REVCVDATAIOEVENT on and all 1756 other options off. 1758 The format of the data structures for each ancillary data item is 1759 given in section 5.2. 1761 8. New Interfaces 1763 Depending on the system, the following interface can be implemented 1764 as a system call or library funtion. 1766 8.1 sctp_bindx() 1768 The syntax of sctp_bindx() is, 1770 int sctp_bindx(int sd, struct sockaddr_storage *addrs, int addrcnt, 1771 int flags); 1773 If sd is an IPv4 socket, the addresses passed must be IPv4 1774 addresses. If the sd is an IPv6 socket, the addresses passed can 1775 either be IPv4 or IPv6 addresses. 1777 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 1778 section 3.1.2 for this usage. 1780 addrs is a pointer to an array of one or more socket addresses. 1781 Each address is contained in a struct sockaddr_storage, so each 1782 address is a fixed length. The caller specifies the number of 1783 addresses in the array with addrcnt. 1785 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 1786 -1, and sets errno to the appropriate error code. 1788 For SCTP, the port given in each socket address must be the same, or 1789 sctp_bindx() will fail, setting errno to EINVAL. 1791 The flags parameter is formed from the bitwise OR of zero or more of 1792 the following currently defined flags: 1794 SCTP_BINDX_ADD_ADDR 1795 SCTP_BINDX_REM_ADDR 1797 SCTP_BIND_ADD_ADDR directs SCTP to add the given addresses to the 1798 association, and SCTP_BIND_REM_ADDR directs SCTP to remove the given 1799 addresses from the association. The two flags are mutually 1800 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 1801 caller may not remove all addresses from an association; 1802 sctp_bindx() will reject such an attempt with EINVAL. 1804 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 1805 additional addresses with an endpoint after calling bind(). Or use 1806 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 1807 socket is associated with so that no new association accepted will 1808 be associated with those addresses. 1810 Adding and removing addresses from a connected association is 1811 optional functionality. Implementations that do not support this 1812 functionality should return EOPNOTSUPP. 1814 8.2 Branched-off Association 1816 After an association is established on a UDP-style socket, the 1817 application may wish to branch off the association into a separate 1818 socket/file descriptor. 1820 This is particularly desirable when, for instance, the application 1821 wishes to have a number of sporadic message senders/receivers remain 1822 under the original UDP-style socket but branch off those 1823 associations carrying high volume data traffic into their own 1824 separate socket descriptors. 1826 The application uses sctp_peeloff() call to branch off an 1827 association into a separate socket (Note the semantics are somewhat 1828 changed from the traditional TCP-style accept() call). 1830 The syntax is: 1832 new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id, int *addrlen) 1834 new_sd - the new socket descriptor representing the branched-off 1835 association. 1837 sd - the original UDP-style socket descriptor returned from the 1838 socket() system call (see Section 3.1.1). 1840 assoc_id - the specified identifier of the association that is to be 1841 branched off to a separate file descriptor (Note, in a 1842 traditional TCP-style accept() call, this would be an out 1843 parameter, but for the UDP-style call, this is an in 1844 parameter). 1846 addrlen - an integer pointer to the size of the sockaddr structure 1847 addr (in a traditional TCP-style call, this would be a out 1848 parameter, but for the UDP-style call this is an in 1849 parameter). 1851 8.3 sctp_getpaddrs() 1853 sctp_getpaddrs() returns all peer addresses in an association. The 1854 syntax is, 1856 int sctp_getpaddrs(int sd, sctp_assoc_t id, 1857 struct sockaddr_storage **addrs); 1859 On return, addrs will point to a dynamically allocated array of 1860 struct sockaddr_storages, one for each peer address. The caller 1861 should use sctp_freepaddrs() to free the memory. addrs must not be 1862 NULL. 1864 If sd is an IPv4 socket, the addresses returned will be all IPv4 1865 addresses. If sd is an IPv6 socket, the addresses returned can be a 1866 mix of IPv4 or IPv6 addresses. 1868 For UDP-style sockets, id specifies the association to query. For 1869 TCP-style sockets, id is ignored. 1871 On success, sctp_getpaddrs() returns the number of peer addresses in 1872 the association. If there is no association on this socket, 1873 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 1874 an error occurs, sctp_getpaddrs() returns -1, and the value of 1875 *addrs is undefined. 1877 8.4 sctp_freepaddrs() 1879 sctp_freepaddrs() frees all resources allocated by 1880 sctp_getpaddrs(). Its syntax is, 1882 void sctp_freepaddrs(struct sockaddr_storage *addrs); 1884 addrs is the array of peer addresses returned by sctp_getpaddrs. 1886 8.5 sctp_opt_info() 1888 getsockopt() is read-only, so a new interface is required when 1889 information must be passed both in to and out of the SCTP stack. The 1890 syntax for scpt_opt_info() is, 1892 int sctp_opt_info(int sd, sctp_assoc_t id, int opt, void *arg); 1893 For UDP-style sockets, id specifies the association to query. For 1894 TCP-style sockets, id is ignored. 1896 opt specifies which SCTP option to get or set. It can be one of the 1897 following: 1899 SCTP_SET_PRIMARY_ADDRS 1900 SCTP_SET_PEER_PRIMARY_ADDRS 1901 SCTP_SET_PEER_ADDR_PARAMS 1902 SCTP_GET_PEER_ADDR_PARAMS 1903 SCTP_GET_PEER_ADDR_INFO 1905 arg is an option-specific structure buffer provided by the caller. 1906 See 8.5 subsections for more information on these options and 1907 option-specific structures. 1909 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1910 sets errno to the appropriate error code. 1912 8.5.1 Peer Address Parameters 1914 Applications can enable or disable heartbeats for any peer address 1915 of an association, modify an address's heartbeat interval, force a 1916 heartbeat to be sent immediately, and adjust the address's maximum 1917 number of retransmissions sent before an address is considered 1918 unreachable. An application may also set what it deems as the 1919 primary address as well as communicate to the remote peer what 1920 address the local application would like the remote peer to use 1921 as its primary address (when sending to the local endpoint). 1922 The following structure is used to access and modify an address's 1923 parameters: 1925 struct sctp_paddrparams { 1926 struct sockaddr_storage spp_address; 1927 uint32_t spp_hbinterval; 1928 uint16_t spp_pathmaxrxt; 1929 sctp_assoc_t spp_assoc_id; 1930 }; 1932 spp_address - This specifies which address is of interest. 1933 spp_hbinterval - This contains the value of the heartbeat interval, 1934 in milliseconds. A value of 0, when modifying the 1935 parameter, specifies that the heartbeat on this 1936 address should be disabled. A value of UINT32_MAX 1937 (4294967295), when modifying the parameter, 1938 specifies that a heartbeat should be sent 1939 immediately to the peer address, and the current 1940 interval should remain unchanged. 1941 spp_pathmaxrxt - This contains the maximum number of 1942 retransmissions before this address shall be 1943 considered unreachable. 1944 spp_assoc_id - (UDP style socket) This is filled in the application, 1945 and identifies the association for this query. 1947 To modify these parameters, the application should call 1948 sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. To get 1949 these parameters, the application should use 1950 SCTP_GET_PEER_ADDR_PARAMS. 1952 8.5.2 Peer Address Information 1954 Applications can retrieve information about a specific peer address 1955 of an association, including its reachability state, congestion 1956 window, and retransmission timer values. This information is 1957 read-only. The following structure is used to access this 1958 information: 1960 struct sctp_paddrinfo { 1961 struct sockaddr_storage spinfo_address; 1962 int32_t spinfo_state; 1963 uint32_t spinfo_cwnd; 1964 uint32_t spinfo_srtt; 1965 uint32_t spinfo_rto; 1966 sctp_assoc_t spinfo_assoc_id; 1967 }; 1969 spinfo_address - This is filled in the application, and contains 1970 the peer address of interest. 1972 On return from getsockopt(): 1974 spinfo_state - This contains the peer addresses's state (either 1975 SCTP_ACTIVE or SCTP_INACTIVE). 1976 spinfo_cwnd - This contains the peer addresses's current congestion 1977 window. 1978 spinfo_srtt - This contains the peer addresses's current smoothed 1979 round-trip time calculation in milliseconds. 1980 spinfo_rto - This contains the peer addresses's current 1981 retransmission timeout value in milliseconds. 1982 spinfo_assoc_id - (UDP style socket) This is filled in the application, 1983 and identifies the association for this query. 1985 To retrieve this information, use sctp_opt_info() with the 1986 SCTP_GET_PEER_ADDR_INFO options. 1988 9. Security Considerations 1990 Many TCP and UDP implementations reserve port numbers below 1024 for 1991 privileged users. If the target platform supports privileged users, 1992 the SCTP implementation SHOULD restrict the ability to call bind() 1993 or sctp_bindx() on these port numbers to privileged users. 1995 Similarly unprivelged users should not be able to set protocol 1996 parameters which could result in the congestion control algorithm 1997 being more agressive than permitted on the public Internet. These 1998 paramaters are: 2000 struct sctp_rtoinfo 2002 If an unprivileged user inherits a datagram model socket with open 2003 associations on a privileged port, it MAY be permitted to accept new 2004 associations, but it SHOULD NOT be permitted to open new 2005 associations. This could be relevant for the r* family of 2006 protocols. 2008 10. Authors' Addresses 2010 Randall R. Stewart Tel: +1-815-477-2127 2011 Cisco Systems, Inc. EMail: rrs@cisco.com 2012 Crystal Lake, IL 60012 2013 USA 2015 Qiaobing Xie Tel: +1-847-632-3028 2016 Motorola, Inc. EMail: qxie1@email.mot.com 2017 1501 W. Shure Drive, Room 2309 2018 Arlington Heights, IL 60004 2019 USA 2021 La Monte H.P. Yarroll NIC Handle: LY 2022 Motorola, Inc. EMail: piggy@acm.org 2023 1501 W. Shure Drive, IL27-2315 2024 Arlington Heights, IL 60004 2025 USA 2027 Jonathan Wood 2028 Sun Microsystems, Inc. Email: jonathan.wood@sun.com 2029 901 San Antonio Road 2030 Palo Alto, CA 94303 2031 USA 2033 Kacheong Poon 2034 Sun Microsystems, Inc. Email: kacheong.poon@sun.com 2035 901 San Antonio Road 2036 Palo Alto, CA 94303 2037 USA 2039 Ken Fujita Tel: +81-471-82-1131 2040 NEC Corporation Email: fken@cd.jp.nec.com 2041 1131, Hinode, Abiko 2042 Chiba, 270-1198 2043 Japan 2045 11. References 2047 [RFC1644] Braden, R., "T/TCP -- TCP Extensions for Transactions 2048 Functional Specification," RFC 1644, July 1994. 2050 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", 2051 RFC 2026, October 1996. 2053 [RFC2292] W.R. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 2054 RFC 2292, February 1998. 2056 [RFC2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens. "Basic Socket 2057 Interface Extensions for IPv6," RFC 2553, March 1999. 2059 [SCTP] R.R. Stewart, Q. Xie, K. Morneault, C. Sharp, H.J. Schwarzbauer, 2060 T. Taylor, I. Rytina, M. Kalla, L. Zhang, and, V. Paxson, 2061 "Stream Control Transmission Protocol," RFC2960, October 2000. 2063 [STEVENS] W.R. Stevens, M. Thomas, E. Nordmark, "Advanced Sockets API for 2064 IPv6," , December 1999 2065 (Work in progress) 2067 Appendix A: TCP-style Code Example 2069 The following code is a simple implementation of an echo server over 2070 SCTP. The example shows how to use some features of TCP-style IPv4 2071 SCTP sockets, including: 2073 o Opening, binding, and listening for new associations on a socket; 2074 o Enabling ancillary data 2075 o Enabling notifications 2076 o Using ancillary data with sendmsg() and recvmsg() 2077 o Using MSG_EOR to determine if an entire message has been read 2078 o Handling notifications 2080 static void 2081 handle_event(void *buf) 2082 { 2083 struct sctp_assoc_change *sac; 2084 struct sctp_send_failed *ssf; 2085 struct sctp_paddr_change *spc; 2086 struct sctp_remote_error *sre; 2087 union sctp_notification *snp; 2088 char addrbuf[INET6_ADDRSTRLEN]; 2089 const char *ap; 2090 struct sockaddr_in *sin; 2091 struct sockaddr_in6 *sin6; 2093 snp = buf; 2095 switch (snp->sn_type) { 2096 case SCTP_ASSOC_CHANGE: 2097 sac = &snp->sn_assoc_change; 2098 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2099 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2100 sac->sac_inbound_streams, sac->sac_outbound_streams); 2101 break; 2102 case SCTP_SEND_FAILED: 2103 ssf = &snp->sn_send_failed; 2104 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2105 ssf->ssf_error); 2106 break; 2107 case SCTP_PEER_ADDR_CHANGE: 2108 spc = &snp->sn_intf_change; 2109 if (spc->spc_addr.ss_family == AF_INET) { 2110 sin = (struct sockaddr_in *)&spc->spc_addr; 2111 ap = inet_ntop(AF_INET, &sin->sin_addr, addrbuf, 2112 INET6_ADDRSTRLEN); 2113 } else { 2114 sin6 = (struct sockaddr_in6 *)&spc->spc_addr; 2115 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, addrbuf, 2116 INET6_ADDRSTRLEN); 2117 } 2118 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2119 spc->spc_state, spc->spc_error); 2120 break; 2121 case SCTP_REMOTE_ERROR: 2122 sre = &snp->sn_remote_error; 2123 printf("^^^ remote_error: err=%hu len=%hu\n", 2124 ntohs(sre->sre_error), ntohs(sre->sre_len)); 2125 break; 2126 case SCTP_SHUTDOWN_EVENT: 2127 printf("^^^ shutdown event\n"); 2128 break; 2129 default: 2130 printf("unknown type: %hu\n", snp->sn_type); 2131 break; 2132 } 2133 } 2135 static void * 2136 sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2137 ssize_t *nrp, size_t cmsglen) 2138 { 2139 ssize_t nr = 0; 2140 struct iovec iov[1]; 2142 *nrp = 0; 2143 iov->iov_base = buf; 2144 msg->msg_iov = iov; 2145 msg->msg_iovlen = 1; 2147 for (;;) { 2148 msg->msg_flags = MSG_XPG4_2; 2149 msg->msg_iov->iov_len = *buflen; 2150 msg->msg_controllen = cmsglen; 2152 nr += recvmsg(fd, msg, 0); 2153 if (nr <= 0) { 2154 /* EOF or error */ 2155 *nrp = nr; 2156 return (NULL); 2157 } 2158 if ((msg->msg_flags & MSG_EOR) != 0) { 2159 *nrp = nr; 2160 return (buf); 2161 } 2163 /* Realloc the buffer? */ 2164 if (*buflen == nr) { 2165 buf = realloc(buf, *buflen * 2); 2166 if (buf == 0) { 2167 fprintf(stderr, "out of memory\n"); 2168 exit(1); 2169 } 2170 *buflen *= 2; 2171 } 2173 /* Set the next read offset */ 2174 iov->iov_base = (char *)buf + nr; 2175 iov->iov_len = *buflen - nr; 2177 } 2178 } 2180 static void 2181 echo(int fd, int socketModeUDP) 2182 { 2183 ssize_t nr; 2184 struct sctp_sndrcvinfo *sri; 2185 struct msghdr msg[1]; 2186 struct cmsghdr *cmsg; 2187 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 2188 char *buf; 2189 size_t buflen; 2190 struct iovec iov[1]; 2191 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 2193 /* Allocate the initial data buffer */ 2194 buflen = BUFLEN; 2195 if (!(buf = malloc(BUFLEN))) { 2196 fprintf(stderr, "out of memory\n"); 2197 exit(1); 2198 } 2200 /* Set up the msghdr structure for receiving */ 2201 memset(msg, 0, sizeof (*msg)); 2202 msg->msg_control = cbuf; 2203 msg->msg_controllen = cmsglen; 2204 msg->msg_flags = 0; 2205 cmsg = (struct cmsghdr *)cbuf; 2206 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 2208 /* Wait for something to echo */ 2209 while (buf = sctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 2211 /* Intercept notifications here */ 2212 if (msg->msg_flags & MSG_NOTIFICATION) { 2213 handle_event(buf); 2214 continue; 2215 } 2217 iov->iov_base = buf; 2218 iov->iov_len = nr; 2219 msg->msg_iov = iov; 2220 msg->msg_iovlen = 1; 2222 printf("got %u bytes on stream %hu:\n", nr, 2223 sri->sinfo_stream); 2224 write(0, buf, nr); 2226 /* Echo it back */ 2227 msg->msg_flags = MSG_XPG4_2; 2228 if (sendmsg(fd, msg, 0) < 0) { 2229 perror("sendmsg"); 2230 exit(1); 2231 } 2232 } 2234 if (nr < 0) { 2235 perror("recvmsg"); 2236 } 2237 if(socketModeUDP == 0) 2238 close(fd); 2239 } 2241 main() 2242 { 2243 int lfd, cfd; 2244 int onoff = 1; 2245 struct sockaddr_in sin[1]; 2247 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 2248 perror("socket"); 2249 exit(1); 2250 } 2252 sin->sin_family = AF_INET; 2253 sin->sin_port = htons(7); 2254 sin->sin_addr.s_addr = INADDR_ANY; 2255 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2256 perror("bind"); 2257 exit(1); 2258 } 2260 if (listen(lfd, 1) == -1) { 2261 perror("listen"); 2262 exit(1); 2263 } 2265 /* Wait for new associations */ 2266 for (;;) { 2267 if ((cfd = accept(lfd, NULL, 0)) == -1) { 2268 perror("accept"); 2269 exit(1); 2270 } 2272 /* Enable ancillary data */ 2273 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2274 &onoff, 4) < 0) { 2275 perror("setsockopt RECVDATAIOEVNT"); 2276 exit(1); 2277 } 2278 /* Enable notifications */ 2279 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, 2280 &onoff, 4) < 0) { 2281 perror("setsockopt SCTP_RECVASSOCEVNT"); 2282 exit(1); 2283 } 2284 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2285 &onoff, 4) < 0) { 2286 perror("setsockopt SCTP_RECVASSOCEVNT"); 2287 exit(1); 2288 } 2289 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2290 &onoff, 4) < 0) { 2291 perror("setsockopt SCTP_RECVPADDREVNT"); 2292 exit(1); 2293 } 2294 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2295 &onoff, 4) < 0) { 2296 perror("setsockopt SCTP_RECVDATAIOEVNT"); 2297 exit(1); 2298 } 2299 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2300 &onoff, 4) < 0) { 2301 perror("setsockopt SCTP_RECVPEERERR"); 2302 exit(1); 2303 } 2304 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2305 &onoff, 4) < 0) { 2306 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2307 exit(1); 2308 } 2310 /* Echo back any and all data */ 2311 echo(cfd,0); 2312 } 2313 } 2315 Appendix B: UDP-style Code Example 2317 The following code is a simple implementation of an echo server over 2318 SCTP. The example shows how to use some features of UDP-style IPv4 2319 SCTP sockets, including: 2321 o Opening and binding of a socket; 2322 o Enabling ancillary data 2323 o Enabling notifications 2324 o Using ancillary data with sendmsg() and recvmsg() 2325 o Using MSG_EOR to determine if an entire message has been read 2326 o Handling notifications 2328 Note most functions defined in Appendix A are reused in 2329 this example. 2331 main() 2332 { 2333 int fd; 2334 int onoff = 1; 2335 int idleTime = 2; 2336 struct sockaddr_in sin[1]; 2338 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 2339 perror("socket"); 2340 exit(1); 2341 } 2343 sin->sin_family = AF_INET; 2344 sin->sin_port = htons(7); 2345 sin->sin_addr.s_addr = INADDR_ANY; 2346 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2347 perror("bind"); 2348 exit(1); 2349 } 2351 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2352 &onoff, 4) < 0) { 2353 perror("setsockopt RECVDATAIOEVNT"); 2354 exit(1); 2355 } 2356 /* Enable notifications */ 2358 /* This will get us new associations as well */ 2359 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, 2360 &onoff, 4) < 0) { 2361 perror("setsockopt SCTP_RECVASSOCEVNT"); 2362 exit(1); 2363 } 2364 /* if a send fails we want to know it */ 2365 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2366 &onoff, 4) < 0) { 2367 perror("setsockopt SCTP_RECVASSOCEVNT"); 2368 exit(1); 2369 } 2370 /* if a network address change or event transpires 2371 * we wish to know it 2372 */ 2373 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2374 &onoff, 4) < 0) { 2375 perror("setsockopt SCTP_RECVPADDREVNT"); 2376 exit(1); 2377 } 2378 /* We would like all io events */ 2379 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2380 &onoff, 4) < 0) { 2381 perror("setsockopt SCTP_RECVDATAIOEVNT"); 2382 exit(1); 2383 } 2384 /* We would like all error TLV's from the peer */ 2385 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2386 &onoff, 4) < 0) { 2387 perror("setsockopt SCTP_RECVPEERERR"); 2388 exit(1); 2389 } 2390 /* And of course we would like to know about shutdown's */ 2391 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2392 &onoff, 4) < 0) { 2393 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2394 exit(1); 2395 } 2396 /* Set associations to auto-close in 2 seconds of 2397 * inactivity 2398 */ 2399 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 2400 &idleTime, 4) < 0) { 2401 perror("setsockopt SCTP_AUTOCLOSE"); 2402 exit(1); 2403 } 2404 /* Wait for new associations */ 2405 while(1){ 2406 /* Echo back any and all data */ 2407 echo(fd,1); 2408 } 2409 }