idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-25.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 (January 7, 2011) is 4858 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 Huawei 4 Intended status: Informational M. Tuexen 5 Expires: July 11, 2011 Muenster Univ. of Applied Sciences 6 K. Poon 7 Oracle Corporation 8 P. Lei 9 Cisco Systems, Inc. 10 V. Yasevich 11 HP 12 January 7, 2011 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-25.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 July 11, 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() . . . . . . . . . . . . . . . . . . . . . . 9 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() . . . . . . . . . . . . . . . . . . . . . . 14 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() . . . . . . . . . . . . . . . . . . . . 24 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() . . . . . . . . . . . . . . . . . . . 59 135 7.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 59 136 7.5. Implicit Association Setup . . . . . . . . . . . . . . . 60 137 8. Socket Options . . . . . . . . . . . . . . . . . . . . . . . 61 138 8.1. Read / Write Options . . . . . . . . . . . . . . . . . . 62 139 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . 62 140 8.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 63 141 8.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . 65 142 8.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 65 143 8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . 65 144 8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 66 145 8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 66 146 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . 66 147 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 67 148 8.1.10. Set Adaptation Layer Indicator 149 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 67 150 8.1.11. Enable/Disable Message Fragmentation 151 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . 67 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 . . . . . . . 70 155 8.1.14. Set Notification and Ancillary Events 156 (SCTP_EVENTS) - DEPRECATED . . . . . . . . . . . . . 70 157 8.1.15. Set/Clear IPv4 Mapped Addresses 158 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . 71 159 8.1.16. Get or Set the Maximum Fragmentation Size 160 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 71 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) . . . . . . . . . . . . . . . 72 165 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 73 166 8.1.20. Get or Set Fragmented Interleave 167 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . 74 168 8.1.21. Set or Get the SCTP Partial Delivery Point 169 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 75 170 8.1.22. Set or Get the Use of Extended Receive Info 171 (SCTP_USE_EXT_RCVINFO) - DEPRECATED . . . . . . . . . 75 172 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . 76 173 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 76 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) . . . . . . . . . . . . . . . . . 77 177 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . 77 178 8.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 78 179 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as 180 Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 78 181 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as 182 Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 78 183 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . 78 184 8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 79 185 8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . 79 186 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . 80 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) . . . . 82 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) . . . . . . . . . . . . . . 83 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) . . . . . . . . . . . . . . . . . . 84 200 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . 85 201 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . 85 202 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . 86 203 9. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 86 204 9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . 87 205 9.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . 88 206 9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . 89 207 9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 90 208 9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . 90 209 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 90 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_recvv() . . . . . . . . . . . . . . . . . . . . . . 96 216 9.13. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 98 217 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 100 218 11. Security Considerations . . . . . . . . . . . . . . . . . . . 101 219 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 101 220 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 101 221 13.1. Normative References . . . . . . . . . . . . . . . . . . 101 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 ID so that an application 251 can use the ID to differentiate them. Note that SCTP is 252 connection-oriented in nature, and it does not support broadcast 253 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 ID (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 ID cannot be specified. 336 Once an association ID is assigned to an SCTP association, that ID 337 will not be reused until the application explicitly terminates the 338 use of the association. The resources belonging to that association 339 will not be freed until that happens. This is similar to the close() 340 operation on a normal socket. The only exception is when the 341 SCTP_AUTOCLOSE option (section 7.1.8) is set. In this case, after 342 the association is terminated gracefully and automatically, the 343 association ID assigned to it can be reused. All applications using 344 this option should be aware of this to avoid the possible problem of 345 sending data to an incorrect peer endpoint. 347 If the server or client wishes to branch an existing association off 348 to a separate socket, it is required to call sctp_peeloff() and to 349 specify the association identifier. The sctp_peeloff() call will 350 return a new one-to-one style socket which can then be used with 351 recv() and send() functions for message passing. See Section 9.2 for 352 more on branched-off associations. 354 Once an association is branched off to a separate socket, it becomes 355 completely separated from the original socket. All subsequent 356 control and data operations to that association must be done through 357 the new socket. For example, the close operation on the original 358 socket will not terminate any associations that have been branched 359 off to a different socket. 361 One-to-many style socket calls are discussed in more detail in the 362 following subsections. 364 3.1.1. socket() 366 Applications use socket() to create a socket descriptor to represent 367 an SCTP endpoint. 369 The function prototype is 371 int socket(int domain, 372 int type, 373 int protocol); 375 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 376 type and IPPROTO_SCTP as the protocol. 378 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 379 socket. 381 The function returns a socket descriptor or -1 in case of an error. 383 Using the PF_INET domain indicates the creation of an endpoint which 384 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 385 can use both IPv6 and IPv4 addresses. 387 3.1.2. bind() 389 Applications use bind() to specify which local address and port the 390 SCTP endpoint should associate itself with. 392 An SCTP endpoint can be associated with multiple addresses. To do 393 this, sctp_bindx() is introduced in Section 9.1 to help applications 394 do the job of associating multiple addresses. But note that an 395 endpoint can only be associated with one local port. 397 These addresses associated with a socket are the eligible transport 398 addresses for the endpoint to send and receive data. The endpoint 399 will also present these addresses to its peers during the association 400 initialization process, see [RFC4960]. 402 After calling bind(), if the endpoint wishes to accept new 403 associations on the socket, it must call listen() (see 404 Section 3.1.3). 406 The function prototype of bind() is 408 int bind(int sd, 409 struct sockaddr *addr, 410 socklen_t addrlen); 412 and the arguments are 413 sd: The socket descriptor returned by socket(). 415 addr: The address structure (struct sockaddr_in for an IPv4 address 416 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 418 addrlen: The size of the address structure. 420 It returns 0 on success and -1 in case of an error. 422 If sd is an IPv4 socket, the address passed must be an IPv4 address. 423 If the sd is an IPv6 socket, the address passed can either be an IPv4 424 or an IPv6 address. 426 Applications cannot call bind() multiple times to associate multiple 427 addresses to an endpoint. After the first call to bind(), all 428 subsequent calls will return an error. 430 If the IP address part of addr is specified as a wildcard (INADDR_ANY 431 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 432 IPv6 address), the operating system will associate the endpoint with 433 an optimal address set of the available interfaces. If the IPv4 434 sin_port or IPv6 sin6_port is set to 0, the operating system will 435 choose an ephemeral port for the endpoint. 437 If a bind() is not called prior to a sendmsg() call that initiates a 438 new association, the system picks an ephemeral port and will choose 439 an address set equivalent to binding with a wildcard address. One of 440 those addresses will be the primary address for the association. 441 This automatically enables the multi-homing capability of SCTP. 443 The completion of this bind() process does not allow the SCTP 444 endpoint to accept inbound SCTP association requests. Until a 445 listen() system call, described below, is performed on the socket, 446 the SCTP endpoint will promptly reject an inbound SCTP INIT request 447 with an SCTP ABORT. 449 3.1.3. listen() 451 By default, a one-to-many style socket does not accept new 452 association requests. An application uses listen() to mark a socket 453 as being able to accept new associations. 455 The function prototype is 457 int listen(int sd, 458 int backlog); 460 and the arguments are 461 sd: The socket descriptor of the endpoint. 463 backlog: If backlog is non-zero, enable listening, else disable 464 listening. 466 It returns 0 on success and -1 in case of an error. 468 Note that one-to-many style socket consumers do not need to call 469 accept to retrieve new associations. Calling accept() on a one-to- 470 many style socket should return EOPNOTSUPP. Rather, new associations 471 are accepted automatically, and notifications of the new associations 472 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 473 these notifications are enabled). Clients will typically not call 474 listen(), so that they can be assured that only actively initiated 475 associations are possible on the socket. Server or peer-to-peer 476 sockets, on the other hand, will always accept new associations, so a 477 well-written application using server one-to-many style sockets must 478 be prepared to handle new associations from unwanted peers. 480 Also note that the SCTP_ASSOC_CHANGE event provides the association 481 ID for a new association, so if applications wish to use the 482 association ID as a parameter to other socket calls, they should 483 ensure that the SCTP_ASSOC_CHANGE event is enabled. 485 3.1.4. sendmsg() and recvmsg() 487 An application uses the sendmsg() and recvmsg() call to transmit data 488 to and receive data from its peer. 490 The function prototypes are 492 ssize_t sendmsg(int sd, 493 const struct msghdr *message, 494 int flags); 496 and 498 ssize_t recvmsg(int sd, 499 struct msghdr *message, 500 int flags); 502 using the arguments: 504 sd: The socket descriptor of the endpoint. 506 message: Pointer to the msghdr structure which contains a single 507 user message and possibly some ancillary data. See Section 5 for 508 complete description of the data structures. 510 flags: No new flags are defined for SCTP at this level. See 511 Section 5 for SCTP specific flags used in the msghdr structure. 513 sendmsg() returns the number of bytes accepted by the kernel or -1 in 514 case of an error. recvmsg() returns the number of bytes received or 515 -1 in case of an error. 517 As described in Section 5, different types of ancillary data can be 518 sent and received along with user data. When sending, the ancillary 519 data is used to specify the sent behavior, such as the SCTP stream 520 number to use. When receiving, the ancillary data is used to 521 describe the received data, such as the SCTP stream sequence number 522 of the message. 524 When sending user data with sendmsg(), the msg_name field in the 525 msghdr structure will be filled with one of the transport addresses 526 of the intended receiver. If there is no existing association 527 between the sender and the intended receiver, the sender's SCTP stack 528 will set up a new association and then send the user data (see 529 Section 7.5 for more on implicit association setup). If sendmsg() is 530 called with no data and there is no existing association, a new one 531 will be established. The SCTP_INIT type ancillary data can be used 532 to change some of the parameters used to set up a new association. 533 If sendmsg() is called with NULL data, and there is no existing 534 association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is 535 returned and errno is set to EINVAL. Sending a message using 536 sendmsg() is atomic unless explicit EOR marking is enabled on the 537 socket specified by sd (see Section 8.1.26). 539 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 540 be delivered if that notification has been enabled, and no more data 541 can be sent to that association. Any attempt to send more data will 542 cause sendmsg() to return with an ESHUTDOWN error. Note that the 543 socket is still open for reading at this point so it is possible to 544 retrieve notifications. 546 When receiving a user message with recvmsg(), the msg_name field in 547 the msghdr structure will be populated with the source transport 548 address of the user data. The caller of recvmsg() can use this 549 address information to determine to which association the received 550 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 551 disabled, applications must use the peer transport address provided 552 in the msg_name field by recvmsg() to perform correlation to an 553 association, since they will not have the association ID. 555 If all data in a single message has been delivered, MSG_EOR will be 556 set in the msg_flags field of the msghdr structure (see Section 5.1). 558 If the application does not provide enough buffer space to completely 559 receive a data message, MSG_EOR will not be set in msg_flags. 560 Successive reads will consume more of the same message until the 561 entire message has been delivered, and MSG_EOR will be set. 563 If the SCTP stack is running low on buffers, it may partially deliver 564 a message. In this case, MSG_EOR will not be set, and more calls to 565 recvmsg() will be necessary to completely consume the message. Only 566 one message at a time can be partially delivered in any stream. The 567 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 568 what interlacing of messages occurs for both the one-to-one and the 569 one-to-many model sockets. Please consult Section 8.1.20 for further 570 details on message delivery options. 572 3.1.5. close() 574 Applications use close() to perform graceful shutdown (as described 575 in Section 10.1 of [RFC4960]) on all the associations currently 576 represented by a one-to-many style socket. 578 The function prototype is 580 int close(int sd); 582 and the argument is 584 sd: The socket descriptor of the associations to be closed. 586 0 is returned on success and -1 in case of an error. 588 To gracefully shutdown a specific association represented by the one- 589 to-many style socket, an application should use the sendmsg() call, 590 and include the SCTP_EOF flag. A user may optionally terminate an 591 association non-gracefully by sending with the SCTP_ABORT flag set 592 and possibly passing a user specified abort code in the data field. 593 Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data 594 (see Section 5.3.2) in the sendmsg() call. 596 If sd in the close() call is a branched-off socket representing only 597 one association, the shutdown is performed on that association only. 599 3.1.6. connect() 601 An application may use the connect() call in the one-to-many style to 602 initiate an association without sending data. 604 The function prototype is 606 int connect(int sd, 607 const struct sockaddr *nam, 608 socklen_t len); 610 and the arguments are 612 sd: The socket descriptor to have a new association added to. 614 nam: The address structure (struct sockaddr_in for an IPv4 address 615 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 617 len: The size of the address. 619 0 is returned on success and -1 in case of an error. 621 Multiple connect() calls can be made on the same socket to create 622 multiple associations. This is different from the semantics of 623 connect() on a UDP socket. 625 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 626 during the association set up phase. If an application wants to do 627 this, it cannot use the connect() call. Instead, it should use 628 sendto() or sendmsg() to initiate an association. If it uses 629 sendto() and it wants to change the initialization behavior, it needs 630 to use the SCTP_INITMSG socket option before calling sendto(). Or it 631 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 632 association without calling setsockopt(). Note that the implicit 633 setup is supported for the one-to-many style sockets. 635 SCTP does not support half close semantics. This means that unlike 636 T/TCP, MSG_EOF should not be set in the flags parameter when calling 637 sendto() or sendmsg() when the call is used to initiate a connection. 638 MSG_EOF is not an acceptable flag with an SCTP socket. 640 3.2. Non-blocking mode 642 Some SCTP application may wish to avoid being blocked when calling a 643 socket interface function. 645 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 646 one-to-many style socket, an application may set the non-blocking 647 option by a fcntl() (such as O_NONBLOCK). After setting the socket 648 to non-blocking mode, the sendmsg() function returns immediately. 649 The success or failure of sending the data message (with possible 650 SCTP_INITMSG ancillary data) will be signaled by the 651 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or SCTP_CANT_START_ASSOC. 653 If user data could not be sent (due to a SCTP_CANT_START_ASSOC), the 654 sender will also receive an SCTP_SEND_FAILED_EVENT event. Events can 655 be received by the user calling recvmsg(). A server (having called 656 listen()) is also notified of an association up event by the 657 reception of an SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling 658 of recvmsg() and possibly the reception of the first data message. 660 To shutdown the association gracefully, the user must call sendmsg() 661 with no data and with the SCTP_EOF flag set. The function returns 662 immediately, and completion of the graceful shutdown is indicated by 663 an SCTP_ASSOC_CHANGE notification of type SHUTDOWN_COMPLETE (see 664 Section 6.1.1). Note that this can also be done using the 665 sctp_send() call described in Section 9.10. 667 An application is recommended to use caution when using select() (or 668 poll()) for writing on a one-to-many style socket. The reason being 669 that the interpretation of select on write is implementation 670 specific. Generally a positive return on a select on write would 671 only indicate that one of the associations represented by the one-to- 672 many socket is writable. An application that writes after the 673 select() returns may still block since the association that was 674 writeable is not the destination association of the write call. 675 Likewise select() (or poll()) for reading from a one-to-many socket 676 will only return an indication that one of the associations 677 represented by the socket has data to be read. 679 An application that wishes to know that a particular association is 680 ready for reading or writing should either use the one-to-one style 681 or use the sctp_peeloff() (see Section 9.2) function to separate the 682 association of interest from the one-to-many socket. 684 Note some implementations may have an extended select call such as 685 epoll or kqueue that may escape this limitation and allow a select on 686 a specific association of a one-to-many socket, but this is an 687 implementation specific detail that a portable application cannot 688 depend on. 690 3.3. Special considerations 692 The fact that a one-to-many style socket can provide access to many 693 SCTP associations through a single socket descriptor has important 694 implications for both application programmers and system programmers 695 implementing this API. A key issue is how buffer space inside the 696 sockets layer is managed. Because this implementation detail 697 directly affects how application programmers must write their code to 698 ensure correct operation and portability, this section provides some 699 guidance to both implementers and application programmers. 701 An important feature that SCTP shares with TCP is flow control. 702 Specifically, a sender may not send data faster than the receiver can 703 consume it. 705 For TCP, flow control is typically provided for in the sockets API as 706 follows. If the reader stops reading, the sender queues messages in 707 the socket layer until it uses all of its socket buffer space 708 allocation creating a "stalled connection". Further attempts to 709 write to the socket will block or return the error EAGAIN or 710 EWOULDBLOCK for a non-blocking socket. At some point, either the 711 connection is closed, or the receiver begins to read again freeing 712 space in the output queue. 714 For one-to-one style SCTP sockets (this includes sockets descriptors 715 that were separated from a one-to-many style socket with 716 sctp_peeloff()) the behavior is identical. For one-to-many style 717 SCTP sockets there are multiple associations for a single socket, 718 which makes the situation more complicated. If the implementation 719 uses a single buffer space allocation shared by all associations, a 720 single stalled association can prevent the further sending of data on 721 all associations active on a particular one-to-many style socket. 723 For a blocking socket, it should be clear that a single stalled 724 association can block the entire socket. For this reason, 725 application programmers may want to use non-blocking one-to-many 726 style sockets. The application should at least be able to send 727 messages to the non-stalled associations. 729 But a non-blocking socket is not sufficient if the API implementer 730 has chosen a single shared buffer allocation for the socket. A 731 single stalled association would eventually cause the shared 732 allocation to fill, and it would become impossible to send even to 733 non-stalled associations. 735 The API implementer can solve this problem by providing each 736 association with its own allocation of outbound buffer space. Each 737 association should conceptually have as much buffer space as it would 738 have if it had its own socket. As a bonus, this simplifies the 739 implementation of sctp_peeloff(). 741 To ensure that a given stalled association will not prevent other 742 non-stalled associations from being writable, application programmers 743 should either: 745 o demand that the underlying implementation dedicates independent 746 buffer space reservation to each association (as suggested above), 747 or 749 o verify that their application layer protocol does not permit large 750 amounts of unread data at the receiver (this is true of some 751 request-response protocols, for example), or 753 o use one-to-one style sockets for association which may potentially 754 stall (either from the beginning, or by using sctp_peeloff before 755 sending large amounts of data that may cause a stalled condition). 757 4. One-to-One Style Interface 759 The goal of this style is to follow as closely as possible the 760 current practice of using the sockets interface for a connection 761 oriented protocol, such as TCP. This style enables existing 762 applications using connection oriented protocols to be ported to SCTP 763 with very little effort. 765 One-to-one style sockets can be connected (explicitly or implicitly) 766 at most once, similar to TCP sockets. 768 Note that some new SCTP features and some new SCTP socket options can 769 only be utilized through the use of sendmsg() and recvmsg() calls, 770 see Section 4.1.8. 772 4.1. Basic Operation 774 A typical server in one-to-one style uses the following system call 775 sequence to prepare an SCTP endpoint for servicing requests: 777 o socket() 779 o bind() 781 o listen() 783 o accept() 785 The accept() call blocks until a new association is set up. It 786 returns with a new socket descriptor. The server then uses the new 787 socket descriptor to communicate with the client, using recv() and 788 send() calls to get requests and send back responses. 790 Then it calls 792 o close() 794 to terminate the association. 796 A typical client uses the following system call sequence to setup an 797 association with a server to request services: 799 o socket() 801 o connect() 803 After returning from connect(), the client uses send()/sendmsg() and 804 recv()/recvmsg() calls to send out requests and receive responses 805 from the server. 807 The client calls 809 o close() 811 to terminate this association when done. 813 4.1.1. socket() 815 Applications call socket() to create a socket descriptor to represent 816 an SCTP endpoint. 818 The function prototype is 820 int socket(int domain, 821 int type, 822 int protocol); 824 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 825 type and IPPROTO_SCTP as the protocol. 827 Here, SOCK_STREAM indicates the creation of a one-to-one style 828 socket. 830 Using the PF_INET domain indicates the creation of an endpoint which 831 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 832 can use both IPv6 and IPv4 addresses. 834 4.1.2. bind() 836 Applications use bind() to specify which local address and port the 837 SCTP endpoint should associate itself with. 839 An SCTP endpoint can be associated with multiple addresses. To do 840 this, sctp_bindx() is introduced in Section 9.1 to help applications 841 do the job of associating multiple addresses. But note that an 842 endpoint can only be associated with one local port. 844 These addresses associated with a socket are the eligible transport 845 addresses for the endpoint to send and receive data. The endpoint 846 will also present these addresses to its peers during the association 847 initialization process, see [RFC4960]. 849 The function prototype of bind() is 851 int bind(int sd, 852 struct sockaddr *addr, 853 socklen_t addrlen); 855 and the arguments are 857 sd: The socket descriptor returned by socket(). 859 addr: The address structure (struct sockaddr_in for an IPv4 address 860 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 862 addrlen: The size of the address structure. 864 If sd is an IPv4 socket, the address passed must be an IPv4 address. 865 If sd is an IPv6 socket, the address passed can either be an IPv4 or 866 an IPv6 address. 868 Applications cannot call bind() multiple times to associate multiple 869 addresses to the endpoint. After the first call to bind(), all 870 subsequent calls will return an error. 872 If the IP address part of addr is specified as a wildcard (INADDR_ANY 873 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 874 IPv6 address), the operating system will associate the endpoint with 875 an optimal address set of the available interfaces. If the IPv4 876 sin_port or IPv6 sin6_port is set to 0, the operating system will 877 choose an ephemeral port for the endpoint. 879 If a bind() is not called prior to the connect() call, the system 880 picks an ephemeral port and will choose an address set equivalent to 881 binding with a wildcard address. One of these addresses will be the 882 primary address for the association. This automatically enables the 883 multi-homing capability of SCTP. 885 The completion of this bind() process does not allow the SCTP 886 endpoint to accept inbound SCTP association requests. Until a 887 listen() system call, described below, is performed on the socket, 888 the SCTP endpoint will promptly reject an inbound SCTP INIT request 889 with an SCTP ABORT. 891 4.1.3. listen() 893 Applications use listen() to allow the SCTP endpoint to accept 894 inbound associations. 896 The function prototype is 898 int listen(int sd, 899 int backlog); 901 and the arguments are 903 sd: the socket descriptor of the SCTP endpoint. 905 backlog: this specifies the max number of outstanding associations 906 allowed in the socket's accept queue. These are the associations 907 that have finished the four-way initiation handshake (see Section 908 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 909 of '0' indicates that the caller no longer wishes to receive new 910 associations. 912 It returns 0 on success an -1 in case of an error. 914 4.1.4. accept() 916 Applications use the accept() call to remove an established SCTP 917 association from the accept queue of the endpoint. A new socket 918 descriptor will be returned from accept() to represent the newly 919 formed association. 921 The function prototype is 923 int accept(int sd, 924 struct sockaddr *addr, 925 socklen_t *addrlen); 927 and the arguments are 929 sd: The listening socket descriptor. 931 addr: On return, addr (struct sockaddr_in for an IPv4 address or 932 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 933 contain the primary address of the peer endpoint. 935 addrlen: On return, addrlen will contain the size of addr. 937 The function returns the socket descriptor for the newly formed 938 association on success and -1 in case of an error. 940 4.1.5. connect() 942 Applications use connect() to initiate an association to a peer. 944 The function prototype is 946 int connect(int sd, 947 const struct sockaddr *addr, 948 socklen_t addrlen); 950 and the arguments are 952 sd: The socket descriptor of the endpoint. 954 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 955 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 957 addrlen: The size of the address. 959 It returns 0 on success and -1 on error. 961 This operation corresponds to the ASSOCIATE primitive described in 962 Section 10.1 of [RFC4960]. 964 The number of outbound streams the new association has is stack 965 dependent. Applications can use the SCTP_INITMSG option described in 966 Section 8.1.3 before connecting to change the number of outbound 967 streams. 969 If a bind() is not called prior to the connect() call, the system 970 picks an ephemeral port and will choose an address set equivalent to 971 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 972 respectively. One of the addresses will be the primary address for 973 the association. This automatically enables the multi-homing 974 capability of SCTP. 976 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 977 during the association set up phase. If an application wants to do 978 this, it cannot use the connect() call. Instead, it should use 979 sendto() or sendmsg() to initiate an association. If it uses 980 sendto() and it wants to change the initialization behavior, it needs 981 to use the SCTP_INITMSG socket option before calling sendto(). Or it 982 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 983 association without calling setsockopt(). Note that the implicit 984 setup is supported for the one-to-one style sockets. 986 SCTP does not support half close semantics. This means that unlike 987 T/TCP, MSG_EOF should not be set in the flags parameter when calling 988 sendto() or sendmsg() when the call is used to initiate a connection. 989 MSG_EOF is not an acceptable flag with an SCTP socket. 991 4.1.6. close() 993 Applications use close() to gracefully close down an association. 995 The function prototype is 997 int close(int sd); 999 and the argument is 1001 sd: The socket descriptor of the association to be closed. 1003 It returns 0 on success and -1 in case of an error. 1005 After an application calls close() on a socket descriptor, no further 1006 socket operations will succeed on that descriptor. 1008 4.1.7. shutdown() 1010 SCTP differs from TCP in that it does not have half closed semantics. 1011 Hence the shutdown() call for SCTP is an approximation of the TCP 1012 shutdown() call, and solves some different problems. Full TCP- 1013 compatibility is not provided, so developers porting TCP applications 1014 to SCTP may need to recode sections that use shutdown(). (Note that 1015 it is possible to achieve the same results as half close in SCTP 1016 using SCTP streams.) 1018 The function prototype is 1020 int shutdown(int sd, 1021 int how); 1023 and the arguments are 1025 sd: The socket descriptor of the association to be closed. 1027 how: Specifies the type of shutdown. The values are as follows: 1029 SHUT_RD: Disables further receive operations. No SCTP protocol 1030 action is taken. 1032 SHUT_WR: Disables further send operations, and initiates the SCTP 1033 shutdown sequence. 1035 SHUT_RDWR: Disables further send and receive operations and 1036 initiates the SCTP shutdown sequence. 1038 It returns 0 on success and -1 in case of an error. 1040 The major difference between SCTP and TCP shutdown() is that SCTP 1041 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 1042 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 1043 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 1044 the SCTP association while still leaving the socket descriptor open. 1045 This allows the caller to receive back any data which SCTP is unable 1046 to deliver (see Section 6.1.4 for more information) and receive event 1047 notifications. 1049 To perform the ABORT operation described in [RFC4960] Section 10.1, 1050 an application can use the socket option SO_LINGER. It is described 1051 in Section 8.1.4. 1053 4.1.8. sendmsg() and recvmsg() 1055 With a one-to-one style socket, the application can also use 1056 sendmsg() and recvmsg() to transmit data to and receive data from its 1057 peer. The semantics is similar to those used in the one-to-many 1058 style (see Section 3.1.3), with the following differences: 1060 1. When sending, the msg_name field in the msghdr is not used to 1061 specify the intended receiver, rather it is used to indicate a 1062 preferred peer address if the sender wishes to discourage the 1063 stack from sending the message to the primary address of the 1064 receiver. If the socket is connected and the transport address 1065 given is not part of the current association, the data will not 1066 be sent and an SCTP_SEND_FAILED_EVENT event will be delivered to 1067 the application if send failure events are enabled. 1069 2. Using sendmsg() on a non-connected one-to-one style socket for 1070 implicit connection setup may or may not work depending on the 1071 SCTP implementation. 1073 4.1.9. getpeername() 1075 Applications use getpeername() to retrieve the primary socket address 1076 of the peer. This call is for TCP compatibility, and is not multi- 1077 homed. It may not work with one-to-many style sockets depending on 1078 the implementation. See Section 9.3 for a multi-homed style version 1079 of the call. 1081 The function prototype is 1082 int getpeername(int sd, 1083 struct sockaddr *address, 1084 socklen_t *len); 1086 and the arguments are: 1088 sd: The socket descriptor to be queried. 1090 address: On return, the peer primary address is stored in this 1091 buffer. If the socket is an IPv4 socket, the address will be 1092 IPv4. If the socket is an IPv6 socket, the address will be either 1093 an IPv6 or IPv4 address. 1095 len: The caller should set the length of address here. On return, 1096 this is set to the length of the returned address. 1098 It returns 0 on success and -1 in case of an error. 1100 If the actual length of the address is greater than the length of the 1101 supplied sockaddr structure, the stored address will be truncated. 1103 5. Data Structures 1105 This section discusses important data structures which are specific 1106 to SCTP and are used with sendmsg() and recvmsg() calls to control 1107 SCTP endpoint operations and to access ancillary information and 1108 notifications. 1110 5.1. The msghdr and cmsghdr Structures 1112 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1113 well as the ancillary data carried in the structure, is the key for 1114 the application to set and get various control information from the 1115 SCTP endpoint. 1117 The msghdr and the related cmsghdr structures are defined and 1118 discussed in detail in [RFC3542]. They are defined as: 1120 struct msghdr { 1121 void *msg_name; /* ptr to socket address structure */ 1122 socklen_t msg_namelen; /* size of socket address structure */ 1123 struct iovec *msg_iov; /* scatter/gather array */ 1124 int msg_iovlen; /* # elements in msg_iov */ 1125 void *msg_control; /* ancillary data */ 1126 socklen_t msg_controllen; /* ancillary data buffer length */ 1127 int msg_flags; /* flags on received message */ 1128 }; 1130 struct cmsghdr { 1131 socklen_t cmsg_len; /* #bytes, including this header */ 1132 int cmsg_level; /* originating protocol */ 1133 int cmsg_type; /* protocol-specific type */ 1134 /* followed by unsigned char cmsg_data[]; */ 1135 }; 1137 In the msghdr structure, the usage of msg_name has been discussed in 1138 previous sections (see Section 3.1.3 and Section 4.1.8). 1140 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1141 field) are treated by SCTP as a single user message for both 1142 sendmsg() and recvmsg(). 1144 SCTP stack uses the ancillary data (msg_control field) to communicate 1145 the attributes, such as SCTP_RCVINFO, of the message stored in 1146 msg_iov to the socket end point. The different ancillary data types 1147 are described in Section 5.3. 1149 The msg_flags are not used when sending a message with sendmsg(). 1151 If a notification has arrived, recvmsg() will return the notification 1152 in msg_iov field and set MSG_NOTIFICATION flag in msg_flags. If the 1153 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1154 Section 6 for more information about notifications. 1156 If all portions of a data frame or notification have been read, 1157 recvmsg() will return with MSG_EOR set in msg_flags. 1159 5.2. Ancillary Data Considerations and Semantics 1161 Programming with ancillary socket data (msg_control) contains some 1162 subtleties and pitfalls, which are discussed below. 1164 5.2.1. Multiple Items and Ordering 1166 Multiple ancillary data items may be included in any call to 1167 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP, 1168 such as IP level items, or both. 1170 The ordering of ancillary data items (either by SCTP or another 1171 protocol) is not significant and is implementation-dependent, so 1172 applications must not depend on any ordering. 1174 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 1175 correspond to the data in the msghdr's msg_iov member. There can be 1176 only one single such type ancillary data for each sendmsg() or 1177 recvmsg() call. 1179 5.2.2. Accessing and Manipulating Ancillary Data 1181 Applications can infer the presence of data or ancillary data by 1182 examining the msg_iovlen and msg_controllen msghdr members, 1183 respectively. 1185 Implementations may have different padding requirements for ancillary 1186 data, so portable applications should make use of the macros 1187 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1188 [RFC3542] and the SCTP implementation's documentation for more 1189 information. The following is an example, from [RFC3542], 1190 demonstrating the use of these macros to access ancillary data: 1192 struct msghdr msg; 1193 struct cmsghdr *cmsgptr; 1195 /* fill in msg */ 1197 /* call recvmsg() */ 1199 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1200 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1201 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1202 u_char *ptr; 1204 ptr = CMSG_DATA(cmsgptr); 1205 /* process data pointed to by ptr */ 1206 } 1207 } 1209 5.2.3. Control Message Buffer Sizing 1211 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1212 ancillary data will often be fundamental to the correct and sane 1213 operation of the sockets application. This is particularly true of 1214 the one-to-many semantics, but also of the one-to-one semantics. For 1215 example, if an application needs to send and receive data on 1216 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1217 ancillary data is indispensable. 1219 Given that some ancillary data is critical, and that multiple 1220 ancillary data items may appear in any order, applications should be 1221 carefully written to always provide a large enough buffer to contain 1222 all possible ancillary data that can be presented by recvmsg(). If 1223 the buffer is too small, and crucial data is truncated, it may pose a 1224 fatal error condition. 1226 Thus, it is essential that applications be able to deterministically 1227 calculate the maximum required buffer size to pass to recvmsg(). One 1228 constraint imposed on this specification that makes this possible is 1229 that all ancillary data definitions are of a fixed length. One way 1230 to calculate the maximum required buffer size might be to take the 1231 sum the sizes of all enabled ancillary data item structures, as 1232 calculated by CMSG_SPACE. For example, if we enabled 1233 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 1234 and allocate the buffer size as follows: 1236 size_t total; 1237 void *buf; 1239 total = CMSG_SPACE(sizeof(struct sctp_sndrcvinfo)) + 1240 CMSG_SPACE(sizeof(struct in6_pktinfo)); 1242 buf = malloc(total); 1244 We could then use this buffer (buf) for msg_control on each call to 1245 recvmsg() and be assured that we would not lose any ancillary data to 1246 truncation. 1248 5.3. SCTP msg_control Structures 1250 A key element of all SCTP specific socket extensions is the use of 1251 ancillary data to specify and access SCTP specific data via the 1252 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1253 Fine-grained control over initialization and sending parameters are 1254 handled with ancillary data. 1256 Each ancillary data item is proceeded by a struct cmsghdr (see 1257 Section 5.1), which defines the function and purpose of the data 1258 contained in the cmsg_data[] member. 1260 By default on either style socket, SCTP will pass no ancillary data; 1261 Specific ancillary data items can be enabled with socket options 1262 defined for SCTP; see Section 6.2. 1264 Note that all ancillary types are fixed length; see Section 5.2 for 1265 further discussion on this. These data structures use struct 1266 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1267 address format. 1269 Other protocols may also provide ancillary data to the socket layer 1270 consumer. These ancillary data items from other protocols may 1271 intermingle with SCTP data. For example, the IPv6 socket API 1272 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1273 data items. If a socket API consumer enables delivery of both SCTP 1274 and IPv6 ancillary data, they both may appear in the same msg_control 1275 buffer in any order. An application may thus need to handle other 1276 types of ancillary data besides those passed by SCTP. 1278 The sockets application must provide a buffer large enough to 1279 accommodate all ancillary data provided via recvmsg(). If the buffer 1280 is not large enough, the ancillary data will be truncated and the 1281 msghdr's msg_flags will include MSG_CTRUNC. 1283 5.3.1. SCTP Initiation Structure (SCTP_INIT) 1285 This cmsghdr structure provides information for initializing new SCTP 1286 associations with sendmsg(). The SCTP_INITMSG socket option uses 1287 this same data structure. This structure is not used for recvmsg(). 1289 +--------------+-----------+---------------------+ 1290 | cmsg_level | cmsg_type | cmsg_data[] | 1291 +--------------+-----------+---------------------+ 1292 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1293 +--------------+-----------+---------------------+ 1295 The sctp_initmsg structure is defined below: 1297 struct sctp_initmsg { 1298 uint16_t sinit_num_ostreams; 1299 uint16_t sinit_max_instreams; 1300 uint16_t sinit_max_attempts; 1301 uint16_t sinit_max_init_timeo; 1302 }; 1304 sinit_num_ostreams: This is an integer number representing the 1305 number of streams that the application wishes to be able to send 1306 to. This number is confirmed in the SCTP_COMM_UP notification and 1307 must be verified since it is a negotiated number with the remote 1308 endpoint. The default value of 0 indicates to use the endpoint 1309 default value. 1311 sinit_max_instreams: This value represents the maximum number of 1312 inbound streams the application is prepared to support. This 1313 value is bounded by the actual implementation. In other words the 1314 user may be able to support more streams than the Operating 1315 System. In such a case, the Operating System limit overrides the 1316 value requested by the user. The default value of 0 indicates to 1317 use the endpoints default value. 1319 sinit_max_attempts: This integer specifies how many attempts the 1320 SCTP endpoint should make at resending the INIT. This value 1321 overrides the system SCTP 'Max.Init.Retransmits' value. The 1322 default value of 0 indicates to use the endpoints default value. 1323 This is normally set to the system's default 'Max.Init.Retransmit' 1324 value. 1326 sinit_max_init_timeo: This value represents the largest Time-Out or 1327 RTO value (in milliseconds) to use in attempting an INIT. 1328 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1329 upon timeout. For the INIT message this value may override 1330 'RTO.Max'. This value must not influence 'RTO.Max' during data 1331 transmission and is only used to bound the initial setup time. A 1332 default value of 0 indicates to use the endpoints default value. 1333 This is normally set to the system's 'RTO.Max' value (60 seconds). 1335 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - DEPRECATED 1337 This cmsghdr structure specifies SCTP options for sendmsg() and 1338 describes SCTP header information about a received message through 1339 recvmsg(). This structure mixes the send and receive path. 1340 SCTP_SNDINFO described in Section 5.3.4 and SCTP_RCVINFO described in 1341 Section 5.3.5 split this information. These structures should be 1342 used, when possible, since SCTP_SNDRCV is deprecated. 1344 +--------------+-------------+------------------------+ 1345 | cmsg_level | cmsg_type | cmsg_data[] | 1346 +--------------+-------------+------------------------+ 1347 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1348 +--------------+-------------+------------------------+ 1350 The sctp_sndrcvinfo structure is defined below: 1352 struct sctp_sndrcvinfo { 1353 uint16_t sinfo_stream; 1354 uint16_t sinfo_ssn; 1355 uint16_t sinfo_flags; 1356 uint32_t sinfo_ppid; 1357 uint32_t sinfo_context; 1358 uint32_t sinfo_timetolive; 1359 uint32_t sinfo_tsn; 1360 uint32_t sinfo_cumtsn; 1361 sctp_assoc_t sinfo_assoc_id; 1362 }; 1364 sinfo_stream: For recvmsg() the SCTP stack places the message's 1365 stream number in this value. For sendmsg() this value holds the 1366 stream number that the application wishes to send this message to. 1367 If a sender specifies an invalid stream number an error indication 1368 is returned and the call fails. 1370 sinfo_ssn: For recvmsg() this value contains the stream sequence 1371 number that the remote endpoint placed in the DATA chunk. For 1372 fragmented messages this is the same number for all deliveries of 1373 the message (if more than one recvmsg() is needed to read the 1374 message). The sendmsg() call will ignore this parameter. 1376 sinfo_flags: This field may contain any of the following flags and 1377 is composed of a bitwise OR of these values. 1379 recvmsg() flags: 1381 SCTP_UNORDERED: This flag is present when the message was sent 1382 un-ordered. 1384 sendmsg() flags: 1386 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1387 the message. If this flag is clear the datagram is 1388 considered an ordered send. 1390 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1391 the SCTP stack to override the primary destination address 1392 with the address found with the sendto/sendmsg call. 1394 SCTP_ABORT: Setting this flag causes the specified association 1395 to abort by sending an ABORT message to the peer. The ABORT 1396 chunk will contain an error cause 'User Initiated Abort' 1397 with cause code 12. The cause specific information of this 1398 error cause is provided in msg_iov. 1400 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1401 procedure on the specified association. Graceful shutdown 1402 assures that all data queued by both endpoints is 1403 successfully transmitted before closing the association. 1405 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1406 model socket to send the message to all associations that 1407 are currently established on this socket. For the one-to- 1408 one socket, this flag has no effect. 1410 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1411 passed to the remote end in each user message. In recvmsg() this 1412 value is the same information that was passed by the upper layer 1413 in the peer application. Please note that the SCTP stack performs 1414 no byte order modification of this field. For example, if the 1415 DATA chunk has to contain a given value in network byte order, the 1416 SCTP user has to perform the htonl() computation. 1418 sinfo_context: This value is an opaque 32 bit context datum that is 1419 used in the sendmsg() function. This value is passed back to the 1420 upper layer if an error occurs on the send of a message and is 1421 retrieved with each undelivered message. 1423 sinfo_timetolive: For the sending side, this field contains the 1424 message time to live in milliseconds. The sending side will 1425 expire the message within the specified time period if the message 1426 as not been sent to the peer within this time period. This value 1427 will override any default value set using any socket option. Also 1428 note that the value of 0 is special in that it indicates no 1429 timeout should occur on this message. 1431 sinfo_tsn: For the receiving side, this field holds a TSN that was 1432 assigned to one of the SCTP Data Chunks. For the sending side it 1433 is ignored. 1435 sinfo_cumtsn: This field will hold the current cumulative TSN as 1436 known by the underlying SCTP layer. Note this field is ignored 1437 when sending. 1439 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1440 the identifier for the association announced in the SCTP_COMM_UP 1441 notification. All notifications for a given association have the 1442 same identifier. Ignored for one-to-one style sockets. 1444 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1446 5.3.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) - 1447 DEPRECATED 1449 This cmsghdr structure specifies SCTP options for SCTP header 1450 information about a received message via recvmsg(). Note that this 1451 structure is an extended version of SCTP_SNDRCV (see Section 5.3.2) 1452 and will only be received if the user has set the socket option 1453 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1454 needed to receive ancillary data. See Section 8.1.22 on this socket 1455 option. Note that next message data is not valid unless the current 1456 message is completely read, i.e. the MSG_EOR is set, in other words 1457 if the application has more data to read from the current message 1458 then no next message information will be available. 1460 SCTP_NXTINFO described in Section 5.3.6 should be used when possible, 1461 since SCTP_EXTRCV is considered deprecated. 1463 +--------------+-------------+------------------------+ 1464 | cmsg_level | cmsg_type | cmsg_data[] | 1465 +--------------+-------------+------------------------+ 1466 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1467 +--------------+-------------+------------------------+ 1469 The sctp_extrcvinfo structure is defined below: 1471 struct sctp_extrcvinfo { 1472 uint16_t sinfo_stream; 1473 uint16_t sinfo_ssn; 1474 uint16_t sinfo_flags; 1475 uint32_t sinfo_ppid; 1476 uint32_t sinfo_context; 1477 uint32_t sinfo_pr_value; 1478 uint32_t sinfo_tsn; 1479 uint32_t sinfo_cumtsn; 1480 uint16_t serinfo_next_flags; 1481 uint16_t serinfo_next_stream; 1482 uint32_t serinfo_next_aid; 1483 uint32_t serinfo_next_length; 1484 uint32_t serinfo_next_ppid; 1485 sctp_assoc_t sinfo_assoc_id; 1486 }; 1488 sinfo_*: Please see Section 5.3.2 for the details for these fields. 1490 serinfo_next_flags: This bitmask will hold one or more of the 1491 following values: 1493 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1494 message information is available i.e.: next_stream, 1495 next_asocid, next_length and next_ppid fields all have valid 1496 values. If this bit is set to 0, then these fields are not 1497 valid and should be ignored. 1499 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1500 next message is completely in the receive buffer. The 1501 next_length field thus contains the entire message size. If 1502 this flag is set to 0, then the next_length field only contains 1503 part of the message size since the message is still being 1504 received (it is being partially delivered). 1506 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1507 the next message to be received was sent by the peer as 1508 unordered. If this bit is not set (i.e. the bit is 0) the next 1509 message to be read is an ordered message in the stream 1510 specified. 1512 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1513 the next message to be received is not a message from the peer, 1514 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1516 serinfo_next_stream: This value, when valid (see 1517 serinfo_next_flags), contains the next stream number that will be 1518 received on a subsequent call to one of the receive message 1519 functions. 1521 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1522 contains the next association identification that will be received 1523 on a subsequent call to one of the receive message functions. 1525 serinfo_next_length: This value, when valid (see 1526 serinfo_next_flags), contains the length of the next message that 1527 will be received on a subsequent call to one of the receive 1528 message functions. Note that this length may be a partial length 1529 depending on the settings of next_flags. 1531 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1532 contains the ppid of the next message that will be received on a 1533 subsequent call to one of the receive message functions. 1535 5.3.4. SCTP Send Information Structure (SCTP_SNDINFO) 1537 This cmsghdr structure specifies SCTP options for sendmsg(). 1539 +--------------+--------------+---------------------+ 1540 | cmsg_level | cmsg_type | cmsg_data[] | 1541 +--------------+--------------+---------------------+ 1542 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1543 +--------------+--------------+---------------------+ 1545 The sctp_sndinfo structure is defined below: 1547 struct sctp_sndinfo { 1548 uint16_t snd_sid; 1549 uint16_t snd_flags; 1550 uint32_t snd_ppid; 1551 uint32_t snd_context; 1552 sctp_assoc_t snd_assoc_id; 1553 }; 1555 snd_sid: This value holds the stream number that the application 1556 wishes to send this message to. If a sender specifies an invalid 1557 stream number an error indication is returned and the call fails. 1559 snd_flags: This field may contain any of the following flags and is 1560 composed of a bitwise OR of these values. 1562 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1563 message. If this flag is clear the datagram is considered an 1564 ordered send. 1566 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1567 SCTP stack to override the primary destination address with the 1568 address found with the sendto()/sendmsg call. 1570 SCTP_ABORT: Setting this flag causes the specified association to 1571 abort by sending an ABORT message to the peer. The ABORT chunk 1572 will contain an error cause 'User Initiated Abort' with cause 1573 code 12. The cause specific information of this error cause is 1574 provided in msg_iov. 1576 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1577 procedures on the specified association. Graceful shutdown 1578 assures that all data queued by both endpoints is successfully 1579 transmitted before closing the association. 1581 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1582 socket to send the message to all associations that are 1583 currently established on this socket. For the one-to-one 1584 socket, this flag has no effect. 1586 snd_ppid: This value in sendmsg() is an unsigned integer that is 1587 passed to the remote end in each user message. Please note that 1588 the SCTP stack performs no byte order modification of this field. 1589 For example, if the DATA chunk has to contain a given value in 1590 network byte order, the SCTP user has to perform the htonl() 1591 computation. 1593 snd_context: This value is an opaque 32 bit context datum that is 1594 used in the sendmsg() function. This value is passed back to the 1595 upper layer if an error occurs on the send of a message and is 1596 retrieved with each undelivered message. 1598 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1599 the identifier for the association announced in the SCTP_COMM_UP 1600 notification. All notifications for a given association have the 1601 same identifier. Ignored for one-to-one style sockets. 1603 An sctp_sndinfo item always corresponds to the data in msg_iov. 1605 5.3.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1607 This cmsghdr structure describes SCTP receive information about a 1608 received message through recvmsg(). 1610 To enable the delivery of this information an application must use 1611 the SCTP_RECVRCVINFO socket option (see Section 8.1.29). 1613 +--------------+--------------+---------------------+ 1614 | cmsg_level | cmsg_type | cmsg_data[] | 1615 +--------------+--------------+---------------------+ 1616 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1617 +--------------+--------------+---------------------+ 1619 The sctp_rcvinfo structure is defined below: 1621 struct sctp_rcvinfo { 1622 uint16_t rcv_sid; 1623 uint16_t rcv_ssn; 1624 uint16_t rcv_flags; 1625 uint32_t rcv_ppid; 1626 uint32_t rcv_tsn; 1627 uint32_t rcv_cumtsn; 1628 uint32_t rcv_context; 1629 sctp_assoc_t rcv_assoc_id; 1630 }; 1631 rcv_sid: The SCTP stack places the message's stream number in this 1632 value. 1634 rcv_ssn: This value contains the stream sequence number that the 1635 remote endpoint placed in the DATA chunk. For fragmented messages 1636 this is the same number for all deliveries of the message (if more 1637 than one recvmsg() is needed to read the message). 1639 rcv_flags: This field may contain any of the following flags and is 1640 composed of a bitwise OR of these values. 1642 SCTP_UNORDERED: This flag is present when the message was sent 1643 un-ordered. 1645 rcv_ppid: This value is the same information that was passed by the 1646 upper layer in the peer application. Please note that the SCTP 1647 stack performs no byte order modification of this field. For 1648 example, if the DATA chunk has to contain a given value in network 1649 byte order, the SCTP user has to perform the ntohl() computation. 1651 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1652 Data Chunks. 1654 rcv_cumtsn: This field will hold the current cumulative TSN as known 1655 by the underlying SCTP layer. 1657 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1658 the identifier for the association announced in the SCTP_COMM_UP 1659 notification. All notifications for a given association have the 1660 same identifier. Ignored for one-to-one style sockets. 1662 rcv_context: This value is an opaque 32 bit context datum that was 1663 set by the user with the SCTP_CONTEXT socket option. This value 1664 is passed back to the upper layer if an error occurs on the send 1665 of a message and is retrieved with each undelivered message. 1667 An sctp_rcvinfo item always corresponds to the data in msg_iov. 1669 5.3.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1671 This cmsghdr structure describes SCTP receive information of the next 1672 message which will be delivered through recvmsg() if this information 1673 is already available when delivering the current message. 1675 To enable the delivery of this information an application must use 1676 the SCTP_RECVNXTINFO socket option (see Section 8.1.30). 1678 +--------------+--------------+---------------------+ 1679 | cmsg_level | cmsg_type | cmsg_data[] | 1680 +--------------+--------------+---------------------+ 1681 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_nxtinfo | 1682 +--------------+--------------+---------------------+ 1684 The sctp_nxtinfo structure is defined below: 1686 struct sctp_nxtinfo { 1687 uint16_t nxt_sid; 1688 uint16_t nxt_flags; 1689 uint32_t nxt_ppid; 1690 size_t nxt_length; 1691 sctp_assoc_t nxt_assoc_id; 1692 }; 1694 nxt_sid: The SCTP stack places the next message's stream number in 1695 this value. 1697 nxt_flags: This field may contain any of the following flags and is 1698 composed of a bitwise OR of these values. 1700 SCTP_UNORDERED: This flag is present when the next message was 1701 sent un-ordered. 1703 SCTP_COMPLETE: This flag indicates that the entire message has 1704 been received and is in the socket buffer. Note that this has 1705 special implications with respect to the nxt_length field, see 1706 nxt_length description below. 1708 SCTP_NOTIFICATION: This flag is present when the next message is 1709 not a user message but instead is a notification. 1711 nxt_ppid: This value is the same information that was passed by the 1712 upper layer in the peer application for the next message. Please 1713 note that the SCTP stack performs no byte order modification of 1714 this field. For example, if the DATA chunk has to contain a given 1715 value in network byte order, the SCTP user has to perform the 1716 ntohl() computation. 1718 nxt_length: This value is the length of the message currently within 1719 the socket buffer. This might NOT be the entire length of the 1720 message since a partial delivery may be in progress. Only if the 1721 flag SCTP_COMPLETE is set in the nxt_flags field does this field 1722 represent the entire next message size. 1724 nxt_assoc_id: The association handle field of the next message, 1725 nxt_assoc_id, holds the identifier for the association announced 1726 in the SCTP_COMM_UP notification. All notifications for a given 1727 association have the same identifier. Ignored for one-to-one 1728 style sockets. 1730 5.3.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1732 This cmsghdr structure specifies SCTP options for sendmsg(). 1734 +--------------+-------------+--------------------+ 1735 | cmsg_level | cmsg_type | cmsg_data[] | 1736 +--------------+-------------+--------------------+ 1737 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1738 +--------------+-------------+--------------------+ 1740 The sctp_prinfo structure is defined below: 1742 struct sctp_prinfo { 1743 uint16_t pr_policy; 1744 uint32_t pr_value; 1745 }; 1747 pr_policy: This specifies which PR-SCTP policy is used. Using 1748 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1749 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1750 defined in [RFC3758] is used. In this case, the lifetime is 1751 provided in pr_value. 1753 pr_value: The meaning of this field depends on the PR-SCTP policy 1754 specified by the pr_policy field. It is ignored when 1755 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1756 lifetime in milliseconds is specified. 1758 An sctp_prinfo item always corresponds to the data in msg_iov. 1760 5.3.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1762 This cmsghdr structure specifies SCTP options for sendmsg(). 1764 +--------------+---------------+----------------------+ 1765 | cmsg_level | cmsg_type | cmsg_data[] | 1766 +--------------+---------------+----------------------+ 1767 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1768 +--------------+---------------+----------------------+ 1770 The sctp_authinfo structure is defined below: 1772 struct sctp_authinfo { 1773 uint16_t auth_keyid; 1774 }; 1776 auth_keyid: This specifies the shared key identifier used for 1777 sending the user message. 1779 An sctp_authinfo item always corresponds to the data in msg_iov. 1780 Please note that the SCTP implementation must not bundle user 1781 messages that needs to be authenticated using different shared key 1782 identifiers. 1784 5.3.9. SCTP Destination Address Structure (IPv4) (SCTP_DSTADDRV4) 1786 This cmsghdr structure specifies SCTP options for sendmsg(). 1788 +--------------+----------------+----------------+ 1789 | cmsg_level | cmsg_type | cmsg_data[] | 1790 +--------------+----------------+----------------+ 1791 | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | 1792 +--------------+----------------+----------------+ 1794 This ancillary data can be used to provide more than one destination 1795 address to sendmsg(). It can be used to implement sctp_sendv() using 1796 send_msg(). 1798 5.3.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6) 1800 This cmsghdr structure specifies SCTP options for sendmsg(). 1802 +--------------+----------------+-----------------+ 1803 | cmsg_level | cmsg_type | cmsg_data[] | 1804 +--------------+----------------+-----------------+ 1805 | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | 1806 +--------------+----------------+-----------------+ 1808 This ancillary data can be used to provide more than one destination 1809 address to sendmsg(). It can be used to implement sctp_sendv() using 1810 send_msg(). 1812 6. SCTP Events and Notifications 1814 An SCTP application may need to understand and process events and 1815 errors that happen on the SCTP stack. These events include network 1816 status changes, association startups, remote operational errors and 1817 undeliverable messages. All of these can be essential for the 1818 application. 1820 When an SCTP application layer does a recvmsg() the message read is 1821 normally a data message from a peer endpoint. If the application 1822 wishes to have the SCTP stack deliver notifications of non-data 1823 events, it sets the appropriate socket option for the notifications 1824 it wants. See Section 6.2 for these socket options. When a 1825 notification arrives, recvmsg() returns the notification in the 1826 application-supplied data buffer via msg_iov, and sets 1827 MSG_NOTIFICATION in msg_flags. 1829 This section details the notification structures. Every notification 1830 structure carries some common fields which provide general 1831 information. 1833 A recvmsg() call will return only one notification at a time. Just 1834 as when reading normal data, it may return part of a notification if 1835 the msg_iov buffer is not large enough. If a single read is not 1836 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1837 reading the notification before subsequent data can arrive. 1839 6.1. SCTP Notification Structure 1841 The notification structure is defined as the union of all 1842 notification types. 1844 union sctp_notification { 1845 struct sctp_tlv { 1846 uint16_t sn_type; /* Notification type. */ 1847 uint16_t sn_flags; 1848 uint32_t sn_length; 1849 } sn_header; 1850 struct sctp_assoc_change sn_assoc_change; 1851 struct sctp_paddr_change sn_paddr_change; 1852 struct sctp_remote_error sn_remote_error; 1853 struct sctp_send_failed sn_send_failed; 1854 struct sctp_shutdown_event sn_shutdown_event; 1855 struct sctp_adaptation_event sn_adaptation_event; 1856 struct sctp_pdapi_event sn_pdapi_event; 1857 struct sctp_authkey_event sn_auth_event; 1858 struct sctp_sender_dry_event sn_sender_dry_event; 1859 struct sctp_send_failed_event sn_send_failed_event; 1860 }; 1862 sn_type: The following list describes the SCTP notification and 1863 event types for the field sn_type. 1865 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1866 either been opened or closed. Refer to Section 6.1.1 for 1867 details. 1869 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1870 part of an existing association has experienced a change of 1871 state (e.g. a failure or return to service of the reachability 1872 of an endpoint via a specific transport address). Please see 1873 Section 6.1.2 for data structure details. 1875 SCTP_REMOTE_ERROR: The attached error message is an Operational 1876 Error received from the remote peer. It includes the complete 1877 TLV sent by the remote endpoint. See Section 6.1.3 for the 1878 detailed format. 1880 SCTP_SEND_FAILED_EVENT: The attached datagram could not be sent 1881 to the remote endpoint. This structure includes the original 1882 SCTP_SNDINFO that was used in sending this message i.e. this 1883 structure uses the sctp_sndinfo per Section 6.1.11. 1885 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1886 data should be sent on this socket. 1888 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1889 indicated adaptation layer. Please see Section 6.1.6. 1891 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1892 receiver that the partial delivery has been aborted. This may 1893 indicate the association is about to be aborted. Please see 1894 Section 6.1.7. 1896 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1897 receiver that either an error occurred on authentication, or a 1898 new key was made active. See Section 6.1.8. 1900 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1901 application that the sender has no more user data queued for 1902 transmission nor retransmission. See Section 6.1.9. 1904 sn_flags: These are notification-specific flags. 1906 sn_length: This is the length of the whole sctp_notification 1907 structure including the sn_type, sn_flags, and sn_length fields. 1909 6.1.1. SCTP_ASSOC_CHANGE 1911 Communication notifications inform the application that an SCTP 1912 association has either begun or ended. The identifier for a new 1913 association is provided by this notification. The notification 1914 information has the following format: 1916 struct sctp_assoc_change { 1917 uint16_t sac_type; 1918 uint16_t sac_flags; 1919 uint32_t sac_length; 1920 uint16_t sac_state; 1921 uint16_t sac_error; 1922 uint16_t sac_outbound_streams; 1923 uint16_t sac_inbound_streams; 1924 sctp_assoc_t sac_assoc_id; 1925 uint8_t sac_info[]; 1926 }; 1928 sac_type: It should be SCTP_ASSOC_CHANGE. 1930 sac_flags: Currently unused. 1932 sac_length: This field is the total length of the notification data, 1933 including the notification header. 1935 sac_state: This field holds one of a number of values that 1936 communicate the event that happened to the association. They 1937 include: 1939 SCTP_COMM_UP: A new association is now ready and data may be 1940 exchanged with this peer. When an association has been 1941 established successfully, this notification should be the first 1942 one. 1944 SCTP_COMM_LOST: The association has failed. The association is 1945 now in the closed state. If SEND_FAILED notifications are 1946 turned on, an SCTP_COMM_LOST is accompanied by a series of 1947 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1948 message. 1950 SCTP_RESTART: SCTP has detected that the peer has restarted. 1952 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1954 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1955 blocking mode is set and data was sent (on a one-to-many style 1956 socket), an SCTP_CANT_STR_ASSOC is accompanied by a series of 1957 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1958 message. 1960 sac_error: If the state was reached due to an error condition (e.g. 1961 SCTP_COMM_LOST) any relevant error information is available in 1962 this field. This corresponds to the protocol error codes defined 1963 in [RFC4960]. 1965 sac_outbound_streams: 1967 sac_inbound_streams: The maximum number of streams allowed in each 1968 direction are available in sac_outbound_streams and sac_inbound 1969 streams. 1971 sac_assoc_id: The association id field holds the identifier for the 1972 association. All notifications for a given association have the 1973 same association identifier. For a one-to-one style socket, this 1974 field is ignored. 1976 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1977 received for this association, sac_info[] contains the complete 1978 ABORT chunk as defined in the SCTP specification [RFC4960] Section 1979 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1980 may contain an array of uint8_t describing the features that the 1981 current association supports. Features may include 1983 SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol 1984 extension described in [RFC3758]. 1986 SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol 1987 extension described in [RFC4895]. 1989 SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol 1990 extension described in [RFC5061]. 1992 SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the 1993 local endpoints use separate send and/or receive buffers for 1994 each SCTP association. 1996 6.1.2. SCTP_PEER_ADDR_CHANGE 1998 When a destination address of a multi-homed peer encounters a state 1999 change a peer address change event is sent. The notification has the 2000 following format: 2002 struct sctp_paddr_change { 2003 uint16_t spc_type; 2004 uint16_t spc_flags; 2005 uint32_t spc_length; 2006 struct sockaddr_storage spc_aaddr; 2007 uint32_t spc_state; 2008 uint32_t spc_error; 2009 sctp_assoc_t spc_assoc_id; 2010 } 2012 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 2014 spc_flags: Currently unused. 2016 spc_length: This field is the total length of the notification data, 2017 including the notification header. 2019 spc_aaddr: The affected address field holds the remote peer's 2020 address that is encountering the change of state. 2022 spc_state: This field holds one of a number of values that 2023 communicate the event that happened to the address. They include: 2025 SCTP_ADDR_AVAILABLE: This address is now reachable. This 2026 notification is provided whenever an address becomes reachable. 2028 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 2029 reached. Any data sent to this address is rerouted to an 2030 alternate until this address becomes reachable. This 2031 notification is provided whenever an address becomes 2032 unreachable. 2034 SCTP_ADDR_REMOVED: The address is no longer part of the 2035 association. 2037 SCTP_ADDR_ADDED: The address is now part of the association. 2039 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 2040 primary destination address. This notification is provided 2041 whenever an address is made primary. 2043 spc_error: If the state was reached due to any error condition (e.g. 2044 SCTP_ADDR_UNREACHABLE) any relevant error information is available 2045 in this field. 2047 spc_assoc_id: The association id field holds the identifier for the 2048 association. All notifications for a given association have the 2049 same association identifier. For a one-to-one style socket, this 2050 field is ignored. 2052 6.1.3. SCTP_REMOTE_ERROR 2054 A remote peer may send an Operational Error message to its peer. 2055 This message indicates a variety of error conditions on an 2056 association. The entire ERROR chunk as it appears on the wire is 2057 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 2058 specification [RFC4960] and any extensions for a list of possible 2059 error formats. An SCTP error notification has the following format: 2061 struct sctp_remote_error { 2062 uint16_t sre_type; 2063 uint16_t sre_flags; 2064 uint32_t sre_length; 2065 uint16_t sre_error; 2066 sctp_assoc_t sre_assoc_id; 2067 uint8_t sre_data[]; 2068 }; 2070 sre_type: It should be SCTP_REMOTE_ERROR. 2072 sre_flags: Currently unused. 2074 sre_length: This field is the total length of the notification data, 2075 including the notification header and the contents of sre_data. 2077 sre_error: This value represents one of the Operational Error causes 2078 defined in the SCTP specification, in network byte order. 2080 sre_assoc_id: The association id field holds the identifier for the 2081 association. All notifications for a given association have the 2082 same association identifier. For a one-to-one style socket, this 2083 field is ignored. 2085 sre_data: This contains the ERROR chunk as defined in the SCTP 2086 specification [RFC4960] Section 3.3.10. 2088 6.1.4. SCTP_SEND_FAILED - DEPRECATED 2090 Please note that this notification is deprecated. Use 2091 SCTP_SEND_FAILED_EVENT instead. 2093 If SCTP cannot deliver a message, it can return back the message as a 2094 notification if the SCTP_SEND_FAILED event is enabled. The 2095 notification has the following format: 2097 struct sctp_send_failed { 2098 uint16_t ssf_type; 2099 uint16_t ssf_flags; 2100 uint32_t ssf_length; 2101 uint32_t ssf_error; 2102 struct sctp_sndrcvinfo ssf_info; 2103 sctp_assoc_t ssf_assoc_id; 2104 uint8_t ssf_data[]; 2105 }; 2107 ssf_type: It should be SCTP_SEND_FAILED. 2109 ssf_flags: The flag value will take one of the following values: 2111 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2112 wire. 2114 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2115 Note that this does not necessarily mean that the data was (or 2116 was not) successfully delivered. 2118 ssf_length: This field is the total length of the notification data, 2119 including the notification header and the payload in ssf_data. 2121 ssf_error: This value represents the reason why the send failed, and 2122 if set, will be an SCTP protocol error code as defined in 2123 [RFC4960] Section 3.3.10. 2125 ssf_info: The ancillary data (struct sctp_sndrcvinfo) used to send 2126 the undelivered message. Regardless of if ancillary data is used 2127 or not, the ssf_info.sinfo_flags field indicates if the complete 2128 message or only part of the message is returned in ssf_data. If 2129 only part of the message is returned, it means that the part which 2130 is not present has been sent successfully to the peer. 2132 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2133 flags is set in ssf_info.sinfo_flags. If the first part of the 2134 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2135 This means that the tail end of the message is returned in 2136 ssf_data. 2138 ssf_assoc_id: The association id field, ssf_assoc_id, holds the 2139 identifier for the association. All notifications for a given 2140 association have the same association identifier. For a one-to- 2141 one style socket, this field is ignored. 2143 ssf_data: The undelivered message or part of the undelivered message 2144 will be present in the ssf_data field. Note that the 2145 ssf_info.sinfo_flags field as noted above should be used to 2146 determine if a complete message is present or just a piece of the 2147 message. Note that only user data is present in this field, any 2148 chunk headers or SCTP common headers must be removed by the SCTP 2149 stack. 2151 6.1.5. SCTP_SHUTDOWN_EVENT 2153 When a peer sends a SHUTDOWN, SCTP delivers this notification to 2154 inform the application that it should cease sending data. 2156 struct sctp_shutdown_event { 2157 uint16_t sse_type; 2158 uint16_t sse_flags; 2159 uint32_t sse_length; 2160 sctp_assoc_t sse_assoc_id; 2161 }; 2163 sse_type: It should be SCTP_SHUTDOWN_EVENT. 2165 sse_flags: Currently unused. 2167 sse_length: This field is the total length of the notification data, 2168 including the notification header. It will generally be 2169 sizeof(struct sctp_shutdown_event). 2171 sse_flags: Currently unused. 2173 sse_assoc_id: The association id field holds the identifier for the 2174 association. All notifications for a given association have the 2175 same association identifier. For a one-to-one style socket, this 2176 field is ignored. 2178 6.1.6. SCTP_ADAPTATION_INDICATION 2180 When a peer sends an Adaptation Layer Indication parameter as 2181 described in [RFC5061], SCTP delivers this notification to inform the 2182 application about the peer's adaptation layer indication. 2184 struct sctp_adaptation_event { 2185 uint16_t sai_type; 2186 uint16_t sai_flags; 2187 uint32_t sai_length; 2188 uint32_t sai_adaptation_ind; 2189 sctp_assoc_t sai_assoc_id; 2190 }; 2191 sai_type: It should be SCTP_ADAPTATION_INDICATION. 2193 sai_flags: Currently unused. 2195 sai_length: This field is the total length of the notification data, 2196 including the notification header. It will generally be 2197 sizeof(struct sctp_adaptation_event). 2199 sai_adaptation_ind: This field holds the bit array sent by the peer 2200 in the adaptation layer indication parameter. 2202 sai_assoc_id: The association id field holds the identifier for the 2203 association. All notifications for a given association have the 2204 same association identifier. For a one-to-one style socket, this 2205 field is ignored. 2207 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT 2209 When a receiver is engaged in a partial delivery of a message this 2210 notification will be used to indicate various events. 2212 struct sctp_pdapi_event { 2213 uint16_t pdapi_type; 2214 uint16_t pdapi_flags; 2215 uint32_t pdapi_length; 2216 uint32_t pdapi_indication; 2217 uint32_t pdapi_stream; 2218 uint32_t pdapi_seq; 2219 sctp_assoc_t pdapi_assoc_id; 2220 }; 2222 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 2224 pdapi_flags: Currently unused. 2226 pdapi_length: This field is the total length of the notification 2227 data, including the notification header. It will generally be 2228 sizeof(struct sctp_pdapi_event). 2230 pdapi_indication: This field holds the indication being sent to the 2231 application. Currently there is only one defined value: 2233 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 2234 delivery of a user message has been aborted. This happens, for 2235 example, if an association is aborted while a partial delivery 2236 is going on or the user message gets abandoned using PR-SCTP 2237 while the partial delivery of this message is going on. 2239 pdapi_stream: This field holds the stream on which the partial 2240 delivery event happened. 2242 pdapi_seq: This field holds the stream sequence number which was 2243 being partially delivered. 2245 pdapi_assoc_id: The association id field holds the identifier for 2246 the association. All notifications for a given association have 2247 the same association identifier. For a one-to-one style socket 2248 this field is ignored. 2250 6.1.8. SCTP_AUTHENTICATION_EVENT 2252 [RFC4895] defines an extension to authenticate SCTP messages. The 2253 following notification is used to report different events relating to 2254 the use of this extension. 2256 struct sctp_authkey_event { 2257 uint16_t auth_type; 2258 uint16_t auth_flags; 2259 uint32_t auth_length; 2260 uint16_t auth_keynumber; 2261 uint32_t auth_indication; 2262 sctp_assoc_t auth_assoc_id; 2263 }; 2265 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 2267 auth_flags: Currently unused. 2269 auth_length: This field is the total length of the notification 2270 data, including the notification header. It will generally be 2271 sizeof(struct sctp_authkey_event). 2273 auth_keynumber: This field holds the keynumber for the affected key 2274 indicated in the event (depends on auth_indication). 2276 auth_indication: This field holds the error or indication being 2277 reported. The following values are currently defined: 2279 SCTP_AUTH_NEW_KEY: This report indicates that a new key has been 2280 made active (used for the first time by the peer) and is now 2281 the active key. The auth_keynumber field holds the user 2282 specified key number. 2284 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 2285 support SCTP AUTH as defined in [RFC4895]. 2287 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 2288 implementation will no longer use the key identifier specified 2289 in auth_keynumber. 2291 auth_assoc_id: The association id field holds the identifier for the 2292 association. All notifications for a given association have the 2293 same association identifier. For a one-to-one style socket this 2294 field is ignored. 2296 6.1.9. SCTP_SENDER_DRY_EVENT 2298 When the SCTP stack has no more user data to send or retransmit, this 2299 notification is given to the user. Also, at the time when a user app 2300 subscribes to this event, if there is no data to be sent or 2301 retransmit, the stack will immediately send up this notification. 2303 struct sctp_sender_dry_event { 2304 uint16_t sender_dry_type; 2305 uint16_t sender_dry_flags; 2306 uint32_t sender_dry_length; 2307 sctp_assoc_t sender_dry_assoc_id; 2308 }; 2310 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 2312 sender_dry_flags: Currently unused. 2314 sender_dry_length: This field is the total length of the 2315 notification data, including the notification header. It will 2316 generally be sizeof(struct sctp_sender_dry_event). 2318 sender_dry_assoc_id: The association id field holds the identifier 2319 for the association. All notifications for a given association 2320 have the same association identifier. For a one-to-one style 2321 socket this field is ignored. 2323 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT 2325 SCTP notifications, when subscribed to, are reliable. They are 2326 always delivered as long as there is space in the socket receive 2327 buffer. However, if an implementation experiences a notification 2328 storm, it may run out of socket buffer space. When this occurs it 2329 may wish to disable notifications. If the implementation chooses to 2330 do this, it will append a final notification 2331 SCTP_NOTIFICATIONS_STOPPED_EVENT. This notification is a union 2332 sctp_notification, where only the struct sctp_tlv (see the union 2333 above) is used. It only contains this type in the sn_type field, the 2334 sn_length field set to the sizeof an sctp_tlv structure and the 2335 sn_flags set to 0. If an application receives this notification, it 2336 will need to re-subscribe to any notifications of interest to it, 2337 except for the sctp_data_io_event (note that SCTP_EVENTS is 2338 deprecated). 2340 An endpoint is automatically subscribed to this event as soon as it 2341 is subscribed to any event other than data io events. 2343 6.1.11. SCTP_SEND_FAILED_EVENT 2345 If SCTP cannot deliver a message, it can return back the message as a 2346 notification if the SCTP_SEND_FAILED_EVENT event is enabled. The 2347 notification has the following format: 2349 struct sctp_send_failed_event { 2350 uint16_t ssfe_type; 2351 uint16_t ssfe_flags; 2352 uint32_t ssfe_length; 2353 uint32_t ssfe_error; 2354 struct sctp_sndinfo ssfe_info; 2355 sctp_assoc_t ssfe_assoc_id; 2356 uint8_t ssfe_data[]; 2357 }; 2359 ssfe_type: It should be SCTP_SEND_FAILED_EVENT. 2361 ssfe_flags: The flag value will take one of the following values: 2363 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2364 wire. 2366 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2367 Note that this does not necessarily mean that the data was (or 2368 was not) successfully delivered. 2370 ssfe_length: This field is the total length of the notification 2371 data, including the notification header and the payload in 2372 ssf_data. 2374 ssfe_error: This value represents the reason why the send failed, 2375 and if set, will be an SCTP protocol error code as defined in 2376 [RFC4960] Section 3.3.10. 2378 ssfe_info: The ancillary data (struct sctp_sndinfo) used to send the 2379 undelivered message. Regardless of if ancillary data is used or 2380 not, the ssfe_info.sinfo_flags field indicates if the complete 2381 message or only part of the message is returned in ssf_data. If 2382 only part of the message is returned, it means that the part which 2383 is not present has been sent successfully to the peer. 2385 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2386 flags is set in ssfe_info.sinfo_flags. If the first part of the 2387 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2388 This means that the tail end of the message is returned in 2389 ssf_data. 2391 ssfe_assoc_id: The association id field, ssf_assoc_id, holds the 2392 identifier for the association. All notifications for a given 2393 association have the same association identifier. For a one-to- 2394 one style socket, this field is ignored. 2396 ssfe_data: The undelivered message or part of the undelivered 2397 message will be present in the ssf_data field. Note that the 2398 ssf_info.sinfo_flags field as noted above should be used to 2399 determine if a complete message is present or just a piece of the 2400 message. Note that only user data is present in this field, any 2401 chunk headers or SCTP common headers must be removed by the SCTP 2402 stack. 2404 6.2. Notification Interest Options 2406 6.2.1. SCTP_EVENTS option - DEPRECATED 2408 To receive SCTP event notifications, an application registers its 2409 interest by setting the SCTP_EVENTS socket option. The application 2410 then uses recvmsg() to retrieve notifications. A notification is 2411 stored in the data part (msg_iov) of the struct msghdr. The socket 2412 option uses the following structure: 2414 struct sctp_event_subscribe { 2415 uint8_t sctp_data_io_event; 2416 uint8_t sctp_association_event; 2417 uint8_t sctp_address_event; 2418 uint8_t sctp_send_failure_event; 2419 uint8_t sctp_peer_error_event; 2420 uint8_t sctp_shutdown_event; 2421 uint8_t sctp_partial_delivery_event; 2422 uint8_t sctp_adaptation_layer_event; 2423 uint8_t sctp_authentication_event; 2424 uint8_t sctp_sender_dry_event; 2425 }; 2426 sctp_data_io_event: Setting this flag to 1 will cause the reception 2427 of SCTP_SNDRCV information on a per message basis. The 2428 application will need to use the recvmsg() interface so that it 2429 can receive the event information contained in the msg_control 2430 field. Setting the flag to 0 will disable the reception of the 2431 message control information. Note that this is not really a 2432 notification and this is stored in the ancillary data 2433 (msg_control), not in the data part (msg_iov). 2435 sctp_association_event: Setting this flag to 1 will enable the 2436 reception of association event notifications. Setting the flag to 2437 0 will disable association event notifications. 2439 sctp_address_event: Setting this flag to 1 will enable the reception 2440 of address event notifications. Setting the flag to 0 will 2441 disable address event notifications. 2443 sctp_send_failure_event: Setting this flag to 1 will enable the 2444 reception of send failure event notifications. Setting the flag 2445 to 0 will disable send failure event notifications. 2447 sctp_peer_error_event: Setting this flag to 1 will enable the 2448 reception of peer error event notifications. Setting the flag to 2449 0 will disable peer error event notifications. 2451 sctp_shutdown_event: Setting this flag to 1 will enable the 2452 reception of shutdown event notifications. Setting the flag to 0 2453 will disable shutdown event notifications. 2455 sctp_partial_delivery_event: Setting this flag to 1 will enable the 2456 reception of partial delivery notifications. Setting the flag to 2457 0 will disable partial delivery event notifications. 2459 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 2460 reception of adaptation layer notifications. Setting the flag to 2461 0 will disable adaptation layer event notifications. 2463 sctp_authentication_event: Setting this flag to 1 will enable the 2464 reception of authentication layer notifications. Setting the flag 2465 to 0 will disable authentication layer event notifications. 2467 sctp_sender_dry_event: Setting this flag to 1 will enable the 2468 reception of sender dry notifications. Setting the flag to 0 will 2469 disable sender dry event notifications. 2471 An example where an application would like to receive data io events 2472 and association events but no others would be as follows: 2474 { 2475 struct sctp_event_subscribe events; 2477 memset(&events,0,sizeof(events)); 2479 events.sctp_data_io_event = 1; 2480 events.sctp_association_event = 1; 2482 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 2483 } 2485 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2486 receives ancillary data and notifications for all associations bound 2487 to the file descriptor. For one-to-one style SCTP sockets, the 2488 caller receives ancillary data and notifications only for the single 2489 association bound to the file descriptor. 2491 By default both the one-to-one style and the one-to-many style socket 2492 do not subscribe to any notification. 2494 6.2.2. SCTP_EVENT option 2496 The SCTP_EVENTS socket option has one issue for future compatibility. 2497 As new features are added the structure (sctp_event_subscribe) must 2498 be expanded. This can cause an application binary interface (ABI) 2499 issue unless an implementation has added padding at the end of the 2500 structure. To avoid this problem, SCTP_EVENTS has been deprecated 2501 and a new socket option SCTP_EVENT has taken its place. The option 2502 is used with the following structure: 2504 struct sctp_event { 2505 sctp_assoc_t se_assoc_id; 2506 uint16_t se_type; 2507 uint8_t se_on; 2508 }; 2510 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 2511 sockets. For one-to-many style sockets this field can be a 2512 particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. 2514 se_type: The se_type field can be filled with any value that would 2515 show up in the respective sn_type field (in the sctp_tlv structure 2516 of the notification). 2518 se_on: The se_on field is set to 1 to turn on an event and set to 0 2519 to turn off an event. 2521 To use this option the user fills in this structure and then calls 2522 the setsockopt to turn on or off an individual event. The following 2523 is an example use of this option: 2525 { 2526 struct sctp_event event; 2528 memset(&event, 0, sizeof(event)); 2530 event.se_assoc_id = SCTP_FUTURE_ASSOC; 2531 event.se_type = SCTP_SENDER_DRY_EVENT; 2532 event.se_on = 1; 2533 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2534 } 2536 By default both the one-to-one style and the one-to-many style socket 2537 do not subscribe to any notification. 2539 7. Common Operations for Both Styles 2541 7.1. send(), recv(), sendto(), and recvfrom() 2543 Applications can use send() and sendto() to transmit data to the peer 2544 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2545 data from the peer. 2547 The function prototypes are 2549 ssize_t send(int sd, 2550 const void *msg, 2551 size_t len, 2552 int flags); 2554 ssize_t sendto(int sd, 2555 const void *msg, 2556 size_t len, 2557 int flags, 2558 const struct sockaddr *to, 2559 socklen_t tolen); 2561 ssize_t recv(int sd, 2562 void *buf, 2563 size_t len, 2564 int flags); 2566 ssize_t recvfrom(int sd, 2567 void *buf, 2568 size_t len, 2569 int flags, 2570 struct sockaddr *from, 2571 socklen_t *fromlen); 2573 and the arguments are 2575 sd: The socket descriptor of an SCTP endpoint. 2577 msg: The message to be sent. 2579 len: the size of the message or the size of the buffer. 2581 to: one of the peer addresses of the association to be used to send 2582 the message. 2584 tolen: The size of the address. 2586 buf: The buffer to store a received message. 2588 from: The buffer to store the peer address used to send the received 2589 message. 2591 fromlen: The size of the from address. 2593 flags: (described below). 2595 These calls give access to only basic SCTP protocol features. If 2596 either peer in the association uses multiple streams, or sends 2597 unordered data, these calls will usually be inadequate, and may 2598 deliver the data in unpredictable ways. 2600 SCTP has the concept of multiple streams in one association. The 2601 above calls do not allow the caller to specify on which stream a 2602 message should be sent. The system uses stream 0 as the default 2603 stream for send() and sendto(). recv() and recvfrom() return data 2604 from any stream, but the caller can not distinguish the different 2605 streams. This may result in data seeming to arrive out of order. 2606 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2607 provide no indication. 2609 SCTP is message based. The msg buffer above in send() and sendto() 2610 is considered to be a single message. This means that if the caller 2611 wants to send a message that is composed by several buffers, the 2612 caller needs to combine them before calling send() or sendto(). 2613 Alternately, the caller can use sendmsg() to do that without 2614 combining them. Sending a message using send() or sendto() is atomic 2615 unless explicit EOR marking is enabled on the socket specified by sd. 2616 Using sendto() on a non-connected one-to-one style socket for 2617 implicit connection setup may or may not work depending on the SCTP 2618 implementation. recv() and recvfrom() cannot distinguish message 2619 boundaries (i.e. there is no way to observe the MSG_EOR flag to 2620 detect partial delivery). 2622 In receiving, if the buffer supplied is not large enough to hold a 2623 complete message, the receive call acts like a stream socket and 2624 returns as much data as will fit in the buffer. 2626 Note, the send() and recv() calls may not be used for a one-to-many 2627 style socket. 2629 Note, if an application calls a send() or sendto() function with no 2630 user data the SCTP implementation should reject the request with an 2631 appropriate error message. An implementation is not allowed to send 2632 a DATA chunk with no user data [RFC4960]. 2634 7.2. setsockopt() and getsockopt() 2636 Applications use setsockopt() and getsockopt() to set or retrieve 2637 socket options. Socket options are used to change the default 2638 behavior of socket calls. They are described in Section 8. 2640 The function prototypes are 2642 int getsockopt(int sd, 2643 int level, 2644 int optname, 2645 void *optval, 2646 socklen_t *optlen); 2648 and 2650 int setsockopt(int sd, 2651 int level, 2652 int optname, 2653 const void *optval, 2654 socklen_t optlen); 2656 and the arguments are 2658 sd: The socket descriptor. 2660 level: Set to IPPROTO_SCTP for all SCTP options. 2662 optname: The option name. 2664 optval: The buffer to store the value of the option. 2666 optlen: The size of the buffer (or the length of the option 2667 returned). 2669 They return 0 on success and -1 in case of an error. 2671 All socket options set on a one-to-one style listening socket also 2672 apply to all future accepted sockets. For one-to-many style sockets 2673 often a socket option will pass a structure that includes an assoc_id 2674 field. This field can be filled with the association id of a 2675 particular association and unless otherwise specified can be filled 2676 with one of the following constants: 2678 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2679 after this socket option will be affected by this call. 2681 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2682 associations will be affected by this call, future associations 2683 will still receive the previous default value. 2685 SCTP_ALL_ASSOC: Specifies that all current and future associations 2686 will be affected by this call. 2688 7.3. read() and write() 2690 Applications can use read() and write() to send and receive data to 2691 and from a peer. They have the same semantics as send() and recv() 2692 except that the flags parameter cannot be used. 2694 7.4. getsockname() 2696 Applications use getsockname() to retrieve the locally-bound socket 2697 address of the specified socket. This is especially useful if the 2698 caller let SCTP choose a local port. This call is for single homed 2699 endpoints. It does not work well with multi-homed endpoints. See 2700 Section 9.5 for a multi-homed version of the call. 2702 The function prototype is 2704 int getsockname(int sd, 2705 struct sockaddr *address, 2706 socklen_t *len); 2708 and the arguments are 2710 sd: The socket descriptor to be queried. 2712 address: On return, one locally bound address (chosen by the SCTP 2713 stack) is stored in this buffer. If the socket is an IPv4 socket, 2714 the address will be IPv4. If the socket is an IPv6 socket, the 2715 address will be either an IPv6 or IPv4 address. 2717 len: The caller should set the length of the address here. On 2718 return, this is set to the length of the returned address. 2720 It returns 0 on success and -1 in case of an error. 2722 If the actual length of the address is greater than the length of the 2723 supplied sockaddr structure, the stored address will be truncated. 2725 If the socket has not been bound to a local name, the value stored in 2726 the object pointed to by address is unspecified. 2728 7.5. Implicit Association Setup 2730 The application can begin sending and receiving data using the 2731 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 2732 through any explicit association setup procedures (i.e., no connect() 2733 calls required). 2735 Whenever sendmsg() or sendto() is called and the SCTP stack at the 2736 sender finds that no association exists between the sender and the 2737 intended receiver (identified by the address passed either in the 2738 msg_name field of msghdr structure in the sendmsg() call or the 2739 dest_addr field in the sendto() call), the SCTP stack will 2740 automatically setup an association to the intended receiver. 2742 Upon the successful association setup an SCTP_COMM_UP notification 2743 will be dispatched to the socket at both the sender and receiver 2744 side. This notification can be read by the recvmsg() system call 2745 (see Section 3.1.3). 2747 Note, if the SCTP stack at the sender side supports bundling, the 2748 first user message may be bundled with the COOKIE ECHO message 2749 [RFC4960]. 2751 When the SCTP stack sets up a new association implicitly, the 2752 SCTP_INIT type ancillary data may also be passed along (see 2753 Section 5.3.1 for details of the data structures) to change some 2754 parameters used in setting up a new association. 2756 If this information is not present in the sendmsg() call, or if the 2757 implicit association setup is triggered by a sendto() call, the 2758 default association initialization parameters will be used. These 2759 default association parameters may be set with respective 2760 setsockopt() calls or be left to the system defaults. 2762 Implicit association setup cannot be initiated by send() calls. 2764 8. Socket Options 2766 The following sub-section describes various SCTP level socket options 2767 that are common to both styles. SCTP associations can be multi- 2768 homed. Therefore, certain option parameters include a 2769 sockaddr_storage structure to select which peer address the option 2770 should be applied to. 2772 For the one-to-many style sockets, an sctp_assoc_t (association ID) 2773 parameter is used to identify the association instance that the 2774 operation affects. So it must be set when using this style. 2776 For the one-to-one style sockets and branched off one-to-many style 2777 sockets (see Section 9.2) this association ID parameter is ignored. 2779 Note that socket or IP level options are set or retrieved per socket. 2780 This means that for one-to-many style sockets, the options will be 2781 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2782 association ID) belonging to the socket. For one-to-one style, these 2783 options will be applied to all peer addresses of the association 2784 controlled by the socket. Applications should be careful in setting 2785 those options. 2787 For some IP stacks getsockopt() is read-only; so a new interface will 2788 be needed when information must be passed both into and out of the 2789 SCTP stack. The syntax for sctp_opt_info() is 2791 int sctp_opt_info(int sd, 2792 sctp_assoc_t id, 2793 int opt, 2794 void *arg, 2795 socklen_t *size); 2797 The sctp_opt_info() call is a replacement for getsockopt() only and 2798 will not set any options associated with the specified socket. A 2799 setsockopt() must be used to set any writeable option. 2801 For one-to-many style sockets, id specifies the association to query. 2802 For one-to-one style sockets, id is ignored. For one-to-many 2803 sockets, any association identifier in the structure provided as arg 2804 is ignored and id takes precedence. 2806 Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used with 2807 sctp_opt_info() or in getsockopt() calls. Using them will result in 2808 an error (returning -1 and errno set to EINVAL). SCTP_FUTURE_ASSOC 2809 can be used to query information for future associations. 2811 The field opt specifies which SCTP socket option to get. It can get 2812 any socket option currently supported that requests information 2813 (either read/write options or read only) such as: 2815 SCTP_RTOINFO 2817 SCTP_ASSOCINFO 2819 SCTP_DEFAULT_SEND_PARAM 2821 SCTP_GET_PEER_ADDR_INFO 2823 SCTP_PRIMARY_ADDR 2825 SCTP_PEER_ADDR_PARAMS 2827 SCTP_STATUS 2829 SCTP_CONTEXT 2831 SCTP_AUTH_ACTIVE_KEY 2833 SCTP_PEER_AUTH_CHUNKS 2835 SCTP_LOCAL_AUTH_CHUNKS 2837 The arg field is an option-specific structure buffer provided by the 2838 caller. See the rest of this sections subsections for more 2839 information on these options and option-specific structures. 2841 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2842 sets errno to the appropriate error code. 2844 8.1. Read / Write Options 2846 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2848 The protocol parameters used to initialize and limit the 2849 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2850 information on how these parameters are used in RTO calculation. 2852 The following structure is used to access and modify these 2853 parameters: 2855 struct sctp_rtoinfo { 2856 sctp_assoc_t srto_assoc_id; 2857 uint32_t srto_initial; 2858 uint32_t srto_max; 2859 uint32_t srto_min; 2860 }; 2862 srto_initial: This contains the initial RTO value. 2864 srto_max and srto_min: These contain the maximum and minimum bounds 2865 for all RTOs. 2867 srto_assoc_id: This parameter is ignored for one-to-one style 2868 sockets. For one-to-many style sockets the application may fill 2869 in an association identification or SCTP_FUTURE_ASSOC. It is an 2870 error to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id. 2872 All times are given in milliseconds. A value of 0, when modifying 2873 the parameters, indicates that the current value should not be 2874 changed. 2876 To access or modify these parameters, the application should call 2877 getsockopt() or setsockopt() respectively with the option name 2878 SCTP_RTOINFO. 2880 8.1.2. Association Parameters (SCTP_ASSOCINFO) 2882 This option is used to both examine and set various association and 2883 endpoint parameters. See [RFC4960] for more information on how this 2884 parameter is used. 2886 The following structure is used to access and modify these 2887 parameters: 2889 struct sctp_assocparams { 2890 sctp_assoc_t sasoc_assoc_id; 2891 uint16_t sasoc_asocmaxrxt; 2892 uint16_t sasoc_number_peer_destinations; 2893 uint32_t sasoc_peer_rwnd; 2894 uint32_t sasoc_local_rwnd; 2895 uint32_t sasoc_cookie_life; 2896 }; 2897 sasoc_assoc_id: This parameter is ignored for one-to-one style 2898 sockets. For one-to-many style sockets the application may fill 2899 in an association identification or SCTP_FUTURE_ASSOC. It is an 2900 error to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id. 2902 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2903 to make for the association. 2905 sasoc_number_peer_destinations: This is the number of destination 2906 addresses that the peer has. 2908 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2909 (reported in the last SACK) minus any outstanding data (i.e. data 2910 in flight). 2912 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2913 the peer. 2915 sasoc_cookie_life: This is the association's cookie life value used 2916 when issuing cookies. 2918 The values of the sasoc_peer_rwnd is meaningless when examining 2919 endpoint information (i.e. it is only valid when examining 2920 information on a specific association). 2922 All time values are given in milliseconds. A value of 0, when 2923 modifying the parameters, indicates that the current value should not 2924 be changed. 2926 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2927 on either an endpoint or association basis. The rwnd and destination 2928 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2929 sasoc_local_rwnd) are not settable and any value placed in these is 2930 ignored. 2932 To access or modify these parameters, the application should call 2933 getsockopt() or setsockopt() respectively with the option name 2934 SCTP_ASSOCINFO. 2936 The maximum number of retransmissions before an address is considered 2937 unreachable is also tunable, but is address-specific, so it is 2938 covered in a separate option. If an application attempts to set the 2939 value of the association maximum retransmission parameter to more 2940 than the sum of all maximum retransmission parameters, setsockopt() 2941 may return an error. The reason for this, from [RFC4960] Section 2942 8.2: 2944 Note: When configuring the SCTP endpoint, the user should avoid 2945 having the value of 'Association.Max.Retrans' (sasoc_maxrxt in this 2946 option) larger than the summation of the 'Path.Max.Retrans' (see 2947 Section 8.1.2 on spp_pathmaxrxt) of all the destination addresses for 2948 the remote endpoint. Otherwise, all the destination addresses may 2949 become inactive while the endpoint still considers the peer endpoint 2950 reachable. 2952 8.1.3. Initialization Parameters (SCTP_INITMSG) 2954 Applications can specify protocol parameters for the default 2955 association initialization. The structure used to access and modify 2956 these parameters is defined in Section 5.3.1. The option name 2957 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2959 Setting initialization parameters is effective only on an unconnected 2960 socket (for one-to-many style sockets only future associations are 2961 affected by the change). 2963 8.1.4. SO_LINGER 2965 An application can use this option to perform the SCTP ABORT 2966 primitive. This option affects all associations related to the 2967 socket. 2969 The linger option structure is: 2971 struct linger { 2972 int l_onoff; /* option on/off */ 2973 int l_linger; /* linger time */ 2974 }; 2976 To enable the option, set l_onoff to 1. If the l_linger value is set 2977 to 0, calling close() is the same as the ABORT primitive. If the 2978 value is set to a negative value, the setsockopt() call will return 2979 an error. If the value is set to a positive value linger_time, the 2980 close() can be blocked for at most linger_time ms. If the graceful 2981 shutdown phase does not finish during this period, close() will 2982 return but the graceful shutdown phase will continue in the system. 2984 Note, this is a socket level option, not an SCTP level option. When 2985 using this option, an application must specify a level of SOL_SOCKET 2986 in the call. 2988 8.1.5. SCTP_NODELAY 2990 Turn on/off any Nagle-like algorithm. This means that packets are 2991 generally sent as soon as possible and no unnecessary delays are 2992 introduced, at the cost of more packets in the network. Turning this 2993 option on disables any Nagle-like algorithm. 2995 This option expects an integer boolean flag, where a non-zero value 2996 turns on the option, and a zero value turns off the option. 2998 8.1.6. SO_RCVBUF 3000 Sets the receive buffer size in octets. For SCTP one-to-one style 3001 sockets, this controls the receiver window size. For one-to-many 3002 style sockets the meaning is implementation dependent. It might 3003 control the receive buffer for each association bound to the socket 3004 descriptor or it might control the receive buffer for the whole 3005 socket. This option expects an integer. 3007 Note, this is a socket level option, not an SCTP level option. When 3008 using this option, an application must specify a level of SOL_SOCKET 3009 in the call. 3011 8.1.7. SO_SNDBUF 3013 Sets the send buffer size. For SCTP one-to-one style sockets, this 3014 controls the amount of data SCTP may have waiting in internal buffers 3015 to be sent. This option therefore bounds the maximum size of data 3016 that can be sent in a single send call. For one-to-many style 3017 sockets, the effect is the same, except that it applies to one or all 3018 associations (see Section 3.3) bound to the socket descriptor used in 3019 the setsockopt() or getsockopt() call. The option applies to each 3020 association's window size separately. This option expects an 3021 integer. 3023 Note, this is a socket level option, not an SCTP level option. When 3024 using this option, an application must specify a level of SOL_SOCKET 3025 in the call. 3027 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 3029 This socket option is applicable to the one-to-many style socket 3030 only. When set it will cause associations that are idle for more 3031 than the specified number of seconds to automatically close using the 3032 graceful shutdown procedure. An association being idle is defined as 3033 an association that has not sent or received user data. The special 3034 value of '0' indicates that no automatic close of any association 3035 should be performed, this is the default value. This option expects 3036 an integer defining the number of seconds of idle time before an 3037 association is closed. 3039 An application using this option should enable receiving the 3040 association change notification. This is the only mechanism an 3041 application is informed about the closing of an association. After 3042 an association is closed, the association ID assigned to it can be 3043 reused. An application should be aware of this to avoid the possible 3044 problem of sending data to an incorrect peer endpoint. 3046 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 3048 Requests that the local SCTP stack uses the enclosed peer address as 3049 the association's primary. The enclosed address must be one of the 3050 association peer's addresses. 3052 The following structure is used to make a set peer primary request: 3054 struct sctp_setprim { 3055 sctp_assoc_t ssp_assoc_id; 3056 struct sockaddr_storage ssp_addr; 3057 }; 3059 ssp_addr: The address to set as primary. No wildcard address is 3060 allowed. 3062 ssp_assoc_id: This parameter is ignored for one-to-one style 3063 sockets. For one-to-many style sockets it identifies the 3064 association for this request. Note that the special sctp_assoc_t 3065 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 3067 8.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 3069 Requests that the local endpoint set the specified Adaptation Layer 3070 Indication parameter for all future INIT and INIT-ACK exchanges. 3072 The following structure is used to access and modify this parameter: 3074 struct sctp_setadaptation { 3075 uint32_t ssb_adaptation_ind; 3076 }; 3078 ssb_adaptation_ind: The adaptation layer indicator that will be 3079 included in any outgoing Adaptation Layer Indication parameter. 3081 8.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 3083 This option is a on/off flag and is passed as an integer where a non- 3084 zero is on and a zero is off. If enabled no SCTP message 3085 fragmentation will be performed. The effect of enabling this option 3086 are that if a message being sent exceeds the current PMTU size, the 3087 message will not be sent and instead an error will be indicated to 3088 the user. If this option is disabled (the default) then a message 3089 exceeding the size of the PMTU will be fragmented and reassembled by 3090 the peer. 3092 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 3094 Applications can enable or disable heartbeats for any peer address of 3095 an association, modify an address's heartbeat interval, force a 3096 heartbeat to be sent immediately, and adjust the address's maximum 3097 number of retransmissions sent before an address is considered 3098 unreachable. 3100 The following structure is used to access and modify an address's 3101 parameters: 3103 struct sctp_paddrparams { 3104 sctp_assoc_t spp_assoc_id; 3105 struct sockaddr_storage spp_address; 3106 uint32_t spp_hbinterval; 3107 uint16_t spp_pathmaxrxt; 3108 uint32_t spp_pathmtu; 3109 uint32_t spp_flags; 3110 uint32_t spp_ipv6_flowlabel; 3111 uint8_t spp_ipv4_tos; 3112 }; 3114 spp_assoc_id: This parameter is ignored for one-to-one style 3115 sockets. For one-to-many style sockets it identifies the 3116 association for this query. Note that the predefined constants 3117 are not allowed. 3119 spp_address: This specifies which address is of interest. If a 3120 wildcard address is provided it applies to all current and future 3121 paths. 3123 spp_hbinterval: This contains the value of the heartbeat interval, 3124 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 3125 spp_flag is set to SPP_HB_ENABLE the value of this field is 3126 ignored. Note also that a value of zero indicates the current 3127 setting should be left unchanged. To set an actual value of zero 3128 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 3129 it is set to 0, it does not mean that SCTP will continuously send 3130 out heartbeat since the actual interval also includes the current 3131 RTO and jitter (see Section 8.3 in [RFC4960]). 3133 spp_pathmaxrxt: This contains the maximum number of retransmissions 3134 before this address shall be considered unreachable. Note that a 3135 value of zero indicates the current setting should be left 3136 unchanged. 3138 spp_pathmtu: The current path MTU of the peer address. It is the 3139 number of bytes available in an SCTP packet for chunks. Providing 3140 a value of 0 does not change the current setting. If a positive 3141 value is provided and SPP_PMTUD_DISABLE is set in the spp_flags, 3142 the given value is used as the path MTU. If SPP_PMTUD_ENABLE is 3143 set in the spp_flags, the spp_pathmtu field is ignored. 3145 spp_ipv6_flowlabel: This field is used in conjunction with the 3146 SPP_IPV6_FLOWLABEL flag. This setting has precedence over any 3147 IPv6 layer setting. 3149 spp_ipv4_tos: This field is used in conjunction with the 3150 SPP_IPV4_TOS flag. This setting has precedence over any IPv4 3151 layer setting. 3153 spp_flags: These flags are used to control various features on an 3154 association. The flag field is a bit mask which may contain zero 3155 or more of the following options: 3157 SPP_HB_ENABLE: Enable heartbeats on the specified address. 3159 SPP_HB_DISABLE: Disable heartbeats on the specified address. 3160 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 3161 exclusive, only one of these two should be specified. Enabling 3162 both fields will have undetermined results. 3164 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 3165 immediately. This must not be used in conjunction with a 3166 wildcard address. 3168 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 3169 is to be set to the value of 0 milliseconds. 3171 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 3172 specified address. 3174 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 3175 the specified address. Note that if the address field is empty 3176 then all addresses on the association are affected. Note also 3177 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 3178 exclusive. Enabling both will have undetermined results. 3180 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 3181 IPV6 flowlabel value. The value is obtained in the 3182 spp_ipv6_flowlabel field. 3184 Upon retrieval, this flag will be set to indicate that the 3185 spp_ipv6_flowlabel field has a valid value returned. If a 3186 specific destination address is set (in the spp_address field), 3187 then the value returned is that of the address. If just an 3188 association is specified (and no address), then the 3189 association's default flowlabel is returned. If neither an 3190 association nor a destination is specified, then the socket's 3191 default flowlabel is returned. For non IPv6 sockets, this flag 3192 will be left cleared. 3194 SPP_IPV4_TOS: Setting this flag enables the setting of the IPV4 3195 TOS value associated with either the association or a specific 3196 address. The value is obtained in the spp_ipv4_tos field. 3198 Upon retrieval, this flag will be set to indicate that the 3199 spp_ipv4_tos field has a valid value returned. If a specific 3200 destination address is set when called (in the spp_address 3201 field) then that specific destination address' TOS value is 3202 returned. If just an association is specified then the 3203 association default TOS is returned. If neither an association 3204 nor a destination is specified, then the sockets default TOS is 3205 returned. 3207 To read or modify these parameters, the application should call 3208 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 3210 8.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) - 3211 DEPRECATED 3213 Please note that this options is deprecated. Section 8.1.31 should 3214 be used instead. 3216 Applications that wish to use the sendto() system call may wish to 3217 specify a default set of parameters that would normally be supplied 3218 through the inclusion of ancillary data. This socket option allows 3219 such an application to set the default sctp_sndrcvinfo structure. 3220 The application that wishes to use this socket option simply passes 3221 the sctp_sndrcvinfo structure defined in Section 5.3.2 to this call. 3222 The input parameters accepted by this call include sinfo_stream, 3223 sinfo_flags, sinfo_ppid, sinfo_context, and sinfo_timetolive. The 3224 sinfo_flags is composed of a bitwise OR of SCTP_UNORDERED, SCTP_EOF, 3225 and SCTP_SENDALL. The sinfo_assoc_id field specifies the association 3226 to apply the parameters to. For a one-to-many style socket any of 3227 the predefined constants are also allowed in this field. The field 3228 is ignored on the one-to-one style. 3230 8.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) - 3231 DEPRECATED 3233 This socket option is used to specify various notifications and 3234 ancillary data the user wishes to receive. Please see Section 6.2.1 3235 for a full description of this option and its usage. Note that this 3236 option is considered deprecated and present for backward 3237 compatibility. New applications should use the SCTP_EVENT option. 3238 See Section 6.2.2 for a full description of that option as well. 3240 8.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 3242 This socket option is a boolean flag which turns on or off the 3243 mapping of IPv4 addresses. If this option is turned on, then IPv4 3244 addresses will be mapped to V6 representation. If this option is 3245 turned off, then no mapping will be done of V4 addresses and a user 3246 will receive both PF_INET6 and PF_INET type addresses on the socket. 3247 See [RFC3542] for more details on mapped V6 addresses. 3249 If this socket option is used on a socket of type PF_INET an error is 3250 returned. 3252 By default this option is turned off and expects an integer to be 3253 passed where a non-zero value turns on the option and a zero value 3254 turns off the option. 3256 8.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 3258 This option will get or set the maximum size to put in any outgoing 3259 SCTP DATA chunk. If a message is larger than this size it will be 3260 fragmented by SCTP into the specified size. Note that the underlying 3261 SCTP implementation may fragment into smaller sized chunks when the 3262 PMTU of the underlying association is smaller than the value set by 3263 the user. The default value for this option is '0' which indicates 3264 the user is not limiting fragmentation and only the PMTU will affect 3265 SCTP's choice of DATA chunk size. Note also that values set larger 3266 than the maximum size of an IP datagram will effectively let SCTP 3267 control fragmentation (i.e. the same as setting this option to 0). 3269 The following structure is used to access and modify this parameter: 3271 struct sctp_assoc_value { 3272 sctp_assoc_t assoc_id; 3273 uint32_t assoc_value; 3274 }; 3276 assoc_id: This parameter is ignored for one-to-one style sockets. 3277 For one-to-many style sockets this parameter indicates which 3278 association the user is performing an action upon. It is an error 3279 to use SCTP_{CURRENT|ALL}_ASSOC in assoc_id. 3281 assoc_value: This parameter specifies the maximum size in bytes. 3283 8.1.17. Get or Set the List of Supported HMAC Identifiers 3284 (SCTP_HMAC_IDENT) 3286 This option gets or sets the list of HMAC algorithms that the local 3287 endpoint requires the peer to use. 3289 The following structure is used to get or set these identifiers: 3291 struct sctp_hmacalgo { 3292 uint32_t shmac_number_of_idents; 3293 uint16_t shmac_idents[]; 3294 }; 3296 shmac_number_of_idents: This field gives the number of elements 3297 present in the array shmac_idents. 3299 shmac_idents: This parameter contains an array of HMAC identifiers 3300 that the local endpoint is requesting the peer to use, in priority 3301 order. The following identifiers are valid: 3303 * SCTP_AUTH_HMAC_ID_SHA1 3305 * SCTP_AUTH_HMAC_ID_SHA256 3307 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 3308 may include any of the other values in its preferred order (lowest 3309 list position has the highest preference in algorithm selection). 3310 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 3311 of an unknown HMAC identifier (including optional identifiers unknown 3312 to the implementation) will cause the set option to fail and return 3313 an error. 3315 8.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 3317 This option will get or set the active shared key to be used to build 3318 the association shared key. 3320 The following structure is used to access and modify these 3321 parameters: 3323 struct sctp_authkeyid { 3324 sctp_assoc_t scact_assoc_id; 3325 uint16_t scact_keynumber; 3326 }; 3327 scact_assoc_id: This parameter sets the active key of the specified 3328 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 3329 used. For one-to-one sockets, this parameter is ignored. Note, 3330 however, that this option will set the active key on the 3331 association if the socket is connected, otherwise this will set 3332 the default active key for the endpoint. 3334 scact_keynumber: This parameter is the shared key identifier which 3335 the application is requesting to become the active shared key to 3336 be used for sending authenticated chunks. The key identifier must 3337 correspond to an existing shared key. Note that shared key 3338 identifier '0' defaults to a null key. 3340 When used with setsockopt() the SCTP implementation must use the 3341 indicated shared key identifier for all messages being given to an 3342 SCTP implementation via a send call after the setsockopt() call until 3343 changed again. Therefore, the SCTP implementation must not bundle 3344 user messages which should be authenticated using different shared 3345 key identifiers. 3347 Initially the key with key identifier 0 is the active key. 3349 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 3351 This option will affect the way delayed sacks are performed. This 3352 option allows the application to get or set the delayed sack time, in 3353 milliseconds. It also allows changing the delayed sack frequency. 3354 Changing the frequency to 1 disables the delayed sack algorithm. 3355 Note that if sack_delay or sack_freq are 0 when setting this option, 3356 the current values will remain unchanged. 3358 The following structure is used to access and modify these 3359 parameters: 3361 struct sctp_sack_info { 3362 sctp_assoc_t sack_assoc_id; 3363 uint32_t sack_delay; 3364 uint32_t sack_freq; 3365 }; 3367 sack_assoc_id: This parameter is ignored for one-to-one style 3368 sockets. For one-to-many style sockets this parameter indicates 3369 which association the user is performing an action upon. The 3370 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3372 sack_delay: This parameter contains the number of milliseconds that 3373 the user is requesting the delayed SACK timer to be set to. Note 3374 that this value is defined in the standard to be between 200 and 3375 500 milliseconds. 3377 sack_freq: This parameter contains the number of packets that must 3378 be received before a sack is sent without waiting for the delay 3379 timer to expire. The default value is 2, setting this value to 1 3380 will disable the delayed sack algorithm. 3382 8.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 3384 Fragmented interleave controls how the presentation of messages 3385 occurs for the message receiver. There are three levels of fragment 3386 interleave defined. Two of the levels affect the one-to-one model, 3387 while the one-to-many model is affected by all three levels. 3389 This option takes an integer value. It can be set to a value of 0, 1 3390 or 2. Attempting to set this level to other values will return an 3391 error. 3393 Setting the three levels provides the following receiver 3394 interactions: 3396 level 0: Prevents the interleaving of any messages. This means that 3397 when a partial delivery begins, no other messages will be received 3398 except the message being partially delivered. If another message 3399 arrives on a different stream (or association) that could be 3400 delivered, it will be blocked waiting for the user to read all of 3401 the partially delivered message. 3403 level 1: Allows interleaving of messages that are from different 3404 associations. For the one-to-one model, level 0 and level 1 thus 3405 have the same meaning since a one-to-one socket always receives 3406 messages from the same association. Note that setting the one-to- 3407 many model to this level may cause multiple partial deliveries 3408 from different associations but for any given association, only 3409 one message will be delivered until all parts of a message have 3410 been delivered. This means that one large message, being read 3411 with an association identification of "X", will block other 3412 messages from association "X" from being delivered. 3414 level 2: Allows complete interleaving of messages. This level 3415 requires that the sender carefully observes not only the peer 3416 association identification (or address) but must also pay careful 3417 attention to the stream number. With this option enabled a 3418 partially delivered message may begin being delivered for 3419 association "X" stream "Y" and the next subsequent receive may 3420 return a message from association "X" stream "Z". Note that no 3421 other messages would be delivered for association "X" stream "Y" 3422 until all of stream "Y"'s partially delivered message was read. 3423 Note that this option also affects the one-to-one model. Also 3424 note that for the one-to-many model not only another stream's 3425 message from the same association may be delivered upon the next 3426 receive, some other association's message may be delivered upon 3427 the next receive. 3429 An implementation should default the one-to-many model to level 1. 3430 The reason for this is that otherwise it is possible that a peer 3431 could begin sending a partial message and thus block all other peers 3432 from sending data. However a setting of level 2 requires the 3433 application to not only be aware of the association (via the 3434 association id or peer's address) but also the stream number. The 3435 stream number is not present unless the user has subscribed to the 3436 sctp_data_io_events (see Section 6.2). This is also why we recommend 3437 that the one-to-one model be defaulted to level 0 (level 1 for the 3438 one-to-one model has no effect). Note that an implementation should 3439 return an error if an application attempts to set the level to 2 and 3440 has not subscribed to the sctp_data_io_events. 3442 For applications that have subscribed to events, those events appear 3443 in the normal socket buffer data stream. This means that unless the 3444 user has set the fragmentation interleave level to 0, notifications 3445 may also be interleaved with partially delivered messages. 3447 8.1.21. Set or Get the SCTP Partial Delivery Point 3448 (SCTP_PARTIAL_DELIVERY_POINT) 3450 This option will set or get the SCTP partial delivery point. This 3451 point is the size of a message where the partial delivery API will be 3452 invoked to help free up rwnd space for the peer. Setting this to a 3453 lower value will cause partial deliveries to happen more often. This 3454 option expects an integer that sets or gets the partial delivery 3455 point in bytes. Note also that the call will fail if the user 3456 attempts to set this value larger than the socket receive buffer 3457 size. 3459 Note that any single message having a length smaller than or equal to 3460 the SCTP partial delivery point will be delivered in one single read 3461 call as long as the user provided buffer is large enough to hold the 3462 message. 3464 8.1.22. Set or Get the Use of Extended Receive Info 3465 (SCTP_USE_EXT_RCVINFO) - DEPRECATED 3467 This option will enable or disable the use of the extended version of 3468 the sctp_sndrcvinfo structure. If this option is disabled, then the 3469 normal sctp_sndrcvinfo structure is returned in all receive message 3470 calls. If this option is enabled then the sctp_extrcvinfo structure 3471 is returned in all receive message calls. The default is off. 3473 Note that the sctp_extrcvinfo structure is never used in any send 3474 call. 3476 This option is present for compatibility with older applications and 3477 is deprecated. Future applications should use SCTP_NXTINFO to 3478 retrieve this same information via ancillary data. 3480 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 3482 This option will enable or disable the use of the automatic 3483 generation of ASCONF chunks to add and delete addresses to an 3484 existing association. Note that this option has two caveats namely: 3485 a) it only affects sockets that are bound to all addresses available 3486 to the SCTP stack, and b) the system administrator may have an 3487 overriding control that turns the ASCONF feature off no matter what 3488 setting the socket option may have. 3490 This option expects an integer boolean flag, where a non-zero value 3491 turns on the option, and a zero value turns off the option. 3493 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 3495 This option will allow a user to change the maximum burst of packets 3496 that can be emitted by this association. Note that the default value 3497 is 4, and some implementations may restrict this setting so that it 3498 can only be lowered to positive values. 3500 To set or get this option the user fills in the following structure: 3502 struct sctp_assoc_value { 3503 sctp_assoc_t assoc_id; 3504 uint32_t assoc_value; 3505 }; 3507 assoc_id: This parameter is ignored for one-to-one style sockets. 3508 For one-to-many style sockets this parameter indicates which 3509 association the user is performing an action upon. The special 3510 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3512 assoc_value: This parameter contains the maximum burst. Setting the 3513 value to 0 disables burst mitigation. 3515 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) 3517 The context field in the sctp_sndrcvinfo structure is normally only 3518 used when a failed message is retrieved holding the value that was 3519 sent down on the actual send call. This option allows the setting of 3520 a default context on an association basis that will be received on 3521 reading messages from the peer. This is especially helpful in the 3522 one-to-many model for an application to keep some reference to an 3523 internal state machine that is processing messages on the 3524 association. Note that the setting of this value only affects 3525 received messages from the peer and does not affect the value that is 3526 saved with outbound messages. 3528 To set or get this option the user fills in the following structure: 3530 struct sctp_assoc_value { 3531 sctp_assoc_t assoc_id; 3532 uint32_t assoc_value; 3533 }; 3535 assoc_id: This parameter is ignored for one-to-one style sockets. 3536 For one-to-many style sockets this parameter indicates which 3537 association the user is performing an action upon. The special 3538 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3540 assoc_value: This parameter contains the context. 3542 8.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 3544 This boolean flag is used to enable or disable explicit end of record 3545 (EOR) marking. When this option is enabled, a user may make multiple 3546 send system calls to send a record and must indicate that they are 3547 finished sending a particular record by including the SCTP_EOR flag. 3548 If this boolean flag is disabled then each individual send system 3549 call is considered to have an SCTP_EOR indicator set on it implicitly 3550 without the user having to explicitly add this flag. The default is 3551 off. 3553 This option expects an integer boolean flag, where a non-zero value 3554 turns on the option, and a zero value turns off the option. 3556 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 3558 This option only supports one-to-one style SCTP sockets. If used on 3559 a one-to-many style SCTP socket an error is indicated. 3561 This option expects an integer boolean flag, where a non-zero value 3562 turns on the option, and a zero value turns off the option. 3564 This socket option must not be used after calling bind() or 3565 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 3566 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3567 SCTP sockets bound to the same port must have set the 3568 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3569 having set the SCTP_REUSE_PORT option will fail if there are other 3570 sockets bound to the same port. At most one socket being bound to 3571 the same port may be listening. 3573 It should be noted that the behavior of the socket level socket 3574 option to reuse ports and/or addresses for SCTP sockets is 3575 unspecified. 3577 8.1.28. Set Notification Event (SCTP_EVENT) 3579 This socket option is used to set a specific notification option. 3580 Please see Section 6.2.2 for a full description of this option and 3581 its usage. 3583 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary 3584 Data (SCTP_RECVRCVINFO) 3586 Setting this option specifies that SCTP_RCVINFO defined in 3587 Section 5.3.5 is returned as ancillary data by recvmsg(). 3589 This option expects an integer boolean flag, where a non-zero value 3590 turns on the option, and a zero value turns off the option. 3592 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary 3593 Data (SCTP_RECVNXTINFO) 3595 Setting this option specifies that SCTP_NXTINFO defined in 3596 Section 5.3.6 is returned as ancillary data by recvmsg(). 3598 This option expects an integer boolean flag, where a non-zero value 3599 turns on the option, and a zero value turns off the option. 3601 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) 3603 Applications that wish to use the sendto() system call may wish to 3604 specify a default set of parameters that would normally be supplied 3605 through the inclusion of ancillary data. This socket option allows 3606 such an application to set the default sctp_sndinfo structure. The 3607 application that wishes to use this socket option simply passes the 3608 sctp_sndinfo structure defined in Section 5.3.4 to this call. The 3609 input parameters accepted by this call include snd_sid, snd_flags, 3610 snd_ppid, snd_context. The snd_flags is composed of a bitwise OR of 3611 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The snd_assoc_id field 3612 specifies the association to apply the parameters to. For a one-to- 3613 many style socket any of the predefined constants are also allowed in 3614 this field. The field is ignored on the one-to-one style. 3616 8.2. Read-Only Options 3618 The options defined in this subsection are read-only. Using this 3619 option in a setsockopt() call will result in an error indicating 3620 EOPNOTSUPP. 3622 8.2.1. Association Status (SCTP_STATUS) 3624 Applications can retrieve current status information about an 3625 association, including association state, peer receiver window size, 3626 number of unacked data chunks, and number of data chunks pending 3627 receipt. This information is read-only. 3629 The following structure is used to access this information: 3631 struct sctp_status { 3632 sctp_assoc_t sstat_assoc_id; 3633 int32_t sstat_state; 3634 uint32_t sstat_rwnd; 3635 uint16_t sstat_unackdata; 3636 uint16_t sstat_penddata; 3637 uint16_t sstat_instrms; 3638 uint16_t sstat_outstrms; 3639 uint32_t sstat_fragmentation_point; 3640 struct sctp_paddrinfo sstat_primary; 3641 }; 3643 sstat_assoc_id: This parameter is ignored for one-to-one style 3644 sockets. For one-to-many style sockets it holds the identifier 3645 for the association. All notifications for a given association 3646 have the same association identifier. The special SCTP_{FUTURE| 3647 CURRENT|ALL}_ASSOC cannot be used. 3649 sstat_state: This contains the association's current state, i.e. one 3650 of the following values: 3652 * SCTP_CLOSED 3654 * SCTP_BOUND 3656 * SCTP_LISTEN 3658 * SCTP_COOKIE_WAIT 3659 * SCTP_COOKIE_ECHOED 3661 * SCTP_ESTABLISHED 3663 * SCTP_SHUTDOWN_PENDING 3665 * SCTP_SHUTDOWN_SENT 3667 * SCTP_SHUTDOWN_RECEIVED 3669 * SCTP_SHUTDOWN_ACK_SENT 3671 sstat_rwnd: This contains the association peer's current receiver 3672 window size. 3674 sstat_unackdata: This is the number of unacked data chunks. 3676 sstat_penddata: This is the number of data chunks pending receipt. 3678 sstat_instrms: The number of streams that the peer will be using 3679 outbound. 3681 sstat_outstrms: The number of streams that the endpoint is allowed 3682 to use outbound. 3684 sstat_fragmentation_point: The size at which SCTP fragmentation will 3685 occur. 3687 sstat_primary: This is information on the current primary peer 3688 address. 3690 To access these status values, the application calls getsockopt() 3691 with the option name SCTP_STATUS. 3693 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3695 Applications can retrieve information about a specific peer address 3696 of an association, including its reachability state, congestion 3697 window, and retransmission timer values. This information is read- 3698 only. 3700 The following structure is used to access this information: 3702 struct sctp_paddrinfo { 3703 sctp_assoc_t spinfo_assoc_id; 3704 struct sockaddr_storage spinfo_address; 3705 int32_t spinfo_state; 3706 uint32_t spinfo_cwnd; 3707 uint32_t spinfo_srtt; 3708 uint32_t spinfo_rto; 3709 uint32_t spinfo_mtu; 3710 }; 3712 spinfo_assoc_id: This parameter is ignored for one-to-one style 3713 sockets. For one-to-many style sockets the following applies: 3714 This field may be filled by the application, if so, this field 3715 will have priority in looking up the association instead of using 3716 the address specified in spinfo_address. Note that if the address 3717 does not belong to the association specified then this call will 3718 fail. If the application does not fill in the spinfo_assoc_id, 3719 then the address will be used to lookup the association and on 3720 return this field will have the valid association id. In other 3721 words, this call can be used to translate an address into an 3722 association id. Note that the predefined constants are not 3723 allowed on this option. 3725 spinfo_address: This is filled by the application, and contains the 3726 peer address of interest. 3728 spinfo_state: This contains the peer address' state: 3730 SCTP_UNCONFIRMED: The initial state of a peer address. 3732 SCTP_ACTIVE: The state is entered the first time after path 3733 verification. It can also be entered if the state is 3734 SCTP_INACTIVE and the path supervision detects that the peer 3735 address is reachable again. 3737 SCTP_INACTIVE: This state is entered whenever a path failure is 3738 detected. 3740 spinfo_cwnd: This contains the peer address' current congestion 3741 window. 3743 spinfo_srtt: This contains the peer address' current smoothed round- 3744 trip time calculation in milliseconds. 3746 spinfo_rto: This contains the peer address' current retransmission 3747 timeout value in milliseconds. 3749 spinfo_mtu: The current path MTU of the peer address. It is the 3750 number of bytes available in an SCTP packet for chunks. 3752 8.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3753 (SCTP_PEER_AUTH_CHUNKS) 3755 This option gets a list of chunk types (see [RFC4960]) for a 3756 specified association that the peer requires to be received 3757 authenticated only. 3759 The following structure is used to access these parameters: 3761 struct sctp_authchunks { 3762 sctp_assoc_t gauth_assoc_id; 3763 uint32_t gauth_number_of_chunks 3764 uint8_t gauth_chunks[]; 3765 }; 3767 gauth_assoc_id: This parameter indicates for which association the 3768 user is requesting the list of peer authenticated chunks. For 3769 one-to-one sockets, this parameter is ignored. Note that the 3770 predefined constants are not allowed with this option. 3772 gauth_number_of_chunks: This parameter gives the number of elements 3773 in the array gauth_chunks. 3775 gauth_chunks: This parameter contains an array of chunk types that 3776 the peer is requesting to be authenticated. If the passed in 3777 buffer size is not large enough to hold the list of chunk types, 3778 ENOBUFS is returned. 3780 8.2.4. Get the List of Chunks the Local Endpoint Requires to be 3781 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3783 This option gets a list of chunk types (see [RFC4960]) for a 3784 specified association that the local endpoint requires to be received 3785 authenticated only. 3787 The following structure is used to access these parameters: 3789 struct sctp_authchunks { 3790 sctp_assoc_t gauth_assoc_id; 3791 uint32_t gauth_number_of_chunks; 3792 uint8_t gauth_chunks[]; 3793 }; 3794 gauth_assoc_id: This parameter indicates for which association the 3795 user is requesting the list of local authenticated chunks. For 3796 one-to-one sockets, this parameter is ignored. 3798 gauth_number_of_chunks: This parameter gives the number of elements 3799 in the array gauth_chunks. 3801 gauth_chunks: This parameter contains an array of chunk types that 3802 the local endpoint is requesting to be authenticated. If the 3803 passed in buffer is not large enough to hold the list of chunk 3804 types, ENOBUFS is returned. 3806 8.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3808 This option gets the current number of associations that are attached 3809 to a one-to-many style socket. The option value is an uint32_t. 3810 Note that this number is only a snap shot. This means that the 3811 number of associations may have changed when the caller gets back the 3812 option result. 3814 For a one-to-one style socket, this socket option results in an 3815 error. 3817 8.2.6. Get the Current Identifiers of Associations 3818 (SCTP_GET_ASSOC_ID_LIST) 3820 This option gets the current list of SCTP association identifiers of 3821 the SCTP associations handled by a one-to-many style socket. 3823 The option value has the structure 3825 struct sctp_assoc_ids { 3826 uint32_t gaids_number_of_ids; 3827 sctp_assoc_t gaids_assoc_id[]; 3828 }; 3830 The caller must provide a large enough buffer to hold all association 3831 identifiers. If the buffer is too small, an error must be returned. 3832 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3833 idea how large the buffer has to be. gaids_number_of_ids gives the 3834 number of elements in the array gaids_assoc_id. Note also that some 3835 or all of sctp_assoc_t returned in the array may become invalid by 3836 the time the caller gets back the result. 3838 For a one-to-one style socket, this socket option results in an 3839 error. 3841 8.3. Write-Only Options 3843 The options defined in this subsection are write-only. Using this 3844 option in a getsockopt() or sctp_opt_info() call will result in an 3845 error indicating EOPNOTSUPP. 3847 8.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3849 Requests that the peer marks the enclosed address as the association 3850 primary (see [RFC5061]). The enclosed address must be one of the 3851 association's locally bound addresses. 3853 The following structure is used to make a set peer primary request: 3855 struct sctp_setpeerprim { 3856 sctp_assoc_t sspp_assoc_id; 3857 struct sockaddr_storage sspp_addr; 3858 }; 3860 sspp_addr: The address to set as primary. 3862 sspp_assoc_id: This parameter is ignored for one-to-one style 3863 sockets. For one-to-many style sockets it identifies the 3864 association for this request. Note that the predefined constants 3865 are not allowed on this option. 3867 8.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) 3869 This set option adds a chunk type that the user is requesting to be 3870 received only in an authenticated way. Changes to the list of chunks 3871 will only affect future associations on the socket. 3873 The following structure is used to add a chunk: 3875 struct sctp_authchunk { 3876 uint8_t sauth_chunk; 3877 }; 3879 sauth_chunk: This parameter contains a chunk type that the user is 3880 requesting to be authenticated. 3882 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3883 chunks must not be used. If they are used, an error must be 3884 returned. The usage of this option enables SCTP AUTH in cases where 3885 it is not required by other means (for example the use of dynamic 3886 address reconfiguration). 3888 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3890 This option will set a shared secret key that is used to build an 3891 association shared key. 3893 The following structure is used to access and modify these 3894 parameters: 3896 struct sctp_authkey { 3897 sctp_assoc_t sca_assoc_id; 3898 uint16_t sca_keynumber; 3899 uint16_t sca_keylength; 3900 uint8_t sca_key[]; 3901 }; 3903 sca_assoc_id: This parameter indicates what association the shared 3904 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3905 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3906 ignored. Note, however on one to one sockets, that this option 3907 will set a key on the association if the socket is connected, 3908 otherwise this will set a key on the endpoint. 3910 sca_keynumber: This parameter is the shared key identifier by which 3911 the application will refer to this shared key. If a key of the 3912 specified index already exists, then this new key will replace the 3913 old existing key. Note that shared key identifier '0' defaults to 3914 a null key. 3916 sca_keylength: This parameter is the length of the array sca_key. 3918 sca_key: This parameter contains an array of bytes that is to be 3919 used by the endpoint (or association) as the shared secret key. 3920 Note, if the length of this field is zero, a null key is set. 3922 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3924 This set option indicates that the application will no longer send 3925 user messages using the indicated key identifier. 3927 struct sctp_authkeyid { 3928 sctp_assoc_t scact_assoc_id; 3929 uint16_t scact_keynumber; 3930 }; 3931 scact_assoc_id: This parameter indicates which association the 3932 shared key identifier is being deleted from. The special 3933 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3934 sockets, this parameter is ignored. Note, however, that this 3935 option will deactivate the key from the association if the socket 3936 is connected, otherwise this will deactivate the key from the 3937 endpoint. 3939 scact_keynumber: This parameter is the shared key identifier which 3940 the application is requesting to be deactivated. The key 3941 identifier must correspond to an existing shared key. Note if 3942 this parameter is zero, use of the null key identifier '0' is 3943 deactivated on the endpoint and/or association. 3945 The currently active key cannot be deactivated. 3947 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3949 This set option will delete a shared secret key which has been 3950 deactivated of an SCTP association. 3952 struct sctp_authkeyid { 3953 sctp_assoc_t scact_assoc_id; 3954 uint16_t scact_keynumber; 3955 }; 3957 scact_assoc_id: This parameter indicates which association the 3958 shared key identifier is being deleted from. The special 3959 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3960 sockets, this parameter is ignored. Note, however, that this 3961 option will delete the key from the association if the socket is 3962 connected, otherwise this will delete the key from the endpoint. 3964 scact_keynumber: This parameter is the shared key identifier which 3965 the application is requesting to be deleted. The key identifier 3966 must correspond to an existing shared key and must not be in use 3967 for any packet being sent by the SCTP implementation. This means 3968 in particular, that it must be deactivated first. Note if this 3969 parameter is zero, use of the null key identifier '0' is deleted 3970 from the endpoint and/or association. 3972 Only deactivated keys that are no longer used by an association can 3973 be deleted. 3975 9. New Functions 3977 Depending on the system, the following interface can be implemented 3978 as a system call or library function. 3980 9.1. sctp_bindx() 3982 This function allows the user to bind a specific subset of addresses 3983 or, if the SCTP extension described in [RFC5061] is supported, add or 3984 delete specific addresses. 3986 The function prototype is 3988 int sctp_bindx(int sd, 3989 struct sockaddr *addrs, 3990 int addrcnt, 3991 int flags); 3993 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3994 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3995 or IPv6 addresses. 3997 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3998 Section 3.1.2 for this usage. 4000 addrs is a pointer to an array of one or more socket addresses. Each 4001 address is contained in its appropriate structure. For an IPv6 4002 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 4003 array of sockaddr_in is used. The caller specifies the number of 4004 addresses in the array with addrcnt. Note that the wildcard 4005 addresses cannot be used in combination with non wildcard addresses 4006 on a socket with this function, doing so will result in an error. 4008 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 4009 -1 and sets errno to the appropriate error code. 4011 For SCTP, the port given in each socket address must be the same, or 4012 sctp_bindx() will fail, setting errno to EINVAL. 4014 The flags parameter is formed from the bitwise OR of zero or more of 4015 the following currently defined flags: 4017 o SCTP_BINDX_ADD_ADDR 4019 o SCTP_BINDX_REM_ADDR 4021 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 4022 socket (i.e. endpoint), and SCTP_BINDX_REM_ADDR directs SCTP to 4023 remove the given addresses from the socket. The two flags are 4024 mutually exclusive; if both are given, sctp_bindx() will fail with 4025 EINVAL. A caller may not remove all addresses from a socket; 4026 sctp_bindx() will reject such an attempt with EINVAL. 4028 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 4029 additional addresses with an endpoint after calling bind(). Or use 4030 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 4031 socket is associated with, so that no new association accepted will 4032 be associated with these addresses. If the endpoint supports dynamic 4033 address reconfiguration, an SCTP_BINDX_REM_ADDR or 4034 SCTP_BINDX_ADD_ADDR may cause an endpoint to send the appropriate 4035 message to its peers to change the peers' address lists. 4037 Adding and removing addresses from established associations is an 4038 optional functionality. Implementations that do not support this 4039 functionality should return -1 and set errno to EOPNOTSUPP. 4041 sctp_bindx() can be called on an already bound socket or on an 4042 unbound socket. If the socket is unbound and the first port number 4043 in the addrs is zero, the kernel will choose a port number. All port 4044 numbers after the first one being 0 must also be zero. If the first 4045 port number is not zero, the following port numbers must be zero or 4046 have the same value as the first one. For an already bound socket, 4047 all port numbers provided must be the bound one or 0. 4049 sctp_bindx() is an atomic operation. Therefore, the binding will be 4050 either successful on all addresses or fail on all addresses. If 4051 multiple addresses are provided and the sctp_bindx() call fails there 4052 is no indication which address is responsible for the failure. The 4053 only way to identify the specific error indication is to call 4054 sctp_bindx() sequentially with only one address per call. 4056 9.2. sctp_peeloff() 4058 After an association is established on a one-to-many style socket, 4059 the application may wish to branch off the association into a 4060 separate socket/file descriptor. 4062 This is particularly desirable when, for instance, the application 4063 wishes to have a number of sporadic message senders/receivers remain 4064 under the original one-to-many style socket, but branch off these 4065 associations carrying high volume data traffic into their own 4066 separate socket descriptors. 4068 The application uses the sctp_peeloff() call to branch off an 4069 association into a separate socket (Note the semantics are somewhat 4070 changed from the traditional one-to-one style accept() call). Note 4071 that the new socket is a one-to-one style socket. Thus it will be 4072 confined to operations allowed for a one-to-one style socket. 4074 The function prototype is 4076 int sctp_peeloff(int sd, 4077 sctp_assoc_t assoc_id); 4079 and the arguments are 4081 sd: The original one-to-many style socket descriptor returned from 4082 the socket() system call (see Section 3.1.1). 4084 assoc_id: the specified identifier of the association that is to be 4085 branched off to a separate file descriptor (Note, in a traditional 4086 one-to-one style accept() call, this would be an out parameter, 4087 but for the one-to-many style call, this is an in parameter). 4089 The function returns a non-negative file descriptor representing the 4090 branched-off association, or -1 if an error occurred. The variable 4091 errno is then set appropriately. 4093 9.3. sctp_getpaddrs() 4095 sctp_getpaddrs() returns all peer addresses in an association. 4097 The function prototype is: 4099 int sctp_getpaddrs(int sd, 4100 sctp_assoc_t id, 4101 struct sockaddr **addrs); 4103 On return, addrs will point to a dynamically allocated array of 4104 sockaddr structures of the appropriate type for the socket type. The 4105 caller should use sctp_freepaddrs() to free the memory. Note that 4106 the in/out parameter addrs must not be NULL. 4108 If sd is an IPv4 socket, the addresses returned will be all IPv4 4109 addresses. If sd is an IPv6 socket, the addresses returned can be a 4110 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4111 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4113 For one-to-many style sockets, id specifies the association to query. 4114 For one-to-one style sockets, id is ignored. 4116 On success, sctp_getpaddrs() returns the number of peer addresses in 4117 the association. If there is no association on this socket, 4118 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 4119 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 4120 is undefined. 4122 9.4. sctp_freepaddrs() 4124 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 4126 The function prototype is 4128 void sctp_freepaddrs(struct sockaddr *addrs); 4130 and addrs is the array of peer addresses returned by 4131 sctp_getpaddrs(). 4133 9.5. sctp_getladdrs() 4135 sctp_getladdrs() returns all locally bound address(es) on a socket. 4137 The function prototype is 4139 int sctp_getladdrs(int sd, 4140 sctp_assoc_t id, 4141 struct sockaddr **addrs); 4143 On return, addrs will point to a dynamically allocated array of 4144 sockaddr structures of the appropriate type for the socket type. The 4145 caller should use sctp_freeladdrs() to free the memory. Note that 4146 the in/out parameter addrs must not be NULL. 4148 If sd is an IPv4 socket, the addresses returned will be all IPv4 4149 addresses. If sd is an IPv6 socket, the addresses returned can be a 4150 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4151 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4153 For one-to-many style sockets, id specifies the association to query. 4154 For one-to-one style sockets, id is ignored. 4156 If the id field is set to the value '0' then the locally bound 4157 addresses are returned without regard to any particular association. 4159 On success, sctp_getladdrs() returns the number of local addresses 4160 bound to the socket. If the socket is unbound, sctp_getladdrs() 4161 returns 0, and the value of *addrs is undefined. If an error occurs, 4162 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 4164 9.6. sctp_freeladdrs() 4166 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 4168 The function prototype is 4169 void sctp_freeladdrs(struct sockaddr *addrs); 4171 and addrs is the array of local addresses returned by 4172 sctp_getladdrs(). 4174 9.7. sctp_sendmsg() - DEPRECATED 4176 This function is deprecated, sctp_sendv() (see Section 9.13) should 4177 be used instead. 4179 An implementation may provide a library function (or possibly system 4180 call) to assist the user with the advanced features of SCTP. 4182 The function prototype is 4184 ssize_t sctp_sendmsg(int sd, 4185 const void *msg, 4186 size_t len, 4187 const struct sockaddr *to, 4188 socklen_t tolen, 4189 uint32_t ppid, 4190 uint32_t flags, 4191 uint16_t stream_no, 4192 uint32_t timetolive, 4193 uint32_t context); 4195 and the arguments are: 4197 sd: The socket descriptor. 4199 msg: The message to be sent. 4201 len: The length of the message. 4203 to: The destination address of the message. 4205 tolen: The length of the destination address. 4207 ppid: The same as sinfo_ppid (see Section 5.3.2). 4209 flags: The same as sinfo_flags (see Section 5.3.2). 4211 stream_no: The same as sinfo_stream (see Section 5.3.2). 4213 timetolive: The same as sinfo_timetolive (see Section 5.3.2). 4215 context: The same as sinfo_context (see Section 5.3.2). 4217 The call returns the number of characters sent, or -1 if an error 4218 occurred. The variable errno is then set appropriately. 4220 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 4221 marking is enabled on the socket specified by sd). 4223 Using sctp_sendmsg() on a non-connected one-to-one style socket for 4224 implicit connection setup may or may not work depending on the SCTP 4225 implementation. 4227 9.8. sctp_recvmsg() - DEPRECATED 4229 This function is deprecated, sctp_recvv() (see Section 9.12) should 4230 be used instead. 4232 An implementation may provide a library function (or possibly system 4233 call) to assist the user with the advanced features of SCTP. Note 4234 that in order for the sctp_sndrcvinfo structure to be filled in by 4235 sctp_recvmsg() the caller must enable the sctp_data_io_events with 4236 the SCTP_EVENTS option. Note that the setting of the 4237 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 4238 sctp_sndrcvinfo information to be extended. 4240 The function prototype is 4242 ssize_t sctp_recvmsg(int sd, 4243 void *msg, 4244 size_t len, 4245 struct sockaddr *from, 4246 socklen_t *fromlen 4247 struct sctp_sndrcvinfo *sinfo 4248 int *msg_flags); 4250 and the arguments are 4252 sd: The socket descriptor. 4254 msg: The message buffer to be filled. 4256 len: The length of the message buffer. 4258 from: A pointer to an address to be filled with the sender of this 4259 messages address. 4261 fromlen: An in/out parameter describing the from length. 4263 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 4264 receipt of the message. 4266 msg_flags: A pointer to an integer to be filled with any message 4267 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 4268 field. Options for the receive may also be passed into the value 4269 (e.g. MSG_PEEK). On return from the call, the msg_flags value 4270 will be different than what was sent in to the call. If 4271 implemented via a recvmsg() call, the msg_flags should only 4272 contain the value of the flags from the recvmsg() call. 4274 The call returns the number of bytes received, or -1 if an error 4275 occurred. The variable errno is then set appropriately. 4277 9.9. sctp_connectx() 4279 An implementation may provide a library function (or possibly system 4280 call) to assist the user with associating to an endpoint that is 4281 multi-homed. Much like sctp_bindx() this call allows a caller to 4282 specify multiple addresses at which a peer can be reached. The way 4283 the SCTP stack uses the list of addresses to set up the association 4284 is implementation dependent. This function only specifies that the 4285 stack will try to make use of all the addresses in the list when 4286 needed. 4288 Note that the list of addresses passed in is only used for setting up 4289 the association. It does not necessarily equal the set of addresses 4290 the peer uses for the resulting association. If the caller wants to 4291 find out the set of peer addresses, it must use sctp_getpaddrs() to 4292 retrieve them after the association has been set up. 4294 The function prototype is 4296 int sctp_connectx(int sd, 4297 struct sockaddr *addrs, 4298 int addrcnt, 4299 sctp_assoc_t *id); 4301 and the arguments are: 4303 sd: The socket descriptor. 4305 addrs: An array of addresses. 4307 addrcnt: The number of addresses in the array. 4309 id: An output parameter that if passed in as a non-NULL will return 4310 the association identification for the newly created association 4311 (if successful). 4313 The call returns 0 on success or -1 if an error occurred. The 4314 variable errno is then set appropriately. 4316 9.10. sctp_send() - DEPRECATED 4318 This function is deprecated, sctp_sendv() should be used instead. 4320 An implementation may provide another alternative function or system 4321 call to assist an application with the sending of data without the 4322 use of the CMSG header structures. 4324 The function prototype is 4326 ssize_t sctp_send(int sd, 4327 const void *msg, 4328 size_t len, 4329 const struct sctp_sndrcvinfo *sinfo, 4330 int flags); 4332 and the arguments are 4334 sd: The socket descriptor. 4336 msg: The message to be sent. 4338 len: The length of the message. 4340 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4341 in Section 5.3.2 for a sendmsg() call. 4343 flags: The same flags as used by the sendmsg() call flags (e.g. 4344 MSG_DONTROUTE). 4346 The call returns the number of bytes sent, or -1 if an error 4347 occurred. The variable errno is then set appropriately. 4349 This function call may also be used to terminate an association using 4350 an association identification by setting the sinfo.sinfo_flags to 4351 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4352 to be terminated. In such a case the len of the message can be zero. 4354 Using sctp_send() on a non-connected one-to-one style socket for 4355 implicit connection setup may or may not work depending on the SCTP 4356 implementation. 4358 Sending a message using sctp_send() is atomic unless explicit EOR 4359 marking is enabled on the socket specified by sd. 4361 9.11. sctp_sendx() - DEPRECATED 4363 This function is deprecated, sctp_sendv() should be used instead. 4365 An implementation may provide another alternative function or system 4366 call to assist an application with the sending of data without the 4367 use of the CMSG header structures that also gives a list of 4368 addresses. The list of addresses is provided for implicit 4369 association setup. In such a case the list of addresses serves the 4370 same purpose as the addresses given in sctp_connectx() (see 4371 Section 9.9). 4373 The function prototype is 4375 ssize_t sctp_sendx(int sd, 4376 const void *msg, 4377 size_t len, 4378 struct sockaddr *addrs, 4379 int addrcnt, 4380 struct sctp_sndrcvinfo *sinfo, 4381 int flags); 4383 and the arguments are: 4385 sd: The socket descriptor. 4387 msg: The message to be sent. 4389 len: The length of the message. 4391 addrs: is an array of addresses. 4393 addrcnt: The number of addresses in the array. 4395 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4396 in Section 5.3.2 for a sendmsg() call. 4398 flags: The same flags as used by the sendmsg() call flags (e.g. 4399 MSG_DONTROUTE). 4401 The call returns the number of bytes sent, or -1 if an error 4402 occurred. The variable errno is then set appropriately. 4404 Note that in case of implicit connection setup, on return from this 4405 call the sinfo_assoc_id field of the sinfo structure will contain the 4406 new association id. 4408 This function call may also be used to terminate an association using 4409 an association identification by setting the sinfo.sinfo_flags to 4410 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4411 to be terminated. In such a case the len of the message would be 4412 zero. 4414 Sending a message using sctp_sendx() is atomic unless explicit EOR 4415 marking is enabled on the socket specified by sd. 4417 Using sctp_sendx() on a non-connected one-to-one style socket for 4418 implicit connection setup may or may not work depending on the SCTP 4419 implementation. 4421 9.12. sctp_recvv() 4423 The function prototype is 4425 ssize_t sctp_recvv(int sd, 4426 const struct iovec *iov, 4427 int iovlen, 4428 struct sockaddr *from, 4429 socklen_t *fromlen, 4430 void *info, 4431 socklen_t *infolen, 4432 unsigned int *infotype, 4433 int *flags); 4435 The function sctp_recvv() provides an extensible way for the SCTP 4436 stack to pass up different SCTP attributes associated with a received 4437 message to an application. An implementation may provide 4438 sctp_recvv() as a library function or as a system call. 4440 This document defines two types of attributes which can be returned 4441 by this call, the attribute of the received message and the attribute 4442 of the next message in receive buffer. The caller enables the 4443 SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these 4444 attributes respectively. Attributes of the received message are 4445 returned in struct sctp_rcvinfo (Section 5.3.5) and attributes of the 4446 next message are returned in struct sctp_nxtinfo (Section 5.3.6). If 4447 both options are enabled, both attributes are returned using the 4448 following structure. 4450 struct sctp_recvv_rn { 4451 struct sctp_rcvinfo recvv_rcvinfo; 4452 struct sctp_nxtinfo recvv_nxtinfo; 4453 }; 4455 In future, new structures can be defined to hold new types of 4456 attributes. The new structures do not need to be based on struct 4457 sctp_recvv_rn or struct sctp_rcvinfo. 4459 This function takes the following arguments: 4461 sd: The socket descriptor. 4463 iov: The scatter buffer. Only one user message is returned in this 4464 buffer. 4466 iovlen: The number of elements in iov. 4468 from: A pointer to an address to be filled with the sender of the 4469 received message's address. 4471 fromlen: An in/out parameter describing the from length. 4473 info: A pointer to the buffer to hold the attributes of the received 4474 message. The structure type of info is determined by the 4475 info_type parameter. 4477 infolen: An in/out parameter describing the size of the info buffer. 4479 infotype: In return, *info_type is set to the type of the info 4480 buffer. The current defined values are: 4482 SCTP_RECVV_NOINFO: If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO 4483 options are not enabled, no attribute will be returned. If 4484 only the SCTP_RECVNXTINFO option is enabled but there is no 4485 next message in the buffer, there will also no attribute be 4486 returned. In these cases *info_type will be set to 4487 SCTP_RECVV_NOINFO. 4489 SCTP_RECVV_RCVINFO: The type of info is struct sctp_rcvinfo and 4490 the attribute is about the received message. 4492 SCTP_RECVV_NXTINFO: The type of info is struct sctp_nxtinfo and 4493 the attribute is about the next message in receive buffer. 4494 This is the case when only the SCTP_RECVNXTINFO option is 4495 enabled and there is a next message in buffer. 4497 SCTP_RECVV_RN: The type of info is struct sctp_recvv_rn. The 4498 recvv_rcvinfo field is the attribute of the received message 4499 and the recvv_nxtinfo field is the attribute of the next 4500 message in buffer. This is the case when both SCTP_RECVRCVINFO 4501 and SCTP_RECVNXTINFO options are enabled and there is a next 4502 message in the receive buffer. 4504 flags: A pointer to an integer to be filled with any message flags 4505 (e.g. MSG_NOTIFICATION). Note that this field is an in/out 4506 parameter. Options for the receive may also be passed into the 4507 value (e.g. MSG_PEEK). On return from the call, the flags value 4508 will be different than what was sent in to the call. If 4509 implemented via a recvmsg() call, the flags should only contain 4510 the value of the flags from the recvmsg() call when calling 4511 sctp_recvv() and on return it has the value from msg_flags. 4513 The call returns the number of bytes received, or -1 if an error 4514 occurred. The variable errno is then set appropriately. 4516 9.13. sctp_sendv() 4518 The function prototype is 4520 ssize_t sctp_sendv(int sd, 4521 const struct iovec *iov, 4522 int iovcnt, 4523 struct sockaddr *addrs, 4524 int addrcnt, 4525 void *info, 4526 socklen_t infolen, 4527 unsigned int infotype, 4528 int flags); 4530 The function sctp_sendv() provides an extensible way for an 4531 application to communicate different send attributes to the SCTP 4532 stack when sending a message. An implementation may provide 4533 sctp_sendv() as a library function or a system call. 4535 This document defines three types of attributes which can be used to 4536 describe a message to be sent. They are struct sctp_sndinfo 4537 (Section 5.3.4), struct sctp_prinfo (Section 5.3.7), and struct 4538 sctp_authinfo (Section 5.3.8). The following structure 4539 sctp_sendv_spa is defined to be used when more than one of the above 4540 attributes are needed to describe a message to be sent. 4542 struct sctp_sendv_spa { 4543 uint32_t sendv_flags; 4544 struct sctp_sndinfo sendv_sndinfo; 4545 struct sctp_prinfo sendv_prinfo; 4546 struct sctp_authinfo sendv_authinfo; 4547 }; 4549 The sendv_flags field holds a bit wise OR of SCTP_SEND_SNDINFO_VALID, 4550 SCTP_SEND_PRINFO_VALID and SCTP_SEND_AUTHINFO_VALID indicating if the 4551 sendv_sndinfo/sendv_prinfo/sendv_authinfo fields contain valid 4552 information. 4554 In future, when new send attributes are needed, new structures can be 4555 defined. But those new structures do not need to be based on any of 4556 the above defined structures. 4558 The function takes the following arguments: 4560 sd: The socket descriptor. 4562 iov: The gather buffer. The data in the buffer is treated as one 4563 single user message. 4565 iovcnt: The number of elements in iov. 4567 addrs: An array of addresses to be used to set up an association or 4568 one single address to be used to send the message. Pass in NULL 4569 if the caller does not want to set up an association nor want to 4570 send the message to a specific address. 4572 addrcnt: The number of addresses in the addrs array. 4574 info: A pointer to the buffer containing the attribute associated 4575 with the message to be sent. The type is indicated by info_type 4576 parameter. 4578 infolen: The length in bytes of info. 4580 infotype: Identifies the type of the information provided in info. 4581 The current defined values are: 4583 SCTP_SENDV_SNDINFO: The type of info is struct sctp_sndinfo. 4585 SCTP_SENDV_PRINFO: The type of info is struct sctp_prinfo. 4587 SCTP_SENDV_AUTHINFO: The type of info is struct sctp_authinfo. 4589 SCTP_SENDV_SPA: The type of info is struct sctp_sendv_spa. 4591 flags: The same flags as used by the sendmsg() call flags (e.g. 4592 MSG_DONTROUTE). 4594 The call returns the number of bytes sent, or -1 if an error 4595 occurred. The variable errno is then set appropriately. 4597 A note on one-to-many style socket. The struct sctp_sndinfo 4598 attribute must always be used in order to specify the association the 4599 message is to be sent on. The only case where it is not needed is 4600 when this call is used to set up a new association. 4602 The caller provides a list of addresses in the addrs parameter to set 4603 up an association. This function will behave like calling 4604 sctp_connectx() (see Section 9.9) first using the list of addresses 4605 and then calling sendmsg() with the given message and attributes. 4606 For an one-to-many style socket, if struct sctp_sndinfo attribute is 4607 provided, the snd_assoc_id field must be 0. When this function 4608 returns, the snd_assoc_id field will contain the association ID of 4609 the newly established association. Note that struct sctp_sndinfo 4610 attribute is not required to set up an association for one-to-many 4611 style socket. If this attribute is not provided, the caller can 4612 enable the SCTP_ASSOC_CHANGE notification and use the SCTP_COMM_UP 4613 message to find out the association ID. 4615 If the caller wants to send the message to a specific peer address 4616 (hence overriding the primary address), it can provide the specific 4617 address in the addrs parameter and provide a struct sctp_sndinfo 4618 attribute with the field snd_flags set to SCTP_ADDR_OVER. 4620 This function call may also be used to terminate an association. The 4621 caller provides an sctp_sndinfo attribute with the snd_flags set to 4622 SCTP_EOF. In this case the len of the message would be zero. 4624 Sending a message using sctp_sendv() is atomic unless explicit EOR 4625 marking is enabled on the socket specified by sd. 4627 10. IANA Considerations 4629 This document requires no actions from IANA. 4631 11. Security Considerations 4633 Many TCP and UDP implementations reserve port numbers below 1024 for 4634 privileged users. If the target platform supports privileged users, 4635 the SCTP implementation should restrict the ability to call bind() or 4636 sctp_bindx() on these port numbers to privileged users. 4638 Similarly unprivileged users should not be able to set protocol 4639 parameters that could result in the congestion control algorithm 4640 being more aggressive than permitted on the public Internet. These 4641 parameters are: 4643 o struct sctp_rtoinfo 4645 If an unprivileged user inherits a one-to-many style socket with open 4646 associations on a privileged port, it may be permitted to accept new 4647 associations, but it should not be permitted to open new 4648 associations. This could be relevant for the r* family of protocols. 4650 Applications using the one-to-many style sockets and using the 4651 interleave level if 0 are subject to denial of service attacks as 4652 described in Section 8.1.20. 4654 12. Acknowledgments 4656 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 4657 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 4658 early formation of this document. 4660 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 4661 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 4662 Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG 4663 mailing list for contributing valuable comments. 4665 A special thanks to Phillip Conrad, for his suggested text, quick and 4666 constructive insights, and most of all his persistent fighting to 4667 keep the interface to SCTP usable for the application programmer. 4669 13. References 4671 13.1. Normative References 4673 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 4674 Stevens, "Basic Socket Interface Extensions for IPv6", 4675 RFC 3493, February 2003. 4677 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4678 "Advanced Sockets Application Program Interface (API) for 4679 IPv6", RFC 3542, May 2003. 4681 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 4682 Conrad, "Stream Control Transmission Protocol (SCTP) 4683 Partial Reliability Extension", RFC 3758, May 2004. 4685 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 4686 "Authenticated Chunks for the Stream Control Transmission 4687 Protocol (SCTP)", RFC 4895, August 2007. 4689 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 4690 RFC 4960, September 2007. 4692 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 4693 Kozuka, "Stream Control Transmission Protocol (SCTP) 4694 Dynamic Address Reconfiguration", RFC 5061, 4695 September 2007. 4697 13.2. Informative References 4699 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4700 RFC 793, September 1981. 4702 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4703 August 1980. 4705 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 4706 Functional Specification", RFC 1644, July 1994. 4708 Appendix A. One-to-One Style Code Example 4710 The following code is an implementation of a simple client which 4711 sends a number of messages marked for unordered delivery to an echo 4712 server making use of all outgoing streams. The example shows how to 4713 use some features of one-to-one style IPv4 SCTP sockets, including: 4715 o Creating and connecting an SCTP socket. 4717 o Requesting to negotiate a number of outgoing streams. 4719 o Determining the negotiated number of outgoing streams. 4721 o Setting an adaptation layer indication. 4723 o Sending messages with a given payload protocol identifier on a 4724 particular stream using sctp_sendv(). 4726 #include 4727 #include 4728 #include 4729 #include 4730 #include 4731 #include 4732 #include 4733 #include 4734 #include 4736 #define PORT 9 4737 #define ADDR "127.0.0.1" 4738 #define SIZE_OF_MESSAGE 1000 4739 #define NUMBER_OF_MESSAGES 10 4740 #define PPID 1234 4742 int 4743 main(void) { 4744 unsigned int i; 4745 int sd; 4746 struct sockaddr_in addr; 4747 char buffer[SIZE_OF_MESSAGE]; 4748 struct iovec iov; 4749 struct sctp_status status; 4750 struct sctp_initmsg init; 4751 struct sctp_sndinfo info; 4752 struct sctp_setadaptation ind; 4753 socklen_t opt_len; 4755 /* Create a one-to-one style SCTP socket. */ 4756 if ((sd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) < 0) { 4757 perror("socket"); 4758 exit(1); 4759 } 4761 /* Prepare for requesting 2048 outgoing streams. */ 4762 memset(&init, 0, sizeof(init)); 4763 init.sinit_num_ostreams = 2048; 4764 if (setsockopt(sd, IPPROTO_SCTP, SCTP_INITMSG, 4765 &init, (socklen_t)sizeof(init)) < 0) { 4766 perror("setsockopt"); 4767 exit(1); 4768 } 4769 ind.ssb_adaptation_ind = 0x01020304; 4770 if (setsockopt(sd, IPPROTO_SCTP, SCTP_ADAPTATION_LAYER, 4771 &ind, (socklen_t)sizeof(ind)) < 0) { 4772 perror("setsockopt"); 4773 exit(1); 4774 } 4776 /* Connect to the discard server. */ 4777 memset(&addr, 0, sizeof(addr)); 4778 #ifdef HAVE_SIN_LEN 4779 addr.sin_len = sizeof(struct sockaddr_in); 4780 #endif 4781 addr.sin_family = AF_INET; 4782 addr.sin_port = htons(PORT); 4783 addr.sin_addr.s_addr = inet_addr(ADDR); 4784 if (connect(sd, 4785 (const struct sockaddr *)&addr, 4786 sizeof(struct sockaddr_in)) < 0) { 4787 perror("connect"); 4788 exit(1); 4789 } 4791 /* Get the actual number of outgoing streams. */ 4792 memset(&status, 0, sizeof(status)); 4793 opt_len = (socklen_t)sizeof(status); 4794 if (getsockopt(sd, IPPROTO_SCTP, SCTP_STATUS, 4795 &status, &opt_len) < 0) { 4796 perror("getsockopt"); 4797 exit(1); 4798 } 4800 memset(&info, 0, sizeof(info)); 4801 info.snd_ppid = htonl(PPID); 4802 info.snd_flags = SCTP_UNORDERED; 4803 memset(buffer, 'A', SIZE_OF_MESSAGE); 4804 iov.iov_base = buffer; 4805 iov.iov_len = SIZE_OF_MESSAGE; 4806 for (i = 0; i < NUMBER_OF_MESSAGES; i++) { 4807 info.snd_sid = i % status.sstat_outstrms; 4808 if (sctp_sendv(sd, 4809 (const struct iovec *)&iov, 1, 4810 NULL, 0, 4811 &info, sizeof(info), SCTP_SENDV_SNDINFO, 4812 0) < 0) { 4813 perror("sctp_sendv"); 4814 exit(1); 4815 } 4816 } 4817 if (close(sd) < 0) { 4818 perror("close"); 4819 exit(1); 4820 } 4821 return(0); 4822 } 4824 Appendix B. One-to-Many Style Code Example 4826 The following code is a simple implementation of a discard server 4827 over SCTP. The example shows how to use some features of one-to-many 4828 style IPv6 SCTP sockets, including: 4830 o Opening and binding of a socket. 4832 o Enabling notifications. 4834 o Handling notifications. 4836 o Configuring the auto close timer. 4838 o Using sctp_recvv() to receive messages. 4840 Please note that this server can be used in combination with the 4841 client described in Appendix A. 4843 #include 4844 #include 4845 #include 4846 #include 4847 #include 4848 #include 4849 #include 4850 #include 4851 #include 4853 #define BUFFER_SIZE (1<<16) 4854 #define PORT 9 4855 #define ADDR "0.0.0.0" 4856 #define TIMEOUT 5 4858 static void 4859 print_notification(void *buf) 4860 { 4861 struct sctp_assoc_change *sac; 4862 struct sctp_paddr_change *spc; 4863 struct sctp_adaptation_event *sad; 4864 union sctp_notification *snp; 4865 char addrbuf[INET6_ADDRSTRLEN]; 4866 const char *ap; 4867 struct sockaddr_in *sin; 4868 struct sockaddr_in6 *sin6; 4870 snp = buf; 4872 switch (snp->sn_header.sn_type) { 4873 case SCTP_ASSOC_CHANGE: 4874 sac = &snp->sn_assoc_change; 4875 printf("^^^ Association change: "); 4876 switch (sac->sac_state) { 4877 case SCTP_COMM_UP: 4878 printf("Communication up (streams (in/out)=(%u/%u)).\n", 4879 sac->sac_inbound_streams, sac->sac_outbound_streams); 4880 break; 4881 case SCTP_COMM_LOST: 4882 printf("Communication lost (error=%d).\n", sac->sac_error); 4883 break; 4884 case SCTP_RESTART: 4885 printf("Communication restarted (streams (in/out)=(%u/%u).\n", 4886 sac->sac_inbound_streams, sac->sac_outbound_streams); 4887 break; 4888 case SCTP_SHUTDOWN_COMP: 4889 printf("Communication completed.\n"); 4890 break; 4891 case SCTP_CANT_STR_ASSOC: 4892 printf("Communication couldn't be started.\n"); 4893 break; 4894 default: 4895 printf("Unknown state: %d.\n", sac->sac_state); 4896 break; 4897 } 4898 break; 4899 case SCTP_PEER_ADDR_CHANGE: 4900 spc = &snp->sn_paddr_change; 4901 if (spc->spc_aaddr.ss_family == AF_INET) { 4902 sin = (struct sockaddr_in *)&spc->spc_aaddr; 4903 ap = inet_ntop(AF_INET, &sin->sin_addr, 4904 addrbuf, INET6_ADDRSTRLEN); 4905 } else { 4906 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 4907 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 4908 addrbuf, INET6_ADDRSTRLEN); 4909 } 4910 printf("^^^ Peer Address change: %s ", ap); 4911 switch (spc->spc_state) { 4912 case SCTP_ADDR_AVAILABLE: 4913 printf("is available.\n"); 4914 break; 4915 case SCTP_ADDR_UNREACHABLE: 4916 printf("is not available (error=%d).\n", spc->spc_error); 4917 break; 4918 case SCTP_ADDR_REMOVED: 4919 printf("was removed.\n"); 4920 break; 4921 case SCTP_ADDR_ADDED: 4922 printf("was added.\n"); 4923 break; 4924 case SCTP_ADDR_MADE_PRIM: 4925 printf("is primary.\n"); 4926 break; 4927 default: 4928 printf("unknown state (%d).\n", spc->spc_state); 4929 break; 4930 } 4931 break; 4932 case SCTP_SHUTDOWN_EVENT: 4933 printf("^^^ Shutdown received.\n"); 4934 break; 4935 case SCTP_ADAPTATION_INDICATION: 4936 sad = &snp->sn_adaptation_event; 4937 printf("^^^ Adaptation indication 0x%08x received.\n", 4938 sad->sai_adaptation_ind); 4939 break; 4940 default: 4941 printf("^^^ Unknown event of type: %u.\n", 4942 snp->sn_header.sn_type); 4943 break; 4944 }; 4945 } 4947 int 4948 main(void) { 4949 int sd, flags, timeout; 4950 ssize_t n; 4951 unsigned int i; 4952 union { 4953 struct sockaddr sa; 4954 struct sockaddr_in sin; 4955 struct sockaddr_in6 sin6; 4956 } addr; 4957 socklen_t fromlen, infolen; 4958 struct sctp_rcvinfo info; 4959 unsigned int infotype; 4960 struct iovec iov; 4961 char buffer[BUFFER_SIZE]; 4962 struct sctp_event event; 4963 uint16_t event_types[] = {SCTP_ASSOC_CHANGE, 4964 SCTP_PEER_ADDR_CHANGE, 4965 SCTP_SHUTDOWN_EVENT, 4966 SCTP_ADAPTATION_INDICATION }; 4968 /* Create a 1-to-many style SCTP socket. */ 4969 if ((sd = socket(AF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP)) < 0) { 4970 perror("socket"); 4971 exit(1); 4972 } 4974 /* Enable the events of interest. */ 4975 memset(&event, 0, sizeof(event)); 4976 event.se_assoc_id = SCTP_FUTURE_ASSOC; 4977 event.se_on = 1; 4978 for (i = 0; i < sizeof(event_types)/sizeof(uint16_t); i++) { 4979 event.se_type = event_types[i]; 4980 if (setsockopt(sd, IPPROTO_SCTP, SCTP_EVENT, 4981 &event, sizeof(event)) < 0) { 4982 perror("setsockopt"); 4983 exit(1); 4984 } 4985 } 4987 /* Configure auto-close timer. */ 4988 timeout = TIMEOUT; 4989 if (setsockopt(sd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 4990 &timeout, 4) < 0) { 4991 perror("setsockopt SCTP_AUTOCLOSE"); 4992 exit(1); 4993 } 4995 /* Bind the socket to all local addresses. */ 4996 memset(&addr, 0, sizeof(addr)); 4997 #ifdef HAVE_SIN6_LEN 4998 addr.sin6.sin6_len = sizeof(addr.sin6); 4999 #endif 5000 addr.sin6.sin6_family = AF_INET6; 5001 addr.sin6.sin6_port = htons(PORT); 5002 addr.sin6.sin6_addr = in6addr_any; 5003 if (bind(sd, &addr.sa, sizeof(addr.sin6)) < 0) { 5004 perror("bind"); 5005 exit(1); 5006 } 5007 /* Enable accepting associations. */ 5008 if (listen(sd, 1) < 0) { 5009 perror("listen"); 5010 exit(1); 5011 } 5013 for (;;) { 5014 flags = 0; 5015 memset(&addr, 0, sizeof(addr)); 5016 fromlen = (socklen_t)sizeof(addr); 5017 memset(&info, 0, sizeof(info)); 5018 infolen = (socklen_t)sizeof(info); 5019 infotype = 0; 5020 iov.iov_base = buffer; 5021 iov.iov_len = BUFFER_SIZE; 5023 n = sctp_recvv(sd, &iov, 1, 5024 &addr.sa, &fromlen, 5025 &info, &infolen, &infotype, 5026 &flags); 5028 if (flags & MSG_NOTIFICATION) { 5029 print_notification(iov.iov_base); 5030 } else { 5031 char addrbuf[INET6_ADDRSTRLEN]; 5032 char *ap; 5033 in_port_t port; 5035 if (addr.sa.sa_family == AF_INET) { 5036 ap = inet_ntop(AF_INET, &addr.sin.sin_addr, 5037 addrbuf, INET6_ADDRSTRLEN); 5038 port = ntohs(addr.sin.sin_port); 5039 } else { 5040 ap = inet_ntop(AF_INET6, &addr.sin6.sin6_addr, 5041 addrbuf, INET6_ADDRSTRLEN); 5042 port = ntohs(addr.sin6.sin6_port); 5043 } 5044 printf("Message received from %s:%u: len=%d", 5045 ap, port, (int)n); 5046 switch (infotype) { 5047 case SCTP_RECVV_RCVINFO: 5048 printf(", sid=%u", info.rcv_sid); 5049 if (info.rcv_flags & SCTP_UNORDERED) { 5050 printf(", unordered"); 5051 } else { 5052 printf(", ssn=%u", info.rcv_ssn); 5053 } 5054 printf(", tsn=%u", info.rcv_tsn); 5055 printf(", ppid=%u.\n", ntohl(info.rcv_ppid)); 5056 break; 5057 case SCTP_RECVV_NOINFO: 5058 case SCTP_RECVV_NXTINFO: 5059 case SCTP_RECVV_RN: 5060 printf(".\n"); 5061 break; 5062 default: 5063 printf(" unknown infotype.\n"); 5064 } 5065 } 5066 } 5068 if (close(sd) < 0) { 5069 perror("close"); 5070 exit(1); 5071 } 5073 return (0); 5074 } 5076 Authors' Addresses 5078 Randall R. Stewart 5079 Huawei 5080 Chapin, SC 29036 5081 USA 5083 Email: randall@lakerest.net 5085 Michael Tuexen 5086 Muenster University of Applied Sciences 5087 Stegerwaldstr. 39 5088 48565 Steinfurt 5089 Germany 5091 Email: tuexen@fh-muenster.de 5093 Kacheong Poon 5094 Oracle Corporation 5096 Email: ka-cheong.poon@oracle.com 5097 Peter Lei 5098 Cisco Systems, Inc. 5099 9501 Technology Blvd 5100 West Office Center 5101 Rosemont, IL 60018 5102 USA 5104 Email: peterlei@cisco.com 5106 Vladislav Yasevich 5107 HP 5108 110 Spitrook Rd 5109 Nashua, NH 03062 5110 USA 5112 Email: vladislav.yasevich@hp.com