idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-29.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 (April 23, 2011) is 4744 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: October 25, 2011 Muenster Univ. of Appl. Sciences 6 K. Poon 7 Oracle Corporation 8 P. Lei 9 Cisco Systems, Inc. 10 V. Yasevich 11 HP 12 April 23, 2011 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-29.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 October 25, 2011. 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 Address Structure (IPv4) 112 (SCTP_DSTADDRV4) . . . . . . . . . . . . . . . . . . 40 113 5.3.10. SCTP Destination Address Structure (IPv6) 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 . . . . . . . . . . . . . . . . . . . . . . 65 143 8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . 66 144 8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 66 145 8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 66 146 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . 67 147 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 67 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) . . . 68 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 . . . . . . . . . . . . . 71 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) . . . . . . . . . . . . . . . . . . 72 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 . . . . . . . . . 76 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) . . . . 77 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) . . . . . 78 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) . 79 184 8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 79 185 8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . 80 186 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . 81 187 8.2.3. Get the List of Chunks the Peer Requires to be 188 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 82 189 8.2.4. Get the List of Chunks the Local Endpoint Requires 190 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . 83 191 8.2.5. Get the Current Number of Associations 192 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 83 193 8.2.6. Get the Current Identifiers of Associations 194 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . 84 195 8.3. Write-Only Options . . . . . . . . . . . . . . . . . . . 84 196 8.3.1. Set Peer Primary Address 197 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . 84 198 8.3.2. Add a Chunk that must be Authenticated 199 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 85 200 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . 85 201 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . 86 202 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . 86 203 9. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 87 204 9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . 87 205 9.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . 89 206 9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . 89 207 9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 90 208 9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . 90 209 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 91 210 9.7. sctp_sendmsg() - DEPRECATED . . . . . . . . . . . . . . . 91 211 9.8. sctp_recvmsg() - DEPRECATED . . . . . . . . . . . . . . . 92 212 9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 93 213 9.10. sctp_send() - DEPRECATED . . . . . . . . . . . . . . . . 94 214 9.11. sctp_sendx() - DEPRECATED . . . . . . . . . . . . . . . . 95 215 9.12. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 96 216 9.13. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . 99 217 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 101 218 11. Security Considerations . . . . . . . . . . . . . . . . . . . 101 219 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 101 220 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 102 221 13.1. Normative References . . . . . . . . . . . . . . . . . . 102 222 13.2. Informative References . . . . . . . . . . . . . . . . . 102 223 Appendix A. One-to-One Style Code Example . . . . . . . . . . . 102 224 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 105 225 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 110 227 1. Introduction 229 The sockets API has provided a standard mapping of the Internet 230 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 231 [RFC0768] have benefited from this standard representation and access 232 method across many diverse platforms. SCTP is a new protocol that 233 provides many of the characteristics of TCP but also incorporates 234 semantics more akin to UDP. This document defines a method to map 235 the existing sockets API for use with SCTP, providing both a base for 236 access to new features and compatibility so that most existing TCP 237 applications can be migrated to SCTP with few (if any) changes. 239 There are three basic design objectives: 241 1. Maintain consistency with existing sockets APIs: We define a 242 sockets mapping for SCTP that is consistent with other sockets 243 API protocol mappings (for instance UDP, TCP, IPv4, and IPv6). 245 2. Support a one-to-many style interface: This set of semantics is 246 similar to that defined for connection-less protocols, such as 247 UDP. A one-to-many style SCTP socket should be able to control 248 multiple SCTP associations. This is similar to a UDP socket, 249 which can communicate with many peer endpoints. Each of these 250 associations is assigned an association identifier so that an 251 application can use the ID to differentiate them. Note that SCTP 252 is connection-oriented in nature, and it does not support 253 broadcast or multicast communications, as UDP does. 255 3. Support a one-to-one style interface: This interface supports a 256 similar semantics as sockets for connection-oriented protocols, 257 such as TCP. A one-to-one style SCTP socket should only control 258 one SCTP association. One purpose of defining this interface is 259 to allow existing applications built on other connection-oriented 260 protocols to be ported to use SCTP with very little effort. 261 Developers familiar with these semantics can easily adapt to 262 SCTP. Another purpose is to make sure that existing mechanisms 263 in most operating systems that support sockets, such as select(), 264 should continue to work with this style of socket. Extensions 265 are added to this mapping to provide mechanisms to exploit new 266 features of SCTP. 268 Goals 2 and 3 are not compatible, so this document defines two modes 269 of mapping, namely the one-to-many style mapping and the one-to-one 270 style mapping. These two modes share some common data structures and 271 operations, but will require the use of two different application 272 programming styles. Note that all new SCTP features can be used with 273 both styles of socket. The decision on which one to use depends 274 mainly on the nature of applications. 276 A mechanism is defined to extract a one-to-many style SCTP 277 association into a one-to-one style socket. 279 Some of the SCTP mechanisms cannot be adequately mapped to an 280 existing socket interface. In some cases, it is more desirable to 281 have a new interface instead of using existing socket calls. 282 Section 9 of this document describes these new interfaces. 284 2. Data Types 286 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 287 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 288 (e.g. uint16_t). This document also assumes the argument data types 289 from 1003.1g when possible (e.g. the final argument to setsockopt() 290 is a size_t value). Whenever buffer sizes are specified, the POSIX 291 1003.1 size_t data type is used. 293 3. One-to-Many Style Interface 295 In the one-to-many style interface there is a 1 to many relationship 296 between sockets and associations. 298 3.1. Basic Operation 300 A typical server in this style uses the following socket calls in 301 sequence to prepare an endpoint for servicing requests: 303 o socket() 305 o bind() 307 o listen() 309 o recvmsg() 311 o sendmsg() 313 o close() 315 A typical client uses the following calls in sequence to setup an 316 association with a server to request services: 318 o socket() 320 o sendmsg() 321 o recvmsg() 323 o close() 325 In this style, by default, all the associations connected to the 326 endpoint are represented with a single socket. Each association is 327 assigned an association identifier (type is sctp_assoc_t) so that an 328 application can use it to differentiate among them. In some 329 implementations, the peer endpoints' addresses can also be used for 330 this purpose. But this is not required for performance reasons. If 331 an implementation does not support using addresses to differentiate 332 between different associations, the sendto() call can only be used to 333 setup an association implicitly. It cannot be used to send data to 334 an established association as the association identifier cannot be 335 specified. 337 Once an association identifier is assigned to an SCTP association, 338 that identifier will not be reused until the application explicitly 339 terminates the use of the association. The resources belonging to 340 that association will not be freed until that happens. This is 341 similar to the close() operation on a normal socket. The only 342 exception is when the SCTP_AUTOCLOSE option (Section 8.1.8) is set. 343 In this case, after the association is terminated gracefully and 344 automatically, the association identifier assigned to it can be 345 reused. All applications using this option should be aware of this 346 to avoid the possible problem of sending data to an incorrect peer 347 endpoint. 349 If the server or client wishes to branch an existing association off 350 to a separate socket, it is required to call sctp_peeloff() and to 351 specify the association identifier. The sctp_peeloff() call will 352 return a new one-to-one style socket which can then be used with 353 recv() and send() functions for message passing. See Section 9.2 for 354 more on branched-off associations. 356 Once an association is branched off to a separate socket, it becomes 357 completely separated from the original socket. All subsequent 358 control and data operations to that association must be done through 359 the new socket. For example, the close operation on the original 360 socket will not terminate any associations that have been branched 361 off to a different socket. 363 One-to-many style socket calls are discussed in more detail in the 364 following subsections. 366 3.1.1. socket() 368 Applications use socket() to create a socket descriptor to represent 369 an SCTP endpoint. 371 The function prototype is 373 int socket(int domain, 374 int type, 375 int protocol); 377 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 378 type and IPPROTO_SCTP as the protocol. 380 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 381 socket. 383 The function returns a socket descriptor or -1 in case of an error. 385 Using the PF_INET domain indicates the creation of an endpoint which 386 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 387 can use both IPv6 and IPv4 addresses. 389 3.1.2. bind() 391 Applications use bind() to specify which local address and port the 392 SCTP endpoint should associate itself with. 394 An SCTP endpoint can be associated with multiple addresses. To do 395 this, sctp_bindx() is introduced in Section 9.1 to help applications 396 do the job of associating multiple addresses. But note that an 397 endpoint can only be associated with one local port. 399 These addresses associated with a socket are the eligible transport 400 addresses for the endpoint to send and receive data. The endpoint 401 will also present these addresses to its peers during the association 402 initialization process, see [RFC4960]. 404 After calling bind(), if the endpoint wishes to accept new 405 associations on the socket, it must call listen() (see 406 Section 3.1.3). 408 The function prototype of bind() is 410 int bind(int sd, 411 struct sockaddr *addr, 412 socklen_t addrlen); 414 and the arguments are 416 sd: The socket descriptor returned by socket(). 418 addr: The address structure (struct sockaddr_in for an IPv4 address 419 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 421 addrlen: The size of the address structure. 423 It returns 0 on success and -1 in case of an error. 425 If sd is an IPv4 socket, the address passed must be an IPv4 address. 426 If the sd is an IPv6 socket, the address passed can either be an IPv4 427 or an IPv6 address. 429 Applications cannot call bind() multiple times to associate multiple 430 addresses to an endpoint. After the first call to bind(), all 431 subsequent calls will return an error. 433 If the IP address part of addr is specified as a wildcard (INADDR_ANY 434 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 435 IPv6 address), the operating system will associate the endpoint with 436 an optimal address set of the available interfaces. If the IPv4 437 sin_port or IPv6 sin6_port is set to 0, the operating system will 438 choose an ephemeral port for the endpoint. 440 If a bind() is not called prior to a sendmsg() call that initiates a 441 new association, the system picks an ephemeral port and will choose 442 an address set equivalent to binding with a wildcard address. One of 443 those addresses will be the primary address for the association. 444 This automatically enables the multi-homing capability of SCTP. 446 The completion of this bind() process does not allow the SCTP 447 endpoint to accept inbound SCTP association requests. Until a 448 listen() system call, described below, is performed on the socket, 449 the SCTP endpoint will promptly reject an inbound SCTP INIT request 450 with an SCTP ABORT. 452 3.1.3. listen() 454 By default, a one-to-many style socket does not accept new 455 association requests. An application uses listen() to mark a socket 456 as being able to accept new associations. 458 The function prototype is 460 int listen(int sd, 461 int backlog); 463 and the arguments are 465 sd: The socket descriptor of the endpoint. 467 backlog: If backlog is non-zero, enable listening, else disable 468 listening. 470 It returns 0 on success and -1 in case of an error. 472 Note that one-to-many style socket consumers do not need to call 473 accept to retrieve new associations. Calling accept() on a one-to- 474 many style socket should return EOPNOTSUPP. Rather, new associations 475 are accepted automatically, and notifications of the new associations 476 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 477 these notifications are enabled). Clients will typically not call 478 listen(), so that they can be assured that only actively initiated 479 associations are possible on the socket. Server or peer-to-peer 480 sockets, on the other hand, will always accept new associations, so a 481 well-written application using server one-to-many style sockets must 482 be prepared to handle new associations from unwanted peers. 484 Also note that the SCTP_ASSOC_CHANGE event provides the association 485 identifier for a new association, so if applications wish to use the 486 association identifier as a parameter to other socket calls, they 487 should ensure that the SCTP_ASSOC_CHANGE event is enabled. 489 3.1.4. sendmsg() and recvmsg() 491 An application uses the sendmsg() and recvmsg() call to transmit data 492 to and receive data from its peer. 494 The function prototypes are 496 ssize_t sendmsg(int sd, 497 const struct msghdr *message, 498 int flags); 500 and 502 ssize_t recvmsg(int sd, 503 struct msghdr *message, 504 int flags); 506 using the arguments: 508 sd: The socket descriptor of the endpoint. 510 message: Pointer to the msghdr structure which contains a single 511 user message and possibly some ancillary data. See Section 5 for 512 complete description of the data structures. 514 flags: No new flags are defined for SCTP at this level. See 515 Section 5 for SCTP specific flags used in the msghdr structure. 517 sendmsg() returns the number of bytes accepted by the kernel or -1 in 518 case of an error. recvmsg() returns the number of bytes received or 519 -1 in case of an error. 521 As described in Section 5, different types of ancillary data can be 522 sent and received along with user data. When sending, the ancillary 523 data is used to specify the sent behavior, such as the SCTP stream 524 number to use. When receiving, the ancillary data is used to 525 describe the received data, such as the SCTP stream sequence number 526 of the message. 528 When sending user data with sendmsg(), the msg_name field in the 529 msghdr structure will be filled with one of the transport addresses 530 of the intended receiver. If there is no existing association 531 between the sender and the intended receiver, the sender's SCTP stack 532 will set up a new association and then send the user data (see 533 Section 7.5 for more on implicit association setup). If sendmsg() is 534 called with no data and there is no existing association, a new one 535 will be established. The SCTP_INIT type ancillary data can be used 536 to change some of the parameters used to set up a new association. 537 If sendmsg() is called with NULL data, and there is no existing 538 association but the SCTP_ABORT or SCTP_EOF flags are set as described 539 in Section 5.3.4, then -1 is returned and errno is set to EINVAL. 540 Sending a message using sendmsg() is atomic unless explicit EOR 541 marking is enabled on the socket specified by sd (see 542 Section 8.1.26). 544 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 545 be delivered if that notification has been enabled, and no more data 546 can be sent to that association. Any attempt to send more data will 547 cause sendmsg() to return with an ESHUTDOWN error. Note that the 548 socket is still open for reading at this point so it is possible to 549 retrieve notifications. 551 When receiving a user message with recvmsg(), the msg_name field in 552 the msghdr structure will be populated with the source transport 553 address of the user data. The caller of recvmsg() can use this 554 address information to determine to which association the received 555 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 556 disabled, applications must use the peer transport address provided 557 in the msg_name field by recvmsg() to perform correlation to an 558 association, since they will not have the association identifier. 560 If all data in a single message has been delivered, MSG_EOR will be 561 set in the msg_flags field of the msghdr structure (see Section 5.1). 563 If the application does not provide enough buffer space to completely 564 receive a data message, MSG_EOR will not be set in msg_flags. 565 Successive reads will consume more of the same message until the 566 entire message has been delivered, and MSG_EOR will be set. 568 If the SCTP stack is running low on buffers, it may partially deliver 569 a message. In this case, MSG_EOR will not be set, and more calls to 570 recvmsg() will be necessary to completely consume the message. Only 571 one message at a time can be partially delivered in any stream. The 572 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 573 what interlacing of messages occurs for both the one-to-one and the 574 one-to-many model sockets. Please consult Section 8.1.20 for further 575 details on message delivery options. 577 3.1.5. close() 579 Applications use close() to perform graceful shutdown (as described 580 in Section 10.1 of [RFC4960]) on all the associations currently 581 represented by a one-to-many style socket. 583 The function prototype is 585 int close(int sd); 587 and the argument is 589 sd: The socket descriptor of the associations to be closed. 591 0 is returned on success and -1 in case of an error. 593 To gracefully shutdown a specific association represented by the one- 594 to-many style socket, an application should use the sendmsg() call, 595 and include the SCTP_EOF flag. A user may optionally terminate an 596 association non-gracefully by sending with the SCTP_ABORT flag set 597 and possibly passing a user specified abort code in the data field. 598 Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data 599 (see Section 5.3.4) in the sendmsg() call. 601 If sd in the close() call is a branched-off socket representing only 602 one association, the shutdown is performed on that association only. 604 3.1.6. connect() 606 An application may use the connect() call in the one-to-many style to 607 initiate an association without sending data. 609 The function prototype is 611 int connect(int sd, 612 const struct sockaddr *nam, 613 socklen_t len); 615 and the arguments are 617 sd: The socket descriptor to have a new association added to. 619 nam: The address structure (struct sockaddr_in for an IPv4 address 620 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 622 len: The size of the address. 624 0 is returned on success and -1 in case of an error. 626 Multiple connect() calls can be made on the same socket to create 627 multiple associations. This is different from the semantics of 628 connect() on a UDP socket. 630 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 631 during the association set up phase. If an application wants to do 632 this, it cannot use the connect() call. Instead, it should use 633 sendto() or sendmsg() to initiate an association. If it uses 634 sendto() and it wants to change the initialization behavior, it needs 635 to use the SCTP_INITMSG socket option before calling sendto(). Or it 636 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 637 association without calling setsockopt(). Note that the implicit 638 setup is supported for the one-to-many style sockets. 640 SCTP does not support half close semantics. This means that unlike 641 T/TCP, MSG_EOF should not be set in the flags parameter when calling 642 sendto() or sendmsg() when the call is used to initiate a connection. 643 MSG_EOF is not an acceptable flag with an SCTP socket. 645 3.2. Non-blocking mode 647 Some SCTP application may wish to avoid being blocked when calling a 648 socket interface function. 650 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 651 one-to-many style socket, an application may set the non-blocking 652 option by a fcntl() (such as O_NONBLOCK). After setting the socket 653 to non-blocking mode, the sendmsg() function returns immediately. 654 The success or failure of sending the data message (with possible 655 SCTP_INITMSG ancillary data) will be signaled by the 656 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or SCTP_CANT_START_ASSOC. 657 If user data could not be sent (due to a SCTP_CANT_START_ASSOC), the 658 sender will also receive an SCTP_SEND_FAILED_EVENT event. Events can 659 be received by the user calling recvmsg(). A server (having called 660 listen()) is also notified of an association up event by the 661 reception of an SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling 662 of recvmsg() and possibly the reception of the first data message. 664 To shutdown the association gracefully, the user must call sendmsg() 665 with no data and with the SCTP_EOF flag set as described in 666 Section 5.3.4. The function returns immediately, and completion of 667 the graceful shutdown is indicated by an SCTP_ASSOC_CHANGE 668 notification of type SHUTDOWN_COMPLETE (see Section 6.1.1). Note 669 that this can also be done using the sctp_sendv() call described in 670 Section 9.12. 672 An application is recommended to use caution when using select() (or 673 poll()) for writing on a one-to-many style socket. The reason being 674 that the interpretation of select on write is implementation 675 specific. Generally a positive return on a select on write would 676 only indicate that one of the associations represented by the one-to- 677 many socket is writable. An application that writes after the 678 select() returns may still block since the association that was 679 writeable is not the destination association of the write call. 680 Likewise select() (or poll()) for reading from a one-to-many socket 681 will only return an indication that one of the associations 682 represented by the socket has data to be read. 684 An application that wishes to know that a particular association is 685 ready for reading or writing should either use the one-to-one style 686 or use the sctp_peeloff() (see Section 9.2) function to separate the 687 association of interest from the one-to-many socket. 689 Note some implementations may have an extended select call such as 690 epoll or kqueue that may escape this limitation and allow a select on 691 a specific association of a one-to-many socket, but this is an 692 implementation specific detail that a portable application cannot 693 depend on. 695 3.3. Special considerations 697 The fact that a one-to-many style socket can provide access to many 698 SCTP associations through a single socket descriptor, has important 699 implications for both application programmers and system programmers 700 implementing this API. A key issue is how buffer space inside the 701 sockets layer is managed. Because this implementation detail 702 directly affects how application programmers must write their code to 703 ensure correct operation and portability, this section provides some 704 guidance to both implementers and application programmers. 706 An important feature that SCTP shares with TCP is flow control. 707 Specifically, a sender may not send data faster than the receiver can 708 consume it. 710 For TCP, flow control is typically provided for in the sockets API as 711 follows. If the reader stops reading, the sender queues messages in 712 the socket layer until the send socket buffer is completely filled. 713 This results in a "stalled connection". Further attempts to write to 714 the socket will block or return the error EAGAIN or EWOULDBLOCK for a 715 non-blocking socket. At some point, either the connection is closed, 716 or the receiver begins to read again freeing space in the output 717 queue. 719 For one-to-one style SCTP sockets (this includes sockets descriptors 720 that were separated from a one-to-many style socket with 721 sctp_peeloff()) the behavior is identical. For one-to-many style 722 SCTP sockets there are multiple associations for a single socket, 723 which makes the situation more complicated. If the implementation 724 uses a single buffer space allocation shared by all associations, a 725 single stalled association can prevent the further sending of data on 726 all associations active on a particular one-to-many style socket. 728 For a blocking socket, it should be clear that a single stalled 729 association can block the entire socket. For this reason, 730 application programmers may want to use non-blocking one-to-many 731 style sockets. The application should at least be able to send 732 messages to the non-stalled associations. 734 But a non-blocking socket is not sufficient if the API implementer 735 has chosen a single shared buffer allocation for the socket. A 736 single stalled association would eventually cause the shared 737 allocation to fill, and it would become impossible to send even to 738 non-stalled associations. 740 The API implementer can solve this problem by providing each 741 association with its own allocation of outbound buffer space. Each 742 association should conceptually have as much buffer space as it would 743 have if it had its own socket. As a bonus, this simplifies the 744 implementation of sctp_peeloff(). 746 To ensure that a given stalled association will not prevent other 747 non-stalled associations from being writable, application programmers 748 should either: 750 o demand that the underlying implementation dedicates independent 751 buffer space reservation to each association (as suggested above), 752 or 754 o verify that their application layer protocol does not permit large 755 amounts of unread data at the receiver (this is true of some 756 request-response protocols, for example), or 758 o use one-to-one style sockets for association which may potentially 759 stall (either from the beginning, or by using sctp_peeloff before 760 sending large amounts of data that may cause a stalled condition). 762 4. One-to-One Style Interface 764 The goal of this style is to follow as closely as possible the 765 current practice of using the sockets interface for a connection 766 oriented protocol, such as TCP. This style enables existing 767 applications using connection oriented protocols to be ported to SCTP 768 with very little effort. 770 One-to-one style sockets can be connected (explicitly or implicitly) 771 at most once, similar to TCP sockets. 773 Note that some new SCTP features and some new SCTP socket options can 774 only be utilized through the use of sendmsg() and recvmsg() calls, 775 see Section 4.1.8. 777 4.1. Basic Operation 779 A typical server in one-to-one style uses the following system call 780 sequence to prepare an SCTP endpoint for servicing requests: 782 o socket() 784 o bind() 786 o listen() 788 o accept() 790 The accept() call blocks until a new association is set up. It 791 returns with a new socket descriptor. The server then uses the new 792 socket descriptor to communicate with the client, using recv() and 793 send() calls to get requests and send back responses. 795 Then it calls 797 o close() 799 to terminate the association. 801 A typical client uses the following system call sequence to setup an 802 association with a server to request services: 804 o socket() 806 o connect() 808 After returning from connect(), the client uses send()/sendmsg() and 809 recv()/recvmsg() calls to send out requests and receive responses 810 from the server. 812 The client calls 814 o close() 816 to terminate this association when done. 818 4.1.1. socket() 820 Applications call socket() to create a socket descriptor to represent 821 an SCTP endpoint. 823 The function prototype is 825 int socket(int domain, 826 int type, 827 int protocol); 829 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 830 type and IPPROTO_SCTP as the protocol. 832 Here, SOCK_STREAM indicates the creation of a one-to-one style 833 socket. 835 Using the PF_INET domain indicates the creation of an endpoint which 836 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 837 can use both IPv6 and IPv4 addresses. 839 4.1.2. bind() 841 Applications use bind() to specify which local address and port the 842 SCTP endpoint should associate itself with. 844 An SCTP endpoint can be associated with multiple addresses. To do 845 this, sctp_bindx() is introduced in Section 9.1 to help applications 846 do the job of associating multiple addresses. But note that an 847 endpoint can only be associated with one local port. 849 These addresses associated with a socket are the eligible transport 850 addresses for the endpoint to send and receive data. The endpoint 851 will also present these addresses to its peers during the association 852 initialization process, see [RFC4960]. 854 The function prototype of bind() is 856 int bind(int sd, 857 struct sockaddr *addr, 858 socklen_t addrlen); 860 and the arguments are 862 sd: The socket descriptor returned by socket(). 864 addr: The address structure (struct sockaddr_in for an IPv4 address 865 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 867 addrlen: The size of the address structure. 869 If sd is an IPv4 socket, the address passed must be an IPv4 address. 870 If sd is an IPv6 socket, the address passed can either be an IPv4 or 871 an IPv6 address. 873 Applications cannot call bind() multiple times to associate multiple 874 addresses to the endpoint. After the first call to bind(), all 875 subsequent calls will return an error. 877 If the IP address part of addr is specified as a wildcard (INADDR_ANY 878 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 879 IPv6 address), the operating system will associate the endpoint with 880 an optimal address set of the available interfaces. If the IPv4 881 sin_port or IPv6 sin6_port is set to 0, the operating system will 882 choose an ephemeral port for the endpoint. 884 If a bind() is not called prior to the connect() call, the system 885 picks an ephemeral port and will choose an address set equivalent to 886 binding with a wildcard address. One of these addresses will be the 887 primary address for the association. This automatically enables the 888 multi-homing capability of SCTP. 890 The completion of this bind() process does not allow the SCTP 891 endpoint to accept inbound SCTP association requests. Until a 892 listen() system call, described below, is performed on the socket, 893 the SCTP endpoint will promptly reject an inbound SCTP INIT request 894 with an SCTP ABORT. 896 4.1.3. listen() 898 Applications use listen() to allow the SCTP endpoint to accept 899 inbound associations. 901 The function prototype is 903 int listen(int sd, 904 int backlog); 906 and the arguments are 908 sd: the socket descriptor of the SCTP endpoint. 910 backlog: this specifies the max number of outstanding associations 911 allowed in the socket's accept queue. These are the associations 912 that have finished the four-way initiation handshake (see Section 913 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 914 of '0' indicates that the caller no longer wishes to receive new 915 associations. 917 It returns 0 on success an -1 in case of an error. 919 4.1.4. accept() 921 Applications use the accept() call to remove an established SCTP 922 association from the accept queue of the endpoint. A new socket 923 descriptor will be returned from accept() to represent the newly 924 formed association. 926 The function prototype is 928 int accept(int sd, 929 struct sockaddr *addr, 930 socklen_t *addrlen); 932 and the arguments are 934 sd: The listening socket descriptor. 936 addr: On return, addr (struct sockaddr_in for an IPv4 address or 937 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 938 contain the primary address of the peer endpoint. 940 addrlen: On return, addrlen will contain the size of addr. 942 The function returns the socket descriptor for the newly formed 943 association on success and -1 in case of an error. 945 4.1.5. connect() 947 Applications use connect() to initiate an association to a peer. 949 The function prototype is 951 int connect(int sd, 952 const struct sockaddr *addr, 953 socklen_t addrlen); 955 and the arguments are 957 sd: The socket descriptor of the endpoint. 959 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 960 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 962 addrlen: The size of the address. 964 It returns 0 on success and -1 on error. 966 This operation corresponds to the ASSOCIATE primitive described in 967 Section 10.1 of [RFC4960]. 969 The number of outbound streams the new association has is stack 970 dependent. Applications can use the SCTP_INITMSG option described in 971 Section 8.1.3 before connecting to change the number of outbound 972 streams. 974 If a bind() is not called prior to the connect() call, the system 975 picks an ephemeral port and will choose an address set equivalent to 976 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 977 respectively. One of the addresses will be the primary address for 978 the association. This automatically enables the multi-homing 979 capability of SCTP. 981 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 982 during the association set up phase. If an application wants to do 983 this, it cannot use the connect() call. Instead, it should use 984 sendto() or sendmsg() to initiate an association. If it uses 985 sendto() and it wants to change the initialization behavior, it needs 986 to use the SCTP_INITMSG socket option before calling sendto(). Or it 987 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 988 association without calling setsockopt(). Note that the implicit 989 setup is supported for the one-to-one style sockets. 991 SCTP does not support half close semantics. This means that unlike 992 T/TCP, MSG_EOF should not be set in the flags parameter when calling 993 sendto() or sendmsg() when the call is used to initiate a connection. 994 MSG_EOF is not an acceptable flag with an SCTP socket. 996 4.1.6. close() 998 Applications use close() to gracefully close down an association. 1000 The function prototype is 1002 int close(int sd); 1004 and the argument is 1006 sd: The socket descriptor of the association to be closed. 1008 It returns 0 on success and -1 in case of an error. 1010 After an application calls close() on a socket descriptor, no further 1011 socket operations will succeed on that descriptor. 1013 4.1.7. shutdown() 1015 SCTP differs from TCP in that it does not have half closed semantics. 1016 Hence the shutdown() call for SCTP is an approximation of the TCP 1017 shutdown() call, and solves some different problems. Full TCP- 1018 compatibility is not provided, so developers porting TCP applications 1019 to SCTP may need to recode sections that use shutdown(). (Note that 1020 it is possible to achieve the same results as half close in SCTP 1021 using SCTP streams.) 1023 The function prototype is 1025 int shutdown(int sd, 1026 int how); 1028 and the arguments are 1030 sd: The socket descriptor of the association to be closed. 1032 how: Specifies the type of shutdown. The values are as follows: 1034 SHUT_RD: Disables further receive operations. No SCTP protocol 1035 action is taken. 1037 SHUT_WR: Disables further send operations, and initiates the SCTP 1038 shutdown sequence. 1040 SHUT_RDWR: Disables further send and receive operations and 1041 initiates the SCTP shutdown sequence. 1043 It returns 0 on success and -1 in case of an error. 1045 The major difference between SCTP and TCP shutdown() is that SCTP 1046 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 1047 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 1048 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 1049 the SCTP association while still leaving the socket descriptor open. 1050 This allows the caller to receive back any data which SCTP is unable 1051 to deliver (see Section 6.1.4 for more information) and receive event 1052 notifications. 1054 To perform the ABORT operation described in [RFC4960] Section 10.1, 1055 an application can use the socket option SO_LINGER. It is described 1056 in Section 8.1.4. 1058 4.1.8. sendmsg() and recvmsg() 1060 With a one-to-one style socket, the application can also use 1061 sendmsg() and recvmsg() to transmit data to and receive data from its 1062 peer. The semantics is similar to those used in the one-to-many 1063 style (see Section 3.1.4), with the following differences: 1065 1. When sending, the msg_name field in the msghdr is not used to 1066 specify the intended receiver, rather it is used to indicate a 1067 preferred peer address if the sender wishes to discourage the 1068 stack from sending the message to the primary address of the 1069 receiver. If the socket is connected and the transport address 1070 given is not part of the current association, the data will not 1071 be sent and an SCTP_SEND_FAILED_EVENT event will be delivered to 1072 the application if send failure events are enabled. 1074 2. Using sendmsg() on a non-connected one-to-one style socket for 1075 implicit connection setup may or may not work depending on the 1076 SCTP implementation. 1078 4.1.9. getpeername() 1080 Applications use getpeername() to retrieve the primary socket address 1081 of the peer. This call is for TCP compatibility, and is not multi- 1082 homed. It may not work with one-to-many style sockets depending on 1083 the implementation. See Section 9.3 for a multi-homed style version 1084 of the call. 1086 The function prototype is 1088 int getpeername(int sd, 1089 struct sockaddr *address, 1090 socklen_t *len); 1092 and the arguments are: 1094 sd: The socket descriptor to be queried. 1096 address: On return, the peer primary address is stored in this 1097 buffer. If the socket is an IPv4 socket, the address will be 1098 IPv4. If the socket is an IPv6 socket, the address will be either 1099 an IPv6 or IPv4 address. 1101 len: The caller should set the length of address here. On return, 1102 this is set to the length of the returned address. 1104 It returns 0 on success and -1 in case of an error. 1106 If the actual length of the address is greater than the length of the 1107 supplied sockaddr structure, the stored address will be truncated. 1109 5. Data Structures 1111 This section discusses important data structures which are specific 1112 to SCTP and are used with sendmsg() and recvmsg() calls to control 1113 SCTP endpoint operations and to access ancillary information and 1114 notifications. 1116 5.1. The msghdr and cmsghdr Structures 1118 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1119 well as the ancillary data carried in the structure, is the key for 1120 the application to set and get various control information from the 1121 SCTP endpoint. 1123 The msghdr and the related cmsghdr structures are defined and 1124 discussed in detail in [RFC3542]. They are defined as: 1126 struct msghdr { 1127 void *msg_name; /* ptr to socket address structure */ 1128 socklen_t msg_namelen; /* size of socket address structure */ 1129 struct iovec *msg_iov; /* scatter/gather array */ 1130 int msg_iovlen; /* # elements in msg_iov */ 1131 void *msg_control; /* ancillary data */ 1132 socklen_t msg_controllen; /* ancillary data buffer length */ 1133 int msg_flags; /* flags on received message */ 1134 }; 1136 struct cmsghdr { 1137 socklen_t cmsg_len; /* #bytes, including this header */ 1138 int cmsg_level; /* originating protocol */ 1139 int cmsg_type; /* protocol-specific type */ 1140 /* followed by unsigned char cmsg_data[]; */ 1141 }; 1143 In the msghdr structure, the usage of msg_name has been discussed in 1144 previous sections (see Section 3.1.4 and Section 4.1.8). 1146 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1147 field) are treated by SCTP as a single user message for both 1148 sendmsg() and recvmsg(). 1150 SCTP stack uses the ancillary data (msg_control field) to communicate 1151 the attributes, such as SCTP_RCVINFO, of the message stored in 1152 msg_iov to the socket end point. The different ancillary data types 1153 are described in Section 5.3. 1155 The msg_flags are not used when sending a message with sendmsg(). 1157 If a notification has arrived, recvmsg() will return the notification 1158 in msg_iov field and set MSG_NOTIFICATION flag in msg_flags. If the 1159 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1160 Section 6 for more information about notifications. 1162 If all portions of a data frame or notification have been read, 1163 recvmsg() will return with MSG_EOR set in msg_flags. 1165 5.2. Ancillary Data Considerations and Semantics 1167 Programming with ancillary socket data (msg_control) contains some 1168 subtleties and pitfalls, which are discussed below. 1170 5.2.1. Multiple Items and Ordering 1172 Multiple ancillary data items may be included in any call to 1173 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP, 1174 such as IP level items, or both. 1176 The ordering of ancillary data items (either by SCTP or another 1177 protocol) is not significant and is implementation-dependent, so 1178 applications must not depend on any ordering. 1180 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 1181 correspond to the data in the msghdr's msg_iov member. There can be 1182 only one single such type ancillary data for each sendmsg() or 1183 recvmsg() call. 1185 5.2.2. Accessing and Manipulating Ancillary Data 1187 Applications can infer the presence of data or ancillary data by 1188 examining the msg_iovlen and msg_controllen msghdr members, 1189 respectively. 1191 Implementations may have different padding requirements for ancillary 1192 data, so portable applications should make use of the macros 1193 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1194 [RFC3542] and the SCTP implementation's documentation for more 1195 information. The following is an example, from [RFC3542], 1196 demonstrating the use of these macros to access ancillary data: 1198 struct msghdr msg; 1199 struct cmsghdr *cmsgptr; 1201 /* fill in msg */ 1203 /* call recvmsg() */ 1205 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1206 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1207 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1208 u_char *ptr; 1210 ptr = CMSG_DATA(cmsgptr); 1211 /* process data pointed to by ptr */ 1212 } 1213 } 1215 5.2.3. Control Message Buffer Sizing 1217 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1218 ancillary data will often be fundamental to the correct and sane 1219 operation of the sockets application. This is particularly true of 1220 the one-to-many semantics, but also of the one-to-one semantics. For 1221 example, if an application needs to send and receive data on 1222 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1223 ancillary data is indispensable. 1225 Given that some ancillary data is critical, and that multiple 1226 ancillary data items may appear in any order, applications should be 1227 carefully written to always provide a large enough buffer to contain 1228 all possible ancillary data that can be presented by recvmsg(). If 1229 the buffer is too small, and crucial data is truncated, it may pose a 1230 fatal error condition. 1232 Thus, it is essential that applications be able to deterministically 1233 calculate the maximum required buffer size to pass to recvmsg(). One 1234 constraint imposed on this specification that makes this possible is 1235 that all ancillary data definitions are of a fixed length. One way 1236 to calculate the maximum required buffer size might be to take the 1237 sum the sizes of all enabled ancillary data item structures, as 1238 calculated by CMSG_SPACE. For example, if we enabled 1239 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 1240 and allocate the buffer size as follows: 1242 size_t total; 1243 void *buf; 1245 total = CMSG_SPACE(sizeof(struct sctp_sndrcvinfo)) + 1246 CMSG_SPACE(sizeof(struct in6_pktinfo)); 1248 buf = malloc(total); 1250 We could then use this buffer (buf) for msg_control on each call to 1251 recvmsg() and be assured that we would not lose any ancillary data to 1252 truncation. 1254 5.3. SCTP msg_control Structures 1256 A key element of all SCTP specific socket extensions is the use of 1257 ancillary data to specify and access SCTP specific data via the 1258 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1259 Fine-grained control over initialization and sending parameters are 1260 handled with ancillary data. 1262 Each ancillary data item is proceeded by a struct cmsghdr (see 1263 Section 5.1), which defines the function and purpose of the data 1264 contained in the cmsg_data[] member. 1266 By default on either style socket, SCTP will pass no ancillary data; 1267 Specific ancillary data items can be enabled with socket options 1268 defined for SCTP; see Section 6.2. 1270 Note that all ancillary types are fixed length; see Section 5.2 for 1271 further discussion on this. These data structures use struct 1272 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1273 address format. 1275 Other protocols may also provide ancillary data to the socket layer 1276 consumer. These ancillary data items from other protocols may 1277 intermingle with SCTP data. For example, the IPv6 socket API 1278 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1279 data items. If a socket API consumer enables delivery of both SCTP 1280 and IPv6 ancillary data, they both may appear in the same msg_control 1281 buffer in any order. An application may thus need to handle other 1282 types of ancillary data besides those passed by SCTP. 1284 The sockets application must provide a buffer large enough to 1285 accommodate all ancillary data provided via recvmsg(). If the buffer 1286 is not large enough, the ancillary data will be truncated and the 1287 msghdr's msg_flags will include MSG_CTRUNC. 1289 5.3.1. SCTP Initiation Structure (SCTP_INIT) 1291 This cmsghdr structure provides information for initializing new SCTP 1292 associations with sendmsg(). The SCTP_INITMSG socket option uses 1293 this same data structure. This structure is not used for recvmsg(). 1295 +--------------+-----------+---------------------+ 1296 | cmsg_level | cmsg_type | cmsg_data[] | 1297 +--------------+-----------+---------------------+ 1298 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1299 +--------------+-----------+---------------------+ 1301 The sctp_initmsg structure is defined below: 1303 struct sctp_initmsg { 1304 uint16_t sinit_num_ostreams; 1305 uint16_t sinit_max_instreams; 1306 uint16_t sinit_max_attempts; 1307 uint16_t sinit_max_init_timeo; 1308 }; 1310 sinit_num_ostreams: This is an integer number representing the 1311 number of streams that the application wishes to be able to send 1312 to. This number is confirmed in the SCTP_COMM_UP notification and 1313 must be verified since it is a negotiated number with the remote 1314 endpoint. The default value of 0 indicates to use the endpoint 1315 default value. 1317 sinit_max_instreams: This value represents the maximum number of 1318 inbound streams the application is prepared to support. This 1319 value is bounded by the actual implementation. In other words the 1320 user may be able to support more streams than the Operating 1321 System. In such a case, the Operating System limit overrides the 1322 value requested by the user. The default value of 0 indicates to 1323 use the endpoints default value. 1325 sinit_max_attempts: This integer specifies how many attempts the 1326 SCTP endpoint should make at resending the INIT. This value 1327 overrides the system SCTP 'Max.Init.Retransmits' value. The 1328 default value of 0 indicates to use the endpoints default value. 1329 This is normally set to the system's default 'Max.Init.Retransmit' 1330 value. 1332 sinit_max_init_timeo: This value represents the largest Time-Out or 1333 RTO value (in milliseconds) to use in attempting an INIT. 1334 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1335 upon timeout. For the INIT message this value may override 1336 'RTO.Max'. This value must not influence 'RTO.Max' during data 1337 transmission and is only used to bound the initial setup time. A 1338 default value of 0 indicates to use the endpoints default value. 1339 This is normally set to the system's 'RTO.Max' value (60 seconds). 1341 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - DEPRECATED 1343 This cmsghdr structure specifies SCTP options for sendmsg() and 1344 describes SCTP header information about a received message through 1345 recvmsg(). This structure mixes the send and receive path. 1346 SCTP_SNDINFO described in Section 5.3.4 and SCTP_RCVINFO described in 1347 Section 5.3.5 split this information. These structures should be 1348 used, when possible, since SCTP_SNDRCV is deprecated. 1350 +--------------+-------------+------------------------+ 1351 | cmsg_level | cmsg_type | cmsg_data[] | 1352 +--------------+-------------+------------------------+ 1353 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1354 +--------------+-------------+------------------------+ 1356 The sctp_sndrcvinfo structure is defined below: 1358 struct sctp_sndrcvinfo { 1359 uint16_t sinfo_stream; 1360 uint16_t sinfo_ssn; 1361 uint16_t sinfo_flags; 1362 uint32_t sinfo_ppid; 1363 uint32_t sinfo_context; 1364 uint32_t sinfo_timetolive; 1365 uint32_t sinfo_tsn; 1366 uint32_t sinfo_cumtsn; 1367 sctp_assoc_t sinfo_assoc_id; 1368 }; 1370 sinfo_stream: For recvmsg() the SCTP stack places the message's 1371 stream number in this value. For sendmsg() this value holds the 1372 stream number that the application wishes to send this message to. 1373 If a sender specifies an invalid stream number an error indication 1374 is returned and the call fails. 1376 sinfo_ssn: For recvmsg() this value contains the stream sequence 1377 number that the remote endpoint placed in the DATA chunk. For 1378 fragmented messages this is the same number for all deliveries of 1379 the message (if more than one recvmsg() is needed to read the 1380 message). The sendmsg() call will ignore this parameter. 1382 sinfo_flags: This field may contain any of the following flags and 1383 is composed of a bitwise OR of these values. 1385 recvmsg() flags: 1387 SCTP_UNORDERED: This flag is present when the message was sent 1388 un-ordered. 1390 sendmsg() flags: 1392 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1393 the message. If this flag is clear the datagram is 1394 considered an ordered send. 1396 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1397 the SCTP stack to override the primary destination address 1398 with the address found with the sendto/sendmsg call. 1400 SCTP_ABORT: Setting this flag causes the specified association 1401 to abort by sending an ABORT message to the peer. The ABORT 1402 chunk will contain an error cause 'User Initiated Abort' 1403 with cause code 12. The cause specific information of this 1404 error cause is provided in msg_iov. 1406 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1407 procedure on the specified association. Graceful shutdown 1408 assures that all data queued by both endpoints is 1409 successfully transmitted before closing the association. 1411 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1412 model socket to send the message to all associations that 1413 are currently established on this socket. For the one-to- 1414 one socket, this flag has no effect. 1416 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1417 passed to the remote end in each user message. In recvmsg() this 1418 value is the same information that was passed by the upper layer 1419 in the peer application. Please note that the SCTP stack performs 1420 no byte order modification of this field. For example, if the 1421 DATA chunk has to contain a given value in network byte order, the 1422 SCTP user has to perform the htonl() computation. 1424 sinfo_context: This value is an opaque 32 bit context datum that is 1425 used in the sendmsg() function. This value is passed back to the 1426 upper layer if an error occurs on the send of a message and is 1427 retrieved with each undelivered message. 1429 sinfo_timetolive: For the sending side, this field contains the 1430 message time to live in milliseconds. The sending side will 1431 expire the message within the specified time period if the message 1432 as not been sent to the peer within this time period. This value 1433 will override any default value set using any socket option. Also 1434 note that the value of 0 is special in that it indicates no 1435 timeout should occur on this message. 1437 sinfo_tsn: For the receiving side, this field holds a TSN that was 1438 assigned to one of the SCTP Data Chunks. For the sending side it 1439 is ignored. 1441 sinfo_cumtsn: This field will hold the current cumulative TSN as 1442 known by the underlying SCTP layer. Note this field is ignored 1443 when sending. 1445 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1446 the identifier for the association announced in the SCTP_COMM_UP 1447 notification. All notifications for a given association have the 1448 same identifier. Ignored for one-to-one style sockets. 1450 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1452 5.3.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) - 1453 DEPRECATED 1455 This cmsghdr structure specifies SCTP options for SCTP header 1456 information about a received message via recvmsg(). Note that this 1457 structure is an extended version of SCTP_SNDRCV (see Section 5.3.2) 1458 and will only be received if the user has set the socket option 1459 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1460 needed to receive ancillary data. See Section 8.1.22 on this socket 1461 option. Note that next message data is not valid unless the current 1462 message is completely read, i.e. the MSG_EOR is set, in other words 1463 if the application has more data to read from the current message 1464 then no next message information will be available. 1466 SCTP_NXTINFO described in Section 5.3.6 should be used when possible, 1467 since SCTP_EXTRCV is considered deprecated. 1469 +--------------+-------------+------------------------+ 1470 | cmsg_level | cmsg_type | cmsg_data[] | 1471 +--------------+-------------+------------------------+ 1472 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1473 +--------------+-------------+------------------------+ 1475 The sctp_extrcvinfo structure is defined below: 1477 struct sctp_extrcvinfo { 1478 uint16_t sinfo_stream; 1479 uint16_t sinfo_ssn; 1480 uint16_t sinfo_flags; 1481 uint32_t sinfo_ppid; 1482 uint32_t sinfo_context; 1483 uint32_t sinfo_pr_value; 1484 uint32_t sinfo_tsn; 1485 uint32_t sinfo_cumtsn; 1486 uint16_t serinfo_next_flags; 1487 uint16_t serinfo_next_stream; 1488 uint32_t serinfo_next_aid; 1489 uint32_t serinfo_next_length; 1490 uint32_t serinfo_next_ppid; 1491 sctp_assoc_t sinfo_assoc_id; 1492 }; 1494 sinfo_*: Please see Section 5.3.2 for the details for these fields. 1496 serinfo_next_flags: This bitmask will hold one or more of the 1497 following values: 1499 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1500 message information is available i.e.: next_stream, 1501 next_asocid, next_length and next_ppid fields all have valid 1502 values. If this bit is set to 0, then these fields are not 1503 valid and should be ignored. 1505 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1506 next message is completely in the receive buffer. The 1507 next_length field thus contains the entire message size. If 1508 this flag is set to 0, then the next_length field only contains 1509 part of the message size since the message is still being 1510 received (it is being partially delivered). 1512 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1513 the next message to be received was sent by the peer as 1514 unordered. If this bit is not set (i.e. the bit is 0) the next 1515 message to be read is an ordered message in the stream 1516 specified. 1518 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1519 the next message to be received is not a message from the peer, 1520 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1522 serinfo_next_stream: This value, when valid (see 1523 serinfo_next_flags), contains the next stream number that will be 1524 received on a subsequent call to one of the receive message 1525 functions. 1527 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1528 contains the next association identifier that will be received on 1529 a subsequent call to one of the receive message functions. 1531 serinfo_next_length: This value, when valid (see 1532 serinfo_next_flags), contains the length of the next message that 1533 will be received on a subsequent call to one of the receive 1534 message functions. Note that this length may be a partial length 1535 depending on the settings of next_flags. 1537 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1538 contains the ppid of the next message that will be received on a 1539 subsequent call to one of the receive message functions. 1541 5.3.4. SCTP Send Information Structure (SCTP_SNDINFO) 1543 This cmsghdr structure specifies SCTP options for sendmsg(). 1545 +--------------+--------------+---------------------+ 1546 | cmsg_level | cmsg_type | cmsg_data[] | 1547 +--------------+--------------+---------------------+ 1548 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1549 +--------------+--------------+---------------------+ 1551 The sctp_sndinfo structure is defined below: 1553 struct sctp_sndinfo { 1554 uint16_t snd_sid; 1555 uint16_t snd_flags; 1556 uint32_t snd_ppid; 1557 uint32_t snd_context; 1558 sctp_assoc_t snd_assoc_id; 1559 }; 1561 snd_sid: This value holds the stream number that the application 1562 wishes to send this message to. If a sender specifies an invalid 1563 stream number an error indication is returned and the call fails. 1565 snd_flags: This field may contain any of the following flags and is 1566 composed of a bitwise OR of these values. 1568 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1569 message. If this flag is clear the datagram is considered an 1570 ordered send. 1572 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1573 SCTP stack to override the primary destination address with the 1574 address found with the sendto()/sendmsg call. 1576 SCTP_ABORT: Setting this flag causes the specified association to 1577 abort by sending an ABORT message to the peer. The ABORT chunk 1578 will contain an error cause 'User Initiated Abort' with cause 1579 code 12. The cause specific information of this error cause is 1580 provided in msg_iov. 1582 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1583 procedures on the specified association. Graceful shutdown 1584 assures that all data queued by both endpoints is successfully 1585 transmitted before closing the association. 1587 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1588 socket to send the message to all associations that are 1589 currently established on this socket. For the one-to-one 1590 socket, this flag has no effect. 1592 snd_ppid: This value in sendmsg() is an unsigned integer that is 1593 passed to the remote end in each user message. Please note that 1594 the SCTP stack performs no byte order modification of this field. 1595 For example, if the DATA chunk has to contain a given value in 1596 network byte order, the SCTP user has to perform the htonl() 1597 computation. 1599 snd_context: This value is an opaque 32 bit context datum that is 1600 used in the sendmsg() function. This value is passed back to the 1601 upper layer if an error occurs on the send of a message and is 1602 retrieved with each undelivered message. 1604 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1605 the identifier for the association announced in the SCTP_COMM_UP 1606 notification. All notifications for a given association have the 1607 same identifier. Ignored for one-to-one style sockets. 1609 An sctp_sndinfo item always corresponds to the data in msg_iov. 1611 5.3.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1613 This cmsghdr structure describes SCTP receive information about a 1614 received message through recvmsg(). 1616 To enable the delivery of this information an application must use 1617 the SCTP_RECVRCVINFO socket option (see Section 8.1.29). 1619 +--------------+--------------+---------------------+ 1620 | cmsg_level | cmsg_type | cmsg_data[] | 1621 +--------------+--------------+---------------------+ 1622 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1623 +--------------+--------------+---------------------+ 1625 The sctp_rcvinfo structure is defined below: 1627 struct sctp_rcvinfo { 1628 uint16_t rcv_sid; 1629 uint16_t rcv_ssn; 1630 uint16_t rcv_flags; 1631 uint32_t rcv_ppid; 1632 uint32_t rcv_tsn; 1633 uint32_t rcv_cumtsn; 1634 uint32_t rcv_context; 1635 sctp_assoc_t rcv_assoc_id; 1636 }; 1637 rcv_sid: The SCTP stack places the message's stream number in this 1638 value. 1640 rcv_ssn: This value contains the stream sequence number that the 1641 remote endpoint placed in the DATA chunk. For fragmented messages 1642 this is the same number for all deliveries of the message (if more 1643 than one recvmsg() is needed to read the message). 1645 rcv_flags: This field may contain any of the following flags and is 1646 composed of a bitwise OR of these values. 1648 SCTP_UNORDERED: This flag is present when the message was sent 1649 un-ordered. 1651 rcv_ppid: This value is the same information that was passed by the 1652 upper layer in the peer application. Please note that the SCTP 1653 stack performs no byte order modification of this field. For 1654 example, if the DATA chunk has to contain a given value in network 1655 byte order, the SCTP user has to perform the ntohl() computation. 1657 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1658 Data Chunks. 1660 rcv_cumtsn: This field will hold the current cumulative TSN as known 1661 by the underlying SCTP layer. 1663 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1664 the identifier for the association announced in the SCTP_COMM_UP 1665 notification. All notifications for a given association have the 1666 same identifier. Ignored for one-to-one style sockets. 1668 rcv_context: This value is an opaque 32 bit context datum that was 1669 set by the user with the SCTP_CONTEXT socket option. This value 1670 is passed back to the upper layer if an error occurs on the send 1671 of a message and is retrieved with each undelivered message. 1673 An sctp_rcvinfo item always corresponds to the data in msg_iov. 1675 5.3.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1677 This cmsghdr structure describes SCTP receive information of the next 1678 message which will be delivered through recvmsg() if this information 1679 is already available when delivering the current message. 1681 To enable the delivery of this information an application must use 1682 the SCTP_RECVNXTINFO socket option (see Section 8.1.30). 1684 +--------------+--------------+---------------------+ 1685 | cmsg_level | cmsg_type | cmsg_data[] | 1686 +--------------+--------------+---------------------+ 1687 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_nxtinfo | 1688 +--------------+--------------+---------------------+ 1690 The sctp_nxtinfo structure is defined below: 1692 struct sctp_nxtinfo { 1693 uint16_t nxt_sid; 1694 uint16_t nxt_flags; 1695 uint32_t nxt_ppid; 1696 uint32_t nxt_length; 1697 sctp_assoc_t nxt_assoc_id; 1698 }; 1700 nxt_sid: The SCTP stack places the next message's stream number in 1701 this value. 1703 nxt_flags: This field may contain any of the following flags and is 1704 composed of a bitwise OR of these values. 1706 SCTP_UNORDERED: This flag is present when the next message was 1707 sent un-ordered. 1709 SCTP_COMPLETE: This flag indicates that the entire message has 1710 been received and is in the socket buffer. Note that this has 1711 special implications with respect to the nxt_length field, see 1712 nxt_length description below. 1714 SCTP_NOTIFICATION: This flag is present when the next message is 1715 not a user message but instead is a notification. 1717 nxt_ppid: This value is the same information that was passed by the 1718 upper layer in the peer application for the next message. Please 1719 note that the SCTP stack performs no byte order modification of 1720 this field. For example, if the DATA chunk has to contain a given 1721 value in network byte order, the SCTP user has to perform the 1722 ntohl() computation. 1724 nxt_length: This value is the length of the message currently within 1725 the socket buffer. This might NOT be the entire length of the 1726 message since a partial delivery may be in progress. Only if the 1727 flag SCTP_COMPLETE is set in the nxt_flags field does this field 1728 represent the entire next message size. 1730 nxt_assoc_id: The association handle field of the next message, 1731 nxt_assoc_id, holds the identifier for the association announced 1732 in the SCTP_COMM_UP notification. All notifications for a given 1733 association have the same identifier. Ignored for one-to-one 1734 style sockets. 1736 5.3.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1738 This cmsghdr structure specifies SCTP options for sendmsg(). 1740 +--------------+-------------+--------------------+ 1741 | cmsg_level | cmsg_type | cmsg_data[] | 1742 +--------------+-------------+--------------------+ 1743 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1744 +--------------+-------------+--------------------+ 1746 The sctp_prinfo structure is defined below: 1748 struct sctp_prinfo { 1749 uint16_t pr_policy; 1750 uint32_t pr_value; 1751 }; 1753 pr_policy: This specifies which PR-SCTP policy is used. Using 1754 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1755 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1756 defined in [RFC3758] is used. In this case, the lifetime is 1757 provided in pr_value. 1759 pr_value: The meaning of this field depends on the PR-SCTP policy 1760 specified by the pr_policy field. It is ignored when 1761 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1762 lifetime in milliseconds is specified. 1764 An sctp_prinfo item always corresponds to the data in msg_iov. 1766 5.3.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1768 This cmsghdr structure specifies SCTP options for sendmsg(). 1770 +--------------+---------------+----------------------+ 1771 | cmsg_level | cmsg_type | cmsg_data[] | 1772 +--------------+---------------+----------------------+ 1773 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1774 +--------------+---------------+----------------------+ 1776 The sctp_authinfo structure is defined below: 1778 struct sctp_authinfo { 1779 uint16_t auth_keyid; 1780 }; 1782 auth_keyid: This specifies the shared key identifier used for 1783 sending the user message. 1785 An sctp_authinfo item always corresponds to the data in msg_iov. 1786 Please note that the SCTP implementation must not bundle user 1787 messages that needs to be authenticated using different shared key 1788 identifiers. 1790 5.3.9. SCTP Destination Address Structure (IPv4) (SCTP_DSTADDRV4) 1792 This cmsghdr structure specifies SCTP options for sendmsg(). 1794 +--------------+----------------+----------------+ 1795 | cmsg_level | cmsg_type | cmsg_data[] | 1796 +--------------+----------------+----------------+ 1797 | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | 1798 +--------------+----------------+----------------+ 1800 This ancillary data can be used to provide more than one destination 1801 address to sendmsg(). It can be used to implement sctp_sendv() using 1802 sendmsg(). 1804 5.3.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6) 1806 This cmsghdr structure specifies SCTP options for sendmsg(). 1808 +--------------+----------------+-----------------+ 1809 | cmsg_level | cmsg_type | cmsg_data[] | 1810 +--------------+----------------+-----------------+ 1811 | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | 1812 +--------------+----------------+-----------------+ 1814 This ancillary data can be used to provide more than one destination 1815 address to sendmsg(). It can be used to implement sctp_sendv() using 1816 sendmsg(). 1818 6. SCTP Events and Notifications 1820 An SCTP application may need to understand and process events and 1821 errors that happen on the SCTP stack. These events include network 1822 status changes, association startups, remote operational errors and 1823 undeliverable messages. All of these can be essential for the 1824 application. 1826 When an SCTP application layer does a recvmsg() the message read is 1827 normally a data message from a peer endpoint. If the application 1828 wishes to have the SCTP stack deliver notifications of non-data 1829 events, it sets the appropriate socket option for the notifications 1830 it wants. See Section 6.2 for these socket options. When a 1831 notification arrives, recvmsg() returns the notification in the 1832 application-supplied data buffer via msg_iov, and sets 1833 MSG_NOTIFICATION in msg_flags. 1835 This section details the notification structures. Every notification 1836 structure carries some common fields which provide general 1837 information. 1839 A recvmsg() call will return only one notification at a time. Just 1840 as when reading normal data, it may return part of a notification if 1841 the msg_iov buffer is not large enough. If a single read is not 1842 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1843 reading the notification before subsequent data can arrive. 1845 6.1. SCTP Notification Structure 1847 The notification structure is defined as the union of all 1848 notification types. 1850 union sctp_notification { 1851 struct sctp_tlv { 1852 uint16_t sn_type; /* Notification type. */ 1853 uint16_t sn_flags; 1854 uint32_t sn_length; 1855 } sn_header; 1856 struct sctp_assoc_change sn_assoc_change; 1857 struct sctp_paddr_change sn_paddr_change; 1858 struct sctp_remote_error sn_remote_error; 1859 struct sctp_send_failed sn_send_failed; 1860 struct sctp_shutdown_event sn_shutdown_event; 1861 struct sctp_adaptation_event sn_adaptation_event; 1862 struct sctp_pdapi_event sn_pdapi_event; 1863 struct sctp_authkey_event sn_auth_event; 1864 struct sctp_sender_dry_event sn_sender_dry_event; 1865 struct sctp_send_failed_event sn_send_failed_event; 1866 }; 1868 sn_type: The following list describes the SCTP notification and 1869 event types for the field sn_type. 1871 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1872 either been opened or closed. Refer to Section 6.1.1 for 1873 details. 1875 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1876 part of an existing association has experienced a change of 1877 state (e.g. a failure or return to service of the reachability 1878 of an endpoint via a specific transport address). Please see 1879 Section 6.1.2 for data structure details. 1881 SCTP_REMOTE_ERROR: The attached error message is an Operational 1882 Error received from the remote peer. It includes the complete 1883 TLV sent by the remote endpoint. See Section 6.1.3 for the 1884 detailed format. 1886 SCTP_SEND_FAILED_EVENT: The attached datagram could not be sent 1887 to the remote endpoint. This structure includes the original 1888 SCTP_SNDINFO that was used in sending this message i.e. this 1889 structure uses the sctp_sndinfo per Section 6.1.11. 1891 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1892 data should be sent on this socket. 1894 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1895 indicated adaptation layer. Please see Section 6.1.6. 1897 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1898 receiver that the partial delivery has been aborted. This may 1899 indicate the association is about to be aborted. Please see 1900 Section 6.1.7. 1902 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1903 receiver that either an error occurred on authentication, or a 1904 new key was made active. See Section 6.1.8. 1906 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1907 application that the sender has no more user data queued for 1908 transmission nor retransmission. See Section 6.1.9. 1910 sn_flags: These are notification-specific flags. 1912 sn_length: This is the length of the whole sctp_notification 1913 structure including the sn_type, sn_flags, and sn_length fields. 1915 6.1.1. SCTP_ASSOC_CHANGE 1917 Communication notifications inform the application that an SCTP 1918 association has either begun or ended. The identifier for a new 1919 association is provided by this notification. The notification 1920 information has the following format: 1922 struct sctp_assoc_change { 1923 uint16_t sac_type; 1924 uint16_t sac_flags; 1925 uint32_t sac_length; 1926 uint16_t sac_state; 1927 uint16_t sac_error; 1928 uint16_t sac_outbound_streams; 1929 uint16_t sac_inbound_streams; 1930 sctp_assoc_t sac_assoc_id; 1931 uint8_t sac_info[]; 1932 }; 1934 sac_type: It should be SCTP_ASSOC_CHANGE. 1936 sac_flags: Currently unused. 1938 sac_length: This field is the total length of the notification data, 1939 including the notification header. 1941 sac_state: This field holds one of a number of values that 1942 communicate the event that happened to the association. They 1943 include: 1945 SCTP_COMM_UP: A new association is now ready and data may be 1946 exchanged with this peer. When an association has been 1947 established successfully, this notification should be the first 1948 one. 1950 SCTP_COMM_LOST: The association has failed. The association is 1951 now in the closed state. If SEND_FAILED notifications are 1952 turned on, an SCTP_COMM_LOST is accompanied by a series of 1953 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1954 message. 1956 SCTP_RESTART: SCTP has detected that the peer has restarted. 1958 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1960 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1961 blocking mode is set and data was sent (on a one-to-many style 1962 socket), an SCTP_CANT_STR_ASSOC is accompanied by a series of 1963 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1964 message. 1966 sac_error: If the state was reached due to an error condition (e.g. 1967 SCTP_COMM_LOST) any relevant error information is available in 1968 this field. This corresponds to the protocol error codes defined 1969 in [RFC4960]. 1971 sac_outbound_streams: 1973 sac_inbound_streams: The maximum number of streams allowed in each 1974 direction are available in sac_outbound_streams and sac_inbound 1975 streams. 1977 sac_assoc_id: The sac_assoc_id field holds the identifier for the 1978 association. All notifications for a given association have the 1979 same association identifier. For a one-to-one style socket, this 1980 field is ignored. 1982 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1983 received for this association, sac_info[] contains the complete 1984 ABORT chunk as defined in the SCTP specification [RFC4960] Section 1985 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1986 may contain an array of uint8_t describing the features that the 1987 current association supports. Features may include 1989 SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol 1990 extension described in [RFC3758]. 1992 SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol 1993 extension described in [RFC4895]. 1995 SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol 1996 extension described in [RFC5061]. 1998 SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the 1999 local endpoints use separate send and/or receive buffers for 2000 each SCTP association. 2002 6.1.2. SCTP_PEER_ADDR_CHANGE 2004 When a destination address of a multi-homed peer encounters a state 2005 change a peer address change event is sent. The notification has the 2006 following format: 2008 struct sctp_paddr_change { 2009 uint16_t spc_type; 2010 uint16_t spc_flags; 2011 uint32_t spc_length; 2012 struct sockaddr_storage spc_aaddr; 2013 uint32_t spc_state; 2014 uint32_t spc_error; 2015 sctp_assoc_t spc_assoc_id; 2016 } 2018 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 2020 spc_flags: Currently unused. 2022 spc_length: This field is the total length of the notification data, 2023 including the notification header. 2025 spc_aaddr: The affected address field holds the remote peer's 2026 address that is encountering the change of state. 2028 spc_state: This field holds one of a number of values that 2029 communicate the event that happened to the address. They include: 2031 SCTP_ADDR_AVAILABLE: This address is now reachable. This 2032 notification is provided whenever an address becomes reachable. 2034 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 2035 reached. Any data sent to this address is rerouted to an 2036 alternate until this address becomes reachable. This 2037 notification is provided whenever an address becomes 2038 unreachable. 2040 SCTP_ADDR_REMOVED: The address is no longer part of the 2041 association. 2043 SCTP_ADDR_ADDED: The address is now part of the association. 2045 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 2046 primary destination address. This notification is provided 2047 whenever an address is made primary. 2049 spc_error: If the state was reached due to any error condition (e.g. 2050 SCTP_ADDR_UNREACHABLE) any relevant error information is available 2051 in this field. 2053 spc_assoc_id: The spc_assoc_id field holds the identifier for the 2054 association. All notifications for a given association have the 2055 same association identifier. For a one-to-one style socket, this 2056 field is ignored. 2058 6.1.3. SCTP_REMOTE_ERROR 2060 A remote peer may send an Operational Error message to its peer. 2061 This message indicates a variety of error conditions on an 2062 association. The entire ERROR chunk as it appears on the wire is 2063 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 2064 specification [RFC4960] and any extensions for a list of possible 2065 error formats. An SCTP error notification has the following format: 2067 struct sctp_remote_error { 2068 uint16_t sre_type; 2069 uint16_t sre_flags; 2070 uint32_t sre_length; 2071 uint16_t sre_error; 2072 sctp_assoc_t sre_assoc_id; 2073 uint8_t sre_data[]; 2074 }; 2076 sre_type: It should be SCTP_REMOTE_ERROR. 2078 sre_flags: Currently unused. 2080 sre_length: This field is the total length of the notification data, 2081 including the notification header and the contents of sre_data. 2083 sre_error: This value represents one of the Operational Error causes 2084 defined in the SCTP specification, in network byte order. 2086 sre_assoc_id: The sre_assoc_id field holds the identifier for the 2087 association. All notifications for a given association have the 2088 same association identifier. For a one-to-one style socket, this 2089 field is ignored. 2091 sre_data: This contains the ERROR chunk as defined in the SCTP 2092 specification [RFC4960] Section 3.3.10. 2094 6.1.4. SCTP_SEND_FAILED - DEPRECATED 2096 Please note that this notification is deprecated. Use 2097 SCTP_SEND_FAILED_EVENT instead. 2099 If SCTP cannot deliver a message, it can return back the message as a 2100 notification if the SCTP_SEND_FAILED event is enabled. The 2101 notification has the following format: 2103 struct sctp_send_failed { 2104 uint16_t ssf_type; 2105 uint16_t ssf_flags; 2106 uint32_t ssf_length; 2107 uint32_t ssf_error; 2108 struct sctp_sndrcvinfo ssf_info; 2109 sctp_assoc_t ssf_assoc_id; 2110 uint8_t ssf_data[]; 2111 }; 2113 ssf_type: It should be SCTP_SEND_FAILED. 2115 ssf_flags: The flag value will take one of the following values: 2117 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2118 wire. 2120 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2121 Note that this does not necessarily mean that the data was (or 2122 was not) successfully delivered. 2124 ssf_length: This field is the total length of the notification data, 2125 including the notification header and the payload in ssf_data. 2127 ssf_error: This value represents the reason why the send failed, and 2128 if set, will be an SCTP protocol error code as defined in 2129 [RFC4960] Section 3.3.10. 2131 ssf_info: The ancillary data (struct sctp_sndrcvinfo) used to send 2132 the undelivered message. Regardless of if ancillary data is used 2133 or not, the ssf_info.sinfo_flags field indicates if the complete 2134 message or only part of the message is returned in ssf_data. If 2135 only part of the message is returned, it means that the part which 2136 is not present has been sent successfully to the peer. 2138 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2139 flags is set in ssf_info.sinfo_flags. If the first part of the 2140 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2141 This means that the tail end of the message is returned in 2142 ssf_data. 2144 ssf_assoc_id: The ssf_assoc_id field, ssf_assoc_id, holds the 2145 identifier for the association. All notifications for a given 2146 association have the same association identifier. For a one-to- 2147 one style socket, this field is ignored. 2149 ssf_data: The undelivered message or part of the undelivered message 2150 will be present in the ssf_data field. Note that the 2151 ssf_info.sinfo_flags field as noted above should be used to 2152 determine if a complete message is present or just a piece of the 2153 message. Note that only user data is present in this field, any 2154 chunk headers or SCTP common headers must be removed by the SCTP 2155 stack. 2157 6.1.5. SCTP_SHUTDOWN_EVENT 2159 When a peer sends a SHUTDOWN, SCTP delivers this notification to 2160 inform the application that it should cease sending data. 2162 struct sctp_shutdown_event { 2163 uint16_t sse_type; 2164 uint16_t sse_flags; 2165 uint32_t sse_length; 2166 sctp_assoc_t sse_assoc_id; 2167 }; 2169 sse_type: It should be SCTP_SHUTDOWN_EVENT. 2171 sse_flags: Currently unused. 2173 sse_length: This field is the total length of the notification data, 2174 including the notification header. It will generally be 2175 sizeof(struct sctp_shutdown_event). 2177 sse_flags: Currently unused. 2179 sse_assoc_id: The sse_assoc_id field holds the identifier for the 2180 association. All notifications for a given association have the 2181 same association identifier. For a one-to-one style socket, this 2182 field is ignored. 2184 6.1.6. SCTP_ADAPTATION_INDICATION 2186 When a peer sends an Adaptation Layer Indication parameter as 2187 described in [RFC5061], SCTP delivers this notification to inform the 2188 application about the peer's adaptation layer indication. 2190 struct sctp_adaptation_event { 2191 uint16_t sai_type; 2192 uint16_t sai_flags; 2193 uint32_t sai_length; 2194 uint32_t sai_adaptation_ind; 2195 sctp_assoc_t sai_assoc_id; 2196 }; 2197 sai_type: It should be SCTP_ADAPTATION_INDICATION. 2199 sai_flags: Currently unused. 2201 sai_length: This field is the total length of the notification data, 2202 including the notification header. It will generally be 2203 sizeof(struct sctp_adaptation_event). 2205 sai_adaptation_ind: This field holds the bit array sent by the peer 2206 in the adaptation layer indication parameter. 2208 sai_assoc_id: The sai_assoc_id field holds the identifier for the 2209 association. All notifications for a given association have the 2210 same association identifier. For a one-to-one style socket, this 2211 field is ignored. 2213 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT 2215 When a receiver is engaged in a partial delivery of a message this 2216 notification will be used to indicate various events. 2218 struct sctp_pdapi_event { 2219 uint16_t pdapi_type; 2220 uint16_t pdapi_flags; 2221 uint32_t pdapi_length; 2222 uint32_t pdapi_indication; 2223 uint32_t pdapi_stream; 2224 uint32_t pdapi_seq; 2225 sctp_assoc_t pdapi_assoc_id; 2226 }; 2228 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 2230 pdapi_flags: Currently unused. 2232 pdapi_length: This field is the total length of the notification 2233 data, including the notification header. It will generally be 2234 sizeof(struct sctp_pdapi_event). 2236 pdapi_indication: This field holds the indication being sent to the 2237 application. Currently there is only one defined value: 2239 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 2240 delivery of a user message has been aborted. This happens, for 2241 example, if an association is aborted while a partial delivery 2242 is going on or the user message gets abandoned using PR-SCTP 2243 while the partial delivery of this message is going on. 2245 pdapi_stream: This field holds the stream on which the partial 2246 delivery event happened. 2248 pdapi_seq: This field holds the stream sequence number which was 2249 being partially delivered. 2251 pdapi_assoc_id: The pdapi_assoc_id field holds the identifier for 2252 the association. All notifications for a given association have 2253 the same association identifier. For a one-to-one style socket 2254 this field is ignored. 2256 6.1.8. SCTP_AUTHENTICATION_EVENT 2258 [RFC4895] defines an extension to authenticate SCTP messages. The 2259 following notification is used to report different events relating to 2260 the use of this extension. 2262 struct sctp_authkey_event { 2263 uint16_t auth_type; 2264 uint16_t auth_flags; 2265 uint32_t auth_length; 2266 uint16_t auth_keynumber; 2267 uint32_t auth_indication; 2268 sctp_assoc_t auth_assoc_id; 2269 }; 2271 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 2273 auth_flags: Currently unused. 2275 auth_length: This field is the total length of the notification 2276 data, including the notification header. It will generally be 2277 sizeof(struct sctp_authkey_event). 2279 auth_keynumber: This field holds the keynumber for the affected key 2280 indicated in the event (depends on auth_indication). 2282 auth_indication: This field holds the error or indication being 2283 reported. The following values are currently defined: 2285 SCTP_AUTH_NEW_KEY: This report indicates that a new key has been 2286 made active (used for the first time by the peer) and is now 2287 the active key. The auth_keynumber field holds the user 2288 specified key number. 2290 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 2291 support SCTP AUTH as defined in [RFC4895]. 2293 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 2294 implementation will no longer use the key identifier specified 2295 in auth_keynumber. 2297 auth_assoc_id: The auth_assoc_id field holds the identifier for the 2298 association. All notifications for a given association have the 2299 same association identifier. For a one-to-one style socket this 2300 field is ignored. 2302 6.1.9. SCTP_SENDER_DRY_EVENT 2304 When the SCTP stack has no more user data to send or retransmit, this 2305 notification is given to the user. Also, at the time when a user app 2306 subscribes to this event, if there is no data to be sent or 2307 retransmit, the stack will immediately send up this notification. 2309 struct sctp_sender_dry_event { 2310 uint16_t sender_dry_type; 2311 uint16_t sender_dry_flags; 2312 uint32_t sender_dry_length; 2313 sctp_assoc_t sender_dry_assoc_id; 2314 }; 2316 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 2318 sender_dry_flags: Currently unused. 2320 sender_dry_length: This field is the total length of the 2321 notification data, including the notification header. It will 2322 generally be sizeof(struct sctp_sender_dry_event). 2324 sender_dry_assoc_id: The sender_dry_assoc_id field holds the 2325 identifier for the association. All notifications for a given 2326 association have the same association identifier. For a one-to- 2327 one style socket this field is ignored. 2329 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT 2331 SCTP notifications, when subscribed to, are reliable. They are 2332 always delivered as long as there is space in the socket receive 2333 buffer. However, if an implementation experiences a notification 2334 storm, it may run out of socket buffer space. When this occurs it 2335 may wish to disable notifications. If the implementation chooses to 2336 do this, it will append a final notification 2337 SCTP_NOTIFICATIONS_STOPPED_EVENT. This notification is a union 2338 sctp_notification, where only the struct sctp_tlv (see the union 2339 above) is used. It only contains this type in the sn_type field, the 2340 sn_length field set to the sizeof an sctp_tlv structure and the 2341 sn_flags set to 0. If an application receives this notification, it 2342 will need to re-subscribe to any notifications of interest to it, 2343 except for the sctp_data_io_event (note that SCTP_EVENTS is 2344 deprecated). 2346 An endpoint is automatically subscribed to this event as soon as it 2347 is subscribed to any event other than data io events. 2349 6.1.11. SCTP_SEND_FAILED_EVENT 2351 If SCTP cannot deliver a message, it can return back the message as a 2352 notification if the SCTP_SEND_FAILED_EVENT event is enabled. The 2353 notification has the following format: 2355 struct sctp_send_failed_event { 2356 uint16_t ssfe_type; 2357 uint16_t ssfe_flags; 2358 uint32_t ssfe_length; 2359 uint32_t ssfe_error; 2360 struct sctp_sndinfo ssfe_info; 2361 sctp_assoc_t ssfe_assoc_id; 2362 uint8_t ssfe_data[]; 2363 }; 2365 ssfe_type: It should be SCTP_SEND_FAILED_EVENT. 2367 ssfe_flags: The flag value will take one of the following values: 2369 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2370 wire. 2372 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2373 Note that this does not necessarily mean that the data was (or 2374 was not) successfully delivered. 2376 ssfe_length: This field is the total length of the notification 2377 data, including the notification header and the payload in 2378 ssf_data. 2380 ssfe_error: This value represents the reason why the send failed, 2381 and if set, will be an SCTP protocol error code as defined in 2382 [RFC4960] Section 3.3.10. 2384 ssfe_info: The ancillary data (struct sctp_sndinfo) used to send the 2385 undelivered message. Regardless of if ancillary data is used or 2386 not, the ssfe_info.sinfo_flags field indicates if the complete 2387 message or only part of the message is returned in ssf_data. If 2388 only part of the message is returned, it means that the part which 2389 is not present has been sent successfully to the peer. 2391 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2392 flags is set in ssfe_info.sinfo_flags. If the first part of the 2393 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2394 This means that the tail end of the message is returned in 2395 ssf_data. 2397 ssfe_assoc_id: The ssfe_assoc_id field, ssf_assoc_id, holds the 2398 identifier for the association. All notifications for a given 2399 association have the same association identifier. For a one-to- 2400 one style socket, this field is ignored. 2402 ssfe_data: The undelivered message or part of the undelivered 2403 message will be present in the ssf_data field. Note that the 2404 ssf_info.sinfo_flags field as noted above should be used to 2405 determine if a complete message is present or just a piece of the 2406 message. Note that only user data is present in this field, any 2407 chunk headers or SCTP common headers must be removed by the SCTP 2408 stack. 2410 6.2. Notification Interest Options 2412 6.2.1. SCTP_EVENTS option - DEPRECATED 2414 Please note that this option is deprecated. Use the SCTP_EVENT 2415 option described in Section 6.2.2 instead. 2417 To receive SCTP event notifications, an application registers its 2418 interest by setting the SCTP_EVENTS socket option. The application 2419 then uses recvmsg() to retrieve notifications. A notification is 2420 stored in the data part (msg_iov) of the struct msghdr. The socket 2421 option uses the following structure: 2423 struct sctp_event_subscribe { 2424 uint8_t sctp_data_io_event; 2425 uint8_t sctp_association_event; 2426 uint8_t sctp_address_event; 2427 uint8_t sctp_send_failure_event; 2428 uint8_t sctp_peer_error_event; 2429 uint8_t sctp_shutdown_event; 2430 uint8_t sctp_partial_delivery_event; 2431 uint8_t sctp_adaptation_layer_event; 2432 uint8_t sctp_authentication_event; 2433 uint8_t sctp_sender_dry_event; 2434 }; 2436 sctp_data_io_event: Setting this flag to 1 will cause the reception 2437 of SCTP_SNDRCV information on a per message basis. The 2438 application will need to use the recvmsg() interface so that it 2439 can receive the event information contained in the msg_control 2440 field. Setting the flag to 0 will disable the reception of the 2441 message control information. Note that this is not really a 2442 notification and this is stored in the ancillary data 2443 (msg_control), not in the data part (msg_iov). 2445 sctp_association_event: Setting this flag to 1 will enable the 2446 reception of association event notifications. Setting the flag to 2447 0 will disable association event notifications. 2449 sctp_address_event: Setting this flag to 1 will enable the reception 2450 of address event notifications. Setting the flag to 0 will 2451 disable address event notifications. 2453 sctp_send_failure_event: Setting this flag to 1 will enable the 2454 reception of send failure event notifications. Setting the flag 2455 to 0 will disable send failure event notifications. 2457 sctp_peer_error_event: Setting this flag to 1 will enable the 2458 reception of peer error event notifications. Setting the flag to 2459 0 will disable peer error event notifications. 2461 sctp_shutdown_event: Setting this flag to 1 will enable the 2462 reception of shutdown event notifications. Setting the flag to 0 2463 will disable shutdown event notifications. 2465 sctp_partial_delivery_event: Setting this flag to 1 will enable the 2466 reception of partial delivery notifications. Setting the flag to 2467 0 will disable partial delivery event notifications. 2469 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 2470 reception of adaptation layer notifications. Setting the flag to 2471 0 will disable adaptation layer event notifications. 2473 sctp_authentication_event: Setting this flag to 1 will enable the 2474 reception of authentication layer notifications. Setting the flag 2475 to 0 will disable authentication layer event notifications. 2477 sctp_sender_dry_event: Setting this flag to 1 will enable the 2478 reception of sender dry notifications. Setting the flag to 0 will 2479 disable sender dry event notifications. 2481 An example where an application would like to receive data_io_events 2482 and association_events but no others would be as follows: 2484 { 2485 struct sctp_event_subscribe events; 2487 memset(&events,0,sizeof(events)); 2489 events.sctp_data_io_event = 1; 2490 events.sctp_association_event = 1; 2492 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 2493 } 2495 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2496 receives ancillary data and notifications for all associations bound 2497 to the file descriptor. For one-to-one style SCTP sockets, the 2498 caller receives ancillary data and notifications only for the single 2499 association bound to the file descriptor. 2501 By default both the one-to-one style and the one-to-many style socket 2502 do not subscribe to any notification. 2504 6.2.2. SCTP_EVENT option 2506 The SCTP_EVENTS socket option has one issue for future compatibility. 2507 As new features are added the structure (sctp_event_subscribe) must 2508 be expanded. This can cause an application binary interface (ABI) 2509 issue unless an implementation has added padding at the end of the 2510 structure. To avoid this problem, SCTP_EVENTS has been deprecated 2511 and a new socket option SCTP_EVENT has taken its place. The option 2512 is used with the following structure: 2514 struct sctp_event { 2515 sctp_assoc_t se_assoc_id; 2516 uint16_t se_type; 2517 uint8_t se_on; 2518 }; 2520 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 2521 sockets. For one-to-many style sockets this field can be a 2522 particular association identifier or SCTP_{FUTURE|CURRENT| 2523 ALL}_ASSOC. 2525 se_type: The se_type field can be filled with any value that would 2526 show up in the respective sn_type field (in the sctp_tlv structure 2527 of the notification). 2529 se_on: The se_on field is set to 1 to turn on an event and set to 0 2530 to turn off an event. 2532 To use this option the user fills in this structure and then calls 2533 the setsockopt to turn on or off an individual event. The following 2534 is an example use of this option: 2536 { 2537 struct sctp_event event; 2539 memset(&event, 0, sizeof(event)); 2541 event.se_assoc_id = SCTP_FUTURE_ASSOC; 2542 event.se_type = SCTP_SENDER_DRY_EVENT; 2543 event.se_on = 1; 2544 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2545 } 2547 By default both the one-to-one style and the one-to-many style socket 2548 do not subscribe to any notification. 2550 7. Common Operations for Both Styles 2552 7.1. send(), recv(), sendto(), and recvfrom() 2554 Applications can use send() and sendto() to transmit data to the peer 2555 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2556 data from the peer. 2558 The function prototypes are 2559 ssize_t send(int sd, 2560 const void *msg, 2561 size_t len, 2562 int flags); 2564 ssize_t sendto(int sd, 2565 const void *msg, 2566 size_t len, 2567 int flags, 2568 const struct sockaddr *to, 2569 socklen_t tolen); 2571 ssize_t recv(int sd, 2572 void *buf, 2573 size_t len, 2574 int flags); 2576 ssize_t recvfrom(int sd, 2577 void *buf, 2578 size_t len, 2579 int flags, 2580 struct sockaddr *from, 2581 socklen_t *fromlen); 2583 and the arguments are 2585 sd: The socket descriptor of an SCTP endpoint. 2587 msg: The message to be sent. 2589 len: The size of the message or the size of the buffer. 2591 to: One of the peer addresses of the association to be used to send 2592 the message. 2594 tolen: The size of the address. 2596 buf: The buffer to store a received message. 2598 from: The buffer to store the peer address used to send the received 2599 message. 2601 fromlen: The size of the from address. 2603 flags: (described below). 2605 These calls give access to only basic SCTP protocol features. If 2606 either peer in the association uses multiple streams, or sends 2607 unordered data, these calls will usually be inadequate, and may 2608 deliver the data in unpredictable ways. 2610 SCTP has the concept of multiple streams in one association. The 2611 above calls do not allow the caller to specify on which stream a 2612 message should be sent. The system uses stream 0 as the default 2613 stream for send() and sendto(). recv() and recvfrom() return data 2614 from any stream, but the caller can not distinguish the different 2615 streams. This may result in data seeming to arrive out of order. 2616 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2617 provide no indication. 2619 SCTP is message based. The msg buffer above in send() and sendto() 2620 is considered to be a single message. This means that if the caller 2621 wants to send a message that is composed by several buffers, the 2622 caller needs to combine them before calling send() or sendto(). 2623 Alternately, the caller can use sendmsg() to do that without 2624 combining them. Sending a message using send() or sendto() is atomic 2625 unless explicit EOR marking is enabled on the socket specified by sd. 2626 Using sendto() on a non-connected one-to-one style socket for 2627 implicit connection setup may or may not work depending on the SCTP 2628 implementation. recv() and recvfrom() cannot distinguish message 2629 boundaries (i.e. there is no way to observe the MSG_EOR flag to 2630 detect partial delivery). 2632 In receiving, if the buffer supplied is not large enough to hold a 2633 complete message, the receive call acts like a stream socket and 2634 returns as much data as will fit in the buffer. 2636 Note, the send() and recv() calls may not be used for a one-to-many 2637 style socket. 2639 Note, if an application calls a send() or sendto() function with no 2640 user data the SCTP implementation should reject the request with an 2641 appropriate error message. An implementation is not allowed to send 2642 a DATA chunk with no user data [RFC4960]. 2644 7.2. setsockopt() and getsockopt() 2646 Applications use setsockopt() and getsockopt() to set or retrieve 2647 socket options. Socket options are used to change the default 2648 behavior of socket calls. They are described in Section 8. 2650 The function prototypes are 2652 int getsockopt(int sd, 2653 int level, 2654 int optname, 2655 void *optval, 2656 socklen_t *optlen); 2658 and 2660 int setsockopt(int sd, 2661 int level, 2662 int optname, 2663 const void *optval, 2664 socklen_t optlen); 2666 and the arguments are 2668 sd: The socket descriptor. 2670 level: Set to IPPROTO_SCTP for all SCTP options. 2672 optname: The option name. 2674 optval: The buffer to store the value of the option. 2676 optlen: The size of the buffer (or the length of the option 2677 returned). 2679 They return 0 on success and -1 in case of an error. 2681 All socket options set on a one-to-one style listening socket also 2682 apply to all future accepted sockets. For one-to-many style sockets 2683 often a socket option will pass a structure that includes an assoc_id 2684 field. This field can be filled with the association identifier of a 2685 particular association and unless otherwise specified can be filled 2686 with one of the following constants: 2688 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2689 after this socket option will be affected by this call. 2691 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2692 associations will be affected by this call, future associations 2693 will still receive the previous default value. 2695 SCTP_ALL_ASSOC: Specifies that all current and future associations 2696 will be affected by this call. 2698 7.3. read() and write() 2700 Applications can use read() and write() to send and receive data to 2701 and from a peer. They have the same semantics as send() and recv() 2702 except that the flags parameter cannot be used. 2704 7.4. getsockname() 2706 Applications use getsockname() to retrieve the locally-bound socket 2707 address of the specified socket. This is especially useful if the 2708 caller let SCTP choose a local port. This call is for single homed 2709 endpoints. It does not work well with multi-homed endpoints. See 2710 Section 9.5 for a multi-homed version of the call. 2712 The function prototype is 2714 int getsockname(int sd, 2715 struct sockaddr *address, 2716 socklen_t *len); 2718 and the arguments are 2720 sd: The socket descriptor to be queried. 2722 address: On return, one locally bound address (chosen by the SCTP 2723 stack) is stored in this buffer. If the socket is an IPv4 socket, 2724 the address will be IPv4. If the socket is an IPv6 socket, the 2725 address will be either an IPv6 or IPv4 address. 2727 len: The caller should set the length of the address here. On 2728 return, this is set to the length of the returned address. 2730 It returns 0 on success and -1 in case of an error. 2732 If the actual length of the address is greater than the length of the 2733 supplied sockaddr structure, the stored address will be truncated. 2735 If the socket has not been bound to a local name, the value stored in 2736 the object pointed to by address is unspecified. 2738 7.5. Implicit Association Setup 2740 The application can begin sending and receiving data using the 2741 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 2742 through any explicit association setup procedures (i.e., no connect() 2743 calls required). 2745 Whenever sendmsg() or sendto() is called and the SCTP stack at the 2746 sender finds that no association exists between the sender and the 2747 intended receiver (identified by the address passed either in the 2748 msg_name field of msghdr structure in the sendmsg() call or the 2749 dest_addr field in the sendto() call), the SCTP stack will 2750 automatically setup an association to the intended receiver. 2752 Upon the successful association setup an SCTP_COMM_UP notification 2753 will be dispatched to the socket at both the sender and receiver 2754 side. This notification can be read by the recvmsg() system call 2755 (see Section 3.1.4). 2757 Note, if the SCTP stack at the sender side supports bundling, the 2758 first user message may be bundled with the COOKIE ECHO message 2759 [RFC4960]. 2761 When the SCTP stack sets up a new association implicitly, the 2762 SCTP_INIT type ancillary data may also be passed along (see 2763 Section 5.3.1 for details of the data structures) to change some 2764 parameters used in setting up a new association. 2766 If this information is not present in the sendmsg() call, or if the 2767 implicit association setup is triggered by a sendto() call, the 2768 default association initialization parameters will be used. These 2769 default association parameters may be set with respective 2770 setsockopt() calls or be left to the system defaults. 2772 Implicit association setup cannot be initiated by send() calls. 2774 8. Socket Options 2776 The following sub-section describes various SCTP level socket options 2777 that are common to both styles. SCTP associations can be multi- 2778 homed. Therefore, certain option parameters include a 2779 sockaddr_storage structure to select which peer address the option 2780 should be applied to. 2782 For the one-to-many style sockets, an sctp_assoc_t (association 2783 identifier) parameter is used to identify the association instance 2784 that the operation affects. So it must be set when using this style. 2786 For the one-to-one style sockets and branched off one-to-many style 2787 sockets (see Section 9.2) this association ID parameter is ignored. 2789 Note that socket or IP level options are set or retrieved per socket. 2791 This means that for one-to-many style sockets, the options will be 2792 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2793 association identifier) belonging to the socket. For one-to-one 2794 style, these options will be applied to all peer addresses of the 2795 association controlled by the socket. Applications should be careful 2796 in setting those options. 2798 For some IP stacks getsockopt() is read-only; so a new interface will 2799 be needed when information must be passed both into and out of the 2800 SCTP stack. The syntax for sctp_opt_info() is 2802 int sctp_opt_info(int sd, 2803 sctp_assoc_t id, 2804 int opt, 2805 void *arg, 2806 socklen_t *size); 2808 The sctp_opt_info() call is a replacement for getsockopt() only and 2809 will not set any options associated with the specified socket. A 2810 setsockopt() must be used to set any writeable option. 2812 For one-to-many style sockets, id specifies the association to query. 2813 For one-to-one style sockets, id is ignored. For one-to-many 2814 sockets, any association identifier in the structure provided as arg 2815 is ignored and id takes precedence. 2817 Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used with 2818 sctp_opt_info() or in getsockopt() calls. Using them will result in 2819 an error (returning -1 and errno set to EINVAL). SCTP_FUTURE_ASSOC 2820 can be used to query information for future associations. 2822 The field opt specifies which SCTP socket option to get. It can get 2823 any socket option currently supported that requests information 2824 (either read/write options or read only) such as: 2826 SCTP_RTOINFO 2828 SCTP_ASSOCINFO 2830 SCTP_DEFAULT_SEND_PARAM 2832 SCTP_GET_PEER_ADDR_INFO 2834 SCTP_PRIMARY_ADDR 2835 SCTP_PEER_ADDR_PARAMS 2837 SCTP_STATUS 2839 SCTP_CONTEXT 2841 SCTP_AUTH_ACTIVE_KEY 2843 SCTP_PEER_AUTH_CHUNKS 2845 SCTP_LOCAL_AUTH_CHUNKS 2847 The arg field is an option-specific structure buffer provided by the 2848 caller. See the rest of this sections subsections for more 2849 information on these options and option-specific structures. 2851 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2852 sets errno to the appropriate error code. 2854 8.1. Read / Write Options 2856 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2858 The protocol parameters used to initialize and limit the 2859 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2860 information on how these parameters are used in RTO calculation. 2862 The following structure is used to access and modify these 2863 parameters: 2865 struct sctp_rtoinfo { 2866 sctp_assoc_t srto_assoc_id; 2867 uint32_t srto_initial; 2868 uint32_t srto_max; 2869 uint32_t srto_min; 2870 }; 2872 srto_initial: This contains the initial RTO value. 2874 srto_max and srto_min: These contain the maximum and minimum bounds 2875 for all RTOs. 2877 srto_assoc_id: This parameter is ignored for one-to-one style 2878 sockets. For one-to-many style sockets the application may fill 2879 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 2880 to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id. 2882 All times are given in milliseconds. A value of 0, when modifying 2883 the parameters, indicates that the current value should not be 2884 changed. 2886 To access or modify these parameters, the application should call 2887 getsockopt() or setsockopt() respectively with the option name 2888 SCTP_RTOINFO. 2890 8.1.2. Association Parameters (SCTP_ASSOCINFO) 2892 This option is used to both examine and set various association and 2893 endpoint parameters. See [RFC4960] for more information on how this 2894 parameter is used. 2896 The following structure is used to access and modify these 2897 parameters: 2899 struct sctp_assocparams { 2900 sctp_assoc_t sasoc_assoc_id; 2901 uint16_t sasoc_asocmaxrxt; 2902 uint16_t sasoc_number_peer_destinations; 2903 uint32_t sasoc_peer_rwnd; 2904 uint32_t sasoc_local_rwnd; 2905 uint32_t sasoc_cookie_life; 2906 }; 2908 sasoc_assoc_id: This parameter is ignored for one-to-one style 2909 sockets. For one-to-many style sockets the application may fill 2910 in an association identifier or SCTP_FUTURE_ASSOC. It is an error 2911 to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id. 2913 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2914 to make for the association. 2916 sasoc_number_peer_destinations: This is the number of destination 2917 addresses that the peer has. 2919 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2920 (reported in the last SACK) minus any outstanding data (i.e. data 2921 in flight). 2923 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2924 the peer. 2926 sasoc_cookie_life: This is the association's cookie life value used 2927 when issuing cookies. 2929 The values of the sasoc_peer_rwnd is meaningless when examining 2930 endpoint information (i.e. it is only valid when examining 2931 information on a specific association). 2933 All time values are given in milliseconds. A value of 0, when 2934 modifying the parameters, indicates that the current value should not 2935 be changed. 2937 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2938 on either an endpoint or association basis. The rwnd and destination 2939 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2940 sasoc_local_rwnd) are not settable and any value placed in these is 2941 ignored. 2943 To access or modify these parameters, the application should call 2944 getsockopt() or setsockopt() respectively with the option name 2945 SCTP_ASSOCINFO. 2947 The maximum number of retransmissions before an address is considered 2948 unreachable is also tunable, but is address-specific, so it is 2949 covered in a separate option. If an application attempts to set the 2950 value of the association maximum retransmission parameter to more 2951 than the sum of all maximum retransmission parameters, setsockopt() 2952 may return an error. The reason for this, from [RFC4960] Section 2953 8.2: 2955 Note: When configuring the SCTP endpoint, the user should avoid 2956 having the value of 'Association.Max.Retrans' (sasoc_maxrxt in this 2957 option) larger than the summation of the 'Path.Max.Retrans' (see 2958 Section 8.1.12 on spp_pathmaxrxt) of all the destination addresses 2959 for the remote endpoint. Otherwise, all the destination addresses 2960 may become inactive while the endpoint still considers the peer 2961 endpoint reachable. 2963 8.1.3. Initialization Parameters (SCTP_INITMSG) 2965 Applications can specify protocol parameters for the default 2966 association initialization. The structure used to access and modify 2967 these parameters is defined in Section 5.3.1. The option name 2968 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2970 Setting initialization parameters is effective only on an unconnected 2971 socket (for one-to-many style sockets only future associations are 2972 affected by the change). 2974 8.1.4. SO_LINGER 2976 An application can use this option to perform the SCTP ABORT 2977 primitive. This option affects all associations related to the 2978 socket. 2980 The linger option structure is: 2982 struct linger { 2983 int l_onoff; /* option on/off */ 2984 int l_linger; /* linger time */ 2985 }; 2987 To enable the option, set l_onoff to 1. If the l_linger value is set 2988 to 0, calling close() is the same as the ABORT primitive. If the 2989 value is set to a negative value, the setsockopt() call will return 2990 an error. If the value is set to a positive value linger_time, the 2991 close() can be blocked for at most linger_time. Please note that the 2992 time unit is seconds according to POSIX, but might be different on 2993 specific platforms. If the graceful shutdown phase does not finish 2994 during this period, close() will return but the graceful shutdown 2995 phase will continue in the system. 2997 Note, this is a socket level option, not an SCTP level option. When 2998 using this option, an application must specify a level of SOL_SOCKET 2999 in the call. 3001 8.1.5. SCTP_NODELAY 3003 Turn on/off any Nagle-like algorithm. This means that packets are 3004 generally sent as soon as possible and no unnecessary delays are 3005 introduced, at the cost of more packets in the network. Turning this 3006 option on disables any Nagle-like algorithm. 3008 This option expects an integer boolean flag, where a non-zero value 3009 turns on the option, and a zero value turns off the option. 3011 8.1.6. SO_RCVBUF 3013 Sets the receive buffer size in octets. For SCTP one-to-one style 3014 sockets, this controls the receiver window size. For one-to-many 3015 style sockets the meaning is implementation dependent. It might 3016 control the receive buffer for each association bound to the socket 3017 descriptor or it might control the receive buffer for the whole 3018 socket. This option expects an integer. 3020 Note, this is a socket level option, not an SCTP level option. When 3021 using this option, an application must specify a level of SOL_SOCKET 3022 in the call. 3024 8.1.7. SO_SNDBUF 3026 Sets the send buffer size. For SCTP one-to-one style sockets, this 3027 controls the amount of data SCTP may have waiting in internal buffers 3028 to be sent. This option therefore bounds the maximum size of data 3029 that can be sent in a single send call. For one-to-many style 3030 sockets, the effect is the same, except that it applies to one or all 3031 associations (see Section 3.3) bound to the socket descriptor used in 3032 the setsockopt() or getsockopt() call. The option applies to each 3033 association's window size separately. This option expects an 3034 integer. 3036 Note, this is a socket level option, not an SCTP level option. When 3037 using this option, an application must specify a level of SOL_SOCKET 3038 in the call. 3040 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 3042 This socket option is applicable to the one-to-many style socket 3043 only. When set it will cause associations that are idle for more 3044 than the specified number of seconds to automatically close using the 3045 graceful shutdown procedure. An association being idle is defined as 3046 an association that has not sent or received user data. The special 3047 value of '0' indicates that no automatic close of any association 3048 should be performed, this is the default value. This option expects 3049 an integer defining the number of seconds of idle time before an 3050 association is closed. 3052 An application using this option should enable receiving the 3053 association change notification. This is the only mechanism an 3054 application is informed about the closing of an association. After 3055 an association is closed, the association identifier assigned to it 3056 can be reused. An application should be aware of this to avoid the 3057 possible problem of sending data to an incorrect peer endpoint. 3059 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 3061 Requests that the local SCTP stack uses the enclosed peer address as 3062 the association's primary. The enclosed address must be one of the 3063 association peer's addresses. 3065 The following structure is used to make a set peer primary request: 3067 struct sctp_setprim { 3068 sctp_assoc_t ssp_assoc_id; 3069 struct sockaddr_storage ssp_addr; 3070 }; 3071 ssp_addr: The address to set as primary. No wildcard address is 3072 allowed. 3074 ssp_assoc_id: This parameter is ignored for one-to-one style 3075 sockets. For one-to-many style sockets it identifies the 3076 association for this request. Note that the special sctp_assoc_t 3077 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 3079 8.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 3081 Requests that the local endpoint set the specified Adaptation Layer 3082 Indication parameter for all future INIT and INIT-ACK exchanges. 3084 The following structure is used to access and modify this parameter: 3086 struct sctp_setadaptation { 3087 uint32_t ssb_adaptation_ind; 3088 }; 3090 ssb_adaptation_ind: The adaptation layer indicator that will be 3091 included in any outgoing Adaptation Layer Indication parameter. 3093 8.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 3095 This option is a on/off flag and is passed as an integer where a non- 3096 zero is on and a zero is off. If enabled no SCTP message 3097 fragmentation will be performed. The effect of enabling this option 3098 are that if a message being sent exceeds the current PMTU size, the 3099 message will not be sent and instead an error will be indicated to 3100 the user. If this option is disabled (the default) then a message 3101 exceeding the size of the PMTU will be fragmented and reassembled by 3102 the peer. 3104 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 3106 Applications can enable or disable heartbeats for any peer address of 3107 an association, modify an address's heartbeat interval, force a 3108 heartbeat to be sent immediately, and adjust the address's maximum 3109 number of retransmissions sent before an address is considered 3110 unreachable. 3112 The following structure is used to access and modify an address's 3113 parameters: 3115 struct sctp_paddrparams { 3116 sctp_assoc_t spp_assoc_id; 3117 struct sockaddr_storage spp_address; 3118 uint32_t spp_hbinterval; 3119 uint16_t spp_pathmaxrxt; 3120 uint32_t spp_pathmtu; 3121 uint32_t spp_flags; 3122 uint32_t spp_ipv6_flowlabel; 3123 uint8_t spp_ipv4_tos; 3124 }; 3126 spp_assoc_id: This parameter is ignored for one-to-one style 3127 sockets. For one-to-many style sockets it identifies the 3128 association for this query. Note that the predefined constants 3129 are not allowed. 3131 spp_address: This specifies which address is of interest. If a 3132 wildcard address is provided it applies to all current and future 3133 paths. 3135 spp_hbinterval: This contains the value of the heartbeat interval, 3136 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 3137 spp_flag is set to SPP_HB_ENABLE the value of this field is 3138 ignored. Note also that a value of zero indicates the current 3139 setting should be left unchanged. To set an actual value of zero 3140 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 3141 it is set to 0, it does not mean that SCTP will continuously send 3142 out heartbeat since the actual interval also includes the current 3143 RTO and jitter (see Section 8.3 in [RFC4960]). 3145 spp_pathmaxrxt: This contains the maximum number of retransmissions 3146 before this address shall be considered unreachable. Note that a 3147 value of zero indicates the current setting should be left 3148 unchanged. 3150 spp_pathmtu: The current path MTU of the peer address. It is the 3151 number of bytes available in an SCTP packet for chunks. Providing 3152 a value of 0 does not change the current setting. If a positive 3153 value is provided and SPP_PMTUD_DISABLE is set in the spp_flags, 3154 the given value is used as the path MTU. If SPP_PMTUD_ENABLE is 3155 set in the spp_flags, the spp_pathmtu field is ignored. 3157 spp_ipv6_flowlabel: This field is used in conjunction with the 3158 SPP_IPV6_FLOWLABEL flag. This setting has precedence over any 3159 IPv6 layer setting. 3161 spp_ipv4_tos: This field is used in conjunction with the 3162 SPP_IPV4_TOS flag. This setting has precedence over any IPv4 3163 layer setting. 3165 spp_flags: These flags are used to control various features on an 3166 association. The flag field is a bit mask which may contain zero 3167 or more of the following options: 3169 SPP_HB_ENABLE: Enable heartbeats on the specified address. 3171 SPP_HB_DISABLE: Disable heartbeats on the specified address. 3172 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 3173 exclusive, only one of these two should be specified. Enabling 3174 both fields will have undetermined results. 3176 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 3177 immediately. This must not be used in conjunction with a 3178 wildcard address. 3180 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 3181 is to be set to the value of 0 milliseconds. 3183 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 3184 specified address. 3186 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 3187 the specified address. Note that if the address field is empty 3188 then all addresses on the association are affected. Note also 3189 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 3190 exclusive. Enabling both will have undetermined results. 3192 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 3193 IPV6 flowlabel value. The value is obtained in the 3194 spp_ipv6_flowlabel field. 3196 Upon retrieval, this flag will be set to indicate that the 3197 spp_ipv6_flowlabel field has a valid value returned. If a 3198 specific destination address is set (in the spp_address field), 3199 then the value returned is that of the address. If just an 3200 association is specified (and no address), then the 3201 association's default flowlabel is returned. If neither an 3202 association nor a destination is specified, then the socket's 3203 default flowlabel is returned. For non IPv6 sockets, this flag 3204 will be left cleared. 3206 SPP_IPV4_TOS: Setting this flag enables the setting of the IPV4 3207 TOS value associated with either the association or a specific 3208 address. The value is obtained in the spp_ipv4_tos field. 3210 Upon retrieval, this flag will be set to indicate that the 3211 spp_ipv4_tos field has a valid value returned. If a specific 3212 destination address is set when called (in the spp_address 3213 field) then that specific destination address' TOS value is 3214 returned. If just an association is specified then the 3215 association default TOS is returned. If neither an association 3216 nor a destination is specified, then the sockets default TOS is 3217 returned. 3219 To read or modify these parameters, the application should call 3220 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 3222 8.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) - 3223 DEPRECATED 3225 Please note that this options is deprecated. Section 8.1.31 should 3226 be used instead. 3228 Applications that wish to use the sendto() system call may wish to 3229 specify a default set of parameters that would normally be supplied 3230 through the inclusion of ancillary data. This socket option allows 3231 such an application to set the default sctp_sndrcvinfo structure. 3232 The application that wishes to use this socket option simply passes 3233 the sctp_sndrcvinfo structure defined in Section 5.3.2 to this call. 3234 The input parameters accepted by this call include sinfo_stream, 3235 sinfo_flags, sinfo_ppid, sinfo_context, and sinfo_timetolive. The 3236 sinfo_flags is composed of a bitwise OR of SCTP_UNORDERED, SCTP_EOF, 3237 and SCTP_SENDALL. The sinfo_assoc_id field specifies the association 3238 to apply the parameters to. For a one-to-many style socket any of 3239 the predefined constants are also allowed in this field. The field 3240 is ignored on the one-to-one style. 3242 8.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) - 3243 DEPRECATED 3245 This socket option is used to specify various notifications and 3246 ancillary data the user wishes to receive. Please see Section 6.2.1 3247 for a full description of this option and its usage. Note that this 3248 option is considered deprecated and present for backward 3249 compatibility. New applications should use the SCTP_EVENT option. 3250 See Section 6.2.2 for a full description of that option as well. 3252 8.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 3254 This socket option is a boolean flag which turns on or off the 3255 mapping of IPv4 addresses. If this option is turned on, then IPv4 3256 addresses will be mapped to V6 representation. If this option is 3257 turned off, then no mapping will be done of V4 addresses and a user 3258 will receive both PF_INET6 and PF_INET type addresses on the socket. 3259 See [RFC3542] for more details on mapped V6 addresses. 3261 If this socket option is used on a socket of type PF_INET an error is 3262 returned. 3264 By default this option is turned off and expects an integer to be 3265 passed where a non-zero value turns on the option and a zero value 3266 turns off the option. 3268 8.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 3270 This option will get or set the maximum size to put in any outgoing 3271 SCTP DATA chunk. If a message is larger than this size it will be 3272 fragmented by SCTP into the specified size. Note that the underlying 3273 SCTP implementation may fragment into smaller sized chunks when the 3274 PMTU of the underlying association is smaller than the value set by 3275 the user. The default value for this option is '0' which indicates 3276 the user is not limiting fragmentation and only the PMTU will affect 3277 SCTP's choice of DATA chunk size. Note also that values set larger 3278 than the maximum size of an IP datagram will effectively let SCTP 3279 control fragmentation (i.e. the same as setting this option to 0). 3281 The following structure is used to access and modify this parameter: 3283 struct sctp_assoc_value { 3284 sctp_assoc_t assoc_id; 3285 uint32_t assoc_value; 3286 }; 3288 assoc_id: This parameter is ignored for one-to-one style sockets. 3289 For one-to-many style sockets this parameter indicates which 3290 association the user is performing an action upon. It is an error 3291 to use SCTP_{CURRENT|ALL}_ASSOC in assoc_id. 3293 assoc_value: This parameter specifies the maximum size in bytes. 3295 8.1.17. Get or Set the List of Supported HMAC Identifiers 3296 (SCTP_HMAC_IDENT) 3298 This option gets or sets the list of HMAC algorithms that the local 3299 endpoint requires the peer to use. 3301 The following structure is used to get or set these identifiers: 3303 struct sctp_hmacalgo { 3304 uint32_t shmac_number_of_idents; 3305 uint16_t shmac_idents[]; 3306 }; 3308 shmac_number_of_idents: This field gives the number of elements 3309 present in the array shmac_idents. 3311 shmac_idents: This parameter contains an array of HMAC identifiers 3312 that the local endpoint is requesting the peer to use, in priority 3313 order. The following identifiers are valid: 3315 * SCTP_AUTH_HMAC_ID_SHA1 3317 * SCTP_AUTH_HMAC_ID_SHA256 3319 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 3320 may include any of the other values in its preferred order (lowest 3321 list position has the highest preference in algorithm selection). 3322 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 3323 of an unknown HMAC identifier (including optional identifiers unknown 3324 to the implementation) will cause the set option to fail and return 3325 an error. 3327 8.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 3329 This option will get or set the active shared key to be used to build 3330 the association shared key. 3332 The following structure is used to access and modify these 3333 parameters: 3335 struct sctp_authkeyid { 3336 sctp_assoc_t scact_assoc_id; 3337 uint16_t scact_keynumber; 3338 }; 3340 scact_assoc_id: This parameter sets the active key of the specified 3341 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 3342 used. For one-to-one sockets, this parameter is ignored. Note, 3343 however, that this option will set the active key on the 3344 association if the socket is connected, otherwise this will set 3345 the default active key for the endpoint. 3347 scact_keynumber: This parameter is the shared key identifier which 3348 the application is requesting to become the active shared key to 3349 be used for sending authenticated chunks. The key identifier must 3350 correspond to an existing shared key. Note that shared key 3351 identifier '0' defaults to a null key. 3353 When used with setsockopt() the SCTP implementation must use the 3354 indicated shared key identifier for all messages being given to an 3355 SCTP implementation via a send call after the setsockopt() call until 3356 changed again. Therefore, the SCTP implementation must not bundle 3357 user messages which should be authenticated using different shared 3358 key identifiers. 3360 Initially the key with key identifier 0 is the active key. 3362 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 3364 This option will affect the way delayed sacks are performed. This 3365 option allows the application to get or set the delayed sack time, in 3366 milliseconds. It also allows changing the delayed sack frequency. 3367 Changing the frequency to 1 disables the delayed sack algorithm. 3368 Note that if sack_delay or sack_freq are 0 when setting this option, 3369 the current values will remain unchanged. 3371 The following structure is used to access and modify these 3372 parameters: 3374 struct sctp_sack_info { 3375 sctp_assoc_t sack_assoc_id; 3376 uint32_t sack_delay; 3377 uint32_t sack_freq; 3378 }; 3380 sack_assoc_id: This parameter is ignored for one-to-one style 3381 sockets. For one-to-many style sockets this parameter indicates 3382 which association the user is performing an action upon. The 3383 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3385 sack_delay: This parameter contains the number of milliseconds that 3386 the user is requesting the delayed SACK timer to be set to. Note 3387 that this value is defined in the standard to be between 200 and 3388 500 milliseconds. 3390 sack_freq: This parameter contains the number of packets that must 3391 be received before a sack is sent without waiting for the delay 3392 timer to expire. The default value is 2, setting this value to 1 3393 will disable the delayed sack algorithm. 3395 8.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 3397 Fragmented interleave controls how the presentation of messages 3398 occurs for the message receiver. There are three levels of fragment 3399 interleave defined. Two of the levels affect the one-to-one model, 3400 while the one-to-many model is affected by all three levels. 3402 This option takes an integer value. It can be set to a value of 0, 1 3403 or 2. Attempting to set this level to other values will return an 3404 error. 3406 Setting the three levels provides the following receiver 3407 interactions: 3409 level 0: Prevents the interleaving of any messages. This means that 3410 when a partial delivery begins, no other messages will be received 3411 except the message being partially delivered. If another message 3412 arrives on a different stream (or association) that could be 3413 delivered, it will be blocked waiting for the user to read all of 3414 the partially delivered message. 3416 level 1: Allows interleaving of messages that are from different 3417 associations. For the one-to-one model, level 0 and level 1 thus 3418 have the same meaning since a one-to-one socket always receives 3419 messages from the same association. Note that setting the one-to- 3420 many model to this level may cause multiple partial deliveries 3421 from different associations but for any given association, only 3422 one message will be delivered until all parts of a message have 3423 been delivered. This means that one large message, being read 3424 with an association identifier of "X", will block other messages 3425 from association "X" from being delivered. 3427 level 2: Allows complete interleaving of messages. This level 3428 requires that the sender carefully observes not only the peer 3429 association identifier (or address) but must also pay careful 3430 attention to the stream number. With this option enabled a 3431 partially delivered message may begin being delivered for 3432 association "X" stream "Y" and the next subsequent receive may 3433 return a message from association "X" stream "Z". Note that no 3434 other messages would be delivered for association "X" stream "Y" 3435 until all of stream "Y"'s partially delivered message was read. 3436 Note that this option also affects the one-to-one model. Also 3437 note that for the one-to-many model not only another stream's 3438 message from the same association may be delivered upon the next 3439 receive, some other association's message may be delivered upon 3440 the next receive. 3442 An implementation should default the one-to-many model to level 1. 3444 The reason for this is that otherwise it is possible that a peer 3445 could begin sending a partial message and thus block all other peers 3446 from sending data. However a setting of level 2 requires the 3447 application to not only be aware of the association (via the 3448 association identifier or peer's address) but also the stream number. 3449 The stream number is not present unless the user has subscribed to 3450 the sctp_data_io_event (see Section 6.2). This is also why we 3451 recommend that the one-to-one model be defaulted to level 0 (level 1 3452 for the one-to-one model has no effect). Note that an implementation 3453 should return an error if an application attempts to set the level to 3454 2 and has not subscribed to the sctp_data_io_event. 3456 For applications that have subscribed to events, those events appear 3457 in the normal socket buffer data stream. This means that unless the 3458 user has set the fragmentation interleave level to 0, notifications 3459 may also be interleaved with partially delivered messages. 3461 8.1.21. Set or Get the SCTP Partial Delivery Point 3462 (SCTP_PARTIAL_DELIVERY_POINT) 3464 This option will set or get the SCTP partial delivery point. This 3465 point is the size of a message where the partial delivery API will be 3466 invoked to help free up rwnd space for the peer. Setting this to a 3467 lower value will cause partial deliveries to happen more often. This 3468 option expects an integer that sets or gets the partial delivery 3469 point in bytes. Note also that the call will fail if the user 3470 attempts to set this value larger than the socket receive buffer 3471 size. 3473 Note that any single message having a length smaller than or equal to 3474 the SCTP partial delivery point will be delivered in one single read 3475 call as long as the user provided buffer is large enough to hold the 3476 message. 3478 8.1.22. Set or Get the Use of Extended Receive Info 3479 (SCTP_USE_EXT_RCVINFO) - DEPRECATED 3481 This option will enable or disable the use of the extended version of 3482 the sctp_sndrcvinfo structure. If this option is disabled, then the 3483 normal sctp_sndrcvinfo structure is returned in all receive message 3484 calls. If this option is enabled then the sctp_extrcvinfo structure 3485 is returned in all receive message calls. The default is off. 3487 Note that the sctp_extrcvinfo structure is never used in any send 3488 call. 3490 This option is present for compatibility with older applications and 3491 is deprecated. Future applications should use SCTP_NXTINFO to 3492 retrieve this same information via ancillary data. 3494 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 3496 This option will enable or disable the use of the automatic 3497 generation of ASCONF chunks to add and delete addresses to an 3498 existing association. Note that this option has two caveats namely: 3499 a) it only affects sockets that are bound to all addresses available 3500 to the SCTP stack, and b) the system administrator may have an 3501 overriding control that turns the ASCONF feature off no matter what 3502 setting the socket option may have. 3504 This option expects an integer boolean flag, where a non-zero value 3505 turns on the option, and a zero value turns off the option. 3507 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 3509 This option will allow a user to change the maximum burst of packets 3510 that can be emitted by this association. Note that the default value 3511 is 4, and some implementations may restrict this setting so that it 3512 can only be lowered to positive values. 3514 To set or get this option the user fills in the following structure: 3516 struct sctp_assoc_value { 3517 sctp_assoc_t assoc_id; 3518 uint32_t assoc_value; 3519 }; 3521 assoc_id: This parameter is ignored for one-to-one style sockets. 3522 For one-to-many style sockets this parameter indicates which 3523 association the user is performing an action upon. The special 3524 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3526 assoc_value: This parameter contains the maximum burst. Setting the 3527 value to 0 disables burst mitigation. 3529 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) 3531 The context field in the sctp_sndrcvinfo structure is normally only 3532 used when a failed message is retrieved holding the value that was 3533 sent down on the actual send call. This option allows the setting of 3534 a default context on an association basis that will be received on 3535 reading messages from the peer. This is especially helpful in the 3536 one-to-many model for an application to keep some reference to an 3537 internal state machine that is processing messages on the 3538 association. Note that the setting of this value only affects 3539 received messages from the peer and does not affect the value that is 3540 saved with outbound messages. 3542 To set or get this option the user fills in the following structure: 3544 struct sctp_assoc_value { 3545 sctp_assoc_t assoc_id; 3546 uint32_t assoc_value; 3547 }; 3549 assoc_id: This parameter is ignored for one-to-one style sockets. 3550 For one-to-many style sockets this parameter indicates which 3551 association the user is performing an action upon. The special 3552 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3554 assoc_value: This parameter contains the context. 3556 8.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 3558 This boolean flag is used to enable or disable explicit end of record 3559 (EOR) marking. When this option is enabled, a user may make multiple 3560 send system calls to send a record and must indicate that they are 3561 finished sending a particular record by including the SCTP_EOR flag. 3562 If this boolean flag is disabled then each individual send system 3563 call is considered to have an SCTP_EOR indicator set on it implicitly 3564 without the user having to explicitly add this flag. The default is 3565 off. 3567 This option expects an integer boolean flag, where a non-zero value 3568 turns on the option, and a zero value turns off the option. 3570 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 3572 This option only supports one-to-one style SCTP sockets. If used on 3573 a one-to-many style SCTP socket an error is indicated. 3575 This option expects an integer boolean flag, where a non-zero value 3576 turns on the option, and a zero value turns off the option. 3578 This socket option must not be used after calling bind() or 3579 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 3580 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3581 SCTP sockets bound to the same port must have set the 3582 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3583 having set the SCTP_REUSE_PORT option will fail if there are other 3584 sockets bound to the same port. At most one socket being bound to 3585 the same port may be listening. 3587 It should be noted that the behavior of the socket level socket 3588 option to reuse ports and/or addresses for SCTP sockets is 3589 unspecified. 3591 8.1.28. Set Notification Event (SCTP_EVENT) 3593 This socket option is used to set a specific notification option. 3594 Please see Section 6.2.2 for a full description of this option and 3595 its usage. 3597 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary 3598 Data (SCTP_RECVRCVINFO) 3600 Setting this option specifies that SCTP_RCVINFO defined in 3601 Section 5.3.5 is returned as ancillary data by recvmsg(). 3603 This option expects an integer boolean flag, where a non-zero value 3604 turns on the option, and a zero value turns off the option. 3606 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary 3607 Data (SCTP_RECVNXTINFO) 3609 Setting this option specifies that SCTP_NXTINFO defined in 3610 Section 5.3.6 is returned as ancillary data by recvmsg(). 3612 This option expects an integer boolean flag, where a non-zero value 3613 turns on the option, and a zero value turns off the option. 3615 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) 3617 Applications that wish to use the sendto() system call may wish to 3618 specify a default set of parameters that would normally be supplied 3619 through the inclusion of ancillary data. This socket option allows 3620 such an application to set the default sctp_sndinfo structure. The 3621 application that wishes to use this socket option simply passes the 3622 sctp_sndinfo structure defined in Section 5.3.4 to this call. The 3623 input parameters accepted by this call include snd_sid, snd_flags, 3624 snd_ppid, snd_context. The snd_flags is composed of a bitwise OR of 3625 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The snd_assoc_id field 3626 specifies the association to apply the parameters to. For a one-to- 3627 many style socket any of the predefined constants are also allowed in 3628 this field. The field is ignored on the one-to-one style. 3630 8.2. Read-Only Options 3632 The options defined in this subsection are read-only. Using this 3633 option in a setsockopt() call will result in an error indicating 3634 EOPNOTSUPP. 3636 8.2.1. Association Status (SCTP_STATUS) 3638 Applications can retrieve current status information about an 3639 association, including association state, peer receiver window size, 3640 number of unacked data chunks, and number of data chunks pending 3641 receipt. This information is read-only. 3643 The following structure is used to access this information: 3645 struct sctp_status { 3646 sctp_assoc_t sstat_assoc_id; 3647 int32_t sstat_state; 3648 uint32_t sstat_rwnd; 3649 uint16_t sstat_unackdata; 3650 uint16_t sstat_penddata; 3651 uint16_t sstat_instrms; 3652 uint16_t sstat_outstrms; 3653 uint32_t sstat_fragmentation_point; 3654 struct sctp_paddrinfo sstat_primary; 3655 }; 3657 sstat_assoc_id: This parameter is ignored for one-to-one style 3658 sockets. For one-to-many style sockets it holds the identifier 3659 for the association. All notifications for a given association 3660 have the same association identifier. The special SCTP_{FUTURE| 3661 CURRENT|ALL}_ASSOC cannot be used. 3663 sstat_state: This contains the association's current state, i.e. one 3664 of the following values: 3666 * SCTP_CLOSED 3668 * SCTP_BOUND 3670 * SCTP_LISTEN 3672 * SCTP_COOKIE_WAIT 3674 * SCTP_COOKIE_ECHOED 3676 * SCTP_ESTABLISHED 3678 * SCTP_SHUTDOWN_PENDING 3680 * SCTP_SHUTDOWN_SENT 3682 * SCTP_SHUTDOWN_RECEIVED 3683 * SCTP_SHUTDOWN_ACK_SENT 3685 sstat_rwnd: This contains the association peer's current receiver 3686 window size. 3688 sstat_unackdata: This is the number of unacked data chunks. 3690 sstat_penddata: This is the number of data chunks pending receipt. 3692 sstat_instrms: The number of streams that the peer will be using 3693 outbound. 3695 sstat_outstrms: The number of streams that the endpoint is allowed 3696 to use outbound. 3698 sstat_fragmentation_point: The size at which SCTP fragmentation will 3699 occur. 3701 sstat_primary: This is information on the current primary peer 3702 address. 3704 To access these status values, the application calls getsockopt() 3705 with the option name SCTP_STATUS. 3707 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3709 Applications can retrieve information about a specific peer address 3710 of an association, including its reachability state, congestion 3711 window, and retransmission timer values. This information is read- 3712 only. 3714 The following structure is used to access this information: 3716 struct sctp_paddrinfo { 3717 sctp_assoc_t spinfo_assoc_id; 3718 struct sockaddr_storage spinfo_address; 3719 int32_t spinfo_state; 3720 uint32_t spinfo_cwnd; 3721 uint32_t spinfo_srtt; 3722 uint32_t spinfo_rto; 3723 uint32_t spinfo_mtu; 3724 }; 3726 spinfo_assoc_id: This parameter is ignored for one-to-one style 3727 sockets. For one-to-many style sockets the following applies: 3728 This field may be filled by the application, if so, this field 3729 will have priority in looking up the association instead of using 3730 the address specified in spinfo_address. Note that if the address 3731 does not belong to the association specified then this call will 3732 fail. If the application does not fill in the spinfo_assoc_id, 3733 then the address will be used to lookup the association and on 3734 return this field will have the valid association identifier. In 3735 other words, this call can be used to translate an address into an 3736 association identifier. Note that the predefined constants are 3737 not allowed on this option. 3739 spinfo_address: This is filled by the application, and contains the 3740 peer address of interest. 3742 spinfo_state: This contains the peer address' state: 3744 SCTP_UNCONFIRMED: The initial state of a peer address. 3746 SCTP_ACTIVE: The state is entered the first time after path 3747 verification. It can also be entered if the state is 3748 SCTP_INACTIVE and the path supervision detects that the peer 3749 address is reachable again. 3751 SCTP_INACTIVE: This state is entered whenever a path failure is 3752 detected. 3754 spinfo_cwnd: This contains the peer address' current congestion 3755 window. 3757 spinfo_srtt: This contains the peer address' current smoothed round- 3758 trip time calculation in milliseconds. 3760 spinfo_rto: This contains the peer address' current retransmission 3761 timeout value in milliseconds. 3763 spinfo_mtu: The current path MTU of the peer address. It is the 3764 number of bytes available in an SCTP packet for chunks. 3766 8.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3767 (SCTP_PEER_AUTH_CHUNKS) 3769 This option gets a list of chunk types (see [RFC4960]) for a 3770 specified association that the peer requires to be received 3771 authenticated only. 3773 The following structure is used to access these parameters: 3775 struct sctp_authchunks { 3776 sctp_assoc_t gauth_assoc_id; 3777 uint32_t gauth_number_of_chunks 3778 uint8_t gauth_chunks[]; 3780 }; 3782 gauth_assoc_id: This parameter indicates for which association the 3783 user is requesting the list of peer authenticated chunks. For 3784 one-to-one sockets, this parameter is ignored. Note that the 3785 predefined constants are not allowed with this option. 3787 gauth_number_of_chunks: This parameter gives the number of elements 3788 in the array gauth_chunks. 3790 gauth_chunks: This parameter contains an array of chunk types that 3791 the peer is requesting to be authenticated. If the passed in 3792 buffer size is not large enough to hold the list of chunk types, 3793 ENOBUFS is returned. 3795 8.2.4. Get the List of Chunks the Local Endpoint Requires to be 3796 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3798 This option gets a list of chunk types (see [RFC4960]) for a 3799 specified association that the local endpoint requires to be received 3800 authenticated only. 3802 The following structure is used to access these parameters: 3804 struct sctp_authchunks { 3805 sctp_assoc_t gauth_assoc_id; 3806 uint32_t gauth_number_of_chunks; 3807 uint8_t gauth_chunks[]; 3808 }; 3810 gauth_assoc_id: This parameter indicates for which association the 3811 user is requesting the list of local authenticated chunks. For 3812 one-to-one sockets, this parameter is ignored. 3814 gauth_number_of_chunks: This parameter gives the number of elements 3815 in the array gauth_chunks. 3817 gauth_chunks: This parameter contains an array of chunk types that 3818 the local endpoint is requesting to be authenticated. If the 3819 passed in buffer is not large enough to hold the list of chunk 3820 types, ENOBUFS is returned. 3822 8.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3824 This option gets the current number of associations that are attached 3825 to a one-to-many style socket. The option value is an uint32_t. 3826 Note that this number is only a snap shot. This means that the 3827 number of associations may have changed when the caller gets back the 3828 option result. 3830 For a one-to-one style socket, this socket option results in an 3831 error. 3833 8.2.6. Get the Current Identifiers of Associations 3834 (SCTP_GET_ASSOC_ID_LIST) 3836 This option gets the current list of SCTP association identifiers of 3837 the SCTP associations handled by a one-to-many style socket. 3839 The option value has the structure 3841 struct sctp_assoc_ids { 3842 uint32_t gaids_number_of_ids; 3843 sctp_assoc_t gaids_assoc_id[]; 3844 }; 3846 The caller must provide a large enough buffer to hold all association 3847 identifiers. If the buffer is too small, an error must be returned. 3848 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3849 idea how large the buffer has to be. gaids_number_of_ids gives the 3850 number of elements in the array gaids_assoc_id. Note also that some 3851 or all of sctp_assoc_t returned in the array may become invalid by 3852 the time the caller gets back the result. 3854 For a one-to-one style socket, this socket option results in an 3855 error. 3857 8.3. Write-Only Options 3859 The options defined in this subsection are write-only. Using this 3860 option in a getsockopt() or sctp_opt_info() call will result in an 3861 error indicating EOPNOTSUPP. 3863 8.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3865 Requests that the peer marks the enclosed address as the association 3866 primary (see [RFC5061]). The enclosed address must be one of the 3867 association's locally bound addresses. 3869 The following structure is used to make a set peer primary request: 3871 struct sctp_setpeerprim { 3872 sctp_assoc_t sspp_assoc_id; 3873 struct sockaddr_storage sspp_addr; 3874 }; 3875 sspp_assoc_id: This parameter is ignored for one-to-one style 3876 sockets. For one-to-many style sockets it identifies the 3877 association for this request. Note that the predefined constants 3878 are not allowed on this option. 3880 sspp_addr: The address to set as primary. 3882 8.3.2. Add a Chunk that must be Authenticated (SCTP_AUTH_CHUNK) 3884 This set option adds a chunk type that the user is requesting to be 3885 received only in an authenticated way. Changes to the list of chunks 3886 will only affect future associations on the socket. 3888 The following structure is used to add a chunk: 3890 struct sctp_authchunk { 3891 uint8_t sauth_chunk; 3892 }; 3894 sauth_chunk: This parameter contains a chunk type that the user is 3895 requesting to be authenticated. 3897 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3898 chunks must not be used. If they are used, an error must be 3899 returned. The usage of this option enables SCTP AUTH in cases where 3900 it is not required by other means (for example the use of dynamic 3901 address reconfiguration). 3903 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3905 This option will set a shared secret key that is used to build an 3906 association shared key. 3908 The following structure is used to access and modify these 3909 parameters: 3911 struct sctp_authkey { 3912 sctp_assoc_t sca_assoc_id; 3913 uint16_t sca_keynumber; 3914 uint16_t sca_keylength; 3915 uint8_t sca_key[]; 3916 }; 3918 sca_assoc_id: This parameter indicates what association the shared 3919 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3920 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3921 ignored. Note, however on one to one sockets, that this option 3922 will set a key on the association if the socket is connected, 3923 otherwise this will set a key on the endpoint. 3925 sca_keynumber: This parameter is the shared key identifier by which 3926 the application will refer to this shared key. If a key of the 3927 specified index already exists, then this new key will replace the 3928 old existing key. Note that shared key identifier '0' defaults to 3929 a null key. 3931 sca_keylength: This parameter is the length of the array sca_key. 3933 sca_key: This parameter contains an array of bytes that is to be 3934 used by the endpoint (or association) as the shared secret key. 3935 Note, if the length of this field is zero, a null key is set. 3937 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3939 This set option indicates that the application will no longer send 3940 user messages using the indicated key identifier. 3942 struct sctp_authkeyid { 3943 sctp_assoc_t scact_assoc_id; 3944 uint16_t scact_keynumber; 3945 }; 3947 scact_assoc_id: This parameter indicates which association the 3948 shared key identifier is being deleted from. The special 3949 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3950 sockets, this parameter is ignored. Note, however, that this 3951 option will deactivate the key from the association if the socket 3952 is connected, otherwise this will deactivate the key from the 3953 endpoint. 3955 scact_keynumber: This parameter is the shared key identifier which 3956 the application is requesting to be deactivated. The key 3957 identifier must correspond to an existing shared key. Note if 3958 this parameter is zero, use of the null key identifier '0' is 3959 deactivated on the endpoint and/or association. 3961 The currently active key cannot be deactivated. 3963 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3965 This set option will delete a shared secret key which has been 3966 deactivated of an SCTP association. 3968 struct sctp_authkeyid { 3969 sctp_assoc_t scact_assoc_id; 3970 uint16_t scact_keynumber; 3972 }; 3974 scact_assoc_id: This parameter indicates which association the 3975 shared key identifier is being deleted from. The special 3976 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3977 sockets, this parameter is ignored. Note, however, that this 3978 option will delete the key from the association if the socket is 3979 connected, otherwise this will delete the key from the endpoint. 3981 scact_keynumber: This parameter is the shared key identifier which 3982 the application is requesting to be deleted. The key identifier 3983 must correspond to an existing shared key and must not be in use 3984 for any packet being sent by the SCTP implementation. This means 3985 in particular, that it must be deactivated first. Note if this 3986 parameter is zero, use of the null key identifier '0' is deleted 3987 from the endpoint and/or association. 3989 Only deactivated keys that are no longer used by an association can 3990 be deleted. 3992 9. New Functions 3994 Depending on the system, the following interface can be implemented 3995 as a system call or library function. 3997 9.1. sctp_bindx() 3999 This function allows the user to bind a specific subset of addresses 4000 or, if the SCTP extension described in [RFC5061] is supported, add or 4001 delete specific addresses. 4003 The function prototype is 4005 int sctp_bindx(int sd, 4006 struct sockaddr *addrs, 4007 int addrcnt, 4008 int flags); 4010 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 4011 If the sd is an IPv6 socket, the addresses passed can either be IPv4 4012 or IPv6 addresses. 4014 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 4015 Section 3.1.2 for this usage. 4017 addrs is a pointer to an array of one or more socket addresses. Each 4018 address is contained in its appropriate structure. For an IPv6 4019 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 4020 array of sockaddr_in is used. The caller specifies the number of 4021 addresses in the array with addrcnt. Note that the wildcard 4022 addresses cannot be used in combination with non wildcard addresses 4023 on a socket with this function, doing so will result in an error. 4025 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 4026 -1 and sets errno to the appropriate error code. 4028 For SCTP, the port given in each socket address must be the same, or 4029 sctp_bindx() will fail, setting errno to EINVAL. 4031 The flags parameter is formed from the bitwise OR of zero or more of 4032 the following currently defined flags: 4034 o SCTP_BINDX_ADD_ADDR 4036 o SCTP_BINDX_REM_ADDR 4038 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 4039 socket (i.e. endpoint), and SCTP_BINDX_REM_ADDR directs SCTP to 4040 remove the given addresses from the socket. The two flags are 4041 mutually exclusive; if both are given, sctp_bindx() will fail with 4042 EINVAL. A caller may not remove all addresses from a socket; 4043 sctp_bindx() will reject such an attempt with EINVAL. 4045 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 4046 additional addresses with an endpoint after calling bind(). Or use 4047 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 4048 socket is associated with, so that no new association accepted will 4049 be associated with these addresses. If the endpoint supports dynamic 4050 address reconfiguration, an SCTP_BINDX_REM_ADDR or 4051 SCTP_BINDX_ADD_ADDR may cause an endpoint to send the appropriate 4052 message to its peers to change the peers' address lists. 4054 Adding and removing addresses from established associations is an 4055 optional functionality. Implementations that do not support this 4056 functionality should return -1 and set errno to EOPNOTSUPP. 4058 sctp_bindx() can be called on an already bound socket or on an 4059 unbound socket. If the socket is unbound and the first port number 4060 in the addrs is zero, the kernel will choose a port number. All port 4061 numbers after the first one being 0 must also be zero. If the first 4062 port number is not zero, the following port numbers must be zero or 4063 have the same value as the first one. For an already bound socket, 4064 all port numbers provided must be the bound one or 0. 4066 sctp_bindx() is an atomic operation. Therefore, the binding will be 4067 either successful on all addresses or fail on all addresses. If 4068 multiple addresses are provided and the sctp_bindx() call fails there 4069 is no indication which address is responsible for the failure. The 4070 only way to identify the specific error indication is to call 4071 sctp_bindx() sequentially with only one address per call. 4073 9.2. sctp_peeloff() 4075 After an association is established on a one-to-many style socket, 4076 the application may wish to branch off the association into a 4077 separate socket/file descriptor. 4079 This is particularly desirable when, for instance, the application 4080 wishes to have a number of sporadic message senders/receivers remain 4081 under the original one-to-many style socket, but branch off these 4082 associations carrying high volume data traffic into their own 4083 separate socket descriptors. 4085 The application uses the sctp_peeloff() call to branch off an 4086 association into a separate socket (Note the semantics are somewhat 4087 changed from the traditional one-to-one style accept() call). Note 4088 that the new socket is a one-to-one style socket. Thus it will be 4089 confined to operations allowed for a one-to-one style socket. 4091 The function prototype is 4093 int sctp_peeloff(int sd, 4094 sctp_assoc_t assoc_id); 4096 and the arguments are 4098 sd: The original one-to-many style socket descriptor returned from 4099 the socket() system call (see Section 3.1.1). 4101 assoc_id: the specified identifier of the association that is to be 4102 branched off to a separate file descriptor (Note, in a traditional 4103 one-to-one style accept() call, this would be an out parameter, 4104 but for the one-to-many style call, this is an in parameter). 4106 The function returns a non-negative file descriptor representing the 4107 branched-off association, or -1 if an error occurred. The variable 4108 errno is then set appropriately. 4110 9.3. sctp_getpaddrs() 4112 sctp_getpaddrs() returns all peer addresses in an association. 4114 The function prototype is: 4116 int sctp_getpaddrs(int sd, 4117 sctp_assoc_t id, 4118 struct sockaddr **addrs); 4120 On return, addrs will point to a dynamically allocated array of 4121 sockaddr structures of the appropriate type for the socket type. The 4122 caller should use sctp_freepaddrs() to free the memory. Note that 4123 the in/out parameter addrs must not be NULL. 4125 If sd is an IPv4 socket, the addresses returned will be all IPv4 4126 addresses. If sd is an IPv6 socket, the addresses returned can be a 4127 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4128 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4130 For one-to-many style sockets, id specifies the association to query. 4131 For one-to-one style sockets, id is ignored. 4133 On success, sctp_getpaddrs() returns the number of peer addresses in 4134 the association. If there is no association on this socket, 4135 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 4136 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 4137 is undefined. 4139 9.4. sctp_freepaddrs() 4141 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 4143 The function prototype is 4145 void sctp_freepaddrs(struct sockaddr *addrs); 4147 and addrs is the array of peer addresses returned by 4148 sctp_getpaddrs(). 4150 9.5. sctp_getladdrs() 4152 sctp_getladdrs() returns all locally bound address(es) on a socket. 4154 The function prototype is 4156 int sctp_getladdrs(int sd, 4157 sctp_assoc_t id, 4158 struct sockaddr **addrs); 4160 On return, addrs will point to a dynamically allocated array of 4161 sockaddr structures of the appropriate type for the socket type. The 4162 caller should use sctp_freeladdrs() to free the memory. Note that 4163 the in/out parameter addrs must not be NULL. 4165 If sd is an IPv4 socket, the addresses returned will be all IPv4 4166 addresses. If sd is an IPv6 socket, the addresses returned can be a 4167 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4168 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4170 For one-to-many style sockets, id specifies the association to query. 4171 For one-to-one style sockets, id is ignored. 4173 If the id field is set to the value '0' then the locally bound 4174 addresses are returned without regard to any particular association. 4176 On success, sctp_getladdrs() returns the number of local addresses 4177 bound to the socket. If the socket is unbound, sctp_getladdrs() 4178 returns 0, and the value of *addrs is undefined. If an error occurs, 4179 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 4181 9.6. sctp_freeladdrs() 4183 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 4185 The function prototype is 4187 void sctp_freeladdrs(struct sockaddr *addrs); 4189 and addrs is the array of local addresses returned by 4190 sctp_getladdrs(). 4192 9.7. sctp_sendmsg() - DEPRECATED 4194 This function is deprecated, sctp_sendv() (see Section 9.12) should 4195 be used instead. 4197 An implementation may provide a library function (or possibly system 4198 call) to assist the user with the advanced features of SCTP. 4200 The function prototype is 4202 ssize_t sctp_sendmsg(int sd, 4203 const void *msg, 4204 size_t len, 4205 const struct sockaddr *to, 4206 socklen_t tolen, 4207 uint32_t ppid, 4208 uint32_t flags, 4209 uint16_t stream_no, 4210 uint32_t timetolive, 4211 uint32_t context); 4213 and the arguments are: 4215 sd: The socket descriptor. 4217 msg: The message to be sent. 4219 len: The length of the message. 4221 to: The destination address of the message. 4223 tolen: The length of the destination address. 4225 ppid: The same as sinfo_ppid (see Section 5.3.2). 4227 flags: The same as sinfo_flags (see Section 5.3.2). 4229 stream_no: The same as sinfo_stream (see Section 5.3.2). 4231 timetolive: The same as sinfo_timetolive (see Section 5.3.2). 4233 context: The same as sinfo_context (see Section 5.3.2). 4235 The call returns the number of characters sent, or -1 if an error 4236 occurred. The variable errno is then set appropriately. 4238 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 4239 marking is enabled on the socket specified by sd). 4241 Using sctp_sendmsg() on a non-connected one-to-one style socket for 4242 implicit connection setup may or may not work depending on the SCTP 4243 implementation. 4245 9.8. sctp_recvmsg() - DEPRECATED 4247 This function is deprecated, sctp_recvv() (see Section 9.13) should 4248 be used instead. 4250 An implementation may provide a library function (or possibly system 4251 call) to assist the user with the advanced features of SCTP. Note 4252 that in order for the sctp_sndrcvinfo structure to be filled in by 4253 sctp_recvmsg() the caller must enable the sctp_data_io_event with the 4254 SCTP_EVENTS option. Note that the setting of the 4255 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 4256 sctp_sndrcvinfo information to be extended. 4258 The function prototype is 4259 ssize_t sctp_recvmsg(int sd, 4260 void *msg, 4261 size_t len, 4262 struct sockaddr *from, 4263 socklen_t *fromlen 4264 struct sctp_sndrcvinfo *sinfo 4265 int *msg_flags); 4267 and the arguments are 4269 sd: The socket descriptor. 4271 msg: The message buffer to be filled. 4273 len: The length of the message buffer. 4275 from: A pointer to an address to be filled with the sender of this 4276 messages address. 4278 fromlen: An in/out parameter describing the from length. 4280 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 4281 receipt of the message. 4283 msg_flags: A pointer to an integer to be filled with any message 4284 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 4285 field. Options for the receive may also be passed into the value 4286 (e.g. MSG_PEEK). On return from the call, the msg_flags value 4287 will be different than what was sent in to the call. If 4288 implemented via a recvmsg() call, the msg_flags should only 4289 contain the value of the flags from the recvmsg() call. 4291 The call returns the number of bytes received, or -1 if an error 4292 occurred. The variable errno is then set appropriately. 4294 9.9. sctp_connectx() 4296 An implementation may provide a library function (or possibly system 4297 call) to assist the user with associating to an endpoint that is 4298 multi-homed. Much like sctp_bindx() this call allows a caller to 4299 specify multiple addresses at which a peer can be reached. The way 4300 the SCTP stack uses the list of addresses to set up the association 4301 is implementation dependent. This function only specifies that the 4302 stack will try to make use of all the addresses in the list when 4303 needed. 4305 Note that the list of addresses passed in is only used for setting up 4306 the association. It does not necessarily equal the set of addresses 4307 the peer uses for the resulting association. If the caller wants to 4308 find out the set of peer addresses, it must use sctp_getpaddrs() to 4309 retrieve them after the association has been set up. 4311 The function prototype is 4313 int sctp_connectx(int sd, 4314 struct sockaddr *addrs, 4315 int addrcnt, 4316 sctp_assoc_t *id); 4318 and the arguments are: 4320 sd: The socket descriptor. 4322 addrs: An array of addresses. 4324 addrcnt: The number of addresses in the array. 4326 id: An output parameter that if passed in as a non-NULL will return 4327 the association identifier for the newly created association (if 4328 successful). 4330 The call returns 0 on success or -1 if an error occurred. The 4331 variable errno is then set appropriately. 4333 9.10. sctp_send() - DEPRECATED 4335 This function is deprecated, sctp_sendv() should be used instead. 4337 An implementation may provide another alternative function or system 4338 call to assist an application with the sending of data without the 4339 use of the CMSG header structures. 4341 The function prototype is 4343 ssize_t sctp_send(int sd, 4344 const void *msg, 4345 size_t len, 4346 const struct sctp_sndrcvinfo *sinfo, 4347 int flags); 4349 and the arguments are 4351 sd: The socket descriptor. 4353 msg: The message to be sent. 4355 len: The length of the message. 4357 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4358 in Section 5.3.2 for a sendmsg() call. 4360 flags: The same flags as used by the sendmsg() call flags (e.g. 4361 MSG_DONTROUTE). 4363 The call returns the number of bytes sent, or -1 if an error 4364 occurred. The variable errno is then set appropriately. 4366 This function call may also be used to terminate an association using 4367 an association identifier by setting the sinfo.sinfo_flags to 4368 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4369 to be terminated. In such a case the len of the message can be zero. 4371 Using sctp_send() on a non-connected one-to-one style socket for 4372 implicit connection setup may or may not work depending on the SCTP 4373 implementation. 4375 Sending a message using sctp_send() is atomic unless explicit EOR 4376 marking is enabled on the socket specified by sd. 4378 9.11. sctp_sendx() - DEPRECATED 4380 This function is deprecated, sctp_sendv() should be used instead. 4382 An implementation may provide another alternative function or system 4383 call to assist an application with the sending of data without the 4384 use of the CMSG header structures that also gives a list of 4385 addresses. The list of addresses is provided for implicit 4386 association setup. In such a case the list of addresses serves the 4387 same purpose as the addresses given in sctp_connectx() (see 4388 Section 9.9). 4390 The function prototype is 4392 ssize_t sctp_sendx(int sd, 4393 const void *msg, 4394 size_t len, 4395 struct sockaddr *addrs, 4396 int addrcnt, 4397 struct sctp_sndrcvinfo *sinfo, 4398 int flags); 4400 and the arguments are: 4402 sd: The socket descriptor. 4404 msg: The message to be sent. 4406 len: The length of the message. 4408 addrs: Is an array of addresses. 4410 addrcnt: The number of addresses in the array. 4412 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4413 in Section 5.3.2 for a sendmsg() call. 4415 flags: The same flags as used by the sendmsg() call flags (e.g. 4416 MSG_DONTROUTE). 4418 The call returns the number of bytes sent, or -1 if an error 4419 occurred. The variable errno is then set appropriately. 4421 Note that in case of implicit connection setup, on return from this 4422 call the sinfo_assoc_id field of the sinfo structure will contain the 4423 new association identifier. 4425 This function call may also be used to terminate an association using 4426 an association identifier by setting the sinfo.sinfo_flags to 4427 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4428 to be terminated. In such a case the len of the message would be 4429 zero. 4431 Sending a message using sctp_sendx() is atomic unless explicit EOR 4432 marking is enabled on the socket specified by sd. 4434 Using sctp_sendx() on a non-connected one-to-one style socket for 4435 implicit connection setup may or may not work depending on the SCTP 4436 implementation. 4438 9.12. sctp_sendv() 4440 The function prototype is 4442 ssize_t sctp_sendv(int sd, 4443 const struct iovec *iov, 4444 int iovcnt, 4445 struct sockaddr *addrs, 4446 int addrcnt, 4447 void *info, 4448 socklen_t infolen, 4449 unsigned int infotype, 4450 int flags); 4452 The function sctp_sendv() provides an extensible way for an 4453 application to communicate different send attributes to the SCTP 4454 stack when sending a message. An implementation may provide 4455 sctp_sendv() as a library function or a system call. 4457 This document defines three types of attributes which can be used to 4458 describe a message to be sent. They are struct sctp_sndinfo 4459 (Section 5.3.4), struct sctp_prinfo (Section 5.3.7), and struct 4460 sctp_authinfo (Section 5.3.8). The following structure 4461 sctp_sendv_spa is defined to be used when more than one of the above 4462 attributes are needed to describe a message to be sent. 4464 struct sctp_sendv_spa { 4465 uint32_t sendv_flags; 4466 struct sctp_sndinfo sendv_sndinfo; 4467 struct sctp_prinfo sendv_prinfo; 4468 struct sctp_authinfo sendv_authinfo; 4469 }; 4471 The sendv_flags field holds a bit wise OR of SCTP_SEND_SNDINFO_VALID, 4472 SCTP_SEND_PRINFO_VALID and SCTP_SEND_AUTHINFO_VALID indicating if the 4473 sendv_sndinfo/sendv_prinfo/sendv_authinfo fields contain valid 4474 information. 4476 In future, when new send attributes are needed, new structures can be 4477 defined. But those new structures do not need to be based on any of 4478 the above defined structures. 4480 The function takes the following arguments: 4482 sd: The socket descriptor. 4484 iov: The gather buffer. The data in the buffer is treated as one 4485 single user message. 4487 iovcnt: The number of elements in iov. 4489 addrs: An array of addresses to be used to set up an association or 4490 one single address to be used to send the message. Pass in NULL 4491 if the caller does not want to set up an association nor want to 4492 send the message to a specific address. 4494 addrcnt: The number of addresses in the addrs array. 4496 info: A pointer to the buffer containing the attribute associated 4497 with the message to be sent. The type is indicated by info_type 4498 parameter. 4500 infolen: The length in bytes of info. 4502 infotype: Identifies the type of the information provided in info. 4503 The current defined values are: 4505 SCTP_SENDV_SNDINFO: The type of info is struct sctp_sndinfo. 4507 SCTP_SENDV_PRINFO: The type of info is struct sctp_prinfo. 4509 SCTP_SENDV_AUTHINFO: The type of info is struct sctp_authinfo. 4511 SCTP_SENDV_SPA: The type of info is struct sctp_sendv_spa. 4513 flags: The same flags as used by the sendmsg() call flags (e.g. 4514 MSG_DONTROUTE). 4516 The call returns the number of bytes sent, or -1 if an error 4517 occurred. The variable errno is then set appropriately. 4519 A note on one-to-many style socket. The struct sctp_sndinfo 4520 attribute must always be used in order to specify the association the 4521 message is to be sent on. The only case where it is not needed is 4522 when this call is used to set up a new association. 4524 The caller provides a list of addresses in the addrs parameter to set 4525 up an association. This function will behave like calling 4526 sctp_connectx() (see Section 9.9) first using the list of addresses 4527 and then calling sendmsg() with the given message and attributes. 4528 For an one-to-many style socket, if struct sctp_sndinfo attribute is 4529 provided, the snd_assoc_id field must be 0. When this function 4530 returns, the snd_assoc_id field will contain the association 4531 identifier of the newly established association. Note that struct 4532 sctp_sndinfo attribute is not required to set up an association for 4533 one-to-many style socket. If this attribute is not provided, the 4534 caller can enable the SCTP_ASSOC_CHANGE notification and use the 4535 SCTP_COMM_UP message to find out the association identifier. 4537 If the caller wants to send the message to a specific peer address 4538 (hence overriding the primary address), it can provide the specific 4539 address in the addrs parameter and provide a struct sctp_sndinfo 4540 attribute with the field snd_flags set to SCTP_ADDR_OVER. 4542 This function call may also be used to terminate an association. The 4543 caller provides an sctp_sndinfo attribute with the snd_flags set to 4544 SCTP_EOF. In this case the len of the message would be zero. 4546 Sending a message using sctp_sendv() is atomic unless explicit EOR 4547 marking is enabled on the socket specified by sd. 4549 9.13. sctp_recvv() 4551 The function prototype is 4553 ssize_t sctp_recvv(int sd, 4554 const struct iovec *iov, 4555 int iovlen, 4556 struct sockaddr *from, 4557 socklen_t *fromlen, 4558 void *info, 4559 socklen_t *infolen, 4560 unsigned int *infotype, 4561 int *flags); 4563 The function sctp_recvv() provides an extensible way for the SCTP 4564 stack to pass up different SCTP attributes associated with a received 4565 message to an application. An implementation may provide 4566 sctp_recvv() as a library function or as a system call. 4568 This document defines two types of attributes which can be returned 4569 by this call, the attribute of the received message and the attribute 4570 of the next message in receive buffer. The caller enables the 4571 SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these 4572 attributes respectively. Attributes of the received message are 4573 returned in struct sctp_rcvinfo (Section 5.3.5) and attributes of the 4574 next message are returned in struct sctp_nxtinfo (Section 5.3.6). If 4575 both options are enabled, both attributes are returned using the 4576 following structure. 4578 struct sctp_recvv_rn { 4579 struct sctp_rcvinfo recvv_rcvinfo; 4580 struct sctp_nxtinfo recvv_nxtinfo; 4581 }; 4583 In future, new structures can be defined to hold new types of 4584 attributes. The new structures do not need to be based on struct 4585 sctp_recvv_rn or struct sctp_rcvinfo. 4587 This function takes the following arguments: 4589 sd: The socket descriptor. 4591 iov: The scatter buffer. Only one user message is returned in this 4592 buffer. 4594 iovlen: The number of elements in iov. 4596 from: A pointer to an address to be filled with the sender of the 4597 received message's address. 4599 fromlen: An in/out parameter describing the from length. 4601 info: A pointer to the buffer to hold the attributes of the received 4602 message. The structure type of info is determined by the 4603 info_type parameter. 4605 infolen: An in/out parameter describing the size of the info buffer. 4607 infotype: In return, *info_type is set to the type of the info 4608 buffer. The current defined values are: 4610 SCTP_RECVV_NOINFO: If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO 4611 options are not enabled, no attribute will be returned. If 4612 only the SCTP_RECVNXTINFO option is enabled but there is no 4613 next message in the buffer, there will also no attribute be 4614 returned. In these cases *info_type will be set to 4615 SCTP_RECVV_NOINFO. 4617 SCTP_RECVV_RCVINFO: The type of info is struct sctp_rcvinfo and 4618 the attribute is about the received message. 4620 SCTP_RECVV_NXTINFO: The type of info is struct sctp_nxtinfo and 4621 the attribute is about the next message in receive buffer. 4622 This is the case when only the SCTP_RECVNXTINFO option is 4623 enabled and there is a next message in buffer. 4625 SCTP_RECVV_RN: The type of info is struct sctp_recvv_rn. The 4626 recvv_rcvinfo field is the attribute of the received message 4627 and the recvv_nxtinfo field is the attribute of the next 4628 message in buffer. This is the case when both SCTP_RECVRCVINFO 4629 and SCTP_RECVNXTINFO options are enabled and there is a next 4630 message in the receive buffer. 4632 flags: A pointer to an integer to be filled with any message flags 4633 (e.g. MSG_NOTIFICATION). Note that this field is an in/out 4634 parameter. Options for the receive may also be passed into the 4635 value (e.g. MSG_PEEK). On return from the call, the flags value 4636 will be different than what was sent in to the call. If 4637 implemented via a recvmsg() call, the flags should only contain 4638 the value of the flags from the recvmsg() call when calling 4639 sctp_recvv() and on return it has the value from msg_flags. 4641 The call returns the number of bytes received, or -1 if an error 4642 occurred. The variable errno is then set appropriately. 4644 10. IANA Considerations 4646 This document requires no actions from IANA. 4648 11. Security Considerations 4650 Many TCP and UDP implementations reserve port numbers below 1024 for 4651 privileged users. If the target platform supports privileged users, 4652 the SCTP implementation should restrict the ability to call bind() or 4653 sctp_bindx() on these port numbers to privileged users. 4655 Similarly unprivileged users should not be able to set protocol 4656 parameters that could result in the congestion control algorithm 4657 being more aggressive than permitted on the public Internet. These 4658 parameters are: 4660 o struct sctp_rtoinfo 4662 If an unprivileged user inherits a one-to-many style socket with open 4663 associations on a privileged port, it may be permitted to accept new 4664 associations, but it should not be permitted to open new 4665 associations. This could be relevant for the r* family of protocols. 4667 Applications using the one-to-many style sockets and using the 4668 interleave level if 0 are subject to denial of service attacks as 4669 described in Section 8.1.20. 4671 12. Acknowledgments 4673 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 4674 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 4675 early formation of this document. 4677 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, 4678 Martin Becke, Jon Berger, Mark Butler, Thomas Dreibholz, Scott 4679 Kimble, Renee Revis, Andreas Fink, Jonathan Leighton, Irene 4680 Ruengeler, and many others on the TSVWG mailing list for contributing 4681 valuable comments. 4683 A special thanks to Phillip Conrad, for his suggested text, quick and 4684 constructive insights, and most of all his persistent fighting to 4685 keep the interface to SCTP usable for the application programmer. 4687 13. References 4689 13.1. Normative References 4691 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 4692 Stevens, "Basic Socket Interface Extensions for IPv6", 4693 RFC 3493, February 2003. 4695 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4696 "Advanced Sockets Application Program Interface (API) for 4697 IPv6", RFC 3542, May 2003. 4699 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 4700 Conrad, "Stream Control Transmission Protocol (SCTP) 4701 Partial Reliability Extension", RFC 3758, May 2004. 4703 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 4704 "Authenticated Chunks for the Stream Control Transmission 4705 Protocol (SCTP)", RFC 4895, August 2007. 4707 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 4708 RFC 4960, September 2007. 4710 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 4711 Kozuka, "Stream Control Transmission Protocol (SCTP) 4712 Dynamic Address Reconfiguration", RFC 5061, 4713 September 2007. 4715 13.2. Informative References 4717 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4718 RFC 793, September 1981. 4720 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4721 August 1980. 4723 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 4724 Functional Specification", RFC 1644, July 1994. 4726 Appendix A. One-to-One Style Code Example 4728 The following code is an implementation of a simple client which 4729 sends a number of messages marked for unordered delivery to an echo 4730 server making use of all outgoing streams. The example shows how to 4731 use some features of one-to-one style IPv4 SCTP sockets, including: 4733 o Creating and connecting an SCTP socket. 4735 o Requesting to negotiate a number of outgoing streams. 4737 o Determining the negotiated number of outgoing streams. 4739 o Setting an adaptation layer indication. 4741 o Sending messages with a given payload protocol identifier on a 4742 particular stream using sctp_sendv(). 4744 #include 4745 #include 4746 #include 4747 #include 4748 #include 4749 #include 4750 #include 4751 #include 4752 #include 4754 #define PORT 9 4755 #define ADDR "127.0.0.1" 4756 #define SIZE_OF_MESSAGE 1000 4757 #define NUMBER_OF_MESSAGES 10 4758 #define PPID 1234 4760 int 4761 main(void) { 4762 unsigned int i; 4763 int sd; 4764 struct sockaddr_in addr; 4765 char buffer[SIZE_OF_MESSAGE]; 4766 struct iovec iov; 4767 struct sctp_status status; 4768 struct sctp_initmsg init; 4769 struct sctp_sndinfo info; 4770 struct sctp_setadaptation ind; 4771 socklen_t opt_len; 4773 /* Create a one-to-one style SCTP socket. */ 4774 if ((sd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) < 0) { 4775 perror("socket"); 4776 exit(1); 4777 } 4779 /* Prepare for requesting 2048 outgoing streams. */ 4780 memset(&init, 0, sizeof(init)); 4781 init.sinit_num_ostreams = 2048; 4782 if (setsockopt(sd, IPPROTO_SCTP, SCTP_INITMSG, 4783 &init, (socklen_t)sizeof(init)) < 0) { 4784 perror("setsockopt"); 4785 exit(1); 4786 } 4788 ind.ssb_adaptation_ind = 0x01020304; 4789 if (setsockopt(sd, IPPROTO_SCTP, SCTP_ADAPTATION_LAYER, 4790 &ind, (socklen_t)sizeof(ind)) < 0) { 4791 perror("setsockopt"); 4792 exit(1); 4793 } 4795 /* Connect to the discard server. */ 4796 memset(&addr, 0, sizeof(addr)); 4797 #ifdef HAVE_SIN_LEN 4798 addr.sin_len = sizeof(struct sockaddr_in); 4799 #endif 4800 addr.sin_family = AF_INET; 4801 addr.sin_port = htons(PORT); 4802 addr.sin_addr.s_addr = inet_addr(ADDR); 4803 if (connect(sd, 4804 (const struct sockaddr *)&addr, 4805 sizeof(struct sockaddr_in)) < 0) { 4806 perror("connect"); 4807 exit(1); 4808 } 4810 /* Get the actual number of outgoing streams. */ 4811 memset(&status, 0, sizeof(status)); 4812 opt_len = (socklen_t)sizeof(status); 4813 if (getsockopt(sd, IPPROTO_SCTP, SCTP_STATUS, 4814 &status, &opt_len) < 0) { 4815 perror("getsockopt"); 4816 exit(1); 4817 } 4819 memset(&info, 0, sizeof(info)); 4820 info.snd_ppid = htonl(PPID); 4821 info.snd_flags = SCTP_UNORDERED; 4822 memset(buffer, 'A', SIZE_OF_MESSAGE); 4823 iov.iov_base = buffer; 4824 iov.iov_len = SIZE_OF_MESSAGE; 4825 for (i = 0; i < NUMBER_OF_MESSAGES; i++) { 4826 info.snd_sid = i % status.sstat_outstrms; 4827 if (sctp_sendv(sd, 4828 (const struct iovec *)&iov, 1, 4829 NULL, 0, 4830 &info, sizeof(info), SCTP_SENDV_SNDINFO, 4831 0) < 0) { 4832 perror("sctp_sendv"); 4833 exit(1); 4834 } 4835 } 4837 if (close(sd) < 0) { 4838 perror("close"); 4839 exit(1); 4840 } 4841 return(0); 4842 } 4844 Appendix B. One-to-Many Style Code Example 4846 The following code is a simple implementation of a discard server 4847 over SCTP. The example shows how to use some features of one-to-many 4848 style IPv6 SCTP sockets, including: 4850 o Opening and binding of a socket. 4852 o Enabling notifications. 4854 o Handling notifications. 4856 o Configuring the auto close timer. 4858 o Using sctp_recvv() to receive messages. 4860 Please note that this server can be used in combination with the 4861 client described in Appendix A. 4863 #include 4864 #include 4865 #include 4866 #include 4867 #include 4868 #include 4869 #include 4870 #include 4871 #include 4873 #define BUFFER_SIZE (1<<16) 4874 #define PORT 9 4875 #define ADDR "0.0.0.0" 4876 #define TIMEOUT 5 4878 static void 4879 print_notification(void *buf) 4880 { 4881 struct sctp_assoc_change *sac; 4882 struct sctp_paddr_change *spc; 4883 struct sctp_adaptation_event *sad; 4884 union sctp_notification *snp; 4885 char addrbuf[INET6_ADDRSTRLEN]; 4886 const char *ap; 4887 struct sockaddr_in *sin; 4888 struct sockaddr_in6 *sin6; 4890 snp = buf; 4892 switch (snp->sn_header.sn_type) { 4893 case SCTP_ASSOC_CHANGE: 4894 sac = &snp->sn_assoc_change; 4895 printf("^^^ Association change: "); 4896 switch (sac->sac_state) { 4897 case SCTP_COMM_UP: 4898 printf("Communication up (streams (in/out)=(%u/%u)).\n", 4899 sac->sac_inbound_streams, sac->sac_outbound_streams); 4900 break; 4901 case SCTP_COMM_LOST: 4902 printf("Communication lost (error=%d).\n", sac->sac_error); 4903 break; 4904 case SCTP_RESTART: 4905 printf("Communication restarted (streams (in/out)=(%u/%u).\n", 4906 sac->sac_inbound_streams, sac->sac_outbound_streams); 4907 break; 4908 case SCTP_SHUTDOWN_COMP: 4909 printf("Communication completed.\n"); 4910 break; 4911 case SCTP_CANT_STR_ASSOC: 4912 printf("Communication couldn't be started.\n"); 4913 break; 4914 default: 4915 printf("Unknown state: %d.\n", sac->sac_state); 4916 break; 4917 } 4918 break; 4920 case SCTP_PEER_ADDR_CHANGE: 4921 spc = &snp->sn_paddr_change; 4922 if (spc->spc_aaddr.ss_family == AF_INET) { 4923 sin = (struct sockaddr_in *)&spc->spc_aaddr; 4924 ap = inet_ntop(AF_INET, &sin->sin_addr, 4925 addrbuf, INET6_ADDRSTRLEN); 4926 } else { 4927 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 4928 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 4929 addrbuf, INET6_ADDRSTRLEN); 4930 } 4931 printf("^^^ Peer Address change: %s ", ap); 4932 switch (spc->spc_state) { 4933 case SCTP_ADDR_AVAILABLE: 4934 printf("is available.\n"); 4935 break; 4936 case SCTP_ADDR_UNREACHABLE: 4937 printf("is not available (error=%d).\n", spc->spc_error); 4938 break; 4939 case SCTP_ADDR_REMOVED: 4940 printf("was removed.\n"); 4941 break; 4942 case SCTP_ADDR_ADDED: 4943 printf("was added.\n"); 4944 break; 4945 case SCTP_ADDR_MADE_PRIM: 4946 printf("is primary.\n"); 4947 break; 4948 default: 4949 printf("unknown state (%d).\n", spc->spc_state); 4950 break; 4951 } 4952 break; 4953 case SCTP_SHUTDOWN_EVENT: 4954 printf("^^^ Shutdown received.\n"); 4955 break; 4956 case SCTP_ADAPTATION_INDICATION: 4957 sad = &snp->sn_adaptation_event; 4958 printf("^^^ Adaptation indication 0x%08x received.\n", 4959 sad->sai_adaptation_ind); 4960 break; 4961 default: 4962 printf("^^^ Unknown event of type: %u.\n", 4963 snp->sn_header.sn_type); 4964 break; 4965 }; 4966 } 4967 int 4968 main(void) { 4969 int sd, flags, timeout, on; 4970 ssize_t n; 4971 unsigned int i; 4972 union { 4973 struct sockaddr sa; 4974 struct sockaddr_in sin; 4975 struct sockaddr_in6 sin6; 4976 } addr; 4977 socklen_t fromlen, infolen; 4978 struct sctp_rcvinfo info; 4979 unsigned int infotype; 4980 struct iovec iov; 4981 char buffer[BUFFER_SIZE]; 4982 struct sctp_event event; 4983 uint16_t event_types[] = {SCTP_ASSOC_CHANGE, 4984 SCTP_PEER_ADDR_CHANGE, 4985 SCTP_SHUTDOWN_EVENT, 4986 SCTP_ADAPTATION_INDICATION}; 4988 /* Create a 1-to-many style SCTP socket. */ 4989 if ((sd = socket(AF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP)) < 0) { 4990 perror("socket"); 4991 exit(1); 4992 } 4994 /* Enable the events of interest. */ 4995 memset(&event, 0, sizeof(event)); 4996 event.se_assoc_id = SCTP_FUTURE_ASSOC; 4997 event.se_on = 1; 4998 for (i = 0; i < sizeof(event_types)/sizeof(uint16_t); i++) { 4999 event.se_type = event_types[i]; 5000 if (setsockopt(sd, IPPROTO_SCTP, SCTP_EVENT, 5001 &event, sizeof(event)) < 0) { 5002 perror("setsockopt"); 5003 exit(1); 5004 } 5005 } 5007 /* Configure auto-close timer. */ 5008 timeout = TIMEOUT; 5009 if (setsockopt(sd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 5010 &timeout, sizeof(timeout)) < 0) { 5011 perror("setsockopt SCTP_AUTOCLOSE"); 5012 exit(1); 5013 } 5014 /* Enable delivery of SCTP_RCVINFO. */ 5015 on = 1; 5016 if (setsockopt(sd, IPPROTO_SCTP, SCTP_RECVRCVINFO, 5017 &on, sizeof(on)) < 0) { 5018 perror("setsockopt SCTP_RECVRCVINFO"); 5019 exit(1); 5020 } 5022 /* Bind the socket to all local addresses. */ 5023 memset(&addr, 0, sizeof(addr)); 5024 #ifdef HAVE_SIN6_LEN 5025 addr.sin6.sin6_len = sizeof(addr.sin6); 5026 #endif 5027 addr.sin6.sin6_family = AF_INET6; 5028 addr.sin6.sin6_port = htons(PORT); 5029 addr.sin6.sin6_addr = in6addr_any; 5030 if (bind(sd, &addr.sa, sizeof(addr.sin6)) < 0) { 5031 perror("bind"); 5032 exit(1); 5033 } 5034 /* Enable accepting associations. */ 5035 if (listen(sd, 1) < 0) { 5036 perror("listen"); 5037 exit(1); 5038 } 5040 for (;;) { 5041 flags = 0; 5042 memset(&addr, 0, sizeof(addr)); 5043 fromlen = (socklen_t)sizeof(addr); 5044 memset(&info, 0, sizeof(info)); 5045 infolen = (socklen_t)sizeof(info); 5046 infotype = 0; 5047 iov.iov_base = buffer; 5048 iov.iov_len = BUFFER_SIZE; 5050 n = sctp_recvv(sd, &iov, 1, 5051 &addr.sa, &fromlen, 5052 &info, &infolen, &infotype, 5053 &flags); 5055 if (flags & MSG_NOTIFICATION) { 5056 print_notification(iov.iov_base); 5057 } else { 5058 char addrbuf[INET6_ADDRSTRLEN]; 5059 const char *ap; 5060 in_port_t port; 5061 if (addr.sa.sa_family == AF_INET) { 5062 ap = inet_ntop(AF_INET, &addr.sin.sin_addr, 5063 addrbuf, INET6_ADDRSTRLEN); 5064 port = ntohs(addr.sin.sin_port); 5065 } else { 5066 ap = inet_ntop(AF_INET6, &addr.sin6.sin6_addr, 5067 addrbuf, INET6_ADDRSTRLEN); 5068 port = ntohs(addr.sin6.sin6_port); 5069 } 5070 printf("Message received from %s:%u: len=%d", 5071 ap, port, (int)n); 5072 switch (infotype) { 5073 case SCTP_RECVV_RCVINFO: 5074 printf(", sid=%u", info.rcv_sid); 5075 if (info.rcv_flags & SCTP_UNORDERED) { 5076 printf(", unordered"); 5077 } else { 5078 printf(", ssn=%u", info.rcv_ssn); 5079 } 5080 printf(", tsn=%u", info.rcv_tsn); 5081 printf(", ppid=%u.\n", ntohl(info.rcv_ppid)); 5082 break; 5083 case SCTP_RECVV_NOINFO: 5084 case SCTP_RECVV_NXTINFO: 5085 case SCTP_RECVV_RN: 5086 printf(".\n"); 5087 break; 5088 default: 5089 printf(" unknown infotype.\n"); 5090 } 5091 } 5092 } 5094 if (close(sd) < 0) { 5095 perror("close"); 5096 exit(1); 5097 } 5099 return (0); 5100 } 5102 Authors' Addresses 5104 Randall R. Stewart 5105 Adara Networks 5106 Chapin, SC 29036 5107 USA 5109 Email: randall@lakerest.net 5111 Michael Tuexen 5112 Muenster University of Applied Sciences 5113 Stegerwaldstr. 39 5114 48565 Steinfurt 5115 Germany 5117 Email: tuexen@fh-muenster.de 5119 Kacheong Poon 5120 Oracle Corporation 5122 Email: ka-cheong.poon@oracle.com 5124 Peter Lei 5125 Cisco Systems, Inc. 5126 9501 Technology Blvd 5127 West Office Center 5128 Rosemont, IL 60018 5129 USA 5131 Email: peterlei@cisco.com 5133 Vladislav Yasevich 5134 HP 5135 110 Spitrook Rd 5136 Nashua, NH 03062 5137 USA 5139 Email: vladislav.yasevich@hp.com