idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 19, 2010) is 5204 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: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 4185 == Unused Reference: 'RFC2119' is defined on line 3900, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Huawei 4 Intended status: Informational K. Poon 5 Expires: July 19, 2010 Sun Microsystems, Inc. 6 M. Tuexen 7 Univ. of Applied Sciences Muenster 8 V. Yasevich 9 HP 10 P. Lei 11 Cisco Systems, Inc. 12 January 19, 2010 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-20.txt 17 Abstract 19 This document describes a mapping of the Stream Control Transmission 20 Protocol SCTP into a sockets API. The benefits of this mapping 21 include compatibility for TCP applications, access to new SCTP 22 features and a consolidated error and event notification scheme. 24 Status of this Memo 26 This Internet-Draft is submitted to IETF in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF), its areas, and its working groups. Note that 31 other groups may also distribute working documents as Internet- 32 Drafts. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 The list of current Internet-Drafts can be accessed at 40 http://www.ietf.org/ietf/1id-abstracts.txt. 42 The list of Internet-Draft Shadow Directories can be accessed at 43 http://www.ietf.org/shadow.html. 45 This Internet-Draft will expire on July 19, 2010. 47 Copyright Notice 48 Copyright (c) 2010 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the BSD License. 61 This document may contain material from IETF Documents or IETF 62 Contributions published or made publicly available before November 63 10, 2008. The person(s) controlling the copyright in some of this 64 material may not have granted the IETF Trust the right to allow 65 modifications of such material outside the IETF Standards Process. 66 Without obtaining an adequate license from the person(s) controlling 67 the copyright in such materials, this document may not be modified 68 outside the IETF Standards Process, and derivative works of it may 69 not be created outside the IETF Standards Process, except to format 70 it for publication as an RFC or to translate it into languages other 71 than English. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 7 77 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 7 78 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 7 79 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 8 80 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 9 81 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 10 82 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 10 83 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 12 84 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 13 85 3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 13 86 3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14 87 3.4. Special considerations . . . . . . . . . . . . . . . . . . 15 88 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . . 16 89 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 17 90 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 17 91 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 18 92 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 19 93 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . . 19 94 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 20 95 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 21 96 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . . 21 97 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 22 98 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 22 99 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 23 100 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 23 101 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 24 102 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 25 103 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 26 104 5.2.3. Extended SCTP Header Information Structure 105 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 28 106 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) . . . . 29 107 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 31 108 5.2.6. SCTP Next Receive Information Structure 109 (SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . . 32 110 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . . 32 111 5.2.8. SCTP PR-SCTP Information Structure (SCTP_AUTHINFO) . . 32 112 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 33 113 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 33 114 5.3.2. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 35 115 5.3.3. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 36 116 5.3.4. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 37 117 5.3.5. SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . 38 118 5.3.6. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 39 119 5.3.7. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . . 40 120 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 40 121 5.3.9. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 41 122 5.3.10. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 42 123 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . . 42 124 5.4. Ancillary Data Considerations and Semantics . . . . . . . 42 125 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 43 126 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 43 127 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 44 128 6. Common Operations for Both Styles . . . . . . . . . . . . . . 44 129 6.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . . 44 130 6.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 46 131 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 47 132 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 47 133 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 48 134 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 50 135 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 50 136 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 50 137 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 52 138 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 52 139 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 53 140 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 53 141 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 53 142 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . . 53 143 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 54 144 7.1.10. Set Adaptation Layer Indicator 145 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 54 146 7.1.11. Enable/Disable Message Fragmentation 147 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 54 148 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 54 149 7.1.13. Set Default Send Parameters 150 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 57 151 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) . 57 152 7.1.15. Set/Clear IPv4 Mapped Addresses 153 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 57 154 7.1.16. Get or Set the Maximum Fragmentation Size 155 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 58 156 7.1.17. Get or Set the List of Supported HMAC Identifiers 157 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 58 158 7.1.18. Get or Set the Active Shared Key 159 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 59 160 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 60 161 7.1.20. Get or Set Fragmented Interleave 162 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 60 163 7.1.21. Set or Get the SCTP Partial Delivery Point 164 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 62 165 7.1.22. Set or Get the Use of Extended Receive Info 166 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 62 167 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . . 62 168 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 63 169 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 63 170 7.1.26. Enable or Disable Explicit EOR Marking 171 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 64 172 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . . 64 173 7.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 64 174 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 64 175 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 64 176 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 66 177 7.2.3. Get the List of Chunks the Peer Requires to be 178 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 66 179 7.2.4. Get the List of Chunks the Local Endpoint Requires 180 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 67 181 7.2.5. Get the Current Number of Associations 182 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 67 183 7.2.6. Get the Current Identifiers of Associations 184 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 68 185 7.3. Write-Only Options . . . . . . . . . . . . . . . . . . . . 68 186 7.3.1. Set Peer Primary Address 187 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 68 188 7.3.2. Add a Chunk That Must Be Authenticated 189 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 68 190 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . . 69 191 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . . 70 192 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . . 70 193 7.4. Ancillary Data and Notification Interest Options . . . . . 71 194 8. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 74 195 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 74 196 8.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . . 75 197 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 76 198 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 77 199 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 77 200 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 78 201 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 78 202 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 79 203 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 79 204 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 80 205 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 81 206 8.12. sctp_getaddrlen() . . . . . . . . . . . . . . . . . . . . 82 207 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 82 208 10. Security Considerations . . . . . . . . . . . . . . . . . . . 83 209 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 83 210 12. Normative References . . . . . . . . . . . . . . . . . . . . . 83 211 Appendix A. One-to-One Style Code Example . . . . . . . . . . . . 84 212 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 89 213 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 91 215 1. Introduction 217 The sockets API has provided a standard mapping of the Internet 218 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 219 [RFC0768] have benefited from this standard representation and access 220 method across many diverse platforms. SCTP is a new protocol that 221 provides many of the characteristics of TCP but also incorporates 222 semantics more akin to UDP. This document defines a method to map 223 the existing sockets API for use with SCTP, providing both a base for 224 access to new features and compatibility so that most existing TCP 225 applications can be migrated to SCTP with few (if any) changes. 227 There are three basic design objectives: 228 1. Maintain consistency with existing sockets APIs: We define a 229 sockets mapping for SCTP that is consistent with other sockets 230 API protocol mappings (for instance, UDP, TCP, IPv4, and IPv6). 231 2. Support a one-to-many style interface This set of semantics is 232 similar to that defined for connection-less protocols, such as 233 UDP. A one-to-many style SCTP socket should be able to control 234 multiple SCTP associations. This is similar to a UDP socket, 235 which can communicate with many peer end points. Each of these 236 associations is assigned an association ID so that an application 237 can use the ID to differentiate them. Note that SCTP is 238 connection-oriented in nature, and it does not support broadcast 239 or multicast communications, as UDP does. 240 3. Support a one-to-one style interface This interface supports a 241 similar semantics as sockets for connection-oriented protocols, 242 such as TCP. A one-to-one style SCTP socket should only control 243 one SCTP association. One purpose of defining this interface is 244 to allow existing applications built on other connection-oriented 245 protocols be ported to use SCTP with very little effort. And 246 developers familiar with those semantics can easily adapt to 247 SCTP. Another purpose is to make sure that existing mechanisms 248 in most OSes to deal with socket, such as select(), should 249 continue to work with this style of socket. Extensions are added 250 to this mapping to provide mechanisms to exploit new features of 251 SCTP. 253 Goals 2 and 3 are not compatible, so in this document we define two 254 modes of mapping, namely the one-to-many style mapping and the one- 255 to-one style mapping. These two modes share some common data 256 structures and operations, but will require the use of two different 257 application programming styles. Note that all new SCTP features can 258 be used with both styles of socket. The decision on which one to use 259 depends mainly on the nature of applications. 261 A mechanism is defined to extract a one-to-many style SCTP 262 association into a one-to-one style socket. 264 Some of the SCTP mechanisms cannot be adequately mapped to existing 265 socket interface. In some cases, it is more desirable to have new 266 interface instead of using existing socket calls. Section 8 of this 267 document describes those new interface. 269 2. Data Types 271 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 272 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 273 (e.g., uint16_t). We also assume the argument data types from 274 1003.1g when possible (e.g., the final argument to setsockopt() is a 275 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 276 size_t data type is used. 278 3. One-to-Many Style Interface 280 The one-to-many style interface has the following characteristics: 281 o Outbound association setup is implicit. 282 o Messages are delivered in complete messages (with one notable 283 exception). 284 o There is a 1 to MANY relationship between socket and association. 286 3.1. Basic Operation 288 A typical server in this style uses the following socket calls in 289 sequence to prepare an endpoint for servicing requests: 290 o socket() 291 o bind() 292 o listen() 293 o recvmsg() 294 o sendmsg() 295 o close() 297 A typical client uses the following calls in sequence to setup an 298 association with a server to request services: 299 o socket() 300 o sendmsg() 301 o recvmsg() 302 o close() 304 In this style, by default, all the associations connected to the 305 endpoint are represented with a single socket. Each associations is 306 assigned an association ID (type is sctp_assoc_t) so that an 307 application can use it to differentiate between them. In some 308 implementations, the peer endpoints addresses can also be used for 309 this purpose. But this is not required for performance reasons. If 310 an implementation does not support using addresses to differentiate 311 between different associations, the sendto() call can only be used to 312 setup an association implicitly. It cannot be used to send data to 313 an established association as the association ID cannot be specified. 315 Once as association ID is assigned to an SCTP association, that ID 316 will not be reused until the application explicitly terminates the 317 association. The resources belonging to that association will not be 318 freed until that happens. This is similar to the close() operation 319 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 320 option (section 7.1.8) is set. In this case, after the association 321 is terminated gracefully and automatically, the association ID 322 assigned to it can be reused. All applications using this option 323 should be aware of this to avoid the possible problem of sending data 324 to an incorrect peer end point. 326 If the server or client wishes to branch an existing association off 327 to a separate socket, it is required to call sctp_peeloff() and in 328 the parameter specifies the association identification. The 329 sctp_peeloff() call will return a new socket which can then be used 330 with recv() and send() functions for message passing. See 331 Section 8.2 for more on branched-off associations. 333 Once an association is branched off to a separate socket, it becomes 334 completely separated from the original socket. All subsequent 335 control and data operations to that association must be done through 336 the new socket. For example, the close operation on the original 337 socket will not terminate any associations that have been branched 338 off to a different socket. 340 We will discuss the one-to-many style socket calls in more details in 341 the following subsections. 343 3.1.1. socket() 345 Applications use socket() to create a socket descriptor to represent 346 an SCTP endpoint. 348 The function prototype is 350 int socket(int domain, 351 int type, 352 int protocol); 354 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 355 type and IPPROTO_SCTP as the protocol. 357 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 358 socket. 360 Using the PF_INET domain indicates the creation of an endpoint which 361 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 362 can use both IPv6 and IPv4 address. 364 3.1.2. bind() 366 Applications use bind() to specify which local address the SCTP 367 endpoint should associate itself with. 369 An SCTP endpoint can be associated with multiple addresses. To do 370 this, sctp_bindx() is introduced in Section 8.1 to help applications 371 do the job of associating multiple addresses. 373 These addresses associated with a socket are the eligible transport 374 addresses for the endpoint to send and receive data. The endpoint 375 will also present these addresses to its peers during the association 376 initialization process, see [RFC4960]. 378 After calling bind(), if the endpoint wishes to accept new 379 associations on the socket, it must call listen() (see 380 Section 3.1.3). 382 The function prototype of bind() is 384 int bind(int sd, 385 struct sockaddr *addr, 386 socklen_t addrlen); 388 and the arguments are 389 sd: The socket descriptor returned by socket(). 390 addr: The address structure (struct sockaddr_in or struct 391 sockaddr_in6, see [RFC3493]). 392 addrlen: The size of the address structure. 394 If sd is an IPv4 socket, the address passed must be an IPv4 address. 395 If the sd is an IPv6 socket, the address passed can either be an IPv4 396 or an IPv6 address. 398 Applications cannot call bind() multiple times to associate multiple 399 addresses to an endpoint. After the first call to bind(), all 400 subsequent calls will return an error. 402 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 403 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 404 operating system will associate the endpoint with an optimal address 405 set of the available interfaces. 407 If a bind() is not called prior to a sendmsg() call that initiates a 408 new association, the system picks an ephemeral port and will choose 409 an address set equivalent to binding with a wildcard address. One of 410 those addresses will be the primary address for the association. 411 This automatically enables the multi-homing capability of SCTP. 413 3.1.3. listen() 415 By default, new associations are not accepted for one-to-many style 416 sockets. An application uses listen() to mark a socket as being able 417 to accept new associations. 419 The function prototype is 421 int listen(int sd, 422 int backlog); 424 and the arguments are 425 sd: The socket descriptor of the endpoint. 426 backlog: If backlog is non-zero, enable listening else disable 427 listening. 429 Note that one-to-many style socket consumers do not need to call 430 accept to retrieve new associations. Calling accept() on a one-to- 431 many style socket should return EOPNOTSUPP. Rather, new associations 432 are accepted automatically, and notifications of the new associations 433 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 434 these notifications are enabled). Clients will typically not call 435 listen(), so that they can be assured that the only associations on 436 the socket will be ones they actively initiated. Server or peer-to- 437 peer sockets, on the other hand, will always accept new associations, 438 so a well-written application using server one-to-many style sockets 439 must be prepared to handle new associations from unwanted peers. 441 Also note that the SCTP_ASSOC_CHANGE event provides the association 442 ID for a new association, so if applications wish to use the 443 association ID as input to other socket calls, they should ensure 444 that the SCTP_ASSOC_CHANGE event is enabled. 446 3.1.4. sendmsg() and recvmsg() 448 An application uses sendmsg() and recvmsg() call to transmit data to 449 and receive data from its peer. 451 The function prototypes are 453 ssize_t sendmsg(int sd, 454 const struct msghdr *message, 455 int flags); 457 and 459 ssize_t recvmsg(int sd, 460 struct msghdr *message, 461 int flags); 463 using the arguments: 464 sd: The socket descriptor of the endpoint. 465 message: Pointer to the msghdr structure which contains a single 466 user message and possibly some ancillary data. See Section 5 for 467 complete description of the data structures. 468 flags: No new flags are defined for SCTP at this level. See 469 Section 5 for SCTP-specific flags used in the msghdr structure. 471 As we will see in Section 5, along with the user data, the ancillary 472 data field is used to carry the sctp_sndrcvinfo and/or the 473 sctp_initmsg structures to perform various SCTP functions including 474 specifying options for sending each user message. Those options, 475 depending on whether sending or receiving, include stream number, 476 stream sequence number, various flags, context and payload protocol 477 Id, etc. 479 When sending user data with sendmsg(), the msg_name field in msghdr 480 structure will be filled with one of the transport addresses of the 481 intended receiver. If there is no association existing between the 482 sender and the intended receiver, the sender's SCTP stack will set up 483 a new association and then send the user data (see Section 3.2 for 484 more on implicit association setup). If an SCTP_INIT cmsg structure 485 is used with NULL data, an association will be established using the 486 parameters from the struct sctp_initmsg structure. If no SCTP_INIT 487 cmsg structure is used in combination with NULL data, an association 488 is established using the default parameters. If NULL data is used, 489 no association exists and the SCTP_ABORT or SCTP_EOF flags are 490 present then -1 must be returned and an errno should be set to 491 something like EDONOTBESTUPID. Sending a message using sendmsg() is 492 atomic unless explicit EOR marking is enabled on the socket specified 493 by sd. 495 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 496 be delivered if that notification has been enabled, and no more data 497 can be sent to that association. Any attempt to send more data will 498 cause sendmsg() to return with an ESHUTDOWN error. Note that the 499 socket is still open for reading at this point so it is possible to 500 retrieve notifications. 502 When receiving a user message with recvmsg(), the msg_name field in 503 msghdr structure will be populated with the source transport address 504 of the user data. The caller of recvmsg() can use this address 505 information to determine to which association the received user 506 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 507 applications must use the peer transport address provided in the 508 msg_name field by recvmsg() to perform correlation to an association, 509 since they will not have the association ID. 511 If all data in a single message has been delivered, MSG_EOR will be 512 set in the msg_flags field of the msghdr structure (see section 513 Section 5.1). 515 If the application does not provide enough buffer space to completely 516 receive a data message, MSG_EOR will not be set in msg_flags. 517 Successive reads will consume more of the same message until the 518 entire message has been delivered, and MSG_EOR will be set. 520 If the SCTP stack is running low on buffers, it may partially deliver 521 a message. In this case, MSG_EOR will not be set, and more calls to 522 recvmsg() will be necessary to completely consume the message. Only 523 one message at a time can be partially delivered in any stream. The 524 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 525 what interlacing of messages occurs for both the one-to-one and the 526 one-to-many model sockets. Please consult Section 7.1.20 for further 527 details on message delivery options. 529 Note, if the socket is a branched-off socket that only represents one 530 association (see Section 3.1), the msg_name field can be used to 531 override the primary address when sending data. 533 3.1.5. close() 535 Applications use close() to perform graceful shutdown (as described 536 in Section 10.1 of [RFC4960]) on ALL the associations currently 537 represented by a one-to-many style socket. 539 The function prototype is 541 int close(int sd); 543 and the argument is 544 sd: The socket descriptor of the associations to be closed. 546 To gracefully shutdown a specific association represented by the one- 547 to-many style socket, an application should use the sendmsg() call, 548 and include the SCTP_EOF flag. A user may optionally terminate an 549 association non-gracefully by sending with the SCTP_ABORT flag and 550 possibly passing a user specified abort code in the data field. Both 551 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 552 Section 5.2.2) in the sendmsg call. 554 If sd in the close() call is a branched-off socket representing only 555 one association, the shutdown is performed on that association only. 557 3.1.6. connect() 559 An application may use the connect() call in the one-to-many style to 560 initiate an association without sending data. 562 The function prototype is 564 int connect(int sd, 565 const struct sockaddr *nam, 566 socklen_t len); 568 and the arguments are 569 sd: The socket descriptor to have a new association added to. 570 nam: The address structure (either struct sockaddr_in or struct 571 sockaddr_in6 defined in [RFC3493]). 572 len: The size of the address. 574 Multiple connect() calls can be made on the same socket to create 575 multiple associations. This is different from the semantics of 576 connect() on a UDP socket. 578 3.2. Implicit Association Setup 580 Implicit association setup applies only to one-to-many style sockets. 581 For one-to-one style sockets implicit association setup must not be 582 used. 584 Once the bind() call is complete on a one-to-many style socket, the 585 application can begin sending and receiving data using the sendmsg()/ 586 recvmsg() or sendto()/recvfrom() calls, without going through any 587 explicit association setup procedures (i.e., no connect() calls 588 required). 590 Whenever sendmsg() or sendto() is called and the SCTP stack at the 591 sender finds that there is no association existing between the sender 592 and the intended receiver (identified by the address passed either in 593 the msg_name field of msghdr structure in the sendmsg() call or the 594 dest_addr field in the sendto() call), the SCTP stack will 595 automatically setup an association to the intended receiver. 597 Upon the successful association setup a SCTP_COMM_UP notification 598 will be dispatched to the socket at both the sender and receiver 599 side. This notification can be read by the recvmsg() system call 600 (see Section 3.1.3). 602 Note, if the SCTP stack at the sender side supports bundling, the 603 first user message may be bundled with the COOKIE ECHO message 604 [RFC4960]. 606 When the SCTP stack sets up a new association implicitly, it first 607 consults the sctp_initmsg structure, which is passed along within the 608 ancillary data in the sendmsg() call (see Section 5.2.1 for details 609 of the data structures), for any special options to be used on the 610 new association. 612 If this information is not present in the sendmsg() call, or if the 613 implicit association setup is triggered by a sendto() call, the 614 default association initialization parameters will be used. These 615 default association parameters may be set with respective 616 setsockopt() calls or be left to the system defaults. 618 Implicit association setup cannot be initiated by send()/recv() 619 calls. 621 3.3. Non-blocking mode 623 Some SCTP users might want to avoid blocking when they call socket 624 interface function. 626 Once all bind() calls are complete on a one-to-many style socket, the 627 application must set the non-blocking option by a fcntl() (such as 628 O_NONBLOCK). After which the sendmsg() function returns immediately, 629 and the success or failure of the data message (and possible 630 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 631 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 632 be sent (due to a CANT_START_ASSOC), the sender will also receive a 633 SCTP_SEND_FAILED event. Those event(s) can be received by the user 634 calling of recvmsg(). A server (having called listen()) is also 635 notified of an association up event by the reception of a 636 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 637 possibly the reception of the first data message. 639 In order to shutdown the association gracefully, the user must call 640 sendmsg() with no data and with the SCTP_EOF flag set. The function 641 returns immediately, and completion of the graceful shutdown is 642 indicated by an SCTP_ASSOC_CHANGE notification of type 643 SHUTDOWN_COMPLETE (see Section 5.3.2). Note that this can also be 644 done using the sctp_send() call described in Section 8.10. 646 An application is recommended to use caution when using select() (or 647 poll()) for writing on a one-to-many style socket. The reason being 648 that the interpretation of select on write is implementation 649 specific. Generally a positive return on a select on write would 650 only indicate that one of the associations represented by the one-to- 651 many socket is writable. An application that writes after the select 652 return may still block since the association that was writeable is 653 not the destination association of the write call. Likewise select 654 (or poll()) for reading from a one-to-many socket will only return an 655 indication that one of the associations represented by the socket has 656 data to be read. 658 An application that wishes to know that a particular association is 659 ready for reading or writing should either use the one-to-one style 660 or use the sctp_peeloff() (see Section 8.2) function to separate the 661 association of interest from the one-to-many socket. 663 3.4. Special considerations 665 The fact that a one-to-many style socket can provide access to many 666 SCTP associations through a single socket descriptor has important 667 implications for both application programmers and system programmers 668 implementing this API. A key issue is how buffer space inside the 669 sockets layer is managed. Because this implementation detail 670 directly affects how application programmers must write their code to 671 ensure correct operation and portability, this section provides some 672 guidance to both implementers and application programmers. 674 An important feature that SCTP shares with TCP is flow control: 675 specifically, a sender may not send data faster than the receiver can 676 consume it. 678 For TCP, flow control is typically provided for in the sockets API as 679 follows. If the reader stops reading, the sender queues messages in 680 the socket layer until it uses all of its socket buffer space 681 allocation creating a "stalled connection". Further attempts to 682 write to the socket will block or return the error EAGAIN or 683 EWOULDBLOCK for a non-blocking socket. At some point, either the 684 connection is closed, or the receiver begins to read again freeing 685 space in the output queue. 687 For one-to-one style SCTP sockets (this includes sockets descriptors 688 that were separated from a one-to-many style socket with 689 sctp_peeloff()) the behavior is identical. For one-to-many style 690 SCTP sockets, the fact that we have multiple associations on a single 691 socket makes the situation more complicated. If the implementation 692 uses a single buffer space allocation shared by all associations, a 693 single stalled association can prevent the further sending of data on 694 all associations active on a particular one-to-many style socket. 696 For a blocking socket, it should be clear that a single stalled 697 association can block the entire socket. For this reason, 698 application programmers may want to use non-blocking one-to-many 699 style sockets. The application should at least be able to send 700 messages to the non-stalled associations. 702 But a non-blocking socket is not sufficient if the API implementer 703 has chosen a single shared buffer allocation for the socket. A 704 single stalled association would eventually cause the shared 705 allocation to fill, and it would become impossible to send even to 706 non-stalled associations. 708 The API implementer can solve this problem by providing each 709 association with its own allocation of outbound buffer space. Each 710 association should conceptually have as much buffer space as it would 711 have if it had its own socket. As a bonus, this simplifies the 712 implementation of sctp_peeloff(). 714 To ensure that a given stalled association will not prevent other 715 non-stalled associations from being writable, application programmers 716 should either: 717 o demand that the underlying implementation dedicates independent 718 buffer space allotments to each association (as suggested above), 719 or 720 o verify that their application layer protocol does not permit large 721 amounts of unread data at the receiver (this is true of some 722 request-response protocols, for example), or 723 o use one-to-one style sockets for association which may potentially 724 stall (either from the beginning, or by using sctp_peeloff before 725 sending large amounts of data that may cause a stalled condition). 727 4. One-to-One Style Interface 729 The goal of this style is to follow as closely as possible the 730 current practice of using the sockets interface for a connection 731 oriented protocol, such as TCP. This style enables existing 732 applications using connection oriented protocols to be ported to SCTP 733 with very little effort. 735 Note that some new SCTP features and some new SCTP socket options can 736 only be utilized through the use of sendmsg() and recvmsg() calls, 737 see Section 4.1.8. Also note that some socket interfaces may not be 738 able to provide data on the third leg of the association set up with 739 this interface style. 741 4.1. Basic Operation 743 A typical server in one-to-one style uses the following system call 744 sequence to prepare an SCTP endpoint for servicing requests: 745 o socket() 746 o bind() 747 o listen() 748 o accept() 750 The accept() call blocks until a new association is set up. It 751 returns with a new socket descriptor. The server then uses the new 752 socket descriptor to communicate with the client, using recv() and 753 send() calls to get requests and send back responses. 755 Then it calls 756 o close() 757 to terminate the association. 759 A typical client uses the following system call sequence to setup an 760 association with a server to request services: 761 o socket() 762 o connect() 764 After returning from connect(), the client uses send() and recv() 765 calls to send out requests and receive responses from the server. 767 The client calls 768 o close() 769 to terminate this association when done. 771 4.1.1. socket() 773 Applications calls socket() to create a socket descriptor to 774 represent an SCTP endpoint. 776 The function prototype is 778 int socket(int domain, 779 int type, 780 int protocol); 782 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 783 type and IPPROTO_SCTP as the protocol. 785 Here, SOCK_STREAM indicates the creation of a one-to-one style 786 socket. 788 Using the PF_INET domain indicates the creation of an endpoint which 789 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 790 can use both IPv6 and IPv4 address. 792 4.1.2. bind() 794 Applications use bind() to pass an address to be associated with an 795 SCTP endpoint to the system. bind() allows only either a single 796 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 797 endpoint can be associated with multiple addresses. To do this, 798 sctp_bindx() is introduced in Section 8.1 to help applications do the 799 job of associating multiple addresses. 801 These addresses associated with a socket are the eligible transport 802 addresses for the endpoint to send and receive data. The endpoint 803 will also present these addresses to its peers during the association 804 initialization process, see [RFC4960]. 806 The function prototype of bind() is 808 int bind(int sd, 809 struct sockaddr *addr, 810 socklen_t addrlen); 812 and the arguments are 813 sd: The socket descriptor returned by socket(). 814 addr: The address structure (struct sockaddr_in or struct 815 sockaddr_in6, see [RFC3493]). 816 addrlen: The size of the address structure. 818 If sd is an IPv4 socket, the address passed must be an IPv4 address. 819 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 820 either be an IPv4 or an IPv6 address. 822 Applications cannot call bind() multiple times to associate multiple 823 addresses to the endpoint. After the first call to bind(), all 824 subsequent calls will return an error. 826 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 827 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 828 operating system will associate the endpoint with an optimal address 829 set of the available interfaces. 831 If a bind() is not called prior to the connect() call, the system 832 picks an ephemeral port and will choose an address set equivalent to 833 binding with a wildcard address. One of those addresses will be the 834 primary address for the association. This automatically enables the 835 multi-homing capability of SCTP. 837 The completion of this bind() process does not ready the SCTP 838 endpoint to accept inbound SCTP association requests. Until a 839 listen() system call, described below, is performed on the socket, 840 the SCTP endpoint will promptly reject an inbound SCTP INIT request 841 with an SCTP ABORT. 843 4.1.3. listen() 845 Applications use listen() to ready the SCTP endpoint for accepting 846 inbound associations. 848 The function prototype is 850 int listen(int sd, 851 int backlog); 853 and the arguments are 854 sd: the socket descriptor of the SCTP endpoint. 855 backlog: this specifies the max number of outstanding associations 856 allowed in the socket's accept queue. These are the associations 857 that have finished the four-way initiation handshake (see Section 858 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 859 of '0' indicates that the caller no longer wishes to receive new 860 associations. 862 4.1.4. accept() 864 Applications use accept() call to remove an established SCTP 865 association from the accept queue of the endpoint. A new socket 866 descriptor will be returned from accept() to represent the newly 867 formed association. 869 The function prototype is 871 int accept(int sd, 872 struct sockaddr *addr, 873 socklen_t *addrlen); 875 and the arguments are 876 sd: The listening socket descriptor. 877 addr: On return, will contain the primary address of the peer 878 endpoint. 879 addrlen: On return, will contain the size of addr. 880 The functions returns the socket descriptor for the newly formed 881 association. 883 4.1.5. connect() 885 Applications use connect() to initiate an association to a peer. 887 The function prototype is 889 int connect(int sd, 890 const struct sockaddr *addr, 891 socklen_t addrlen); 893 and the arguments are 894 sd: The socket descriptor of the endpoint. 895 addr: The peer's address. 896 addrlen: The size of the address. 898 This operation corresponds to the ASSOCIATE primitive described in 899 section 10.1 of [RFC4960]. 901 By default, the new association created has only one outbound stream. 902 The SCTP_INITMSG option described in Section 7.1.3 should be used 903 before connecting to change the number of outbound streams. 905 If a bind() is not called prior to the connect() call, the system 906 picks an ephemeral port and will choose an address set equivalent to 907 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 908 respectively. One of those addresses will be the primary address for 909 the association. This automatically enables the multi-homing 910 capability of SCTP. 912 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 913 during the association set up phase. If an application wants to do 914 this, it cannot use connect() call. Instead, it should use sendto() 915 or sendmsg() to initiate an association. If it uses sendto() and it 916 wants to change initialization behavior, it needs to use the 917 SCTP_INITMSG socket option before calling sendto(). Or it can use 918 SCTP_INIT type sendmsg() to initiate an association without doing the 919 setsockopt(). Note that some sockets implementations may not support 920 the sending of data to initiate an association with the one-to-one 921 style (implementations that do not support T/TCP normally have this 922 restriction). 924 SCTP does not support half close semantics. This means that unlike 925 T/TCP, MSG_EOF should not be set in the flags parameter when calling 926 sendto() or sendmsg() when the call is used to initiate a connection. 927 MSG_EOF is not an acceptable flag with an SCTP socket. 929 4.1.6. close() 931 Applications use close() to gracefully close down an association. 933 The function prototype is 935 int close(int sd); 937 and the argument is 938 sd: The socket descriptor of the associations to be closed. 940 After an application calls close() on a socket descriptor, no further 941 socket operations will succeed on that descriptor. 943 4.1.7. shutdown() 945 SCTP differs from TCP in that it does not have half closed semantics. 946 Hence the shutdown() call for SCTP is an approximation of the TCP 947 shutdown() call, and solves some different problems. Full TCP- 948 compatibility is not provided, so developers porting TCP applications 949 to SCTP may need to recode sections that use shutdown(). (Note that 950 it is possible to achieve the same results as half close in SCTP 951 using SCTP streams.) 953 The function prototype is 955 int shutdown(int sd, 956 int how); 958 and the arguments are 959 sd: The socket descriptor of the association to be closed. 960 how: Specifies the type of shutdown. The values are as follows: 961 SHUT_RD: Disables further receive operations. No SCTP protocol 962 action is taken. 963 SHUT_WR: Disables further send operations, and initiates the SCTP 964 shutdown sequence. 965 SHUT_RDWR: Disables further send and receive operations and 966 initiates the SCTP shutdown sequence. 968 The major difference between SCTP and TCP shutdown() is that SCTP 969 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 970 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 971 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 972 the SCTP association while still leaving the socket descriptor open, 973 so that the caller can receive back any data SCTP was unable to 974 deliver (see Section 5.3.5 for more information). 976 To perform the ABORT operation described in [RFC4960] section 10.1, 977 an application can use the socket option SO_LINGER. It is described 978 in Section 7.1.4. 980 4.1.8. sendmsg() and recvmsg() 982 With a one-to-one style socket, the application can also use 983 sendmsg() and recvmsg() to transmit data to and receive data from its 984 peer. The semantics is similar to those used in the one-to-many 985 style (section Section 3.1.3), with the following differences: 986 1. When sending, the msg_name field in the msghdr is not used to 987 specify the intended receiver, rather it is used to indicate a 988 preferred peer address if the sender wishes to discourage the 989 stack from sending the message to the primary address of the 990 receiver. If the socket is connected and the transport address 991 given is not part of the current association, the data will not 992 be sent and a SCTP_SEND_FAILED event will be delivered to the 993 application if send failure events are enabled. 994 2. Using sendmsg() on a non-connected one-to-one style socket for 995 implicit connection setup may or may not work depending on the 996 SCTP implementation. 998 4.1.9. getpeername() 1000 Applications use getpeername() to retrieve the primary socket address 1001 of the peer. This call is for TCP compatibility, and is not multi- 1002 homed. It does not work with one-to-many style sockets. See 1003 Section 8.3 for a multi-homed/one-to-many style version of the call. 1005 The function prototype is 1007 int getpeername(int sd, 1008 struct sockaddr *address, 1009 socklen_t *len); 1011 and the arguments are: 1012 sd: The socket descriptor to be queried. 1013 address: On return, the peer primary address is stored in this 1014 buffer. If the socket is an IPv4 socket, the address will be 1015 IPv4. If the socket is an IPv6 socket, the address will be either 1016 an IPv6 or IPv4 address. 1017 len: The caller should set the length of address here. On return, 1018 this is set to the length of the returned address. 1020 If the actual length of the address is greater than the length of the 1021 supplied sockaddr structure, the stored address will be truncated. 1023 5. Data Structures 1025 We discuss in this section important data structures which are 1026 specific to SCTP and are used with sendmsg() and recvmsg() calls to 1027 control SCTP endpoint operations and to access ancillary information 1028 and notifications. 1030 5.1. The msghdr and cmsghdr Structures 1032 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1033 well as the ancillary data carried in the structure, is the key for 1034 the application to set and get various control information from the 1035 SCTP endpoint. 1037 The msghdr and the related cmsghdr structures are defined and 1038 discussed in details in [RFC3542]. Here we will cite their 1039 definitions from [RFC3542]. 1041 The msghdr structure: 1043 struct msghdr { 1044 void *msg_name; /* ptr to socket address structure */ 1045 socklen_t msg_namelen; /* size of socket address structure */ 1046 struct iovec *msg_iov; /* scatter/gather array */ 1047 size_t msg_iovlen; /* # elements in msg_iov */ 1048 void *msg_control; /* ancillary data */ 1049 socklen_t msg_controllen; /* ancillary data buffer length */ 1050 int msg_flags; /* flags on received message */ 1051 }; 1053 and the cmsghdr structure: 1055 struct cmsghdr { 1056 socklen_t cmsg_len; /* #bytes, including this header */ 1057 int cmsg_level; /* originating protocol */ 1058 int cmsg_type; /* protocol-specific type */ 1059 /* followed by unsigned char cmsg_data[]; */ 1060 }; 1062 In the msghdr structure, the usage of msg_name has been discussed in 1063 previous sections (see Section 3.1.3 and Section 4.1.8). 1065 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1066 field) are treated as a single SCTP data chunk, rather than multiple 1067 chunks, for both sendmsg() and recvmsg(). 1069 The msg_flags are not used when sending a message with sendmsg(). 1071 If a notification has arrived, recvmsg() will return the notification 1072 with the MSG_NOTIFICATION flag set in msg_flags. If the 1073 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1074 Section 5.3 for more information about notifications. 1076 If all portions of a data frame or notification have been read, 1077 recvmsg() will return with MSG_EOR set in msg_flags. 1079 5.2. SCTP msg_control Structures 1081 A key element of all SCTP-specific socket extensions is the use of 1082 ancillary data to specify and access SCTP-specific data via the 1083 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1084 Fine-grained control over initialization and sending parameters are 1085 handled with ancillary data. 1087 Each ancillary data item is proceeded by a struct cmsghdr (see 1088 Section 5.1), which defines the function and purpose of the data 1089 contained in in the cmsg_data[] member. 1091 There are two kinds of ancillary data used by SCTP: initialization 1092 data, and, header information (SNDRCV). Initialization data sets 1093 protocol parameters for new associations. Section 5.2.1 provides 1094 more details. Header information can set or report parameters on 1095 individual messages in a stream. See Section 5.2.2 for how to use 1096 SNDRCV ancillary data. 1098 By default on either style socket, SCTP will pass no ancillary data; 1099 Specific ancillary data items can be enabled with socket options 1100 defined for SCTP; see Section 7.4. 1102 Note that all ancillary types are fixed length; see Section 5.4 for 1103 further discussion on this. These data structures use struct 1104 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1105 address format. 1107 Other protocols may also provide ancillary data to the socket layer 1108 consumer. These ancillary data items from other protocols may 1109 intermingle with SCTP data. For example, the IPv6 socket API 1110 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1111 data items. If a socket API consumer enables delivery of both SCTP 1112 and IPv6 ancillary data, they both may appear in the same msg_control 1113 buffer in any order. An application may thus need to handle other 1114 types of ancillary data besides that passed by SCTP. 1116 The sockets application must provide a buffer large enough to 1117 accommodate all ancillary data provided via recvmsg(). If the buffer 1118 is not large enough, the ancillary data will be truncated and the 1119 msghdr's msg_flags will include MSG_CTRUNC. 1121 5.2.1. SCTP Initiation Structure (SCTP_INIT) 1123 This cmsghdr structure provides information for initializing new SCTP 1124 associations with sendmsg(). The SCTP_INITMSG socket option uses 1125 this same data structure. This structure is not used for recvmsg(). 1127 +--------------+-----------+---------------------+ 1128 | cmsg_level | cmsg_type | cmsg_data[] | 1129 +--------------+-----------+---------------------+ 1130 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1131 +--------------+-----------+---------------------+ 1133 Here is the definition of the sctp_initmsg structure: 1135 struct sctp_initmsg { 1136 uint16_t sinit_num_ostreams; 1137 uint16_t sinit_max_instreams; 1138 uint16_t sinit_max_attempts; 1139 uint16_t sinit_max_init_timeo; 1140 }; 1142 sinit_num_ostreams: This is an integer number representing the 1143 number of streams that the application wishes to be able to send 1144 to. This number is confirmed in the SCTP_COMM_UP notification and 1145 must be verified since it is a negotiated number with the remote 1146 endpoint. The default value of 0 indicates to use the endpoint 1147 default value. 1148 sinit_max_instreams: This value represents the maximum number of 1149 inbound streams the application is prepared to support. This 1150 value is bounded by the actual implementation. In other words the 1151 user MAY be able to support more streams than the Operating 1152 System. In such a case, the Operating System limit overrides the 1153 value requested by the user. The default value of 0 indicates to 1154 use the endpoints default value. 1155 sinit_max_attempts: This integer specifies how many attempts the 1156 SCTP endpoint should make at resending the INIT. This value 1157 overrides the system SCTP 'Max.Init.Retransmits' value. The 1158 default value of 0 indicates to use the endpoints default value. 1159 This is normally set to the system's default 'Max.Init.Retransmit' 1160 value. 1161 sinit_max_init_timeo: This value represents the largest Time-Out or 1162 RTO value (in milliseconds) to use in attempting an INIT. 1163 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1164 upon timeout. For the INIT message this value MAY override 1165 'RTO.Max'. This value must not influence 'RTO.Max' during data 1166 transmission and is only used to bound the initial setup time. A 1167 default value of 0 indicates to use the endpoints default value. 1168 This is normally set to the system's 'RTO.Max' value (60 seconds). 1170 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1172 This cmsghdr structure specifies SCTP options for sendmsg() and 1173 describes SCTP header information about a received message through 1174 recvmsg(). 1176 +--------------+-------------+------------------------+ 1177 | cmsg_level | cmsg_type | cmsg_data[] | 1178 +--------------+-------------+------------------------+ 1179 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1180 +--------------+-------------+------------------------+ 1182 Here is the definition of sctp_sndrcvinfo: 1184 struct sctp_sndrcvinfo { 1185 uint16_t sinfo_stream; 1186 uint16_t sinfo_ssn; 1187 uint16_t sinfo_flags; 1188 uint32_t sinfo_ppid; 1189 uint32_t sinfo_context; 1190 uint32_t sinfo_pr_value; 1191 uint32_t sinfo_tsn; 1192 uint32_t sinfo_cumtsn; 1193 sctp_assoc_t sinfo_assoc_id; 1194 }; 1196 sinfo_stream: For recvmsg() the SCTP stack places the message's 1197 stream number in this value. For sendmsg() this value holds the 1198 stream number that the application wishes to send this message to. 1199 If a sender specifies an invalid stream number an error indication 1200 is returned and the call fails. 1201 sinfo_ssn: For recvmsg() this value contains the stream sequence 1202 number that the remote endpoint placed in the DATA chunk. For 1203 fragmented messages this is the same number for all deliveries of 1204 the message (if more than one recvmsg() is needed to read the 1205 message). The sendmsg() call will ignore this parameter. 1206 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1207 passed to the remote end in each user message. In recvmsg() this 1208 value is the same information that was passed by the upper layer 1209 in the peer application. Please note that the SCTP stack performs 1210 no byte order modification of this field. For example, if the 1211 DATA chunk has to contain a given value in network byte order, the 1212 SCTP user has to perform the htonl() computation. 1214 sinfo_context: This value is an opaque 32 bit context datum that is 1215 used in the sendmsg() function. This value is passed back to the 1216 upper layer if a error occurs on the send of a message and is 1217 retrieved with each undelivered message (Note: if a endpoint has 1218 done multiple sends, all of which fail, multiple different 1219 sinfo_context values will be returned. One with each user data 1220 message). 1221 sinfo_flags: This field may contain any of the following flags and 1222 is composed of a bitwise OR of these values. 1223 recvmsg() flags: 1224 SCTP_UNORDERED: This flag is present when the message was sent 1225 non-ordered. 1226 sendmsg() flags: 1227 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1228 message. If this flag is clear the datagram is considered an 1229 ordered send. 1230 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1231 SCTP stack to override the primary destination address with the 1232 address found with the sendto/sendmsg call. 1233 SCTP_ABORT: Setting this flag causes the specified association to 1234 abort by sending an ABORT message to the peer (one-to-many 1235 style only). The ABORT chunk will contain an error cause 'User 1236 Initiated Abort' with cause code 12. The cause specific 1237 information of this error cause is provided in msg_iov. 1238 SCTP_EOF Setting this flag invokes the SCTP graceful shutdown 1239 procedures on the specified association. Graceful shutdown 1240 assures that all data queued by both endpoints is successfully 1241 transmitted before closing the association (one-to-many style 1242 only). 1243 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1244 socket to send the message to all associations that are 1245 currently established on this socket. For the one-to-one 1246 socket, this flag has no effect. 1247 sinfo_pr_value: The meaning of this field depends of the PR-SCTP 1248 policy specified by the sinfo_pr_policy field. It is ignored when 1249 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1250 lifetime is specified. 1251 sinfo_tsn: For the receiving side, this field holds a TSN that was 1252 assigned to one of the SCTP Data Chunks. 1253 sinfo_cumtsn: This field will hold the current cumulative TSN as 1254 known by the underlying SCTP layer. Note this field is ignored 1255 when sending. 1256 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1257 the identifier for the association announced in the SCTP_COMM_UP 1258 notification. All notifications for a given association have the 1259 same identifier. Ignored for one-to-one style sockets. 1261 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1263 5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1265 This cmsghdr structure specifies SCTP options for SCTP header 1266 information about a received message via recvmsg(). Note that this 1267 structure is an extended version of SCTP_SNDRCV (see Section 5.2.2) 1268 and will only be received if the user has set the socket option 1269 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1270 needed to receive ancillary data. Note that next message data is not 1271 valid unless the current message is completely read, i.e. the MSG_EOR 1272 is set, in other words if you have more data to read from the current 1273 message then no next message information will be available. 1275 +--------------+-------------+------------------------+ 1276 | cmsg_level | cmsg_type | cmsg_data[] | 1277 +--------------+-------------+------------------------+ 1278 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1279 +--------------+-------------+------------------------+ 1281 Here is the definition of sctp_extrcvinfo structure: 1283 struct sctp_extrcvinfo { 1284 uint16_t sinfo_stream; 1285 uint16_t sinfo_ssn; 1286 uint16_t sinfo_flags; 1287 uint16_t sinfo_pr_policy; 1288 uint32_t sinfo_ppid; 1289 uint32_t sinfo_context; 1290 uint32_t sinfo_pr_value; 1291 uint32_t sinfo_tsn; 1292 uint32_t sinfo_cumtsn; 1293 uint16_t serinfo_next_flags; 1294 uint16_t serinfo_next_stream; 1295 uint32_t serinfo_next_aid; 1296 uint32_t serinfo_next_length; 1297 uint32_t serinfo_next_ppid; 1298 sctp_assoc_t sinfo_assoc_id; 1299 }; 1301 sinfo_xxxxfieldsxxx: Please see Section 5.2.2 for the details for 1302 these fields. 1303 serinfo_next_flags: This bitmask will hold one or more of the 1304 following values: 1305 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1306 message information is available i.e.: next_stream, 1307 next_asocid, next_length and next_ppid fields all have valid 1308 values. If this bit is set to 0, then these fields are not 1309 valid and should be ignored. 1311 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1312 next message is completely in the receive buffer. The 1313 next_length field thus contains the entire message size. If 1314 this flag is set to 0, then the next_length field only contains 1315 part of the message size since the message is still being 1316 received (it is being partially delivered). 1317 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1318 the next message to be received was sent by the peer as 1319 unordered. If this bit is not set (i.e the bit is 0) the next 1320 message to be read is an ordered message in the stream 1321 specified. 1322 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1323 the next message to be received is not a message from the peer, 1324 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1325 serinfo_next_stream This value, when valid (see sreinfo_next_flags), 1326 contains the next stream number that will be received on a 1327 subsequent call to one of the receive message functions. 1328 serinfo_next_aid: This value, when valid (see next_flags), contains 1329 the next association identification that will be received on a 1330 subsequent call to one of the receive message functions. 1331 sreinfo_next_length: This value, when valid (see 1332 sreinfo_next_flags), contains the length of the next message that 1333 will be received on a subsequent call to one of the receive 1334 message functions. Note that this length may be a partial length 1335 depending on the settings of next_flags. 1336 sreinfo_next_ppid: This value, when valid (see sreinfo_next_flags), 1337 contains the ppid of the next message that will be received on a 1338 subsequent call to one of the receive message functions. 1340 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) 1342 This cmsghdr structure specifies SCTP options for sendmsg(). 1344 +--------------+--------------+---------------------+ 1345 | cmsg_level | cmsg_type | cmsg_data[] | 1346 +--------------+--------------+---------------------+ 1347 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1348 +--------------+--------------+---------------------+ 1350 Here is the definition of the sctp_sndinfo structure: 1352 struct sctp_sndinfo { 1353 uint16_t snd_sid; 1354 uint16_t snd_flags; 1355 uint32_t snd_ppid; 1356 uint32_t snd_context; 1357 sctp_assoc_t snd_assoc_id; 1358 }; 1359 snd_sid: This value holds the stream number that the application 1360 wishes to send this message to. If a sender specifies an invalid 1361 stream number an error indication is returned and the call fails. 1362 snd_flags: This field may contain any of the following flags and is 1363 composed of a bitwise OR of these values. 1365 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1366 message. If this flag is clear the datagram is considered an 1367 ordered send. 1368 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1369 SCTP stack to override the primary destination address with the 1370 address found with the sendto/sendmsg call. 1371 SCTP_ABORT: Setting this flag causes the specified association to 1372 abort by sending an ABORT message to the peer (one-to-many 1373 style only). The ABORT chunk will contain an error cause 'User 1374 Initiated Abort' with cause code 12. The cause specific 1375 information of this error cause is provided in msg_iov. 1376 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1377 procedures on the specified association. Graceful shutdown 1378 assures that all data queued by both endpoints is successfully 1379 transmitted before closing the association (one-to-many style 1380 only). 1381 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1382 socket to send the message to all associations that are 1383 currently established on this socket. For the one-to-one 1384 socket, this flag has no effect. 1385 snd_ppid: This value in sendmsg() is an unsigned integer that is 1386 passed to the remote end in each user message. Please note that 1387 the SCTP stack performs no byte order modification of this field. 1388 For example, if the DATA chunk has to contain a given value in 1389 network byte order, the SCTP user has to perform the htonl() 1390 computation. 1391 snd_context: This value is an opaque 32 bit context datum that is 1392 used in the sendmsg() function. This value is passed back to the 1393 upper layer if a error occurs on the send of a message and is 1394 retrieved with each undelivered message (Note: if a endpoint has 1395 done multiple sends, all of which fail, multiple different 1396 sinfo_context values will be returned. One with each user data 1397 message). 1398 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1399 the identifier for the association announced in the SCTP_COMM_UP 1400 notification. All notifications for a given association have the 1401 same identifier. Ignored for one-to-one style sockets. 1403 A sctp_sndvinfo item always corresponds to the data in msg_iov. 1405 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1407 This cmsghdr structure describes SCTP header information about a 1408 received message through recvmsg(). 1410 +--------------+--------------+---------------------+ 1411 | cmsg_level | cmsg_type | cmsg_data[] | 1412 +--------------+--------------+---------------------+ 1413 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1414 +--------------+--------------+---------------------+ 1416 Here is the definition of sctp_rcvinfo structure: 1418 struct sctp_rcvinfo { 1419 uint16_t rcv_sid; 1420 uint16_t rcv_ssn; 1421 uint16_t rcv_flags; 1422 uint32_t rcv_ppid; 1423 uint32_t rcv_tsn; 1424 uint32_t rcv_cumtsn; 1425 sctp_assoc_t rcv_assoc_id; 1426 }; 1428 rcv_sid: The SCTP stack places the message's stream number in this 1429 value. 1430 rcv_ssn: This value contains the stream sequence number that the 1431 remote endpoint placed in the DATA chunk. For fragmented messages 1432 this is the same number for all deliveries of the message (if more 1433 than one recvmsg() is needed to read the message). 1434 rcv_flags: This field may contain any of the following flags and is 1435 composed of a bitwise OR of these values. 1437 SCTP_UNORDERED: This flag is present when the message was sent 1438 non-ordered. 1439 rcv_ppid: This value is the same information that was passed by the 1440 upper layer in the peer application. Please note that the SCTP 1441 stack performs no byte order modification of this field. For 1442 example, if the DATA chunk has to contain a given value in network 1443 byte order, the SCTP user has to perform the htonl() computation. 1444 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1445 Data Chunks. 1446 rcv_cumtsn: This field will hold the current cumulative TSN as known 1447 by the underlying SCTP layer. 1448 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1449 the identifier for the association announced in the SCTP_COMM_UP 1450 notification. All notifications for a given association have the 1451 same identifier. Ignored for one-to-one style sockets. 1453 A sctp_rcvinfo item always corresponds to the data in msg_iov. 1455 5.2.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1457 This cmsghdr structure describes SCTP receive information of the next 1458 message which will be delivered through recvmsg() if this information 1459 is available. It uses the same structure as the SCTP Receive 1460 Information Structure. 1462 +--------------+--------------+---------------------+ 1463 | cmsg_level | cmsg_type | cmsg_data[] | 1464 +--------------+--------------+---------------------+ 1465 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_rcvinfo | 1466 +--------------+--------------+---------------------+ 1468 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1470 This cmsghdr structure specifies SCTP options for sendmsg(). 1472 +--------------+-------------+--------------------+ 1473 | cmsg_level | cmsg_type | cmsg_data[] | 1474 +--------------+-------------+--------------------+ 1475 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1476 +--------------+-------------+--------------------+ 1478 Here is the definition of the sctp_prinfo structure: 1480 struct sctp_prinfo { 1481 uint16_t pr_policy; 1482 uint32_t pr_value; 1483 }; 1485 pr_policy: This specifies which PR-SCTP policy is used. Using 1486 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1487 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1488 defined in [RFC3758] is used. In this case, the lifetime is 1489 provided in pr_value. 1490 pr_value: The meaning of this field depends of the PR-SCTP policy 1491 specified by the sinfo_pr_policy field. It is ignored when 1492 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1493 lifetime in milli seconds is specified. 1495 A sctp_prinfo item always corresponds to the data in msg_iov. 1497 5.2.8. SCTP PR-SCTP Information Structure (SCTP_AUTHINFO) 1499 This cmsghdr structure specifies SCTP options for sendmsg(). 1501 +--------------+---------------+----------------------+ 1502 | cmsg_level | cmsg_type | cmsg_data[] | 1503 +--------------+---------------+----------------------+ 1504 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1505 +--------------+---------------+----------------------+ 1507 Here is the definition of the sctp_authinfo structure: 1509 struct sctp_authinfo { 1510 uint16_t auth_keyid; 1511 }; 1513 auth_keyid: This specifies the shared key identifier used for 1514 sending the user message. 1516 A sctp_authinfo item always corresponds to the data in msg_iov. 1518 5.3. SCTP Events and Notifications 1520 An SCTP application may need to understand and process events and 1521 errors that happen on the SCTP stack. These events include network 1522 status changes, association startups, remote operational errors and 1523 undeliverable messages. All of these can be essential for the 1524 application. 1526 When an SCTP application layer does a recvmsg() the message read is 1527 normally a data message from a peer endpoint. If the application 1528 wishes to have the SCTP stack deliver notifications of non-data 1529 events, it sets the appropriate socket option for the notifications 1530 it wants. See Section 7.4 for these socket options. When a 1531 notification arrives, recvmsg() returns the notification in the 1532 application-supplied data buffer via msg_iov, and sets 1533 MSG_NOTIFICATION in msg_flags. 1535 This section details the notification structures. Every notification 1536 structure carries some common fields which provides general 1537 information. 1539 A recvmsg() call will return only one notification at a time. Just 1540 as when reading normal data, it may return part of a notification if 1541 the msg_iov buffer is not large enough. If a single read is not 1542 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1543 reading the notification before subsequent data can arrive. 1545 5.3.1. SCTP Notification Structure 1547 The notification structure is defined as the union of all 1548 notification types. 1550 union sctp_notification { 1551 struct sctp_tlv { 1552 uint16_t sn_type; /* Notification type. */ 1553 uint16_t sn_flags; 1554 uint32_t sn_length; 1555 } sn_header; 1556 struct sctp_assoc_change sn_assoc_change; 1557 struct sctp_paddr_change sn_paddr_change; 1558 struct sctp_remote_error sn_remote_error; 1559 struct sctp_send_failed sn_send_failed; 1560 struct sctp_shutdown_event sn_shutdown_event; 1561 struct sctp_adaptation_event sn_adaptation_event; 1562 struct sctp_pdapi_event sn_pdapi_event; 1563 struct sctp_authkey_event sn_auth_event; 1564 struct sctp_sender_dry_event sn_sender_dry_event; 1565 }; 1567 sn_type: The following list describes the SCTP notification and 1568 event types for the field sn_type. 1569 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1570 either been opened or closed. Refer to Section 5.3.2 for 1571 details. 1572 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1573 part of an existing association has experienced a change of 1574 state (e.g. a failure or return to service of the reachability 1575 of a endpoint via a specific transport address). Please see 1576 Section 5.3.3 for data structure details. 1577 SCTP_REMOTE_ERROR: The attached error message is an Operational 1578 Error received from the remote peer. It includes the complete 1579 TLV sent by the remote endpoint. See Section 5.3.4 for the 1580 detailed format. 1581 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1582 remote endpoint. This structure includes the original 1583 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1584 structure uses the sctp_sndrecvinfo per Section 5.3.5. 1585 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1586 data should be sent on this socket. 1587 SCTP_ADAPTATION_INDICATION: This notification holds the peers 1588 indicated adaptation layer. Please see Section 5.3.7. 1589 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1590 receiver that the partial delivery has been aborted. This may 1591 indicate the association is about to be aborted. Please see 1592 Section 5.3.8 1593 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1594 receiver that either an error occurred on authentication, or a 1595 new key was made active. Section 5.3.9 1597 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1598 application that the sender has no user data queued anymore, 1599 neither for transmission or retransmission. Section 5.3.10 1600 sn_flags: These are notification-specific flags. 1601 sn_length: This is the length of the whole sctp_notification 1602 structure including the sn_type, sn_flags, and sn_length fields. 1604 5.3.2. SCTP_ASSOC_CHANGE 1606 Communication notifications inform the ULP that an SCTP association 1607 has either begun or ended. The identifier for a new association is 1608 provided by this notification. The notification information has the 1609 following format: 1611 struct sctp_assoc_change { 1612 uint16_t sac_type; 1613 uint16_t sac_flags; 1614 uint32_t sac_length; 1615 uint16_t sac_state; 1616 uint16_t sac_error; 1617 uint16_t sac_outbound_streams; 1618 uint16_t sac_inbound_streams; 1619 sctp_assoc_t sac_assoc_id; 1620 uint8_t sac_info[]; 1621 }; 1623 sac_type: It should be SCTP_ASSOC_CHANGE. 1624 sac_flags: Currently unused. 1625 sac_length: This field is the total length of the notification data, 1626 including the notification header. 1627 sac_state: This field holds one of a number of values that 1628 communicate the event that happened to the association. They 1629 include: 1630 SCTP_COMM_UP: A new association is now ready and data may be 1631 exchanged with this peer. When an association has been 1632 established successfully, this notification should be the first 1633 one. 1634 SCTP_COMM_LOST: The association has failed. The association is 1635 now in the closed state. If SEND FAILED notifications are 1636 turned on, a SCTP_COMM_LOST is accompanied by a series of 1637 SCTP_SEND_FAILED events, one for each outstanding message. 1638 SCTP_RESTART: SCTP has detected that the peer has restarted. 1639 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1640 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1641 blocking mode is set and data was sent (in the udp mode), a 1642 SCTP_CANT_STR_ASSOC is accompanied by a series of 1643 SCTP_SEND_FAILED events, one for each outstanding message. 1645 sac_error: If the state was reached due to a error condition (e.g. 1646 SCTP_COMM_LOST) any relevant error information is available in 1647 this field. This corresponds to the protocol error codes defined 1648 in [RFC4960]. 1649 sac_outbound_streams: 1650 sac_inbound_streams: The maximum number of streams allowed in each 1651 direction are available in sac_outbound_streams and sac_inbound 1652 streams. 1653 sac_assoc_id: The association id field, holds the identifier for the 1654 association. All notifications for a given association have the 1655 same association identifier. For one-to-one style socket, this 1656 field is ignored. 1657 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1658 received for this association, sac_info[] contains the complete 1659 ABORT chunk as defined in the SCTP specification [RFC4960] section 1660 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1661 may contain an array of features that the current association 1662 supports. Features may include 1663 SCTP_PR: The both endpoints support the protocol extension 1664 described in [RFC3758]. 1665 SCTP_AUTH: The both endpoints support the protocol extension 1666 described in [RFC4895]. 1667 SCTP_ASCONF: The both endpoints support the protocol extension 1668 described in [RFC5061]. 1669 SCTP_MULTIBUF: For an one-to-many style socket, the local 1670 endpoints uses separate send and/or receive buffers for each 1671 SCTP association. 1673 5.3.3. SCTP_PEER_ADDR_CHANGE 1675 When a destination address on a multi-homed peer encounters a change 1676 an interface details event is sent. The information has the 1677 following structure: 1679 struct sctp_paddr_change { 1680 uint16_t spc_type; 1681 uint16_t spc_flags; 1682 uint32_t spc_length; 1683 struct sockaddr_storage spc_aaddr; 1684 uint32_t spc_state; 1685 uint32_t spc_error; 1686 sctp_assoc_t spc_assoc_id; 1687 } 1688 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 1689 spc_flags: Currently unused. 1690 spc_length: This field is the total length of the notification data, 1691 including the notification header. 1692 spc_aaddr: The affected address field, holds the remote peer's 1693 address that is encountering the change of state. 1694 spc_state: This field holds one of a number of values that 1695 communicate the event that happened to the address. They include: 1696 SCTP_ADDR_AVAILABLE: This address is now reachable. 1697 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 1698 reached. Any data sent to this address is rerouted to an 1699 alternate until this address becomes reachable. 1700 SCTP_ADDR_REMOVED: The address is no longer part of the 1701 association. 1702 SCTP_ADDR_ADDED: The address is now part of the association. 1703 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 1704 primary destination address. 1705 SCTP_ADDR_CONFIRMED: This address has now been confirmed as a 1706 valid address. 1707 spc_error: If the state was reached due to any error condition (e.g. 1708 SCTP_ADDR_UNREACHABLE) any relevant error information is available 1709 in this field. 1710 spc_assoc_id: The association id field, holds the identifier for the 1711 association. All notifications for a given association have the 1712 same association identifier. For one-to-one style socket, this 1713 field is ignored. 1715 5.3.4. SCTP_REMOTE_ERROR 1717 A remote peer may send an Operational Error message to its peer. 1718 This message indicates a variety of error conditions on an 1719 association. The entire ERROR chunk as it appears on the wire is 1720 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1721 specification [RFC4960] and any extensions for a list of possible 1722 error formats. SCTP error notifications have the format: 1724 struct sctp_remote_error { 1725 uint16_t sre_type; 1726 uint16_t sre_flags; 1727 uint32_t sre_length; 1728 uint16_t sre_error; 1729 sctp_assoc_t sre_assoc_id; 1730 uint8_t sre_data[]; 1731 }; 1732 sre_type: It should be SCTP_REMOTE_ERROR. 1733 sre_flags: Currently unused. 1734 sre_length: This field is the total length of the notification data, 1735 including the notification header and the contents of sre_data. 1736 sre_error: This value represents one of the Operational Error causes 1737 defined in the SCTP specification, in network byte order. 1738 sre_assoc_id: The association id field, holds the identifier for the 1739 association. All notifications for a given association have the 1740 same association identifier. For one-to-one style socket, this 1741 field is ignored. 1742 sre_data: This contains the ERROR chunk as defined in the SCTP 1743 specification [RFC4960] section 3.3.10. 1745 5.3.5. SCTP_SEND_FAILED 1747 If SCTP cannot deliver a message it may return the message as a 1748 notification. 1750 struct sctp_send_failed { 1751 uint16_t ssf_type; 1752 uint16_t ssf_flags; 1753 uint32_t ssf_length; 1754 uint32_t ssf_error; 1755 struct sctp_sndrcvinfo ssf_info; 1756 sctp_assoc_t ssf_assoc_id; 1757 uint8_t ssf_data[]; 1758 }; 1760 ssf_type: It should be SCTP_SEND_FAILED. 1761 ssf_flags: The flag value will take one of the following values: 1762 SCTP_DATA_UNSENT: Indicates that the data was never put on the 1763 wire. 1764 SCTP_DATA_SENT: Indicates that the data was put on the wire. 1765 Note that this does not necessarily mean that the data was (or 1766 was not) successfully delivered. 1767 ssf_length: This field is the total length of the notification data, 1768 including the notification header and the payload in ssf_data. 1769 ssf_error: This value represents the reason why the send failed, and 1770 if set, will be a SCTP protocol error code as defined in [RFC4960] 1771 section 3.3.10. 1772 ssf_info: The send information associated with the undelivered 1773 message. The sinfo_flags field will also contain an indication if 1774 the beginning of the message and/or end of the message is present. 1775 In cases where no data has been sent on the wire, this field will 1776 have or'ed in the value SCTP_DATA_NOT_FRAG, which is a composition 1777 of both a "BEGIN" and "END" fragmentation bit. In cases where 1778 part of the data has been sent this field will hold an indication 1779 that just the part not sent is present SCTP_DATA_LAST_FRAG which 1780 corresponds to the "END" bit. Note that the message itself may be 1781 more than one chunk. If the sinfo_flags field holds neither of 1782 these two values then a piece that has been fragmented and sent 1783 but not acknowledged is present. This piece is from an 1784 unspecified position in the message and the application can make 1785 no assumptions about the data itself. Applications wanting to 1786 examine a recovered message should look for the 1787 SCTP_DATA_NOT_FRAG. Without this flag the application should 1788 assume part of the message arrived and take appropriate steps to 1789 audit and recover any lost or missing data. Note also that the 1790 partial reliablity information that was sent down to the SCTP 1791 stack is NOT present in the sinfo_flags field since it occupies 1792 the same bit positions as the SCTP_DATA_NOT_FRAG and the 1793 SCTP_DATA_LAST_FRAG bits. 1794 ssf_assoc_id: The association id field, sf_assoc_id, holds the 1795 identifier for the association. All notifications for a given 1796 association have the same association identifier. For one-to-one 1797 style socket, this field is ignored. 1798 ssf_data: The undelivered message or part of the undelivered message 1799 will be present in the sf_data field. Note that the sinfo_flags 1800 field as noted above should be used to determine if a complete 1801 message is present or just a piece of the message. Note that only 1802 user data is present in this field, any chunk headers or SCTP 1803 common headers must be removed by the SCTP stack. 1805 5.3.6. SCTP_SHUTDOWN_EVENT 1807 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1808 inform the application that it should cease sending data. 1810 struct sctp_shutdown_event { 1811 uint16_t sse_type; 1812 uint16_t sse_flags; 1813 uint32_t sse_length; 1814 sctp_assoc_t sse_assoc_id; 1815 }; 1817 sse_type It should be SCTP_SHUTDOWN_EVENT. 1818 sse_flags: Currently unused. 1819 sse_length: This field is the total length of the notification data, 1820 including the notification header. It will generally be sizeof 1821 (struct sctp_shutdown_event). 1822 sse_flags: Currently unused. 1823 sse_assoc_id: The association id field, holds the identifier for the 1824 association. All notifications for a given association have the 1825 same association identifier. For one-to-one style socket, this 1826 field is ignored. 1828 5.3.7. SCTP_ADAPTATION_INDICATION 1830 When a peer sends a Adaptation Layer Indication parameter , SCTP 1831 delivers this notification to inform the application that of the 1832 peers requested adaptation layer. 1834 struct sctp_adaptation_event { 1835 uint16_t sai_type; 1836 uint16_t sai_flags; 1837 uint32_t sai_length; 1838 uint32_t sai_adaptation_ind; 1839 sctp_assoc_t sai_assoc_id; 1840 }; 1842 sai_type: It should be SCTP_ADAPTATION_INDICATION. 1843 sai_flags: Currently unused. 1844 sai_length: This field is the total length of the notification data, 1845 including the notification header. It will generally be sizeof 1846 (struct sctp_adaptation_event). 1847 sai_adaptation_ind: This field holds the bit array sent by the peer 1848 in the adaptation layer indication parameter. The bits are in 1849 network byte order. 1850 sai_assoc_id: The association id field, holds the identifier for the 1851 association. All notifications for a given association have the 1852 same association identifier. For one-to-one style socket, this 1853 field is ignored. 1855 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT 1857 When a receiver is engaged in a partial delivery of a message this 1858 notification will be used to indicate various events. 1860 struct sctp_pdapi_event { 1861 uint16_t pdapi_type; 1862 uint16_t pdapi_flags; 1863 uint32_t pdapi_length; 1864 uint32_t pdapi_indication; 1865 uint32_t pdapi_stream; 1866 uint32_t pdapi_seq; 1867 sctp_assoc_t pdapi_assoc_id; 1868 }; 1870 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 1871 pdapi_flags: Currently unused. 1873 pdapi_length: This field is the total length of the notification 1874 data, including the notification header. It will generally be 1875 sizeof(struct sctp_pdapi_event). 1876 pdapi_indication: This field holds the indication being sent to the 1877 application possible values include: 1878 SCTP_PARTIAL_DELIVERY_ABORTED: This notification indicates that 1879 the partial delivery of a user message has been aborted. 1880 pdapi_stream: This field holds the stream on which the partial 1881 delivery event happened. 1882 pdapi_seq: This field holds the stream sequence number which was 1883 being partially delivered. 1884 pdapi_assoc_id: The association id field, holds the identifier for 1885 the association. All notifications for a given association have 1886 the same association identifier. For one-to-one style socket, 1887 this field is ignored. 1889 5.3.9. SCTP_AUTHENTICATION_EVENT 1891 When a receiver is using authentication this message will provide 1892 notifications regarding new keys being made active as well as errors. 1894 struct sctp_authkey_event { 1895 uint16_t auth_type; 1896 uint16_t auth_flags; 1897 uint32_t auth_length; 1898 uint16_t auth_keynumber; 1899 uint16_t auth_altkeynumber; 1900 uint32_t auth_indication; 1901 sctp_assoc_t auth_assoc_id; 1902 }; 1904 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 1905 auth_flags: Currently unused. 1906 auth_length: This field is the total length of the notification 1907 data, including the notification header. It will generally be 1908 sizeof (struct sctp_authkey_event). 1909 auth_keynumber: This field holds the keynumber set by the user for 1910 the effected key. If more than one key is involved, this will 1911 contain one of the keys involved in the notification. 1912 auth_altkeynumber: This field holds an alternate keynumber which is 1913 used by some notifications. 1914 auth_indication: This field hold the error or indication being 1915 reported. The following values are currently defined: 1916 SCTP_AUTH_NEWKEY: This report indicates that a new key has been 1917 made active (used for the first time by the peer) and is now 1918 the active key. The auth_keynumber field holds the user 1919 specified key number. 1921 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 1922 support the SCTP-AUTH. 1923 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 1924 implementation will not use the key identifier specified in 1925 auth_keynumber anymore. 1926 auth_assoc_id: The association id field, holds the identifier for 1927 the association. All notifications for a given association have 1928 the same association identifier. 1930 5.3.10. SCTP_SENDER_DRY_EVENT 1932 When the SCTP implementation has no user data anymore to send or 1933 retransmit this notification is given to the user. If the user 1934 subscribes to this event and the SCTP has at this point of time no 1935 user data to send or retransmit this notification is also given to 1936 the user. 1938 struct sctp_sender_dry_event { 1939 uint16_t sender_dry_type; 1940 uint16_t sender_dry_flags; 1941 uint32_t sender_dry_length; 1942 sctp_assoc_t sender_dry_assoc_id; 1943 }; 1945 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 1946 sender_dry_flags: Currently unused. 1947 sender_dry_length: This field is the total length of the 1948 notification data, including the notification header. It will 1949 generally be sizeof (struct sctp_sender_dry_event). 1951 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT 1953 Notifications, when subscribed to, are reliable. They are always 1954 delivered as long as there is space in the socket receive buffer. 1955 However if an implementation experiences a notification storm, it may 1956 run out of socket buffer space. When this occurs it may wish to 1957 disable notifications. If the implementation chooses to do this, it 1958 will append a final notification SCTP_NOTIFICATIONS_STOPPED_EVENT. 1959 This notification is an empty sctp_tlv (see the union above), that 1960 mearly has this type in the sn_type field, the sn_length field set to 1961 the sizeof a sctp_tlv structure and the sn_flags set to 0. If an 1962 application receives this notification, it will need to resubscribe 1963 to any notifications of interest to it. 1965 5.4. Ancillary Data Considerations and Semantics 1967 Programming with ancillary socket data contains some subtleties and 1968 pitfalls, which are discussed below. 1970 5.4.1. Multiple Items and Ordering 1972 Multiple ancillary data items may be included in any call to 1973 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1974 items, or both. 1976 The ordering of ancillary data items (either by SCTP or another 1977 protocol) is not significant and is implementation-dependent, so 1978 applications must not depend on any ordering. 1980 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1981 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1982 sendmsg() or recvmsg() call. 1984 5.4.2. Accessing and Manipulating Ancillary Data 1986 Applications can infer the presence of data or ancillary data by 1987 examining the msg_iovlen and msg_controllen msghdr members, 1988 respectively. 1990 Implementations may have different padding requirements for ancillary 1991 data, so portable applications should make use of the macros 1992 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1993 [RFC3542] and your SCTP implementation's documentation for more 1994 information. The following is an example, from [RFC3542], 1995 demonstrating the use of these macros to access ancillary data: 1997 struct msghdr msg; 1998 struct cmsghdr *cmsgptr; 2000 /* fill in msg */ 2002 /* call recvmsg() */ 2004 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 2005 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 2006 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 2007 u_char *ptr; 2009 ptr = CMSG_DATA(cmsgptr); 2010 /* process data pointed to by ptr */ 2011 } 2012 } 2014 5.4.3. Control Message Buffer Sizing 2016 The information conveyed via SCTP_SNDRCV events will often be 2017 fundamental to the correct and sane operation of the sockets 2018 application. This is particularly true of the one-to-many semantics, 2019 but also of the one-ton-one semantics. For example, if an 2020 application needs to send and receive data on different SCTP streams, 2021 SCTP_SNDRCV events are indispensable. 2023 Given that some ancillary data is critical, and that multiple 2024 ancillary data items may appear in any order, applications should be 2025 carefully written to always provide a large enough buffer to contain 2026 all possible ancillary data that can be presented by recvmsg(). If 2027 the buffer is too small, and crucial data is truncated, it may pose a 2028 fatal error condition. 2030 Thus it is essential that applications be able to deterministically 2031 calculate the maximum required buffer size to pass to recvmsg(). One 2032 constraint imposed on this specification that makes this possible is 2033 that all ancillary data definitions are of a fixed length. One way 2034 to calculate the maximum required buffer size might be to take the 2035 sum the sizes of all enabled ancillary data item structures, as 2036 calculated by CMSG_SPACE. For example, if we enabled 2037 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 2038 and allocate the buffer size as follows: 2040 size_t total; 2041 void *buf; 2043 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 2044 CMSG_SPACE(sizeof (struct in6_pktinfo)); 2046 buf = malloc(total); 2048 We could then use this buffer (buf) for msg_control on each call to 2049 recvmsg() and be assured that we would not lose any ancillary data to 2050 truncation. 2052 6. Common Operations for Both Styles 2054 6.1. send(), recv(), sendto(), and recvfrom() 2056 Applications can use send() and sendto() to transmit data to the peer 2057 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2058 data from the peer. 2060 The function prototypes are 2061 ssize_t send(int sd, 2062 const void *msg, 2063 size_t len, 2064 int flags); 2066 ssize_t sendto(int sd, 2067 const void *msg, 2068 size_t len, 2069 int flags, 2070 const struct sockaddr *to, 2071 socklen_t tolen); 2073 ssize_t recv(int sd, 2074 void *buf, 2075 size_t len, 2076 int flags); 2078 ssize_t recvfrom(int sd, 2079 void *buf, 2080 size_t len, 2081 int flags, 2082 struct sockaddr *from, 2083 socklen_t *fromlen); 2085 and the arguments are 2086 sd: The socket descriptor of an SCTP endpoint. 2087 msg: The message to be sent. 2088 len: the size of the message or the size of buffer. 2089 to: one of the peer addresses of the association to be used to send 2090 the message. 2091 tolen: The size of the address. 2092 buf: The buffer to store a received message. 2093 from: The buffer to store the peer address used to send the received 2094 message. 2095 fromlen: The size of the from address. 2096 flags: (described below). 2098 These calls give access to only basic SCTP protocol features. If 2099 either peer in the association uses multiple streams, or sends 2100 unordered data these calls will usually be inadequate, and may 2101 deliver the data in unpredictable ways. 2103 SCTP has the concept of multiple streams in one association. The 2104 above calls do not allow the caller to specify on which stream a 2105 message should be sent. The system uses stream 0 as the default 2106 stream for send() and sendto(). recv() and recvfrom() return data 2107 from any stream, but the caller can not distinguish the different 2108 streams. This may result in data seeming to arrive out of order. 2109 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2110 provide no indication. 2112 SCTP is message based. The msg buffer above in send() and sendto() 2113 is considered to be a single message. This means that if the caller 2114 wants to send a message which is composed by several buffers, the 2115 caller needs to combine them before calling send() or sendto(). 2116 Alternately, the caller can use sendmsg() to do that without 2117 combining them. Sending a message using send() or sendto() is atomic 2118 unless explicit EOR marking is enabled on the socket specified by sd. 2119 Using sendto() on a non-connected one-to-one style socket for 2120 implicit connection setup may or may not work depending on the SCTP 2121 implementation. recv() and recvfrom() cannot distinguish message 2122 boundaries. 2124 In receiving, if the buffer supplied is not large enough to hold a 2125 complete message, the receive call acts like a stream socket and 2126 returns as much data as will fit in the buffer. 2128 Note, the send() and recv() calls may not be used for a one-to-many 2129 style socket. 2131 Note, if an application calls a send function with no user data and 2132 no ancillary data the SCTP implementation should reject the request 2133 with an appropriate error message. An implementation is NOT allowed 2134 to send a Data chunk with no user data [RFC4960]. 2136 6.2. setsockopt() and getsockopt() 2138 Applications use setsockopt() and getsockopt() to set or retrieve 2139 socket options. Socket options are used to change the default 2140 behavior of sockets calls. They are described in Section 7. 2142 The function prototypes are 2144 int getsockopt(int sd, 2145 int level, 2146 int optname, 2147 void *optval, 2148 socklen_t *optlen); 2150 and 2151 int setsockopt(int sd, 2152 int level, 2153 int optname, 2154 const void *optval, 2155 socklen_t optlen); 2157 and the arguments are 2158 sd: The socket descriptor. 2159 level: Set to IPPROTO_SCTP for all SCTP options. 2160 optname - The option name. 2161 optval: The buffer to store the value of the option. 2162 optlen: The size of the buffer (or the length of the option 2163 returned). 2165 All socket options set on a 1-to-1 listening sockets also apply to 2166 all accepted sockets. For one-to-many style sockets often times a 2167 socket option will pass a structure that includes an assoc_id field. 2168 This field can be filled with the association id of a particular 2169 association and unless otherwise specified can be filled with one of 2170 the following constants: 2171 SCTP_FUTURE_ASSOC Specifies that only future associations created 2172 after this socket option will be effected by this call. 2173 SCTP_CURRENT_ASSOC Specifies that only currently existing 2174 associations will be effected by this call, future associations 2175 will still receive the previous default value. 2176 SCTP_ALL_ASSOC Specifies that all current and future associations 2177 will be effected by this call. 2179 6.3. read() and write() 2181 Applications can use read() and write() to send and receive data to 2182 and from peer. They have the same semantics as send() and recv() 2183 except that the flags parameter cannot be used. 2185 Note, these calls, when used in the one-to-many style, should only be 2186 used with branched off socket descriptors (see Section 8.2). 2188 6.4. getsockname() 2190 Applications use getsockname() to retrieve the locally-bound socket 2191 address of the specified socket. This is especially useful if the 2192 caller let SCTP chose a local port. This call is for where the 2193 endpoint is not multi-homed. It does not work well with multi-homed 2194 sockets. See Section 8.5 for a multi-homed version of the call. 2196 The function prototype is 2197 int getsockname(int sd, 2198 struct sockaddr *address, 2199 socklen_t *len); 2201 and the arguments are 2202 sd: The socket descriptor to be queried. 2203 address: On return, one locally bound address (chosen by the SCTP 2204 stack) is stored in this buffer. If the socket is an IPv4 socket, 2205 the address will be IPv4. If the socket is an IPv6 socket, the 2206 address will be either an IPv6 or IPv4 address. 2207 len: The caller should set the length of address here. On return, 2208 this is set to the length of the returned address. 2210 If the actual length of the address is greater than the length of the 2211 supplied sockaddr structure, the stored address will be truncated. 2213 If the socket has not been bound to a local name, the value stored in 2214 the object pointed to by address is unspecified. 2216 7. Socket Options 2218 The following sub-section describes various SCTP level socket options 2219 that are common to both styles. SCTP associations can be multi- 2220 homed. Therefore, certain option parameters include a 2221 sockaddr_storage structure to select which peer address the option 2222 should be applied to. 2224 For the one-to-many style sockets, an sctp_assoc_t structure 2225 (association ID) is used to identify the association instance that 2226 the operation affects. So it must be set when using this style. 2228 For the one-to-one style sockets and branched off one-to-many style 2229 sockets (see Section 8.2) this association ID parameter is ignored. 2231 Note that socket or IP level options are set or retrieved per socket. 2232 This means that for one-to-many style sockets, those options will be 2233 applied to all associations belonging to the socket. And for one-to- 2234 one style, those options will be applied to all peer addresses of the 2235 association controlled by the socket. Applications should be very 2236 careful in setting those options. 2238 For some IP stacks getsockopt() is read-only; so a new interface will 2239 be needed when information must be passed both in to and out of the 2240 SCTP stack. The syntax for sctp_opt_info() is 2241 int sctp_opt_info(int sd, 2242 sctp_assoc_t id, 2243 int opt, 2244 void *arg, 2245 socklen_t *size); 2247 The sctp_opt_info() call is a replacement for getsockopt() only and 2248 will not set any options associated with the specified socket. A 2249 setsockopt() must be used to set any writeable option. 2251 For one-to-many style sockets, id specifies the association to query. 2252 For one-to-one style sockets, id is ignored. 2254 The field opt specifies which SCTP socket option to get. It can get 2255 any socket option currently supported that requests information 2256 (either read/write options or read only) such as: 2257 SCTP_RTOINFO 2258 SCTP_ASSOCINFO 2259 SCTP_DEFAULT_SEND_PARAM 2260 SCTP_GET_PEER_ADDR_INFO 2261 SCTP_PRIMARY_ADDR 2262 SCTP_PEER_ADDR_PARAMS 2263 SCTP_STATUS 2264 SCTP_CONTEXT 2265 SCTP_AUTH_ACTIVE_KEY 2266 SCTP_PEER_AUTH_CHUNKS 2267 SCTP_LOCAL_AUTH_CHUNKS 2269 The arg field is an option-specific structure buffer provided by the 2270 caller. See Section 8.5 subsections for more information on these 2271 options and option-specific structures. 2273 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2274 sets errno to the appropriate error code. 2276 All options that support specific settings on an association by 2277 filling in either an association id variable or a sockaddr_storage 2278 should also support setting of the same value for the entire endpoint 2279 (i.e. future associations). To accomplish this the following logic 2280 is used when setting one of these options: 2281 o If an address is specified via a sockaddr_storage that is included 2282 in the structure, the address is used to lookup the association 2283 and the settings are applied to the specific address (if 2284 appropriate) or to the entire association. 2285 o If an association identification is filled in but not a 2286 sockaddr_storage (if present), the association is found using the 2287 association identification and the settings should be applied to 2288 the entire association (since a specific address is not 2289 specified). Note this also applies to options that hold an 2290 association identification in their structure but do not have a 2291 sockaddr_storage field. 2292 o If neither the sockaddr_storage or association identification is 2293 set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 2294 the association identification is 0, the settings are a default 2295 and to be applied to the endpoint (all future associations). 2297 7.1. Read / Write Options 2299 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2301 The protocol parameters used to initialize and bound retransmission 2302 timeout (RTO) are tunable. See [RFC4960] for more information on how 2303 these parameters are used in RTO calculation. 2305 The following structure is used to access and modify these 2306 parameters: 2308 struct sctp_rtoinfo { 2309 sctp_assoc_t srto_assoc_id; 2310 uint32_t srto_initial; 2311 uint32_t srto_max; 2312 uint32_t srto_min; 2313 }; 2315 srto_initial: This contains the initial RTO value. 2316 srto_max and srto_min: These contain the maximum and minimum bounds 2317 for all RTOs. 2318 srto_assoc_id: This parameter is ignored for one-to-one style 2319 sockets. For one-to-many style sockets the application may fill 2320 in an association identification or one of the predefined 2321 constants. 2323 All times are given in milliseconds. A value of 0, when modifying 2324 the parameters, indicates that the current value should not be 2325 changed. 2327 To access or modify these parameters, the application should call 2328 getsockopt or setsockopt() respectively with the option name 2329 SCTP_RTOINFO. 2331 7.1.2. Association Parameters (SCTP_ASSOCINFO) 2333 This option is used to both examine and set various association and 2334 endpoint parameters. See [RFC4960] for more information on how this 2335 parameter is used. 2337 The following structure is used to access and modify this parameters: 2339 struct sctp_assocparams { 2340 sctp_assoc_t sasoc_assoc_id; 2341 uint16_t sasoc_asocmaxrxt; 2342 uint16_t sasoc_number_peer_destinations; 2343 uint32_t sasoc_peer_rwnd; 2344 uint32_t sasoc_local_rwnd; 2345 uint32_t sasoc_cookie_life; 2346 }; 2348 sasoc_assoc_id: This parameter is ignored for one-to-one style 2349 sockets. For one-to-many style sockets the application may fill 2350 in an association identification or one of the predefined 2351 constants. 2352 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2353 to make for the association. 2354 sasoc_number_peer_destinations: This is the number of destination 2355 addresses that the peer has. 2356 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2357 (reported in the last SACK) minus any outstanding data (i.e. data 2358 inflight). 2359 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2360 the peer. 2361 sasoc_cookie_life: This is the associations cookie life value used 2362 when issuing cookies. 2364 The values of the sasoc_peer_rwnd is meaningless when examining 2365 endpoint information. 2367 All time values are given in milliseconds. A value of 0, when 2368 modifying the parameters, indicates that the current value should not 2369 be changed. 2371 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2372 on either an endpoint or association basis. The rwnd and destination 2373 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2374 sasoc_local_rwnd) are NOT settable and any value placed in these is 2375 ignored. 2377 To access or modify these parameters, the application should call 2378 getsockopt or setsockopt() respectively with the option name 2379 SCTP_ASSOCINFO. 2381 The maximum number of retransmissions before an address is considered 2382 unreachable is also tunable, but is address-specific, so it is 2383 covered in a separate option. If an application attempts to set the 2384 value of the association maximum retransmission parameter to more 2385 than the sum of all maximum retransmission parameters, setsockopt() 2386 may return an error. The reason for this, from [RFC4960] section 2387 8.2: 2389 Note: When configuring the SCTP endpoint, the user should avoid 2390 having the value of 'Association.Max.Retrans' larger than the 2391 summation of the 'Path.Max.Retrans' of all the destination addresses 2392 for the remote endpoint. Otherwise, all the destination addresses 2393 may become inactive while the endpoint still considers the peer 2394 endpoint reachable. 2396 7.1.3. Initialization Parameters (SCTP_INITMSG) 2398 Applications can specify protocol parameters for the default 2399 association initialization. The structure used to access and modify 2400 these parameters is defined in Section 5.2.1). The option name 2401 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2403 Setting initialization parameters is effective only on an unconnected 2404 socket (for one-to-many style sockets only future associations are 2405 effected by the change). With one-to-one style sockets, this option 2406 is inherited by sockets derived from a listener socket. 2408 7.1.4. SO_LINGER 2410 An application can use this option to perform the SCTP ABORT 2411 primitive. This option affects all associations related to the 2412 socket. 2414 The linger option structure is: 2416 struct linger { 2417 int l_onoff; /* option on/off */ 2418 int l_linger; /* linger time */ 2419 }; 2421 To enable the option, set l_onoff to 1. If the l_linger value is set 2422 to 0, calling close() is the same as the ABORT primitive. If the 2423 value is set to a negative value, the setsockopt() call will return 2424 an error. If the value is set to a positive value linger_time, the 2425 close() can be blocked for at most linger_time ms. If the graceful 2426 shutdown phase does not finish during this period, close() will 2427 return but the graceful shutdown phase continues in the system. 2429 Note, this is a socket level option NOT an SCTP level option. So 2430 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2431 setsockopt() call. 2433 7.1.5. SCTP_NODELAY 2435 Turn on/off any Nagle-like algorithm. This means that packets are 2436 generally sent as soon as possible and no unnecessary delays are 2437 introduced, at the cost of more packets in the network. Expects an 2438 integer boolean flag. Turning this option on disables any Nagle-like 2439 algoithm. 2441 7.1.6. SO_RCVBUF 2443 Sets receive buffer size in octets. For SCTP one-to-one style 2444 sockets, this controls the receiver window size. For one-to-many 2445 style sockets the meaning is implementation dependent. It might 2446 control the receive buffer for each association bound to the socket 2447 descriptor or it might control the receive buffer for the whole 2448 socket. The call expects an integer. 2450 7.1.7. SO_SNDBUF 2452 Sets send buffer size. For SCTP one-to-one style sockets, this 2453 controls the amount of data SCTP may have waiting in internal buffers 2454 to be sent. This option therefore bounds the maximum size of data 2455 that can be sent in a single send call. For one-to-many style 2456 sockets, the effect is the same, except that it applies to one or all 2457 associations (see Section 3.4) bound to the socket descriptor used in 2458 the setsockopt() or getsockopt() call. The option applies to each 2459 association's window size separately. The call expects an integer. 2461 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 2463 This socket option is applicable to the one-to-many style socket 2464 only. When set it will cause associations that are idle for more 2465 than the specified number of seconds to automatically close using the 2466 graceful shutdown procedure. An association being idle is defined as 2467 an association that has NOT sent or received user data. The special 2468 value of '0' indicates that no automatic close of any associations 2469 should be performed, this is the default value. The option expects 2470 an integer defining the number of seconds of idle time before an 2471 association is closed. 2473 An application using this option should enable receiving the 2474 association change notification. This is the only mechanism an 2475 application is informed about the closing of an association. After 2476 an association is closed, the association ID assigned to it can be 2477 reused. An application should be aware of this to avoid the possible 2478 problem of sending data to an incorrect peer end point. 2480 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 2482 Requests that the local SCTP stack use the enclosed peer address as 2483 the association primary. The enclosed address must be one of the 2484 association peer's addresses. 2486 The following structure is used to make a set peer primary request: 2488 struct sctp_setprim { 2489 sctp_assoc_t ssp_assoc_id; 2490 struct sockaddr_storage ssp_addr; 2491 }; 2493 ssp_addr: The address to set as primary. 2494 ssp_assoc_id: This parameter is ignored for one-to-one style 2495 sockets. For one-to-many style sockets it identifies the 2496 association for this request. Note that the predefined constants 2497 are NOT allowed. 2499 7.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2501 Requests that the local endpoint set the specified Adaptation Layer 2502 Indication parameter for all future INIT and INIT-ACK exchanges. 2504 The following structure is used to access and modify this parameter: 2506 struct sctp_setadaptation { 2507 uint32_t ssb_adaptation_ind; 2508 }; 2510 ssb_adaptation_ind: The adaptation layer indicator that will be 2511 included in any outgoing Adaptation Layer Indication parameter. 2513 7.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 2515 This option is a on/off flag and is passed has an integer where a 2516 non-zero is on and a zero is off. If enabled no SCTP message 2517 fragmentation will be performed. Instead if a message being sent 2518 exceeds the current PMTU size, the message will NOT be sent and 2519 instead a error will be indicated to the user. 2521 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2523 Applications can enable or disable heartbeats for any peer address of 2524 an association, modify an address's heartbeat interval, force a 2525 heartbeat to be sent immediately, and adjust the address's maximum 2526 number of retransmissions sent before an address is considered 2527 unreachable. 2529 The following structure is used to access and modify an address's 2530 parameters: 2532 struct sctp_paddrparams { 2533 sctp_assoc_t spp_assoc_id; 2534 struct sockaddr_storage spp_address; 2535 uint32_t spp_hbinterval; 2536 uint16_t spp_pathmaxrxt; 2537 uint32_t spp_pathmtu; 2538 uint32_t spp_flags; 2539 uint32_t spp_ipv6_flowlabel; 2540 uint8_t spp_ipv4_tos; 2541 }; 2543 spp_assoc_id: This parameter is ignored for one-to-one style 2544 sockets. For one-to-many style sockets it identifies the 2545 association for this query. Note that the predefined constants 2546 are NOT allowed. 2547 spp_address: This specifies which address is of interest. 2548 spp_hbinterval: This contains the value of the heartbeat interval, 2549 in milliseconds. Note that unless the spp_flag is set to 2550 SPP_HB_ENABLE the value of this field is ignored. Note also that 2551 a value of zero indicates the current setting should be left 2552 unchanged. To set an actual value of zero the use of the flag 2553 SPP_HB_TIME_IS_ZERO should be used. 2554 spp_pathmaxrxt: This contains the maximum number of retransmissions 2555 before this address shall be considered unreachable. Note that a 2556 value of zero indicates the current setting should be left 2557 unchanged. 2558 spp_pathmtu: When Path MTU discovery is disabled the value specified 2559 here will be the "fixed" path MTU (i.e. the value of the spp_flags 2560 field must include the flag SPP_PMTUD_DISABLE). Note that if the 2561 spp_address field is empty then all destinations for this 2562 association will have this fixed path MTU set upon them. If an 2563 address is specified, then only that address will be effected. 2564 Note also that this option cannot be set on the endpoint, but must 2565 be set on each individual association. Also, when disabling PMTU 2566 discovery, the implementation may disallow this behavior if the 2567 "fixed" path MTU is below the constant value SCTP_SMALLEST_PMTU. 2568 spp_ipv6_flowlabel: This field is used in conjunction with the 2569 SPP_IPV6_FLOWLABEL flag. 2570 spp_ipv4_tos: This field is used in conjunction with the 2571 SPP_IPV4_TOS flag. 2572 spp_flags: These flags are used to control various features on an 2573 association. The flag field is a bit mask which may contain zero 2574 or more of the following options: 2576 SPP_HB_ENABLE: Enable heartbeats on the specified address. Note 2577 that if the address field is empty all addresses for the 2578 association have heartbeats enabled upon them. 2579 SPP_HB_DISABLE: Disable heartbeats on the specified address. 2580 Note that if the address field is empty all addresses for the 2581 association will have their heartbeats disabled. Note also 2582 that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, 2583 only one of these two should be specified. Enabling both 2584 fields will have undetermined results. 2585 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 2586 immediately. 2587 SPP_HB_TIME_IS_ZERO: Specify's that the time for heartbeat delay 2588 is to be set to the value of 0 milliseconds. 2589 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 2590 specified address. Note that if the address field is empty 2591 then all addresses on the association are effected. 2592 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 2593 the specified address. Note that if the address field is empty 2594 then all addresses on the association are effected. Note also 2595 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2596 exclusive. Enabling both will have undetermined results. 2597 SPP_IPV6_FLOWLABEL: Setting this flag enables setting of the IPV6 2598 flowlabel value associated with either the association or the 2599 specific address. If the address field is filled in, then the 2600 specific destination address has this value set upon it. If 2601 the association is specified, but not the address, then the 2602 flowlabel value is set for any future destination addresses 2603 that may be added. The value is obtained in the 2604 spp_ipv6_flowlabel field. 2606 Upon retrieval, this flag will be set to indicate that the 2607 spp_ipv6_flowlabel field has a valid value returned. If a 2608 specific destination addresses is set (in the spp_address 2609 field) when called then the value returned is that of the 2610 address. If just an association is specified (and no address) 2611 then the association default flowlabel is returned. If neither 2612 an association nor an destination is specified, then the 2613 sockets default flowlabel is returned. For non IPv6 sockets, 2614 then this flag will be left cleared. 2615 SPP_IPV4_TOS: Setting this flag enables setting of the IPV4 tos 2616 value associated with either the association or specific 2617 address. If the address field is filled in, then the specific 2618 destination address has this value set upon it. If the 2619 association is specified, but not the address, then the tos 2620 value is set for any future destination addresses that may be 2621 added. The value is obtained in the spp_ipv4_tos field. 2623 Upon retrieval, this flag will be set to indicate that the 2624 spp_ipv4_tos field has a valid value returned. If a specific 2625 destination addresses is set when called (in the spp_address 2626 field) then that specific destination addresses tos value is 2627 returned. If just an association is specified then the 2628 association default tos is returned. If neither an association 2629 nor an destination is specified, then the sockets default tos 2630 is returned. For non IPv4 sockets, then this flag will be left 2631 cleared. 2633 To read or modify these parameters, the application should call 2634 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2636 7.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) 2638 Applications that wish to use the sendto() system call may wish to 2639 specify a default set of parameters that would normally be supplied 2640 through the inclusion of ancillary data. This socket option allows 2641 such an application to set the default sctp_sndrcvinfo structure. 2642 The application that wishes to use this socket option simply passes 2643 in to this call the sctp_sndrcvinfo structure defined in 2644 Section 5.2.2. The input parameters accepted by this call include 2645 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy 2646 and sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of 2647 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field 2648 specifies the association to apply the parameters to in a one-to-many 2649 style sockets any of the predefined constants are also allowed in 2650 this field. The field is ignored on the one-to-one style. 2652 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) 2654 This socket option is used to specify various notifications and 2655 ancillary data the user wishes to receive. Please see Section 7.4 2656 for a full description of this option and its usage. Note that this 2657 option is considered deprecated and present for backward 2658 compatiability. New applications should use the SCTP_SET_EVENT 2659 option see section Section 7.4 for a full description of that option 2660 as well. 2662 7.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2664 This socket option is a boolean flag which turns on or off mapped V4 2665 addresses. If this option is turned on and the socket is type 2666 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2667 If this option is turned off, then no mapping will be done of V4 2668 addresses and a user will receive both PF_INET6 and PF_INET type 2669 addresses on the socket. 2671 By default this option is turned off and expects an integer to be 2672 passed where non-zero turns on the option and zero turns off the 2673 option. 2675 7.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 2677 This option will get or set the maximum size to put in any outgoing 2678 SCTP DATA chunk. If a message is larger than this size it will be 2679 fragmented by SCTP into the specified size. Note that the underlying 2680 SCTP implementation may fragment into smaller sized chunks when the 2681 PMTU of the underlying association is smaller than the value set by 2682 the user. The default value for this option is '0' which indicates 2683 the user is NOT limiting fragmentation and only the PMTU will effect 2684 SCTP's choice of DATA chunk size. Note also that values set larger 2685 than the maximum size of an IP datagram will effectively let SCTP 2686 control fragmentation (i.e. the same as setting this option to 0). 2688 The following structure is used to access and modify this parameter: 2690 struct sctp_assoc_value { 2691 sctp_assoc_t assoc_id; 2692 uint32_t assoc_value; 2693 }; 2695 assoc_id: This parameter is ignored for one-to-one style sockets. 2696 For one-to-many style sockets this parameter indicates which 2697 association the user is performing an action upon. Note that any 2698 of the predefined constants are also allowed in this field. 2699 assoc_value: This parameter specifies the maximum size in bytes. 2701 7.1.17. Get or Set the List of Supported HMAC Identifiers 2702 (SCTP_HMAC_IDENT) 2704 This option gets or sets the list of HMAC algorithms that the local 2705 endpoint requires the peer to use. 2707 The following structure is used to get or set these identifiers: 2709 struct sctp_hmacalgo { 2710 uint32_t shmac_number_of_idents; 2711 uint16_t shmac_idents[]; 2712 }; 2714 shmac_number_of_idents: This field gives the number of elements 2715 present in the array shmac_idents. 2717 shmac_idents: This parameter contains an array of HMAC Identifiers 2718 that the local endpoint is requesting the peer to use, in priority 2719 order. The following identifiers are valid: 2720 * SCTP_AUTH_HMAC_ID_SHA1 2721 * SCTP_AUTH_HMAC_ID_SHA256 2723 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 2724 may include any of the other values in its preferred order (lowest 2725 list position has the most preference in algorithm selection). Note 2726 also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion of an 2727 unknown HMAC identifier (including optional identifiers unknown to 2728 the implementation) will cause the set option to fail and return an 2729 error. 2731 7.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 2733 This option will get or set the active shared key to be used to build 2734 the association shared key. 2736 The following structure is used to access and modify these 2737 parameters: 2739 struct sctp_authkeyid { 2740 sctp_assoc_t scact_assoc_id; 2741 uint16_t scact_keynumber; 2742 }; 2744 scact_assoc_id: This parameter, if non-zero, indicates what 2745 association that the shared key identifier is being set active 2746 upon. Note that if this element contains zero, then the 2747 activation applies to the endpoint and all future associations 2748 will use the specified shared key identifier. For one-to-one 2749 sockets, this parameter is ignored. Note, however, that this 2750 option will set the active key on the association if the socket is 2751 connected, otherwise this will set the default active key for the 2752 endpoint. 2753 scact_keynumber: This parameter is the shared key identifier which 2754 the application is requesting to become the active shared key to 2755 be used for sending authenticated chunks. The key identifier must 2756 correspond to an existing shared key. Note that shared key 2757 identifier '0' defaults to a null key. 2759 When used with setsockopt() the SCTP implementation must use the 2760 indicated shared key identifier for all messages being given to an 2761 SCTP implementation via a send call after the setsockopt() call until 2762 changed again. Therefore the SCTP implementation must not bundle 2763 user messages which should be authenticated using different shared 2764 key identifiers. 2766 Initially the key with key identifier 0 is the active key. 2768 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 2770 This option will effect the way delayed acks are performed. This 2771 option allows you to get or set the delayed ack time, in 2772 milliseconds. It also allows changing the delayed ack frequency. 2773 Changing the frequency to 1 disables the delayed sack algorithm. If 2774 the sack_assoc_id is 0, then this sets or gets the endpoints default 2775 values. If the sack_assoc_id field is non-zero, then the set or get 2776 effects the specified association for the one to many model (the 2777 assoc_id field is ignored by the one to one model). Note that if 2778 sack_delay or sack_freq are 0 when setting this option, then the 2779 current values will remain unchanged. 2781 The following structure is used to access and modify these 2782 parameters: 2784 struct sctp_sack_info { 2785 sctp_assoc_t sack_assoc_id; 2786 uint32_t sack_delay; 2787 uint32_t sack_freq; 2788 }; 2790 sack_assoc_id: This parameter is ignored for one-to-one style 2791 sockets. For one-to-many style sockets this parameter indicates 2792 which association the user is performing an action upon. Note 2793 that any of the predefined constants may also be used for one-to- 2794 many style sockets. 2795 sack_delay: This parameter contains the number of milliseconds that 2796 the user is requesting the delayed ACK timer be set to. Note that 2797 this value is defined in the standard to be between 200 and 500 2798 milliseconds. 2799 sack_freq: This parameter contains the number of packets that must 2800 be received before a sack is sent without waiting for the delay 2801 timer to expire. The default value for this is 2, setting this 2802 value to 1 will disable the delayed sack algorithm. 2804 7.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 2806 Fragmented interleave controls how the presentation of messages 2807 occurs for the message receiver. There are three levels of fragment 2808 interleave defined. Two of the levels effect the one-to-one model, 2809 while the one-to-many model is effected by all three levels. 2811 This option takes an integer value. It can be set to a value of 0, 1 2812 or 2. Attempting to set this level to other values will return an 2813 error. 2815 Setting the three levels provides the following receiver 2816 interactions: 2818 level 0: Prevents the interleaving of any messages. This means that 2819 when a partial delivery begins, no other messages will be received 2820 except the message being partially delivered. If another message 2821 arrives on a different stream (or association) that could be 2822 delivered, it will be blocked waiting for the user to read all of 2823 the partially delivered message. 2824 level 1: Allows interleaving of messages that are from different 2825 associations. For the one-to-one model, level 0 and level 1 thus 2826 have the same meaning since a one-to-one socket always receives 2827 messages from the same association. Note that setting the one-to- 2828 many model to this level may cause multiple partial delivers from 2829 different associations but for any given association, only one 2830 message will be delivered until all parts of a message have been 2831 delivered. This means that one large message, being read with an 2832 association identification of "X", will block other messages from 2833 association "X" from being delivered. 2834 level 2: Allows complete interleaving of messages. This level 2835 requires that the sender carefully observe not only the peer 2836 association identification (or address) but also must pay careful 2837 attention to the stream number. With this option enabled a 2838 partially delivered message may begin being delivered for 2839 association "X" stream "Y" and the next subsequent receive may 2840 return a message from association "X" stream "Z". Note that no 2841 other messages would be delivered for association "X" stream "Y" 2842 until all of stream "Y"'s partially delivered message was read. 2843 Note that this option also effects the one-to-one model. Also 2844 note that for the one-to-many model not only may another streams 2845 message from the same association be delivered from the next 2846 receive, some other associations message may be delivered upon the 2847 next receive. 2849 An implementation should default the one-to-many model to level 1. 2850 The reason for this is that otherwise it is possible that a peer 2851 could begin sending a partial message and thus block all other peers 2852 from sending data. However a setting of level 2 requires the 2853 application to not only be aware of the association (via the 2854 association id or peers address) but also the stream number. The 2855 stream number is NOT present unless the user has subscribed to the 2856 sctp_data_io_events (see Section 7.4). This is also why we recommend 2857 that the one-to-one model be defaulted to level 0 (level 1 for the 2858 one-to-one model has no effect). Note that an implementation should 2859 return an error if a application attempts to set the level to 2 and 2860 has NOT subscribed to the sctp_data_io_events. 2862 For applications that have subscribed to events those events appear 2863 in the normal socket buffer data stream. This means that unless the 2864 user has set the fragmentation interleave level to 0, notifications 2865 may also be interleaved with partially delivered messages. 2867 7.1.21. Set or Get the SCTP Partial Delivery Point 2868 (SCTP_PARTIAL_DELIVERY_POINT) 2870 This option will set or get the SCTP partial delivery point. This 2871 point is the size of a message where the partial delivery API will be 2872 invoked to help free up rwnd space for the peer. Setting this to a 2873 lower value will cause partial deliveries to happen more often. The 2874 calls argument is an integer that sets or gets the partial delivery 2875 point. Note also that the call will fail if the user attempts to set 2876 this value larger than the socket receive buffer size. 2878 Note that any single message having a length smaller than or equal to 2879 the SCTP partial delivery point will be delivered in one single read 2880 call as long as the user provided buffer is large enough to hold the 2881 message. 2883 7.1.22. Set or Get the Use of Extended Receive Info 2884 (SCTP_USE_EXT_RCVINFO) 2886 This option will enable or disable the use of the extended version of 2887 the sctp_sndrcvinfo structure. If this option is disabled, then the 2888 normal sctp_sndrcvinfo structure is returned in all receive message 2889 calls. If this option is enabled then the sctp_extrcvinfo structure 2890 is returned in all receive message calls. This option is present for 2891 compatability with older applications and is deprecated. Future 2892 applications should use SCTP_NXTINFO to retrieve this same 2893 information via ancillary data. 2895 Note that the sctp_extrcvinfo structure is never used in any send 2896 call. 2898 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 2900 This option will enable or disable the use of the automatic 2901 generation of ASCONF chunks to add and delete addresses to an 2902 existing association. Note that this option has two caveats namely: 2903 a) it only effects sockets that are bound to all addresses on the 2904 machine, and b) the system administrator may have an overriding 2905 control that turns the ASCONF feature off no matter what setting the 2906 socket option may have. 2908 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 2910 This option will allow a user to change the maximum burst of packets 2911 that can be emitted by this association. Note that the default value 2912 is 4, and some implementations may restrict this setting so that it 2913 can only be lowered. 2915 To set or get this option the user fills in the following structure: 2917 struct sctp_assoc_value { 2918 sctp_assoc_t assoc_id; 2919 uint32_t assoc_value; 2920 }; 2922 assoc_id: This parameter is ignored for one-to-one style sockets. 2923 For one-to-many style sockets this parameter indicates which 2924 association the user is performing an action upon. Note that any 2925 of the predefined constants may be used for one-to-many style 2926 sockets. 2927 assoc_value: This parameter contains the maximum burst. 2929 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) 2931 The context field in the sctp_sndrcvinfo structure is normally only 2932 used when a failed message is retrieved holding the value that was 2933 sent down on the actual send call. This option allows the setting of 2934 a default context on an association basis that will be received on 2935 reading messages from the peer. This is especially helpful in the 2936 one-2-many model for an application to keep some reference to an 2937 internal state machine that is processing messages on the 2938 association. Note that the setting of this value only effects 2939 received messages from the peer and does not effect the value that is 2940 saved with outbound messages. 2942 To set or get this option the user fills in the following structure: 2944 struct sctp_assoc_value { 2945 sctp_assoc_t assoc_id; 2946 uint32_t assoc_value; 2947 }; 2949 assoc_id: This parameter is ignored for one-to-one style sockets. 2950 For one-to-many style sockets this parameter indicates which 2951 association the user is performing an action upon. Note that any 2952 of the predefined constants may be used for one-to-many style 2953 sockets. 2955 assoc_value: This parameter contains the context. 2957 7.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 2959 This boolean flag is used to enable or disable explicit end of record 2960 (EOR) marking. When this option is enabled, a user may make multiple 2961 send system calls to send a record and must indicate that they are 2962 finished sending a particular record by including on the send the 2963 SCTP_EOR flag. If this boolean flag is disabled then each individual 2964 send system call is considered to have a SCTP_EOR indicator set on it 2965 implicitly without the user having to explicitly add this flag. 2967 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 2969 This option only supports one-to-one style SCTP sockets. If used on 2970 a one-to-many style SCTP socket an error is indicated. 2972 This setsockopt() call must not be used after calling bind() or 2973 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 2974 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 2975 SCTP sockets bound to the same port must have set the 2976 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 2977 having set the SCTP_REUSE_PORT option will fail if there are other 2978 sockets bound to the same port. At most one socket being bound to 2979 the same port may be listening. 2981 It should be noted that the behaviour of the socket level socket 2982 option to reuse ports and/or addresses for SCTP sockets is 2983 unspecified. 2985 7.1.28. Set Notification Event (SCTP_EVENT) 2987 This socket option is used to set a specific notification or 2988 ancillary data option. Please see Section 7.4 for a full description 2989 of this option and its usage. 2991 7.2. Read-Only Options 2993 The options defined in this subsection are read-only. Using this 2994 option in a setsockopt() call will result in a error indicating 2995 EOPNOTSUPP. 2997 7.2.1. Association Status (SCTP_STATUS) 2999 Applications can retrieve current status information about an 3000 association, including association state, peer receiver window size, 3001 number of unacked data chunks, and number of data chunks pending 3002 receipt. This information is read-only. 3004 The following structure is used to access this information: 3006 struct sctp_status { 3007 sctp_assoc_t sstat_assoc_id; 3008 int32_t sstat_state; 3009 uint32_t sstat_rwnd; 3010 uint16_t sstat_unackdata; 3011 uint16_t sstat_penddata; 3012 uint16_t sstat_instrms; 3013 uint16_t sstat_outstrms; 3014 uint32_t sstat_fragmentation_point; 3015 struct sctp_paddrinfo sstat_primary; 3016 }; 3018 sstat_assoc_id: This parameter is ignored for one-to-one style 3019 sockets. For one-to-many style sockets it holds the identifier 3020 for the association. All notifications for a given association 3021 have the same association identifier. Note that the one-to-many 3022 predefined constants may not be used with this option. 3023 sstat_state: This contains the association's current state one of 3024 the following values: 3025 * SCTP_CLOSED 3026 * SCTP_BOUND 3027 * SCTP_LISTEN 3028 * SCTP_COOKIE_WAIT 3029 * SCTP_COOKIE_ECHOED 3030 * SCTP_ESTABLISHED 3031 * SCTP_SHUTDOWN_PENDING 3032 * SCTP_SHUTDOWN_SENT 3033 * SCTP_SHUTDOWN_RECEIVED 3034 * SCTP_SHUTDOWN_ACK_SENT 3035 sstat_rwnd: This contains the association peer's current receiver 3036 window size. 3037 sstat_unackdata: This is the number of unacked data chunks. 3038 sstat_penddata: This is the number of data chunks pending receipt. 3039 sstat_primary: This is information on the current primary peer 3040 address. 3041 sstat_instrms: The number of streams that the peer will be using 3042 inbound. 3043 sstat_outstrms: The number of streams that the endpoint is allowed 3044 to use outbound. 3045 sstat_fragmentation_point - The size at which SCTP fragmentation 3046 will occur. 3048 To access these status values, the application calls getsockopt() 3049 with the option name SCTP_STATUS. 3051 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3053 Applications can retrieve information about a specific peer address 3054 of an association, including its reachability state, congestion 3055 window, and retransmission timer values. This information is read- 3056 only. 3058 The following structure is used to access this information: 3060 struct sctp_paddrinfo { 3061 sctp_assoc_t spinfo_assoc_id; 3062 struct sockaddr_storage spinfo_address; 3063 int32_t spinfo_state; 3064 uint32_t spinfo_cwnd; 3065 uint32_t spinfo_srtt; 3066 uint32_t spinfo_rto; 3067 uint32_t spinfo_mtu; 3068 }; 3070 spinfo_assoc_id: This is parameter is ignored for one-to-one style 3071 sockets. For one-to-many style sockets the following applies: 3072 This is field may be filled in by the application, if so, this 3073 field will have priority in looking up the association over the 3074 address specified in spinfo_address. Note that if the address 3075 does not belong to the association specified then this call will 3076 fail. If the application does NOT fill in the spinfo_assoc_id, 3077 then the address will be used to lookup the association and on 3078 return this field will have the valid association id. In other 3079 words, this call can be used to translate a address into an 3080 association id. Note that the predefined constants are not 3081 allowed on this option. 3082 spinfo_address: This is filled in the application, and contains the 3083 peer address of interest. 3084 spinfo_state: This contains the peer addresses's state (either 3085 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 3086 SCTP_UNCONFIRMED). 3087 spinfo_cwnd: This contains the peer addresses's current congestion 3088 window. 3089 spinfo_srtt: This contains the peer addresses's current smoothed 3090 round-trip time calculation in milliseconds. 3091 spinfo_rto: This contains the peer addresses's current 3092 retransmission timeout value in milliseconds. 3093 spinfo_mtu: The current P-MTU of this address. 3095 7.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3096 (SCTP_PEER_AUTH_CHUNKS) 3098 This option gets a list of chunks for a specified association that 3099 the peer requires to be received authenticated only. 3101 The following structure is used to access these parameters: 3103 struct sctp_authchunks { 3104 sctp_assoc_t gauth_assoc_id; 3105 guint32_t gauth_number_of_chunks 3106 uint8_t gauth_chunks[]; 3107 }; 3109 gauth_assoc_id: This parameter, indicates which association the user 3110 is requesting the list of peer authenticated chunks. For one-to- 3111 one sockets, this parameter is ignored. Note that the predefined 3112 constants are not allowed with this option. 3113 gauth_number_of_chunks: This parameter gives the number of elements 3114 in the array gauth_chunks. 3115 gauth_chunks: This parameter contains an array of chunks that the 3116 peer is requesting to be authenticated. 3118 7.2.4. Get the List of Chunks the Local Endpoint Requires to be 3119 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3121 This option gets a list of chunks for a specified association that 3122 the local endpoint requires to be received authenticated only. 3124 The following structure is used to access these parameters: 3126 struct sctp_authchunks { 3127 sctp_assoc_t gauth_assoc_id; 3128 uint32_t gauth_number_of_chunks; 3129 uint8_t gauth_chunks[]; 3130 }; 3132 gauth_assoc_id: This parameter, indicates which association the user 3133 is requesting the list of local authenticated chunks. For one-to- 3134 one sockets, this parameter is ignored. 3135 gauth_number_of_chunks: This parameter gives the number of elements 3136 in the array gauth_chunks. 3137 gauth_chunks: This parameter contains an array of chunks that the 3138 local endpoint is requesting to be authenticated. 3140 7.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3142 This option gets the current number of associations that are attached 3143 to a one-to-many style socket. The option value is an uint32_t. 3145 7.2.6. Get the Current Identifiers of Associations 3146 (SCTP_GET_ASSOC_ID_LIST) 3148 This option gets the current list of SCTP association identifiers of 3149 the SCTP associations handled by a one-to-many style socket. 3151 The option value has the structure 3153 struct sctp_assoc_ids { 3154 uint32_t gaids_number_of_ids; 3155 sctp_assoc_t gaids_assoc_id[]; 3156 }; 3158 The caller must provide a large enough buffer to hold all association 3159 identifiers. If the buffer is too small, an error must be returned. 3160 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3161 idea how large the buffer has to be. gaids_number_of_ids gives the 3162 number of elements in the array gaids_assoc_id. 3164 7.3. Write-Only Options 3166 The options defined in this subsection are write-only. Using this 3167 option in a getsockopt() or sctp_opt_info() call will result in a 3168 error indicating EOPNOTSUPP. 3170 7.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3172 Requests that the peer mark the enclosed address as the association 3173 primary. The enclosed address must be one of the association's 3174 locally bound addresses. 3176 The following structure is used to make a set peer primary request: 3178 struct sctp_setpeerprim { 3179 sctp_assoc_t sspp_assoc_id; 3180 struct sockaddr_storage sspp_addr; 3181 }; 3183 sspp_addr: The address to set as primary. 3184 sspp_assoc_id: This parameter is ignored for one-to-one style 3185 sockets. For one-to-many style sockets it identifies the 3186 association for this request. Note that the predefined constants 3187 are not allowed on this option. 3189 7.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) 3191 This set option adds a chunk type that the user is requesting to be 3192 received only in an authenticated way. Changes to the list of chunks 3193 will only effect future associations on the socket. 3195 The following structure is used to add a chunk: 3197 struct sctp_authchunk { 3198 uint8_t sauth_chunk; 3199 }; 3201 sauth_chunk: This parameter contains a chunk type that the user is 3202 requesting to be authenticated. 3204 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3205 chunks must not be used. If they are used, an error must be 3206 returned. The usage of this option enables SCTP-AUTH in cases where 3207 it is not required by other means (for example the use of dynamic 3208 address reconfiguration). 3210 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3212 This option will set a shared secret key which is used to build an 3213 association shared key. 3215 The following structure is used to access and modify these 3216 parameters: 3218 struct sctp_authkey { 3219 sctp_assoc_t sca_assoc_id; 3220 uint16_t sca_keynumber; 3221 uint16_t sca_keylength; 3222 uint8_t sca_key[]; 3223 }; 3225 sca_assoc_id: This parameter, if non-zero, indicates what 3226 association that the shared key is being set upon. Note that any 3227 of the predefined constants can be used. For one-to-one sockets, 3228 this parameter is ignored. Note, however, that this option will 3229 set a key on the association if the socket is connected, otherwise 3230 this will set a key on the endpoint. 3231 sca_keynumber: This parameter is the shared key identifier by which 3232 the application will refer to this key. If a key of the specified 3233 index already exists, then this new key will replace the old 3234 existing key. Note that shared key identifier '0' defaults to a 3235 null key. 3236 sca_keylength: This parameter is the length of the array sca_key. 3238 sca_key: This parameter contains an array of bytes that is to be 3239 used by the endpoint (or association) as the shared secret key. 3240 Note, if the length of this field is zero, a null key is set. 3242 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3244 This set option indicates that the application will not send user 3245 messages anymore requiring the usage of the indicated key identifier. 3247 struct sctp_authkeyid { 3248 sctp_assoc_t scact_assoc_id; 3249 uint16_t scact_keynumber; 3250 }; 3252 scact_assoc_id: This parameter, if non-zero, indicates what 3253 association that the shared key identifier is being deactivated. 3254 Note that the predefined constants may be used with this option. 3255 For one-to-one sockets, this parameter is ignored. Note, however, 3256 that this option will deactivate the key from the association if 3257 the socket is connected, otherwise this will deactivate the key 3258 from the endpoint. 3259 scact_keynumber: This parameter is the shared key identifier which 3260 the application is requesting to be deactivated. The key 3261 identifier must correspond to an existing shared key. Note if 3262 this parameter is zero, use of the null key identifier '0' is 3263 deactivated on the endpoint and/or association. 3265 The currently active key can not be deactivated. 3267 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3269 This set option will delete a shared secret key in the SCTP 3270 implementation. 3272 struct sctp_authkeyid { 3273 sctp_assoc_t scact_assoc_id; 3274 uint16_t scact_keynumber; 3275 }; 3277 scact_assoc_id: This parameter, if non-zero, indicates what 3278 association that the shared key identifier is being deleted from. 3279 Note that if this element contains zero, then the shared key is 3280 deleted from the endpoint and all associations will no longer use 3281 the specified shared key identifier (unless otherwise set on the 3282 association using SCTP_AUTH_KEY). For one-to-one sockets, this 3283 parameter is ignored. Note, however, that this option will delete 3284 the key from the association if the socket is connected, otherwise 3285 this will delete the key from the endpoint. 3287 scact_keynumber: This parameter is the shared key identifier which 3288 the application is requesting to be deleted. The key identifier 3289 must correspond to an existing shared key and must not be in use 3290 for any packet being sent by the SCTP implementation. This means 3291 in particular, that it must be deactivated first. Note if this 3292 parameter is zero, use of the null key identifier '0' is deleted 3293 from the endpoint and/or association. 3295 Only deactivated keys which are no longer used by the kernel can be 3296 deleted. 3298 7.4. Ancillary Data and Notification Interest Options 3300 Applications can receive per-message ancillary information and 3301 notifications of certain SCTP events with recvmsg(). 3303 The following optional information is available to the application: 3304 SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3305 stream number, TSN, SSN, etc. described in Section 5.2.2) 3306 SCTP_ASSOC_CHANGE (sctp_association_event): described in 3307 Section 5.3.2 3308 SCTP_PEER_ADDR_CHANGE (sctp_address_event): described in 3309 Section 5.3.3 3310 SCTP_SEND_FAILED (sctp_send_failure_event): described in 3311 Section 5.3.5 3312 SCTP_REMOTE_ERROR (sctp_peer_error_event): described in 3313 Section 5.3.4 3314 SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): described in 3315 Section 5.3.6 3316 SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): described 3317 in Section 5.3.8 3318 SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): described 3319 in Section 5.3.7 3320 SCTP_AUTHENTICATION_EVENT (sctp_authentication_event): described in 3321 Section 5.3.9) 3322 SCTP_SENDER_DRY_EVENT (sctp_sender_dry_event): described in 3323 Section 5.3.10 3324 SCTP_NOTIFICATIONS_STOPPED_EVENT (sctp_tlv): described in 3325 Section 5.3.11 3327 To receive any ancillary data or notifications, first the application 3328 registers its interest by calling the SCTP_EVENTS setsockopt() with 3329 the following structure: 3331 struct sctp_event_subscribe{ 3332 uint8_t sctp_data_io_event; 3333 uint8_t sctp_association_event; 3334 uint8_t sctp_address_event; 3335 uint8_t sctp_send_failure_event; 3336 uint8_t sctp_peer_error_event; 3337 uint8_t sctp_shutdown_event; 3338 uint8_t sctp_partial_delivery_event; 3339 uint8_t sctp_adaptation_layer_event; 3340 uint8_t sctp_authentication_event; 3341 uint8_t sctp_sender_dry_event; 3342 }; 3344 sctp_data_io_event: Setting this flag to 1 will cause the reception 3345 of SCTP_SNDRCV information on a per message basis. The 3346 application will need to use the recvmsg() interface so that it 3347 can receive the event information contained in the msg_control 3348 field. Setting the flag to 0 will disable reception of the 3349 message control information. 3350 sctp_association_event: Setting this flag to 1 will enable the 3351 reception of association event notifications. Setting the flag to 3352 0 will disable association event notifications. 3353 sctp_address_event: Setting this flag to 1 will enable the reception 3354 of address event notifications. Setting the flag to 0 will 3355 disable address event notifications. 3356 sctp_send_failure_event: Setting this flag to 1 will enable the 3357 reception of send failure event notifications. Setting the flag 3358 to 0 will disable send failure event notifications. 3359 sctp_peer_error_event: Setting this flag to 1 will enable the 3360 reception of peer error event notifications. Setting the flag to 3361 0 will disable peer error event notifications. 3362 sctp_shutdown_event: Setting this flag to 1 will enable the 3363 reception of shutdown event notifications. Setting the flag to 0 3364 will disable shutdown event notifications. 3365 sctp_partial_delivery_event: Setting this flag to 1 will enable the 3366 reception of partial delivery notifications. Setting the flag to 3367 0 will disable partial delivery event notifications. 3368 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 3369 reception of adaptation layer notifications. Setting the flag to 3370 0 will disable adaptation layer event notifications. 3371 sctp_authentication_event: Setting this flag to 1 will enable the 3372 reception of authentication layer notifications. Setting the flag 3373 to 0 will disable authentication layer event notifications. 3374 sctp_sender_dry_event: Setting this flag to 1 will enable the 3375 reception of sender dry notifications. Setting the flag to 0 will 3376 disable sender dry event notifications. 3378 An example where an application would like to receive data io events 3379 and association events but no others would be as follows: 3381 { 3382 struct sctp_event_subscribe event; 3384 memset(&event,0,sizeof(event)); 3386 event.sctp_data_io_event = 1; 3387 event.sctp_association_event = 1; 3389 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event)); 3390 } 3392 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3393 receives ancillary data and notifications for ALL associations bound 3394 to the file descriptor. For one-to-one style SCTP sockets, the 3395 caller receives ancillary data and notifications for only the single 3396 association bound to the file descriptor. 3398 The SCTP_EVENTS socket option has one issue for future compatability. 3399 As new features are added the structure (sctp_event_subscribe) must 3400 be expanded. This can cause an ABI issue unless an implementation 3401 has added padding at the end of the structure. To avoid this 3402 problem, SCTP_EVENTS has been deprecated and a new option SCTP_EVENT 3403 socket option has taken its place. The option is used with the 3404 following structure: 3406 struct sctp_event { 3407 sctp_assoc_t se_assoc_id; 3408 uint16_t se_type; 3409 uint8_t se_on; 3410 }; 3412 To use this option the user fills in this structure and then calls 3413 the setsockopt to turn on or off an individual event. The following 3414 is an example use of this option: 3416 { 3417 struct sctp_event set; 3419 memset(&set,0,sizeof(set)); 3421 set.se_assoc_id = SCTP_FUTURE_ASSOC; 3422 set.se_type = SCTP_SENDER_DRY_EVENT; 3423 set.se_on = 1; 3424 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event)); 3425 } 3426 The previous example would turn on the sender dry event. The se_type 3427 field can be filled with any value that would show up in the 3428 respective sn_type field (in the sctp_tlv structure of the 3429 notification). The se_on field is set to 1 to turn on an event and 3430 set to 0 to turn off an event. The se_assoc_id field is ignored for 3431 one-to-one style sockets any this field can be a particular 3432 association id or one of the defined constants. 3434 By default both the one-to-one style and one-to-many style socket has 3435 all options off. 3437 8. New Functions 3439 Depending on the system, the following interface can be implemented 3440 as a system call or library function. 3442 8.1. sctp_bindx() 3444 This function allows the user to bind a specific subset of addresses 3445 or, if the SCTP extension described in [RFC5061] is supported, add or 3446 delete specific addresses. 3448 The function prototype is 3450 int sctp_bindx(int sd, 3451 struct sockaddr *addrs, 3452 int addrcnt, 3453 int flags); 3455 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3456 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3457 or IPv6 addresses. 3459 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3460 Section 3.1.2 for this usage. 3462 addrs is a pointer to an array of one or more socket addresses. Each 3463 address is contained in its appropriate structure. For an IPv6 3464 socket, an array of sockaddr_in6 would be returned. For a IPv4 3465 socket, an array of sockaddr_in would be returned. The caller 3466 specifies the number of addresses in the array with addrcnt. Note 3467 that the wildcard addresses cannot be used in combination with non 3468 wildcard addresses on a socket with this function, doing so will 3469 result in an error. 3471 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3472 -1, and sets errno to the appropriate error code. 3474 For SCTP, the port given in each socket address must be the same, or 3475 sctp_bindx() will fail, setting errno to EINVAL. 3477 The flags parameter is formed from the bitwise OR of zero or more of 3478 the following currently defined flags: 3479 o SCTP_BINDX_ADD_ADDR 3480 o SCTP_BINDX_REM_ADDR 3481 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3482 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3483 addresses from the association. The two flags are mutually 3484 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3485 caller may not remove all addresses from an association; sctp_bindx() 3486 will reject such an attempt with EINVAL. 3488 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3489 additional addresses with an endpoint after calling bind(). Or use 3490 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3491 socket is associated with so that no new association accepted will be 3492 associated with those addresses. If the endpoint supports dynamic 3493 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 3494 endpoint to send the appropriate message to the peer to change the 3495 peers address lists. 3497 Adding and removing addresses from a connected association is an 3498 optional functionality. Implementations that do not support this 3499 functionality should return EOPNOTSUPP. 3501 sctp_bindx() can be called on an already bound socket or on an 3502 unbound socket. If the socket is unbound and the first port number 3503 in the addrs is zero, the kernel will chose a port number. All port 3504 numbers after the first one being 0 must also be zero. If the first 3505 port number is not zero, the following port numbers must be zero or 3506 have the same value as the first one. For an already bound socket, 3507 all port numbers provided must be the bound one or 0. 3509 sctp_bindx() is an atomic operation. Therefore the binding will be 3510 either successful on all addresses or fail on all addresses. If 3511 multiple addresses are provided and the sctp_bindx() call fails there 3512 is no indication which address is responsible for the failure. The 3513 only way to get an specific error indication is to call sctp_bindx() 3514 with only one address sequentially. 3516 8.2. sctp_peeloff() 3518 After an association is established on a one-to-many style socket, 3519 the application may wish to branch off the association into a 3520 separate socket/file descriptor. 3522 This is particularly desirable when, for instance, the application 3523 wishes to have a number of sporadic message senders/receivers remain 3524 under the original one-to-many style socket but branch off those 3525 associations carrying high volume data traffic into their own 3526 separate socket descriptors. 3528 The application uses sctp_peeloff() call to branch off an association 3529 into a separate socket (Note the semantics are somewhat changed from 3530 the traditional one-to-one style accept() call). Note that the new 3531 socket is a one-to-one style socket. Thus it will be confined to 3532 operations allowed for a one-to-one style socket. 3534 The function prototype is 3536 int sctp_peeloff(int sd, 3537 sctp_assoc_t assoc_id); 3539 and the arguments are 3540 sd: The original one-to-many style socket descriptor returned from 3541 the socket() system call (see Section 3.1.1). 3542 assoc_id: the specified identifier of the association that is to be 3543 branched off to a separate file descriptor (Note, in a traditional 3544 one-to-one style accept() call, this would be an out parameter, 3545 but for the one-to-many style call, this is an in parameter). 3546 The function returns a non-negative file descriptor representing the 3547 branched-off association, or -1 if an error occurred. The variable 3548 errno is then set appropriately. 3550 8.3. sctp_getpaddrs() 3552 sctp_getpaddrs() returns all peer addresses in an association. 3554 The function protoype is: 3556 int sctp_getpaddrs(int sd, 3557 sctp_assoc_t id, 3558 struct sockaddr **addrs); 3560 On return, addrs will point to an array dynamically allocated 3561 sockaddr structures of the appropriate type for the socket type. The 3562 caller should use sctp_freepaddrs() to free the memory. Note that 3563 the in/out parameter addrs must not be NULL. 3565 If sd is an IPv4 socket, the addresses returned will be all IPv4 3566 addresses. If sd is an IPv6 socket, the addresses returned can be a 3567 mix of IPv4 or IPv6 addresses. 3569 For one-to-many style sockets, id specifies the association to query. 3571 For one-to-one style sockets, id is ignored. 3573 On success, sctp_getpaddrs() returns the number of peer addresses in 3574 the association. If there is no association on this socket, 3575 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3576 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3577 is undefined. 3579 8.4. sctp_freepaddrs() 3581 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 3583 The function prototype is 3585 void sctp_freepaddrs(struct sockaddr *addrs); 3587 and addrs is the array of peer addresses returned by 3588 sctp_getpaddrs(). 3590 8.5. sctp_getladdrs() 3592 sctp_getladdrs() returns all locally bound address(es) on a socket. 3594 The function prototype is 3596 int sctp_getladdrs(int sd, 3597 sctp_assoc_t id, 3598 struct sockaddr **ss); 3600 On return, addrs will point to a dynamically allocated array of 3601 sockaddr structures of the appropriate type for the socket type. The 3602 caller should use sctp_freeladdrs() to free the memory. Note that 3603 the in/out parameter addrs must not be NULL. 3605 If sd is an IPv4 socket, the addresses returned will be all IPv4 3606 addresses. If sd is an IPv6 socket, the addresses returned can be a 3607 mix of IPv4 or IPv6 addresses. 3609 For one-to-many style sockets, id specifies the association to query. 3610 For one-to-one style sockets, id is ignored. 3612 If the id field is set to the value '0' then the locally bound 3613 addresses are returned without regard to any particular association. 3615 On success, sctp_getladdrs() returns the number of local addresses 3616 bound to the socket. If the socket is unbound, sctp_getladdrs() 3617 returns 0, and the value of *addrs is undefined. If an error occurs, 3618 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3620 8.6. sctp_freeladdrs() 3622 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 3624 The function prototype is 3626 void sctp_freeladdrs(struct sockaddr *addrs); 3628 and addrs is the array of peer addresses returned by 3629 sctp_getladdrs(). 3631 8.7. sctp_sendmsg() 3633 An implementation may provide a library function (or possibly system 3634 call) to assist the user with the advanced features of SCTP. 3636 The function prototype is 3638 ssize_t sctp_sendmsg(int sd, 3639 const void *msg, 3640 size_t len, 3641 const struct sockaddr *to, 3642 socklen_t tolen, 3643 uint32_t ppid, 3644 uint32_t flags, 3645 uint16_t stream_no, 3646 uint32_t pr_value, 3647 uint32_t context); 3649 and the arguments are: 3650 sd: The socket descriptor 3651 msg: The message to be sent. 3652 len: Yhe length of the message. 3653 to: The destination address of the message. 3654 tolen: The length of the destination address. 3655 ppid: The same as sinfo_ppid (see Section 5.2.2) 3656 flags: The same as sinfo_flags (see Section 5.2.2) 3657 stream_no: The same as sinfo_stream (see Section 5.2.2) 3658 pr_value: The same as sinfo_pr_value (see Section 5.2.2). 3659 context: The same as sinfo_context (see Section 5.2.2) 3660 The call returns the number of characters sent, or -1 if an error 3661 occurred. The variable errno is then set appropriately. 3663 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 3664 marking is enabled on the socket specified by sd). 3666 Using sctp_sendmsg() on a non-connected one-to-one style socket for 3667 implicit connection setup may or may not work depending on the SCTP 3668 implementation. 3670 8.8. sctp_recvmsg() 3672 An implementation may provide a library function (or possibly system 3673 call) to assist the user with the advanced features of SCTP. Note 3674 that in order for the sctp_sndrcvinfo structure to be filled in by 3675 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3676 the SCTP_EVENTS option. Note that the setting of the 3677 SCTP_USE_EXT_RCVINFO will effect this function as well, causing the 3678 sctp_sndrcvinfo information to be extended. 3680 The function prototype is 3682 ssize_t sctp_recvmsg(int sd, 3683 void *msg, 3684 size_t len, 3685 struct sockaddr *from, 3686 socklen_t *fromlen 3687 struct sctp_sndrcvinfo *sinfo 3688 int *msg_flags); 3690 and the arguments are 3691 sd: The socket descriptor. 3692 msg: The message buffer to be filled. 3693 len: The length of the message buffer. 3694 from: A pointer to a address to be filled with the sender of this 3695 messages address. 3696 fromlen: An in/out parameter describing the from length. 3697 sinfo: A pointer to a sctp_sndrcvinfo structure to be filled upon 3698 receipt of the message. 3699 msg_flags: A pointer to a integer to be filled with any message 3700 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 3701 field. Options for the receive may also be passed into the value 3702 (e.g. MSG_PEEK). On return from the call, the msg_flags value 3703 will be different than what was sent in to the call. If 3704 implemented via a recvmsg() call, the msg_flags should only 3705 contain the value of the flags from the recvmsg() call. 3706 The call returns the number of bytes received, or -1 if an error 3707 occurred. The variable errno is then set appropriately. 3709 8.9. sctp_connectx() 3711 An implementation may provide a library function (or possibly system 3712 call) to assist the user with associating to an endpoint that is 3713 multi-homed. Much like sctp_bindx() this call allows a caller to 3714 specify multiple addresses at which a peer can be reached. The way 3715 the SCTP stack uses the list of addresses to set up the association 3716 is implementation dependent. This function only specifies that the 3717 stack will try to make use of all the addresses in the list when 3718 needed. 3720 Note that the list of addresses passed in is only used for setting up 3721 the association. It does not necessarily equal the set of addresses 3722 the peer uses for the resulting association. If the caller wants to 3723 find out the set of peer addresses, it must use sctp_getpaddrs() to 3724 retrieve them after the association has been set up. 3726 The function prototype is 3728 int sctp_connectx(int sd, 3729 struct sockaddr *addrs, 3730 int addrcnt, 3731 sctp_assoc_t *id); 3733 and the arguments are: 3734 sd: The socket descriptor. 3735 addrs: An (packed) array of addresses. 3736 addrcnt: The number of addresses in the array. 3737 id: An output parameter that if passed in as a non-NULL will return 3738 the association identification for the newly created association 3739 (if successful). 3741 The call returns 0 on success or -1 if an error occurred. The 3742 variable errno is then set appropriately. 3744 8.10. sctp_send() 3746 An implementation may provide another alternative function or system 3747 call to assist an application with the sending of data without the 3748 use of the CMSG header structures. 3750 The function prototype is 3752 ssize_t sctp_send(int sd, 3753 const void *msg, 3754 size_t len, 3755 const struct sctp_sndrcvinfo *sinfo, 3756 int flags); 3758 and the arguments are 3759 sd: The socket descriptor. 3761 msg: The message to be sent. 3762 len: The length of the message. 3763 sinfo: A pointer to a sctp_sndrcvinfo structure used as described in 3764 Section 5.2.2 for a sendmsg call. 3765 flags: The same flags as used by the sendmsg call flags (e.g. 3766 MSG_DONTROUTE). 3767 The call returns the number of bytes sent, or -1 if an error 3768 occurred. The variable errno is then set appropriately. 3770 This function call may also be used to terminate an association using 3771 an association identification by setting the sinfo.sinfo_flags to 3772 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3773 to be terminated. In such a case the len of the message would be 3774 zero. 3776 Using sctp_send() on a non-connected one-to-one style socket for 3777 implicit connection setup may or may not work depending on the SCTP 3778 implementation. 3780 Sending a message using sctp_send() is atomic unless explicit EOR 3781 marking is enabled on the socket specified by sd. 3783 8.11. sctp_sendx() 3785 An implementation may provide another alternative function or system 3786 call to assist an application with the sending of data without the 3787 use of the CMSG header structures that also gives a list of 3788 addresses. The list of addresses is provided for implicit 3789 association setup. In such a case the list of addresses serves the 3790 same purpose as the addresses given in sctp_connectx() (see 3791 Section 8.9). 3793 The function prototype is 3795 ssize_t sctp_sendx(int sd, 3796 const void *msg, 3797 size_t len, 3798 struct sockaddr *addrs, 3799 int addrcnt, 3800 struct sctp_sndrcvinfo *sinfo, 3801 int flags); 3803 and the arguments are: 3804 sd: The socket descriptor. 3806 msg: The message to be sent. 3807 len: The length of the message. 3808 addrs: is an array of addresses. 3809 addrcnt: The number of addresses in the array. 3810 sinfo: A pointer to a sctp_sndrcvinfo structure used as described in 3811 Section 5.2.2 for a sendmsg call. 3812 flags: The same flags as used by the sendmsg call flags (e.g. 3813 MSG_DONTROUTE). 3814 The call returns the number of bytes sent, or -1 if an error 3815 occurred. The variable errno is then set appropriately. 3817 Note that on return from this call the sinfo structure will have 3818 changed in that the sinfo_assoc_id will be filled in with the new 3819 association id. 3821 This function call may also be used to terminate an association using 3822 an association identification by setting the sinfo.sinfo_flags to 3823 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3824 to be terminated. In such a case the len of the message would be 3825 zero. 3827 Sending a message using sctp_send() is atomic unless explicit EOR 3828 marking is enabled on the socket specified by sd. 3830 Using sctp_sendx() on a non-connected one-to-one style socket for 3831 implicit connection setup may or may not work depending on the SCTP 3832 implementation. 3834 8.12. sctp_getaddrlen() 3836 For application binary portability it is sometimes desirable to know 3837 what the kernel thinks is the length of a socket address family. 3839 The function prototype is: 3841 int sctp_getaddrlen(sa_family_t family); 3843 This function, when called with a valid family type returns the 3844 length that the operating system uses in the specified family's 3845 socket address structure. In case of an error, -1 is returned an the 3846 variable errno is then set appropriately. 3848 9. IANA Considerations 3850 This document requires no actions from IANA. 3852 10. Security Considerations 3854 Many TCP and UDP implementations reserve port numbers below 1024 for 3855 privileged users. If the target platform supports privileged users, 3856 the SCTP implementation should restrict the ability to call bind() or 3857 sctp_bindx() on these port numbers to privileged users. 3859 Similarly unprivileged users should not be able to set protocol 3860 parameters which could result in the congestion control algorithm 3861 being more aggressive than permitted on the public Internet. These 3862 parameters are: 3863 o struct sctp_rtoinfo 3865 If an unprivileged user inherits a one-to-many style socket with open 3866 associations on a privileged port, it MAY be permitted to accept new 3867 associations, but it should not be permitted to open new 3868 associations. This could be relevant for the r* family of protocols. 3870 Applications using the one-to-many style sockets and using the 3871 interleave level if 0 are subject to denial of service attacks as 3872 described in Section 7.1.20. 3874 11. Acknowledgments 3876 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 3877 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 3878 early formation of this document. 3880 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 3881 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 3882 Jonathan Leighton, and many others on the TSVWG mailing list for 3883 contributing valuable comments. 3885 A special thanks to Phillip Conrad, for his suggested text, quick and 3886 constructive insights, and most of all his persistent fighting to 3887 keep the interface to SCTP usable for the application programmer. 3889 12. Normative References 3891 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3892 RFC 793, September 1981. 3894 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 3895 August 1980. 3897 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 3898 Functional Specification", RFC 1644, July 1994. 3900 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3901 Requirement Levels", BCP 14, RFC 2119, March 1997. 3903 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 3904 Stevens, "Basic Socket Interface Extensions for IPv6", 3905 RFC 3493, February 2003. 3907 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 3908 "Advanced Sockets Application Program Interface (API) for 3909 IPv6", RFC 3542, May 2003. 3911 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 3912 Conrad, "Stream Control Transmission Protocol (SCTP) 3913 Partial Reliability Extension", RFC 3758, May 2004. 3915 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 3916 "Authenticated Chunks for the Stream Control Transmission 3917 Protocol (SCTP)", RFC 4895, August 2007. 3919 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 3920 RFC 4960, September 2007. 3922 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 3923 Kozuka, "Stream Control Transmission Protocol (SCTP) 3924 Dynamic Address Reconfiguration", RFC 5061, 3925 September 2007. 3927 Appendix A. One-to-One Style Code Example 3929 The following code is a simple implementation of an echo server over 3930 SCTP. The example shows how to use some features of one-to-one style 3931 IPv4 SCTP sockets, including: 3932 o Opening, binding, and listening for new associations on a socket 3933 o Enabling ancillary data 3934 o Enabling notifications 3935 o Using ancillary data with sendmsg() and recvmsg() 3936 o Using MSG_EOR to determine if an entire message has been read 3937 o Handling notifications 3939 #include 3940 #include 3941 #include 3942 #include 3943 #include 3944 #include 3945 #include 3946 #include 3947 #include 3949 #define BUFLEN 100 3951 static void 3952 handle_event(void *buf) 3953 { 3954 struct sctp_assoc_change *sac; 3955 struct sctp_send_failed *ssf; 3956 struct sctp_paddr_change *spc; 3957 struct sctp_remote_error *sre; 3958 union sctp_notification *snp; 3959 char addrbuf[INET6_ADDRSTRLEN]; 3960 const char *ap; 3961 struct sockaddr_in *sin; 3962 struct sockaddr_in6 *sin6; 3964 snp = buf; 3966 switch (snp->sn_header.sn_type) { 3967 case SCTP_ASSOC_CHANGE: 3968 sac = &snp->sn_assoc_change; 3969 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3970 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3971 sac->sac_inbound_streams, sac->sac_outbound_streams); 3972 break; 3973 case SCTP_SEND_FAILED: 3974 ssf = &snp->sn_send_failed; 3975 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3976 ssf->ssf_error); 3977 break; 3979 case SCTP_PEER_ADDR_CHANGE: 3980 spc = &snp->sn_paddr_change; 3981 if (spc->spc_aaddr.ss_family == AF_INET) { 3982 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3983 ap = inet_ntop(AF_INET, &sin->sin_addr, 3984 addrbuf, INET6_ADDRSTRLEN); 3985 } else { 3986 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3987 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3988 addrbuf, INET6_ADDRSTRLEN); 3989 } 3990 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3991 spc->spc_state, spc->spc_error); 3992 break; 3994 case SCTP_REMOTE_ERROR: 3995 sre = &snp->sn_remote_error; 3996 printf("^^^ remote_error: err=%hu len=%hu\n", 3997 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3998 break; 3999 case SCTP_SHUTDOWN_EVENT: 4000 printf("^^^ shutdown event\n"); 4001 break; 4002 default: 4003 printf("unknown type: %hu\n", snp->sn_header.sn_type); 4004 break; 4005 }; 4006 } 4008 static void * 4009 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 4010 ssize_t *nrp, size_t cmsglen) 4011 { 4012 ssize_t nr = 0, nnr = 0; 4013 struct iovec iov[1]; 4015 *nrp = 0; 4016 iov->iov_base = buf; 4017 iov->iov_len = *buflen; 4018 msg->msg_iov = iov; 4019 msg->msg_iovlen = 1; 4021 for (;;) { 4022 #ifndef MSG_XPG4_2 4023 #define MSG_XPG4_2 0 4024 #endif 4025 msg->msg_flags = MSG_XPG4_2; 4026 msg->msg_controllen = cmsglen; 4028 nnr = recvmsg(fd, msg, 0); 4029 if (nnr <= 0) { 4030 /* EOF or error */ 4031 *nrp = nr; 4032 return (NULL); 4033 } 4034 nr += nnr; 4036 if ((msg->msg_flags & MSG_EOR) != 0) { 4037 *nrp = nr; 4038 return (buf); 4039 } 4040 /* Realloc the buffer? */ 4041 if (*buflen == (size_t)nr) { 4042 buf = realloc(buf, *buflen * 2); 4043 if (buf == 0) { 4044 fprintf(stderr, "out of memory\n"); 4045 exit(1); 4046 } 4047 *buflen *= 2; 4048 } 4049 /* Set the next read offset */ 4050 iov->iov_base = (char *)buf + nr; 4051 iov->iov_len = *buflen - nr; 4052 } 4053 } 4055 static void 4056 echo(int fd, int socketModeone_to_many) 4057 { 4058 ssize_t nr; 4059 struct sctp_sndrcvinfo *sri; 4060 struct msghdr msg[1]; 4061 struct cmsghdr *cmsg; 4062 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 4063 char *buf; 4064 size_t buflen; 4065 struct iovec iov[1]; 4066 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 4067 /* Allocate the initial data buffer */ 4068 buflen = BUFLEN; 4069 if (!(buf = malloc(BUFLEN))) { 4070 fprintf(stderr, "out of memory\n"); 4071 exit(1); 4072 } 4074 /* Set up the msghdr structure for receiving */ 4075 memset(msg, 0, sizeof (*msg)); 4076 msg->msg_control = cbuf; 4077 msg->msg_controllen = cmsglen; 4078 msg->msg_flags = 0; 4079 cmsg = (struct cmsghdr *)cbuf; 4080 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 4082 /* Wait for something to echo */ 4083 while (buf = mysctp_recvmsg(fd, msg, 4084 buf, &buflen, &nr, cmsglen)) { 4086 /* Intercept notifications here */ 4087 if (msg->msg_flags & MSG_NOTIFICATION) { 4088 handle_event(buf); 4089 continue; 4090 } 4092 iov->iov_base = buf; 4093 iov->iov_len = nr; 4094 msg->msg_iov = iov; 4095 msg->msg_iovlen = 1; 4097 printf("got %u bytes on stream %hu:\n", nr, 4098 sri->sinfo_stream); 4099 write(0, buf, nr); 4101 /* Echo it back */ 4102 msg->msg_flags = MSG_XPG4_2; 4103 if (sendmsg(fd, msg, 0) < 0) { 4104 perror("sendmsg"); 4105 exit(1); 4106 } 4107 } 4109 if (nr < 0) { 4110 perror("recvmsg"); 4111 } 4112 if(socketModeone_to_many == 0) 4113 close(fd); 4114 } 4116 int main() 4117 { 4118 struct sctp_event_subscribe event; 4119 int lfd, cfd; 4120 int onoff = 1; 4121 struct sockaddr_in sin[1]; 4122 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 4123 perror("socket"); 4124 exit(1); 4125 } 4127 sin->sin_family = AF_INET; 4128 sin->sin_port = htons(7); 4129 sin->sin_addr.s_addr = INADDR_ANY; 4130 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 4131 perror("bind"); 4132 exit(1); 4133 } 4135 if (listen(lfd, 1) == -1) { 4136 perror("listen"); 4137 exit(1); 4138 } 4140 /* Wait for new associations */ 4141 for (;;) { 4142 if ((cfd = accept(lfd, NULL, 0)) == -1) { 4143 perror("accept"); 4144 exit(1); 4145 } 4147 /* Enable all events */ 4148 event.sctp_data_io_event = 1; 4149 event.sctp_association_event = 1; 4150 event.sctp_address_event = 1; 4151 event.sctp_send_failure_event = 1; 4152 event.sctp_peer_error_event = 1; 4153 event.sctp_shutdown_event = 1; 4154 event.sctp_partial_delivery_event = 1; 4155 event.sctp_adaptation_layer_event = 1; 4156 if (setsockopt(cfd, IPPROTO_SCTP, 4157 SCTP_EVENTS, &event, 4158 sizeof(event)) != 0) { 4159 perror("setevent failed"); 4160 exit(1); 4161 } 4162 /* Echo back any and all data */ 4163 echo(cfd,0); 4164 } 4165 } 4167 Appendix B. One-to-Many Style Code Example 4169 The following code is a simple implementation of an echo server over 4170 SCTP. The example shows how to use some features of one-to-many 4171 style IPv4 SCTP sockets, including: 4172 o Opening and binding of a socket 4173 o Enabling ancillary data 4174 o Enabling notifications 4175 o Using ancillary data with sendmsg() and recvmsg() 4176 o Using MSG_EOR to determine if an entire message has been read 4177 o Handling notifications 4179 Note most functions defined in Appendix A are reused in this example. 4181 int main() 4182 { 4183 int fd; 4184 int idleTime = 2; 4185 struct sockaddr_in sin[1]; 4186 struct sctp_event_subscribe event; 4188 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 4189 perror("socket"); 4190 exit(1); 4191 } 4193 sin->sin_family = AF_INET; 4194 sin->sin_port = htons(7); 4195 sin->sin_addr.s_addr = INADDR_ANY; 4196 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 4197 perror("bind"); 4198 exit(1); 4199 } 4201 /* Enable all notifications and events */ 4202 event.sctp_data_io_event = 1; 4203 event.sctp_association_event = 1; 4204 event.sctp_address_event = 1; 4205 event.sctp_send_failure_event = 1; 4206 event.sctp_peer_error_event = 1; 4207 event.sctp_shutdown_event = 1; 4208 event.sctp_partial_delivery_event = 1; 4209 event.sctp_adaptation_layer_event = 1; 4210 if (setsockopt(fd, IPPROTO_SCTP, 4211 SCTP_EVENTS, &event, 4212 sizeof(event)) != 0) { 4213 perror("setevent failed"); 4214 exit(1); 4215 } 4216 /* Set associations to auto-close in 2 seconds of 4217 * inactivity 4218 */ 4219 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 4220 &idleTime, 4) < 0) { 4221 perror("setsockopt SCTP_AUTOCLOSE"); 4222 exit(1); 4223 } 4225 /* Allow new associations to be accepted */ 4226 if (listen(fd, 1) < 0) { 4227 perror("listen"); 4228 exit(1); 4229 } 4230 /* Wait for new associations */ 4231 while(1){ 4232 /* Echo back any and all data */ 4233 echo(fd,1); /* from appendix a */ 4234 } 4235 } 4237 Authors' Addresses 4239 Randall R. Stewart 4240 Huawei 4241 Chapin, SC 29036 4242 USA 4244 Email: rstewart@huawei.com 4246 Kacheong Poon 4247 Sun Microsystems, Inc. 4248 4150 Network Circle 4249 Santa Clara, CA 95054 4250 USA 4252 Email: kacheong.poon@sun.com 4254 Michael Tuexen 4255 Univ. of Applied Sciences Muenster 4256 Stegerwaldstr. 39 4257 48565 Steinfurt 4258 Germany 4260 Email: tuexen@fh-muenster.de 4262 Vladislav Yasevich 4263 HP 4264 110 Spitrook Rd 4265 Nashua, NH, 03062 4266 USA 4268 Email: vladislav.yasevich@hp.com 4269 Peter Lei 4270 Cisco Systems, Inc. 4271 8735 West Higgins Road 4272 Suite 300 4273 Chicago, IL 60631 4274 USA 4276 Email: peterlei@cisco.com