idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-31.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 (August 10, 2011) is 4640 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: February 11, 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 August 10, 2011 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-31.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 February 11, 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() . . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . 15 81 3.3. Special considerations . . . . . . . . . . . . . . . . . 16 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() . . . . . . . . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . . . . . . . . . . . . 102 222 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 103 223 13.1. Normative References . . . . . . . . . . . . . . . . . . 103 224 13.2. Informative References . . . . . . . . . . . . . . . . . 103 225 Appendix A. One-to-One Style Code Example . . . . . . . . . . . 104 226 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 106 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 2. Data Types 288 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 289 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 290 (e.g. uint16_t). This document also assumes the argument data types 291 from 1003.1g when possible (e.g. the final argument to setsockopt() 292 is a size_t value). Whenever buffer sizes are specified, the POSIX 293 1003.1 size_t data type is used. 295 3. One-to-Many Style Interface 297 In the one-to-many style interface there is a 1 to many relationship 298 between sockets and associations. 300 3.1. Basic Operation 302 A typical server in this style uses the following socket calls in 303 sequence to prepare an endpoint for servicing requests: 305 o socket() 307 o bind() 309 o listen() 311 o recvmsg() 313 o sendmsg() 315 o close() 317 A typical client uses the following calls in sequence to setup an 318 association with a server to request services: 320 o socket() 322 o sendmsg() 323 o recvmsg() 325 o close() 327 In this style, by default, all the associations connected to the 328 endpoint are represented with a single socket. Each association is 329 assigned an association identifier (type is sctp_assoc_t) so that an 330 application can use it to differentiate among them. In some 331 implementations, the peer endpoints' addresses can also be used for 332 this purpose. But this is not required for performance reasons. If 333 an implementation does not support using addresses to differentiate 334 between different associations, the sendto() call can only be used to 335 setup an association implicitly. It cannot be used to send data to 336 an established association as the association identifier cannot be 337 specified. 339 Once an association identifier is assigned to an SCTP association, 340 that identifier will not be reused until the application explicitly 341 terminates the use of the association. The resources belonging to 342 that association will not be freed until that happens. This is 343 similar to the close() operation on a normal socket. The only 344 exception is when the SCTP_AUTOCLOSE option (Section 8.1.8) is set. 345 In this case, after the association is terminated gracefully and 346 automatically, the association identifier assigned to it can be 347 reused. All applications using this option should be aware of this 348 to avoid the possible problem of sending data to an incorrect peer 349 endpoint. 351 If the server or client wishes to branch an existing association off 352 to a separate socket, it is required to call sctp_peeloff() and to 353 specify the association identifier. The sctp_peeloff() call will 354 return a new one-to-one style socket which can then be used with 355 recv() and send() functions for message passing. See Section 9.2 for 356 more on branched-off associations. 358 Once an association is branched off to a separate socket, it becomes 359 completely separated from the original socket. All subsequent 360 control and data operations to that association must be done through 361 the new socket. For example, the close operation on the original 362 socket will not terminate any associations that have been branched 363 off to a different socket. 365 One-to-many style socket calls are discussed in more detail in the 366 following subsections. 368 3.1.1. socket() 370 Applications use socket() to create a socket descriptor to represent 371 an SCTP endpoint. 373 The function prototype is 375 int socket(int domain, 376 int type, 377 int protocol); 379 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 380 type and IPPROTO_SCTP as the protocol. 382 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 383 socket. 385 The function returns a socket descriptor or -1 in case of an error. 387 Using the PF_INET domain indicates the creation of an endpoint which 388 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 389 can use both IPv6 and IPv4 addresses. 391 3.1.2. bind() 393 Applications use bind() to specify which local address and port the 394 SCTP endpoint should associate itself with. 396 An SCTP endpoint can be associated with multiple addresses. To do 397 this, sctp_bindx() is introduced in Section 9.1 to help applications 398 do the job of associating multiple addresses. But note that an 399 endpoint can only be associated with one local port. 401 These addresses associated with a socket are the eligible transport 402 addresses for the endpoint to send and receive data. The endpoint 403 will also present these addresses to its peers during the association 404 initialization process, see [RFC4960]. 406 After calling bind(), if the endpoint wishes to accept new 407 associations on the socket, it must call listen() (see 408 Section 3.1.3). 410 The function prototype of bind() is 412 int bind(int sd, 413 struct sockaddr *addr, 414 socklen_t addrlen); 416 and the arguments are 418 sd: The socket descriptor returned by socket(). 420 addr: The address structure (struct sockaddr_in for an IPv4 address 421 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 423 addrlen: The size of the address structure. 425 It returns 0 on success and -1 in case of an error. 427 If sd is an IPv4 socket, the address passed must be an IPv4 address. 428 If the sd is an IPv6 socket, the address passed can either be an IPv4 429 or an IPv6 address. 431 Applications cannot call bind() multiple times to associate multiple 432 addresses to an endpoint. After the first call to bind(), all 433 subsequent calls will return an error. 435 If the IP address part of addr is specified as a wildcard (INADDR_ANY 436 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 437 IPv6 address), the operating system will associate the endpoint with 438 an optimal address set of the available interfaces. If the IPv4 439 sin_port or IPv6 sin6_port is set to 0, the operating system will 440 choose an ephemeral port for the endpoint. 442 If a bind() is not called prior to a sendmsg() call that initiates a 443 new association, the system picks an ephemeral port and will choose 444 an address set equivalent to binding with a wildcard address. One of 445 those addresses will be the primary address for the association. 446 This automatically enables the multi-homing capability of SCTP. 448 The completion of this bind() process does not allow the SCTP 449 endpoint to accept inbound SCTP association requests. Until a 450 listen() system call, described below, is performed on the socket, 451 the SCTP endpoint will promptly reject an inbound SCTP INIT request 452 with an SCTP ABORT. 454 3.1.3. listen() 456 By default, a one-to-many style socket does not accept new 457 association requests. An application uses listen() to mark a socket 458 as being able to accept new associations. 460 The function prototype is 462 int listen(int sd, 463 int backlog); 465 and the arguments are 467 sd: The socket descriptor of the endpoint. 469 backlog: If backlog is non-zero, enable listening, else disable 470 listening. 472 It returns 0 on success and -1 in case of an error. 474 Note that one-to-many style socket consumers do not need to call 475 accept to retrieve new associations. Calling accept() on a one-to- 476 many style socket should return EOPNOTSUPP. Rather, new associations 477 are accepted automatically, and notifications of the new associations 478 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 479 these notifications are enabled). Clients will typically not call 480 listen(), so that they can be assured that only actively initiated 481 associations are possible on the socket. Server or peer-to-peer 482 sockets, on the other hand, will always accept new associations, so a 483 well-written application using server one-to-many style sockets must 484 be prepared to handle new associations from unwanted peers. 486 Also note that the SCTP_ASSOC_CHANGE event provides the association 487 identifier for a new association, so if applications wish to use the 488 association identifier as a parameter to other socket calls, they 489 should ensure that the SCTP_ASSOC_CHANGE event is enabled. 491 3.1.4. sendmsg() and recvmsg() 493 An application uses the sendmsg() and recvmsg() call to transmit data 494 to and receive data from its peer. 496 The function prototypes are 498 ssize_t sendmsg(int sd, 499 const struct msghdr *message, 500 int flags); 502 and 504 ssize_t recvmsg(int sd, 505 struct msghdr *message, 506 int flags); 508 using the arguments: 510 sd: The socket descriptor of the endpoint. 512 message: Pointer to the msghdr structure which contains a single 513 user message and possibly some ancillary data. See Section 5 for 514 complete description of the data structures. 516 flags: No new flags are defined for SCTP at this level. See 517 Section 5 for SCTP specific flags used in the msghdr structure. 519 sendmsg() returns the number of bytes accepted by the kernel or -1 in 520 case of an error. recvmsg() returns the number of bytes received or 521 -1 in case of an error. 523 As described in Section 5, different types of ancillary data can be 524 sent and received along with user data. When sending, the ancillary 525 data is used to specify the sent behavior, such as the SCTP stream 526 number to use. When receiving, the ancillary data is used to 527 describe the received data, such as the SCTP stream sequence number 528 of the message. 530 When sending user data with sendmsg(), the msg_name field in the 531 msghdr structure will be filled with one of the transport addresses 532 of the intended receiver. If there is no existing association 533 between the sender and the intended receiver, the sender's SCTP stack 534 will set up a new association and then send the user data (see 535 Section 7.5 for more on implicit association setup). If sendmsg() is 536 called with no data and there is no existing association, a new one 537 will be established. The SCTP_INIT type ancillary data can be used 538 to change some of the parameters used to set up a new association. 539 If sendmsg() is called with NULL data, and there is no existing 540 association but the SCTP_ABORT or SCTP_EOF flags are set as described 541 in Section 5.3.4, then -1 is returned and errno is set to EINVAL. 542 Sending a message using sendmsg() is atomic unless explicit EOR 543 marking is enabled on the socket specified by sd (see 544 Section 8.1.26). 546 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 547 be delivered if that notification has been enabled, and no more data 548 can be sent to that association. Any attempt to send more data will 549 cause sendmsg() to return with an ESHUTDOWN error. Note that the 550 socket is still open for reading at this point so it is possible to 551 retrieve notifications. 553 When receiving a user message with recvmsg(), the msg_name field in 554 the msghdr structure will be populated with the source transport 555 address of the user data. The caller of recvmsg() can use this 556 address information to determine to which association the received 557 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 558 disabled, applications must use the peer transport address provided 559 in the msg_name field by recvmsg() to perform correlation to an 560 association, since they will not have the association identifier. 562 If all data in a single message has been delivered, MSG_EOR will be 563 set in the msg_flags field of the msghdr structure (see Section 5.1). 565 If the application does not provide enough buffer space to completely 566 receive a data message, MSG_EOR will not be set in msg_flags. 567 Successive reads will consume more of the same message until the 568 entire message has been delivered, and MSG_EOR will be set. 570 If the SCTP stack is running low on buffers, it may partially deliver 571 a message. In this case, MSG_EOR will not be set, and more calls to 572 recvmsg() will be necessary to completely consume the message. Only 573 one message at a time can be partially delivered in any stream. The 574 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 575 what interlacing of messages occurs for both the one-to-one and the 576 one-to-many model sockets. Please consult Section 8.1.20 for further 577 details on message delivery options. 579 3.1.5. close() 581 Applications use close() to perform graceful shutdown (as described 582 in Section 10.1 of [RFC4960]) on all the associations currently 583 represented by a one-to-many style socket. 585 The function prototype is 587 int close(int sd); 589 and the argument is 591 sd: The socket descriptor of the associations to be closed. 593 0 is returned on success and -1 in case of an error. 595 To gracefully shutdown a specific association represented by the one- 596 to-many style socket, an application should use the sendmsg() call, 597 and include the SCTP_EOF flag. A user may optionally terminate an 598 association non-gracefully by sending with the SCTP_ABORT flag set 599 and possibly passing a user specified abort code in the data field. 600 Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data 601 (see Section 5.3.4) in the sendmsg() call. 603 If sd in the close() call is a branched-off socket representing only 604 one association, the shutdown is performed on that association only. 606 3.1.6. connect() 608 An application may use the connect() call in the one-to-many style to 609 initiate an association without sending data. 611 The function prototype is 613 int connect(int sd, 614 const struct sockaddr *nam, 615 socklen_t len); 617 and the arguments are 619 sd: The socket descriptor to have a new association added to. 621 nam: The address structure (struct sockaddr_in for an IPv4 address 622 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 624 len: The size of the address. 626 0 is returned on success and -1 in case of an error. 628 Multiple connect() calls can be made on the same socket to create 629 multiple associations. This is different from the semantics of 630 connect() on a UDP socket. 632 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 633 during the association set up phase. If an application wants to do 634 this, it cannot use the connect() call. Instead, it should use 635 sendto() or sendmsg() to initiate an association. If it uses 636 sendto() and it wants to change the initialization behavior, it needs 637 to use the SCTP_INITMSG socket option before calling sendto(). Or it 638 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 639 association without calling setsockopt(). Note that the implicit 640 setup is supported for the one-to-many style sockets. 642 SCTP does not support half close semantics. This means that unlike 643 T/TCP, MSG_EOF should not be set in the flags parameter when calling 644 sendto() or sendmsg() when the call is used to initiate a connection. 645 MSG_EOF is not an acceptable flag with an SCTP socket. 647 3.2. Non-blocking mode 649 Some SCTP application may wish to avoid being blocked when calling a 650 socket interface function. 652 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 653 one-to-many style socket, an application may set the non-blocking 654 option by a fcntl() (such as O_NONBLOCK). After setting the socket 655 to non-blocking mode, the sendmsg() function returns immediately. 656 The success or failure of sending the data message (with possible 657 SCTP_INITMSG ancillary data) will be signaled by the 658 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or SCTP_CANT_START_ASSOC. 659 If user data could not be sent (due to a SCTP_CANT_START_ASSOC), the 660 sender will also receive an SCTP_SEND_FAILED_EVENT event. Events can 661 be received by the user calling recvmsg(). A server (having called 662 listen()) is also notified of an association up event by the 663 reception of an SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling 664 of recvmsg() and possibly the reception of the first data message. 666 To shutdown the association gracefully, the user must call sendmsg() 667 with no data and with the SCTP_EOF flag set as described in 668 Section 5.3.4. The function returns immediately, and completion of 669 the graceful shutdown is indicated by an SCTP_ASSOC_CHANGE 670 notification of type SHUTDOWN_COMPLETE (see Section 6.1.1). Note 671 that this can also be done using the sctp_sendv() call described in 672 Section 9.12. 674 An application is recommended to use caution when using select() (or 675 poll()) for writing on a one-to-many style socket. The reason being 676 that the interpretation of select on write is implementation 677 specific. Generally a positive return on a select on write would 678 only indicate that one of the associations represented by the one-to- 679 many socket is writable. An application that writes after the 680 select() returns may still block since the association that was 681 writeable is not the destination association of the write call. 682 Likewise select() (or poll()) for reading from a one-to-many socket 683 will only return an indication that one of the associations 684 represented by the socket has data to be read. 686 An application that wishes to know that a particular association is 687 ready for reading or writing should either use the one-to-one style 688 or use the sctp_peeloff() (see Section 9.2) function to separate the 689 association of interest from the one-to-many socket. 691 Note some implementations may have an extended select call such as 692 epoll or kqueue that may escape this limitation and allow a select on 693 a specific association of a one-to-many socket, but this is an 694 implementation specific detail that a portable application cannot 695 depend on. 697 3.3. Special considerations 699 The fact that a one-to-many style socket can provide access to many 700 SCTP associations through a single socket descriptor, has important 701 implications for both application programmers and system programmers 702 implementing this API. A key issue is how buffer space inside the 703 sockets layer is managed. Because this implementation detail 704 directly affects how application programmers must write their code to 705 ensure correct operation and portability, this section provides some 706 guidance to both implementers and application programmers. 708 An important feature that SCTP shares with TCP is flow control. 709 Specifically, a sender may not send data faster than the receiver can 710 consume it. 712 For TCP, flow control is typically provided for in the sockets API as 713 follows. If the reader stops reading, the sender queues messages in 714 the socket layer until the send socket buffer is completely filled. 715 This results in a "stalled connection". Further attempts to write to 716 the socket will block or return the error EAGAIN or EWOULDBLOCK for a 717 non-blocking socket. At some point, either the connection is closed, 718 or the receiver begins to read again freeing space in the output 719 queue. 721 For one-to-one style SCTP sockets (this includes sockets descriptors 722 that were separated from a one-to-many style socket with 723 sctp_peeloff()) the behavior is identical. For one-to-many style 724 SCTP sockets there are multiple associations for a single socket, 725 which makes the situation more complicated. If the implementation 726 uses a single buffer space allocation shared by all associations, a 727 single stalled association can prevent the further sending of data on 728 all associations active on a particular one-to-many style socket. 730 For a blocking socket, it should be clear that a single stalled 731 association can block the entire socket. For this reason, 732 application programmers may want to use non-blocking one-to-many 733 style sockets. The application should at least be able to send 734 messages to the non-stalled associations. 736 But a non-blocking socket is not sufficient if the API implementer 737 has chosen a single shared buffer allocation for the socket. A 738 single stalled association would eventually cause the shared 739 allocation to fill, and it would become impossible to send even to 740 non-stalled associations. 742 The API implementer can solve this problem by providing each 743 association with its own allocation of outbound buffer space. Each 744 association should conceptually have as much buffer space as it would 745 have if it had its own socket. As a bonus, this simplifies the 746 implementation of sctp_peeloff(). 748 To ensure that a given stalled association will not prevent other 749 non-stalled associations from being writable, application programmers 750 should either: 752 o demand that the underlying implementation dedicates independent 753 buffer space reservation to each association (as suggested above), 754 or 756 o verify that their application layer protocol does not permit large 757 amounts of unread data at the receiver (this is true of some 758 request-response protocols, for example), or 760 o use one-to-one style sockets for association which may potentially 761 stall (either from the beginning, or by using sctp_peeloff before 762 sending large amounts of data that may cause a stalled condition). 764 4. One-to-One Style Interface 766 The goal of this style is to follow as closely as possible the 767 current practice of using the sockets interface for a connection 768 oriented protocol, such as TCP. This style enables existing 769 applications using connection oriented protocols to be ported to SCTP 770 with very little effort. 772 One-to-one style sockets can be connected (explicitly or implicitly) 773 at most once, similar to TCP sockets. 775 Note that some new SCTP features and some new SCTP socket options can 776 only be utilized through the use of sendmsg() and recvmsg() calls, 777 see Section 4.1.8. 779 4.1. Basic Operation 781 A typical server in one-to-one style uses the following system call 782 sequence to prepare an SCTP endpoint for servicing requests: 784 o socket() 786 o bind() 788 o listen() 790 o accept() 792 The accept() call blocks until a new association is set up. It 793 returns with a new socket descriptor. The server then uses the new 794 socket descriptor to communicate with the client, using recv() and 795 send() calls to get requests and send back responses. 797 Then it calls 799 o close() 801 to terminate the association. 803 A typical client uses the following system call sequence to setup an 804 association with a server to request services: 806 o socket() 808 o connect() 810 After returning from connect(), the client uses send()/sendmsg() and 811 recv()/recvmsg() calls to send out requests and receive responses 812 from the server. 814 The client calls 816 o close() 818 to terminate this association when done. 820 4.1.1. socket() 822 Applications call socket() to create a socket descriptor to represent 823 an SCTP endpoint. 825 The function prototype is 827 int socket(int domain, 828 int type, 829 int protocol); 831 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 832 type and IPPROTO_SCTP as the protocol. 834 Here, SOCK_STREAM indicates the creation of a one-to-one style 835 socket. 837 Using the PF_INET domain indicates the creation of an endpoint which 838 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 839 can use both IPv6 and IPv4 addresses. 841 4.1.2. bind() 843 Applications use bind() to specify which local address and port the 844 SCTP endpoint should associate itself with. 846 An SCTP endpoint can be associated with multiple addresses. To do 847 this, sctp_bindx() is introduced in Section 9.1 to help applications 848 do the job of associating multiple addresses. But note that an 849 endpoint can only be associated with one local port. 851 These addresses associated with a socket are the eligible transport 852 addresses for the endpoint to send and receive data. The endpoint 853 will also present these addresses to its peers during the association 854 initialization process, see [RFC4960]. 856 The function prototype of bind() is 858 int bind(int sd, 859 struct sockaddr *addr, 860 socklen_t addrlen); 862 and the arguments are 864 sd: The socket descriptor returned by socket(). 866 addr: The address structure (struct sockaddr_in for an IPv4 address 867 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 869 addrlen: The size of the address structure. 871 If sd is an IPv4 socket, the address passed must be an IPv4 address. 872 If sd is an IPv6 socket, the address passed can either be an IPv4 or 873 an IPv6 address. 875 Applications cannot call bind() multiple times to associate multiple 876 addresses to the endpoint. After the first call to bind(), all 877 subsequent calls will return an error. 879 If the IP address part of addr is specified as a wildcard (INADDR_ANY 880 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 881 IPv6 address), the operating system will associate the endpoint with 882 an optimal address set of the available interfaces. If the IPv4 883 sin_port or IPv6 sin6_port is set to 0, the operating system will 884 choose an ephemeral port for the endpoint. 886 If a bind() is not called prior to the connect() call, the system 887 picks an ephemeral port and will choose an address set equivalent to 888 binding with a wildcard address. One of these addresses will be the 889 primary address for the association. This automatically enables the 890 multi-homing capability of SCTP. 892 The completion of this bind() process does not allow the SCTP 893 endpoint to accept inbound SCTP association requests. Until a 894 listen() system call, described below, is performed on the socket, 895 the SCTP endpoint will promptly reject an inbound SCTP INIT request 896 with an SCTP ABORT. 898 4.1.3. listen() 900 Applications use listen() to allow the SCTP endpoint to accept 901 inbound associations. 903 The function prototype is 905 int listen(int sd, 906 int backlog); 908 and the arguments are 910 sd: the socket descriptor of the SCTP endpoint. 912 backlog: this specifies the max number of outstanding associations 913 allowed in the socket's accept queue. These are the associations 914 that have finished the four-way initiation handshake (see Section 915 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 916 of '0' indicates that the caller no longer wishes to receive new 917 associations. 919 It returns 0 on success an -1 in case of an error. 921 4.1.4. accept() 923 Applications use the accept() call to remove an established SCTP 924 association from the accept queue of the endpoint. A new socket 925 descriptor will be returned from accept() to represent the newly 926 formed association. 928 The function prototype is 930 int accept(int sd, 931 struct sockaddr *addr, 932 socklen_t *addrlen); 934 and the arguments are 936 sd: The listening socket descriptor. 938 addr: On return, addr (struct sockaddr_in for an IPv4 address or 939 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 940 contain the primary address of the peer endpoint. 942 addrlen: On return, addrlen will contain the size of addr. 944 The function returns the socket descriptor for the newly formed 945 association on success and -1 in case of an error. 947 4.1.5. connect() 949 Applications use connect() to initiate an association to a peer. 951 The function prototype is 953 int connect(int sd, 954 const struct sockaddr *addr, 955 socklen_t addrlen); 957 and the arguments are 959 sd: The socket descriptor of the endpoint. 961 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 962 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 964 addrlen: The size of the address. 966 It returns 0 on success and -1 on error. 968 This operation corresponds to the ASSOCIATE primitive described in 969 Section 10.1 of [RFC4960]. 971 The number of outbound streams the new association has is stack 972 dependent. Applications can use the SCTP_INITMSG option described in 973 Section 8.1.3 before connecting to change the number of outbound 974 streams. 976 If a bind() is not called prior to the connect() call, the system 977 picks an ephemeral port and will choose an address set equivalent to 978 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 979 respectively. One of the addresses will be the primary address for 980 the association. This automatically enables the multi-homing 981 capability of SCTP. 983 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 984 during the association set up phase. If an application wants to do 985 this, it cannot use the connect() call. Instead, it should use 986 sendto() or sendmsg() to initiate an association. If it uses 987 sendto() and it wants to change the initialization behavior, it needs 988 to use the SCTP_INITMSG socket option before calling sendto(). Or it 989 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 990 association without calling setsockopt(). Note that the implicit 991 setup is supported for the one-to-one style sockets. 993 SCTP does not support half close semantics. This means that unlike 994 T/TCP, MSG_EOF should not be set in the flags parameter when calling 995 sendto() or sendmsg() when the call is used to initiate a connection. 996 MSG_EOF is not an acceptable flag with an SCTP socket. 998 4.1.6. close() 1000 Applications use close() to gracefully close down an association. 1002 The function prototype is 1004 int close(int sd); 1006 and the argument is 1008 sd: The socket descriptor of the association to be closed. 1010 It returns 0 on success and -1 in case of an error. 1012 After an application calls close() on a socket descriptor, no further 1013 socket operations will succeed on that descriptor. 1015 4.1.7. shutdown() 1017 SCTP differs from TCP in that it does not have half closed semantics. 1018 Hence the shutdown() call for SCTP is an approximation of the TCP 1019 shutdown() call, and solves some different problems. Full TCP- 1020 compatibility is not provided, so developers porting TCP applications 1021 to SCTP may need to recode sections that use shutdown(). (Note that 1022 it is possible to achieve the same results as half close in SCTP 1023 using SCTP streams.) 1025 The function prototype is 1027 int shutdown(int sd, 1028 int how); 1030 and the arguments are 1032 sd: The socket descriptor of the association to be closed. 1034 how: Specifies the type of shutdown. The values are as follows: 1036 SHUT_RD: Disables further receive operations. No SCTP protocol 1037 action is taken. 1039 SHUT_WR: Disables further send operations, and initiates the SCTP 1040 shutdown sequence. 1042 SHUT_RDWR: Disables further send and receive operations and 1043 initiates the SCTP shutdown sequence. 1045 It returns 0 on success and -1 in case of an error. 1047 The major difference between SCTP and TCP shutdown() is that SCTP 1048 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 1049 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 1050 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 1051 the SCTP association while still leaving the socket descriptor open. 1052 This allows the caller to receive back any data which SCTP is unable 1053 to deliver (see Section 6.1.4 for more information) and receive event 1054 notifications. 1056 To perform the ABORT operation described in [RFC4960] Section 10.1, 1057 an application can use the socket option SO_LINGER. It is described 1058 in Section 8.1.4. 1060 4.1.8. sendmsg() and recvmsg() 1062 With a one-to-one style socket, the application can also use 1063 sendmsg() and recvmsg() to transmit data to and receive data from its 1064 peer. The semantics is similar to those used in the one-to-many 1065 style (see Section 3.1.4), with the following differences: 1067 1. When sending, the msg_name field in the msghdr is not used to 1068 specify the intended receiver, rather it is used to indicate a 1069 preferred peer address if the sender wishes to discourage the 1070 stack from sending the message to the primary address of the 1071 receiver. If the socket is connected and the transport address 1072 given is not part of the current association, the data will not 1073 be sent and an SCTP_SEND_FAILED_EVENT event will be delivered to 1074 the application if send failure events are enabled. 1076 2. Using sendmsg() on a non-connected one-to-one style socket for 1077 implicit connection setup may or may not work depending on the 1078 SCTP implementation. 1080 4.1.9. getpeername() 1082 Applications use getpeername() to retrieve the primary socket address 1083 of the peer. This call is for TCP compatibility, and is not multi- 1084 homed. It may not work with one-to-many style sockets depending on 1085 the implementation. See Section 9.3 for a multi-homed style version 1086 of the call. 1088 The function prototype is 1090 int getpeername(int sd, 1091 struct sockaddr *address, 1092 socklen_t *len); 1094 and the arguments are: 1096 sd: The socket descriptor to be queried. 1098 address: On return, the peer primary address is stored in this 1099 buffer. If the socket is an IPv4 socket, the address will be 1100 IPv4. If the socket is an IPv6 socket, the address will be either 1101 an IPv6 or IPv4 address. 1103 len: The caller should set the length of address here. On return, 1104 this is set to the length of the returned address. 1106 It returns 0 on success and -1 in case of an error. 1108 If the actual length of the address is greater than the length of the 1109 supplied sockaddr structure, the stored address will be truncated. 1111 5. Data Structures 1113 This section discusses important data structures which are specific 1114 to SCTP and are used with sendmsg() and recvmsg() calls to control 1115 SCTP endpoint operations and to access ancillary information and 1116 notifications. 1118 5.1. The msghdr and cmsghdr Structures 1120 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1121 well as the ancillary data carried in the structure, is the key for 1122 the application to set and get various control information from the 1123 SCTP endpoint. 1125 The msghdr and the related cmsghdr structures are defined and 1126 discussed in detail in [RFC3542]. They are defined as: 1128 struct msghdr { 1129 void *msg_name; /* ptr to socket address structure */ 1130 socklen_t msg_namelen; /* size of socket address structure */ 1131 struct iovec *msg_iov; /* scatter/gather array */ 1132 int msg_iovlen; /* # elements in msg_iov */ 1133 void *msg_control; /* ancillary data */ 1134 socklen_t msg_controllen; /* ancillary data buffer length */ 1135 int msg_flags; /* flags on received message */ 1136 }; 1138 struct cmsghdr { 1139 socklen_t cmsg_len; /* #bytes, including this header */ 1140 int cmsg_level; /* originating protocol */ 1141 int cmsg_type; /* protocol-specific type */ 1142 /* followed by unsigned char cmsg_data[]; */ 1143 }; 1145 In the msghdr structure, the usage of msg_name has been discussed in 1146 previous sections (see Section 3.1.4 and Section 4.1.8). 1148 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1149 field) are treated by SCTP as a single user message for both 1150 sendmsg() and recvmsg(). 1152 SCTP stack uses the ancillary data (msg_control field) to communicate 1153 the attributes, such as SCTP_RCVINFO, of the message stored in 1154 msg_iov to the socket end point. The different ancillary data types 1155 are described in Section 5.3. 1157 The msg_flags are not used when sending a message with sendmsg(). 1159 If a notification has arrived, recvmsg() will return the notification 1160 in msg_iov field and set MSG_NOTIFICATION flag in msg_flags. If the 1161 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1162 Section 6 for more information about notifications. 1164 If all portions of a data frame or notification have been read, 1165 recvmsg() will return with MSG_EOR set in msg_flags. 1167 5.2. Ancillary Data Considerations and Semantics 1169 Programming with ancillary socket data (msg_control) contains some 1170 subtleties and pitfalls, which are discussed below. 1172 5.2.1. Multiple Items and Ordering 1174 Multiple ancillary data items may be included in any call to 1175 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP, 1176 such as IP level items, or both. 1178 The ordering of ancillary data items (either by SCTP or another 1179 protocol) is not significant and is implementation-dependent, so 1180 applications must not depend on any ordering. 1182 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 1183 correspond to the data in the msghdr's msg_iov member. There can be 1184 only one single such type ancillary data for each sendmsg() or 1185 recvmsg() call. 1187 5.2.2. Accessing and Manipulating Ancillary Data 1189 Applications can infer the presence of data or ancillary data by 1190 examining the msg_iovlen and msg_controllen msghdr members, 1191 respectively. 1193 Implementations may have different padding requirements for ancillary 1194 data, so portable applications should make use of the macros 1195 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1196 [RFC3542] and the SCTP implementation's documentation for more 1197 information. The following is an example, from [RFC3542], 1198 demonstrating the use of these macros to access ancillary data: 1200 struct msghdr msg; 1201 struct cmsghdr *cmsgptr; 1203 /* fill in msg */ 1205 /* call recvmsg() */ 1207 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1208 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1209 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1210 u_char *ptr; 1212 ptr = CMSG_DATA(cmsgptr); 1213 /* process data pointed to by ptr */ 1214 } 1215 } 1217 5.2.3. Control Message Buffer Sizing 1219 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1220 ancillary data will often be fundamental to the correct and sane 1221 operation of the sockets application. This is particularly true of 1222 the one-to-many semantics, but also of the one-to-one semantics. For 1223 example, if an application needs to send and receive data on 1224 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1225 ancillary data is indispensable. 1227 Given that some ancillary data is critical, and that multiple 1228 ancillary data items may appear in any order, applications should be 1229 carefully written to always provide a large enough buffer to contain 1230 all possible ancillary data that can be presented by recvmsg(). If 1231 the buffer is too small, and crucial data is truncated, it may pose a 1232 fatal error condition. 1234 Thus, it is essential that applications be able to deterministically 1235 calculate the maximum required buffer size to pass to recvmsg(). One 1236 constraint imposed on this specification that makes this possible is 1237 that all ancillary data definitions are of a fixed length. One way 1238 to calculate the maximum required buffer size might be to take the 1239 sum the sizes of all enabled ancillary data item structures, as 1240 calculated by CMSG_SPACE. For example, if we enabled 1241 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 1242 and allocate the buffer size as follows: 1244 size_t total; 1245 void *buf; 1247 total = CMSG_SPACE(sizeof(struct sctp_sndrcvinfo)) + 1248 CMSG_SPACE(sizeof(struct in6_pktinfo)); 1250 buf = malloc(total); 1252 We could then use this buffer (buf) for msg_control on each call to 1253 recvmsg() and be assured that we would not lose any ancillary data to 1254 truncation. 1256 5.3. SCTP msg_control Structures 1258 A key element of all SCTP specific socket extensions is the use of 1259 ancillary data to specify and access SCTP specific data via the 1260 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1261 Fine-grained control over initialization and sending parameters are 1262 handled with ancillary data. 1264 Each ancillary data item is proceeded by a struct cmsghdr (see 1265 Section 5.1), which defines the function and purpose of the data 1266 contained in the cmsg_data[] member. 1268 By default on either style socket, SCTP will pass no ancillary data; 1269 Specific ancillary data items can be enabled with socket options 1270 defined for SCTP; see Section 6.2. 1272 Note that all ancillary types are fixed length; see Section 5.2 for 1273 further discussion on this. These data structures use struct 1274 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1275 address format. 1277 Other protocols may also provide ancillary data to the socket layer 1278 consumer. These ancillary data items from other protocols may 1279 intermingle with SCTP data. For example, the IPv6 socket API 1280 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1281 data items. If a socket API consumer enables delivery of both SCTP 1282 and IPv6 ancillary data, they both may appear in the same msg_control 1283 buffer in any order. An application may thus need to handle other 1284 types of ancillary data besides those passed by SCTP. 1286 The sockets application must provide a buffer large enough to 1287 accommodate all ancillary data provided via recvmsg(). If the buffer 1288 is not large enough, the ancillary data will be truncated and the 1289 msghdr's msg_flags will include MSG_CTRUNC. 1291 5.3.1. SCTP Initiation Structure (SCTP_INIT) 1293 This cmsghdr structure provides information for initializing new SCTP 1294 associations with sendmsg(). The SCTP_INITMSG socket option uses 1295 this same data structure. This structure is not used for recvmsg(). 1297 +--------------+-----------+---------------------+ 1298 | cmsg_level | cmsg_type | cmsg_data[] | 1299 +--------------+-----------+---------------------+ 1300 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1301 +--------------+-----------+---------------------+ 1303 The sctp_initmsg structure is defined below: 1305 struct sctp_initmsg { 1306 uint16_t sinit_num_ostreams; 1307 uint16_t sinit_max_instreams; 1308 uint16_t sinit_max_attempts; 1309 uint16_t sinit_max_init_timeo; 1310 }; 1312 sinit_num_ostreams: This is an integer number representing the 1313 number of streams that the application wishes to be able to send 1314 to. This number is confirmed in the SCTP_COMM_UP notification and 1315 must be verified since it is a negotiated number with the remote 1316 endpoint. The default value of 0 indicates to use the endpoint 1317 default value. 1319 sinit_max_instreams: This value represents the maximum number of 1320 inbound streams the application is prepared to support. This 1321 value is bounded by the actual implementation. In other words the 1322 user may be able to support more streams than the Operating 1323 System. In such a case, the Operating System limit overrides the 1324 value requested by the user. The default value of 0 indicates to 1325 use the endpoints default value. 1327 sinit_max_attempts: This integer specifies how many attempts the 1328 SCTP endpoint should make at resending the INIT. This value 1329 overrides the system SCTP 'Max.Init.Retransmits' value. The 1330 default value of 0 indicates to use the endpoints default value. 1331 This is normally set to the system's default 'Max.Init.Retransmit' 1332 value. 1334 sinit_max_init_timeo: This value represents the largest Time-Out or 1335 RTO value (in milliseconds) to use in attempting an INIT. 1336 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1337 upon timeout. For the INIT message this value may override 1338 'RTO.Max'. This value must not influence 'RTO.Max' during data 1339 transmission and is only used to bound the initial setup time. A 1340 default value of 0 indicates to use the endpoints default value. 1341 This is normally set to the system's 'RTO.Max' value (60 seconds). 1343 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - DEPRECATED 1345 This cmsghdr structure specifies SCTP options for sendmsg() and 1346 describes SCTP header information about a received message through 1347 recvmsg(). This structure mixes the send and receive path. 1348 SCTP_SNDINFO described in Section 5.3.4 and SCTP_RCVINFO described in 1349 Section 5.3.5 split this information. These structures should be 1350 used, when possible, since SCTP_SNDRCV is deprecated. 1352 +--------------+-------------+------------------------+ 1353 | cmsg_level | cmsg_type | cmsg_data[] | 1354 +--------------+-------------+------------------------+ 1355 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1356 +--------------+-------------+------------------------+ 1358 The sctp_sndrcvinfo structure is defined below: 1360 struct sctp_sndrcvinfo { 1361 uint16_t sinfo_stream; 1362 uint16_t sinfo_ssn; 1363 uint16_t sinfo_flags; 1364 uint32_t sinfo_ppid; 1365 uint32_t sinfo_context; 1366 uint32_t sinfo_timetolive; 1367 uint32_t sinfo_tsn; 1368 uint32_t sinfo_cumtsn; 1369 sctp_assoc_t sinfo_assoc_id; 1370 }; 1372 sinfo_stream: For recvmsg() the SCTP stack places the message's 1373 stream number in this value. For sendmsg() this value holds the 1374 stream number that the application wishes to send this message to. 1375 If a sender specifies an invalid stream number an error indication 1376 is returned and the call fails. 1378 sinfo_ssn: For recvmsg() this value contains the stream sequence 1379 number that the remote endpoint placed in the DATA chunk. For 1380 fragmented messages this is the same number for all deliveries of 1381 the message (if more than one recvmsg() is needed to read the 1382 message). The sendmsg() call will ignore this parameter. 1384 sinfo_flags: This field may contain any of the following flags and 1385 is composed of a bitwise OR of these values. 1387 recvmsg() flags: 1389 SCTP_UNORDERED: This flag is present when the message was sent 1390 un-ordered. 1392 sendmsg() flags: 1394 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1395 the message. If this flag is clear the datagram is 1396 considered an ordered send. 1398 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1399 the SCTP stack to override the primary destination address 1400 with the address found with the sendto/sendmsg call. 1402 SCTP_ABORT: Setting this flag causes the specified association 1403 to abort by sending an ABORT message to the peer. The ABORT 1404 chunk will contain an error cause 'User Initiated Abort' 1405 with cause code 12. The cause specific information of this 1406 error cause is provided in msg_iov. 1408 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1409 procedure on the specified association. Graceful shutdown 1410 assures that all data queued by both endpoints is 1411 successfully transmitted before closing the association. 1413 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1414 model socket to send the message to all associations that 1415 are currently established on this socket. For the one-to- 1416 one socket, this flag has no effect. 1418 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1419 passed to the remote end in each user message. In recvmsg() this 1420 value is the same information that was passed by the upper layer 1421 in the peer application. Please note that the SCTP stack performs 1422 no byte order modification of this field. For example, if the 1423 DATA chunk has to contain a given value in network byte order, the 1424 SCTP user has to perform the htonl() computation. 1426 sinfo_context: This value is an opaque 32 bit context datum that is 1427 used in the sendmsg() function. This value is passed back to the 1428 upper layer if an error occurs on the send of a message and is 1429 retrieved with each undelivered message. 1431 sinfo_timetolive: For the sending side, this field contains the 1432 message time to live in milliseconds. The sending side will 1433 expire the message within the specified time period if the message 1434 as not been sent to the peer within this time period. This value 1435 will override any default value set using any socket option. Also 1436 note that the value of 0 is special in that it indicates no 1437 timeout should occur on this message. 1439 sinfo_tsn: For the receiving side, this field holds a TSN that was 1440 assigned to one of the SCTP Data Chunks. For the sending side it 1441 is ignored. 1443 sinfo_cumtsn: This field will hold the current cumulative TSN as 1444 known by the underlying SCTP layer. Note this field is ignored 1445 when sending. 1447 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1448 the identifier for the association announced in the SCTP_COMM_UP 1449 notification. All notifications for a given association have the 1450 same identifier. Ignored for one-to-one style sockets. 1452 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1454 5.3.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) - 1455 DEPRECATED 1457 This cmsghdr structure specifies SCTP options for SCTP header 1458 information about a received message via recvmsg(). Note that this 1459 structure is an extended version of SCTP_SNDRCV (see Section 5.3.2) 1460 and will only be received if the user has set the socket option 1461 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1462 needed to receive ancillary data. See Section 8.1.22 on this socket 1463 option. Note that next message data is not valid unless the current 1464 message is completely read, i.e. the MSG_EOR is set, in other words 1465 if the application has more data to read from the current message 1466 then no next message information will be available. 1468 SCTP_NXTINFO described in Section 5.3.6 should be used when possible, 1469 since SCTP_EXTRCV is considered deprecated. 1471 +--------------+-------------+------------------------+ 1472 | cmsg_level | cmsg_type | cmsg_data[] | 1473 +--------------+-------------+------------------------+ 1474 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1475 +--------------+-------------+------------------------+ 1477 The sctp_extrcvinfo structure is defined below: 1479 struct sctp_extrcvinfo { 1480 uint16_t sinfo_stream; 1481 uint16_t sinfo_ssn; 1482 uint16_t sinfo_flags; 1483 uint32_t sinfo_ppid; 1484 uint32_t sinfo_context; 1485 uint32_t sinfo_pr_value; 1486 uint32_t sinfo_tsn; 1487 uint32_t sinfo_cumtsn; 1488 uint16_t serinfo_next_flags; 1489 uint16_t serinfo_next_stream; 1490 uint32_t serinfo_next_aid; 1491 uint32_t serinfo_next_length; 1492 uint32_t serinfo_next_ppid; 1493 sctp_assoc_t sinfo_assoc_id; 1494 }; 1496 sinfo_*: Please see Section 5.3.2 for the details for these fields. 1498 serinfo_next_flags: This bitmask will hold one or more of the 1499 following values: 1501 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1502 message information is available i.e.: next_stream, 1503 next_asocid, next_length and next_ppid fields all have valid 1504 values. If this bit is set to 0, then these fields are not 1505 valid and should be ignored. 1507 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1508 next message is completely in the receive buffer. The 1509 next_length field thus contains the entire message size. If 1510 this flag is set to 0, then the next_length field only contains 1511 part of the message size since the message is still being 1512 received (it is being partially delivered). 1514 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1515 the next message to be received was sent by the peer as 1516 unordered. If this bit is not set (i.e. the bit is 0) the next 1517 message to be read is an ordered message in the stream 1518 specified. 1520 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1521 the next message to be received is not a message from the peer, 1522 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1524 serinfo_next_stream: This value, when valid (see 1525 serinfo_next_flags), contains the next stream number that will be 1526 received on a subsequent call to one of the receive message 1527 functions. 1529 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1530 contains the next association identifier that will be received on 1531 a subsequent call to one of the receive message functions. 1533 serinfo_next_length: This value, when valid (see 1534 serinfo_next_flags), contains the length of the next message that 1535 will be received on a subsequent call to one of the receive 1536 message functions. Note that this length may be a partial length 1537 depending on the settings of next_flags. 1539 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1540 contains the ppid of the next message that will be received on a 1541 subsequent call to one of the receive message functions. 1543 5.3.4. SCTP Send Information Structure (SCTP_SNDINFO) 1545 This cmsghdr structure specifies SCTP options for sendmsg(). 1547 +--------------+--------------+---------------------+ 1548 | cmsg_level | cmsg_type | cmsg_data[] | 1549 +--------------+--------------+---------------------+ 1550 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1551 +--------------+--------------+---------------------+ 1553 The sctp_sndinfo structure is defined below: 1555 struct sctp_sndinfo { 1556 uint16_t snd_sid; 1557 uint16_t snd_flags; 1558 uint32_t snd_ppid; 1559 uint32_t snd_context; 1560 sctp_assoc_t snd_assoc_id; 1561 }; 1563 snd_sid: This value holds the stream number that the application 1564 wishes to send this message to. If a sender specifies an invalid 1565 stream number an error indication is returned and the call fails. 1567 snd_flags: This field may contain any of the following flags and is 1568 composed of a bitwise OR of these values. 1570 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1571 message. If this flag is clear the datagram is considered an 1572 ordered send. 1574 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1575 SCTP stack to override the primary destination address with the 1576 address found with the sendto()/sendmsg call. 1578 SCTP_ABORT: Setting this flag causes the specified association to 1579 abort by sending an ABORT message to the peer. The ABORT chunk 1580 will contain an error cause 'User Initiated Abort' with cause 1581 code 12. The cause specific information of this error cause is 1582 provided in msg_iov. 1584 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1585 procedures on the specified association. Graceful shutdown 1586 assures that all data queued by both endpoints is successfully 1587 transmitted before closing the association. 1589 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1590 socket to send the message to all associations that are 1591 currently established on this socket. For the one-to-one 1592 socket, this flag has no effect. 1594 snd_ppid: This value in sendmsg() is an unsigned integer that is 1595 passed to the remote end in each user message. Please note that 1596 the SCTP stack performs no byte order modification of this field. 1597 For example, if the DATA chunk has to contain a given value in 1598 network byte order, the SCTP user has to perform the htonl() 1599 computation. 1601 snd_context: This value is an opaque 32 bit context datum that is 1602 used in the sendmsg() function. This value is passed back to the 1603 upper layer if an error occurs on the send of a message and is 1604 retrieved with each undelivered message. 1606 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1607 the identifier for the association announced in the SCTP_COMM_UP 1608 notification. All notifications for a given association have the 1609 same identifier. Ignored for one-to-one style sockets. 1611 An sctp_sndinfo item always corresponds to the data in msg_iov. 1613 5.3.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1615 This cmsghdr structure describes SCTP receive information about a 1616 received message through recvmsg(). 1618 To enable the delivery of this information an application must use 1619 the SCTP_RECVRCVINFO socket option (see Section 8.1.29). 1621 +--------------+--------------+---------------------+ 1622 | cmsg_level | cmsg_type | cmsg_data[] | 1623 +--------------+--------------+---------------------+ 1624 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1625 +--------------+--------------+---------------------+ 1627 The sctp_rcvinfo structure is defined below: 1629 struct sctp_rcvinfo { 1630 uint16_t rcv_sid; 1631 uint16_t rcv_ssn; 1632 uint16_t rcv_flags; 1633 uint32_t rcv_ppid; 1634 uint32_t rcv_tsn; 1635 uint32_t rcv_cumtsn; 1636 uint32_t rcv_context; 1637 sctp_assoc_t rcv_assoc_id; 1638 }; 1639 rcv_sid: The SCTP stack places the message's stream number in this 1640 value. 1642 rcv_ssn: This value contains the stream sequence number that the 1643 remote endpoint placed in the DATA chunk. For fragmented messages 1644 this is the same number for all deliveries of the message (if more 1645 than one recvmsg() is needed to read the message). 1647 rcv_flags: This field may contain any of the following flags and is 1648 composed of a bitwise OR of these values. 1650 SCTP_UNORDERED: This flag is present when the message was sent 1651 un-ordered. 1653 rcv_ppid: This value is the same information that was passed by the 1654 upper layer in the peer application. Please note that the SCTP 1655 stack performs no byte order modification of this field. For 1656 example, if the DATA chunk has to contain a given value in network 1657 byte order, the SCTP user has to perform the ntohl() computation. 1659 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1660 Data Chunks. 1662 rcv_cumtsn: This field will hold the current cumulative TSN as known 1663 by the underlying SCTP layer. 1665 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1666 the identifier for the association announced in the SCTP_COMM_UP 1667 notification. All notifications for a given association have the 1668 same identifier. Ignored for one-to-one style sockets. 1670 rcv_context: This value is an opaque 32 bit context datum that was 1671 set by the user with the SCTP_CONTEXT socket option. This value 1672 is passed back to the upper layer if an error occurs on the send 1673 of a message and is retrieved with each undelivered message. 1675 An sctp_rcvinfo item always corresponds to the data in msg_iov. 1677 5.3.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1679 This cmsghdr structure describes SCTP receive information of the next 1680 message which will be delivered through recvmsg() if this information 1681 is already available when delivering the current message. 1683 To enable the delivery of this information an application must use 1684 the SCTP_RECVNXTINFO socket option (see Section 8.1.30). 1686 +--------------+--------------+---------------------+ 1687 | cmsg_level | cmsg_type | cmsg_data[] | 1688 +--------------+--------------+---------------------+ 1689 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_nxtinfo | 1690 +--------------+--------------+---------------------+ 1692 The sctp_nxtinfo structure is defined below: 1694 struct sctp_nxtinfo { 1695 uint16_t nxt_sid; 1696 uint16_t nxt_flags; 1697 uint32_t nxt_ppid; 1698 uint32_t nxt_length; 1699 sctp_assoc_t nxt_assoc_id; 1700 }; 1702 nxt_sid: The SCTP stack places the next message's stream number in 1703 this value. 1705 nxt_flags: This field may contain any of the following flags and is 1706 composed of a bitwise OR of these values. 1708 SCTP_UNORDERED: This flag is present when the next message was 1709 sent un-ordered. 1711 SCTP_COMPLETE: This flag indicates that the entire message has 1712 been received and is in the socket buffer. Note that this has 1713 special implications with respect to the nxt_length field, see 1714 nxt_length description below. 1716 SCTP_NOTIFICATION: This flag is present when the next message is 1717 not a user message but instead is a notification. 1719 nxt_ppid: This value is the same information that was passed by the 1720 upper layer in the peer application for the next message. Please 1721 note that the SCTP stack performs no byte order modification of 1722 this field. For example, if the DATA chunk has to contain a given 1723 value in network byte order, the SCTP user has to perform the 1724 ntohl() computation. 1726 nxt_length: This value is the length of the message currently within 1727 the socket buffer. This might NOT be the entire length of the 1728 message since a partial delivery may be in progress. Only if the 1729 flag SCTP_COMPLETE is set in the nxt_flags field does this field 1730 represent the entire next message size. 1732 nxt_assoc_id: The association handle field of the next message, 1733 nxt_assoc_id, holds the identifier for the association announced 1734 in the SCTP_COMM_UP notification. All notifications for a given 1735 association have the same identifier. Ignored for one-to-one 1736 style sockets. 1738 5.3.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1740 This cmsghdr structure specifies SCTP options for sendmsg(). 1742 +--------------+-------------+--------------------+ 1743 | cmsg_level | cmsg_type | cmsg_data[] | 1744 +--------------+-------------+--------------------+ 1745 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1746 +--------------+-------------+--------------------+ 1748 The sctp_prinfo structure is defined below: 1750 struct sctp_prinfo { 1751 uint16_t pr_policy; 1752 uint32_t pr_value; 1753 }; 1755 pr_policy: This specifies which PR-SCTP policy is used. Using 1756 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1757 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1758 defined in [RFC3758] is used. In this case, the lifetime is 1759 provided in pr_value. 1761 pr_value: The meaning of this field depends on the PR-SCTP policy 1762 specified by the pr_policy field. It is ignored when 1763 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1764 lifetime in milliseconds is specified. 1766 An sctp_prinfo item always corresponds to the data in msg_iov. 1768 5.3.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1770 This cmsghdr structure specifies SCTP options for sendmsg(). 1772 +--------------+---------------+----------------------+ 1773 | cmsg_level | cmsg_type | cmsg_data[] | 1774 +--------------+---------------+----------------------+ 1775 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1776 +--------------+---------------+----------------------+ 1778 The sctp_authinfo structure is defined below: 1780 struct sctp_authinfo { 1781 uint16_t auth_keynumber; 1782 }; 1784 auth_keynumber: This specifies the shared key identifier used for 1785 sending the user message. 1787 An sctp_authinfo item always corresponds to the data in msg_iov. 1788 Please note that the SCTP implementation must not bundle user 1789 messages that needs to be authenticated using different shared key 1790 identifiers. 1792 5.3.9. SCTP Destination IPv4 Address Structure (SCTP_DSTADDRV4) 1794 This cmsghdr structure specifies SCTP options for sendmsg(). 1796 +--------------+----------------+----------------+ 1797 | cmsg_level | cmsg_type | cmsg_data[] | 1798 +--------------+----------------+----------------+ 1799 | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | 1800 +--------------+----------------+----------------+ 1802 This ancillary data can be used to provide more than one destination 1803 address to sendmsg(). It can be used to implement sctp_sendv() using 1804 sendmsg(). 1806 5.3.10. SCTP Destination IPv6 Address Structure (SCTP_DSTADDRV6) 1808 This cmsghdr structure specifies SCTP options for sendmsg(). 1810 +--------------+----------------+-----------------+ 1811 | cmsg_level | cmsg_type | cmsg_data[] | 1812 +--------------+----------------+-----------------+ 1813 | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | 1814 +--------------+----------------+-----------------+ 1816 This ancillary data can be used to provide more than one destination 1817 address to sendmsg(). It can be used to implement sctp_sendv() using 1818 sendmsg(). 1820 6. SCTP Events and Notifications 1822 An SCTP application may need to understand and process events and 1823 errors that happen on the SCTP stack. These events include network 1824 status changes, association startups, remote operational errors and 1825 undeliverable messages. All of these can be essential for the 1826 application. 1828 When an SCTP application layer does a recvmsg() the message read is 1829 normally a data message from a peer endpoint. If the application 1830 wishes to have the SCTP stack deliver notifications of non-data 1831 events, it sets the appropriate socket option for the notifications 1832 it wants. See Section 6.2 for these socket options. When a 1833 notification arrives, recvmsg() returns the notification in the 1834 application-supplied data buffer via msg_iov, and sets 1835 MSG_NOTIFICATION in msg_flags. 1837 This section details the notification structures. Every notification 1838 structure carries some common fields which provide general 1839 information. 1841 A recvmsg() call will return only one notification at a time. Just 1842 as when reading normal data, it may return part of a notification if 1843 the msg_iov buffer is not large enough. If a single read is not 1844 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1845 reading the notification before subsequent data can arrive. 1847 6.1. SCTP Notification Structure 1849 The notification structure is defined as the union of all 1850 notification types. 1852 union sctp_notification { 1853 struct sctp_tlv { 1854 uint16_t sn_type; /* Notification type. */ 1855 uint16_t sn_flags; 1856 uint32_t sn_length; 1857 } sn_header; 1858 struct sctp_assoc_change sn_assoc_change; 1859 struct sctp_paddr_change sn_paddr_change; 1860 struct sctp_remote_error sn_remote_error; 1861 struct sctp_send_failed sn_send_failed; 1862 struct sctp_shutdown_event sn_shutdown_event; 1863 struct sctp_adaptation_event sn_adaptation_event; 1864 struct sctp_pdapi_event sn_pdapi_event; 1865 struct sctp_authkey_event sn_auth_event; 1866 struct sctp_sender_dry_event sn_sender_dry_event; 1867 struct sctp_send_failed_event sn_send_failed_event; 1868 }; 1870 sn_type: The following list describes the SCTP notification and 1871 event types for the field sn_type. 1873 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1874 either been opened or closed. Refer to Section 6.1.1 for 1875 details. 1877 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1878 part of an existing association has experienced a change of 1879 state (e.g. a failure or return to service of the reachability 1880 of an endpoint via a specific transport address). Please see 1881 Section 6.1.2 for data structure details. 1883 SCTP_REMOTE_ERROR: The attached error message is an Operational 1884 Error received from the remote peer. It includes the complete 1885 TLV sent by the remote endpoint. See Section 6.1.3 for the 1886 detailed format. 1888 SCTP_SEND_FAILED_EVENT: The attached datagram could not be sent 1889 to the remote endpoint. This structure includes the original 1890 SCTP_SNDINFO that was used in sending this message i.e. this 1891 structure uses the sctp_sndinfo per Section 6.1.11. 1893 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1894 data should be sent on this socket. 1896 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1897 indicated adaptation layer. Please see Section 6.1.6. 1899 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1900 receiver that the partial delivery has been aborted. This may 1901 indicate the association is about to be aborted. Please see 1902 Section 6.1.7. 1904 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1905 receiver that either an error occurred on authentication, or a 1906 new key was made active. See Section 6.1.8. 1908 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1909 application that the sender has no more user data queued for 1910 transmission nor retransmission. See Section 6.1.9. 1912 sn_flags: These are notification-specific flags. 1914 sn_length: This is the length of the whole sctp_notification 1915 structure including the sn_type, sn_flags, and sn_length fields. 1917 6.1.1. SCTP_ASSOC_CHANGE 1919 Communication notifications inform the application that an SCTP 1920 association has either begun or ended. The identifier for a new 1921 association is provided by this notification. The notification 1922 information has the following format: 1924 struct sctp_assoc_change { 1925 uint16_t sac_type; 1926 uint16_t sac_flags; 1927 uint32_t sac_length; 1928 uint16_t sac_state; 1929 uint16_t sac_error; 1930 uint16_t sac_outbound_streams; 1931 uint16_t sac_inbound_streams; 1932 sctp_assoc_t sac_assoc_id; 1933 uint8_t sac_info[]; 1934 }; 1936 sac_type: It should be SCTP_ASSOC_CHANGE. 1938 sac_flags: Currently unused. 1940 sac_length: This field is the total length of the notification data, 1941 including the notification header. 1943 sac_state: This field holds one of a number of values that 1944 communicate the event that happened to the association. They 1945 include: 1947 SCTP_COMM_UP: A new association is now ready and data may be 1948 exchanged with this peer. When an association has been 1949 established successfully, this notification should be the first 1950 one. 1952 SCTP_COMM_LOST: The association has failed. The association is 1953 now in the closed state. If SEND_FAILED notifications are 1954 turned on, an SCTP_COMM_LOST is accompanied by a series of 1955 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1956 message. 1958 SCTP_RESTART: SCTP has detected that the peer has restarted. 1960 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1962 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1963 blocking mode is set and data was sent (on a one-to-many style 1964 socket), an SCTP_CANT_STR_ASSOC is accompanied by a series of 1965 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1966 message. 1968 sac_error: If the state was reached due to an error condition (e.g. 1969 SCTP_COMM_LOST) any relevant error information is available in 1970 this field. This corresponds to the protocol error codes defined 1971 in [RFC4960]. 1973 sac_outbound_streams: 1975 sac_inbound_streams: The maximum number of streams allowed in each 1976 direction are available in sac_outbound_streams and sac_inbound 1977 streams. 1979 sac_assoc_id: The sac_assoc_id field holds the identifier for the 1980 association. All notifications for a given association have the 1981 same association identifier. For a one-to-one style socket, this 1982 field is ignored. 1984 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1985 received for this association, sac_info[] contains the complete 1986 ABORT chunk as defined in the SCTP specification [RFC4960] Section 1987 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1988 may contain an array of uint8_t describing the features that the 1989 current association supports. Features may include 1991 SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol 1992 extension described in [RFC3758]. 1994 SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol 1995 extension described in [RFC4895]. 1997 SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol 1998 extension described in [RFC5061]. 2000 SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the 2001 local endpoints use separate send and/or receive buffers for 2002 each SCTP association. 2004 6.1.2. SCTP_PEER_ADDR_CHANGE 2006 When a destination address of a multi-homed peer encounters a state 2007 change a peer address change event is sent. The notification has the 2008 following format: 2010 struct sctp_paddr_change { 2011 uint16_t spc_type; 2012 uint16_t spc_flags; 2013 uint32_t spc_length; 2014 struct sockaddr_storage spc_aaddr; 2015 uint32_t spc_state; 2016 uint32_t spc_error; 2017 sctp_assoc_t spc_assoc_id; 2018 } 2020 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 2022 spc_flags: Currently unused. 2024 spc_length: This field is the total length of the notification data, 2025 including the notification header. 2027 spc_aaddr: The affected address field holds the remote peer's 2028 address that is encountering the change of state. 2030 spc_state: This field holds one of a number of values that 2031 communicate the event that happened to the address. They include: 2033 SCTP_ADDR_AVAILABLE: This address is now reachable. This 2034 notification is provided whenever an address becomes reachable. 2036 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 2037 reached. Any data sent to this address is rerouted to an 2038 alternate until this address becomes reachable. This 2039 notification is provided whenever an address becomes 2040 unreachable. 2042 SCTP_ADDR_REMOVED: The address is no longer part of the 2043 association. 2045 SCTP_ADDR_ADDED: The address is now part of the association. 2047 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 2048 primary destination address. This notification is provided 2049 whenever an address is made primary. 2051 spc_error: If the state was reached due to any error condition (e.g. 2052 SCTP_ADDR_UNREACHABLE) any relevant error information is available 2053 in this field. 2055 spc_assoc_id: The spc_assoc_id field holds the identifier for the 2056 association. All notifications for a given association have the 2057 same association identifier. For a one-to-one style socket, this 2058 field is ignored. 2060 6.1.3. SCTP_REMOTE_ERROR 2062 A remote peer may send an Operational Error message to its peer. 2063 This message indicates a variety of error conditions on an 2064 association. The entire ERROR chunk as it appears on the wire is 2065 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 2066 specification [RFC4960] and any extensions for a list of possible 2067 error formats. An SCTP error notification has the following format: 2069 struct sctp_remote_error { 2070 uint16_t sre_type; 2071 uint16_t sre_flags; 2072 uint32_t sre_length; 2073 uint16_t sre_error; 2074 sctp_assoc_t sre_assoc_id; 2075 uint8_t sre_data[]; 2076 }; 2078 sre_type: It should be SCTP_REMOTE_ERROR. 2080 sre_flags: Currently unused. 2082 sre_length: This field is the total length of the notification data, 2083 including the notification header and the contents of sre_data. 2085 sre_error: This value represents one of the Operational Error causes 2086 defined in the SCTP specification, in network byte order. 2088 sre_assoc_id: The sre_assoc_id field holds the identifier for the 2089 association. All notifications for a given association have the 2090 same association identifier. For a one-to-one style socket, this 2091 field is ignored. 2093 sre_data: This contains the ERROR chunk as defined in the SCTP 2094 specification [RFC4960] Section 3.3.10. 2096 6.1.4. SCTP_SEND_FAILED - DEPRECATED 2098 Please note that this notification is deprecated. Use 2099 SCTP_SEND_FAILED_EVENT instead. 2101 If SCTP cannot deliver a message, it can return back the message as a 2102 notification if the SCTP_SEND_FAILED event is enabled. The 2103 notification has the following format: 2105 struct sctp_send_failed { 2106 uint16_t ssf_type; 2107 uint16_t ssf_flags; 2108 uint32_t ssf_length; 2109 uint32_t ssf_error; 2110 struct sctp_sndrcvinfo ssf_info; 2111 sctp_assoc_t ssf_assoc_id; 2112 uint8_t ssf_data[]; 2113 }; 2115 ssf_type: It should be SCTP_SEND_FAILED. 2117 ssf_flags: The flag value will take one of the following values: 2119 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2120 wire. 2122 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2123 Note that this does not necessarily mean that the data was (or 2124 was not) successfully delivered. 2126 ssf_length: This field is the total length of the notification data, 2127 including the notification header and the payload in ssf_data. 2129 ssf_error: This value represents the reason why the send failed, and 2130 if set, will be an SCTP protocol error code as defined in 2131 [RFC4960] Section 3.3.10. 2133 ssf_info: The ancillary data (struct sctp_sndrcvinfo) used to send 2134 the undelivered message. Regardless of if ancillary data is used 2135 or not, the ssf_info.sinfo_flags field indicates if the complete 2136 message or only part of the message is returned in ssf_data. If 2137 only part of the message is returned, it means that the part which 2138 is not present has been sent successfully to the peer. 2140 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2141 flags is set in ssf_info.sinfo_flags. If the first part of the 2142 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2143 This means that the tail end of the message is returned in 2144 ssf_data. 2146 ssf_assoc_id: The ssf_assoc_id field, ssf_assoc_id, holds the 2147 identifier for the association. All notifications for a given 2148 association have the same association identifier. For a one-to- 2149 one style socket, this field is ignored. 2151 ssf_data: The undelivered message or part of the undelivered message 2152 will be present in the ssf_data field. Note that the 2153 ssf_info.sinfo_flags field as noted above should be used to 2154 determine if a complete message is present or just a piece of the 2155 message. Note that only user data is present in this field, any 2156 chunk headers or SCTP common headers must be removed by the SCTP 2157 stack. 2159 6.1.5. SCTP_SHUTDOWN_EVENT 2161 When a peer sends a SHUTDOWN, SCTP delivers this notification to 2162 inform the application that it should cease sending data. 2164 struct sctp_shutdown_event { 2165 uint16_t sse_type; 2166 uint16_t sse_flags; 2167 uint32_t sse_length; 2168 sctp_assoc_t sse_assoc_id; 2169 }; 2171 sse_type: It should be SCTP_SHUTDOWN_EVENT. 2173 sse_flags: Currently unused. 2175 sse_length: This field is the total length of the notification data, 2176 including the notification header. It will generally be 2177 sizeof(struct sctp_shutdown_event). 2179 sse_flags: Currently unused. 2181 sse_assoc_id: The sse_assoc_id field holds the identifier for the 2182 association. All notifications for a given association have the 2183 same association identifier. For a one-to-one style socket, this 2184 field is ignored. 2186 6.1.6. SCTP_ADAPTATION_INDICATION 2188 When a peer sends an Adaptation Layer Indication parameter as 2189 described in [RFC5061], SCTP delivers this notification to inform the 2190 application about the peer's adaptation layer indication. 2192 struct sctp_adaptation_event { 2193 uint16_t sai_type; 2194 uint16_t sai_flags; 2195 uint32_t sai_length; 2196 uint32_t sai_adaptation_ind; 2197 sctp_assoc_t sai_assoc_id; 2198 }; 2199 sai_type: It should be SCTP_ADAPTATION_INDICATION. 2201 sai_flags: Currently unused. 2203 sai_length: This field is the total length of the notification data, 2204 including the notification header. It will generally be 2205 sizeof(struct sctp_adaptation_event). 2207 sai_adaptation_ind: This field holds the bit array sent by the peer 2208 in the adaptation layer indication parameter. 2210 sai_assoc_id: The sai_assoc_id field holds the identifier for the 2211 association. All notifications for a given association have the 2212 same association identifier. For a one-to-one style socket, this 2213 field is ignored. 2215 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT 2217 When a receiver is engaged in a partial delivery of a message this 2218 notification will be used to indicate various events. 2220 struct sctp_pdapi_event { 2221 uint16_t pdapi_type; 2222 uint16_t pdapi_flags; 2223 uint32_t pdapi_length; 2224 uint32_t pdapi_indication; 2225 uint32_t pdapi_stream; 2226 uint32_t pdapi_seq; 2227 sctp_assoc_t pdapi_assoc_id; 2228 }; 2230 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 2232 pdapi_flags: Currently unused. 2234 pdapi_length: This field is the total length of the notification 2235 data, including the notification header. It will generally be 2236 sizeof(struct sctp_pdapi_event). 2238 pdapi_indication: This field holds the indication being sent to the 2239 application. Currently there is only one defined value: 2241 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 2242 delivery of a user message has been aborted. This happens, for 2243 example, if an association is aborted while a partial delivery 2244 is going on or the user message gets abandoned using PR-SCTP 2245 while the partial delivery of this message is going on. 2247 pdapi_stream: This field holds the stream on which the partial 2248 delivery event happened. 2250 pdapi_seq: This field holds the stream sequence number which was 2251 being partially delivered. 2253 pdapi_assoc_id: The pdapi_assoc_id field holds the identifier for 2254 the association. All notifications for a given association have 2255 the same association identifier. For a one-to-one style socket 2256 this field is ignored. 2258 6.1.8. SCTP_AUTHENTICATION_EVENT 2260 [RFC4895] defines an extension to authenticate SCTP messages. The 2261 following notification is used to report different events relating to 2262 the use of this extension. 2264 struct sctp_authkey_event { 2265 uint16_t auth_type; 2266 uint16_t auth_flags; 2267 uint32_t auth_length; 2268 uint16_t auth_keynumber; 2269 uint32_t auth_indication; 2270 sctp_assoc_t auth_assoc_id; 2271 }; 2273 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 2275 auth_flags: Currently unused. 2277 auth_length: This field is the total length of the notification 2278 data, including the notification header. It will generally be 2279 sizeof(struct sctp_authkey_event). 2281 auth_keynumber: This field holds the keynumber for the affected key 2282 indicated in the event (depends on auth_indication). 2284 auth_indication: This field holds the error or indication being 2285 reported. The following values are currently defined: 2287 SCTP_AUTH_NEW_KEY: This report indicates that a new key has been 2288 made active (used for the first time by the peer) and is now 2289 the active key. The auth_keynumber field holds the user 2290 specified key number. 2292 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 2293 support SCTP AUTH as defined in [RFC4895]. 2295 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 2296 implementation will no longer use the key identifier specified 2297 in auth_keynumber. 2299 auth_assoc_id: The auth_assoc_id field holds the identifier for the 2300 association. All notifications for a given association have the 2301 same association identifier. For a one-to-one style socket this 2302 field is ignored. 2304 6.1.9. SCTP_SENDER_DRY_EVENT 2306 When the SCTP stack has no more user data to send or retransmit, this 2307 notification is given to the user. Also, at the time when a user app 2308 subscribes to this event, if there is no data to be sent or 2309 retransmit, the stack will immediately send up this notification. 2311 struct sctp_sender_dry_event { 2312 uint16_t sender_dry_type; 2313 uint16_t sender_dry_flags; 2314 uint32_t sender_dry_length; 2315 sctp_assoc_t sender_dry_assoc_id; 2316 }; 2318 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 2320 sender_dry_flags: Currently unused. 2322 sender_dry_length: This field is the total length of the 2323 notification data, including the notification header. It will 2324 generally be sizeof(struct sctp_sender_dry_event). 2326 sender_dry_assoc_id: The sender_dry_assoc_id field holds the 2327 identifier for the association. All notifications for a given 2328 association have the same association identifier. For a one-to- 2329 one style socket this field is ignored. 2331 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT 2333 SCTP notifications, when subscribed to, are reliable. They are 2334 always delivered as long as there is space in the socket receive 2335 buffer. However, if an implementation experiences a notification 2336 storm, it may run out of socket buffer space. When this occurs it 2337 may wish to disable notifications. If the implementation chooses to 2338 do this, it will append a final notification 2339 SCTP_NOTIFICATIONS_STOPPED_EVENT. This notification is a union 2340 sctp_notification, where only the struct sctp_tlv (see the union 2341 above) is used. It only contains this type in the sn_type field, the 2342 sn_length field set to the size of an sctp_tlv structure and the 2343 sn_flags set to 0. If an application receives this notification, it 2344 will need to re-subscribe to any notifications of interest to it, 2345 except for the sctp_data_io_event (note that SCTP_EVENTS is 2346 deprecated). 2348 An endpoint is automatically subscribed to this event as soon as it 2349 is subscribed to any event other than data io events. 2351 6.1.11. SCTP_SEND_FAILED_EVENT 2353 If SCTP cannot deliver a message, it can return back the message as a 2354 notification if the SCTP_SEND_FAILED_EVENT event is enabled. The 2355 notification has the following format: 2357 struct sctp_send_failed_event { 2358 uint16_t ssfe_type; 2359 uint16_t ssfe_flags; 2360 uint32_t ssfe_length; 2361 uint32_t ssfe_error; 2362 struct sctp_sndinfo ssfe_info; 2363 sctp_assoc_t ssfe_assoc_id; 2364 uint8_t ssfe_data[]; 2365 }; 2367 ssfe_type: It should be SCTP_SEND_FAILED_EVENT. 2369 ssfe_flags: The flag value will take one of the following values: 2371 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2372 wire. 2374 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2375 Note that this does not necessarily mean that the data was (or 2376 was not) successfully delivered. 2378 ssfe_length: This field is the total length of the notification 2379 data, including the notification header and the payload in 2380 ssf_data. 2382 ssfe_error: This value represents the reason why the send failed, 2383 and if set, will be an SCTP protocol error code as defined in 2384 [RFC4960] Section 3.3.10. 2386 ssfe_info: The ancillary data (struct sctp_sndinfo) used to send the 2387 undelivered message. Regardless of if ancillary data is used or 2388 not, the ssfe_info.sinfo_flags field indicates if the complete 2389 message or only part of the message is returned in ssf_data. If 2390 only part of the message is returned, it means that the part which 2391 is not present has been sent successfully to the peer. 2393 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2394 flags is set in ssfe_info.sinfo_flags. If the first part of the 2395 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2396 This means that the tail end of the message is returned in 2397 ssf_data. 2399 ssfe_assoc_id: The ssfe_assoc_id field, ssf_assoc_id, holds the 2400 identifier for the association. All notifications for a given 2401 association have the same association identifier. For a one-to- 2402 one style socket, this field is ignored. 2404 ssfe_data: The undelivered message or part of the undelivered 2405 message will be present in the ssf_data field. Note that the 2406 ssf_info.sinfo_flags field as noted above should be used to 2407 determine if a complete message is present or just a piece of the 2408 message. Note that only user data is present in this field, any 2409 chunk headers or SCTP common headers must be removed by the SCTP 2410 stack. 2412 6.2. Notification Interest Options 2414 6.2.1. SCTP_EVENTS option - DEPRECATED 2416 Please note that this option is deprecated. Use the SCTP_EVENT 2417 option described in Section 6.2.2 instead. 2419 To receive SCTP event notifications, an application registers its 2420 interest by setting the SCTP_EVENTS socket option. The application 2421 then uses recvmsg() to retrieve notifications. A notification is 2422 stored in the data part (msg_iov) of the struct msghdr. The socket 2423 option uses the following structure: 2425 struct sctp_event_subscribe { 2426 uint8_t sctp_data_io_event; 2427 uint8_t sctp_association_event; 2428 uint8_t sctp_address_event; 2429 uint8_t sctp_send_failure_event; 2430 uint8_t sctp_peer_error_event; 2431 uint8_t sctp_shutdown_event; 2432 uint8_t sctp_partial_delivery_event; 2433 uint8_t sctp_adaptation_layer_event; 2434 uint8_t sctp_authentication_event; 2435 uint8_t sctp_sender_dry_event; 2436 }; 2438 sctp_data_io_event: Setting this flag to 1 will cause the reception 2439 of SCTP_SNDRCV information on a per message basis. The 2440 application will need to use the recvmsg() interface so that it 2441 can receive the event information contained in the msg_control 2442 field. Setting the flag to 0 will disable the reception of the 2443 message control information. Note that this is not really a 2444 notification and this is stored in the ancillary data 2445 (msg_control), not in the data part (msg_iov). 2447 sctp_association_event: Setting this flag to 1 will enable the 2448 reception of association event notifications. Setting the flag to 2449 0 will disable association event notifications. 2451 sctp_address_event: Setting this flag to 1 will enable the reception 2452 of address event notifications. Setting the flag to 0 will 2453 disable address event notifications. 2455 sctp_send_failure_event: Setting this flag to 1 will enable the 2456 reception of send failure event notifications. Setting the flag 2457 to 0 will disable send failure event notifications. 2459 sctp_peer_error_event: Setting this flag to 1 will enable the 2460 reception of peer error event notifications. Setting the flag to 2461 0 will disable peer error event notifications. 2463 sctp_shutdown_event: Setting this flag to 1 will enable the 2464 reception of shutdown event notifications. Setting the flag to 0 2465 will disable shutdown event notifications. 2467 sctp_partial_delivery_event: Setting this flag to 1 will enable the 2468 reception of partial delivery notifications. Setting the flag to 2469 0 will disable partial delivery event notifications. 2471 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 2472 reception of adaptation layer notifications. Setting the flag to 2473 0 will disable adaptation layer event notifications. 2475 sctp_authentication_event: Setting this flag to 1 will enable the 2476 reception of authentication layer notifications. Setting the flag 2477 to 0 will disable authentication layer event notifications. 2479 sctp_sender_dry_event: Setting this flag to 1 will enable the 2480 reception of sender dry notifications. Setting the flag to 0 will 2481 disable sender dry event notifications. 2483 An example where an application would like to receive data_io_events 2484 and association_events but no others would be as follows: 2486 { 2487 struct sctp_event_subscribe events; 2489 memset(&events, 0, sizeof(events)); 2491 events.sctp_data_io_event = 1; 2492 events.sctp_association_event = 1; 2494 setsockopt(sd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 2495 } 2497 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2498 receives ancillary data and notifications for all associations bound 2499 to the file descriptor. For one-to-one style SCTP sockets, the 2500 caller receives ancillary data and notifications only for the single 2501 association bound to the file descriptor. 2503 By default both the one-to-one style and the one-to-many style socket 2504 do not subscribe to any notification. 2506 6.2.2. SCTP_EVENT option 2508 The SCTP_EVENTS socket option has one issue for future compatibility. 2509 As new features are added the structure (sctp_event_subscribe) must 2510 be expanded. This can cause an application binary interface (ABI) 2511 issue unless an implementation has added padding at the end of the 2512 structure. To avoid this problem, SCTP_EVENTS has been deprecated 2513 and a new socket option SCTP_EVENT has taken its place. The option 2514 is used with the following structure: 2516 struct sctp_event { 2517 sctp_assoc_t se_assoc_id; 2518 uint16_t se_type; 2519 uint8_t se_on; 2520 }; 2522 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 2523 sockets. For one-to-many style sockets this field can be a 2524 particular association identifier or SCTP_{FUTURE|CURRENT| 2525 ALL}_ASSOC. 2527 se_type: The se_type field can be filled with any value that would 2528 show up in the respective sn_type field (in the sctp_tlv structure 2529 of the notification). 2531 se_on: The se_on field is set to 1 to turn on an event and set to 0 2532 to turn off an event. 2534 To use this option the user fills in this structure and then calls 2535 the setsockopt() to turn on or off an individual event. The 2536 following is an example use of this option: 2538 { 2539 struct sctp_event event; 2541 memset(&event, 0, sizeof(event)); 2543 event.se_assoc_id = SCTP_FUTURE_ASSOC; 2544 event.se_type = SCTP_SENDER_DRY_EVENT; 2545 event.se_on = 1; 2546 setsockopt(sd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2547 } 2549 By default both the one-to-one style and the one-to-many style socket 2550 do not subscribe to any notification. 2552 7. Common Operations for Both Styles 2554 7.1. send(), recv(), sendto(), and recvfrom() 2556 Applications can use send() and sendto() to transmit data to the peer 2557 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2558 data from the peer. 2560 The function prototypes are 2561 ssize_t send(int sd, 2562 const void *msg, 2563 size_t len, 2564 int flags); 2566 ssize_t sendto(int sd, 2567 const void *msg, 2568 size_t len, 2569 int flags, 2570 const struct sockaddr *to, 2571 socklen_t tolen); 2573 ssize_t recv(int sd, 2574 void *buf, 2575 size_t len, 2576 int flags); 2578 ssize_t recvfrom(int sd, 2579 void *buf, 2580 size_t len, 2581 int flags, 2582 struct sockaddr *from, 2583 socklen_t *fromlen); 2585 and the arguments are 2587 sd: The socket descriptor of an SCTP endpoint. 2589 msg: The message to be sent. 2591 len: The size of the message or the size of the buffer. 2593 to: One of the peer addresses of the association to be used to send 2594 the message. 2596 tolen: The size of the address. 2598 buf: The buffer to store a received message. 2600 from: The buffer to store the peer address used to send the received 2601 message. 2603 fromlen: The size of the from address. 2605 flags: (described below). 2607 These calls give access to only basic SCTP protocol features. If 2608 either peer in the association uses multiple streams, or sends 2609 unordered data, these calls will usually be inadequate, and may 2610 deliver the data in unpredictable ways. 2612 SCTP has the concept of multiple streams in one association. The 2613 above calls do not allow the caller to specify on which stream a 2614 message should be sent. The system uses stream 0 as the default 2615 stream for send() and sendto(). recv() and recvfrom() return data 2616 from any stream, but the caller can not distinguish the different 2617 streams. This may result in data seeming to arrive out of order. 2618 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2619 provide no indication. 2621 SCTP is message based. The msg buffer above in send() and sendto() 2622 is considered to be a single message. This means that if the caller 2623 wants to send a message that is composed by several buffers, the 2624 caller needs to combine them before calling send() or sendto(). 2625 Alternately, the caller can use sendmsg() to do that without 2626 combining them. Sending a message using send() or sendto() is atomic 2627 unless explicit EOR marking is enabled on the socket specified by sd. 2628 Using sendto() on a non-connected one-to-one style socket for 2629 implicit connection setup may or may not work depending on the SCTP 2630 implementation. recv() and recvfrom() cannot distinguish message 2631 boundaries (i.e. there is no way to observe the MSG_EOR flag to 2632 detect partial delivery). 2634 In receiving, if the buffer supplied is not large enough to hold a 2635 complete message, the receive call acts like a stream socket and 2636 returns as much data as will fit in the buffer. 2638 Note, the send() and recv() calls may not be used for a one-to-many 2639 style socket. 2641 Note, if an application calls a send() or sendto() function with no 2642 user data the SCTP implementation should reject the request with an 2643 appropriate error message. An implementation is not allowed to send 2644 a DATA chunk with no user data [RFC4960]. 2646 7.2. setsockopt() and getsockopt() 2648 Applications use setsockopt() and getsockopt() to set or retrieve 2649 socket options. Socket options are used to change the default 2650 behavior of socket calls. They are described in Section 8. 2652 The function prototypes are 2654 int getsockopt(int sd, 2655 int level, 2656 int optname, 2657 void *optval, 2658 socklen_t *optlen); 2660 and 2662 int setsockopt(int sd, 2663 int level, 2664 int optname, 2665 const void *optval, 2666 socklen_t optlen); 2668 and the arguments are 2670 sd: The socket descriptor. 2672 level: Set to IPPROTO_SCTP for all SCTP options. 2674 optname: The option name. 2676 optval: The buffer to store the value of the option. 2678 optlen: The size of the buffer (or the length of the option 2679 returned). 2681 They return 0 on success and -1 in case of an error. 2683 All socket options set on a one-to-one style listening socket also 2684 apply to all future accepted sockets. For one-to-many style sockets 2685 often a socket option will pass a structure that includes an assoc_id 2686 field. This field can be filled with the association identifier of a 2687 particular association and unless otherwise specified can be filled 2688 with one of the following constants: 2690 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2691 after this socket option will be affected by this call. 2693 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2694 associations will be affected by this call, future associations 2695 will still receive the previous default value. 2697 SCTP_ALL_ASSOC: Specifies that all current and future associations 2698 will be affected by this call. 2700 7.3. read() and write() 2702 Applications can use read() and write() to send and receive data to 2703 and from a peer. They have the same semantics as send() and recv() 2704 except that the flags parameter cannot be used. 2706 7.4. getsockname() 2708 Applications use getsockname() to retrieve the locally-bound socket 2709 address of the specified socket. This is especially useful if the 2710 caller let SCTP choose a local port. This call is for single homed 2711 endpoints. It does not work well with multi-homed endpoints. See 2712 Section 9.5 for a multi-homed version of the call. 2714 The function prototype is 2716 int getsockname(int sd, 2717 struct sockaddr *address, 2718 socklen_t *len); 2720 and the arguments are 2722 sd: The socket descriptor to be queried. 2724 address: On return, one locally bound address (chosen by the SCTP 2725 stack) is stored in this buffer. If the socket is an IPv4 socket, 2726 the address will be IPv4. If the socket is an IPv6 socket, the 2727 address will be either an IPv6 or IPv4 address. 2729 len: The caller should set the length of the address here. On 2730 return, this is set to the length of the returned address. 2732 It returns 0 on success and -1 in case of an error. 2734 If the actual length of the address is greater than the length of the 2735 supplied sockaddr structure, the stored address will be truncated. 2737 If the socket has not been bound to a local name, the value stored in 2738 the object pointed to by address is unspecified. 2740 7.5. Implicit Association Setup 2742 The application can begin sending and receiving data using the 2743 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 2744 through any explicit association setup procedures (i.e., no connect() 2745 calls required). 2747 Whenever sendmsg() or sendto() is called and the SCTP stack at the 2748 sender finds that no association exists between the sender and the 2749 intended receiver (identified by the address passed either in the 2750 msg_name field of msghdr structure in the sendmsg() call or the 2751 dest_addr field in the sendto() call), the SCTP stack will 2752 automatically setup an association to the intended receiver. 2754 Upon the successful association setup an SCTP_COMM_UP notification 2755 will be dispatched to the socket at both the sender and receiver 2756 side. This notification can be read by the recvmsg() system call 2757 (see Section 3.1.4). 2759 Note, if the SCTP stack at the sender side supports bundling, the 2760 first user message may be bundled with the COOKIE ECHO message 2761 [RFC4960]. 2763 When the SCTP stack sets up a new association implicitly, the 2764 SCTP_INIT type ancillary data may also be passed along (see 2765 Section 5.3.1 for details of the data structures) to change some 2766 parameters used in setting up a new association. 2768 If this information is not present in the sendmsg() call, or if the 2769 implicit association setup is triggered by a sendto() call, the 2770 default association initialization parameters will be used. These 2771 default association parameters may be set with respective 2772 setsockopt() calls or be left to the system defaults. 2774 Implicit association setup cannot be initiated by send() calls. 2776 8. Socket Options 2778 The following sub-section describes various SCTP level socket options 2779 that are common to both styles. SCTP associations can be multi- 2780 homed. Therefore, certain option parameters include a 2781 sockaddr_storage structure to select which peer address the option 2782 should be applied to. 2784 For the one-to-many style sockets, an sctp_assoc_t (association 2785 identifier) parameter is used to identify the association instance 2786 that the operation affects. So it must be set when using this style. 2788 For the one-to-one style sockets and branched off one-to-many style 2789 sockets (see Section 9.2) this association ID parameter is ignored. 2791 Note that socket or IP level options are set or retrieved per socket. 2793 This means that for one-to-many style sockets, the options will be 2794 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2795 association identifier) belonging to the socket. For one-to-one 2796 style, these options will be applied to all peer addresses of the 2797 association controlled by the socket. Applications should be careful 2798 in setting those options. 2800 For some IP stacks getsockopt() is read-only; so a new interface will 2801 be needed when information must be passed both into and out of the 2802 SCTP stack. The syntax for sctp_opt_info() is 2804 int sctp_opt_info(int sd, 2805 sctp_assoc_t id, 2806 int opt, 2807 void *arg, 2808 socklen_t *size); 2810 The sctp_opt_info() call is a replacement for getsockopt() only and 2811 will not set any options associated with the specified socket. A 2812 setsockopt() must be used to set any writeable option. 2814 For one-to-many style sockets, id specifies the association to query. 2815 For one-to-one style sockets, id is ignored. For one-to-many 2816 sockets, any association identifier in the structure provided as arg 2817 is ignored and id takes precedence. 2819 Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used with 2820 sctp_opt_info() or in getsockopt() calls. Using them will result in 2821 an error (returning -1 and errno set to EINVAL). SCTP_FUTURE_ASSOC 2822 can be used to query information for future associations. 2824 The field opt specifies which SCTP socket option to get. It can get 2825 any socket option currently supported that requests information 2826 (either read/write options or read only) such as: 2828 SCTP_RTOINFO 2830 SCTP_ASSOCINFO 2832 SCTP_PRIMARY_ADDR 2834 SCTP_PEER_ADDR_PARAMS 2836 SCTP_DEFAULT_SEND_PARAM 2837 SCTP_MAX_SEG 2839 SCTP_AUTH_ACTIVE_KEY 2841 SCTP_DELAYED_SACK 2843 SCTP_MAX_BURST 2845 SCTP_CONTEXT 2847 SCTP_EVENT 2849 SCTP_DEFAULT_SNDINFO 2851 SCTP_DEFAULT_PRINFO 2853 SCTP_STATUS 2855 SCTP_GET_PEER_ADDR_INFO 2857 SCTP_PEER_AUTH_CHUNKS 2859 SCTP_LOCAL_AUTH_CHUNKS 2861 The arg field is an option-specific structure buffer provided by the 2862 caller. See the rest of this sections subsections for more 2863 information on these options and option-specific structures. 2865 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2866 sets errno to the appropriate error code. 2868 8.1. Read / Write Options 2870 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2872 The protocol parameters used to initialize and limit the 2873 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2874 information on how these parameters are used in RTO calculation. 2876 The following structure is used to access and modify these 2877 parameters: 2879 struct sctp_rtoinfo { 2880 sctp_assoc_t srto_assoc_id; 2881 uint32_t srto_initial; 2882 uint32_t srto_max; 2883 uint32_t srto_min; 2884 }; 2885 srto_initial: This contains the initial RTO value. 2887 srto_max and srto_min: These contain the maximum and minimum bounds 2888 for all RTOs. 2890 srto_assoc_id: This parameter is ignored for one-to-one style 2891 sockets. For one-to-many style sockets the application may fill 2892 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 2893 to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id. 2895 All times are given in milliseconds. A value of 0, when modifying 2896 the parameters, indicates that the current value should not be 2897 changed. 2899 To access or modify these parameters, the application should call 2900 getsockopt() or setsockopt() respectively with the option name 2901 SCTP_RTOINFO. 2903 8.1.2. Association Parameters (SCTP_ASSOCINFO) 2905 This option is used to both examine and set various association and 2906 endpoint parameters. See [RFC4960] for more information on how this 2907 parameter is used. 2909 The following structure is used to access and modify these 2910 parameters: 2912 struct sctp_assocparams { 2913 sctp_assoc_t sasoc_assoc_id; 2914 uint16_t sasoc_asocmaxrxt; 2915 uint16_t sasoc_number_peer_destinations; 2916 uint32_t sasoc_peer_rwnd; 2917 uint32_t sasoc_local_rwnd; 2918 uint32_t sasoc_cookie_life; 2919 }; 2921 sasoc_assoc_id: This parameter is ignored for one-to-one style 2922 sockets. For one-to-many style sockets the application may fill 2923 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 2924 to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id. 2926 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2927 to make for the association. 2929 sasoc_number_peer_destinations: This is the number of destination 2930 addresses that the peer has. 2932 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2933 (reported in the last SACK) minus any outstanding data (i.e. data 2934 in flight). 2936 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2937 the peer. 2939 sasoc_cookie_life: This is the association's cookie life value used 2940 when issuing cookies. 2942 The values of the sasoc_peer_rwnd is meaningless when examining 2943 endpoint information (i.e. it is only valid when examining 2944 information on a specific association). 2946 All time values are given in milliseconds. A value of 0, when 2947 modifying the parameters, indicates that the current value should not 2948 be changed. 2950 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2951 on either an endpoint or association basis. The rwnd and destination 2952 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2953 sasoc_local_rwnd) are not settable and any value placed in these is 2954 ignored. 2956 To access or modify these parameters, the application should call 2957 getsockopt() or setsockopt() respectively with the option name 2958 SCTP_ASSOCINFO. 2960 The maximum number of retransmissions before an address is considered 2961 unreachable is also tunable, but is address-specific, so it is 2962 covered in a separate option. If an application attempts to set the 2963 value of the association maximum retransmission parameter to more 2964 than the sum of all maximum retransmission parameters, setsockopt() 2965 may return an error. The reason for this, from [RFC4960] Section 2966 8.2: 2968 Note: When configuring the SCTP endpoint, the user should avoid 2969 having the value of 'Association.Max.Retrans' (sasoc_maxrxt in this 2970 option) larger than the summation of the 'Path.Max.Retrans' (see 2971 Section 8.1.12 on spp_pathmaxrxt) of all the destination addresses 2972 for the remote endpoint. Otherwise, all the destination addresses 2973 may become inactive while the endpoint still considers the peer 2974 endpoint reachable. 2976 8.1.3. Initialization Parameters (SCTP_INITMSG) 2978 Applications can specify protocol parameters for the default 2979 association initialization. The structure used to access and modify 2980 these parameters is defined in Section 5.3.1. The option name 2981 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2983 Setting initialization parameters is effective only on an unconnected 2984 socket (for one-to-many style sockets only future associations are 2985 affected by the change). 2987 8.1.4. SO_LINGER 2989 An application can use this option to perform the SCTP ABORT 2990 primitive. This option affects all associations related to the 2991 socket. 2993 The linger option structure is: 2995 struct linger { 2996 int l_onoff; /* option on/off */ 2997 int l_linger; /* linger time */ 2998 }; 3000 To enable the option, set l_onoff to 1. If the l_linger value is set 3001 to 0, calling close() is the same as the ABORT primitive. If the 3002 value is set to a negative value, the setsockopt() call will return 3003 an error. If the value is set to a positive value linger_time, the 3004 close() can be blocked for at most linger_time. Please note that the 3005 time unit is seconds according to POSIX, but might be different on 3006 specific platforms. If the graceful shutdown phase does not finish 3007 during this period, close() will return but the graceful shutdown 3008 phase will continue in the system. 3010 Note, this is a socket level option, not an SCTP level option. When 3011 using this option, an application must specify a level of SOL_SOCKET 3012 in the call. 3014 8.1.5. SCTP_NODELAY 3016 Turn on/off any Nagle-like algorithm. This means that packets are 3017 generally sent as soon as possible and no unnecessary delays are 3018 introduced, at the cost of more packets in the network. In 3019 particular, not using any Nagle-like algorithm might reduce the 3020 bundling of small user messages in cases where this would require an 3021 additional delay. 3023 Turning this option on disables any Nagle-like algorithm. 3025 This option expects an integer boolean flag, where a non-zero value 3026 turns on the option, and a zero value turns off the option. 3028 8.1.6. SO_RCVBUF 3030 Sets the receive buffer size in octets. For SCTP one-to-one style 3031 sockets, this controls the receiver window size. For one-to-many 3032 style sockets the meaning is implementation dependent. It might 3033 control the receive buffer for each association bound to the socket 3034 descriptor or it might control the receive buffer for the whole 3035 socket. This option expects an integer. 3037 Note, this is a socket level option, not an SCTP level option. When 3038 using this option, an application must specify a level of SOL_SOCKET 3039 in the call. 3041 8.1.7. SO_SNDBUF 3043 Sets the send buffer size. For SCTP one-to-one style sockets, this 3044 controls the amount of data SCTP may have waiting in internal buffers 3045 to be sent. This option therefore bounds the maximum size of data 3046 that can be sent in a single send call. For one-to-many style 3047 sockets, the effect is the same, except that it applies to one or all 3048 associations (see Section 3.3) bound to the socket descriptor used in 3049 the setsockopt() or getsockopt() call. The option applies to each 3050 association's window size separately. This option expects an 3051 integer. 3053 Note, this is a socket level option, not an SCTP level option. When 3054 using this option, an application must specify a level of SOL_SOCKET 3055 in the call. 3057 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 3059 This socket option is applicable to the one-to-many style socket 3060 only. When set it will cause associations that are idle for more 3061 than the specified number of seconds to automatically close using the 3062 graceful shutdown procedure. An association being idle is defined as 3063 an association that has not sent or received user data. The special 3064 value of '0' indicates that no automatic close of any association 3065 should be performed, this is the default value. This option expects 3066 an integer defining the number of seconds of idle time before an 3067 association is closed. 3069 An application using this option should enable receiving the 3070 association change notification. This is the only mechanism an 3071 application is informed about the closing of an association. After 3072 an association is closed, the association identifier assigned to it 3073 can be reused. An application should be aware of this to avoid the 3074 possible problem of sending data to an incorrect peer endpoint. 3076 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 3078 Requests that the local SCTP stack uses the enclosed peer address as 3079 the association's primary. The enclosed address must be one of the 3080 association peer's addresses. 3082 The following structure is used to make a set peer primary request: 3084 struct sctp_setprim { 3085 sctp_assoc_t ssp_assoc_id; 3086 struct sockaddr_storage ssp_addr; 3087 }; 3089 ssp_addr: The address to set as primary. No wildcard address is 3090 allowed. 3092 ssp_assoc_id: This parameter is ignored for one-to-one style 3093 sockets. For one-to-many style sockets it identifies the 3094 association for this request. Note that the special sctp_assoc_t 3095 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 3097 8.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 3099 Requests that the local endpoint set the specified Adaptation Layer 3100 Indication parameter for all future INIT and INIT-ACK exchanges. 3102 The following structure is used to access and modify this parameter: 3104 struct sctp_setadaptation { 3105 uint32_t ssb_adaptation_ind; 3106 }; 3108 ssb_adaptation_ind: The adaptation layer indicator that will be 3109 included in any outgoing Adaptation Layer Indication parameter. 3111 8.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 3113 This option is a on/off flag and is passed as an integer where a non- 3114 zero is on and a zero is off. If enabled no SCTP message 3115 fragmentation will be performed. The effect of enabling this option 3116 are that if a message being sent exceeds the current PMTU size, the 3117 message will not be sent and instead an error will be indicated to 3118 the user. If this option is disabled (the default) then a message 3119 exceeding the size of the PMTU will be fragmented and reassembled by 3120 the peer. 3122 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 3124 Applications can enable or disable heartbeats for any peer address of 3125 an association, modify an address's heartbeat interval, force a 3126 heartbeat to be sent immediately, and adjust the address's maximum 3127 number of retransmissions sent before an address is considered 3128 unreachable. 3130 The following structure is used to access and modify an address's 3131 parameters: 3133 struct sctp_paddrparams { 3134 sctp_assoc_t spp_assoc_id; 3135 struct sockaddr_storage spp_address; 3136 uint32_t spp_hbinterval; 3137 uint16_t spp_pathmaxrxt; 3138 uint32_t spp_pathmtu; 3139 uint32_t spp_flags; 3140 uint32_t spp_ipv6_flowlabel; 3141 uint8_t spp_dscp; 3142 }; 3144 spp_assoc_id: This parameter is ignored for one-to-one style 3145 sockets. For one-to-many style sockets the application may fill 3146 in an association identifier or SCTP_FUTURE_ASSOC for this query. 3147 It is an error to use SCTP_{CURRENT|ALL}_ASSOC in spp_assoc_id. 3149 spp_address: This specifies which address is of interest. If a 3150 wildcard address is provided it applies to all current and future 3151 paths. 3153 spp_hbinterval: This contains the value of the heartbeat interval, 3154 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 3155 spp_flag is set to SPP_HB_ENABLE the value of this field is 3156 ignored. Note also that a value of zero indicates the current 3157 setting should be left unchanged. To set an actual value of zero 3158 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 3159 it is set to 0, it does not mean that SCTP will continuously send 3160 out heartbeat since the actual interval also includes the current 3161 RTO and jitter (see Section 8.3 in [RFC4960]). 3163 spp_pathmaxrxt: This contains the maximum number of retransmissions 3164 before this address shall be considered unreachable. Note that a 3165 value of zero indicates the current setting should be left 3166 unchanged. 3168 spp_pathmtu: The current path MTU of the peer address. It is the 3169 number of bytes available in an SCTP packet for chunks. Providing 3170 a value of 0 does not change the current setting. If a positive 3171 value is provided and SPP_PMTUD_DISABLE is set in the spp_flags, 3172 the given value is used as the path MTU. If SPP_PMTUD_ENABLE is 3173 set in the spp_flags, the spp_pathmtu field is ignored. 3175 spp_ipv6_flowlabel: This field is used in conjunction with the 3176 SPP_IPV6_FLOWLABEL flag and contains the IPv6 flowlabel. The 20 3177 least significant bits are used for the flowlabel. This setting 3178 has precedence over any IPv6 layer setting. 3180 spp_dscp: This field is used in conjunction with the SPP_DSCP flag 3181 and contains the Differentiated Services Code Point (DSCP). The 6 3182 least significant bits are used for the DSCP. This setting has 3183 precedence over any IPv4 or IPv6 layer setting. 3185 spp_flags: These flags are used to control various features on an 3186 association. The flag field is a bit mask which may contain zero 3187 or more of the following options: 3189 SPP_HB_ENABLE: Enable heartbeats on the specified address. 3191 SPP_HB_DISABLE: Disable heartbeats on the specified address. 3192 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 3193 exclusive, only one of these two should be specified. Enabling 3194 both fields will have undetermined results. 3196 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 3197 immediately. This must not be used in conjunction with a 3198 wildcard address. 3200 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 3201 is to be set to the value of 0 milliseconds. 3203 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 3204 specified address. 3206 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 3207 the specified address. Note that if the address field is empty 3208 then all addresses on the association are affected. Note also 3209 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 3210 exclusive. Enabling both will have undetermined results. 3212 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 3213 IPV6 flowlabel value. The value is contained in the 3214 spp_ipv6_flowlabel field. 3216 Upon retrieval, this flag will be set to indicate that the 3217 spp_ipv6_flowlabel field has a valid value returned. If a 3218 specific destination address is set (in the spp_address field), 3219 then the value returned is that of the address. If just an 3220 association is specified (and no address), then the 3221 association's default flowlabel is returned. If neither an 3222 association nor a destination is specified, then the socket's 3223 default flowlabel is returned. For non IPv6 sockets, this flag 3224 will be left cleared. 3226 SPP_DSCP: Setting this flag enables the setting of the DSCP value 3227 associated with either the association or a specific address. 3228 The value is obtained in the spp_dscp field. 3230 Upon retrieval, this flag will be set to indicate that the 3231 spp_dscp field has a valid value returned. If a specific 3232 destination address is set when called (in the spp_address 3233 field) then that specific destination address' DSCP value is 3234 returned. If just an association is specified then the 3235 association default DSCP is returned. If neither an 3236 association nor a destination is specified, then the sockets 3237 default DSCP is returned. 3239 Please note that changing the flowlabel or DSCP value will affect all 3240 packets sent by the SCTP stack after setting these parameters. The 3241 flowlabel might also be set via the sin6_flowinfo field of the 3242 sockaddr_in6 structure. 3244 8.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) - 3245 DEPRECATED 3247 Please note that this options is deprecated. Section 8.1.31 should 3248 be used instead. 3250 Applications that wish to use the sendto() system call may wish to 3251 specify a default set of parameters that would normally be supplied 3252 through the inclusion of ancillary data. This socket option allows 3253 such an application to set the default sctp_sndrcvinfo structure. 3254 The application that wishes to use this socket option simply passes 3255 the sctp_sndrcvinfo structure defined in Section 5.3.2 to this call. 3256 The input parameters accepted by this call include sinfo_stream, 3257 sinfo_flags, sinfo_ppid, sinfo_context, and sinfo_timetolive. The 3258 sinfo_flags is composed of a bitwise OR of SCTP_UNORDERED, SCTP_EOF, 3259 and SCTP_SENDALL. The sinfo_assoc_id field specifies the association 3260 to apply the parameters to. For a one-to-many style socket any of 3261 the predefined constants are also allowed in this field. The field 3262 is ignored on the one-to-one style. 3264 8.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) - 3265 DEPRECATED 3267 This socket option is used to specify various notifications and 3268 ancillary data the user wishes to receive. Please see Section 6.2.1 3269 for a full description of this option and its usage. Note that this 3270 option is considered deprecated and present for backward 3271 compatibility. New applications should use the SCTP_EVENT option. 3272 See Section 6.2.2 for a full description of that option as well. 3274 8.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 3276 This socket option is a boolean flag which turns on or off the 3277 mapping of IPv4 addresses. If this option is turned on, then IPv4 3278 addresses will be mapped to V6 representation. If this option is 3279 turned off, then no mapping will be done of V4 addresses and a user 3280 will receive both PF_INET6 and PF_INET type addresses on the socket. 3281 See [RFC3542] for more details on mapped V6 addresses. 3283 If this socket option is used on a socket of type PF_INET an error is 3284 returned. 3286 By default this option is turned off and expects an integer to be 3287 passed where a non-zero value turns on the option and a zero value 3288 turns off the option. 3290 8.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 3292 This option will get or set the maximum size to put in any outgoing 3293 SCTP DATA chunk. If a message is larger than this size it will be 3294 fragmented by SCTP into the specified size. Note that the underlying 3295 SCTP implementation may fragment into smaller sized chunks when the 3296 PMTU of the underlying association is smaller than the value set by 3297 the user. The default value for this option is '0' which indicates 3298 the user is not limiting fragmentation and only the PMTU will affect 3299 SCTP's choice of DATA chunk size. Note also that values set larger 3300 than the maximum size of an IP datagram will effectively let SCTP 3301 control fragmentation (i.e. the same as setting this option to 0). 3303 The following structure is used to access and modify this parameter: 3305 struct sctp_assoc_value { 3306 sctp_assoc_t assoc_id; 3307 uint32_t assoc_value; 3308 }; 3309 assoc_id: This parameter is ignored for one-to-one style sockets. 3310 For one-to-many style sockets this parameter indicates which 3311 association the user is performing an action upon. It is an error 3312 to use SCTP_{CURRENT|ALL}_ASSOC in assoc_id. 3314 assoc_value: This parameter specifies the maximum size in bytes. 3316 8.1.17. Get or Set the List of Supported HMAC Identifiers 3317 (SCTP_HMAC_IDENT) 3319 This option gets or sets the list of HMAC algorithms that the local 3320 endpoint requires the peer to use. 3322 The following structure is used to get or set these identifiers: 3324 struct sctp_hmacalgo { 3325 uint32_t shmac_number_of_idents; 3326 uint16_t shmac_idents[]; 3327 }; 3329 shmac_number_of_idents: This field gives the number of elements 3330 present in the array shmac_idents. 3332 shmac_idents: This parameter contains an array of HMAC identifiers 3333 that the local endpoint is requesting the peer to use, in priority 3334 order. The following identifiers are valid: 3336 * SCTP_AUTH_HMAC_ID_SHA1 3338 * SCTP_AUTH_HMAC_ID_SHA256 3340 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 3341 may include any of the other values in its preferred order (lowest 3342 list position has the highest preference in algorithm selection). 3343 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 3344 of an unknown HMAC identifier (including optional identifiers unknown 3345 to the implementation) will cause the set option to fail and return 3346 an error. 3348 8.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 3350 This option will get or set the active shared key to be used to build 3351 the association shared key. 3353 The following structure is used to access and modify these 3354 parameters: 3356 struct sctp_authkeyid { 3357 sctp_assoc_t scact_assoc_id; 3358 uint16_t scact_keynumber; 3359 }; 3361 scact_assoc_id: This parameter sets the active key of the specified 3362 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 3363 used. For one-to-one sockets, this parameter is ignored. Note, 3364 however, that this option will set the active key on the 3365 association if the socket is connected, otherwise this will set 3366 the default active key for the endpoint. 3368 scact_keynumber: This parameter is the shared key identifier which 3369 the application is requesting to become the active shared key to 3370 be used for sending authenticated chunks. The key identifier must 3371 correspond to an existing shared key. Note that shared key 3372 identifier '0' defaults to a null key. 3374 When used with setsockopt() the SCTP implementation must use the 3375 indicated shared key identifier for all messages being given to an 3376 SCTP implementation via a send call after the setsockopt() call until 3377 changed again. Therefore, the SCTP implementation must not bundle 3378 user messages which should be authenticated using different shared 3379 key identifiers. 3381 Initially the key with key identifier 0 is the active key. 3383 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 3385 This option will affect the way delayed sacks are performed. This 3386 option allows the application to get or set the delayed sack time, in 3387 milliseconds. It also allows changing the delayed sack frequency. 3388 Changing the frequency to 1 disables the delayed sack algorithm. 3389 Note that if sack_delay or sack_freq are 0 when setting this option, 3390 the current values will remain unchanged. 3392 The following structure is used to access and modify these 3393 parameters: 3395 struct sctp_sack_info { 3396 sctp_assoc_t sack_assoc_id; 3397 uint32_t sack_delay; 3398 uint32_t sack_freq; 3399 }; 3400 sack_assoc_id: This parameter is ignored for one-to-one style 3401 sockets. For one-to-many style sockets this parameter indicates 3402 which association the user is performing an action upon. The 3403 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3405 sack_delay: This parameter contains the number of milliseconds that 3406 the user is requesting the delayed SACK timer to be set to. Note 3407 that this value is defined in the standard to be between 200 and 3408 500 milliseconds. 3410 sack_freq: This parameter contains the number of packets that must 3411 be received before a sack is sent without waiting for the delay 3412 timer to expire. The default value is 2, setting this value to 1 3413 will disable the delayed sack algorithm. 3415 8.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 3417 Fragmented interleave controls how the presentation of messages 3418 occurs for the message receiver. There are three levels of fragment 3419 interleave defined. Two of the levels affect the one-to-one model, 3420 while the one-to-many model is affected by all three levels. 3422 This option takes an integer value. It can be set to a value of 0, 1 3423 or 2. Attempting to set this level to other values will return an 3424 error. 3426 Setting the three levels provides the following receiver 3427 interactions: 3429 level 0: Prevents the interleaving of any messages. This means that 3430 when a partial delivery begins, no other messages will be received 3431 except the message being partially delivered. If another message 3432 arrives on a different stream (or association) that could be 3433 delivered, it will be blocked waiting for the user to read all of 3434 the partially delivered message. 3436 level 1: Allows interleaving of messages that are from different 3437 associations. For the one-to-one model, level 0 and level 1 thus 3438 have the same meaning since a one-to-one socket always receives 3439 messages from the same association. Note that setting the one-to- 3440 many model to this level may cause multiple partial deliveries 3441 from different associations but for any given association, only 3442 one message will be delivered until all parts of a message have 3443 been delivered. This means that one large message, being read 3444 with an association identifier of "X", will block other messages 3445 from association "X" from being delivered. 3447 level 2: Allows complete interleaving of messages. This level 3448 requires that the sender carefully observes not only the peer 3449 association identifier (or address) but must also pay careful 3450 attention to the stream number. With this option enabled a 3451 partially delivered message may begin being delivered for 3452 association "X" stream "Y" and the next subsequent receive may 3453 return a message from association "X" stream "Z". Note that no 3454 other messages would be delivered for association "X" stream "Y" 3455 until all of stream "Y"'s partially delivered message was read. 3456 Note that this option also affects the one-to-one model. Also 3457 note that for the one-to-many model not only another stream's 3458 message from the same association may be delivered upon the next 3459 receive, some other association's message may be delivered upon 3460 the next receive. 3462 An implementation should default the one-to-many model to level 1. 3463 The reason for this is that otherwise it is possible that a peer 3464 could begin sending a partial message and thus block all other peers 3465 from sending data. However a setting of level 2 requires the 3466 application to not only be aware of the association (via the 3467 association identifier or peer's address) but also the stream number. 3468 The stream number is not present unless the user has subscribed to 3469 the sctp_data_io_event (see Section 6.2), which is deprecated, or has 3470 enabled the SCTP_RECVRCVINFO socket option (see Section 8.1.29). 3471 This is also why we recommend that the one-to-one model be defaulted 3472 to level 0 (level 1 for the one-to-one model has no effect). Note 3473 that an implementation should return an error if an application 3474 attempts to set the level to 2 and has not subscribed to the 3475 sctp_data_io_event event, which is deprecated, or has enabled the 3476 SCTP_RECVRCVINFO socket option. 3478 For applications that have subscribed to events, those events appear 3479 in the normal socket buffer data stream. This means that unless the 3480 user has set the fragmentation interleave level to 0, notifications 3481 may also be interleaved with partially delivered messages. 3483 8.1.21. Set or Get the SCTP Partial Delivery Point 3484 (SCTP_PARTIAL_DELIVERY_POINT) 3486 This option will set or get the SCTP partial delivery point. This 3487 point is the size of a message where the partial delivery API will be 3488 invoked to help free up rwnd space for the peer. Setting this to a 3489 lower value will cause partial deliveries to happen more often. This 3490 option expects an integer that sets or gets the partial delivery 3491 point in bytes. Note also that the call will fail if the user 3492 attempts to set this value larger than the socket receive buffer 3493 size. 3495 Note that any single message having a length smaller than or equal to 3496 the SCTP partial delivery point will be delivered in one single read 3497 call as long as the user provided buffer is large enough to hold the 3498 message. 3500 8.1.22. Set or Get the Use of Extended Receive Info 3501 (SCTP_USE_EXT_RCVINFO) - DEPRECATED 3503 This option will enable or disable the use of the extended version of 3504 the sctp_sndrcvinfo structure. If this option is disabled, then the 3505 normal sctp_sndrcvinfo structure is returned in all receive message 3506 calls. If this option is enabled then the sctp_extrcvinfo structure 3507 is returned in all receive message calls. The default is off. 3509 Note that the sctp_extrcvinfo structure is never used in any send 3510 call. 3512 This option is present for compatibility with older applications and 3513 is deprecated. Future applications should use SCTP_NXTINFO to 3514 retrieve this same information via ancillary data. 3516 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 3518 This option will enable or disable the use of the automatic 3519 generation of ASCONF chunks to add and delete addresses to an 3520 existing association. Note that this option has two caveats namely: 3521 a) it only affects sockets that are bound to all addresses available 3522 to the SCTP stack, and b) the system administrator may have an 3523 overriding control that turns the ASCONF feature off no matter what 3524 setting the socket option may have. 3526 This option expects an integer boolean flag, where a non-zero value 3527 turns on the option, and a zero value turns off the option. 3529 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 3531 This option will allow a user to change the maximum burst of packets 3532 that can be emitted by this association. Note that the default value 3533 is 4, and some implementations may restrict this setting so that it 3534 can only be lowered to positive values. 3536 To set or get this option the user fills in the following structure: 3538 struct sctp_assoc_value { 3539 sctp_assoc_t assoc_id; 3540 uint32_t assoc_value; 3541 }; 3542 assoc_id: This parameter is ignored for one-to-one style sockets. 3543 For one-to-many style sockets this parameter indicates which 3544 association the user is performing an action upon. The special 3545 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3547 assoc_value: This parameter contains the maximum burst. Setting the 3548 value to 0 disables burst mitigation. 3550 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) 3552 The context field in the sctp_sndrcvinfo structure is normally only 3553 used when a failed message is retrieved holding the value that was 3554 sent down on the actual send call. This option allows the setting of 3555 a default context on an association basis that will be received on 3556 reading messages from the peer. This is especially helpful in the 3557 one-to-many model for an application to keep some reference to an 3558 internal state machine that is processing messages on the 3559 association. Note that the setting of this value only affects 3560 received messages from the peer and does not affect the value that is 3561 saved with outbound messages. 3563 To set or get this option the user fills in the following structure: 3565 struct sctp_assoc_value { 3566 sctp_assoc_t assoc_id; 3567 uint32_t assoc_value; 3568 }; 3570 assoc_id: This parameter is ignored for one-to-one style sockets. 3571 For one-to-many style sockets this parameter indicates which 3572 association the user is performing an action upon. The special 3573 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3575 assoc_value: This parameter contains the context. 3577 8.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 3579 This boolean flag is used to enable or disable explicit end of record 3580 (EOR) marking. When this option is enabled, a user may make multiple 3581 send system calls to send a record and must indicate that they are 3582 finished sending a particular record by including the SCTP_EOR flag. 3583 If this boolean flag is disabled then each individual send system 3584 call is considered to have an SCTP_EOR indicator set on it implicitly 3585 without the user having to explicitly add this flag. The default is 3586 off. 3588 This option expects an integer boolean flag, where a non-zero value 3589 turns on the option, and a zero value turns off the option. 3591 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 3593 This option only supports one-to-one style SCTP sockets. If used on 3594 a one-to-many style SCTP socket an error is indicated. 3596 This option expects an integer boolean flag, where a non-zero value 3597 turns on the option, and a zero value turns off the option. 3599 This socket option must not be used after calling bind() or 3600 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 3601 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3602 SCTP sockets bound to the same port must have set the 3603 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3604 having set the SCTP_REUSE_PORT option will fail if there are other 3605 sockets bound to the same port. At most one socket being bound to 3606 the same port may be listening. 3608 It should be noted that the behavior of the socket level socket 3609 option to reuse ports and/or addresses for SCTP sockets is 3610 unspecified. 3612 8.1.28. Set Notification Event (SCTP_EVENT) 3614 This socket option is used to set a specific notification option. 3615 Please see Section 6.2.2 for a full description of this option and 3616 its usage. 3618 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary 3619 Data (SCTP_RECVRCVINFO) 3621 Setting this option specifies that SCTP_RCVINFO defined in 3622 Section 5.3.5 is returned as ancillary data by recvmsg(). 3624 This option expects an integer boolean flag, where a non-zero value 3625 turns on the option, and a zero value turns off the option. 3627 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary 3628 Data (SCTP_RECVNXTINFO) 3630 Setting this option specifies that SCTP_NXTINFO defined in 3631 Section 5.3.6 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.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) 3638 Applications that wish to use the sendto() system call may wish to 3639 specify a default set of parameters that would normally be supplied 3640 through the inclusion of ancillary data. This socket option allows 3641 such an application to set the default sctp_sndinfo structure. The 3642 application that wishes to use this socket option simply passes the 3643 sctp_sndinfo structure defined in Section 5.3.4 to this call. The 3644 input parameters accepted by this call include snd_sid, snd_flags, 3645 snd_ppid, snd_context. The snd_flags is composed of a bitwise OR of 3646 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The snd_assoc_id field 3647 specifies the association to apply the parameters to. For a one-to- 3648 many style socket any of the predefined constants are also allowed in 3649 this field. The field is ignored on the one-to-one style. 3651 8.1.32. Set Default PR-SCTP Parameters (SCTP_DEFAULT_PRINFO) 3653 This option sets and gets the default parameters for PR-SCTP. They 3654 can be overwritten by specific information provided in send calls. 3656 The following structure is used to access and modify these 3657 parameters: 3659 struct sctp_default_prinfo { 3660 uint16_t pr_policy; 3661 uint32_t pr_value; 3662 sctp_assoc_t pr_assoc_id; 3663 }; 3665 pr_policy: Same as described in Section 5.3.7. 3667 pr_value: Same as described in Section 5.3.7. 3669 pr_assoc_id: This field is ignored for one-to-one style sockets. 3670 For one-to-many style sockets pr_assoc_id can be a particular 3671 association identifier or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. 3673 8.2. Read-Only Options 3675 The options defined in this subsection are read-only. Using this 3676 option in a setsockopt() call will result in an error indicating 3677 EOPNOTSUPP. 3679 8.2.1. Association Status (SCTP_STATUS) 3681 Applications can retrieve current status information about an 3682 association, including association state, peer receiver window size, 3683 number of unacknowledged data chunks, and number of data chunks 3684 pending receipt. This information is read-only. 3686 The following structure is used to access this information: 3688 struct sctp_status { 3689 sctp_assoc_t sstat_assoc_id; 3690 int32_t sstat_state; 3691 uint32_t sstat_rwnd; 3692 uint16_t sstat_unackdata; 3693 uint16_t sstat_penddata; 3694 uint16_t sstat_instrms; 3695 uint16_t sstat_outstrms; 3696 uint32_t sstat_fragmentation_point; 3697 struct sctp_paddrinfo sstat_primary; 3698 }; 3700 sstat_assoc_id: This parameter is ignored for one-to-one style 3701 sockets. For one-to-many style sockets it holds the identifier 3702 for the association. All notifications for a given association 3703 have the same association identifier. The special SCTP_{FUTURE| 3704 CURRENT|ALL}_ASSOC cannot be used. 3706 sstat_state: This contains the association's current state, i.e. one 3707 of the following values: 3709 * SCTP_CLOSED 3711 * SCTP_BOUND 3713 * SCTP_LISTEN 3715 * SCTP_COOKIE_WAIT 3717 * SCTP_COOKIE_ECHOED 3719 * SCTP_ESTABLISHED 3721 * SCTP_SHUTDOWN_PENDING 3723 * SCTP_SHUTDOWN_SENT 3725 * SCTP_SHUTDOWN_RECEIVED 3727 * SCTP_SHUTDOWN_ACK_SENT 3729 sstat_rwnd: This contains the association peer's current receiver 3730 window size. 3732 sstat_unackdata: This is the number of unacknowledged data chunks. 3734 sstat_penddata: This is the number of data chunks pending receipt. 3736 sstat_instrms: The number of streams that the peer will be using 3737 outbound. 3739 sstat_outstrms: The number of streams that the endpoint is allowed 3740 to use outbound. 3742 sstat_fragmentation_point: The size at which SCTP fragmentation will 3743 occur. 3745 sstat_primary: This is information on the current primary peer 3746 address. 3748 To access these status values, the application calls getsockopt() 3749 with the option name SCTP_STATUS. 3751 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3753 Applications can retrieve information about a specific peer address 3754 of an association, including its reachability state, congestion 3755 window, and retransmission timer values. This information is read- 3756 only. 3758 The following structure is used to access this information: 3760 struct sctp_paddrinfo { 3761 sctp_assoc_t spinfo_assoc_id; 3762 struct sockaddr_storage spinfo_address; 3763 int32_t spinfo_state; 3764 uint32_t spinfo_cwnd; 3765 uint32_t spinfo_srtt; 3766 uint32_t spinfo_rto; 3767 uint32_t spinfo_mtu; 3768 }; 3770 spinfo_assoc_id: This parameter is ignored for one-to-one style 3771 sockets. For one-to-many style sockets the following applies: 3772 This field may be filled by the application, if so, this field 3773 will have priority in looking up the association instead of using 3774 the address specified in spinfo_address. Note that if the address 3775 does not belong to the association specified then this call will 3776 fail. If the application does not fill in the spinfo_assoc_id, 3777 then the address will be used to lookup the association and on 3778 return this field will have the valid association identifier. In 3779 other words, this call can be used to translate an address into an 3780 association identifier. Note that the predefined constants are 3781 not allowed on this option. 3783 spinfo_address: This is filled by the application, and contains the 3784 peer address of interest. 3786 spinfo_state: This contains the peer address' state: 3788 SCTP_UNCONFIRMED: The initial state of a peer address. 3790 SCTP_ACTIVE: The state is entered the first time after path 3791 verification. It can also be entered if the state is 3792 SCTP_INACTIVE and the path supervision detects that the peer 3793 address is reachable again. 3795 SCTP_INACTIVE: This state is entered whenever a path failure is 3796 detected. 3798 spinfo_cwnd: This contains the peer address' current congestion 3799 window. 3801 spinfo_srtt: This contains the peer address' current smoothed round- 3802 trip time calculation in milliseconds. 3804 spinfo_rto: This contains the peer address' current retransmission 3805 timeout value in milliseconds. 3807 spinfo_mtu: The current path MTU of the peer address. It is the 3808 number of bytes available in an SCTP packet for chunks. 3810 8.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3811 (SCTP_PEER_AUTH_CHUNKS) 3813 This option gets a list of chunk types (see [RFC4960]) for a 3814 specified association that the peer requires to be received 3815 authenticated only. 3817 The following structure is used to access these parameters: 3819 struct sctp_authchunks { 3820 sctp_assoc_t gauth_assoc_id; 3821 uint32_t gauth_number_of_chunks 3822 uint8_t gauth_chunks[]; 3823 }; 3824 gauth_assoc_id: This parameter indicates for which association the 3825 user is requesting the list of peer authenticated chunks. For 3826 one-to-one sockets, this parameter is ignored. Note that the 3827 predefined constants are not allowed with this option. 3829 gauth_number_of_chunks: This parameter gives the number of elements 3830 in the array gauth_chunks. 3832 gauth_chunks: This parameter contains an array of chunk types that 3833 the peer is requesting to be authenticated. If the passed in 3834 buffer size is not large enough to hold the list of chunk types, 3835 ENOBUFS is returned. 3837 8.2.4. Get the List of Chunks the Local Endpoint Requires to be 3838 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3840 This option gets a list of chunk types (see [RFC4960]) for a 3841 specified association that the local endpoint requires to be received 3842 authenticated only. 3844 The following structure is used to access these parameters: 3846 struct sctp_authchunks { 3847 sctp_assoc_t gauth_assoc_id; 3848 uint32_t gauth_number_of_chunks; 3849 uint8_t gauth_chunks[]; 3850 }; 3852 gauth_assoc_id: This parameter is ignored for one-to-one style 3853 sockets. For one-to-many style sockets the application may fill 3854 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 3855 to use SCTP_{CURRENT|ALL}_ASSOC in gauth_assoc_id. 3857 gauth_number_of_chunks: This parameter gives the number of elements 3858 in the array gauth_chunks. 3860 gauth_chunks: This parameter contains an array of chunk types that 3861 the local endpoint is requesting to be authenticated. If the 3862 passed in buffer is not large enough to hold the list of chunk 3863 types, ENOBUFS is returned. 3865 8.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3867 This option gets the current number of associations that are attached 3868 to a one-to-many style socket. The option value is an uint32_t. 3869 Note that this number is only a snap shot. This means that the 3870 number of associations may have changed when the caller gets back the 3871 option result. 3873 For a one-to-one style socket, this socket option results in an 3874 error. 3876 8.2.6. Get the Current Identifiers of Associations 3877 (SCTP_GET_ASSOC_ID_LIST) 3879 This option gets the current list of SCTP association identifiers of 3880 the SCTP associations handled by a one-to-many style socket. 3882 The option value has the structure 3884 struct sctp_assoc_ids { 3885 uint32_t gaids_number_of_ids; 3886 sctp_assoc_t gaids_assoc_id[]; 3887 }; 3889 The caller must provide a large enough buffer to hold all association 3890 identifiers. If the buffer is too small, an error must be returned. 3891 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3892 idea how large the buffer has to be. gaids_number_of_ids gives the 3893 number of elements in the array gaids_assoc_id. Note also that some 3894 or all of sctp_assoc_t returned in the array may become invalid by 3895 the time the caller gets back the result. 3897 For a one-to-one style socket, this socket option results in an 3898 error. 3900 8.3. Write-Only Options 3902 The options defined in this subsection are write-only. Using this 3903 option in a getsockopt() or sctp_opt_info() call will result in an 3904 error indicating EOPNOTSUPP. 3906 8.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3908 Requests that the peer marks the enclosed address as the association 3909 primary (see [RFC5061]). The enclosed address must be one of the 3910 association's locally bound addresses. 3912 The following structure is used to make a set peer primary request: 3914 struct sctp_setpeerprim { 3915 sctp_assoc_t sspp_assoc_id; 3916 struct sockaddr_storage sspp_addr; 3917 }; 3918 sspp_assoc_id: This parameter is ignored for one-to-one style 3919 sockets. For one-to-many style sockets it identifies the 3920 association for this request. Note that the predefined constants 3921 are not allowed on this option. 3923 sspp_addr: The address to set as primary. 3925 8.3.2. Add a Chunk that must be Authenticated (SCTP_AUTH_CHUNK) 3927 This set option adds a chunk type that the user is requesting to be 3928 received only in an authenticated way. Changes to the list of chunks 3929 will only affect future associations on the socket. 3931 The following structure is used to add a chunk: 3933 struct sctp_authchunk { 3934 uint8_t sauth_chunk; 3935 }; 3937 sauth_chunk: This parameter contains a chunk type that the user is 3938 requesting to be authenticated. 3940 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3941 chunks must not be used. If they are used, an error must be 3942 returned. The usage of this option enables SCTP AUTH in cases where 3943 it is not required by other means (for example the use of dynamic 3944 address reconfiguration). 3946 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3948 This option will set a shared secret key that is used to build an 3949 association shared key. 3951 The following structure is used to access and modify these 3952 parameters: 3954 struct sctp_authkey { 3955 sctp_assoc_t sca_assoc_id; 3956 uint16_t sca_keynumber; 3957 uint16_t sca_keylength; 3958 uint8_t sca_key[]; 3959 }; 3961 sca_assoc_id: This parameter indicates what association the shared 3962 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3963 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3964 ignored. Note, however on one to one sockets, that this option 3965 will set a key on the association if the socket is connected, 3966 otherwise this will set a key on the endpoint. 3968 sca_keynumber: This parameter is the shared key identifier by which 3969 the application will refer to this shared key. If a key of the 3970 specified index already exists, then this new key will replace the 3971 old existing key. Note that shared key identifier '0' defaults to 3972 a null key. 3974 sca_keylength: This parameter is the length of the array sca_key. 3976 sca_key: This parameter contains an array of bytes that is to be 3977 used by the endpoint (or association) as the shared secret key. 3978 Note, if the length of this field is zero, a null key is set. 3980 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3982 This set option indicates that the application will no longer send 3983 user messages using the indicated key identifier. 3985 struct sctp_authkeyid { 3986 sctp_assoc_t scact_assoc_id; 3987 uint16_t scact_keynumber; 3988 }; 3990 scact_assoc_id: This parameter indicates which association the 3991 shared key identifier is being deleted from. The special 3992 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3993 sockets, this parameter is ignored. Note, however, that this 3994 option will deactivate the key from the association if the socket 3995 is connected, otherwise this will deactivate the key from the 3996 endpoint. 3998 scact_keynumber: This parameter is the shared key identifier which 3999 the application is requesting to be deactivated. The key 4000 identifier must correspond to an existing shared key. Note if 4001 this parameter is zero, use of the null key identifier '0' is 4002 deactivated on the endpoint and/or association. 4004 The currently active key cannot be deactivated. 4006 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 4008 This set option will delete a shared secret key which has been 4009 deactivated of an SCTP association. 4011 struct sctp_authkeyid { 4012 sctp_assoc_t scact_assoc_id; 4013 uint16_t scact_keynumber; 4015 }; 4017 scact_assoc_id: This parameter indicates which association the 4018 shared key identifier is being deleted from. The special 4019 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 4020 sockets, this parameter is ignored. Note, however, that this 4021 option will delete the key from the association if the socket is 4022 connected, otherwise this will delete the key from the endpoint. 4024 scact_keynumber: This parameter is the shared key identifier which 4025 the application is requesting to be deleted. The key identifier 4026 must correspond to an existing shared key and must not be in use 4027 for any packet being sent by the SCTP implementation. This means 4028 in particular, that it must be deactivated first. Note if this 4029 parameter is zero, use of the null key identifier '0' is deleted 4030 from the endpoint and/or association. 4032 Only deactivated keys that are no longer used by an association can 4033 be deleted. 4035 9. New Functions 4037 Depending on the system, the following interface can be implemented 4038 as a system call or library function. 4040 9.1. sctp_bindx() 4042 This function allows the user to bind a specific subset of addresses 4043 or, if the SCTP extension described in [RFC5061] is supported, add or 4044 delete specific addresses. 4046 The function prototype is 4048 int sctp_bindx(int sd, 4049 struct sockaddr *addrs, 4050 int addrcnt, 4051 int flags); 4053 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 4054 If the sd is an IPv6 socket, the addresses passed can either be IPv4 4055 or IPv6 addresses. 4057 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 4058 Section 3.1.2 for this usage. 4060 addrs is a pointer to an array of one or more socket addresses. Each 4061 address is contained in its appropriate structure. For an IPv6 4062 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 4063 array of sockaddr_in is used. The caller specifies the number of 4064 addresses in the array with addrcnt. Note that the wildcard 4065 addresses cannot be used in combination with non wildcard addresses 4066 on a socket with this function, doing so will result in an error. 4068 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 4069 -1 and sets errno to the appropriate error code. 4071 For SCTP, the port given in each socket address must be the same, or 4072 sctp_bindx() will fail, setting errno to EINVAL. 4074 The flags parameter is formed from the bitwise OR of zero or more of 4075 the following currently defined flags: 4077 o SCTP_BINDX_ADD_ADDR 4079 o SCTP_BINDX_REM_ADDR 4081 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 4082 socket (i.e. endpoint), and SCTP_BINDX_REM_ADDR directs SCTP to 4083 remove the given addresses from the socket. The two flags are 4084 mutually exclusive; if both are given, sctp_bindx() will fail with 4085 EINVAL. A caller may not remove all addresses from a socket; 4086 sctp_bindx() will reject such an attempt with EINVAL. 4088 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 4089 additional addresses with an endpoint after calling bind(). Or use 4090 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 4091 socket is associated with, so that no new association accepted will 4092 be associated with these addresses. If the endpoint supports dynamic 4093 address reconfiguration, an SCTP_BINDX_REM_ADDR or 4094 SCTP_BINDX_ADD_ADDR may cause an endpoint to send the appropriate 4095 message to its peers to change the peers' address lists. 4097 Adding and removing addresses from established associations is an 4098 optional functionality. Implementations that do not support this 4099 functionality should return -1 and set errno to EOPNOTSUPP. 4101 sctp_bindx() can be called on an already bound socket or on an 4102 unbound socket. If the socket is unbound and the first port number 4103 in the addrs is zero, the kernel will choose a port number. All port 4104 numbers after the first one being 0 must also be zero. If the first 4105 port number is not zero, the following port numbers must be zero or 4106 have the same value as the first one. For an already bound socket, 4107 all port numbers provided must be the bound one or 0. 4109 sctp_bindx() is an atomic operation. Therefore, the binding will be 4110 either successful on all addresses or fail on all addresses. If 4111 multiple addresses are provided and the sctp_bindx() call fails there 4112 is no indication which address is responsible for the failure. The 4113 only way to identify the specific error indication is to call 4114 sctp_bindx() sequentially with only one address per call. 4116 9.2. sctp_peeloff() 4118 After an association is established on a one-to-many style socket, 4119 the application may wish to branch off the association into a 4120 separate socket/file descriptor. 4122 This is particularly desirable when, for instance, the application 4123 wishes to have a number of sporadic message senders/receivers remain 4124 under the original one-to-many style socket, but branch off these 4125 associations carrying high volume data traffic into their own 4126 separate socket descriptors. 4128 The application uses the sctp_peeloff() call to branch off an 4129 association into a separate socket (Note the semantics are somewhat 4130 changed from the traditional one-to-one style accept() call). Note 4131 that the new socket is a one-to-one style socket. Thus it will be 4132 confined to operations allowed for a one-to-one style socket. 4134 The function prototype is 4136 int sctp_peeloff(int sd, 4137 sctp_assoc_t assoc_id); 4139 and the arguments are 4141 sd: The original one-to-many style socket descriptor returned from 4142 the socket() system call (see Section 3.1.1). 4144 assoc_id: the specified identifier of the association that is to be 4145 branched off to a separate file descriptor (Note, in a traditional 4146 one-to-one style accept() call, this would be an out parameter, 4147 but for the one-to-many style call, this is an in parameter). 4149 The function returns a non-negative file descriptor representing the 4150 branched-off association, or -1 if an error occurred. The variable 4151 errno is then set appropriately. 4153 9.3. sctp_getpaddrs() 4155 sctp_getpaddrs() returns all peer addresses in an association. 4157 The function prototype is: 4159 int sctp_getpaddrs(int sd, 4160 sctp_assoc_t id, 4161 struct sockaddr **addrs); 4163 On return, addrs will point to a dynamically allocated array of 4164 sockaddr structures of the appropriate type for the socket type. The 4165 caller should use sctp_freepaddrs() to free the memory. Note that 4166 the in/out parameter addrs must not be NULL. 4168 If sd is an IPv4 socket, the addresses returned will be all IPv4 4169 addresses. If sd is an IPv6 socket, the addresses returned can be a 4170 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4171 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4173 For one-to-many style sockets, id specifies the association to query. 4174 For one-to-one style sockets, id is ignored. 4176 On success, sctp_getpaddrs() returns the number of peer addresses in 4177 the association. If there is no association on this socket, 4178 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 4179 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 4180 is undefined. 4182 9.4. sctp_freepaddrs() 4184 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 4186 The function prototype is 4188 void sctp_freepaddrs(struct sockaddr *addrs); 4190 and addrs is the array of peer addresses returned by 4191 sctp_getpaddrs(). 4193 9.5. sctp_getladdrs() 4195 sctp_getladdrs() returns all locally bound address(es) on a socket. 4197 The function prototype is 4199 int sctp_getladdrs(int sd, 4200 sctp_assoc_t id, 4201 struct sockaddr **addrs); 4203 On return, addrs will point to a dynamically allocated array of 4204 sockaddr structures of the appropriate type for the socket type. The 4205 caller should use sctp_freeladdrs() to free the memory. Note that 4206 the in/out parameter addrs must not be NULL. 4208 If sd is an IPv4 socket, the addresses returned will be all IPv4 4209 addresses. If sd is an IPv6 socket, the addresses returned can be a 4210 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4211 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4213 For one-to-many style sockets, id specifies the association to query. 4214 For one-to-one style sockets, id is ignored. 4216 If the id field is set to the value '0' then the locally bound 4217 addresses are returned without regard to any particular association. 4219 On success, sctp_getladdrs() returns the number of local addresses 4220 bound to the socket. If the socket is unbound, sctp_getladdrs() 4221 returns 0, and the value of *addrs is undefined. If an error occurs, 4222 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 4224 9.6. sctp_freeladdrs() 4226 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 4228 The function prototype is 4230 void sctp_freeladdrs(struct sockaddr *addrs); 4232 and addrs is the array of local addresses returned by 4233 sctp_getladdrs(). 4235 9.7. sctp_sendmsg() - DEPRECATED 4237 This function is deprecated, sctp_sendv() (see Section 9.12) should 4238 be used instead. 4240 An implementation may provide a library function (or possibly system 4241 call) to assist the user with the advanced features of SCTP. 4243 The function prototype is 4245 ssize_t sctp_sendmsg(int sd, 4246 const void *msg, 4247 size_t len, 4248 const struct sockaddr *to, 4249 socklen_t tolen, 4250 uint32_t ppid, 4251 uint32_t flags, 4252 uint16_t stream_no, 4253 uint32_t timetolive, 4254 uint32_t context); 4256 and the arguments are: 4258 sd: The socket descriptor. 4260 msg: The message to be sent. 4262 len: The length of the message. 4264 to: The destination address of the message. 4266 tolen: The length of the destination address. 4268 ppid: The same as sinfo_ppid (see Section 5.3.2). 4270 flags: The same as sinfo_flags (see Section 5.3.2). 4272 stream_no: The same as sinfo_stream (see Section 5.3.2). 4274 timetolive: The same as sinfo_timetolive (see Section 5.3.2). 4276 context: The same as sinfo_context (see Section 5.3.2). 4278 The call returns the number of characters sent, or -1 if an error 4279 occurred. The variable errno is then set appropriately. 4281 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 4282 marking is enabled on the socket specified by sd). 4284 Using sctp_sendmsg() on a non-connected one-to-one style socket for 4285 implicit connection setup may or may not work depending on the SCTP 4286 implementation. 4288 9.8. sctp_recvmsg() - DEPRECATED 4290 This function is deprecated, sctp_recvv() (see Section 9.13) should 4291 be used instead. 4293 An implementation may provide a library function (or possibly system 4294 call) to assist the user with the advanced features of SCTP. Note 4295 that in order for the sctp_sndrcvinfo structure to be filled in by 4296 sctp_recvmsg() the caller must enable the sctp_data_io_event with the 4297 SCTP_EVENTS option. Note that the setting of the 4298 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 4299 sctp_sndrcvinfo information to be extended. 4301 The function prototype is 4302 ssize_t sctp_recvmsg(int sd, 4303 void *msg, 4304 size_t len, 4305 struct sockaddr *from, 4306 socklen_t *fromlen 4307 struct sctp_sndrcvinfo *sinfo 4308 int *msg_flags); 4310 and the arguments are 4312 sd: The socket descriptor. 4314 msg: The message buffer to be filled. 4316 len: The length of the message buffer. 4318 from: A pointer to an address to be filled with the sender of this 4319 messages address. 4321 fromlen: An in/out parameter describing the from length. 4323 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 4324 receipt of the message. 4326 msg_flags: A pointer to an integer to be filled with any message 4327 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 4328 field. Options for the receive may also be passed into the value 4329 (e.g. MSG_PEEK). On return from the call, the msg_flags value 4330 will be different than what was sent in to the call. If 4331 implemented via a recvmsg() call, the msg_flags should only 4332 contain the value of the flags from the recvmsg() call. 4334 The call returns the number of bytes received, or -1 if an error 4335 occurred. The variable errno is then set appropriately. 4337 9.9. sctp_connectx() 4339 An implementation may provide a library function (or possibly system 4340 call) to assist the user with associating to an endpoint that is 4341 multi-homed. Much like sctp_bindx() this call allows a caller to 4342 specify multiple addresses at which a peer can be reached. The way 4343 the SCTP stack uses the list of addresses to set up the association 4344 is implementation dependent. This function only specifies that the 4345 stack will try to make use of all the addresses in the list when 4346 needed. 4348 Note that the list of addresses passed in is only used for setting up 4349 the association. It does not necessarily equal the set of addresses 4350 the peer uses for the resulting association. If the caller wants to 4351 find out the set of peer addresses, it must use sctp_getpaddrs() to 4352 retrieve them after the association has been set up. 4354 The function prototype is 4356 int sctp_connectx(int sd, 4357 struct sockaddr *addrs, 4358 int addrcnt, 4359 sctp_assoc_t *id); 4361 and the arguments are: 4363 sd: The socket descriptor. 4365 addrs: An array of addresses. 4367 addrcnt: The number of addresses in the array. 4369 id: An output parameter that if passed in as a non-NULL will return 4370 the association identifier for the newly created association (if 4371 successful). 4373 The call returns 0 on success or -1 if an error occurred. The 4374 variable errno is then set appropriately. 4376 9.10. sctp_send() - DEPRECATED 4378 This function is deprecated, sctp_sendv() should be used instead. 4380 An implementation may provide another alternative function or system 4381 call to assist an application with the sending of data without the 4382 use of the CMSG header structures. 4384 The function prototype is 4386 ssize_t sctp_send(int sd, 4387 const void *msg, 4388 size_t len, 4389 const struct sctp_sndrcvinfo *sinfo, 4390 int flags); 4392 and the arguments are 4394 sd: The socket descriptor. 4396 msg: The message to be sent. 4398 len: The length of the message. 4400 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4401 in Section 5.3.2 for a sendmsg() call. 4403 flags: The same flags as used by the sendmsg() call flags (e.g. 4404 MSG_DONTROUTE). 4406 The call returns the number of bytes sent, or -1 if an error 4407 occurred. The variable errno is then set appropriately. 4409 This function call may also be used to terminate an association using 4410 an association identifier by setting the sinfo.sinfo_flags to 4411 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4412 to be terminated. In such a case the len of the message can be zero. 4414 Using sctp_send() on a non-connected one-to-one style socket for 4415 implicit connection setup may or may not work depending on the SCTP 4416 implementation. 4418 Sending a message using sctp_send() is atomic unless explicit EOR 4419 marking is enabled on the socket specified by sd. 4421 9.11. sctp_sendx() - DEPRECATED 4423 This function is deprecated, sctp_sendv() should be used instead. 4425 An implementation may provide another alternative function or system 4426 call to assist an application with the sending of data without the 4427 use of the CMSG header structures that also gives a list of 4428 addresses. The list of addresses is provided for implicit 4429 association setup. In such a case the list of addresses serves the 4430 same purpose as the addresses given in sctp_connectx() (see 4431 Section 9.9). 4433 The function prototype is 4435 ssize_t sctp_sendx(int sd, 4436 const void *msg, 4437 size_t len, 4438 struct sockaddr *addrs, 4439 int addrcnt, 4440 struct sctp_sndrcvinfo *sinfo, 4441 int flags); 4443 and the arguments are: 4445 sd: The socket descriptor. 4447 msg: The message to be sent. 4449 len: The length of the message. 4451 addrs: Is an array of addresses. 4453 addrcnt: The number of addresses in the array. 4455 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4456 in Section 5.3.2 for a sendmsg() call. 4458 flags: The same flags as used by the sendmsg() call flags (e.g. 4459 MSG_DONTROUTE). 4461 The call returns the number of bytes sent, or -1 if an error 4462 occurred. The variable errno is then set appropriately. 4464 Note that in case of implicit connection setup, on return from this 4465 call the sinfo_assoc_id field of the sinfo structure will contain the 4466 new association identifier. 4468 This function call may also be used to terminate an association using 4469 an association identifier by setting the sinfo.sinfo_flags to 4470 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4471 to be terminated. In such a case the len of the message would be 4472 zero. 4474 Sending a message using sctp_sendx() is atomic unless explicit EOR 4475 marking is enabled on the socket specified by sd. 4477 Using sctp_sendx() on a non-connected one-to-one style socket for 4478 implicit connection setup may or may not work depending on the SCTP 4479 implementation. 4481 9.12. sctp_sendv() 4483 The function prototype is 4485 ssize_t sctp_sendv(int sd, 4486 const struct iovec *iov, 4487 int iovcnt, 4488 struct sockaddr *addrs, 4489 int addrcnt, 4490 void *info, 4491 socklen_t infolen, 4492 unsigned int infotype, 4493 int flags); 4495 The function sctp_sendv() provides an extensible way for an 4496 application to communicate different send attributes to the SCTP 4497 stack when sending a message. An implementation may provide 4498 sctp_sendv() as a library function or a system call. 4500 This document defines three types of attributes which can be used to 4501 describe a message to be sent. They are struct sctp_sndinfo 4502 (Section 5.3.4), struct sctp_prinfo (Section 5.3.7), and struct 4503 sctp_authinfo (Section 5.3.8). The following structure 4504 sctp_sendv_spa is defined to be used when more than one of the above 4505 attributes are needed to describe a message to be sent. 4507 struct sctp_sendv_spa { 4508 uint32_t sendv_flags; 4509 struct sctp_sndinfo sendv_sndinfo; 4510 struct sctp_prinfo sendv_prinfo; 4511 struct sctp_authinfo sendv_authinfo; 4512 }; 4514 The sendv_flags field holds a bit wise OR of SCTP_SEND_SNDINFO_VALID, 4515 SCTP_SEND_PRINFO_VALID and SCTP_SEND_AUTHINFO_VALID indicating if the 4516 sendv_sndinfo/sendv_prinfo/sendv_authinfo fields contain valid 4517 information. 4519 In future, when new send attributes are needed, new structures can be 4520 defined. But those new structures do not need to be based on any of 4521 the above defined structures. 4523 The function takes the following arguments: 4525 sd: The socket descriptor. 4527 iov: The gather buffer. The data in the buffer is treated as one 4528 single user message. 4530 iovcnt: The number of elements in iov. 4532 addrs: An array of addresses to be used to set up an association or 4533 one single address to be used to send the message. Pass in NULL 4534 if the caller does not want to set up an association nor want to 4535 send the message to a specific address. 4537 addrcnt: The number of addresses in the addrs array. 4539 info: A pointer to the buffer containing the attribute associated 4540 with the message to be sent. The type is indicated by the 4541 info_type parameter. 4543 infolen: The length in bytes of info. 4545 infotype: Identifies the type of the information provided in info. 4546 The current defined values are: 4548 SCTP_SENDV_NOINFO: No information is provided. The parameter 4549 info is a NULL pointer and infolen is 0. 4551 SCTP_SENDV_SNDINFO: The parameter info is pointing to a struct 4552 sctp_sndinfo. 4554 SCTP_SENDV_PRINFO: The parameter info is pointing to a struct 4555 sctp_prinfo. 4557 SCTP_SENDV_AUTHINFO: The parameter info is pointing to a struct 4558 sctp_authinfo. 4560 SCTP_SENDV_SPA: The parameter info is pointing to a struct 4561 sctp_sendv_spa. 4563 flags: The same flags as used by the sendmsg() call flags (e.g. 4564 MSG_DONTROUTE). 4566 The call returns the number of bytes sent, or -1 if an error 4567 occurred. The variable errno is then set appropriately. 4569 A note on one-to-many style socket. The struct sctp_sndinfo 4570 attribute must always be used in order to specify the association the 4571 message is to be sent on. The only case where it is not needed is 4572 when this call is used to set up a new association. 4574 The caller provides a list of addresses in the addrs parameter to set 4575 up an association. This function will behave like calling 4576 sctp_connectx() (see Section 9.9) first using the list of addresses 4577 and then calling sendmsg() with the given message and attributes. 4578 For an one-to-many style socket, if struct sctp_sndinfo attribute is 4579 provided, the snd_assoc_id field must be 0. When this function 4580 returns, the snd_assoc_id field will contain the association 4581 identifier of the newly established association. Note that struct 4582 sctp_sndinfo attribute is not required to set up an association for 4583 one-to-many style socket. If this attribute is not provided, the 4584 caller can enable the SCTP_ASSOC_CHANGE notification and use the 4585 SCTP_COMM_UP message to find out the association identifier. 4587 If the caller wants to send the message to a specific peer address 4588 (hence overriding the primary address), it can provide the specific 4589 address in the addrs parameter and provide a struct sctp_sndinfo 4590 attribute with the field snd_flags set to SCTP_ADDR_OVER. 4592 This function call may also be used to terminate an association. The 4593 caller provides an sctp_sndinfo attribute with the snd_flags set to 4594 SCTP_EOF. In this case the len of the message would be zero. 4596 Sending a message using sctp_sendv() is atomic unless explicit EOR 4597 marking is enabled on the socket specified by sd. 4599 9.13. sctp_recvv() 4601 The function prototype is 4603 ssize_t sctp_recvv(int sd, 4604 const struct iovec *iov, 4605 int iovlen, 4606 struct sockaddr *from, 4607 socklen_t *fromlen, 4608 void *info, 4609 socklen_t *infolen, 4610 unsigned int *infotype, 4611 int *flags); 4613 The function sctp_recvv() provides an extensible way for the SCTP 4614 stack to pass up different SCTP attributes associated with a received 4615 message to an application. An implementation may provide 4616 sctp_recvv() as a library function or as a system call. 4618 This document defines two types of attributes which can be returned 4619 by this call, the attribute of the received message and the attribute 4620 of the next message in receive buffer. The caller enables the 4621 SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these 4622 attributes respectively. Attributes of the received message are 4623 returned in struct sctp_rcvinfo (Section 5.3.5) and attributes of the 4624 next message are returned in struct sctp_nxtinfo (Section 5.3.6). If 4625 both options are enabled, both attributes are returned using the 4626 following structure. 4628 struct sctp_recvv_rn { 4629 struct sctp_rcvinfo recvv_rcvinfo; 4630 struct sctp_nxtinfo recvv_nxtinfo; 4631 }; 4633 In future, new structures can be defined to hold new types of 4634 attributes. The new structures do not need to be based on struct 4635 sctp_recvv_rn or struct sctp_rcvinfo. 4637 This function takes the following arguments: 4639 sd: The socket descriptor. 4641 iov: The scatter buffer. Only one user message is returned in this 4642 buffer. 4644 iovlen: The number of elements in iov. 4646 from: A pointer to an address to be filled with the sender of the 4647 received message's address. 4649 fromlen: An in/out parameter describing the from length. 4651 info: A pointer to the buffer to hold the attributes of the received 4652 message. The structure type of info is determined by the 4653 info_type parameter. 4655 infolen: An in/out parameter describing the size of the info buffer. 4657 infotype: In return, *info_type is set to the type of the info 4658 buffer. The current defined values are: 4660 SCTP_RECVV_NOINFO: If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO 4661 options are not enabled, no attribute will be returned. If 4662 only the SCTP_RECVNXTINFO option is enabled but there is no 4663 next message in the buffer, there will also no attribute be 4664 returned. In these cases *info_type will be set to 4665 SCTP_RECVV_NOINFO. 4667 SCTP_RECVV_RCVINFO: The type of info is struct sctp_rcvinfo and 4668 the attribute is about the received message. 4670 SCTP_RECVV_NXTINFO: The type of info is struct sctp_nxtinfo and 4671 the attribute is about the next message in receive buffer. 4672 This is the case when only the SCTP_RECVNXTINFO option is 4673 enabled and there is a next message in buffer. 4675 SCTP_RECVV_RN: The type of info is struct sctp_recvv_rn. The 4676 recvv_rcvinfo field is the attribute of the received message 4677 and the recvv_nxtinfo field is the attribute of the next 4678 message in buffer. This is the case when both SCTP_RECVRCVINFO 4679 and SCTP_RECVNXTINFO options are enabled and there is a next 4680 message in the receive buffer. 4682 flags: A pointer to an integer to be filled with any message flags 4683 (e.g. MSG_NOTIFICATION). Note that this field is an in/out 4684 parameter. Options for the receive may also be passed into the 4685 value (e.g. MSG_PEEK). On return from the call, the flags value 4686 will be different than what was sent in to the call. If 4687 implemented via a recvmsg() call, the flags should only contain 4688 the value of the flags from the recvmsg() call when calling 4689 sctp_recvv() and on return it has the value from msg_flags. 4691 The call returns the number of bytes received, or -1 if an error 4692 occurred. The variable errno is then set appropriately. 4694 10. IANA Considerations 4696 This document requires no actions from IANA. 4698 11. Security Considerations 4700 Many TCP and UDP implementations reserve port numbers below 1024 for 4701 privileged users. If the target platform supports privileged users, 4702 the SCTP implementation should restrict the ability to call bind() or 4703 sctp_bindx() on these port numbers to privileged users. 4705 Similarly unprivileged users should not be able to set protocol 4706 parameters that could result in the congestion control algorithm 4707 being more aggressive than permitted on the public Internet. These 4708 parameters are: 4710 o struct sctp_rtoinfo 4712 If an unprivileged user inherits a one-to-many style socket with open 4713 associations on a privileged port, it may be permitted to accept new 4714 associations, but it should not be permitted to open new 4715 associations. This could be relevant for the r* family of protocols. 4717 Applications using the one-to-many style sockets and using the 4718 interleave level if 0 are subject to denial of service attacks as 4719 described in Section 8.1.20. 4721 12. Acknowledgments 4723 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 4724 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 4725 early formation of this document. 4727 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, 4728 Martin Becke, Jon Berger, Mark Butler, Thomas Dreibholz, Scott 4729 Kimble, Renee Revis, Andreas Fink, Jonathan Leighton, Irene 4730 Ruengeler, Dan Wing, and many others on the TSVWG mailing list for 4731 contributing valuable comments. 4733 A special thanks to Phillip Conrad, for his suggested text, quick and 4734 constructive insights, and most of all his persistent fighting to 4735 keep the interface to SCTP usable for the application programmer. 4737 13. References 4739 13.1. Normative References 4741 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 4742 Stevens, "Basic Socket Interface Extensions for IPv6", 4743 RFC 3493, February 2003. 4745 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4746 "Advanced Sockets Application Program Interface (API) for 4747 IPv6", RFC 3542, May 2003. 4749 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 4750 Conrad, "Stream Control Transmission Protocol (SCTP) 4751 Partial Reliability Extension", RFC 3758, May 2004. 4753 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 4754 "Authenticated Chunks for the Stream Control Transmission 4755 Protocol (SCTP)", RFC 4895, August 2007. 4757 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 4758 RFC 4960, September 2007. 4760 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 4761 Kozuka, "Stream Control Transmission Protocol (SCTP) 4762 Dynamic Address Reconfiguration", RFC 5061, 4763 September 2007. 4765 13.2. Informative References 4767 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4768 RFC 793, September 1981. 4770 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4771 August 1980. 4773 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 4774 Functional Specification", RFC 1644, July 1994. 4776 Appendix A. One-to-One Style Code Example 4778 The following code is an implementation of a simple client which 4779 sends a number of messages marked for unordered delivery to an echo 4780 server making use of all outgoing streams. The example shows how to 4781 use some features of one-to-one style IPv4 SCTP sockets, including: 4783 o Creating and connecting an SCTP socket. 4785 o Requesting to negotiate a number of outgoing streams. 4787 o Determining the negotiated number of outgoing streams. 4789 o Setting an adaptation layer indication. 4791 o Sending messages with a given payload protocol identifier on a 4792 particular stream using sctp_sendv(). 4794 #include 4795 #include 4796 #include 4797 #include 4798 #include 4799 #include 4800 #include 4801 #include 4802 #include 4804 #define PORT 9 4805 #define ADDR "127.0.0.1" 4806 #define SIZE_OF_MESSAGE 1000 4807 #define NUMBER_OF_MESSAGES 10 4808 #define PPID 1234 4810 int 4811 main(void) { 4812 unsigned int i; 4813 int sd; 4814 struct sockaddr_in addr; 4815 char buffer[SIZE_OF_MESSAGE]; 4816 struct iovec iov; 4817 struct sctp_status status; 4818 struct sctp_initmsg init; 4819 struct sctp_sndinfo info; 4820 struct sctp_setadaptation ind; 4821 socklen_t opt_len; 4823 /* Create a one-to-one style SCTP socket. */ 4824 if ((sd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) < 0) { 4825 perror("socket"); 4826 exit(1); 4827 } 4829 /* Prepare for requesting 2048 outgoing streams. */ 4830 memset(&init, 0, sizeof(init)); 4831 init.sinit_num_ostreams = 2048; 4832 if (setsockopt(sd, IPPROTO_SCTP, SCTP_INITMSG, 4833 &init, (socklen_t)sizeof(init)) < 0) { 4834 perror("setsockopt"); 4835 exit(1); 4836 } 4838 ind.ssb_adaptation_ind = 0x01020304; 4839 if (setsockopt(sd, IPPROTO_SCTP, SCTP_ADAPTATION_LAYER, 4840 &ind, (socklen_t)sizeof(ind)) < 0) { 4841 perror("setsockopt"); 4842 exit(1); 4843 } 4845 /* Connect to the discard server. */ 4846 memset(&addr, 0, sizeof(addr)); 4847 #ifdef HAVE_SIN_LEN 4848 addr.sin_len = sizeof(struct sockaddr_in); 4849 #endif 4850 addr.sin_family = AF_INET; 4851 addr.sin_port = htons(PORT); 4852 addr.sin_addr.s_addr = inet_addr(ADDR); 4853 if (connect(sd, 4854 (const struct sockaddr *)&addr, 4855 sizeof(struct sockaddr_in)) < 0) { 4856 perror("connect"); 4857 exit(1); 4858 } 4860 /* Get the actual number of outgoing streams. */ 4861 memset(&status, 0, sizeof(status)); 4862 opt_len = (socklen_t)sizeof(status); 4863 if (getsockopt(sd, IPPROTO_SCTP, SCTP_STATUS, 4864 &status, &opt_len) < 0) { 4865 perror("getsockopt"); 4866 exit(1); 4867 } 4868 memset(&info, 0, sizeof(info)); 4869 info.snd_ppid = htonl(PPID); 4870 info.snd_flags = SCTP_UNORDERED; 4871 memset(buffer, 'A', SIZE_OF_MESSAGE); 4872 iov.iov_base = buffer; 4873 iov.iov_len = SIZE_OF_MESSAGE; 4874 for (i = 0; i < NUMBER_OF_MESSAGES; i++) { 4875 info.snd_sid = i % status.sstat_outstrms; 4876 if (sctp_sendv(sd, 4877 (const struct iovec *)&iov, 1, 4878 NULL, 0, 4879 &info, sizeof(info), SCTP_SENDV_SNDINFO, 4880 0) < 0) { 4881 perror("sctp_sendv"); 4882 exit(1); 4883 } 4884 } 4886 if (close(sd) < 0) { 4887 perror("close"); 4888 exit(1); 4889 } 4890 return(0); 4891 } 4893 Appendix B. One-to-Many Style Code Example 4895 The following code is a simple implementation of a discard server 4896 over SCTP. The example shows how to use some features of one-to-many 4897 style IPv6 SCTP sockets, including: 4899 o Opening and binding of a socket. 4901 o Enabling notifications. 4903 o Handling notifications. 4905 o Configuring the auto close timer. 4907 o Using sctp_recvv() to receive messages. 4909 Please note that this server can be used in combination with the 4910 client described in Appendix A. 4912 #include 4913 #include 4914 #include 4915 #include 4916 #include 4917 #include 4918 #include 4919 #include 4920 #include 4922 #define BUFFER_SIZE (1<<16) 4923 #define PORT 9 4924 #define ADDR "0.0.0.0" 4925 #define TIMEOUT 5 4927 static void 4928 print_notification(void *buf) 4929 { 4930 struct sctp_assoc_change *sac; 4931 struct sctp_paddr_change *spc; 4932 struct sctp_adaptation_event *sad; 4933 union sctp_notification *snp; 4934 char addrbuf[INET6_ADDRSTRLEN]; 4935 const char *ap; 4936 struct sockaddr_in *sin; 4937 struct sockaddr_in6 *sin6; 4939 snp = buf; 4941 switch (snp->sn_header.sn_type) { 4942 case SCTP_ASSOC_CHANGE: 4943 sac = &snp->sn_assoc_change; 4944 printf("^^^ Association change: "); 4945 switch (sac->sac_state) { 4946 case SCTP_COMM_UP: 4947 printf("Communication up (streams (in/out)=(%u/%u)).\n", 4948 sac->sac_inbound_streams, sac->sac_outbound_streams); 4949 break; 4950 case SCTP_COMM_LOST: 4951 printf("Communication lost (error=%d).\n", sac->sac_error); 4952 break; 4953 case SCTP_RESTART: 4954 printf("Communication restarted (streams (in/out)=(%u/%u).\n", 4955 sac->sac_inbound_streams, sac->sac_outbound_streams); 4956 break; 4957 case SCTP_SHUTDOWN_COMP: 4958 printf("Communication completed.\n"); 4959 break; 4960 case SCTP_CANT_STR_ASSOC: 4961 printf("Communication couldn't be started.\n"); 4962 break; 4964 default: 4965 printf("Unknown state: %d.\n", sac->sac_state); 4966 break; 4967 } 4968 break; 4969 case SCTP_PEER_ADDR_CHANGE: 4970 spc = &snp->sn_paddr_change; 4971 if (spc->spc_aaddr.ss_family == AF_INET) { 4972 sin = (struct sockaddr_in *)&spc->spc_aaddr; 4973 ap = inet_ntop(AF_INET, &sin->sin_addr, 4974 addrbuf, INET6_ADDRSTRLEN); 4975 } else { 4976 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 4977 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 4978 addrbuf, INET6_ADDRSTRLEN); 4979 } 4980 printf("^^^ Peer Address change: %s ", ap); 4981 switch (spc->spc_state) { 4982 case SCTP_ADDR_AVAILABLE: 4983 printf("is available.\n"); 4984 break; 4985 case SCTP_ADDR_UNREACHABLE: 4986 printf("is not available (error=%d).\n", spc->spc_error); 4987 break; 4988 case SCTP_ADDR_REMOVED: 4989 printf("was removed.\n"); 4990 break; 4991 case SCTP_ADDR_ADDED: 4992 printf("was added.\n"); 4993 break; 4994 case SCTP_ADDR_MADE_PRIM: 4995 printf("is primary.\n"); 4996 break; 4997 default: 4998 printf("unknown state (%d).\n", spc->spc_state); 4999 break; 5000 } 5001 break; 5002 case SCTP_SHUTDOWN_EVENT: 5003 printf("^^^ Shutdown received.\n"); 5004 break; 5005 case SCTP_ADAPTATION_INDICATION: 5006 sad = &snp->sn_adaptation_event; 5007 printf("^^^ Adaptation indication 0x%08x received.\n", 5008 sad->sai_adaptation_ind); 5009 break; 5010 default: 5011 printf("^^^ Unknown event of type: %u.\n", 5012 snp->sn_header.sn_type); 5013 break; 5014 }; 5015 } 5017 int 5018 main(void) { 5019 int sd, flags, timeout, on; 5020 ssize_t n; 5021 unsigned int i; 5022 union { 5023 struct sockaddr sa; 5024 struct sockaddr_in sin; 5025 struct sockaddr_in6 sin6; 5026 } addr; 5027 socklen_t fromlen, infolen; 5028 struct sctp_rcvinfo info; 5029 unsigned int infotype; 5030 struct iovec iov; 5031 char buffer[BUFFER_SIZE]; 5032 struct sctp_event event; 5033 uint16_t event_types[] = {SCTP_ASSOC_CHANGE, 5034 SCTP_PEER_ADDR_CHANGE, 5035 SCTP_SHUTDOWN_EVENT, 5036 SCTP_ADAPTATION_INDICATION}; 5038 /* Create a 1-to-many style SCTP socket. */ 5039 if ((sd = socket(AF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP)) < 0) { 5040 perror("socket"); 5041 exit(1); 5042 } 5044 /* Enable the events of interest. */ 5045 memset(&event, 0, sizeof(event)); 5046 event.se_assoc_id = SCTP_FUTURE_ASSOC; 5047 event.se_on = 1; 5048 for (i = 0; i < sizeof(event_types)/sizeof(uint16_t); i++) { 5049 event.se_type = event_types[i]; 5050 if (setsockopt(sd, IPPROTO_SCTP, SCTP_EVENT, 5051 &event, sizeof(event)) < 0) { 5052 perror("setsockopt"); 5053 exit(1); 5054 } 5055 } 5057 /* Configure auto-close timer. */ 5058 timeout = TIMEOUT; 5059 if (setsockopt(sd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 5060 &timeout, sizeof(timeout)) < 0) { 5061 perror("setsockopt SCTP_AUTOCLOSE"); 5062 exit(1); 5063 } 5065 /* Enable delivery of SCTP_RCVINFO. */ 5066 on = 1; 5067 if (setsockopt(sd, IPPROTO_SCTP, SCTP_RECVRCVINFO, 5068 &on, sizeof(on)) < 0) { 5069 perror("setsockopt SCTP_RECVRCVINFO"); 5070 exit(1); 5071 } 5073 /* Bind the socket to all local addresses. */ 5074 memset(&addr, 0, sizeof(addr)); 5075 #ifdef HAVE_SIN6_LEN 5076 addr.sin6.sin6_len = sizeof(addr.sin6); 5077 #endif 5078 addr.sin6.sin6_family = AF_INET6; 5079 addr.sin6.sin6_port = htons(PORT); 5080 addr.sin6.sin6_addr = in6addr_any; 5081 if (bind(sd, &addr.sa, sizeof(addr.sin6)) < 0) { 5082 perror("bind"); 5083 exit(1); 5084 } 5085 /* Enable accepting associations. */ 5086 if (listen(sd, 1) < 0) { 5087 perror("listen"); 5088 exit(1); 5089 } 5091 for (;;) { 5092 flags = 0; 5093 memset(&addr, 0, sizeof(addr)); 5094 fromlen = (socklen_t)sizeof(addr); 5095 memset(&info, 0, sizeof(info)); 5096 infolen = (socklen_t)sizeof(info); 5097 infotype = 0; 5098 iov.iov_base = buffer; 5099 iov.iov_len = BUFFER_SIZE; 5101 n = sctp_recvv(sd, &iov, 1, 5102 &addr.sa, &fromlen, 5103 &info, &infolen, &infotype, 5104 &flags); 5106 if (flags & MSG_NOTIFICATION) { 5107 print_notification(iov.iov_base); 5109 } else { 5110 char addrbuf[INET6_ADDRSTRLEN]; 5111 const char *ap; 5112 in_port_t port; 5114 if (addr.sa.sa_family == AF_INET) { 5115 ap = inet_ntop(AF_INET, &addr.sin.sin_addr, 5116 addrbuf, INET6_ADDRSTRLEN); 5117 port = ntohs(addr.sin.sin_port); 5118 } else { 5119 ap = inet_ntop(AF_INET6, &addr.sin6.sin6_addr, 5120 addrbuf, INET6_ADDRSTRLEN); 5121 port = ntohs(addr.sin6.sin6_port); 5122 } 5123 printf("Message received from %s:%u: len=%d", 5124 ap, port, (int)n); 5125 switch (infotype) { 5126 case SCTP_RECVV_RCVINFO: 5127 printf(", sid=%u", info.rcv_sid); 5128 if (info.rcv_flags & SCTP_UNORDERED) { 5129 printf(", unordered"); 5130 } else { 5131 printf(", ssn=%u", info.rcv_ssn); 5132 } 5133 printf(", tsn=%u", info.rcv_tsn); 5134 printf(", ppid=%u.\n", ntohl(info.rcv_ppid)); 5135 break; 5136 case SCTP_RECVV_NOINFO: 5137 case SCTP_RECVV_NXTINFO: 5138 case SCTP_RECVV_RN: 5139 printf(".\n"); 5140 break; 5141 default: 5142 printf(" unknown infotype.\n"); 5143 } 5144 } 5145 } 5147 if (close(sd) < 0) { 5148 perror("close"); 5149 exit(1); 5150 } 5152 return (0); 5153 } 5155 Authors' Addresses 5157 Randall R. Stewart 5158 Adara Networks 5159 Chapin, SC 29036 5160 USA 5162 Email: randall@lakerest.net 5164 Michael Tuexen 5165 Muenster University of Applied Sciences 5166 Stegerwaldstr. 39 5167 48565 Steinfurt 5168 Germany 5170 Email: tuexen@fh-muenster.de 5172 Kacheong Poon 5173 Oracle Corporation 5175 Email: ka-cheong.poon@oracle.com 5177 Peter Lei 5178 Cisco Systems, Inc. 5179 9501 Technology Blvd 5180 West Office Center 5181 Rosemont, IL 60018 5182 USA 5184 Email: peterlei@cisco.com 5186 Vladislav Yasevich 5187 HP 5188 110 Spitrook Rd 5189 Nashua, NH 03062 5190 USA 5192 Email: vladislav.yasevich@hp.com