idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-32.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 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 (October 11, 2011) is 4552 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 ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 1644 (Obsoleted by RFC 6247) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Adara Networks 4 Intended status: Informational M. Tuexen 5 Expires: April 13, 2012 Muenster Univ. of Appl. Sciences 6 K. Poon 7 Oracle Corporation 8 P. Lei 9 Cisco Systems, Inc. 10 V. Yasevich 11 HP 12 October 11, 2011 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-32.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 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). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 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 This Internet-Draft will expire on April 13, 2012. 41 Copyright Notice 43 Copyright (c) 2011 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 This document may contain material from IETF Documents or IETF 57 Contributions published or made publicly available before November 58 10, 2008. The person(s) controlling the copyright in some of this 59 material may not have granted the IETF Trust the right to allow 60 modifications of such material outside the IETF Standards Process. 61 Without obtaining an adequate license from the person(s) controlling 62 the copyright in such materials, this document may not be modified 63 outside the IETF Standards Process, and derivative works of it may 64 not be created outside the IETF Standards Process, except to format 65 it for publication as an RFC or to translate it into languages other 66 than English. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 71 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8 73 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8 74 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 10 75 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 10 76 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 12 77 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 12 78 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 14 79 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 15 80 3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 16 81 3.3. Special considerations . . . . . . . . . . . . . . . . . 17 82 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . 18 83 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 18 84 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 19 85 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 20 86 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 21 87 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . 21 88 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 22 89 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 23 90 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . 23 91 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 24 92 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 25 93 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 25 94 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 25 95 5.2. Ancillary Data Considerations and Semantics . . . . . . . 26 96 5.2.1. Multiple Items and Ordering . . . . . . . . . . . . . 26 97 5.2.2. Accessing and Manipulating Ancillary Data . . . . . . 27 98 5.2.3. Control Message Buffer Sizing . . . . . . . . . . . . 27 99 5.3. SCTP msg_control Structures . . . . . . . . . . . . . . . 28 100 5.3.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 29 101 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - 102 DEPRECATED . . . . . . . . . . . . . . . . . . . . . 30 103 5.3.3. Extended SCTP Header Information Structure 104 (SCTP_EXTRCV) - DEPRECATED . . . . . . . . . . . . . 33 105 5.3.4. SCTP Send Information Structure (SCTP_SNDINFO) . . . 34 106 5.3.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 36 107 5.3.6. SCTP Next Receive Information Structure 108 (SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . 37 109 5.3.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . 39 110 5.3.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) . . . 39 111 5.3.9. SCTP Destination IPv4 Address Structure 112 (SCTP_DSTADDRV4) . . . . . . . . . . . . . . . . . . 40 113 5.3.10. SCTP Destination IPv6 Address Structure 114 (SCTP_DSTADDRV6) . . . . . . . . . . . . . . . . . . 40 115 6. SCTP Events and Notifications . . . . . . . . . . . . . . . . 40 116 6.1. SCTP Notification Structure . . . . . . . . . . . . . . . 41 117 6.1.1. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 43 118 6.1.2. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 44 119 6.1.3. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 46 120 6.1.4. SCTP_SEND_FAILED - DEPRECATED . . . . . . . . . . . . 46 121 6.1.5. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 48 122 6.1.6. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . 48 123 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 49 124 6.1.8. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 50 125 6.1.9. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 51 126 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . 51 127 6.1.11. SCTP_SEND_FAILED_EVENT . . . . . . . . . . . . . . . 52 128 6.2. Notification Interest Options . . . . . . . . . . . . . . 53 129 6.2.1. SCTP_EVENTS option - DEPRECATED . . . . . . . . . . . 53 130 6.2.2. SCTP_EVENT option . . . . . . . . . . . . . . . . . . 55 131 7. Common Operations for Both Styles . . . . . . . . . . . . . . 56 132 7.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . 56 133 7.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 58 134 7.3. read() and write() . . . . . . . . . . . . . . . . . . . 60 135 7.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 60 136 7.5. Implicit Association Setup . . . . . . . . . . . . . . . 60 137 8. Socket Options . . . . . . . . . . . . . . . . . . . . . . . 61 138 8.1. Read / Write Options . . . . . . . . . . . . . . . . . . 63 139 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . 63 140 8.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 64 141 8.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . 65 142 8.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 66 143 8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . 66 144 8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 67 145 8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 67 146 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . 67 147 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 68 148 8.1.10. Set Adaptation Layer Indicator 149 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 68 150 8.1.11. Enable/Disable Message Fragmentation 151 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . 68 152 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 69 153 8.1.13. Set Default Send Parameters 154 (SCTP_DEFAULT_SEND_PARAM) - DEPRECATED . . . . . . . 71 155 8.1.14. Set Notification and Ancillary Events 156 (SCTP_EVENTS) - DEPRECATED . . . . . . . . . . . . . 72 157 8.1.15. Set/Clear IPv4 Mapped Addresses 158 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . 72 159 8.1.16. Get or Set the Maximum Fragmentation Size 160 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 72 161 8.1.17. Get or Set the List of Supported HMAC Identifiers 162 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 73 163 8.1.18. Get or Set the Active Shared Key 164 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . 73 165 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 74 166 8.1.20. Get or Set Fragmented Interleave 167 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . 75 168 8.1.21. Set or Get the SCTP Partial Delivery Point 169 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 76 170 8.1.22. Set or Get the Use of Extended Receive Info 171 (SCTP_USE_EXT_RCVINFO) - DEPRECATED . . . . . . . . . 77 172 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . 77 173 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 77 174 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 78 175 8.1.26. Enable or Disable Explicit EOR Marking 176 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 78 177 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . 79 178 8.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 79 179 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as 180 Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 79 181 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as 182 Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 79 183 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . 80 184 8.1.32. Set Default PR-SCTP Parameters 185 (SCTP_DEFAULT_PRINFO) . . . . . . . . . . . . . . . . 80 186 8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 80 187 8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . 80 188 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . 82 189 8.2.3. Get the List of Chunks the Peer Requires to be 190 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 83 191 8.2.4. Get the List of Chunks the Local Endpoint Requires 192 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . 84 193 8.2.5. Get the Current Number of Associations 194 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 84 195 8.2.6. Get the Current Identifiers of Associations 196 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . 85 197 8.3. Write-Only Options . . . . . . . . . . . . . . . . . . . 85 198 8.3.1. Set Peer Primary Address 199 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . 85 200 8.3.2. Add a Chunk that must be Authenticated 201 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 86 202 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . 86 203 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . 87 204 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . 87 205 9. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 88 206 9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . 88 207 9.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . 90 208 9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . 90 209 9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 91 210 9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . 91 211 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 92 212 9.7. sctp_sendmsg() - DEPRECATED . . . . . . . . . . . . . . . 92 213 9.8. sctp_recvmsg() - DEPRECATED . . . . . . . . . . . . . . . 93 214 9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 94 215 9.10. sctp_send() - DEPRECATED . . . . . . . . . . . . . . . . 95 216 9.11. sctp_sendx() - DEPRECATED . . . . . . . . . . . . . . . . 96 217 9.12. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 97 218 9.13. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . 100 219 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 102 220 11. Security Considerations . . . . . . . . . . . . . . . . . . . 102 221 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 103 222 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 103 223 13.1. Normative References . . . . . . . . . . . . . . . . . . 103 224 13.2. Informative References . . . . . . . . . . . . . . . . . 104 225 Appendix A. One-to-One Style Code Example . . . . . . . . . . . 104 226 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 107 227 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 112 229 1. Introduction 231 The sockets API has provided a standard mapping of the Internet 232 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 233 [RFC0768] have benefited from this standard representation and access 234 method across many diverse platforms. SCTP is a new protocol that 235 provides many of the characteristics of TCP but also incorporates 236 semantics more akin to UDP. This document defines a method to map 237 the existing sockets API for use with SCTP, providing both a base for 238 access to new features and compatibility so that most existing TCP 239 applications can be migrated to SCTP with few (if any) changes. 241 There are three basic design objectives: 243 1. Maintain consistency with existing sockets APIs: We define a 244 sockets mapping for SCTP that is consistent with other sockets 245 API protocol mappings (for instance UDP, TCP, IPv4, and IPv6). 247 2. Support a one-to-many style interface: This set of semantics is 248 similar to that defined for connection-less protocols, such as 249 UDP. A one-to-many style SCTP socket should be able to control 250 multiple SCTP associations. This is similar to a UDP socket, 251 which can communicate with many peer endpoints. Each of these 252 associations is assigned an association identifier so that an 253 application can use the ID to differentiate them. Note that SCTP 254 is connection-oriented in nature, and it does not support 255 broadcast or multicast communications, as UDP does. 257 3. Support a one-to-one style interface: This interface supports a 258 similar semantics as sockets for connection-oriented protocols, 259 such as TCP. A one-to-one style SCTP socket should only control 260 one SCTP association. One purpose of defining this interface is 261 to allow existing applications built on other connection-oriented 262 protocols to be ported to use SCTP with very little effort. 263 Developers familiar with these semantics can easily adapt to 264 SCTP. Another purpose is to make sure that existing mechanisms 265 in most operating systems that support sockets, such as select(), 266 should continue to work with this style of socket. Extensions 267 are added to this mapping to provide mechanisms to exploit new 268 features of SCTP. 270 Goals 2 and 3 are not compatible, so this document defines two modes 271 of mapping, namely the one-to-many style mapping and the one-to-one 272 style mapping. These two modes share some common data structures and 273 operations, but will require the use of two different application 274 programming styles. Note that all new SCTP features can be used with 275 both styles of socket. The decision on which one to use depends 276 mainly on the nature of applications. 278 A mechanism is defined to extract a one-to-many style SCTP 279 association into a one-to-one style socket. 281 Some of the SCTP mechanisms cannot be adequately mapped to an 282 existing socket interface. In some cases, it is more desirable to 283 have a new interface instead of using existing socket calls. 284 Section 9 of this document describes these new interfaces. 286 Please note that some elements of the SCTP socket API are declared as 287 deprecated. During the evolution of this document, elements of the 288 API were introduced, implemented and later on replaced by other 289 elements. These replaced elements are declared as deprecated since 290 they are still available in some implementations and the replacement 291 functions are not. This applies especially to older versions of 292 operating systems supporting SCTP. New SCTP socket implementations 293 must implement at least the non deprecated elements. Implementations 294 intending interoperability with older versions of the API should also 295 include the deprecated functions. 297 2. Data Types 299 Whenever possible, POSIX data types defined in [IEEE-1003.1-2008] are 300 used: uintN_t means an unsigned integer of exactly N bits (e.g. 301 uint16_t). This document also assumes the argument data types from 302 POSIX when possible (e.g. the final argument to setsockopt() is a 303 socklen_t value). Whenever buffer sizes are specified, the POSIX 304 size_t data type is used. 306 3. One-to-Many Style Interface 308 In the one-to-many style interface there is a 1 to many relationship 309 between sockets and associations. 311 3.1. Basic Operation 313 A typical server in this style uses the following socket calls in 314 sequence to prepare an endpoint for servicing requests: 316 o socket() 318 o bind() 320 o listen() 322 o recvmsg() 323 o sendmsg() 325 o close() 327 A typical client uses the following calls in sequence to setup an 328 association with a server to request services: 330 o socket() 332 o sendmsg() 334 o recvmsg() 336 o close() 338 In this style, by default, all the associations connected to the 339 endpoint are represented with a single socket. Each association is 340 assigned an association identifier (type is sctp_assoc_t) so that an 341 application can use it to differentiate among them. In some 342 implementations, the peer endpoints' addresses can also be used for 343 this purpose. But this is not required for performance reasons. If 344 an implementation does not support using addresses to differentiate 345 between different associations, the sendto() call can only be used to 346 setup an association implicitly. It cannot be used to send data to 347 an established association as the association identifier cannot be 348 specified. 350 Once an association identifier is assigned to an SCTP association, 351 that identifier will not be reused until the application explicitly 352 terminates the use of the association. The resources belonging to 353 that association will not be freed until that happens. This is 354 similar to the close() operation on a normal socket. The only 355 exception is when the SCTP_AUTOCLOSE option (Section 8.1.8) is set. 356 In this case, after the association is terminated gracefully and 357 automatically, the association identifier assigned to it can be 358 reused. All applications using this option should be aware of this 359 to avoid the possible problem of sending data to an incorrect peer 360 endpoint. 362 If the server or client wishes to branch an existing association off 363 to a separate socket, it is required to call sctp_peeloff() and to 364 specify the association identifier. The sctp_peeloff() call will 365 return a new one-to-one style socket which can then be used with 366 recv() and send() functions for message passing. See Section 9.2 for 367 more on branched-off associations. 369 Once an association is branched off to a separate socket, it becomes 370 completely separated from the original socket. All subsequent 371 control and data operations to that association must be done through 372 the new socket. For example, the close operation on the original 373 socket will not terminate any associations that have been branched 374 off to a different socket. 376 One-to-many style socket calls are discussed in more detail in the 377 following subsections. 379 3.1.1. socket() 381 Applications use socket() to create a socket descriptor to represent 382 an SCTP endpoint. 384 The function prototype is 386 int socket(int domain, 387 int type, 388 int protocol); 390 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 391 type and IPPROTO_SCTP as the protocol. 393 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 394 socket. 396 The function returns a socket descriptor or -1 in case of an error. 398 Using the PF_INET domain indicates the creation of an endpoint which 399 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 400 can use both IPv6 and IPv4 addresses. 402 3.1.2. bind() 404 Applications use bind() to specify which local address and port the 405 SCTP endpoint should associate itself with. 407 An SCTP endpoint can be associated with multiple addresses. To do 408 this, sctp_bindx() is introduced in Section 9.1 to help applications 409 do the job of associating multiple addresses. But note that an 410 endpoint can only be associated with one local port. 412 These addresses associated with a socket are the eligible transport 413 addresses for the endpoint to send and receive data. The endpoint 414 will also present these addresses to its peers during the association 415 initialization process, see [RFC4960]. 417 After calling bind(), if the endpoint wishes to accept new 418 associations on the socket, it must call listen() (see 419 Section 3.1.3). 421 The function prototype of bind() is 423 int bind(int sd, 424 struct sockaddr *addr, 425 socklen_t addrlen); 427 and the arguments are 429 sd: The socket descriptor returned by socket(). 431 addr: The address structure (struct sockaddr_in for an IPv4 address 432 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 434 addrlen: The size of the address structure. 436 It returns 0 on success and -1 in case of an error. 438 If sd is an IPv4 socket, the address passed must be an IPv4 address. 439 If the sd is an IPv6 socket, the address passed can either be an IPv4 440 or an IPv6 address. 442 Applications cannot call bind() multiple times to associate multiple 443 addresses to an endpoint. After the first call to bind(), all 444 subsequent calls will return an error. 446 If the IP address part of addr is specified as a wildcard (INADDR_ANY 447 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 448 IPv6 address), the operating system will associate the endpoint with 449 an optimal address set of the available interfaces. If the IPv4 450 sin_port or IPv6 sin6_port is set to 0, the operating system will 451 choose an ephemeral port for the endpoint. 453 If a bind() is not called prior to a sendmsg() call that initiates a 454 new association, the system picks an ephemeral port and will choose 455 an address set equivalent to binding with a wildcard address. One of 456 those addresses will be the primary address for the association. 457 This automatically enables the multi-homing capability of SCTP. 459 The completion of this bind() process does not allow the SCTP 460 endpoint to accept inbound SCTP association requests. Until a 461 listen() system call, described below, is performed on the socket, 462 the SCTP endpoint will promptly reject an inbound SCTP INIT request 463 with an SCTP ABORT. 465 3.1.3. listen() 467 By default, a one-to-many style socket does not accept new 468 association requests. An application uses listen() to mark a socket 469 as being able to accept new associations. 471 The function prototype is 473 int listen(int sd, 474 int backlog); 476 and the arguments are 478 sd: The socket descriptor of the endpoint. 480 backlog: If backlog is non-zero, enable listening, else disable 481 listening. 483 It returns 0 on success and -1 in case of an error. 485 Note that one-to-many style socket consumers do not need to call 486 accept to retrieve new associations. Calling accept() on a one-to- 487 many style socket should return EOPNOTSUPP. Rather, new associations 488 are accepted automatically, and notifications of the new associations 489 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 490 these notifications are enabled). Clients will typically not call 491 listen(), so that they can be assured that only actively initiated 492 associations are possible on the socket. Server or peer-to-peer 493 sockets, on the other hand, will always accept new associations, so a 494 well-written application using server one-to-many style sockets must 495 be prepared to handle new associations from unwanted peers. 497 Also note that the SCTP_ASSOC_CHANGE event provides the association 498 identifier for a new association, so if applications wish to use the 499 association identifier as a parameter to other socket calls, they 500 should ensure that the SCTP_ASSOC_CHANGE event is enabled. 502 3.1.4. sendmsg() and recvmsg() 504 An application uses the sendmsg() and recvmsg() call to transmit data 505 to and receive data from its peer. 507 The function prototypes are 509 ssize_t sendmsg(int sd, 510 const struct msghdr *message, 511 int flags); 513 and 515 ssize_t recvmsg(int sd, 516 struct msghdr *message, 517 int flags); 519 using the arguments: 521 sd: The socket descriptor of the endpoint. 523 message: Pointer to the msghdr structure which contains a single 524 user message and possibly some ancillary data. See Section 5 for 525 complete description of the data structures. 527 flags: No new flags are defined for SCTP at this level. See 528 Section 5 for SCTP specific flags used in the msghdr structure. 530 sendmsg() returns the number of bytes accepted by the kernel or -1 in 531 case of an error. recvmsg() returns the number of bytes received or 532 -1 in case of an error. 534 As described in Section 5, different types of ancillary data can be 535 sent and received along with user data. When sending, the ancillary 536 data is used to specify the sent behavior, such as the SCTP stream 537 number to use. When receiving, the ancillary data is used to 538 describe the received data, such as the SCTP stream sequence number 539 of the message. 541 When sending user data with sendmsg(), the msg_name field in the 542 msghdr structure will be filled with one of the transport addresses 543 of the intended receiver. If there is no existing association 544 between the sender and the intended receiver, the sender's SCTP stack 545 will set up a new association and then send the user data (see 546 Section 7.5 for more on implicit association setup). If sendmsg() is 547 called with no data and there is no existing association, a new one 548 will be established. The SCTP_INIT type ancillary data can be used 549 to change some of the parameters used to set up a new association. 550 If sendmsg() is called with NULL data, and there is no existing 551 association but the SCTP_ABORT or SCTP_EOF flags are set as described 552 in Section 5.3.4, then -1 is returned and errno is set to EINVAL. 553 Sending a message using sendmsg() is atomic unless explicit EOR 554 marking is enabled on the socket specified by sd (see 555 Section 8.1.26). 557 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 558 be delivered if that notification has been enabled, and no more data 559 can be sent to that association. Any attempt to send more data will 560 cause sendmsg() to return with an ESHUTDOWN error. Note that the 561 socket is still open for reading at this point so it is possible to 562 retrieve notifications. 564 When receiving a user message with recvmsg(), the msg_name field in 565 the msghdr structure will be populated with the source transport 566 address of the user data. The caller of recvmsg() can use this 567 address information to determine to which association the received 568 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 569 disabled, applications must use the peer transport address provided 570 in the msg_name field by recvmsg() to perform correlation to an 571 association, since they will not have the association identifier. 573 If all data in a single message has been delivered, MSG_EOR will be 574 set in the msg_flags field of the msghdr structure (see Section 5.1). 576 If the application does not provide enough buffer space to completely 577 receive a data message, MSG_EOR will not be set in msg_flags. 578 Successive reads will consume more of the same message until the 579 entire message has been delivered, and MSG_EOR will be set. 581 If the SCTP stack is running low on buffers, it may partially deliver 582 a message. In this case, MSG_EOR will not be set, and more calls to 583 recvmsg() will be necessary to completely consume the message. Only 584 one message at a time can be partially delivered in any stream. The 585 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 586 what interlacing of messages occurs for both the one-to-one and the 587 one-to-many model sockets. Please consult Section 8.1.20 for further 588 details on message delivery options. 590 3.1.5. close() 592 Applications use close() to perform graceful shutdown (as described 593 in Section 10.1 of [RFC4960]) on all the associations currently 594 represented by a one-to-many style socket. 596 The function prototype is 598 int close(int sd); 600 and the argument is 602 sd: The socket descriptor of the associations to be closed. 604 0 is returned on success and -1 in case of an error. 606 To gracefully shutdown a specific association represented by the one- 607 to-many style socket, an application should use the sendmsg() call, 608 and include the SCTP_EOF flag. A user may optionally terminate an 609 association non-gracefully by sending with the SCTP_ABORT flag set 610 and possibly passing a user specified abort code in the data field. 611 Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data 612 (see Section 5.3.4) in the sendmsg() call. 614 If sd in the close() call is a branched-off socket representing only 615 one association, the shutdown is performed on that association only. 617 3.1.6. connect() 619 An application may use the connect() call in the one-to-many style to 620 initiate an association without sending data. 622 The function prototype is 624 int connect(int sd, 625 const struct sockaddr *nam, 626 socklen_t len); 628 and the arguments are 630 sd: The socket descriptor to have a new association added to. 632 nam: The address structure (struct sockaddr_in for an IPv4 address 633 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 635 len: The size of the address. 637 0 is returned on success and -1 in case of an error. 639 Multiple connect() calls can be made on the same socket to create 640 multiple associations. This is different from the semantics of 641 connect() on a UDP socket. 643 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 644 during the association set up phase. If an application wants to do 645 this, it cannot use the connect() call. Instead, it should use 646 sendto() or sendmsg() to initiate an association. If it uses 647 sendto() and it wants to change the initialization behavior, it needs 648 to use the SCTP_INITMSG socket option before calling sendto(). Or it 649 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 650 association without calling setsockopt(). Note that the implicit 651 setup is supported for the one-to-many style sockets. 653 SCTP does not support half close semantics. This means that unlike 654 T/TCP, MSG_EOF should not be set in the flags parameter when calling 655 sendto() or sendmsg() when the call is used to initiate a connection. 656 MSG_EOF is not an acceptable flag with an SCTP socket. 658 3.2. Non-blocking mode 660 Some SCTP application may wish to avoid being blocked when calling a 661 socket interface function. 663 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 664 one-to-many style socket, an application may set the non-blocking 665 option by a fcntl() (such as O_NONBLOCK). After setting the socket 666 to non-blocking mode, the sendmsg() function returns immediately. 667 The success or failure of sending the data message (with possible 668 SCTP_INITMSG ancillary data) will be signaled by the 669 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or SCTP_CANT_START_ASSOC. 670 If user data could not be sent (due to a SCTP_CANT_START_ASSOC), the 671 sender will also receive an SCTP_SEND_FAILED_EVENT event. Events can 672 be received by the user calling recvmsg(). A server (having called 673 listen()) is also notified of an association up event by the 674 reception of an SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling 675 of recvmsg() and possibly the reception of the first data message. 677 To shutdown the association gracefully, the user must call sendmsg() 678 with no data and with the SCTP_EOF flag set as described in 679 Section 5.3.4. The function returns immediately, and completion of 680 the graceful shutdown is indicated by an SCTP_ASSOC_CHANGE 681 notification of type SHUTDOWN_COMPLETE (see Section 6.1.1). Note 682 that this can also be done using the sctp_sendv() call described in 683 Section 9.12. 685 An application is recommended to use caution when using select() (or 686 poll()) for writing on a one-to-many style socket. The reason being 687 that the interpretation of select on write is implementation 688 specific. Generally a positive return on a select on write would 689 only indicate that one of the associations represented by the one-to- 690 many socket is writable. An application that writes after the 691 select() returns may still block since the association that was 692 writeable is not the destination association of the write call. 693 Likewise select() (or poll()) for reading from a one-to-many socket 694 will only return an indication that one of the associations 695 represented by the socket has data to be read. 697 An application that wishes to know that a particular association is 698 ready for reading or writing should either use the one-to-one style 699 or use the sctp_peeloff() (see Section 9.2) function to separate the 700 association of interest from the one-to-many socket. 702 Note some implementations may have an extended select call such as 703 epoll or kqueue that may escape this limitation and allow a select on 704 a specific association of a one-to-many socket, but this is an 705 implementation specific detail that a portable application cannot 706 depend on. 708 3.3. Special considerations 710 The fact that a one-to-many style socket can provide access to many 711 SCTP associations through a single socket descriptor, has important 712 implications for both application programmers and system programmers 713 implementing this API. A key issue is how buffer space inside the 714 sockets layer is managed. Because this implementation detail 715 directly affects how application programmers must write their code to 716 ensure correct operation and portability, this section provides some 717 guidance to both implementers and application programmers. 719 An important feature that SCTP shares with TCP is flow control. 720 Specifically, a sender may not send data faster than the receiver can 721 consume it. 723 For TCP, flow control is typically provided for in the sockets API as 724 follows. If the reader stops reading, the sender queues messages in 725 the socket layer until the send socket buffer is completely filled. 726 This results in a "stalled connection". Further attempts to write to 727 the socket will block or return the error EAGAIN or EWOULDBLOCK for a 728 non-blocking socket. At some point, either the connection is closed, 729 or the receiver begins to read again freeing space in the output 730 queue. 732 For one-to-one style SCTP sockets (this includes sockets descriptors 733 that were separated from a one-to-many style socket with 734 sctp_peeloff()) the behavior is identical. For one-to-many style 735 SCTP sockets there are multiple associations for a single socket, 736 which makes the situation more complicated. If the implementation 737 uses a single buffer space allocation shared by all associations, a 738 single stalled association can prevent the further sending of data on 739 all associations active on a particular one-to-many style socket. 741 For a blocking socket, it should be clear that a single stalled 742 association can block the entire socket. For this reason, 743 application programmers may want to use non-blocking one-to-many 744 style sockets. The application should at least be able to send 745 messages to the non-stalled associations. 747 But a non-blocking socket is not sufficient if the API implementer 748 has chosen a single shared buffer allocation for the socket. A 749 single stalled association would eventually cause the shared 750 allocation to fill, and it would become impossible to send even to 751 non-stalled associations. 753 The API implementer can solve this problem by providing each 754 association with its own allocation of outbound buffer space. Each 755 association should conceptually have as much buffer space as it would 756 have if it had its own socket. As a bonus, this simplifies the 757 implementation of sctp_peeloff(). 759 To ensure that a given stalled association will not prevent other 760 non-stalled associations from being writable, application programmers 761 should either: 763 o demand that the underlying implementation dedicates independent 764 buffer space reservation to each association (as suggested above), 765 or 767 o verify that their application layer protocol does not permit large 768 amounts of unread data at the receiver (this is true of some 769 request-response protocols, for example), or 771 o use one-to-one style sockets for association which may potentially 772 stall (either from the beginning, or by using sctp_peeloff before 773 sending large amounts of data that may cause a stalled condition). 775 4. One-to-One Style Interface 777 The goal of this style is to follow as closely as possible the 778 current practice of using the sockets interface for a connection 779 oriented protocol, such as TCP. This style enables existing 780 applications using connection oriented protocols to be ported to SCTP 781 with very little effort. 783 One-to-one style sockets can be connected (explicitly or implicitly) 784 at most once, similar to TCP sockets. 786 Note that some new SCTP features and some new SCTP socket options can 787 only be utilized through the use of sendmsg() and recvmsg() calls, 788 see Section 4.1.8. 790 4.1. Basic Operation 792 A typical server in one-to-one style uses the following system call 793 sequence to prepare an SCTP endpoint for servicing requests: 795 o socket() 797 o bind() 799 o listen() 800 o accept() 802 The accept() call blocks until a new association is set up. It 803 returns with a new socket descriptor. The server then uses the new 804 socket descriptor to communicate with the client, using recv() and 805 send() calls to get requests and send back responses. 807 Then it calls 809 o close() 811 to terminate the association. 813 A typical client uses the following system call sequence to setup an 814 association with a server to request services: 816 o socket() 818 o connect() 820 After returning from connect(), the client uses send()/sendmsg() and 821 recv()/recvmsg() calls to send out requests and receive responses 822 from the server. 824 The client calls 826 o close() 828 to terminate this association when done. 830 4.1.1. socket() 832 Applications call socket() to create a socket descriptor to represent 833 an SCTP endpoint. 835 The function prototype is 837 int socket(int domain, 838 int type, 839 int protocol); 841 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 842 type and IPPROTO_SCTP as the protocol. 844 Here, SOCK_STREAM indicates the creation of a one-to-one style 845 socket. 847 Using the PF_INET domain indicates the creation of an endpoint which 848 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 849 can use both IPv6 and IPv4 addresses. 851 4.1.2. bind() 853 Applications use bind() to specify which local address and port the 854 SCTP endpoint should associate itself with. 856 An SCTP endpoint can be associated with multiple addresses. To do 857 this, sctp_bindx() is introduced in Section 9.1 to help applications 858 do the job of associating multiple addresses. But note that an 859 endpoint can only be associated with one local port. 861 These addresses associated with a socket are the eligible transport 862 addresses for the endpoint to send and receive data. The endpoint 863 will also present these addresses to its peers during the association 864 initialization process, see [RFC4960]. 866 The function prototype of bind() is 868 int bind(int sd, 869 struct sockaddr *addr, 870 socklen_t addrlen); 872 and the arguments are 874 sd: The socket descriptor returned by socket(). 876 addr: The address structure (struct sockaddr_in for an IPv4 address 877 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 879 addrlen: The size of the address structure. 881 If sd is an IPv4 socket, the address passed must be an IPv4 address. 882 If sd is an IPv6 socket, the address passed can either be an IPv4 or 883 an IPv6 address. 885 Applications cannot call bind() multiple times to associate multiple 886 addresses to the endpoint. After the first call to bind(), all 887 subsequent calls will return an error. 889 If the IP address part of addr is specified as a wildcard (INADDR_ANY 890 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 891 IPv6 address), the operating system will associate the endpoint with 892 an optimal address set of the available interfaces. If the IPv4 893 sin_port or IPv6 sin6_port is set to 0, the operating system will 894 choose an ephemeral port for the endpoint. 896 If a bind() is not called prior to the connect() call, the system 897 picks an ephemeral port and will choose an address set equivalent to 898 binding with a wildcard address. One of these addresses will be the 899 primary address for the association. This automatically enables the 900 multi-homing capability of SCTP. 902 The completion of this bind() process does not allow the SCTP 903 endpoint to accept inbound SCTP association requests. Until a 904 listen() system call, described below, is performed on the socket, 905 the SCTP endpoint will promptly reject an inbound SCTP INIT request 906 with an SCTP ABORT. 908 4.1.3. listen() 910 Applications use listen() to allow the SCTP endpoint to accept 911 inbound associations. 913 The function prototype is 915 int listen(int sd, 916 int backlog); 918 and the arguments are 920 sd: the socket descriptor of the SCTP endpoint. 922 backlog: this specifies the max number of outstanding associations 923 allowed in the socket's accept queue. These are the associations 924 that have finished the four-way initiation handshake (see Section 925 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 926 of '0' indicates that the caller no longer wishes to receive new 927 associations. 929 It returns 0 on success an -1 in case of an error. 931 4.1.4. accept() 933 Applications use the accept() call to remove an established SCTP 934 association from the accept queue of the endpoint. A new socket 935 descriptor will be returned from accept() to represent the newly 936 formed association. 938 The function prototype is 940 int accept(int sd, 941 struct sockaddr *addr, 942 socklen_t *addrlen); 944 and the arguments are 946 sd: The listening socket descriptor. 948 addr: On return, addr (struct sockaddr_in for an IPv4 address or 949 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 950 contain the primary address of the peer endpoint. 952 addrlen: On return, addrlen will contain the size of addr. 954 The function returns the socket descriptor for the newly formed 955 association on success and -1 in case of an error. 957 4.1.5. connect() 959 Applications use connect() to initiate an association to a peer. 961 The function prototype is 963 int connect(int sd, 964 const struct sockaddr *addr, 965 socklen_t addrlen); 967 and the arguments are 969 sd: The socket descriptor of the endpoint. 971 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 972 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 974 addrlen: The size of the address. 976 It returns 0 on success and -1 on error. 978 This operation corresponds to the ASSOCIATE primitive described in 979 Section 10.1 of [RFC4960]. 981 The number of outbound streams the new association has is stack 982 dependent. Applications can use the SCTP_INITMSG option described in 983 Section 8.1.3 before connecting to change the number of outbound 984 streams. 986 If a bind() is not called prior to the connect() call, the system 987 picks an ephemeral port and will choose an address set equivalent to 988 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 989 respectively. One of the addresses will be the primary address for 990 the association. This automatically enables the multi-homing 991 capability of SCTP. 993 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 994 during the association set up phase. If an application wants to do 995 this, it cannot use the connect() call. Instead, it should use 996 sendto() or sendmsg() to initiate an association. If it uses 997 sendto() and it wants to change the initialization behavior, it needs 998 to use the SCTP_INITMSG socket option before calling sendto(). Or it 999 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 1000 association without calling setsockopt(). Note that the implicit 1001 setup is supported for the one-to-one style sockets. 1003 SCTP does not support half close semantics. This means that unlike 1004 T/TCP, MSG_EOF should not be set in the flags parameter when calling 1005 sendto() or sendmsg() when the call is used to initiate a connection. 1006 MSG_EOF is not an acceptable flag with an SCTP socket. 1008 4.1.6. close() 1010 Applications use close() to gracefully close down an association. 1012 The function prototype is 1014 int close(int sd); 1016 and the argument is 1018 sd: The socket descriptor of the association to be closed. 1020 It returns 0 on success and -1 in case of an error. 1022 After an application calls close() on a socket descriptor, no further 1023 socket operations will succeed on that descriptor. 1025 4.1.7. shutdown() 1027 SCTP differs from TCP in that it does not have half closed semantics. 1028 Hence the shutdown() call for SCTP is an approximation of the TCP 1029 shutdown() call, and solves some different problems. Full TCP- 1030 compatibility is not provided, so developers porting TCP applications 1031 to SCTP may need to recode sections that use shutdown(). (Note that 1032 it is possible to achieve the same results as half close in SCTP 1033 using SCTP streams.) 1035 The function prototype is 1037 int shutdown(int sd, 1038 int how); 1040 and the arguments are 1041 sd: The socket descriptor of the association to be closed. 1043 how: Specifies the type of shutdown. The values are as follows: 1045 SHUT_RD: Disables further receive operations. No SCTP protocol 1046 action is taken. 1048 SHUT_WR: Disables further send operations, and initiates the SCTP 1049 shutdown sequence. 1051 SHUT_RDWR: Disables further send and receive operations and 1052 initiates the SCTP shutdown sequence. 1054 It returns 0 on success and -1 in case of an error. 1056 The major difference between SCTP and TCP shutdown() is that SCTP 1057 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 1058 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 1059 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 1060 the SCTP association while still leaving the socket descriptor open. 1061 This allows the caller to receive back any data which SCTP is unable 1062 to deliver (see Section 6.1.4 for more information) and receive event 1063 notifications. 1065 To perform the ABORT operation described in [RFC4960] Section 10.1, 1066 an application can use the socket option SO_LINGER. It is described 1067 in Section 8.1.4. 1069 4.1.8. sendmsg() and recvmsg() 1071 With a one-to-one style socket, the application can also use 1072 sendmsg() and recvmsg() to transmit data to and receive data from its 1073 peer. The semantics is similar to those used in the one-to-many 1074 style (see Section 3.1.4), with the following differences: 1076 1. When sending, the msg_name field in the msghdr is not used to 1077 specify the intended receiver, rather it is used to indicate a 1078 preferred peer address if the sender wishes to discourage the 1079 stack from sending the message to the primary address of the 1080 receiver. If the socket is connected and the transport address 1081 given is not part of the current association, the data will not 1082 be sent and an SCTP_SEND_FAILED_EVENT event will be delivered to 1083 the application if send failure events are enabled. 1085 2. Using sendmsg() on a non-connected one-to-one style socket for 1086 implicit connection setup may or may not work depending on the 1087 SCTP implementation. 1089 4.1.9. getpeername() 1091 Applications use getpeername() to retrieve the primary socket address 1092 of the peer. This call is for TCP compatibility, and is not multi- 1093 homed. It may not work with one-to-many style sockets depending on 1094 the implementation. See Section 9.3 for a multi-homed style version 1095 of the call. 1097 The function prototype is 1099 int getpeername(int sd, 1100 struct sockaddr *address, 1101 socklen_t *len); 1103 and the arguments are: 1105 sd: The socket descriptor to be queried. 1107 address: On return, the peer primary address is stored in this 1108 buffer. If the socket is an IPv4 socket, the address will be 1109 IPv4. If the socket is an IPv6 socket, the address will be either 1110 an IPv6 or IPv4 address. 1112 len: The caller should set the length of address here. On return, 1113 this is set to the length of the returned address. 1115 It returns 0 on success and -1 in case of an error. 1117 If the actual length of the address is greater than the length of the 1118 supplied sockaddr structure, the stored address will be truncated. 1120 5. Data Structures 1122 This section discusses important data structures which are specific 1123 to SCTP and are used with sendmsg() and recvmsg() calls to control 1124 SCTP endpoint operations and to access ancillary information and 1125 notifications. 1127 5.1. The msghdr and cmsghdr Structures 1129 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1130 well as the ancillary data carried in the structure, is the key for 1131 the application to set and get various control information from the 1132 SCTP endpoint. 1134 The msghdr and the related cmsghdr structures are defined and 1135 discussed in detail in [RFC3542]. They are defined as: 1137 struct msghdr { 1138 void *msg_name; /* ptr to socket address structure */ 1139 socklen_t msg_namelen; /* size of socket address structure */ 1140 struct iovec *msg_iov; /* scatter/gather array */ 1141 int msg_iovlen; /* # elements in msg_iov */ 1142 void *msg_control; /* ancillary data */ 1143 socklen_t msg_controllen; /* ancillary data buffer length */ 1144 int msg_flags; /* flags on received message */ 1145 }; 1147 struct cmsghdr { 1148 socklen_t cmsg_len; /* #bytes, including this header */ 1149 int cmsg_level; /* originating protocol */ 1150 int cmsg_type; /* protocol-specific type */ 1151 /* followed by unsigned char cmsg_data[]; */ 1152 }; 1154 In the msghdr structure, the usage of msg_name has been discussed in 1155 previous sections (see Section 3.1.4 and Section 4.1.8). 1157 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1158 field) are treated by SCTP as a single user message for both 1159 sendmsg() and recvmsg(). 1161 SCTP stack uses the ancillary data (msg_control field) to communicate 1162 the attributes, such as SCTP_RCVINFO, of the message stored in 1163 msg_iov to the socket end point. The different ancillary data types 1164 are described in Section 5.3. 1166 The msg_flags are not used when sending a message with sendmsg(). 1168 If a notification has arrived, recvmsg() will return the notification 1169 in msg_iov field and set MSG_NOTIFICATION flag in msg_flags. If the 1170 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1171 Section 6 for more information about notifications. 1173 If all portions of a data frame or notification have been read, 1174 recvmsg() will return with MSG_EOR set in msg_flags. 1176 5.2. Ancillary Data Considerations and Semantics 1178 Programming with ancillary socket data (msg_control) contains some 1179 subtleties and pitfalls, which are discussed below. 1181 5.2.1. Multiple Items and Ordering 1183 Multiple ancillary data items may be included in any call to 1184 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP, 1185 such as IP level items, or both. 1187 The ordering of ancillary data items (either by SCTP or another 1188 protocol) is not significant and is implementation-dependent, so 1189 applications must not depend on any ordering. 1191 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 1192 correspond to the data in the msghdr's msg_iov member. There can be 1193 only one single such type ancillary data for each sendmsg() or 1194 recvmsg() call. 1196 5.2.2. Accessing and Manipulating Ancillary Data 1198 Applications can infer the presence of data or ancillary data by 1199 examining the msg_iovlen and msg_controllen msghdr members, 1200 respectively. 1202 Implementations may have different padding requirements for ancillary 1203 data, so portable applications should make use of the macros 1204 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1205 [RFC3542] and the SCTP implementation's documentation for more 1206 information. The following is an example, from [RFC3542], 1207 demonstrating the use of these macros to access ancillary data: 1209 struct msghdr msg; 1210 struct cmsghdr *cmsgptr; 1212 /* fill in msg */ 1214 /* call recvmsg() */ 1216 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1217 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1218 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1219 u_char *ptr; 1221 ptr = CMSG_DATA(cmsgptr); 1222 /* process data pointed to by ptr */ 1223 } 1224 } 1226 5.2.3. Control Message Buffer Sizing 1228 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1229 ancillary data will often be fundamental to the correct and sane 1230 operation of the sockets application. This is particularly true of 1231 the one-to-many semantics, but also of the one-to-one semantics. For 1232 example, if an application needs to send and receive data on 1233 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1234 ancillary data is indispensable. 1236 Given that some ancillary data is critical, and that multiple 1237 ancillary data items may appear in any order, applications should be 1238 carefully written to always provide a large enough buffer to contain 1239 all possible ancillary data that can be presented by recvmsg(). If 1240 the buffer is too small, and crucial data is truncated, it may pose a 1241 fatal error condition. 1243 Thus, it is essential that applications be able to deterministically 1244 calculate the maximum required buffer size to pass to recvmsg(). One 1245 constraint imposed on this specification that makes this possible is 1246 that all ancillary data definitions are of a fixed length. One way 1247 to calculate the maximum required buffer size might be to take the 1248 sum the sizes of all enabled ancillary data item structures, as 1249 calculated by CMSG_SPACE. For example, if we enabled 1250 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 1251 and allocate the buffer size as follows: 1253 size_t total; 1254 void *buf; 1256 total = CMSG_SPACE(sizeof(struct sctp_sndrcvinfo)) + 1257 CMSG_SPACE(sizeof(struct in6_pktinfo)); 1259 buf = malloc(total); 1261 We could then use this buffer (buf) for msg_control on each call to 1262 recvmsg() and be assured that we would not lose any ancillary data to 1263 truncation. 1265 5.3. SCTP msg_control Structures 1267 A key element of all SCTP specific socket extensions is the use of 1268 ancillary data to specify and access SCTP specific data via the 1269 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1270 Fine-grained control over initialization and sending parameters are 1271 handled with ancillary data. 1273 Each ancillary data item is proceeded by a struct cmsghdr (see 1274 Section 5.1), which defines the function and purpose of the data 1275 contained in the cmsg_data[] member. 1277 By default on either style socket, SCTP will pass no ancillary data; 1278 Specific ancillary data items can be enabled with socket options 1279 defined for SCTP; see Section 6.2. 1281 Note that all ancillary types are fixed length; see Section 5.2 for 1282 further discussion on this. These data structures use struct 1283 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1284 address format. 1286 Other protocols may also provide ancillary data to the socket layer 1287 consumer. These ancillary data items from other protocols may 1288 intermingle with SCTP data. For example, the IPv6 socket API 1289 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1290 data items. If a socket API consumer enables delivery of both SCTP 1291 and IPv6 ancillary data, they both may appear in the same msg_control 1292 buffer in any order. An application may thus need to handle other 1293 types of ancillary data besides those passed by SCTP. 1295 The sockets application must provide a buffer large enough to 1296 accommodate all ancillary data provided via recvmsg(). If the buffer 1297 is not large enough, the ancillary data will be truncated and the 1298 msghdr's msg_flags will include MSG_CTRUNC. 1300 5.3.1. SCTP Initiation Structure (SCTP_INIT) 1302 This cmsghdr structure provides information for initializing new SCTP 1303 associations with sendmsg(). The SCTP_INITMSG socket option uses 1304 this same data structure. This structure is not used for recvmsg(). 1306 +--------------+-----------+---------------------+ 1307 | cmsg_level | cmsg_type | cmsg_data[] | 1308 +--------------+-----------+---------------------+ 1309 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1310 +--------------+-----------+---------------------+ 1312 The sctp_initmsg structure is defined below: 1314 struct sctp_initmsg { 1315 uint16_t sinit_num_ostreams; 1316 uint16_t sinit_max_instreams; 1317 uint16_t sinit_max_attempts; 1318 uint16_t sinit_max_init_timeo; 1319 }; 1321 sinit_num_ostreams: This is an integer number representing the 1322 number of streams that the application wishes to be able to send 1323 to. This number is confirmed in the SCTP_COMM_UP notification and 1324 must be verified since it is a negotiated number with the remote 1325 endpoint. The default value of 0 indicates to use the endpoint 1326 default value. 1328 sinit_max_instreams: This value represents the maximum number of 1329 inbound streams the application is prepared to support. This 1330 value is bounded by the actual implementation. In other words the 1331 user may be able to support more streams than the Operating 1332 System. In such a case, the Operating System limit overrides the 1333 value requested by the user. The default value of 0 indicates to 1334 use the endpoints default value. 1336 sinit_max_attempts: This integer specifies how many attempts the 1337 SCTP endpoint should make at resending the INIT. This value 1338 overrides the system SCTP 'Max.Init.Retransmits' value. The 1339 default value of 0 indicates to use the endpoints default value. 1340 This is normally set to the system's default 'Max.Init.Retransmit' 1341 value. 1343 sinit_max_init_timeo: This value represents the largest Time-Out or 1344 RTO value (in milliseconds) to use in attempting an INIT. 1345 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1346 upon timeout. For the INIT message this value may override 1347 'RTO.Max'. This value must not influence 'RTO.Max' during data 1348 transmission and is only used to bound the initial setup time. A 1349 default value of 0 indicates to use the endpoints default value. 1350 This is normally set to the system's 'RTO.Max' value (60 seconds). 1352 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - DEPRECATED 1354 This cmsghdr structure specifies SCTP options for sendmsg() and 1355 describes SCTP header information about a received message through 1356 recvmsg(). This structure mixes the send and receive path. 1357 SCTP_SNDINFO described in Section 5.3.4 and SCTP_RCVINFO described in 1358 Section 5.3.5 split this information. These structures should be 1359 used, when possible, since SCTP_SNDRCV is deprecated. 1361 +--------------+-------------+------------------------+ 1362 | cmsg_level | cmsg_type | cmsg_data[] | 1363 +--------------+-------------+------------------------+ 1364 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1365 +--------------+-------------+------------------------+ 1367 The sctp_sndrcvinfo structure is defined below: 1369 struct sctp_sndrcvinfo { 1370 uint16_t sinfo_stream; 1371 uint16_t sinfo_ssn; 1372 uint16_t sinfo_flags; 1373 uint32_t sinfo_ppid; 1374 uint32_t sinfo_context; 1375 uint32_t sinfo_timetolive; 1376 uint32_t sinfo_tsn; 1377 uint32_t sinfo_cumtsn; 1378 sctp_assoc_t sinfo_assoc_id; 1379 }; 1381 sinfo_stream: For recvmsg() the SCTP stack places the message's 1382 stream number in this value. For sendmsg() this value holds the 1383 stream number that the application wishes to send this message to. 1384 If a sender specifies an invalid stream number an error indication 1385 is returned and the call fails. 1387 sinfo_ssn: For recvmsg() this value contains the stream sequence 1388 number that the remote endpoint placed in the DATA chunk. For 1389 fragmented messages this is the same number for all deliveries of 1390 the message (if more than one recvmsg() is needed to read the 1391 message). The sendmsg() call will ignore this parameter. 1393 sinfo_flags: This field may contain any of the following flags and 1394 is composed of a bitwise OR of these values. 1396 recvmsg() flags: 1398 SCTP_UNORDERED: This flag is present when the message was sent 1399 un-ordered. 1401 sendmsg() flags: 1403 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1404 the message. If this flag is clear the datagram is 1405 considered an ordered send. 1407 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1408 the SCTP stack to override the primary destination address 1409 with the address found with the sendto/sendmsg call. 1411 SCTP_ABORT: Setting this flag causes the specified association 1412 to abort by sending an ABORT message to the peer. The ABORT 1413 chunk will contain an error cause 'User Initiated Abort' 1414 with cause code 12. The cause specific information of this 1415 error cause is provided in msg_iov. 1417 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1418 procedure on the specified association. Graceful shutdown 1419 assures that all data queued by both endpoints is 1420 successfully transmitted before closing the association. 1422 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1423 model socket to send the message to all associations that 1424 are currently established on this socket. For the one-to- 1425 one socket, this flag has no effect. 1427 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1428 passed to the remote end in each user message. In recvmsg() this 1429 value is the same information that was passed by the upper layer 1430 in the peer application. Please note that the SCTP stack performs 1431 no byte order modification of this field. For example, if the 1432 DATA chunk has to contain a given value in network byte order, the 1433 SCTP user has to perform the htonl() computation. 1435 sinfo_context: This value is an opaque 32 bit context datum that is 1436 used in the sendmsg() function. This value is passed back to the 1437 upper layer if an error occurs on the send of a message and is 1438 retrieved with each undelivered message. 1440 sinfo_timetolive: For the sending side, this field contains the 1441 message time to live in milliseconds. The sending side will 1442 expire the message within the specified time period if the message 1443 as not been sent to the peer within this time period. This value 1444 will override any default value set using any socket option. Also 1445 note that the value of 0 is special in that it indicates no 1446 timeout should occur on this message. 1448 sinfo_tsn: For the receiving side, this field holds a TSN that was 1449 assigned to one of the SCTP Data Chunks. For the sending side it 1450 is ignored. 1452 sinfo_cumtsn: This field will hold the current cumulative TSN as 1453 known by the underlying SCTP layer. Note this field is ignored 1454 when sending. 1456 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1457 the identifier for the association announced in the SCTP_COMM_UP 1458 notification. All notifications for a given association have the 1459 same identifier. Ignored for one-to-one style sockets. 1461 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1463 5.3.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) - 1464 DEPRECATED 1466 This cmsghdr structure specifies SCTP options for SCTP header 1467 information about a received message via recvmsg(). Note that this 1468 structure is an extended version of SCTP_SNDRCV (see Section 5.3.2) 1469 and will only be received if the user has set the socket option 1470 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1471 needed to receive ancillary data. See Section 8.1.22 on this socket 1472 option. Note that next message data is not valid unless the current 1473 message is completely read, i.e. the MSG_EOR is set, in other words 1474 if the application has more data to read from the current message 1475 then no next message information will be available. 1477 SCTP_NXTINFO described in Section 5.3.6 should be used when possible, 1478 since SCTP_EXTRCV is considered deprecated. 1480 +--------------+-------------+------------------------+ 1481 | cmsg_level | cmsg_type | cmsg_data[] | 1482 +--------------+-------------+------------------------+ 1483 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1484 +--------------+-------------+------------------------+ 1486 The sctp_extrcvinfo structure is defined below: 1488 struct sctp_extrcvinfo { 1489 uint16_t sinfo_stream; 1490 uint16_t sinfo_ssn; 1491 uint16_t sinfo_flags; 1492 uint32_t sinfo_ppid; 1493 uint32_t sinfo_context; 1494 uint32_t sinfo_pr_value; 1495 uint32_t sinfo_tsn; 1496 uint32_t sinfo_cumtsn; 1497 uint16_t serinfo_next_flags; 1498 uint16_t serinfo_next_stream; 1499 uint32_t serinfo_next_aid; 1500 uint32_t serinfo_next_length; 1501 uint32_t serinfo_next_ppid; 1502 sctp_assoc_t sinfo_assoc_id; 1503 }; 1505 sinfo_*: Please see Section 5.3.2 for the details for these fields. 1507 serinfo_next_flags: This bitmask will hold one or more of the 1508 following values: 1510 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1511 message information is available i.e.: next_stream, 1512 next_asocid, next_length and next_ppid fields all have valid 1513 values. If this bit is set to 0, then these fields are not 1514 valid and should be ignored. 1516 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1517 next message is completely in the receive buffer. The 1518 next_length field thus contains the entire message size. If 1519 this flag is set to 0, then the next_length field only contains 1520 part of the message size since the message is still being 1521 received (it is being partially delivered). 1523 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1524 the next message to be received was sent by the peer as 1525 unordered. If this bit is not set (i.e. the bit is 0) the next 1526 message to be read is an ordered message in the stream 1527 specified. 1529 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1530 the next message to be received is not a message from the peer, 1531 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1533 serinfo_next_stream: This value, when valid (see 1534 serinfo_next_flags), contains the next stream number that will be 1535 received on a subsequent call to one of the receive message 1536 functions. 1538 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1539 contains the next association identifier that will be received on 1540 a subsequent call to one of the receive message functions. 1542 serinfo_next_length: This value, when valid (see 1543 serinfo_next_flags), contains the length of the next message that 1544 will be received on a subsequent call to one of the receive 1545 message functions. Note that this length may be a partial length 1546 depending on the settings of next_flags. 1548 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1549 contains the ppid of the next message that will be received on a 1550 subsequent call to one of the receive message functions. 1552 5.3.4. SCTP Send Information Structure (SCTP_SNDINFO) 1554 This cmsghdr structure specifies SCTP options for sendmsg(). 1556 +--------------+--------------+---------------------+ 1557 | cmsg_level | cmsg_type | cmsg_data[] | 1558 +--------------+--------------+---------------------+ 1559 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1560 +--------------+--------------+---------------------+ 1562 The sctp_sndinfo structure is defined below: 1564 struct sctp_sndinfo { 1565 uint16_t snd_sid; 1566 uint16_t snd_flags; 1567 uint32_t snd_ppid; 1568 uint32_t snd_context; 1569 sctp_assoc_t snd_assoc_id; 1570 }; 1572 snd_sid: This value holds the stream number that the application 1573 wishes to send this message to. If a sender specifies an invalid 1574 stream number an error indication is returned and the call fails. 1576 snd_flags: This field may contain any of the following flags and is 1577 composed of a bitwise OR of these values. 1579 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1580 message. If this flag is clear the datagram is considered an 1581 ordered send. 1583 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1584 SCTP stack to override the primary destination address with the 1585 address found with the sendto()/sendmsg call. 1587 SCTP_ABORT: Setting this flag causes the specified association to 1588 abort by sending an ABORT message to the peer. The ABORT chunk 1589 will contain an error cause 'User Initiated Abort' with cause 1590 code 12. The cause specific information of this error cause is 1591 provided in msg_iov. 1593 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1594 procedures on the specified association. Graceful shutdown 1595 assures that all data queued by both endpoints is successfully 1596 transmitted before closing the association. 1598 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1599 socket to send the message to all associations that are 1600 currently established on this socket. For the one-to-one 1601 socket, this flag has no effect. 1603 snd_ppid: This value in sendmsg() is an unsigned integer that is 1604 passed to the remote end in each user message. Please note that 1605 the SCTP stack performs no byte order modification of this field. 1606 For example, if the DATA chunk has to contain a given value in 1607 network byte order, the SCTP user has to perform the htonl() 1608 computation. 1610 snd_context: This value is an opaque 32 bit context datum that is 1611 used in the sendmsg() function. This value is passed back to the 1612 upper layer if an error occurs on the send of a message and is 1613 retrieved with each undelivered message. 1615 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1616 the identifier for the association announced in the SCTP_COMM_UP 1617 notification. All notifications for a given association have the 1618 same identifier. Ignored for one-to-one style sockets. 1620 An sctp_sndinfo item always corresponds to the data in msg_iov. 1622 5.3.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1624 This cmsghdr structure describes SCTP receive information about a 1625 received message through recvmsg(). 1627 To enable the delivery of this information an application must use 1628 the SCTP_RECVRCVINFO socket option (see Section 8.1.29). 1630 +--------------+--------------+---------------------+ 1631 | cmsg_level | cmsg_type | cmsg_data[] | 1632 +--------------+--------------+---------------------+ 1633 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1634 +--------------+--------------+---------------------+ 1636 The sctp_rcvinfo structure is defined below: 1638 struct sctp_rcvinfo { 1639 uint16_t rcv_sid; 1640 uint16_t rcv_ssn; 1641 uint16_t rcv_flags; 1642 uint32_t rcv_ppid; 1643 uint32_t rcv_tsn; 1644 uint32_t rcv_cumtsn; 1645 uint32_t rcv_context; 1646 sctp_assoc_t rcv_assoc_id; 1647 }; 1648 rcv_sid: The SCTP stack places the message's stream number in this 1649 value. 1651 rcv_ssn: This value contains the stream sequence number that the 1652 remote endpoint placed in the DATA chunk. For fragmented messages 1653 this is the same number for all deliveries of the message (if more 1654 than one recvmsg() is needed to read the message). 1656 rcv_flags: This field may contain any of the following flags and is 1657 composed of a bitwise OR of these values. 1659 SCTP_UNORDERED: This flag is present when the message was sent 1660 un-ordered. 1662 rcv_ppid: This value is the same information that was passed by the 1663 upper layer in the peer application. Please note that the SCTP 1664 stack performs no byte order modification of this field. For 1665 example, if the DATA chunk has to contain a given value in network 1666 byte order, the SCTP user has to perform the ntohl() computation. 1668 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1669 Data Chunks. 1671 rcv_cumtsn: This field will hold the current cumulative TSN as known 1672 by the underlying SCTP layer. 1674 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1675 the identifier for the association announced in the SCTP_COMM_UP 1676 notification. All notifications for a given association have the 1677 same identifier. Ignored for one-to-one style sockets. 1679 rcv_context: This value is an opaque 32 bit context datum that was 1680 set by the user with the SCTP_CONTEXT socket option. This value 1681 is passed back to the upper layer if an error occurs on the send 1682 of a message and is retrieved with each undelivered message. 1684 An sctp_rcvinfo item always corresponds to the data in msg_iov. 1686 5.3.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1688 This cmsghdr structure describes SCTP receive information of the next 1689 message which will be delivered through recvmsg() if this information 1690 is already available when delivering the current message. 1692 To enable the delivery of this information an application must use 1693 the SCTP_RECVNXTINFO socket option (see Section 8.1.30). 1695 +--------------+--------------+---------------------+ 1696 | cmsg_level | cmsg_type | cmsg_data[] | 1697 +--------------+--------------+---------------------+ 1698 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_nxtinfo | 1699 +--------------+--------------+---------------------+ 1701 The sctp_nxtinfo structure is defined below: 1703 struct sctp_nxtinfo { 1704 uint16_t nxt_sid; 1705 uint16_t nxt_flags; 1706 uint32_t nxt_ppid; 1707 uint32_t nxt_length; 1708 sctp_assoc_t nxt_assoc_id; 1709 }; 1711 nxt_sid: The SCTP stack places the next message's stream number in 1712 this value. 1714 nxt_flags: This field may contain any of the following flags and is 1715 composed of a bitwise OR of these values. 1717 SCTP_UNORDERED: This flag is present when the next message was 1718 sent un-ordered. 1720 SCTP_COMPLETE: This flag indicates that the entire message has 1721 been received and is in the socket buffer. Note that this has 1722 special implications with respect to the nxt_length field, see 1723 nxt_length description below. 1725 SCTP_NOTIFICATION: This flag is present when the next message is 1726 not a user message but instead is a notification. 1728 nxt_ppid: This value is the same information that was passed by the 1729 upper layer in the peer application for the next message. Please 1730 note that the SCTP stack performs no byte order modification of 1731 this field. For example, if the DATA chunk has to contain a given 1732 value in network byte order, the SCTP user has to perform the 1733 ntohl() computation. 1735 nxt_length: This value is the length of the message currently within 1736 the socket buffer. This might NOT be the entire length of the 1737 message since a partial delivery may be in progress. Only if the 1738 flag SCTP_COMPLETE is set in the nxt_flags field does this field 1739 represent the entire next message size. 1741 nxt_assoc_id: The association handle field of the next message, 1742 nxt_assoc_id, holds the identifier for the association announced 1743 in the SCTP_COMM_UP notification. All notifications for a given 1744 association have the same identifier. Ignored for one-to-one 1745 style sockets. 1747 5.3.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1749 This cmsghdr structure specifies SCTP options for sendmsg(). 1751 +--------------+-------------+--------------------+ 1752 | cmsg_level | cmsg_type | cmsg_data[] | 1753 +--------------+-------------+--------------------+ 1754 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1755 +--------------+-------------+--------------------+ 1757 The sctp_prinfo structure is defined below: 1759 struct sctp_prinfo { 1760 uint16_t pr_policy; 1761 uint32_t pr_value; 1762 }; 1764 pr_policy: This specifies which PR-SCTP policy is used. Using 1765 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1766 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1767 defined in [RFC3758] is used. In this case, the lifetime is 1768 provided in pr_value. 1770 pr_value: The meaning of this field depends on the PR-SCTP policy 1771 specified by the pr_policy field. It is ignored when 1772 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1773 lifetime in milliseconds is specified. 1775 An sctp_prinfo item always corresponds to the data in msg_iov. 1777 5.3.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1779 This cmsghdr structure specifies SCTP options for sendmsg(). 1781 +--------------+---------------+----------------------+ 1782 | cmsg_level | cmsg_type | cmsg_data[] | 1783 +--------------+---------------+----------------------+ 1784 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1785 +--------------+---------------+----------------------+ 1787 The sctp_authinfo structure is defined below: 1789 struct sctp_authinfo { 1790 uint16_t auth_keynumber; 1791 }; 1793 auth_keynumber: This specifies the shared key identifier used for 1794 sending the user message. 1796 An sctp_authinfo item always corresponds to the data in msg_iov. 1797 Please note that the SCTP implementation must not bundle user 1798 messages that needs to be authenticated using different shared key 1799 identifiers. 1801 5.3.9. SCTP Destination IPv4 Address Structure (SCTP_DSTADDRV4) 1803 This cmsghdr structure specifies SCTP options for sendmsg(). 1805 +--------------+----------------+----------------+ 1806 | cmsg_level | cmsg_type | cmsg_data[] | 1807 +--------------+----------------+----------------+ 1808 | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | 1809 +--------------+----------------+----------------+ 1811 This ancillary data can be used to provide more than one destination 1812 address to sendmsg(). It can be used to implement sctp_sendv() using 1813 sendmsg(). 1815 5.3.10. SCTP Destination IPv6 Address Structure (SCTP_DSTADDRV6) 1817 This cmsghdr structure specifies SCTP options for sendmsg(). 1819 +--------------+----------------+-----------------+ 1820 | cmsg_level | cmsg_type | cmsg_data[] | 1821 +--------------+----------------+-----------------+ 1822 | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | 1823 +--------------+----------------+-----------------+ 1825 This ancillary data can be used to provide more than one destination 1826 address to sendmsg(). It can be used to implement sctp_sendv() using 1827 sendmsg(). 1829 6. SCTP Events and Notifications 1831 An SCTP application may need to understand and process events and 1832 errors that happen on the SCTP stack. These events include network 1833 status changes, association startups, remote operational errors and 1834 undeliverable messages. All of these can be essential for the 1835 application. 1837 When an SCTP application layer does a recvmsg() the message read is 1838 normally a data message from a peer endpoint. If the application 1839 wishes to have the SCTP stack deliver notifications of non-data 1840 events, it sets the appropriate socket option for the notifications 1841 it wants. See Section 6.2 for these socket options. When a 1842 notification arrives, recvmsg() returns the notification in the 1843 application-supplied data buffer via msg_iov, and sets 1844 MSG_NOTIFICATION in msg_flags. 1846 This section details the notification structures. Every notification 1847 structure carries some common fields which provide general 1848 information. 1850 A recvmsg() call will return only one notification at a time. Just 1851 as when reading normal data, it may return part of a notification if 1852 the msg_iov buffer is not large enough. If a single read is not 1853 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1854 reading the notification before subsequent data can arrive. 1856 6.1. SCTP Notification Structure 1858 The notification structure is defined as the union of all 1859 notification types. 1861 union sctp_notification { 1862 struct sctp_tlv { 1863 uint16_t sn_type; /* Notification type. */ 1864 uint16_t sn_flags; 1865 uint32_t sn_length; 1866 } sn_header; 1867 struct sctp_assoc_change sn_assoc_change; 1868 struct sctp_paddr_change sn_paddr_change; 1869 struct sctp_remote_error sn_remote_error; 1870 struct sctp_send_failed sn_send_failed; 1871 struct sctp_shutdown_event sn_shutdown_event; 1872 struct sctp_adaptation_event sn_adaptation_event; 1873 struct sctp_pdapi_event sn_pdapi_event; 1874 struct sctp_authkey_event sn_auth_event; 1875 struct sctp_sender_dry_event sn_sender_dry_event; 1876 struct sctp_send_failed_event sn_send_failed_event; 1877 }; 1879 sn_type: The following list describes the SCTP notification and 1880 event types for the field sn_type. 1882 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1883 either been opened or closed. Refer to Section 6.1.1 for 1884 details. 1886 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1887 part of an existing association has experienced a change of 1888 state (e.g. a failure or return to service of the reachability 1889 of an endpoint via a specific transport address). Please see 1890 Section 6.1.2 for data structure details. 1892 SCTP_REMOTE_ERROR: The attached error message is an Operational 1893 Error received from the remote peer. It includes the complete 1894 TLV sent by the remote endpoint. See Section 6.1.3 for the 1895 detailed format. 1897 SCTP_SEND_FAILED_EVENT: The attached datagram could not be sent 1898 to the remote endpoint. This structure includes the original 1899 SCTP_SNDINFO that was used in sending this message i.e. this 1900 structure uses the sctp_sndinfo per Section 6.1.11. 1902 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1903 data should be sent on this socket. 1905 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1906 indicated adaptation layer. Please see Section 6.1.6. 1908 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1909 receiver that the partial delivery has been aborted. This may 1910 indicate the association is about to be aborted. Please see 1911 Section 6.1.7. 1913 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1914 receiver that either an error occurred on authentication, or a 1915 new key was made active. See Section 6.1.8. 1917 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1918 application that the sender has no more user data queued for 1919 transmission nor retransmission. See Section 6.1.9. 1921 sn_flags: These are notification-specific flags. 1923 sn_length: This is the length of the whole sctp_notification 1924 structure including the sn_type, sn_flags, and sn_length fields. 1926 6.1.1. SCTP_ASSOC_CHANGE 1928 Communication notifications inform the application that an SCTP 1929 association has either begun or ended. The identifier for a new 1930 association is provided by this notification. The notification 1931 information has the following format: 1933 struct sctp_assoc_change { 1934 uint16_t sac_type; 1935 uint16_t sac_flags; 1936 uint32_t sac_length; 1937 uint16_t sac_state; 1938 uint16_t sac_error; 1939 uint16_t sac_outbound_streams; 1940 uint16_t sac_inbound_streams; 1941 sctp_assoc_t sac_assoc_id; 1942 uint8_t sac_info[]; 1943 }; 1945 sac_type: It should be SCTP_ASSOC_CHANGE. 1947 sac_flags: Currently unused. 1949 sac_length: This field is the total length of the notification data, 1950 including the notification header. 1952 sac_state: This field holds one of a number of values that 1953 communicate the event that happened to the association. They 1954 include: 1956 SCTP_COMM_UP: A new association is now ready and data may be 1957 exchanged with this peer. When an association has been 1958 established successfully, this notification should be the first 1959 one. 1961 SCTP_COMM_LOST: The association has failed. The association is 1962 now in the closed state. If SEND_FAILED notifications are 1963 turned on, an SCTP_COMM_LOST is accompanied by a series of 1964 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1965 message. 1967 SCTP_RESTART: SCTP has detected that the peer has restarted. 1969 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1971 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1972 blocking mode is set and data was sent (on a one-to-many style 1973 socket), an SCTP_CANT_STR_ASSOC is accompanied by a series of 1974 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1975 message. 1977 sac_error: If the state was reached due to an error condition (e.g. 1978 SCTP_COMM_LOST) any relevant error information is available in 1979 this field. This corresponds to the protocol error codes defined 1980 in [RFC4960]. 1982 sac_outbound_streams: 1984 sac_inbound_streams: The maximum number of streams allowed in each 1985 direction are available in sac_outbound_streams and sac_inbound 1986 streams. 1988 sac_assoc_id: The sac_assoc_id field holds the identifier for the 1989 association. All notifications for a given association have the 1990 same association identifier. For a one-to-one style socket, this 1991 field is ignored. 1993 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1994 received for this association, sac_info[] contains the complete 1995 ABORT chunk as defined in the SCTP specification [RFC4960] Section 1996 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1997 may contain an array of uint8_t describing the features that the 1998 current association supports. Features may include 2000 SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol 2001 extension described in [RFC3758]. 2003 SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol 2004 extension described in [RFC4895]. 2006 SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol 2007 extension described in [RFC5061]. 2009 SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the 2010 local endpoints use separate send and/or receive buffers for 2011 each SCTP association. 2013 6.1.2. SCTP_PEER_ADDR_CHANGE 2015 When a destination address of a multi-homed peer encounters a state 2016 change a peer address change event is sent. The notification has the 2017 following format: 2019 struct sctp_paddr_change { 2020 uint16_t spc_type; 2021 uint16_t spc_flags; 2022 uint32_t spc_length; 2023 struct sockaddr_storage spc_aaddr; 2024 uint32_t spc_state; 2025 uint32_t spc_error; 2026 sctp_assoc_t spc_assoc_id; 2027 } 2029 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 2031 spc_flags: Currently unused. 2033 spc_length: This field is the total length of the notification data, 2034 including the notification header. 2036 spc_aaddr: The affected address field holds the remote peer's 2037 address that is encountering the change of state. 2039 spc_state: This field holds one of a number of values that 2040 communicate the event that happened to the address. They include: 2042 SCTP_ADDR_AVAILABLE: This address is now reachable. This 2043 notification is provided whenever an address becomes reachable. 2045 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 2046 reached. Any data sent to this address is rerouted to an 2047 alternate until this address becomes reachable. This 2048 notification is provided whenever an address becomes 2049 unreachable. 2051 SCTP_ADDR_REMOVED: The address is no longer part of the 2052 association. 2054 SCTP_ADDR_ADDED: The address is now part of the association. 2056 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 2057 primary destination address. This notification is provided 2058 whenever an address is made primary. 2060 spc_error: If the state was reached due to any error condition (e.g. 2061 SCTP_ADDR_UNREACHABLE) any relevant error information is available 2062 in this field. 2064 spc_assoc_id: The spc_assoc_id field holds the identifier for the 2065 association. All notifications for a given association have the 2066 same association identifier. For a one-to-one style socket, this 2067 field is ignored. 2069 6.1.3. SCTP_REMOTE_ERROR 2071 A remote peer may send an Operational Error message to its peer. 2072 This message indicates a variety of error conditions on an 2073 association. The entire ERROR chunk as it appears on the wire is 2074 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 2075 specification [RFC4960] and any extensions for a list of possible 2076 error formats. An SCTP error notification has the following format: 2078 struct sctp_remote_error { 2079 uint16_t sre_type; 2080 uint16_t sre_flags; 2081 uint32_t sre_length; 2082 uint16_t sre_error; 2083 sctp_assoc_t sre_assoc_id; 2084 uint8_t sre_data[]; 2085 }; 2087 sre_type: It should be SCTP_REMOTE_ERROR. 2089 sre_flags: Currently unused. 2091 sre_length: This field is the total length of the notification data, 2092 including the notification header and the contents of sre_data. 2094 sre_error: This value represents one of the Operational Error causes 2095 defined in the SCTP specification, in network byte order. 2097 sre_assoc_id: The sre_assoc_id field holds the identifier for the 2098 association. All notifications for a given association have the 2099 same association identifier. For a one-to-one style socket, this 2100 field is ignored. 2102 sre_data: This contains the ERROR chunk as defined in the SCTP 2103 specification [RFC4960] Section 3.3.10. 2105 6.1.4. SCTP_SEND_FAILED - DEPRECATED 2107 Please note that this notification is deprecated. Use 2108 SCTP_SEND_FAILED_EVENT instead. 2110 If SCTP cannot deliver a message, it can return back the message as a 2111 notification if the SCTP_SEND_FAILED event is enabled. The 2112 notification has the following format: 2114 struct sctp_send_failed { 2115 uint16_t ssf_type; 2116 uint16_t ssf_flags; 2117 uint32_t ssf_length; 2118 uint32_t ssf_error; 2119 struct sctp_sndrcvinfo ssf_info; 2120 sctp_assoc_t ssf_assoc_id; 2121 uint8_t ssf_data[]; 2122 }; 2124 ssf_type: It should be SCTP_SEND_FAILED. 2126 ssf_flags: The flag value will take one of the following values: 2128 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2129 wire. 2131 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2132 Note that this does not necessarily mean that the data was (or 2133 was not) successfully delivered. 2135 ssf_length: This field is the total length of the notification data, 2136 including the notification header and the payload in ssf_data. 2138 ssf_error: This value represents the reason why the send failed, and 2139 if set, will be an SCTP protocol error code as defined in 2140 [RFC4960] Section 3.3.10. 2142 ssf_info: The ancillary data (struct sctp_sndrcvinfo) used to send 2143 the undelivered message. Regardless of if ancillary data is used 2144 or not, the ssf_info.sinfo_flags field indicates if the complete 2145 message or only part of the message is returned in ssf_data. If 2146 only part of the message is returned, it means that the part which 2147 is not present has been sent successfully to the peer. 2149 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2150 flags is set in ssf_info.sinfo_flags. If the first part of the 2151 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2152 This means that the tail end of the message is returned in 2153 ssf_data. 2155 ssf_assoc_id: The ssf_assoc_id field, ssf_assoc_id, holds the 2156 identifier for the association. All notifications for a given 2157 association have the same association identifier. For a one-to- 2158 one style socket, this field is ignored. 2160 ssf_data: The undelivered message or part of the undelivered message 2161 will be present in the ssf_data field. Note that the 2162 ssf_info.sinfo_flags field as noted above should be used to 2163 determine if a complete message is present or just a piece of the 2164 message. Note that only user data is present in this field, any 2165 chunk headers or SCTP common headers must be removed by the SCTP 2166 stack. 2168 6.1.5. SCTP_SHUTDOWN_EVENT 2170 When a peer sends a SHUTDOWN, SCTP delivers this notification to 2171 inform the application that it should cease sending data. 2173 struct sctp_shutdown_event { 2174 uint16_t sse_type; 2175 uint16_t sse_flags; 2176 uint32_t sse_length; 2177 sctp_assoc_t sse_assoc_id; 2178 }; 2180 sse_type: It should be SCTP_SHUTDOWN_EVENT. 2182 sse_flags: Currently unused. 2184 sse_length: This field is the total length of the notification data, 2185 including the notification header. It will generally be 2186 sizeof(struct sctp_shutdown_event). 2188 sse_flags: Currently unused. 2190 sse_assoc_id: The sse_assoc_id field holds the identifier for the 2191 association. All notifications for a given association have the 2192 same association identifier. For a one-to-one style socket, this 2193 field is ignored. 2195 6.1.6. SCTP_ADAPTATION_INDICATION 2197 When a peer sends an Adaptation Layer Indication parameter as 2198 described in [RFC5061], SCTP delivers this notification to inform the 2199 application about the peer's adaptation layer indication. 2201 struct sctp_adaptation_event { 2202 uint16_t sai_type; 2203 uint16_t sai_flags; 2204 uint32_t sai_length; 2205 uint32_t sai_adaptation_ind; 2206 sctp_assoc_t sai_assoc_id; 2207 }; 2208 sai_type: It should be SCTP_ADAPTATION_INDICATION. 2210 sai_flags: Currently unused. 2212 sai_length: This field is the total length of the notification data, 2213 including the notification header. It will generally be 2214 sizeof(struct sctp_adaptation_event). 2216 sai_adaptation_ind: This field holds the bit array sent by the peer 2217 in the adaptation layer indication parameter. 2219 sai_assoc_id: The sai_assoc_id field holds the identifier for the 2220 association. All notifications for a given association have the 2221 same association identifier. For a one-to-one style socket, this 2222 field is ignored. 2224 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT 2226 When a receiver is engaged in a partial delivery of a message this 2227 notification will be used to indicate various events. 2229 struct sctp_pdapi_event { 2230 uint16_t pdapi_type; 2231 uint16_t pdapi_flags; 2232 uint32_t pdapi_length; 2233 uint32_t pdapi_indication; 2234 uint32_t pdapi_stream; 2235 uint32_t pdapi_seq; 2236 sctp_assoc_t pdapi_assoc_id; 2237 }; 2239 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 2241 pdapi_flags: Currently unused. 2243 pdapi_length: This field is the total length of the notification 2244 data, including the notification header. It will generally be 2245 sizeof(struct sctp_pdapi_event). 2247 pdapi_indication: This field holds the indication being sent to the 2248 application. Currently there is only one defined value: 2250 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 2251 delivery of a user message has been aborted. This happens, for 2252 example, if an association is aborted while a partial delivery 2253 is going on or the user message gets abandoned using PR-SCTP 2254 while the partial delivery of this message is going on. 2256 pdapi_stream: This field holds the stream on which the partial 2257 delivery event happened. 2259 pdapi_seq: This field holds the stream sequence number which was 2260 being partially delivered. 2262 pdapi_assoc_id: The pdapi_assoc_id field holds the identifier for 2263 the association. All notifications for a given association have 2264 the same association identifier. For a one-to-one style socket 2265 this field is ignored. 2267 6.1.8. SCTP_AUTHENTICATION_EVENT 2269 [RFC4895] defines an extension to authenticate SCTP messages. The 2270 following notification is used to report different events relating to 2271 the use of this extension. 2273 struct sctp_authkey_event { 2274 uint16_t auth_type; 2275 uint16_t auth_flags; 2276 uint32_t auth_length; 2277 uint16_t auth_keynumber; 2278 uint32_t auth_indication; 2279 sctp_assoc_t auth_assoc_id; 2280 }; 2282 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 2284 auth_flags: Currently unused. 2286 auth_length: This field is the total length of the notification 2287 data, including the notification header. It will generally be 2288 sizeof(struct sctp_authkey_event). 2290 auth_keynumber: This field holds the keynumber for the affected key 2291 indicated in the event (depends on auth_indication). 2293 auth_indication: This field holds the error or indication being 2294 reported. The following values are currently defined: 2296 SCTP_AUTH_NEW_KEY: This report indicates that a new key has been 2297 made active (used for the first time by the peer) and is now 2298 the active key. The auth_keynumber field holds the user 2299 specified key number. 2301 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 2302 support SCTP AUTH as defined in [RFC4895]. 2304 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 2305 implementation will no longer use the key identifier specified 2306 in auth_keynumber. 2308 auth_assoc_id: The auth_assoc_id field holds the identifier for the 2309 association. All notifications for a given association have the 2310 same association identifier. For a one-to-one style socket this 2311 field is ignored. 2313 6.1.9. SCTP_SENDER_DRY_EVENT 2315 When the SCTP stack has no more user data to send or retransmit, this 2316 notification is given to the user. Also, at the time when a user app 2317 subscribes to this event, if there is no data to be sent or 2318 retransmit, the stack will immediately send up this notification. 2320 struct sctp_sender_dry_event { 2321 uint16_t sender_dry_type; 2322 uint16_t sender_dry_flags; 2323 uint32_t sender_dry_length; 2324 sctp_assoc_t sender_dry_assoc_id; 2325 }; 2327 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 2329 sender_dry_flags: Currently unused. 2331 sender_dry_length: This field is the total length of the 2332 notification data, including the notification header. It will 2333 generally be sizeof(struct sctp_sender_dry_event). 2335 sender_dry_assoc_id: The sender_dry_assoc_id field holds the 2336 identifier for the association. All notifications for a given 2337 association have the same association identifier. For a one-to- 2338 one style socket this field is ignored. 2340 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT 2342 SCTP notifications, when subscribed to, are reliable. They are 2343 always delivered as long as there is space in the socket receive 2344 buffer. However, if an implementation experiences a notification 2345 storm, it may run out of socket buffer space. When this occurs it 2346 may wish to disable notifications. If the implementation chooses to 2347 do this, it will append a final notification 2348 SCTP_NOTIFICATIONS_STOPPED_EVENT. This notification is a union 2349 sctp_notification, where only the struct sctp_tlv (see the union 2350 above) is used. It only contains this type in the sn_type field, the 2351 sn_length field set to the size of an sctp_tlv structure and the 2352 sn_flags set to 0. If an application receives this notification, it 2353 will need to re-subscribe to any notifications of interest to it, 2354 except for the sctp_data_io_event (note that SCTP_EVENTS is 2355 deprecated). 2357 An endpoint is automatically subscribed to this event as soon as it 2358 is subscribed to any event other than data io events. 2360 6.1.11. SCTP_SEND_FAILED_EVENT 2362 If SCTP cannot deliver a message, it can return back the message as a 2363 notification if the SCTP_SEND_FAILED_EVENT event is enabled. The 2364 notification has the following format: 2366 struct sctp_send_failed_event { 2367 uint16_t ssfe_type; 2368 uint16_t ssfe_flags; 2369 uint32_t ssfe_length; 2370 uint32_t ssfe_error; 2371 struct sctp_sndinfo ssfe_info; 2372 sctp_assoc_t ssfe_assoc_id; 2373 uint8_t ssfe_data[]; 2374 }; 2376 ssfe_type: It should be SCTP_SEND_FAILED_EVENT. 2378 ssfe_flags: The flag value will take one of the following values: 2380 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2381 wire. 2383 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2384 Note that this does not necessarily mean that the data was (or 2385 was not) successfully delivered. 2387 ssfe_length: This field is the total length of the notification 2388 data, including the notification header and the payload in 2389 ssf_data. 2391 ssfe_error: This value represents the reason why the send failed, 2392 and if set, will be an SCTP protocol error code as defined in 2393 [RFC4960] Section 3.3.10. 2395 ssfe_info: The ancillary data (struct sctp_sndinfo) used to send the 2396 undelivered message. Regardless of if ancillary data is used or 2397 not, the ssfe_info.sinfo_flags field indicates if the complete 2398 message or only part of the message is returned in ssf_data. If 2399 only part of the message is returned, it means that the part which 2400 is not present has been sent successfully to the peer. 2402 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2403 flags is set in ssfe_info.sinfo_flags. If the first part of the 2404 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2405 This means that the tail end of the message is returned in 2406 ssf_data. 2408 ssfe_assoc_id: The ssfe_assoc_id field, ssf_assoc_id, holds the 2409 identifier for the association. All notifications for a given 2410 association have the same association identifier. For a one-to- 2411 one style socket, this field is ignored. 2413 ssfe_data: The undelivered message or part of the undelivered 2414 message will be present in the ssf_data field. Note that the 2415 ssf_info.sinfo_flags field as noted above should be used to 2416 determine if a complete message is present or just a piece of the 2417 message. Note that only user data is present in this field, any 2418 chunk headers or SCTP common headers must be removed by the SCTP 2419 stack. 2421 6.2. Notification Interest Options 2423 6.2.1. SCTP_EVENTS option - DEPRECATED 2425 Please note that this option is deprecated. Use the SCTP_EVENT 2426 option described in Section 6.2.2 instead. 2428 To receive SCTP event notifications, an application registers its 2429 interest by setting the SCTP_EVENTS socket option. The application 2430 then uses recvmsg() to retrieve notifications. A notification is 2431 stored in the data part (msg_iov) of the struct msghdr. The socket 2432 option uses the following structure: 2434 struct sctp_event_subscribe { 2435 uint8_t sctp_data_io_event; 2436 uint8_t sctp_association_event; 2437 uint8_t sctp_address_event; 2438 uint8_t sctp_send_failure_event; 2439 uint8_t sctp_peer_error_event; 2440 uint8_t sctp_shutdown_event; 2441 uint8_t sctp_partial_delivery_event; 2442 uint8_t sctp_adaptation_layer_event; 2443 uint8_t sctp_authentication_event; 2444 uint8_t sctp_sender_dry_event; 2445 }; 2447 sctp_data_io_event: Setting this flag to 1 will cause the reception 2448 of SCTP_SNDRCV information on a per message basis. The 2449 application will need to use the recvmsg() interface so that it 2450 can receive the event information contained in the msg_control 2451 field. Setting the flag to 0 will disable the reception of the 2452 message control information. Note that this is not really a 2453 notification and this is stored in the ancillary data 2454 (msg_control), not in the data part (msg_iov). 2456 sctp_association_event: Setting this flag to 1 will enable the 2457 reception of association event notifications. Setting the flag to 2458 0 will disable association event notifications. 2460 sctp_address_event: Setting this flag to 1 will enable the reception 2461 of address event notifications. Setting the flag to 0 will 2462 disable address event notifications. 2464 sctp_send_failure_event: Setting this flag to 1 will enable the 2465 reception of send failure event notifications. Setting the flag 2466 to 0 will disable send failure event notifications. 2468 sctp_peer_error_event: Setting this flag to 1 will enable the 2469 reception of peer error event notifications. Setting the flag to 2470 0 will disable peer error event notifications. 2472 sctp_shutdown_event: Setting this flag to 1 will enable the 2473 reception of shutdown event notifications. Setting the flag to 0 2474 will disable shutdown event notifications. 2476 sctp_partial_delivery_event: Setting this flag to 1 will enable the 2477 reception of partial delivery notifications. Setting the flag to 2478 0 will disable partial delivery event notifications. 2480 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 2481 reception of adaptation layer notifications. Setting the flag to 2482 0 will disable adaptation layer event notifications. 2484 sctp_authentication_event: Setting this flag to 1 will enable the 2485 reception of authentication layer notifications. Setting the flag 2486 to 0 will disable authentication layer event notifications. 2488 sctp_sender_dry_event: Setting this flag to 1 will enable the 2489 reception of sender dry notifications. Setting the flag to 0 will 2490 disable sender dry event notifications. 2492 An example where an application would like to receive data_io_events 2493 and association_events but no others would be as follows: 2495 { 2496 struct sctp_event_subscribe events; 2498 memset(&events, 0, sizeof(events)); 2500 events.sctp_data_io_event = 1; 2501 events.sctp_association_event = 1; 2503 setsockopt(sd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 2504 } 2506 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2507 receives ancillary data and notifications for all associations bound 2508 to the file descriptor. For one-to-one style SCTP sockets, the 2509 caller receives ancillary data and notifications only for the single 2510 association bound to the file descriptor. 2512 By default both the one-to-one style and the one-to-many style socket 2513 do not subscribe to any notification. 2515 6.2.2. SCTP_EVENT option 2517 The SCTP_EVENTS socket option has one issue for future compatibility. 2518 As new features are added the structure (sctp_event_subscribe) must 2519 be expanded. This can cause an application binary interface (ABI) 2520 issue unless an implementation has added padding at the end of the 2521 structure. To avoid this problem, SCTP_EVENTS has been deprecated 2522 and a new socket option SCTP_EVENT has taken its place. The option 2523 is used with the following structure: 2525 struct sctp_event { 2526 sctp_assoc_t se_assoc_id; 2527 uint16_t se_type; 2528 uint8_t se_on; 2529 }; 2531 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 2532 sockets. For one-to-many style sockets this field can be a 2533 particular association identifier or SCTP_{FUTURE|CURRENT| 2534 ALL}_ASSOC. 2536 se_type: The se_type field can be filled with any value that would 2537 show up in the respective sn_type field (in the sctp_tlv structure 2538 of the notification). 2540 se_on: The se_on field is set to 1 to turn on an event and set to 0 2541 to turn off an event. 2543 To use this option the user fills in this structure and then calls 2544 the setsockopt() to turn on or off an individual event. The 2545 following is an example use of this option: 2547 { 2548 struct sctp_event event; 2550 memset(&event, 0, sizeof(event)); 2552 event.se_assoc_id = SCTP_FUTURE_ASSOC; 2553 event.se_type = SCTP_SENDER_DRY_EVENT; 2554 event.se_on = 1; 2555 setsockopt(sd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2556 } 2558 By default both the one-to-one style and the one-to-many style socket 2559 do not subscribe to any notification. 2561 7. Common Operations for Both Styles 2563 7.1. send(), recv(), sendto(), and recvfrom() 2565 Applications can use send() and sendto() to transmit data to the peer 2566 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2567 data from the peer. 2569 The function prototypes are 2570 ssize_t send(int sd, 2571 const void *msg, 2572 size_t len, 2573 int flags); 2575 ssize_t sendto(int sd, 2576 const void *msg, 2577 size_t len, 2578 int flags, 2579 const struct sockaddr *to, 2580 socklen_t tolen); 2582 ssize_t recv(int sd, 2583 void *buf, 2584 size_t len, 2585 int flags); 2587 ssize_t recvfrom(int sd, 2588 void *buf, 2589 size_t len, 2590 int flags, 2591 struct sockaddr *from, 2592 socklen_t *fromlen); 2594 and the arguments are 2596 sd: The socket descriptor of an SCTP endpoint. 2598 msg: The message to be sent. 2600 len: The size of the message or the size of the buffer. 2602 to: One of the peer addresses of the association to be used to send 2603 the message. 2605 tolen: The size of the address. 2607 buf: The buffer to store a received message. 2609 from: The buffer to store the peer address used to send the received 2610 message. 2612 fromlen: The size of the from address. 2614 flags: (described below). 2616 These calls give access to only basic SCTP protocol features. If 2617 either peer in the association uses multiple streams, or sends 2618 unordered data, these calls will usually be inadequate, and may 2619 deliver the data in unpredictable ways. 2621 SCTP has the concept of multiple streams in one association. The 2622 above calls do not allow the caller to specify on which stream a 2623 message should be sent. The system uses stream 0 as the default 2624 stream for send() and sendto(). recv() and recvfrom() return data 2625 from any stream, but the caller can not distinguish the different 2626 streams. This may result in data seeming to arrive out of order. 2627 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2628 provide no indication. 2630 SCTP is message based. The msg buffer above in send() and sendto() 2631 is considered to be a single message. This means that if the caller 2632 wants to send a message that is composed by several buffers, the 2633 caller needs to combine them before calling send() or sendto(). 2634 Alternately, the caller can use sendmsg() to do that without 2635 combining them. Sending a message using send() or sendto() is atomic 2636 unless explicit EOR marking is enabled on the socket specified by sd. 2637 Using sendto() on a non-connected one-to-one style socket for 2638 implicit connection setup may or may not work depending on the SCTP 2639 implementation. recv() and recvfrom() cannot distinguish message 2640 boundaries (i.e. there is no way to observe the MSG_EOR flag to 2641 detect partial delivery). 2643 In receiving, if the buffer supplied is not large enough to hold a 2644 complete message, the receive call acts like a stream socket and 2645 returns as much data as will fit in the buffer. 2647 Note, the send() and recv() calls may not be used for a one-to-many 2648 style socket. 2650 Note, if an application calls a send() or sendto() function with no 2651 user data the SCTP implementation should reject the request with an 2652 appropriate error message. An implementation is not allowed to send 2653 a DATA chunk with no user data [RFC4960]. 2655 7.2. setsockopt() and getsockopt() 2657 Applications use setsockopt() and getsockopt() to set or retrieve 2658 socket options. Socket options are used to change the default 2659 behavior of socket calls. They are described in Section 8. 2661 The function prototypes are 2663 int getsockopt(int sd, 2664 int level, 2665 int optname, 2666 void *optval, 2667 socklen_t *optlen); 2669 and 2671 int setsockopt(int sd, 2672 int level, 2673 int optname, 2674 const void *optval, 2675 socklen_t optlen); 2677 and the arguments are 2679 sd: The socket descriptor. 2681 level: Set to IPPROTO_SCTP for all SCTP options. 2683 optname: The option name. 2685 optval: The buffer to store the value of the option. 2687 optlen: The size of the buffer (or the length of the option 2688 returned). 2690 They return 0 on success and -1 in case of an error. 2692 All socket options set on a one-to-one style listening socket also 2693 apply to all future accepted sockets. For one-to-many style sockets 2694 often a socket option will pass a structure that includes an assoc_id 2695 field. This field can be filled with the association identifier of a 2696 particular association and unless otherwise specified can be filled 2697 with one of the following constants: 2699 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2700 after this socket option will be affected by this call. 2702 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2703 associations will be affected by this call, future associations 2704 will still receive the previous default value. 2706 SCTP_ALL_ASSOC: Specifies that all current and future associations 2707 will be affected by this call. 2709 7.3. read() and write() 2711 Applications can use read() and write() to send and receive data to 2712 and from a peer. They have the same semantics as send() and recv() 2713 except that the flags parameter cannot be used. 2715 7.4. getsockname() 2717 Applications use getsockname() to retrieve the locally-bound socket 2718 address of the specified socket. This is especially useful if the 2719 caller let SCTP choose a local port. This call is for single homed 2720 endpoints. It does not work well with multi-homed endpoints. See 2721 Section 9.5 for a multi-homed version of the call. 2723 The function prototype is 2725 int getsockname(int sd, 2726 struct sockaddr *address, 2727 socklen_t *len); 2729 and the arguments are 2731 sd: The socket descriptor to be queried. 2733 address: On return, one locally bound address (chosen by the SCTP 2734 stack) is stored in this buffer. If the socket is an IPv4 socket, 2735 the address will be IPv4. If the socket is an IPv6 socket, the 2736 address will be either an IPv6 or IPv4 address. 2738 len: The caller should set the length of the address here. On 2739 return, this is set to the length of the returned address. 2741 It returns 0 on success and -1 in case of an error. 2743 If the actual length of the address is greater than the length of the 2744 supplied sockaddr structure, the stored address will be truncated. 2746 If the socket has not been bound to a local name, the value stored in 2747 the object pointed to by address is unspecified. 2749 7.5. Implicit Association Setup 2751 The application can begin sending and receiving data using the 2752 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 2753 through any explicit association setup procedures (i.e., no connect() 2754 calls required). 2756 Whenever sendmsg() or sendto() is called and the SCTP stack at the 2757 sender finds that no association exists between the sender and the 2758 intended receiver (identified by the address passed either in the 2759 msg_name field of msghdr structure in the sendmsg() call or the 2760 dest_addr field in the sendto() call), the SCTP stack will 2761 automatically setup an association to the intended receiver. 2763 Upon the successful association setup an SCTP_COMM_UP notification 2764 will be dispatched to the socket at both the sender and receiver 2765 side. This notification can be read by the recvmsg() system call 2766 (see Section 3.1.4). 2768 Note, if the SCTP stack at the sender side supports bundling, the 2769 first user message may be bundled with the COOKIE ECHO message 2770 [RFC4960]. 2772 When the SCTP stack sets up a new association implicitly, the 2773 SCTP_INIT type ancillary data may also be passed along (see 2774 Section 5.3.1 for details of the data structures) to change some 2775 parameters used in setting up a new association. 2777 If this information is not present in the sendmsg() call, or if the 2778 implicit association setup is triggered by a sendto() call, the 2779 default association initialization parameters will be used. These 2780 default association parameters may be set with respective 2781 setsockopt() calls or be left to the system defaults. 2783 Implicit association setup cannot be initiated by send() calls. 2785 8. Socket Options 2787 The following sub-section describes various SCTP level socket options 2788 that are common to both styles. SCTP associations can be multi- 2789 homed. Therefore, certain option parameters include a 2790 sockaddr_storage structure to select which peer address the option 2791 should be applied to. 2793 For the one-to-many style sockets, an sctp_assoc_t (association 2794 identifier) parameter is used to identify the association instance 2795 that the operation affects. So it must be set when using this style. 2797 For the one-to-one style sockets and branched off one-to-many style 2798 sockets (see Section 9.2) this association ID parameter is ignored. 2800 Note that socket or IP level options are set or retrieved per socket. 2802 This means that for one-to-many style sockets, the options will be 2803 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2804 association identifier) belonging to the socket. For one-to-one 2805 style, these options will be applied to all peer addresses of the 2806 association controlled by the socket. Applications should be careful 2807 in setting those options. 2809 For some IP stacks getsockopt() is read-only; so a new interface will 2810 be needed when information must be passed both into and out of the 2811 SCTP stack. The syntax for sctp_opt_info() is 2813 int sctp_opt_info(int sd, 2814 sctp_assoc_t id, 2815 int opt, 2816 void *arg, 2817 socklen_t *size); 2819 The sctp_opt_info() call is a replacement for getsockopt() only and 2820 will not set any options associated with the specified socket. A 2821 setsockopt() must be used to set any writeable option. 2823 For one-to-many style sockets, id specifies the association to query. 2824 For one-to-one style sockets, id is ignored. For one-to-many 2825 sockets, any association identifier in the structure provided as arg 2826 is ignored and id takes precedence. 2828 Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used with 2829 sctp_opt_info() or in getsockopt() calls. Using them will result in 2830 an error (returning -1 and errno set to EINVAL). SCTP_FUTURE_ASSOC 2831 can be used to query information for future associations. 2833 The field opt specifies which SCTP socket option to get. It can get 2834 any socket option currently supported that requests information 2835 (either read/write options or read only) such as: 2837 SCTP_RTOINFO 2839 SCTP_ASSOCINFO 2841 SCTP_PRIMARY_ADDR 2843 SCTP_PEER_ADDR_PARAMS 2845 SCTP_DEFAULT_SEND_PARAM 2846 SCTP_MAX_SEG 2848 SCTP_AUTH_ACTIVE_KEY 2850 SCTP_DELAYED_SACK 2852 SCTP_MAX_BURST 2854 SCTP_CONTEXT 2856 SCTP_EVENT 2858 SCTP_DEFAULT_SNDINFO 2860 SCTP_DEFAULT_PRINFO 2862 SCTP_STATUS 2864 SCTP_GET_PEER_ADDR_INFO 2866 SCTP_PEER_AUTH_CHUNKS 2868 SCTP_LOCAL_AUTH_CHUNKS 2870 The arg field is an option-specific structure buffer provided by the 2871 caller. See the rest of this sections subsections for more 2872 information on these options and option-specific structures. 2874 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2875 sets errno to the appropriate error code. 2877 8.1. Read / Write Options 2879 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2881 The protocol parameters used to initialize and limit the 2882 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2883 information on how these parameters are used in RTO calculation. 2885 The following structure is used to access and modify these 2886 parameters: 2888 struct sctp_rtoinfo { 2889 sctp_assoc_t srto_assoc_id; 2890 uint32_t srto_initial; 2891 uint32_t srto_max; 2892 uint32_t srto_min; 2893 }; 2894 srto_initial: This contains the initial RTO value. 2896 srto_max and srto_min: These contain the maximum and minimum bounds 2897 for all RTOs. 2899 srto_assoc_id: This parameter is ignored for one-to-one style 2900 sockets. For one-to-many style sockets the application may fill 2901 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 2902 to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id. 2904 All times are given in milliseconds. A value of 0, when modifying 2905 the parameters, indicates that the current value should not be 2906 changed. 2908 To access or modify these parameters, the application should call 2909 getsockopt() or setsockopt() respectively with the option name 2910 SCTP_RTOINFO. 2912 8.1.2. Association Parameters (SCTP_ASSOCINFO) 2914 This option is used to both examine and set various association and 2915 endpoint parameters. See [RFC4960] for more information on how this 2916 parameter is used. 2918 The following structure is used to access and modify these 2919 parameters: 2921 struct sctp_assocparams { 2922 sctp_assoc_t sasoc_assoc_id; 2923 uint16_t sasoc_asocmaxrxt; 2924 uint16_t sasoc_number_peer_destinations; 2925 uint32_t sasoc_peer_rwnd; 2926 uint32_t sasoc_local_rwnd; 2927 uint32_t sasoc_cookie_life; 2928 }; 2930 sasoc_assoc_id: This parameter is ignored for one-to-one style 2931 sockets. For one-to-many style sockets the application may fill 2932 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 2933 to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id. 2935 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2936 to make for the association. 2938 sasoc_number_peer_destinations: This is the number of destination 2939 addresses that the peer has. 2941 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2942 (reported in the last SACK) minus any outstanding data (i.e. data 2943 in flight). 2945 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2946 the peer. 2948 sasoc_cookie_life: This is the association's cookie life value used 2949 when issuing cookies. 2951 The values of the sasoc_peer_rwnd is meaningless when examining 2952 endpoint information (i.e. it is only valid when examining 2953 information on a specific association). 2955 All time values are given in milliseconds. A value of 0, when 2956 modifying the parameters, indicates that the current value should not 2957 be changed. 2959 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2960 on either an endpoint or association basis. The rwnd and destination 2961 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2962 sasoc_local_rwnd) are not settable and any value placed in these is 2963 ignored. 2965 To access or modify these parameters, the application should call 2966 getsockopt() or setsockopt() respectively with the option name 2967 SCTP_ASSOCINFO. 2969 The maximum number of retransmissions before an address is considered 2970 unreachable is also tunable, but is address-specific, so it is 2971 covered in a separate option. If an application attempts to set the 2972 value of the association maximum retransmission parameter to more 2973 than the sum of all maximum retransmission parameters, setsockopt() 2974 may return an error. The reason for this, from [RFC4960] Section 2975 8.2: 2977 Note: When configuring the SCTP endpoint, the user should avoid 2978 having the value of 'Association.Max.Retrans' (sasoc_maxrxt in this 2979 option) larger than the summation of the 'Path.Max.Retrans' (see 2980 Section 8.1.12 on spp_pathmaxrxt) of all the destination addresses 2981 for the remote endpoint. Otherwise, all the destination addresses 2982 may become inactive while the endpoint still considers the peer 2983 endpoint reachable. 2985 8.1.3. Initialization Parameters (SCTP_INITMSG) 2987 Applications can specify protocol parameters for the default 2988 association initialization. The structure used to access and modify 2989 these parameters is defined in Section 5.3.1. The option name 2990 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2992 Setting initialization parameters is effective only on an unconnected 2993 socket (for one-to-many style sockets only future associations are 2994 affected by the change). 2996 8.1.4. SO_LINGER 2998 An application can use this option to perform the SCTP ABORT 2999 primitive. This option affects all associations related to the 3000 socket. 3002 The linger option structure is: 3004 struct linger { 3005 int l_onoff; /* option on/off */ 3006 int l_linger; /* linger time */ 3007 }; 3009 To enable the option, set l_onoff to 1. If the l_linger value is set 3010 to 0, calling close() is the same as the ABORT primitive. If the 3011 value is set to a negative value, the setsockopt() call will return 3012 an error. If the value is set to a positive value linger_time, the 3013 close() can be blocked for at most linger_time. Please note that the 3014 time unit is seconds according to POSIX, but might be different on 3015 specific platforms. If the graceful shutdown phase does not finish 3016 during this period, close() will return but the graceful shutdown 3017 phase will continue in the system. 3019 Note, this is a socket level option, not an SCTP level option. When 3020 using this option, an application must specify a level of SOL_SOCKET 3021 in the call. 3023 8.1.5. SCTP_NODELAY 3025 Turn on/off any Nagle-like algorithm. This means that packets are 3026 generally sent as soon as possible and no unnecessary delays are 3027 introduced, at the cost of more packets in the network. In 3028 particular, not using any Nagle-like algorithm might reduce the 3029 bundling of small user messages in cases where this would require an 3030 additional delay. 3032 Turning this option on disables any Nagle-like algorithm. 3034 This option expects an integer boolean flag, where a non-zero value 3035 turns on the option, and a zero value turns off the option. 3037 8.1.6. SO_RCVBUF 3039 Sets the receive buffer size in octets. For SCTP one-to-one style 3040 sockets, this controls the receiver window size. For one-to-many 3041 style sockets the meaning is implementation dependent. It might 3042 control the receive buffer for each association bound to the socket 3043 descriptor or it might control the receive buffer for the whole 3044 socket. This option expects an integer. 3046 Note, this is a socket level option, not an SCTP level option. When 3047 using this option, an application must specify a level of SOL_SOCKET 3048 in the call. 3050 8.1.7. SO_SNDBUF 3052 Sets the send buffer size. For SCTP one-to-one style sockets, this 3053 controls the amount of data SCTP may have waiting in internal buffers 3054 to be sent. This option therefore bounds the maximum size of data 3055 that can be sent in a single send call. For one-to-many style 3056 sockets, the effect is the same, except that it applies to one or all 3057 associations (see Section 3.3) bound to the socket descriptor used in 3058 the setsockopt() or getsockopt() call. The option applies to each 3059 association's window size separately. This option expects an 3060 integer. 3062 Note, this is a socket level option, not an SCTP level option. When 3063 using this option, an application must specify a level of SOL_SOCKET 3064 in the call. 3066 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 3068 This socket option is applicable to the one-to-many style socket 3069 only. When set it will cause associations that are idle for more 3070 than the specified number of seconds to automatically close using the 3071 graceful shutdown procedure. An association being idle is defined as 3072 an association that has not sent or received user data. The special 3073 value of '0' indicates that no automatic close of any association 3074 should be performed, this is the default value. This option expects 3075 an integer defining the number of seconds of idle time before an 3076 association is closed. 3078 An application using this option should enable receiving the 3079 association change notification. This is the only mechanism an 3080 application is informed about the closing of an association. After 3081 an association is closed, the association identifier assigned to it 3082 can be reused. An application should be aware of this to avoid the 3083 possible problem of sending data to an incorrect peer endpoint. 3085 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 3087 Requests that the local SCTP stack uses the enclosed peer address as 3088 the association's primary. The enclosed address must be one of the 3089 association peer's addresses. 3091 The following structure is used to make a set peer primary request: 3093 struct sctp_setprim { 3094 sctp_assoc_t ssp_assoc_id; 3095 struct sockaddr_storage ssp_addr; 3096 }; 3098 ssp_addr: The address to set as primary. No wildcard address is 3099 allowed. 3101 ssp_assoc_id: This parameter is ignored for one-to-one style 3102 sockets. For one-to-many style sockets it identifies the 3103 association for this request. Note that the special sctp_assoc_t 3104 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 3106 8.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 3108 Requests that the local endpoint set the specified Adaptation Layer 3109 Indication parameter for all future INIT and INIT-ACK exchanges. 3111 The following structure is used to access and modify this parameter: 3113 struct sctp_setadaptation { 3114 uint32_t ssb_adaptation_ind; 3115 }; 3117 ssb_adaptation_ind: The adaptation layer indicator that will be 3118 included in any outgoing Adaptation Layer Indication parameter. 3120 8.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 3122 This option is a on/off flag and is passed as an integer where a non- 3123 zero is on and a zero is off. If enabled no SCTP message 3124 fragmentation will be performed. The effect of enabling this option 3125 are that if a message being sent exceeds the current PMTU size, the 3126 message will not be sent and instead an error will be indicated to 3127 the user. If this option is disabled (the default) then a message 3128 exceeding the size of the PMTU will be fragmented and reassembled by 3129 the peer. 3131 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 3133 Applications can enable or disable heartbeats for any peer address of 3134 an association, modify an address's heartbeat interval, force a 3135 heartbeat to be sent immediately, and adjust the address's maximum 3136 number of retransmissions sent before an address is considered 3137 unreachable. 3139 The following structure is used to access and modify an address's 3140 parameters: 3142 struct sctp_paddrparams { 3143 sctp_assoc_t spp_assoc_id; 3144 struct sockaddr_storage spp_address; 3145 uint32_t spp_hbinterval; 3146 uint16_t spp_pathmaxrxt; 3147 uint32_t spp_pathmtu; 3148 uint32_t spp_flags; 3149 uint32_t spp_ipv6_flowlabel; 3150 uint8_t spp_dscp; 3151 }; 3153 spp_assoc_id: This parameter is ignored for one-to-one style 3154 sockets. For one-to-many style sockets the application may fill 3155 in an association identifier or SCTP_FUTURE_ASSOC for this query. 3156 It is an error to use SCTP_{CURRENT|ALL}_ASSOC in spp_assoc_id. 3158 spp_address: This specifies which address is of interest. If a 3159 wildcard address is provided it applies to all current and future 3160 paths. 3162 spp_hbinterval: This contains the value of the heartbeat interval, 3163 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 3164 spp_flag is set to SPP_HB_ENABLE the value of this field is 3165 ignored. Note also that a value of zero indicates the current 3166 setting should be left unchanged. To set an actual value of zero 3167 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 3168 it is set to 0, it does not mean that SCTP will continuously send 3169 out heartbeat since the actual interval also includes the current 3170 RTO and jitter (see Section 8.3 in [RFC4960]). 3172 spp_pathmaxrxt: This contains the maximum number of retransmissions 3173 before this address shall be considered unreachable. Note that a 3174 value of zero indicates the current setting should be left 3175 unchanged. 3177 spp_pathmtu: The current path MTU of the peer address. It is the 3178 number of bytes available in an SCTP packet for chunks. Providing 3179 a value of 0 does not change the current setting. If a positive 3180 value is provided and SPP_PMTUD_DISABLE is set in the spp_flags, 3181 the given value is used as the path MTU. If SPP_PMTUD_ENABLE is 3182 set in the spp_flags, the spp_pathmtu field is ignored. 3184 spp_ipv6_flowlabel: This field is used in conjunction with the 3185 SPP_IPV6_FLOWLABEL flag and contains the IPv6 flowlabel. The 20 3186 least significant bits are used for the flowlabel. This setting 3187 has precedence over any IPv6 layer setting. 3189 spp_dscp: This field is used in conjunction with the SPP_DSCP flag 3190 and contains the Differentiated Services Code Point (DSCP). The 6 3191 most significant bits are used for the DSCP. This setting has 3192 precedence over any IPv4 or IPv6 layer setting. 3194 spp_flags: These flags are used to control various features on an 3195 association. The flag field is a bit mask which may contain zero 3196 or more of the following options: 3198 SPP_HB_ENABLE: Enable heartbeats on the specified address. 3200 SPP_HB_DISABLE: Disable heartbeats on the specified address. 3201 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 3202 exclusive, only one of these two should be specified. Enabling 3203 both fields will have undetermined results. 3205 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 3206 immediately. This must not be used in conjunction with a 3207 wildcard address. 3209 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 3210 is to be set to the value of 0 milliseconds. 3212 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 3213 specified address. 3215 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 3216 the specified address. Note that if the address field is empty 3217 then all addresses on the association are affected. Note also 3218 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 3219 exclusive. Enabling both will have undetermined results. 3221 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 3222 IPV6 flowlabel value. The value is contained in the 3223 spp_ipv6_flowlabel field. 3225 Upon retrieval, this flag will be set to indicate that the 3226 spp_ipv6_flowlabel field has a valid value returned. If a 3227 specific destination address is set (in the spp_address field), 3228 then the value returned is that of the address. If just an 3229 association is specified (and no address), then the 3230 association's default flowlabel is returned. If neither an 3231 association nor a destination is specified, then the socket's 3232 default flowlabel is returned. For non IPv6 sockets, this flag 3233 will be left cleared. 3235 SPP_DSCP: Setting this flag enables the setting of the DSCP value 3236 associated with either the association or a specific address. 3237 The value is obtained in the spp_dscp field. 3239 Upon retrieval, this flag will be set to indicate that the 3240 spp_dscp field has a valid value returned. If a specific 3241 destination address is set when called (in the spp_address 3242 field) then that specific destination address' DSCP value is 3243 returned. If just an association is specified then the 3244 association default DSCP is returned. If neither an 3245 association nor a destination is specified, then the sockets 3246 default DSCP is returned. 3248 Please note that changing the flowlabel or DSCP value will affect all 3249 packets sent by the SCTP stack after setting these parameters. The 3250 flowlabel might also be set via the sin6_flowinfo field of the 3251 sockaddr_in6 structure. 3253 8.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) - 3254 DEPRECATED 3256 Please note that this options is deprecated. Section 8.1.31 should 3257 be used instead. 3259 Applications that wish to use the sendto() system call may wish to 3260 specify a default set of parameters that would normally be supplied 3261 through the inclusion of ancillary data. This socket option allows 3262 such an application to set the default sctp_sndrcvinfo structure. 3263 The application that wishes to use this socket option simply passes 3264 the sctp_sndrcvinfo structure defined in Section 5.3.2 to this call. 3265 The input parameters accepted by this call include sinfo_stream, 3266 sinfo_flags, sinfo_ppid, sinfo_context, and sinfo_timetolive. The 3267 sinfo_flags is composed of a bitwise OR of SCTP_UNORDERED, SCTP_EOF, 3268 and SCTP_SENDALL. The sinfo_assoc_id field specifies the association 3269 to apply the parameters to. For a one-to-many style socket any of 3270 the predefined constants are also allowed in this field. The field 3271 is ignored on the one-to-one style. 3273 8.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) - 3274 DEPRECATED 3276 This socket option is used to specify various notifications and 3277 ancillary data the user wishes to receive. Please see Section 6.2.1 3278 for a full description of this option and its usage. Note that this 3279 option is considered deprecated and present for backward 3280 compatibility. New applications should use the SCTP_EVENT option. 3281 See Section 6.2.2 for a full description of that option as well. 3283 8.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 3285 This socket option is a boolean flag which turns on or off the 3286 mapping of IPv4 addresses. If this option is turned on, then IPv4 3287 addresses will be mapped to V6 representation. If this option is 3288 turned off, then no mapping will be done of V4 addresses and a user 3289 will receive both PF_INET6 and PF_INET type addresses on the socket. 3290 See [RFC3542] for more details on mapped V6 addresses. 3292 If this socket option is used on a socket of type PF_INET an error is 3293 returned. 3295 By default this option is turned off and expects an integer to be 3296 passed where a non-zero value turns on the option and a zero value 3297 turns off the option. 3299 8.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 3301 This option will get or set the maximum size to put in any outgoing 3302 SCTP DATA chunk. If a message is larger than this size it will be 3303 fragmented by SCTP into the specified size. Note that the underlying 3304 SCTP implementation may fragment into smaller sized chunks when the 3305 PMTU of the underlying association is smaller than the value set by 3306 the user. The default value for this option is '0' which indicates 3307 the user is not limiting fragmentation and only the PMTU will affect 3308 SCTP's choice of DATA chunk size. Note also that values set larger 3309 than the maximum size of an IP datagram will effectively let SCTP 3310 control fragmentation (i.e. the same as setting this option to 0). 3312 The following structure is used to access and modify this parameter: 3314 struct sctp_assoc_value { 3315 sctp_assoc_t assoc_id; 3316 uint32_t assoc_value; 3317 }; 3318 assoc_id: This parameter is ignored for one-to-one style sockets. 3319 For one-to-many style sockets this parameter indicates which 3320 association the user is performing an action upon. It is an error 3321 to use SCTP_{CURRENT|ALL}_ASSOC in assoc_id. 3323 assoc_value: This parameter specifies the maximum size in bytes. 3325 8.1.17. Get or Set the List of Supported HMAC Identifiers 3326 (SCTP_HMAC_IDENT) 3328 This option gets or sets the list of HMAC algorithms that the local 3329 endpoint requires the peer to use. 3331 The following structure is used to get or set these identifiers: 3333 struct sctp_hmacalgo { 3334 uint32_t shmac_number_of_idents; 3335 uint16_t shmac_idents[]; 3336 }; 3338 shmac_number_of_idents: This field gives the number of elements 3339 present in the array shmac_idents. 3341 shmac_idents: This parameter contains an array of HMAC identifiers 3342 that the local endpoint is requesting the peer to use, in priority 3343 order. The following identifiers are valid: 3345 * SCTP_AUTH_HMAC_ID_SHA1 3347 * SCTP_AUTH_HMAC_ID_SHA256 3349 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 3350 may include any of the other values in its preferred order (lowest 3351 list position has the highest preference in algorithm selection). 3352 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 3353 of an unknown HMAC identifier (including optional identifiers unknown 3354 to the implementation) will cause the set option to fail and return 3355 an error. 3357 8.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 3359 This option will get or set the active shared key to be used to build 3360 the association shared key. 3362 The following structure is used to access and modify these 3363 parameters: 3365 struct sctp_authkeyid { 3366 sctp_assoc_t scact_assoc_id; 3367 uint16_t scact_keynumber; 3368 }; 3370 scact_assoc_id: This parameter sets the active key of the specified 3371 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 3372 used. For one-to-one sockets, this parameter is ignored. Note, 3373 however, that this option will set the active key on the 3374 association if the socket is connected, otherwise this will set 3375 the default active key for the endpoint. 3377 scact_keynumber: This parameter is the shared key identifier which 3378 the application is requesting to become the active shared key to 3379 be used for sending authenticated chunks. The key identifier must 3380 correspond to an existing shared key. Note that shared key 3381 identifier '0' defaults to a null key. 3383 When used with setsockopt() the SCTP implementation must use the 3384 indicated shared key identifier for all messages being given to an 3385 SCTP implementation via a send call after the setsockopt() call until 3386 changed again. Therefore, the SCTP implementation must not bundle 3387 user messages which should be authenticated using different shared 3388 key identifiers. 3390 Initially the key with key identifier 0 is the active key. 3392 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 3394 This option will affect the way delayed sacks are performed. This 3395 option allows the application to get or set the delayed sack time, in 3396 milliseconds. It also allows changing the delayed sack frequency. 3397 Changing the frequency to 1 disables the delayed sack algorithm. 3398 Note that if sack_delay or sack_freq are 0 when setting this option, 3399 the current values will remain unchanged. 3401 The following structure is used to access and modify these 3402 parameters: 3404 struct sctp_sack_info { 3405 sctp_assoc_t sack_assoc_id; 3406 uint32_t sack_delay; 3407 uint32_t sack_freq; 3408 }; 3409 sack_assoc_id: This parameter is ignored for one-to-one style 3410 sockets. For one-to-many style sockets this parameter indicates 3411 which association the user is performing an action upon. The 3412 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3414 sack_delay: This parameter contains the number of milliseconds that 3415 the user is requesting the delayed SACK timer to be set to. Note 3416 that this value is defined in the standard to be between 200 and 3417 500 milliseconds. 3419 sack_freq: This parameter contains the number of packets that must 3420 be received before a sack is sent without waiting for the delay 3421 timer to expire. The default value is 2, setting this value to 1 3422 will disable the delayed sack algorithm. 3424 8.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 3426 Fragmented interleave controls how the presentation of messages 3427 occurs for the message receiver. There are three levels of fragment 3428 interleave defined. Two of the levels affect the one-to-one model, 3429 while the one-to-many model is affected by all three levels. 3431 This option takes an integer value. It can be set to a value of 0, 1 3432 or 2. Attempting to set this level to other values will return an 3433 error. 3435 Setting the three levels provides the following receiver 3436 interactions: 3438 level 0: Prevents the interleaving of any messages. This means that 3439 when a partial delivery begins, no other messages will be received 3440 except the message being partially delivered. If another message 3441 arrives on a different stream (or association) that could be 3442 delivered, it will be blocked waiting for the user to read all of 3443 the partially delivered message. 3445 level 1: Allows interleaving of messages that are from different 3446 associations. For the one-to-one model, level 0 and level 1 thus 3447 have the same meaning since a one-to-one socket always receives 3448 messages from the same association. Note that setting the one-to- 3449 many model to this level may cause multiple partial deliveries 3450 from different associations but for any given association, only 3451 one message will be delivered until all parts of a message have 3452 been delivered. This means that one large message, being read 3453 with an association identifier of "X", will block other messages 3454 from association "X" from being delivered. 3456 level 2: Allows complete interleaving of messages. This level 3457 requires that the sender carefully observes not only the peer 3458 association identifier (or address) but must also pay careful 3459 attention to the stream number. With this option enabled a 3460 partially delivered message may begin being delivered for 3461 association "X" stream "Y" and the next subsequent receive may 3462 return a message from association "X" stream "Z". Note that no 3463 other messages would be delivered for association "X" stream "Y" 3464 until all of stream "Y"'s partially delivered message was read. 3465 Note that this option also affects the one-to-one model. Also 3466 note that for the one-to-many model not only another stream's 3467 message from the same association may be delivered upon the next 3468 receive, some other association's message may be delivered upon 3469 the next receive. 3471 An implementation should default the one-to-many model to level 1. 3472 The reason for this is that otherwise it is possible that a peer 3473 could begin sending a partial message and thus block all other peers 3474 from sending data. However a setting of level 2 requires the 3475 application to not only be aware of the association (via the 3476 association identifier or peer's address) but also the stream number. 3477 The stream number is not present unless the user has subscribed to 3478 the sctp_data_io_event (see Section 6.2), which is deprecated, or has 3479 enabled the SCTP_RECVRCVINFO socket option (see Section 8.1.29). 3480 This is also why we recommend that the one-to-one model be defaulted 3481 to level 0 (level 1 for the one-to-one model has no effect). Note 3482 that an implementation should return an error if an application 3483 attempts to set the level to 2 and has not subscribed to the 3484 sctp_data_io_event event, which is deprecated, or has enabled the 3485 SCTP_RECVRCVINFO socket option. 3487 For applications that have subscribed to events, those events appear 3488 in the normal socket buffer data stream. This means that unless the 3489 user has set the fragmentation interleave level to 0, notifications 3490 may also be interleaved with partially delivered messages. 3492 8.1.21. Set or Get the SCTP Partial Delivery Point 3493 (SCTP_PARTIAL_DELIVERY_POINT) 3495 This option will set or get the SCTP partial delivery point. This 3496 point is the size of a message where the partial delivery API will be 3497 invoked to help free up rwnd space for the peer. Setting this to a 3498 lower value will cause partial deliveries to happen more often. This 3499 option expects an integer that sets or gets the partial delivery 3500 point in bytes. Note also that the call will fail if the user 3501 attempts to set this value larger than the socket receive buffer 3502 size. 3504 Note that any single message having a length smaller than or equal to 3505 the SCTP partial delivery point will be delivered in one single read 3506 call as long as the user provided buffer is large enough to hold the 3507 message. 3509 8.1.22. Set or Get the Use of Extended Receive Info 3510 (SCTP_USE_EXT_RCVINFO) - DEPRECATED 3512 This option will enable or disable the use of the extended version of 3513 the sctp_sndrcvinfo structure. If this option is disabled, then the 3514 normal sctp_sndrcvinfo structure is returned in all receive message 3515 calls. If this option is enabled then the sctp_extrcvinfo structure 3516 is returned in all receive message calls. The default is off. 3518 Note that the sctp_extrcvinfo structure is never used in any send 3519 call. 3521 This option is present for compatibility with older applications and 3522 is deprecated. Future applications should use SCTP_NXTINFO to 3523 retrieve this same information via ancillary data. 3525 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 3527 This option will enable or disable the use of the automatic 3528 generation of ASCONF chunks to add and delete addresses to an 3529 existing association. Note that this option has two caveats namely: 3530 a) it only affects sockets that are bound to all addresses available 3531 to the SCTP stack, and b) the system administrator may have an 3532 overriding control that turns the ASCONF feature off no matter what 3533 setting the socket option may have. 3535 This option expects an integer boolean flag, where a non-zero value 3536 turns on the option, and a zero value turns off the option. 3538 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 3540 This option will allow a user to change the maximum burst of packets 3541 that can be emitted by this association. Note that the default value 3542 is 4, and some implementations may restrict this setting so that it 3543 can only be lowered to positive values. 3545 To set or get this option the user fills in the following structure: 3547 struct sctp_assoc_value { 3548 sctp_assoc_t assoc_id; 3549 uint32_t assoc_value; 3550 }; 3551 assoc_id: This parameter is ignored for one-to-one style sockets. 3552 For one-to-many style sockets this parameter indicates which 3553 association the user is performing an action upon. The special 3554 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3556 assoc_value: This parameter contains the maximum burst. Setting the 3557 value to 0 disables burst mitigation. 3559 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) 3561 The context field in the sctp_sndrcvinfo structure is normally only 3562 used when a failed message is retrieved holding the value that was 3563 sent down on the actual send call. This option allows the setting of 3564 a default context on an association basis that will be received on 3565 reading messages from the peer. This is especially helpful in the 3566 one-to-many model for an application to keep some reference to an 3567 internal state machine that is processing messages on the 3568 association. Note that the setting of this value only affects 3569 received messages from the peer and does not affect the value that is 3570 saved with outbound messages. 3572 To set or get this option the user fills in the following structure: 3574 struct sctp_assoc_value { 3575 sctp_assoc_t assoc_id; 3576 uint32_t assoc_value; 3577 }; 3579 assoc_id: This parameter is ignored for one-to-one style sockets. 3580 For one-to-many style sockets this parameter indicates which 3581 association the user is performing an action upon. The special 3582 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3584 assoc_value: This parameter contains the context. 3586 8.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 3588 This boolean flag is used to enable or disable explicit end of record 3589 (EOR) marking. When this option is enabled, a user may make multiple 3590 send system calls to send a record and must indicate that they are 3591 finished sending a particular record by including the SCTP_EOR flag. 3592 If this boolean flag is disabled then each individual send system 3593 call is considered to have an SCTP_EOR indicator set on it implicitly 3594 without the user having to explicitly add this flag. The default is 3595 off. 3597 This option expects an integer boolean flag, where a non-zero value 3598 turns on the option, and a zero value turns off the option. 3600 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 3602 This option only supports one-to-one style SCTP sockets. If used on 3603 a one-to-many style SCTP socket an error is indicated. 3605 This option expects an integer boolean flag, where a non-zero value 3606 turns on the option, and a zero value turns off the option. 3608 This socket option must not be used after calling bind() or 3609 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 3610 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3611 SCTP sockets bound to the same port must have set the 3612 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3613 having set the SCTP_REUSE_PORT option will fail if there are other 3614 sockets bound to the same port. At most one socket being bound to 3615 the same port may be listening. 3617 It should be noted that the behavior of the socket level socket 3618 option to reuse ports and/or addresses for SCTP sockets is 3619 unspecified. 3621 8.1.28. Set Notification Event (SCTP_EVENT) 3623 This socket option is used to set a specific notification option. 3624 Please see Section 6.2.2 for a full description of this option and 3625 its usage. 3627 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary 3628 Data (SCTP_RECVRCVINFO) 3630 Setting this option specifies that SCTP_RCVINFO defined in 3631 Section 5.3.5 is returned as ancillary data by recvmsg(). 3633 This option expects an integer boolean flag, where a non-zero value 3634 turns on the option, and a zero value turns off the option. 3636 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary 3637 Data (SCTP_RECVNXTINFO) 3639 Setting this option specifies that SCTP_NXTINFO defined in 3640 Section 5.3.6 is returned as ancillary data by recvmsg(). 3642 This option expects an integer boolean flag, where a non-zero value 3643 turns on the option, and a zero value turns off the option. 3645 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) 3647 Applications that wish to use the sendto() system call may wish to 3648 specify a default set of parameters that would normally be supplied 3649 through the inclusion of ancillary data. This socket option allows 3650 such an application to set the default sctp_sndinfo structure. The 3651 application that wishes to use this socket option simply passes the 3652 sctp_sndinfo structure defined in Section 5.3.4 to this call. The 3653 input parameters accepted by this call include snd_sid, snd_flags, 3654 snd_ppid, snd_context. The snd_flags is composed of a bitwise OR of 3655 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The snd_assoc_id field 3656 specifies the association to apply the parameters to. For a one-to- 3657 many style socket any of the predefined constants are also allowed in 3658 this field. The field is ignored on the one-to-one style. 3660 8.1.32. Set Default PR-SCTP Parameters (SCTP_DEFAULT_PRINFO) 3662 This option sets and gets the default parameters for PR-SCTP. They 3663 can be overwritten by specific information provided in send calls. 3665 The following structure is used to access and modify these 3666 parameters: 3668 struct sctp_default_prinfo { 3669 uint16_t pr_policy; 3670 uint32_t pr_value; 3671 sctp_assoc_t pr_assoc_id; 3672 }; 3674 pr_policy: Same as described in Section 5.3.7. 3676 pr_value: Same as described in Section 5.3.7. 3678 pr_assoc_id: This field is ignored for one-to-one style sockets. 3679 For one-to-many style sockets pr_assoc_id can be a particular 3680 association identifier or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. 3682 8.2. Read-Only Options 3684 The options defined in this subsection are read-only. Using this 3685 option in a setsockopt() call will result in an error indicating 3686 EOPNOTSUPP. 3688 8.2.1. Association Status (SCTP_STATUS) 3690 Applications can retrieve current status information about an 3691 association, including association state, peer receiver window size, 3692 number of unacknowledged data chunks, and number of data chunks 3693 pending receipt. This information is read-only. 3695 The following structure is used to access this information: 3697 struct sctp_status { 3698 sctp_assoc_t sstat_assoc_id; 3699 int32_t sstat_state; 3700 uint32_t sstat_rwnd; 3701 uint16_t sstat_unackdata; 3702 uint16_t sstat_penddata; 3703 uint16_t sstat_instrms; 3704 uint16_t sstat_outstrms; 3705 uint32_t sstat_fragmentation_point; 3706 struct sctp_paddrinfo sstat_primary; 3707 }; 3709 sstat_assoc_id: This parameter is ignored for one-to-one style 3710 sockets. For one-to-many style sockets it holds the identifier 3711 for the association. All notifications for a given association 3712 have the same association identifier. The special SCTP_{FUTURE| 3713 CURRENT|ALL}_ASSOC cannot be used. 3715 sstat_state: This contains the association's current state, i.e. one 3716 of the following values: 3718 * SCTP_CLOSED 3720 * SCTP_BOUND 3722 * SCTP_LISTEN 3724 * SCTP_COOKIE_WAIT 3726 * SCTP_COOKIE_ECHOED 3728 * SCTP_ESTABLISHED 3730 * SCTP_SHUTDOWN_PENDING 3732 * SCTP_SHUTDOWN_SENT 3734 * SCTP_SHUTDOWN_RECEIVED 3736 * SCTP_SHUTDOWN_ACK_SENT 3738 sstat_rwnd: This contains the association peer's current receiver 3739 window size. 3741 sstat_unackdata: This is the number of unacknowledged data chunks. 3743 sstat_penddata: This is the number of data chunks pending receipt. 3745 sstat_instrms: The number of streams that the peer will be using 3746 outbound. 3748 sstat_outstrms: The number of streams that the endpoint is allowed 3749 to use outbound. 3751 sstat_fragmentation_point: The size at which SCTP fragmentation will 3752 occur. 3754 sstat_primary: This is information on the current primary peer 3755 address. 3757 To access these status values, the application calls getsockopt() 3758 with the option name SCTP_STATUS. 3760 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3762 Applications can retrieve information about a specific peer address 3763 of an association, including its reachability state, congestion 3764 window, and retransmission timer values. This information is read- 3765 only. 3767 The following structure is used to access this information: 3769 struct sctp_paddrinfo { 3770 sctp_assoc_t spinfo_assoc_id; 3771 struct sockaddr_storage spinfo_address; 3772 int32_t spinfo_state; 3773 uint32_t spinfo_cwnd; 3774 uint32_t spinfo_srtt; 3775 uint32_t spinfo_rto; 3776 uint32_t spinfo_mtu; 3777 }; 3779 spinfo_assoc_id: This parameter is ignored for one-to-one style 3780 sockets. For one-to-many style sockets the following applies: 3781 This field may be filled by the application, if so, this field 3782 will have priority in looking up the association instead of using 3783 the address specified in spinfo_address. Note that if the address 3784 does not belong to the association specified then this call will 3785 fail. If the application does not fill in the spinfo_assoc_id, 3786 then the address will be used to lookup the association and on 3787 return this field will have the valid association identifier. In 3788 other words, this call can be used to translate an address into an 3789 association identifier. Note that the predefined constants are 3790 not allowed on this option. 3792 spinfo_address: This is filled by the application, and contains the 3793 peer address of interest. 3795 spinfo_state: This contains the peer address' state: 3797 SCTP_UNCONFIRMED: The initial state of a peer address. 3799 SCTP_ACTIVE: The state is entered the first time after path 3800 verification. It can also be entered if the state is 3801 SCTP_INACTIVE and the path supervision detects that the peer 3802 address is reachable again. 3804 SCTP_INACTIVE: This state is entered whenever a path failure is 3805 detected. 3807 spinfo_cwnd: This contains the peer address' current congestion 3808 window. 3810 spinfo_srtt: This contains the peer address' current smoothed round- 3811 trip time calculation in milliseconds. 3813 spinfo_rto: This contains the peer address' current retransmission 3814 timeout value in milliseconds. 3816 spinfo_mtu: The current path MTU of the peer address. It is the 3817 number of bytes available in an SCTP packet for chunks. 3819 8.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3820 (SCTP_PEER_AUTH_CHUNKS) 3822 This option gets a list of chunk types (see [RFC4960]) for a 3823 specified association that the peer requires to be received 3824 authenticated only. 3826 The following structure is used to access these parameters: 3828 struct sctp_authchunks { 3829 sctp_assoc_t gauth_assoc_id; 3830 uint32_t gauth_number_of_chunks 3831 uint8_t gauth_chunks[]; 3832 }; 3833 gauth_assoc_id: This parameter indicates for which association the 3834 user is requesting the list of peer authenticated chunks. For 3835 one-to-one sockets, this parameter is ignored. Note that the 3836 predefined constants are not allowed with this option. 3838 gauth_number_of_chunks: This parameter gives the number of elements 3839 in the array gauth_chunks. 3841 gauth_chunks: This parameter contains an array of chunk types that 3842 the peer is requesting to be authenticated. If the passed in 3843 buffer size is not large enough to hold the list of chunk types, 3844 ENOBUFS is returned. 3846 8.2.4. Get the List of Chunks the Local Endpoint Requires to be 3847 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3849 This option gets a list of chunk types (see [RFC4960]) for a 3850 specified association that the local endpoint requires to be received 3851 authenticated only. 3853 The following structure is used to access these parameters: 3855 struct sctp_authchunks { 3856 sctp_assoc_t gauth_assoc_id; 3857 uint32_t gauth_number_of_chunks; 3858 uint8_t gauth_chunks[]; 3859 }; 3861 gauth_assoc_id: This parameter is ignored for one-to-one style 3862 sockets. For one-to-many style sockets the application may fill 3863 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 3864 to use SCTP_{CURRENT|ALL}_ASSOC in gauth_assoc_id. 3866 gauth_number_of_chunks: This parameter gives the number of elements 3867 in the array gauth_chunks. 3869 gauth_chunks: This parameter contains an array of chunk types that 3870 the local endpoint is requesting to be authenticated. If the 3871 passed in buffer is not large enough to hold the list of chunk 3872 types, ENOBUFS is returned. 3874 8.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3876 This option gets the current number of associations that are attached 3877 to a one-to-many style socket. The option value is an uint32_t. 3878 Note that this number is only a snap shot. This means that the 3879 number of associations may have changed when the caller gets back the 3880 option result. 3882 For a one-to-one style socket, this socket option results in an 3883 error. 3885 8.2.6. Get the Current Identifiers of Associations 3886 (SCTP_GET_ASSOC_ID_LIST) 3888 This option gets the current list of SCTP association identifiers of 3889 the SCTP associations handled by a one-to-many style socket. 3891 The option value has the structure 3893 struct sctp_assoc_ids { 3894 uint32_t gaids_number_of_ids; 3895 sctp_assoc_t gaids_assoc_id[]; 3896 }; 3898 The caller must provide a large enough buffer to hold all association 3899 identifiers. If the buffer is too small, an error must be returned. 3900 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3901 idea how large the buffer has to be. gaids_number_of_ids gives the 3902 number of elements in the array gaids_assoc_id. Note also that some 3903 or all of sctp_assoc_t returned in the array may become invalid by 3904 the time the caller gets back the result. 3906 For a one-to-one style socket, this socket option results in an 3907 error. 3909 8.3. Write-Only Options 3911 The options defined in this subsection are write-only. Using this 3912 option in a getsockopt() or sctp_opt_info() call will result in an 3913 error indicating EOPNOTSUPP. 3915 8.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3917 Requests that the peer marks the enclosed address as the association 3918 primary (see [RFC5061]). The enclosed address must be one of the 3919 association's locally bound addresses. 3921 The following structure is used to make a set peer primary request: 3923 struct sctp_setpeerprim { 3924 sctp_assoc_t sspp_assoc_id; 3925 struct sockaddr_storage sspp_addr; 3926 }; 3927 sspp_assoc_id: This parameter is ignored for one-to-one style 3928 sockets. For one-to-many style sockets it identifies the 3929 association for this request. Note that the predefined constants 3930 are not allowed on this option. 3932 sspp_addr: The address to set as primary. 3934 8.3.2. Add a Chunk that must be Authenticated (SCTP_AUTH_CHUNK) 3936 This set option adds a chunk type that the user is requesting to be 3937 received only in an authenticated way. Changes to the list of chunks 3938 will only affect future associations on the socket. 3940 The following structure is used to add a chunk: 3942 struct sctp_authchunk { 3943 uint8_t sauth_chunk; 3944 }; 3946 sauth_chunk: This parameter contains a chunk type that the user is 3947 requesting to be authenticated. 3949 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3950 chunks must not be used. If they are used, an error must be 3951 returned. The usage of this option enables SCTP AUTH in cases where 3952 it is not required by other means (for example the use of dynamic 3953 address reconfiguration). 3955 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3957 This option will set a shared secret key that is used to build an 3958 association shared key. 3960 The following structure is used to access and modify these 3961 parameters: 3963 struct sctp_authkey { 3964 sctp_assoc_t sca_assoc_id; 3965 uint16_t sca_keynumber; 3966 uint16_t sca_keylength; 3967 uint8_t sca_key[]; 3968 }; 3970 sca_assoc_id: This parameter indicates what association the shared 3971 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3972 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3973 ignored. Note, however on one to one sockets, that this option 3974 will set a key on the association if the socket is connected, 3975 otherwise this will set a key on the endpoint. 3977 sca_keynumber: This parameter is the shared key identifier by which 3978 the application will refer to this shared key. If a key of the 3979 specified index already exists, then this new key will replace the 3980 old existing key. Note that shared key identifier '0' defaults to 3981 a null key. 3983 sca_keylength: This parameter is the length of the array sca_key. 3985 sca_key: This parameter contains an array of bytes that is to be 3986 used by the endpoint (or association) as the shared secret key. 3987 Note, if the length of this field is zero, a null key is set. 3989 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3991 This set option indicates that the application will no longer send 3992 user messages using the indicated key identifier. 3994 struct sctp_authkeyid { 3995 sctp_assoc_t scact_assoc_id; 3996 uint16_t scact_keynumber; 3997 }; 3999 scact_assoc_id: This parameter indicates which association the 4000 shared key identifier is being deleted from. The special 4001 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 4002 sockets, this parameter is ignored. Note, however, that this 4003 option will deactivate the key from the association if the socket 4004 is connected, otherwise this will deactivate the key from the 4005 endpoint. 4007 scact_keynumber: This parameter is the shared key identifier which 4008 the application is requesting to be deactivated. The key 4009 identifier must correspond to an existing shared key. Note if 4010 this parameter is zero, use of the null key identifier '0' is 4011 deactivated on the endpoint and/or association. 4013 The currently active key cannot be deactivated. 4015 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 4017 This set option will delete a shared secret key which has been 4018 deactivated of an SCTP association. 4020 struct sctp_authkeyid { 4021 sctp_assoc_t scact_assoc_id; 4022 uint16_t scact_keynumber; 4024 }; 4026 scact_assoc_id: This parameter indicates which association the 4027 shared key identifier is being deleted from. The special 4028 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 4029 sockets, this parameter is ignored. Note, however, that this 4030 option will delete the key from the association if the socket is 4031 connected, otherwise this will delete the key from the endpoint. 4033 scact_keynumber: This parameter is the shared key identifier which 4034 the application is requesting to be deleted. The key identifier 4035 must correspond to an existing shared key and must not be in use 4036 for any packet being sent by the SCTP implementation. This means 4037 in particular, that it must be deactivated first. Note if this 4038 parameter is zero, use of the null key identifier '0' is deleted 4039 from the endpoint and/or association. 4041 Only deactivated keys that are no longer used by an association can 4042 be deleted. 4044 9. New Functions 4046 Depending on the system, the following interface can be implemented 4047 as a system call or library function. 4049 9.1. sctp_bindx() 4051 This function allows the user to bind a specific subset of addresses 4052 or, if the SCTP extension described in [RFC5061] is supported, add or 4053 delete specific addresses. 4055 The function prototype is 4057 int sctp_bindx(int sd, 4058 struct sockaddr *addrs, 4059 int addrcnt, 4060 int flags); 4062 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 4063 If the sd is an IPv6 socket, the addresses passed can either be IPv4 4064 or IPv6 addresses. 4066 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 4067 Section 3.1.2 for this usage. 4069 addrs is a pointer to an array of one or more socket addresses. Each 4070 address is contained in its appropriate structure. For an IPv6 4071 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 4072 array of sockaddr_in is used. The caller specifies the number of 4073 addresses in the array with addrcnt. Note that the wildcard 4074 addresses cannot be used in combination with non wildcard addresses 4075 on a socket with this function, doing so will result in an error. 4077 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 4078 -1 and sets errno to the appropriate error code. 4080 For SCTP, the port given in each socket address must be the same, or 4081 sctp_bindx() will fail, setting errno to EINVAL. 4083 The flags parameter is formed from the bitwise OR of zero or more of 4084 the following currently defined flags: 4086 o SCTP_BINDX_ADD_ADDR 4088 o SCTP_BINDX_REM_ADDR 4090 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 4091 socket (i.e. endpoint), and SCTP_BINDX_REM_ADDR directs SCTP to 4092 remove the given addresses from the socket. The two flags are 4093 mutually exclusive; if both are given, sctp_bindx() will fail with 4094 EINVAL. A caller may not remove all addresses from a socket; 4095 sctp_bindx() will reject such an attempt with EINVAL. 4097 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 4098 additional addresses with an endpoint after calling bind(). Or use 4099 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 4100 socket is associated with, so that no new association accepted will 4101 be associated with these addresses. If the endpoint supports dynamic 4102 address reconfiguration, an SCTP_BINDX_REM_ADDR or 4103 SCTP_BINDX_ADD_ADDR may cause an endpoint to send the appropriate 4104 message to its peers to change the peers' address lists. 4106 Adding and removing addresses from established associations is an 4107 optional functionality. Implementations that do not support this 4108 functionality should return -1 and set errno to EOPNOTSUPP. 4110 sctp_bindx() can be called on an already bound socket or on an 4111 unbound socket. If the socket is unbound and the first port number 4112 in the addrs is zero, the kernel will choose a port number. All port 4113 numbers after the first one being 0 must also be zero. If the first 4114 port number is not zero, the following port numbers must be zero or 4115 have the same value as the first one. For an already bound socket, 4116 all port numbers provided must be the bound one or 0. 4118 sctp_bindx() is an atomic operation. Therefore, the binding will be 4119 either successful on all addresses or fail on all addresses. If 4120 multiple addresses are provided and the sctp_bindx() call fails there 4121 is no indication which address is responsible for the failure. The 4122 only way to identify the specific error indication is to call 4123 sctp_bindx() sequentially with only one address per call. 4125 9.2. sctp_peeloff() 4127 After an association is established on a one-to-many style socket, 4128 the application may wish to branch off the association into a 4129 separate socket/file descriptor. 4131 This is particularly desirable when, for instance, the application 4132 wishes to have a number of sporadic message senders/receivers remain 4133 under the original one-to-many style socket, but branch off these 4134 associations carrying high volume data traffic into their own 4135 separate socket descriptors. 4137 The application uses the sctp_peeloff() call to branch off an 4138 association into a separate socket (Note the semantics are somewhat 4139 changed from the traditional one-to-one style accept() call). Note 4140 that the new socket is a one-to-one style socket. Thus it will be 4141 confined to operations allowed for a one-to-one style socket. 4143 The function prototype is 4145 int sctp_peeloff(int sd, 4146 sctp_assoc_t assoc_id); 4148 and the arguments are 4150 sd: The original one-to-many style socket descriptor returned from 4151 the socket() system call (see Section 3.1.1). 4153 assoc_id: the specified identifier of the association that is to be 4154 branched off to a separate file descriptor (Note, in a traditional 4155 one-to-one style accept() call, this would be an out parameter, 4156 but for the one-to-many style call, this is an in parameter). 4158 The function returns a non-negative file descriptor representing the 4159 branched-off association, or -1 if an error occurred. The variable 4160 errno is then set appropriately. 4162 9.3. sctp_getpaddrs() 4164 sctp_getpaddrs() returns all peer addresses in an association. 4166 The function prototype is: 4168 int sctp_getpaddrs(int sd, 4169 sctp_assoc_t id, 4170 struct sockaddr **addrs); 4172 On return, addrs will point to a dynamically allocated array of 4173 sockaddr structures of the appropriate type for the socket type. The 4174 caller should use sctp_freepaddrs() to free the memory. Note that 4175 the in/out parameter addrs must not be NULL. 4177 If sd is an IPv4 socket, the addresses returned will be all IPv4 4178 addresses. If sd is an IPv6 socket, the addresses returned can be a 4179 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4180 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4182 For one-to-many style sockets, id specifies the association to query. 4183 For one-to-one style sockets, id is ignored. 4185 On success, sctp_getpaddrs() returns the number of peer addresses in 4186 the association. If there is no association on this socket, 4187 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 4188 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 4189 is undefined. 4191 9.4. sctp_freepaddrs() 4193 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 4195 The function prototype is 4197 void sctp_freepaddrs(struct sockaddr *addrs); 4199 and addrs is the array of peer addresses returned by 4200 sctp_getpaddrs(). 4202 9.5. sctp_getladdrs() 4204 sctp_getladdrs() returns all locally bound address(es) on a socket. 4206 The function prototype is 4208 int sctp_getladdrs(int sd, 4209 sctp_assoc_t id, 4210 struct sockaddr **addrs); 4212 On return, addrs will point to a dynamically allocated array of 4213 sockaddr structures of the appropriate type for the socket type. The 4214 caller should use sctp_freeladdrs() to free the memory. Note that 4215 the in/out parameter addrs must not be NULL. 4217 If sd is an IPv4 socket, the addresses returned will be all IPv4 4218 addresses. If sd is an IPv6 socket, the addresses returned can be a 4219 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4220 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4222 For one-to-many style sockets, id specifies the association to query. 4223 For one-to-one style sockets, id is ignored. 4225 If the id field is set to the value '0' then the locally bound 4226 addresses are returned without regard to any particular association. 4228 On success, sctp_getladdrs() returns the number of local addresses 4229 bound to the socket. If the socket is unbound, sctp_getladdrs() 4230 returns 0, and the value of *addrs is undefined. If an error occurs, 4231 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 4233 9.6. sctp_freeladdrs() 4235 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 4237 The function prototype is 4239 void sctp_freeladdrs(struct sockaddr *addrs); 4241 and addrs is the array of local addresses returned by 4242 sctp_getladdrs(). 4244 9.7. sctp_sendmsg() - DEPRECATED 4246 This function is deprecated, sctp_sendv() (see Section 9.12) should 4247 be used instead. 4249 An implementation may provide a library function (or possibly system 4250 call) to assist the user with the advanced features of SCTP. 4252 The function prototype is 4254 ssize_t sctp_sendmsg(int sd, 4255 const void *msg, 4256 size_t len, 4257 const struct sockaddr *to, 4258 socklen_t tolen, 4259 uint32_t ppid, 4260 uint32_t flags, 4261 uint16_t stream_no, 4262 uint32_t timetolive, 4263 uint32_t context); 4265 and the arguments are: 4267 sd: The socket descriptor. 4269 msg: The message to be sent. 4271 len: The length of the message. 4273 to: The destination address of the message. 4275 tolen: The length of the destination address. 4277 ppid: The same as sinfo_ppid (see Section 5.3.2). 4279 flags: The same as sinfo_flags (see Section 5.3.2). 4281 stream_no: The same as sinfo_stream (see Section 5.3.2). 4283 timetolive: The same as sinfo_timetolive (see Section 5.3.2). 4285 context: The same as sinfo_context (see Section 5.3.2). 4287 The call returns the number of characters sent, or -1 if an error 4288 occurred. The variable errno is then set appropriately. 4290 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 4291 marking is enabled on the socket specified by sd). 4293 Using sctp_sendmsg() on a non-connected one-to-one style socket for 4294 implicit connection setup may or may not work depending on the SCTP 4295 implementation. 4297 9.8. sctp_recvmsg() - DEPRECATED 4299 This function is deprecated, sctp_recvv() (see Section 9.13) should 4300 be used instead. 4302 An implementation may provide a library function (or possibly system 4303 call) to assist the user with the advanced features of SCTP. Note 4304 that in order for the sctp_sndrcvinfo structure to be filled in by 4305 sctp_recvmsg() the caller must enable the sctp_data_io_event with the 4306 SCTP_EVENTS option. Note that the setting of the 4307 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 4308 sctp_sndrcvinfo information to be extended. 4310 The function prototype is 4311 ssize_t sctp_recvmsg(int sd, 4312 void *msg, 4313 size_t len, 4314 struct sockaddr *from, 4315 socklen_t *fromlen 4316 struct sctp_sndrcvinfo *sinfo 4317 int *msg_flags); 4319 and the arguments are 4321 sd: The socket descriptor. 4323 msg: The message buffer to be filled. 4325 len: The length of the message buffer. 4327 from: A pointer to an address to be filled with the sender of this 4328 messages address. 4330 fromlen: An in/out parameter describing the from length. 4332 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 4333 receipt of the message. 4335 msg_flags: A pointer to an integer to be filled with any message 4336 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 4337 field. Options for the receive may also be passed into the value 4338 (e.g. MSG_PEEK). On return from the call, the msg_flags value 4339 will be different than what was sent in to the call. If 4340 implemented via a recvmsg() call, the msg_flags should only 4341 contain the value of the flags from the recvmsg() call. 4343 The call returns the number of bytes received, or -1 if an error 4344 occurred. The variable errno is then set appropriately. 4346 9.9. sctp_connectx() 4348 An implementation may provide a library function (or possibly system 4349 call) to assist the user with associating to an endpoint that is 4350 multi-homed. Much like sctp_bindx() this call allows a caller to 4351 specify multiple addresses at which a peer can be reached. The way 4352 the SCTP stack uses the list of addresses to set up the association 4353 is implementation dependent. This function only specifies that the 4354 stack will try to make use of all the addresses in the list when 4355 needed. 4357 Note that the list of addresses passed in is only used for setting up 4358 the association. It does not necessarily equal the set of addresses 4359 the peer uses for the resulting association. If the caller wants to 4360 find out the set of peer addresses, it must use sctp_getpaddrs() to 4361 retrieve them after the association has been set up. 4363 The function prototype is 4365 int sctp_connectx(int sd, 4366 struct sockaddr *addrs, 4367 int addrcnt, 4368 sctp_assoc_t *id); 4370 and the arguments are: 4372 sd: The socket descriptor. 4374 addrs: An array of addresses. 4376 addrcnt: The number of addresses in the array. 4378 id: An output parameter that if passed in as a non-NULL will return 4379 the association identifier for the newly created association (if 4380 successful). 4382 The call returns 0 on success or -1 if an error occurred. The 4383 variable errno is then set appropriately. 4385 9.10. sctp_send() - DEPRECATED 4387 This function is deprecated, sctp_sendv() should be used instead. 4389 An implementation may provide another alternative function or system 4390 call to assist an application with the sending of data without the 4391 use of the CMSG header structures. 4393 The function prototype is 4395 ssize_t sctp_send(int sd, 4396 const void *msg, 4397 size_t len, 4398 const struct sctp_sndrcvinfo *sinfo, 4399 int flags); 4401 and the arguments are 4403 sd: The socket descriptor. 4405 msg: The message to be sent. 4407 len: The length of the message. 4409 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4410 in Section 5.3.2 for a sendmsg() call. 4412 flags: The same flags as used by the sendmsg() call flags (e.g. 4413 MSG_DONTROUTE). 4415 The call returns the number of bytes sent, or -1 if an error 4416 occurred. The variable errno is then set appropriately. 4418 This function call may also be used to terminate an association using 4419 an association identifier by setting the sinfo.sinfo_flags to 4420 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4421 to be terminated. In such a case the len of the message can be zero. 4423 Using sctp_send() on a non-connected one-to-one style socket for 4424 implicit connection setup may or may not work depending on the SCTP 4425 implementation. 4427 Sending a message using sctp_send() is atomic unless explicit EOR 4428 marking is enabled on the socket specified by sd. 4430 9.11. sctp_sendx() - DEPRECATED 4432 This function is deprecated, sctp_sendv() should be used instead. 4434 An implementation may provide another alternative function or system 4435 call to assist an application with the sending of data without the 4436 use of the CMSG header structures that also gives a list of 4437 addresses. The list of addresses is provided for implicit 4438 association setup. In such a case the list of addresses serves the 4439 same purpose as the addresses given in sctp_connectx() (see 4440 Section 9.9). 4442 The function prototype is 4444 ssize_t sctp_sendx(int sd, 4445 const void *msg, 4446 size_t len, 4447 struct sockaddr *addrs, 4448 int addrcnt, 4449 struct sctp_sndrcvinfo *sinfo, 4450 int flags); 4452 and the arguments are: 4454 sd: The socket descriptor. 4456 msg: The message to be sent. 4458 len: The length of the message. 4460 addrs: Is an array of addresses. 4462 addrcnt: The number of addresses in the array. 4464 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4465 in Section 5.3.2 for a sendmsg() call. 4467 flags: The same flags as used by the sendmsg() call flags (e.g. 4468 MSG_DONTROUTE). 4470 The call returns the number of bytes sent, or -1 if an error 4471 occurred. The variable errno is then set appropriately. 4473 Note that in case of implicit connection setup, on return from this 4474 call the sinfo_assoc_id field of the sinfo structure will contain the 4475 new association identifier. 4477 This function call may also be used to terminate an association using 4478 an association identifier by setting the sinfo.sinfo_flags to 4479 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4480 to be terminated. In such a case the len of the message would be 4481 zero. 4483 Sending a message using sctp_sendx() is atomic unless explicit EOR 4484 marking is enabled on the socket specified by sd. 4486 Using sctp_sendx() on a non-connected one-to-one style socket for 4487 implicit connection setup may or may not work depending on the SCTP 4488 implementation. 4490 9.12. sctp_sendv() 4492 The function prototype is 4494 ssize_t sctp_sendv(int sd, 4495 const struct iovec *iov, 4496 int iovcnt, 4497 struct sockaddr *addrs, 4498 int addrcnt, 4499 void *info, 4500 socklen_t infolen, 4501 unsigned int infotype, 4502 int flags); 4504 The function sctp_sendv() provides an extensible way for an 4505 application to communicate different send attributes to the SCTP 4506 stack when sending a message. An implementation may provide 4507 sctp_sendv() as a library function or a system call. 4509 This document defines three types of attributes which can be used to 4510 describe a message to be sent. They are struct sctp_sndinfo 4511 (Section 5.3.4), struct sctp_prinfo (Section 5.3.7), and struct 4512 sctp_authinfo (Section 5.3.8). The following structure 4513 sctp_sendv_spa is defined to be used when more than one of the above 4514 attributes are needed to describe a message to be sent. 4516 struct sctp_sendv_spa { 4517 uint32_t sendv_flags; 4518 struct sctp_sndinfo sendv_sndinfo; 4519 struct sctp_prinfo sendv_prinfo; 4520 struct sctp_authinfo sendv_authinfo; 4521 }; 4523 The sendv_flags field holds a bit wise OR of SCTP_SEND_SNDINFO_VALID, 4524 SCTP_SEND_PRINFO_VALID and SCTP_SEND_AUTHINFO_VALID indicating if the 4525 sendv_sndinfo/sendv_prinfo/sendv_authinfo fields contain valid 4526 information. 4528 In future, when new send attributes are needed, new structures can be 4529 defined. But those new structures do not need to be based on any of 4530 the above defined structures. 4532 The function takes the following arguments: 4534 sd: The socket descriptor. 4536 iov: The gather buffer. The data in the buffer is treated as one 4537 single user message. 4539 iovcnt: The number of elements in iov. 4541 addrs: An array of addresses to be used to set up an association or 4542 one single address to be used to send the message. Pass in NULL 4543 if the caller does not want to set up an association nor want to 4544 send the message to a specific address. 4546 addrcnt: The number of addresses in the addrs array. 4548 info: A pointer to the buffer containing the attribute associated 4549 with the message to be sent. The type is indicated by the 4550 info_type parameter. 4552 infolen: The length in bytes of info. 4554 infotype: Identifies the type of the information provided in info. 4555 The current defined values are: 4557 SCTP_SENDV_NOINFO: No information is provided. The parameter 4558 info is a NULL pointer and infolen is 0. 4560 SCTP_SENDV_SNDINFO: The parameter info is pointing to a struct 4561 sctp_sndinfo. 4563 SCTP_SENDV_PRINFO: The parameter info is pointing to a struct 4564 sctp_prinfo. 4566 SCTP_SENDV_AUTHINFO: The parameter info is pointing to a struct 4567 sctp_authinfo. 4569 SCTP_SENDV_SPA: The parameter info is pointing to a struct 4570 sctp_sendv_spa. 4572 flags: The same flags as used by the sendmsg() call flags (e.g. 4573 MSG_DONTROUTE). 4575 The call returns the number of bytes sent, or -1 if an error 4576 occurred. The variable errno is then set appropriately. 4578 A note on one-to-many style socket. The struct sctp_sndinfo 4579 attribute must always be used in order to specify the association the 4580 message is to be sent on. The only case where it is not needed is 4581 when this call is used to set up a new association. 4583 The caller provides a list of addresses in the addrs parameter to set 4584 up an association. This function will behave like calling 4585 sctp_connectx() (see Section 9.9) first using the list of addresses 4586 and then calling sendmsg() with the given message and attributes. 4587 For an one-to-many style socket, if struct sctp_sndinfo attribute is 4588 provided, the snd_assoc_id field must be 0. When this function 4589 returns, the snd_assoc_id field will contain the association 4590 identifier of the newly established association. Note that struct 4591 sctp_sndinfo attribute is not required to set up an association for 4592 one-to-many style socket. If this attribute is not provided, the 4593 caller can enable the SCTP_ASSOC_CHANGE notification and use the 4594 SCTP_COMM_UP message to find out the association identifier. 4596 If the caller wants to send the message to a specific peer address 4597 (hence overriding the primary address), it can provide the specific 4598 address in the addrs parameter and provide a struct sctp_sndinfo 4599 attribute with the field snd_flags set to SCTP_ADDR_OVER. 4601 This function call may also be used to terminate an association. The 4602 caller provides an sctp_sndinfo attribute with the snd_flags set to 4603 SCTP_EOF. In this case the len of the message would be zero. 4605 Sending a message using sctp_sendv() is atomic unless explicit EOR 4606 marking is enabled on the socket specified by sd. 4608 9.13. sctp_recvv() 4610 The function prototype is 4612 ssize_t sctp_recvv(int sd, 4613 const struct iovec *iov, 4614 int iovlen, 4615 struct sockaddr *from, 4616 socklen_t *fromlen, 4617 void *info, 4618 socklen_t *infolen, 4619 unsigned int *infotype, 4620 int *flags); 4622 The function sctp_recvv() provides an extensible way for the SCTP 4623 stack to pass up different SCTP attributes associated with a received 4624 message to an application. An implementation may provide 4625 sctp_recvv() as a library function or as a system call. 4627 This document defines two types of attributes which can be returned 4628 by this call, the attribute of the received message and the attribute 4629 of the next message in receive buffer. The caller enables the 4630 SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these 4631 attributes respectively. Attributes of the received message are 4632 returned in struct sctp_rcvinfo (Section 5.3.5) and attributes of the 4633 next message are returned in struct sctp_nxtinfo (Section 5.3.6). If 4634 both options are enabled, both attributes are returned using the 4635 following structure. 4637 struct sctp_recvv_rn { 4638 struct sctp_rcvinfo recvv_rcvinfo; 4639 struct sctp_nxtinfo recvv_nxtinfo; 4640 }; 4642 In future, new structures can be defined to hold new types of 4643 attributes. The new structures do not need to be based on struct 4644 sctp_recvv_rn or struct sctp_rcvinfo. 4646 This function takes the following arguments: 4648 sd: The socket descriptor. 4650 iov: The scatter buffer. Only one user message is returned in this 4651 buffer. 4653 iovlen: The number of elements in iov. 4655 from: A pointer to an address to be filled with the sender of the 4656 received message's address. 4658 fromlen: An in/out parameter describing the from length. 4660 info: A pointer to the buffer to hold the attributes of the received 4661 message. The structure type of info is determined by the 4662 info_type parameter. 4664 infolen: An in/out parameter describing the size of the info buffer. 4666 infotype: In return, *info_type is set to the type of the info 4667 buffer. The current defined values are: 4669 SCTP_RECVV_NOINFO: If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO 4670 options are not enabled, no attribute will be returned. If 4671 only the SCTP_RECVNXTINFO option is enabled but there is no 4672 next message in the buffer, there will also no attribute be 4673 returned. In these cases *info_type will be set to 4674 SCTP_RECVV_NOINFO. 4676 SCTP_RECVV_RCVINFO: The type of info is struct sctp_rcvinfo and 4677 the attribute is about the received message. 4679 SCTP_RECVV_NXTINFO: The type of info is struct sctp_nxtinfo and 4680 the attribute is about the next message in receive buffer. 4681 This is the case when only the SCTP_RECVNXTINFO option is 4682 enabled and there is a next message in buffer. 4684 SCTP_RECVV_RN: The type of info is struct sctp_recvv_rn. The 4685 recvv_rcvinfo field is the attribute of the received message 4686 and the recvv_nxtinfo field is the attribute of the next 4687 message in buffer. This is the case when both SCTP_RECVRCVINFO 4688 and SCTP_RECVNXTINFO options are enabled and there is a next 4689 message in the receive buffer. 4691 flags: A pointer to an integer to be filled with any message flags 4692 (e.g. MSG_NOTIFICATION). Note that this field is an in/out 4693 parameter. Options for the receive may also be passed into the 4694 value (e.g. MSG_PEEK). On return from the call, the flags value 4695 will be different than what was sent in to the call. If 4696 implemented via a recvmsg() call, the flags should only contain 4697 the value of the flags from the recvmsg() call when calling 4698 sctp_recvv() and on return it has the value from msg_flags. 4700 The call returns the number of bytes received, or -1 if an error 4701 occurred. The variable errno is then set appropriately. 4703 10. IANA Considerations 4705 This document requires no actions from IANA. 4707 11. Security Considerations 4709 Many TCP and UDP implementations reserve port numbers below 1024 for 4710 privileged users. If the target platform supports privileged users, 4711 the SCTP implementation should restrict the ability to call bind() or 4712 sctp_bindx() on these port numbers to privileged users. 4714 Similarly unprivileged users should not be able to set protocol 4715 parameters that could result in the congestion control algorithm 4716 being more aggressive than permitted on the public Internet. These 4717 parameters are: 4719 o struct sctp_rtoinfo 4721 If an unprivileged user inherits a one-to-many style socket with open 4722 associations on a privileged port, it may be permitted to accept new 4723 associations, but it should not be permitted to open new 4724 associations. This could be relevant for the r* family of protocols. 4726 Applications using the one-to-many style sockets and using the 4727 interleave level if 0 are subject to denial of service attacks as 4728 described in Section 8.1.20. 4730 Applications needing transport layer security can use DTLS/SCTP as 4731 specified in [RFC6083]. This can be implemented using the socket API 4732 described in this document. 4734 12. Acknowledgments 4736 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 4737 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 4738 early formation of this document. 4740 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, 4741 Martin Becke, Jon Berger, Mark Butler, Thomas Dreibholz, Andreas 4742 Fink, Scott Kimble, Jonathan Leighton, Renee Revis, Irene Ruengeler, 4743 Dan Wing, and many others on the TSVWG mailing list for contributing 4744 valuable comments. 4746 A special thanks to Phillip Conrad, for his suggested text, quick and 4747 constructive insights, and most of all his persistent fighting to 4748 keep the interface to SCTP usable for the application programmer. 4750 13. References 4752 13.1. Normative References 4754 [IEEE-1003.1-2008] 4755 Institute of Electrical and Electronics Engineers, 4756 "Information Technology - Portable Operating System 4757 Interface (POSIX)", IEEE Standard 1003.1, 2008. 4759 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 4760 Stevens, "Basic Socket Interface Extensions for IPv6", 4761 RFC 3493, February 2003. 4763 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4764 "Advanced Sockets Application Program Interface (API) for 4765 IPv6", RFC 3542, May 2003. 4767 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 4768 Conrad, "Stream Control Transmission Protocol (SCTP) 4769 Partial Reliability Extension", RFC 3758, May 2004. 4771 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 4772 "Authenticated Chunks for the Stream Control Transmission 4773 Protocol (SCTP)", RFC 4895, August 2007. 4775 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 4776 RFC 4960, September 2007. 4778 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 4779 Kozuka, "Stream Control Transmission Protocol (SCTP) 4780 Dynamic Address Reconfiguration", RFC 5061, 4781 September 2007. 4783 13.2. Informative References 4785 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4786 RFC 793, September 1981. 4788 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4789 August 1980. 4791 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 4792 Functional Specification", RFC 1644, July 1994. 4794 [RFC6083] Tuexen, M., Seggelmann, R., and E. Rescorla, "Datagram 4795 Transport Layer Security (DTLS) for Stream Control 4796 Transmission Protocol (SCTP)", RFC 6083, January 2011. 4798 Appendix A. One-to-One Style Code Example 4800 The following code is an implementation of a simple client which 4801 sends a number of messages marked for unordered delivery to an echo 4802 server making use of all outgoing streams. The example shows how to 4803 use some features of one-to-one style IPv4 SCTP sockets, including: 4805 o Creating and connecting an SCTP socket. 4807 o Requesting to negotiate a number of outgoing streams. 4809 o Determining the negotiated number of outgoing streams. 4811 o Setting an adaptation layer indication. 4813 o Sending messages with a given payload protocol identifier on a 4814 particular stream using sctp_sendv(). 4816 /* 4818 Copyright (c) 2011 IETF Trust and the persons identified 4819 as authors of the code. All rights reserved. 4821 Redistribution and use in source and binary forms, with 4822 or without modification, is permitted pursuant to, and subject 4823 to the license terms contained in, the Simplified BSD License 4824 set forth in Section 4.c of the IETF Trust's Legal Provisions 4825 Relating to IETF Documents (http://trustee.ietf.org/license-info). 4827 */ 4829 #include 4830 #include 4831 #include 4832 #include 4833 #include 4834 #include 4835 #include 4836 #include 4837 #include 4839 #define PORT 9 4840 #define ADDR "127.0.0.1" 4841 #define SIZE_OF_MESSAGE 1000 4842 #define NUMBER_OF_MESSAGES 10 4843 #define PPID 1234 4845 int 4846 main(void) { 4847 unsigned int i; 4848 int sd; 4849 struct sockaddr_in addr; 4850 char buffer[SIZE_OF_MESSAGE]; 4851 struct iovec iov; 4852 struct sctp_status status; 4853 struct sctp_initmsg init; 4854 struct sctp_sndinfo info; 4855 struct sctp_setadaptation ind; 4856 socklen_t opt_len; 4858 /* Create a one-to-one style SCTP socket. */ 4859 if ((sd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) < 0) { 4860 perror("socket"); 4861 exit(1); 4862 } 4864 /* Prepare for requesting 2048 outgoing streams. */ 4865 memset(&init, 0, sizeof(init)); 4866 init.sinit_num_ostreams = 2048; 4867 if (setsockopt(sd, IPPROTO_SCTP, SCTP_INITMSG, 4868 &init, (socklen_t)sizeof(init)) < 0) { 4869 perror("setsockopt"); 4870 exit(1); 4871 } 4873 ind.ssb_adaptation_ind = 0x01020304; 4874 if (setsockopt(sd, IPPROTO_SCTP, SCTP_ADAPTATION_LAYER, 4875 &ind, (socklen_t)sizeof(ind)) < 0) { 4876 perror("setsockopt"); 4877 exit(1); 4878 } 4880 /* Connect to the discard server. */ 4881 memset(&addr, 0, sizeof(addr)); 4882 #ifdef HAVE_SIN_LEN 4883 addr.sin_len = sizeof(struct sockaddr_in); 4884 #endif 4885 addr.sin_family = AF_INET; 4886 addr.sin_port = htons(PORT); 4887 addr.sin_addr.s_addr = inet_addr(ADDR); 4888 if (connect(sd, 4889 (const struct sockaddr *)&addr, 4890 sizeof(struct sockaddr_in)) < 0) { 4891 perror("connect"); 4892 exit(1); 4893 } 4895 /* Get the actual number of outgoing streams. */ 4896 memset(&status, 0, sizeof(status)); 4897 opt_len = (socklen_t)sizeof(status); 4898 if (getsockopt(sd, IPPROTO_SCTP, SCTP_STATUS, 4899 &status, &opt_len) < 0) { 4900 perror("getsockopt"); 4901 exit(1); 4902 } 4904 memset(&info, 0, sizeof(info)); 4905 info.snd_ppid = htonl(PPID); 4906 info.snd_flags = SCTP_UNORDERED; 4907 memset(buffer, 'A', SIZE_OF_MESSAGE); 4908 iov.iov_base = buffer; 4909 iov.iov_len = SIZE_OF_MESSAGE; 4910 for (i = 0; i < NUMBER_OF_MESSAGES; i++) { 4911 info.snd_sid = i % status.sstat_outstrms; 4912 if (sctp_sendv(sd, 4913 (const struct iovec *)&iov, 1, 4914 NULL, 0, 4915 &info, sizeof(info), SCTP_SENDV_SNDINFO, 4916 0) < 0) { 4917 perror("sctp_sendv"); 4918 exit(1); 4919 } 4920 } 4922 if (close(sd) < 0) { 4923 perror("close"); 4924 exit(1); 4925 } 4926 return(0); 4927 } 4929 Appendix B. One-to-Many Style Code Example 4931 The following code is a simple implementation of a discard server 4932 over SCTP. The example shows how to use some features of one-to-many 4933 style IPv6 SCTP sockets, including: 4935 o Opening and binding of a socket. 4937 o Enabling notifications. 4939 o Handling notifications. 4941 o Configuring the auto close timer. 4943 o Using sctp_recvv() to receive messages. 4945 Please note that this server can be used in combination with the 4946 client described in Appendix A. 4948 /* 4950 Copyright (c) 2011 IETF Trust and the persons identified 4951 as authors of the code. All rights reserved. 4953 Redistribution and use in source and binary forms, with 4954 or without modification, is permitted pursuant to, and subject 4955 to the license terms contained in, the Simplified BSD License 4956 set forth in Section 4.c of the IETF Trust's Legal Provisions 4957 Relating to IETF Documents (http://trustee.ietf.org/license-info). 4959 */ 4961 #include 4962 #include 4963 #include 4964 #include 4965 #include 4966 #include 4967 #include 4968 #include 4969 #include 4970 #define BUFFER_SIZE (1<<16) 4971 #define PORT 9 4972 #define ADDR "0.0.0.0" 4973 #define TIMEOUT 5 4975 static void 4976 print_notification(void *buf) 4977 { 4978 struct sctp_assoc_change *sac; 4979 struct sctp_paddr_change *spc; 4980 struct sctp_adaptation_event *sad; 4981 union sctp_notification *snp; 4982 char addrbuf[INET6_ADDRSTRLEN]; 4983 const char *ap; 4984 struct sockaddr_in *sin; 4985 struct sockaddr_in6 *sin6; 4987 snp = buf; 4989 switch (snp->sn_header.sn_type) { 4990 case SCTP_ASSOC_CHANGE: 4991 sac = &snp->sn_assoc_change; 4992 printf("^^^ Association change: "); 4993 switch (sac->sac_state) { 4994 case SCTP_COMM_UP: 4995 printf("Communication up (streams (in/out)=(%u/%u)).\n", 4996 sac->sac_inbound_streams, sac->sac_outbound_streams); 4997 break; 4998 case SCTP_COMM_LOST: 4999 printf("Communication lost (error=%d).\n", sac->sac_error); 5000 break; 5001 case SCTP_RESTART: 5002 printf("Communication restarted (streams (in/out)=(%u/%u).\n", 5003 sac->sac_inbound_streams, sac->sac_outbound_streams); 5004 break; 5005 case SCTP_SHUTDOWN_COMP: 5006 printf("Communication completed.\n"); 5007 break; 5008 case SCTP_CANT_STR_ASSOC: 5009 printf("Communication couldn't be started.\n"); 5010 break; 5011 default: 5012 printf("Unknown state: %d.\n", sac->sac_state); 5013 break; 5014 } 5015 break; 5016 case SCTP_PEER_ADDR_CHANGE: 5017 spc = &snp->sn_paddr_change; 5018 if (spc->spc_aaddr.ss_family == AF_INET) { 5019 sin = (struct sockaddr_in *)&spc->spc_aaddr; 5020 ap = inet_ntop(AF_INET, &sin->sin_addr, 5021 addrbuf, INET6_ADDRSTRLEN); 5022 } else { 5023 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 5024 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 5025 addrbuf, INET6_ADDRSTRLEN); 5026 } 5027 printf("^^^ Peer Address change: %s ", ap); 5028 switch (spc->spc_state) { 5029 case SCTP_ADDR_AVAILABLE: 5030 printf("is available.\n"); 5031 break; 5032 case SCTP_ADDR_UNREACHABLE: 5033 printf("is not available (error=%d).\n", spc->spc_error); 5034 break; 5035 case SCTP_ADDR_REMOVED: 5036 printf("was removed.\n"); 5037 break; 5038 case SCTP_ADDR_ADDED: 5039 printf("was added.\n"); 5040 break; 5041 case SCTP_ADDR_MADE_PRIM: 5042 printf("is primary.\n"); 5043 break; 5044 default: 5045 printf("unknown state (%d).\n", spc->spc_state); 5046 break; 5047 } 5048 break; 5049 case SCTP_SHUTDOWN_EVENT: 5050 printf("^^^ Shutdown received.\n"); 5051 break; 5052 case SCTP_ADAPTATION_INDICATION: 5053 sad = &snp->sn_adaptation_event; 5054 printf("^^^ Adaptation indication 0x%08x received.\n", 5055 sad->sai_adaptation_ind); 5056 break; 5057 default: 5058 printf("^^^ Unknown event of type: %u.\n", 5059 snp->sn_header.sn_type); 5060 break; 5061 }; 5062 } 5064 int 5065 main(void) { 5066 int sd, flags, timeout, on; 5067 ssize_t n; 5068 unsigned int i; 5069 union { 5070 struct sockaddr sa; 5071 struct sockaddr_in sin; 5072 struct sockaddr_in6 sin6; 5073 } addr; 5074 socklen_t fromlen, infolen; 5075 struct sctp_rcvinfo info; 5076 unsigned int infotype; 5077 struct iovec iov; 5078 char buffer[BUFFER_SIZE]; 5079 struct sctp_event event; 5080 uint16_t event_types[] = {SCTP_ASSOC_CHANGE, 5081 SCTP_PEER_ADDR_CHANGE, 5082 SCTP_SHUTDOWN_EVENT, 5083 SCTP_ADAPTATION_INDICATION}; 5085 /* Create a 1-to-many style SCTP socket. */ 5086 if ((sd = socket(AF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP)) < 0) { 5087 perror("socket"); 5088 exit(1); 5089 } 5091 /* Enable the events of interest. */ 5092 memset(&event, 0, sizeof(event)); 5093 event.se_assoc_id = SCTP_FUTURE_ASSOC; 5094 event.se_on = 1; 5095 for (i = 0; i < sizeof(event_types)/sizeof(uint16_t); i++) { 5096 event.se_type = event_types[i]; 5097 if (setsockopt(sd, IPPROTO_SCTP, SCTP_EVENT, 5098 &event, sizeof(event)) < 0) { 5099 perror("setsockopt"); 5100 exit(1); 5101 } 5102 } 5104 /* Configure auto-close timer. */ 5105 timeout = TIMEOUT; 5106 if (setsockopt(sd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 5107 &timeout, sizeof(timeout)) < 0) { 5108 perror("setsockopt SCTP_AUTOCLOSE"); 5109 exit(1); 5110 } 5112 /* Enable delivery of SCTP_RCVINFO. */ 5113 on = 1; 5114 if (setsockopt(sd, IPPROTO_SCTP, SCTP_RECVRCVINFO, 5115 &on, sizeof(on)) < 0) { 5116 perror("setsockopt SCTP_RECVRCVINFO"); 5117 exit(1); 5118 } 5120 /* Bind the socket to all local addresses. */ 5121 memset(&addr, 0, sizeof(addr)); 5122 #ifdef HAVE_SIN6_LEN 5123 addr.sin6.sin6_len = sizeof(addr.sin6); 5124 #endif 5125 addr.sin6.sin6_family = AF_INET6; 5126 addr.sin6.sin6_port = htons(PORT); 5127 addr.sin6.sin6_addr = in6addr_any; 5128 if (bind(sd, &addr.sa, sizeof(addr.sin6)) < 0) { 5129 perror("bind"); 5130 exit(1); 5131 } 5132 /* Enable accepting associations. */ 5133 if (listen(sd, 1) < 0) { 5134 perror("listen"); 5135 exit(1); 5136 } 5138 for (;;) { 5139 flags = 0; 5140 memset(&addr, 0, sizeof(addr)); 5141 fromlen = (socklen_t)sizeof(addr); 5142 memset(&info, 0, sizeof(info)); 5143 infolen = (socklen_t)sizeof(info); 5144 infotype = 0; 5145 iov.iov_base = buffer; 5146 iov.iov_len = BUFFER_SIZE; 5148 n = sctp_recvv(sd, &iov, 1, 5149 &addr.sa, &fromlen, 5150 &info, &infolen, &infotype, 5151 &flags); 5153 if (flags & MSG_NOTIFICATION) { 5154 print_notification(iov.iov_base); 5155 } else { 5156 char addrbuf[INET6_ADDRSTRLEN]; 5157 const char *ap; 5158 in_port_t port; 5160 if (addr.sa.sa_family == AF_INET) { 5161 ap = inet_ntop(AF_INET, &addr.sin.sin_addr, 5162 addrbuf, INET6_ADDRSTRLEN); 5163 port = ntohs(addr.sin.sin_port); 5164 } else { 5165 ap = inet_ntop(AF_INET6, &addr.sin6.sin6_addr, 5166 addrbuf, INET6_ADDRSTRLEN); 5167 port = ntohs(addr.sin6.sin6_port); 5168 } 5169 printf("Message received from %s:%u: len=%d", 5170 ap, port, (int)n); 5171 switch (infotype) { 5172 case SCTP_RECVV_RCVINFO: 5173 printf(", sid=%u", info.rcv_sid); 5174 if (info.rcv_flags & SCTP_UNORDERED) { 5175 printf(", unordered"); 5176 } else { 5177 printf(", ssn=%u", info.rcv_ssn); 5178 } 5179 printf(", tsn=%u", info.rcv_tsn); 5180 printf(", ppid=%u.\n", ntohl(info.rcv_ppid)); 5181 break; 5182 case SCTP_RECVV_NOINFO: 5183 case SCTP_RECVV_NXTINFO: 5184 case SCTP_RECVV_RN: 5185 printf(".\n"); 5186 break; 5187 default: 5188 printf(" unknown infotype.\n"); 5189 } 5190 } 5191 } 5193 if (close(sd) < 0) { 5194 perror("close"); 5195 exit(1); 5196 } 5198 return (0); 5199 } 5201 Authors' Addresses 5203 Randall R. Stewart 5204 Adara Networks 5205 Chapin, SC 29036 5206 USA 5208 Email: randall@lakerest.net 5210 Michael Tuexen 5211 Muenster University of Applied Sciences 5212 Stegerwaldstr. 39 5213 48565 Steinfurt 5214 Germany 5216 Email: tuexen@fh-muenster.de 5218 Kacheong Poon 5219 Oracle Corporation 5221 Email: ka-cheong.poon@oracle.com 5223 Peter Lei 5224 Cisco Systems, Inc. 5225 9501 Technology Blvd 5226 West Office Center 5227 Rosemont, IL 60018 5228 USA 5230 Email: peterlei@cisco.com 5232 Vladislav Yasevich 5233 HP 5234 110 Spitrook Rd 5235 Nashua, NH 03062 5236 USA 5238 Email: vladislav.yasevich@hp.com