idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-26.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 28, 2011) is 4837 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: August 1, 2011 Muenster Univ. of Applied 6 Sciences 7 K. Poon 8 Oracle Corporation 9 P. Lei 10 Cisco Systems, Inc. 11 V. Yasevich 12 HP 13 January 28, 2011 15 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 16 draft-ietf-tsvwg-sctpsocket-26.txt 18 Abstract 20 This document describes a mapping of the Stream Control Transmission 21 Protocol (SCTP) into a sockets API. The benefits of this mapping 22 include compatibility for TCP applications, access to new SCTP 23 features and a consolidated error and event notification scheme. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on August 1, 2011. 42 Copyright Notice 44 Copyright (c) 2011 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 This document may contain material from IETF Documents or IETF 58 Contributions published or made publicly available before November 59 10, 2008. The person(s) controlling the copyright in some of this 60 material may not have granted the IETF Trust the right to allow 61 modifications of such material outside the IETF Standards Process. 62 Without obtaining an adequate license from the person(s) controlling 63 the copyright in such materials, this document may not be modified 64 outside the IETF Standards Process, and derivative works of it may 65 not be created outside the IETF Standards Process, except to format 66 it for publication as an RFC or to translate it into languages other 67 than English. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 72 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8 74 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8 75 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 9 76 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 10 77 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 11 78 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 12 79 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 14 80 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 14 81 3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 15 82 3.3. Special considerations . . . . . . . . . . . . . . . . . 16 83 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . 18 84 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 18 85 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 19 86 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 19 87 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 21 88 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . 21 89 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 22 90 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 23 91 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . 23 92 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 24 93 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 24 94 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 25 95 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 25 96 5.2. Ancillary Data Considerations and Semantics . . . . . . . 26 97 5.2.1. Multiple Items and Ordering . . . . . . . . . . . . . 26 98 5.2.2. Accessing and Manipulating Ancillary Data . . . . . . 27 99 5.2.3. Control Message Buffer Sizing . . . . . . . . . . . . 27 100 5.3. SCTP msg_control Structures . . . . . . . . . . . . . . . 28 101 5.3.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 29 102 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - 103 DEPRECATED . . . . . . . . . . . . . . . . . . . . . 30 104 5.3.3. Extended SCTP Header Information Structure 105 (SCTP_EXTRCV) - DEPRECATED . . . . . . . . . . . . . 33 106 5.3.4. SCTP Send Information Structure (SCTP_SNDINFO) . . . 34 107 5.3.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 36 108 5.3.6. SCTP Next Receive Information Structure 109 (SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . 37 110 5.3.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . 39 111 5.3.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) . . . 39 112 5.3.9. SCTP Destination Address Structure (IPv4) 113 (SCTP_DSTADDRV4) . . . . . . . . . . . . . . . . . . 40 114 5.3.10. SCTP Destination Address Structure (IPv6) 115 (SCTP_DSTADDRV6) . . . . . . . . . . . . . . . . . . 40 116 6. SCTP Events and Notifications . . . . . . . . . . . . . . . . 40 117 6.1. SCTP Notification Structure . . . . . . . . . . . . . . . 41 118 6.1.1. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 43 119 6.1.2. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 44 120 6.1.3. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 46 121 6.1.4. SCTP_SEND_FAILED - DEPRECATED . . . . . . . . . . . . 46 122 6.1.5. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 48 123 6.1.6. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . 48 124 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 49 125 6.1.8. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 50 126 6.1.9. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 51 127 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . 51 128 6.1.11. SCTP_SEND_FAILED_EVENT . . . . . . . . . . . . . . . 52 129 6.2. Notification Interest Options . . . . . . . . . . . . . . 53 130 6.2.1. SCTP_EVENTS option - DEPRECATED . . . . . . . . . . . 53 131 6.2.2. SCTP_EVENT option . . . . . . . . . . . . . . . . . . 55 132 7. Common Operations for Both Styles . . . . . . . . . . . . . . 56 133 7.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . 56 134 7.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 58 135 7.3. read() and write() . . . . . . . . . . . . . . . . . . . 59 136 7.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 59 137 7.5. Implicit Association Setup . . . . . . . . . . . . . . . 60 138 8. Socket Options . . . . . . . . . . . . . . . . . . . . . . . 61 139 8.1. Read / Write Options . . . . . . . . . . . . . . . . . . 62 140 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . 62 141 8.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 63 142 8.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . 65 143 8.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 65 144 8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . 66 145 8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 66 146 8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 66 147 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . 66 148 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 67 149 8.1.10. Set Adaptation Layer Indicator 150 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 67 151 8.1.11. Enable/Disable Message Fragmentation 152 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . 68 153 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 68 154 8.1.13. Set Default Send Parameters 155 (SCTP_DEFAULT_SEND_PARAM) - DEPRECATED . . . . . . . 70 156 8.1.14. Set Notification and Ancillary Events 157 (SCTP_EVENTS) - DEPRECATED . . . . . . . . . . . . . 71 158 8.1.15. Set/Clear IPv4 Mapped Addresses 159 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . 71 160 8.1.16. Get or Set the Maximum Fragmentation Size 161 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 71 162 8.1.17. Get or Set the List of Supported HMAC Identifiers 163 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 72 164 8.1.18. Get or Set the Active Shared Key 165 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . 72 166 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 73 167 8.1.20. Get or Set Fragmented Interleave 168 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . 74 169 8.1.21. Set or Get the SCTP Partial Delivery Point 170 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 75 171 8.1.22. Set or Get the Use of Extended Receive Info 172 (SCTP_USE_EXT_RCVINFO) - DEPRECATED . . . . . . . . . 76 173 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . 76 174 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 76 175 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 77 176 8.1.26. Enable or Disable Explicit EOR Marking 177 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 77 178 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . 78 179 8.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 78 180 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as 181 Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 78 182 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as 183 Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 78 184 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . 79 185 8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 79 186 8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . 79 187 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . 81 188 8.2.3. Get the List of Chunks the Peer Requires to be 189 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 82 190 8.2.4. Get the List of Chunks the Local Endpoint Requires 191 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . 82 192 8.2.5. Get the Current Number of Associations 193 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 83 194 8.2.6. Get the Current Identifiers of Associations 195 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . 83 196 8.3. Write-Only Options . . . . . . . . . . . . . . . . . . . 84 197 8.3.1. Set Peer Primary Address 198 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . 84 199 8.3.2. Add a Chunk That Must Be Authenticated 200 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 84 201 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . 85 202 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . 85 203 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . 86 204 9. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 86 205 9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . 87 206 9.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . 88 207 9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . 89 208 9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 90 209 9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . 90 210 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 90 211 9.7. sctp_sendmsg() - DEPRECATED . . . . . . . . . . . . . . . 91 212 9.8. sctp_recvmsg() - DEPRECATED . . . . . . . . . . . . . . . 92 213 9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 93 214 9.10. sctp_send() - DEPRECATED . . . . . . . . . . . . . . . . 94 215 9.11. sctp_sendx() - DEPRECATED . . . . . . . . . . . . . . . . 95 216 9.12. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . 96 217 9.13. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 98 218 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 100 219 11. Security Considerations . . . . . . . . . . . . . . . . . . . 101 220 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 101 221 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 101 222 13.1. Normative References . . . . . . . . . . . . . . . . . . 101 223 13.2. Informative References . . . . . . . . . . . . . . . . . 102 224 Appendix A. One-to-One Style Code Example . . . . . . . . . . . 102 225 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 105 226 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 110 228 1. Introduction 230 The sockets API has provided a standard mapping of the Internet 231 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 232 [RFC0768] have benefited from this standard representation and access 233 method across many diverse platforms. SCTP is a new protocol that 234 provides many of the characteristics of TCP but also incorporates 235 semantics more akin to UDP. This document defines a method to map 236 the existing sockets API for use with SCTP, providing both a base for 237 access to new features and compatibility so that most existing TCP 238 applications can be migrated to SCTP with few (if any) changes. 240 There are three basic design objectives: 242 1. Maintain consistency with existing sockets APIs: We define a 243 sockets mapping for SCTP that is consistent with other sockets 244 API protocol mappings (for instance UDP, TCP, IPv4, and IPv6). 246 2. Support a one-to-many style interface: This set of semantics is 247 similar to that defined for connection-less protocols, such as 248 UDP. A one-to-many style SCTP socket should be able to control 249 multiple SCTP associations. This is similar to a UDP socket, 250 which can communicate with many peer endpoints. Each of these 251 associations is assigned an association ID so that an application 252 can use the ID to differentiate them. Note that SCTP is 253 connection-oriented in nature, and it does not support broadcast 254 or multicast communications, as UDP does. 256 3. Support a one-to-one style interface: This interface supports a 257 similar semantics as sockets for connection-oriented protocols, 258 such as TCP. A one-to-one style SCTP socket should only control 259 one SCTP association. One purpose of defining this interface is 260 to allow existing applications built on other connection-oriented 261 protocols to be ported to use SCTP with very little effort. 262 Developers familiar with these semantics can easily adapt to 263 SCTP. Another purpose is to make sure that existing mechanisms 264 in most operating systems that support sockets, such as select(), 265 should continue to work with this style of socket. Extensions 266 are added to this mapping to provide mechanisms to exploit new 267 features of SCTP. 269 Goals 2 and 3 are not compatible, so this document defines two modes 270 of mapping, namely the one-to-many style mapping and the one-to-one 271 style mapping. These two modes share some common data structures and 272 operations, but will require the use of two different application 273 programming styles. Note that all new SCTP features can be used with 274 both styles of socket. The decision on which one to use depends 275 mainly on the nature of applications. 277 A mechanism is defined to extract a one-to-many style SCTP 278 association into a one-to-one style socket. 280 Some of the SCTP mechanisms cannot be adequately mapped to an 281 existing socket interface. In some cases, it is more desirable to 282 have a new interface instead of using existing socket calls. 283 Section 9 of this document describes these new interfaces. 285 2. Data Types 287 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 288 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 289 (e.g. uint16_t). This document also assumes the argument data types 290 from 1003.1g when possible (e.g. the final argument to setsockopt() 291 is a size_t value). Whenever buffer sizes are specified, the POSIX 292 1003.1 size_t data type is used. 294 3. One-to-Many Style Interface 296 In the one-to-many style interface there is a 1 to many relationship 297 between sockets and associations. 299 3.1. Basic Operation 301 A typical server in this style uses the following socket calls in 302 sequence to prepare an endpoint for servicing requests: 304 o socket() 306 o bind() 308 o listen() 310 o recvmsg() 312 o sendmsg() 314 o close() 316 A typical client uses the following calls in sequence to setup an 317 association with a server to request services: 319 o socket() 321 o sendmsg() 322 o recvmsg() 324 o close() 326 In this style, by default, all the associations connected to the 327 endpoint are represented with a single socket. Each association is 328 assigned an association ID (type is sctp_assoc_t) so that an 329 application can use it to differentiate among them. In some 330 implementations, the peer endpoints' addresses can also be used for 331 this purpose. But this is not required for performance reasons. If 332 an implementation does not support using addresses to differentiate 333 between different associations, the sendto() call can only be used to 334 setup an association implicitly. It cannot be used to send data to 335 an established association as the association ID cannot be specified. 337 Once an association ID is assigned to an SCTP association, that ID 338 will not be reused until the application explicitly terminates the 339 use of the association. The resources belonging to that association 340 will not be freed until that happens. This is similar to the close() 341 operation on a normal socket. The only exception is when the 342 SCTP_AUTOCLOSE option (section 7.1.8) is set. In this case, after 343 the association is terminated gracefully and automatically, the 344 association ID assigned to it can be reused. All applications using 345 this option should be aware of this to avoid the possible problem of 346 sending data to an incorrect peer endpoint. 348 If the server or client wishes to branch an existing association off 349 to a separate socket, it is required to call sctp_peeloff() and to 350 specify the association identifier. The sctp_peeloff() call will 351 return a new one-to-one style socket which can then be used with 352 recv() and send() functions for message passing. See Section 9.2 for 353 more on branched-off associations. 355 Once an association is branched off to a separate socket, it becomes 356 completely separated from the original socket. All subsequent 357 control and data operations to that association must be done through 358 the new socket. For example, the close operation on the original 359 socket will not terminate any associations that have been branched 360 off to a different socket. 362 One-to-many style socket calls are discussed in more detail in the 363 following subsections. 365 3.1.1. socket() 367 Applications use socket() to create a socket descriptor to represent 368 an SCTP endpoint. 370 The function prototype is 372 int socket(int domain, 373 int type, 374 int protocol); 376 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 377 type and IPPROTO_SCTP as the protocol. 379 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 380 socket. 382 The function returns a socket descriptor or -1 in case of an error. 384 Using the PF_INET domain indicates the creation of an endpoint which 385 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 386 can use both IPv6 and IPv4 addresses. 388 3.1.2. bind() 390 Applications use bind() to specify which local address and port the 391 SCTP endpoint should associate itself with. 393 An SCTP endpoint can be associated with multiple addresses. To do 394 this, sctp_bindx() is introduced in Section 9.1 to help applications 395 do the job of associating multiple addresses. But note that an 396 endpoint can only be associated with one local port. 398 These addresses associated with a socket are the eligible transport 399 addresses for the endpoint to send and receive data. The endpoint 400 will also present these addresses to its peers during the association 401 initialization process, see [RFC4960]. 403 After calling bind(), if the endpoint wishes to accept new 404 associations on the socket, it must call listen() (see 405 Section 3.1.3). 407 The function prototype of bind() is 409 int bind(int sd, 410 struct sockaddr *addr, 411 socklen_t addrlen); 413 and the arguments are 414 sd: The socket descriptor returned by socket(). 416 addr: The address structure (struct sockaddr_in for an IPv4 address 417 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 419 addrlen: The size of the address structure. 421 It returns 0 on success and -1 in case of an error. 423 If sd is an IPv4 socket, the address passed must be an IPv4 address. 424 If the sd is an IPv6 socket, the address passed can either be an IPv4 425 or an IPv6 address. 427 Applications cannot call bind() multiple times to associate multiple 428 addresses to an endpoint. After the first call to bind(), all 429 subsequent calls will return an error. 431 If the IP address part of addr is specified as a wildcard (INADDR_ANY 432 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 433 IPv6 address), the operating system will associate the endpoint with 434 an optimal address set of the available interfaces. If the IPv4 435 sin_port or IPv6 sin6_port is set to 0, the operating system will 436 choose an ephemeral port for the endpoint. 438 If a bind() is not called prior to a sendmsg() call that initiates a 439 new association, the system picks an ephemeral port and will choose 440 an address set equivalent to binding with a wildcard address. One of 441 those addresses will be the primary address for the association. 442 This automatically enables the multi-homing capability of SCTP. 444 The completion of this bind() process does not allow the SCTP 445 endpoint to accept inbound SCTP association requests. Until a 446 listen() system call, described below, is performed on the socket, 447 the SCTP endpoint will promptly reject an inbound SCTP INIT request 448 with an SCTP ABORT. 450 3.1.3. listen() 452 By default, a one-to-many style socket does not accept new 453 association requests. An application uses listen() to mark a socket 454 as being able to accept new associations. 456 The function prototype is 458 int listen(int sd, 459 int backlog); 461 and the arguments are 462 sd: The socket descriptor of the endpoint. 464 backlog: If backlog is non-zero, enable listening, else disable 465 listening. 467 It returns 0 on success and -1 in case of an error. 469 Note that one-to-many style socket consumers do not need to call 470 accept to retrieve new associations. Calling accept() on a one-to- 471 many style socket should return EOPNOTSUPP. Rather, new associations 472 are accepted automatically, and notifications of the new associations 473 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 474 these notifications are enabled). Clients will typically not call 475 listen(), so that they can be assured that only actively initiated 476 associations are possible on the socket. Server or peer-to-peer 477 sockets, on the other hand, will always accept new associations, so a 478 well-written application using server one-to-many style sockets must 479 be prepared to handle new associations from unwanted peers. 481 Also note that the SCTP_ASSOC_CHANGE event provides the association 482 ID for a new association, so if applications wish to use the 483 association ID as a parameter to other socket calls, they should 484 ensure that the SCTP_ASSOC_CHANGE event is enabled. 486 3.1.4. sendmsg() and recvmsg() 488 An application uses the sendmsg() and recvmsg() call to transmit data 489 to and receive data from its peer. 491 The function prototypes are 493 ssize_t sendmsg(int sd, 494 const struct msghdr *message, 495 int flags); 497 and 499 ssize_t recvmsg(int sd, 500 struct msghdr *message, 501 int flags); 503 using the arguments: 505 sd: The socket descriptor of the endpoint. 507 message: Pointer to the msghdr structure which contains a single 508 user message and possibly some ancillary data. See Section 5 for 509 complete description of the data structures. 511 flags: No new flags are defined for SCTP at this level. See 512 Section 5 for SCTP specific flags used in the msghdr structure. 514 sendmsg() returns the number of bytes accepted by the kernel or -1 in 515 case of an error. recvmsg() returns the number of bytes received or 516 -1 in case of an error. 518 As described in Section 5, different types of ancillary data can be 519 sent and received along with user data. When sending, the ancillary 520 data is used to specify the sent behavior, such as the SCTP stream 521 number to use. When receiving, the ancillary data is used to 522 describe the received data, such as the SCTP stream sequence number 523 of the message. 525 When sending user data with sendmsg(), the msg_name field in the 526 msghdr structure will be filled with one of the transport addresses 527 of the intended receiver. If there is no existing association 528 between the sender and the intended receiver, the sender's SCTP stack 529 will set up a new association and then send the user data (see 530 Section 7.5 for more on implicit association setup). If sendmsg() is 531 called with no data and there is no existing association, a new one 532 will be established. The SCTP_INIT type ancillary data can be used 533 to change some of the parameters used to set up a new association. 534 If sendmsg() is called with NULL data, and there is no existing 535 association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is 536 returned and errno is set to EINVAL. Sending a message using 537 sendmsg() is atomic unless explicit EOR marking is enabled on the 538 socket specified by sd (see Section 8.1.26). 540 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 541 be delivered if that notification has been enabled, and no more data 542 can be sent to that association. Any attempt to send more data will 543 cause sendmsg() to return with an ESHUTDOWN error. Note that the 544 socket is still open for reading at this point so it is possible to 545 retrieve notifications. 547 When receiving a user message with recvmsg(), the msg_name field in 548 the msghdr structure will be populated with the source transport 549 address of the user data. The caller of recvmsg() can use this 550 address information to determine to which association the received 551 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 552 disabled, applications must use the peer transport address provided 553 in the msg_name field by recvmsg() to perform correlation to an 554 association, since they will not have the association ID. 556 If all data in a single message has been delivered, MSG_EOR will be 557 set in the msg_flags field of the msghdr structure (see Section 5.1). 559 If the application does not provide enough buffer space to completely 560 receive a data message, MSG_EOR will not be set in msg_flags. 561 Successive reads will consume more of the same message until the 562 entire message has been delivered, and MSG_EOR will be set. 564 If the SCTP stack is running low on buffers, it may partially deliver 565 a message. In this case, MSG_EOR will not be set, and more calls to 566 recvmsg() will be necessary to completely consume the message. Only 567 one message at a time can be partially delivered in any stream. The 568 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 569 what interlacing of messages occurs for both the one-to-one and the 570 one-to-many model sockets. Please consult Section 8.1.20 for further 571 details on message delivery options. 573 3.1.5. close() 575 Applications use close() to perform graceful shutdown (as described 576 in Section 10.1 of [RFC4960]) on all the associations currently 577 represented by a one-to-many style socket. 579 The function prototype is 581 int close(int sd); 583 and the argument is 585 sd: The socket descriptor of the associations to be closed. 587 0 is returned on success and -1 in case of an error. 589 To gracefully shutdown a specific association represented by the one- 590 to-many style socket, an application should use the sendmsg() call, 591 and include the SCTP_EOF flag. A user may optionally terminate an 592 association non-gracefully by sending with the SCTP_ABORT flag set 593 and possibly passing a user specified abort code in the data field. 594 Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data 595 (see Section 5.3.2) in the sendmsg() call. 597 If sd in the close() call is a branched-off socket representing only 598 one association, the shutdown is performed on that association only. 600 3.1.6. connect() 602 An application may use the connect() call in the one-to-many style to 603 initiate an association without sending data. 605 The function prototype is 607 int connect(int sd, 608 const struct sockaddr *nam, 609 socklen_t len); 611 and the arguments are 613 sd: The socket descriptor to have a new association added to. 615 nam: The address structure (struct sockaddr_in for an IPv4 address 616 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 618 len: The size of the address. 620 0 is returned on success and -1 in case of an error. 622 Multiple connect() calls can be made on the same socket to create 623 multiple associations. This is different from the semantics of 624 connect() on a UDP socket. 626 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 627 during the association set up phase. If an application wants to do 628 this, it cannot use the connect() call. Instead, it should use 629 sendto() or sendmsg() to initiate an association. If it uses 630 sendto() and it wants to change the initialization behavior, it needs 631 to use the SCTP_INITMSG socket option before calling sendto(). Or it 632 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 633 association without calling setsockopt(). Note that the implicit 634 setup is supported for the one-to-many style sockets. 636 SCTP does not support half close semantics. This means that unlike 637 T/TCP, MSG_EOF should not be set in the flags parameter when calling 638 sendto() or sendmsg() when the call is used to initiate a connection. 639 MSG_EOF is not an acceptable flag with an SCTP socket. 641 3.2. Non-blocking mode 643 Some SCTP application may wish to avoid being blocked when calling a 644 socket interface function. 646 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 647 one-to-many style socket, an application may set the non-blocking 648 option by a fcntl() (such as O_NONBLOCK). After setting the socket 649 to non-blocking mode, the sendmsg() function returns immediately. 650 The success or failure of sending the data message (with possible 651 SCTP_INITMSG ancillary data) will be signaled by the 652 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or SCTP_CANT_START_ASSOC. 654 If user data could not be sent (due to a SCTP_CANT_START_ASSOC), the 655 sender will also receive an SCTP_SEND_FAILED_EVENT event. Events can 656 be received by the user calling recvmsg(). A server (having called 657 listen()) is also notified of an association up event by the 658 reception of an SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling 659 of recvmsg() and possibly the reception of the first data message. 661 To shutdown the association gracefully, the user must call sendmsg() 662 with no data and with the SCTP_EOF flag set. The function returns 663 immediately, and completion of the graceful shutdown is indicated by 664 an SCTP_ASSOC_CHANGE notification of type SHUTDOWN_COMPLETE (see 665 Section 6.1.1). Note that this can also be done using the 666 sctp_send() call described in Section 9.10. 668 An application is recommended to use caution when using select() (or 669 poll()) for writing on a one-to-many style socket. The reason being 670 that the interpretation of select on write is implementation 671 specific. Generally a positive return on a select on write would 672 only indicate that one of the associations represented by the one-to- 673 many socket is writable. An application that writes after the 674 select() returns may still block since the association that was 675 writeable is not the destination association of the write call. 676 Likewise select() (or poll()) for reading from a one-to-many socket 677 will only return an indication that one of the associations 678 represented by the socket has data to be read. 680 An application that wishes to know that a particular association is 681 ready for reading or writing should either use the one-to-one style 682 or use the sctp_peeloff() (see Section 9.2) function to separate the 683 association of interest from the one-to-many socket. 685 Note some implementations may have an extended select call such as 686 epoll or kqueue that may escape this limitation and allow a select on 687 a specific association of a one-to-many socket, but this is an 688 implementation specific detail that a portable application cannot 689 depend on. 691 3.3. Special considerations 693 The fact that a one-to-many style socket can provide access to many 694 SCTP associations through a single socket descriptor has important 695 implications for both application programmers and system programmers 696 implementing this API. A key issue is how buffer space inside the 697 sockets layer is managed. Because this implementation detail 698 directly affects how application programmers must write their code to 699 ensure correct operation and portability, this section provides some 700 guidance to both implementers and application programmers. 702 An important feature that SCTP shares with TCP is flow control. 703 Specifically, a sender may not send data faster than the receiver can 704 consume it. 706 For TCP, flow control is typically provided for in the sockets API as 707 follows. If the reader stops reading, the sender queues messages in 708 the socket layer until it uses all of its socket buffer space 709 allocation creating a "stalled connection". Further attempts to 710 write to the socket will block or return the error EAGAIN or 711 EWOULDBLOCK for a non-blocking socket. At some point, either the 712 connection is closed, or the receiver begins to read again freeing 713 space in the output queue. 715 For one-to-one style SCTP sockets (this includes sockets descriptors 716 that were separated from a one-to-many style socket with 717 sctp_peeloff()) the behavior is identical. For one-to-many style 718 SCTP sockets there are multiple associations for a single socket, 719 which makes the situation more complicated. If the implementation 720 uses a single buffer space allocation shared by all associations, a 721 single stalled association can prevent the further sending of data on 722 all associations active on a particular one-to-many style socket. 724 For a blocking socket, it should be clear that a single stalled 725 association can block the entire socket. For this reason, 726 application programmers may want to use non-blocking one-to-many 727 style sockets. The application should at least be able to send 728 messages to the non-stalled associations. 730 But a non-blocking socket is not sufficient if the API implementer 731 has chosen a single shared buffer allocation for the socket. A 732 single stalled association would eventually cause the shared 733 allocation to fill, and it would become impossible to send even to 734 non-stalled associations. 736 The API implementer can solve this problem by providing each 737 association with its own allocation of outbound buffer space. Each 738 association should conceptually have as much buffer space as it would 739 have if it had its own socket. As a bonus, this simplifies the 740 implementation of sctp_peeloff(). 742 To ensure that a given stalled association will not prevent other 743 non-stalled associations from being writable, application programmers 744 should either: 746 o demand that the underlying implementation dedicates independent 747 buffer space reservation to each association (as suggested above), 748 or 750 o verify that their application layer protocol does not permit large 751 amounts of unread data at the receiver (this is true of some 752 request-response protocols, for example), or 754 o use one-to-one style sockets for association which may potentially 755 stall (either from the beginning, or by using sctp_peeloff before 756 sending large amounts of data that may cause a stalled condition). 758 4. One-to-One Style Interface 760 The goal of this style is to follow as closely as possible the 761 current practice of using the sockets interface for a connection 762 oriented protocol, such as TCP. This style enables existing 763 applications using connection oriented protocols to be ported to SCTP 764 with very little effort. 766 One-to-one style sockets can be connected (explicitly or implicitly) 767 at most once, similar to TCP sockets. 769 Note that some new SCTP features and some new SCTP socket options can 770 only be utilized through the use of sendmsg() and recvmsg() calls, 771 see Section 4.1.8. 773 4.1. Basic Operation 775 A typical server in one-to-one style uses the following system call 776 sequence to prepare an SCTP endpoint for servicing requests: 778 o socket() 780 o bind() 782 o listen() 784 o accept() 786 The accept() call blocks until a new association is set up. It 787 returns with a new socket descriptor. The server then uses the new 788 socket descriptor to communicate with the client, using recv() and 789 send() calls to get requests and send back responses. 791 Then it calls 793 o close() 795 to terminate the association. 797 A typical client uses the following system call sequence to setup an 798 association with a server to request services: 800 o socket() 802 o connect() 804 After returning from connect(), the client uses send()/sendmsg() and 805 recv()/recvmsg() calls to send out requests and receive responses 806 from the server. 808 The client calls 810 o close() 812 to terminate this association when done. 814 4.1.1. socket() 816 Applications call socket() to create a socket descriptor to represent 817 an SCTP endpoint. 819 The function prototype is 821 int socket(int domain, 822 int type, 823 int protocol); 825 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 826 type and IPPROTO_SCTP as the protocol. 828 Here, SOCK_STREAM indicates the creation of a one-to-one style 829 socket. 831 Using the PF_INET domain indicates the creation of an endpoint which 832 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 833 can use both IPv6 and IPv4 addresses. 835 4.1.2. bind() 837 Applications use bind() to specify which local address and port the 838 SCTP endpoint should associate itself with. 840 An SCTP endpoint can be associated with multiple addresses. To do 841 this, sctp_bindx() is introduced in Section 9.1 to help applications 842 do the job of associating multiple addresses. But note that an 843 endpoint can only be associated with one local port. 845 These addresses associated with a socket are the eligible transport 846 addresses for the endpoint to send and receive data. The endpoint 847 will also present these addresses to its peers during the association 848 initialization process, see [RFC4960]. 850 The function prototype of bind() is 852 int bind(int sd, 853 struct sockaddr *addr, 854 socklen_t addrlen); 856 and the arguments are 858 sd: The socket descriptor returned by socket(). 860 addr: The address structure (struct sockaddr_in for an IPv4 address 861 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 863 addrlen: The size of the address structure. 865 If sd is an IPv4 socket, the address passed must be an IPv4 address. 866 If sd is an IPv6 socket, the address passed can either be an IPv4 or 867 an IPv6 address. 869 Applications cannot call bind() multiple times to associate multiple 870 addresses to the endpoint. After the first call to bind(), all 871 subsequent calls will return an error. 873 If the IP address part of addr is specified as a wildcard (INADDR_ANY 874 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 875 IPv6 address), the operating system will associate the endpoint with 876 an optimal address set of the available interfaces. If the IPv4 877 sin_port or IPv6 sin6_port is set to 0, the operating system will 878 choose an ephemeral port for the endpoint. 880 If a bind() is not called prior to the connect() call, the system 881 picks an ephemeral port and will choose an address set equivalent to 882 binding with a wildcard address. One of these addresses will be the 883 primary address for the association. This automatically enables the 884 multi-homing capability of SCTP. 886 The completion of this bind() process does not allow the SCTP 887 endpoint to accept inbound SCTP association requests. Until a 888 listen() system call, described below, is performed on the socket, 889 the SCTP endpoint will promptly reject an inbound SCTP INIT request 890 with an SCTP ABORT. 892 4.1.3. listen() 894 Applications use listen() to allow the SCTP endpoint to accept 895 inbound associations. 897 The function prototype is 899 int listen(int sd, 900 int backlog); 902 and the arguments are 904 sd: the socket descriptor of the SCTP endpoint. 906 backlog: this specifies the max number of outstanding associations 907 allowed in the socket's accept queue. These are the associations 908 that have finished the four-way initiation handshake (see Section 909 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 910 of '0' indicates that the caller no longer wishes to receive new 911 associations. 913 It returns 0 on success an -1 in case of an error. 915 4.1.4. accept() 917 Applications use the accept() call to remove an established SCTP 918 association from the accept queue of the endpoint. A new socket 919 descriptor will be returned from accept() to represent the newly 920 formed association. 922 The function prototype is 924 int accept(int sd, 925 struct sockaddr *addr, 926 socklen_t *addrlen); 928 and the arguments are 930 sd: The listening socket descriptor. 932 addr: On return, addr (struct sockaddr_in for an IPv4 address or 933 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 934 contain the primary address of the peer endpoint. 936 addrlen: On return, addrlen will contain the size of addr. 938 The function returns the socket descriptor for the newly formed 939 association on success and -1 in case of an error. 941 4.1.5. connect() 943 Applications use connect() to initiate an association to a peer. 945 The function prototype is 947 int connect(int sd, 948 const struct sockaddr *addr, 949 socklen_t addrlen); 951 and the arguments are 953 sd: The socket descriptor of the endpoint. 955 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 956 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 958 addrlen: The size of the address. 960 It returns 0 on success and -1 on error. 962 This operation corresponds to the ASSOCIATE primitive described in 963 Section 10.1 of [RFC4960]. 965 The number of outbound streams the new association has is stack 966 dependent. Applications can use the SCTP_INITMSG option described in 967 Section 8.1.3 before connecting to change the number of outbound 968 streams. 970 If a bind() is not called prior to the connect() call, the system 971 picks an ephemeral port and will choose an address set equivalent to 972 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 973 respectively. One of the addresses will be the primary address for 974 the association. This automatically enables the multi-homing 975 capability of SCTP. 977 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 978 during the association set up phase. If an application wants to do 979 this, it cannot use the connect() call. Instead, it should use 980 sendto() or sendmsg() to initiate an association. If it uses 981 sendto() and it wants to change the initialization behavior, it needs 982 to use the SCTP_INITMSG socket option before calling sendto(). Or it 983 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 984 association without calling setsockopt(). Note that the implicit 985 setup is supported for the one-to-one style sockets. 987 SCTP does not support half close semantics. This means that unlike 988 T/TCP, MSG_EOF should not be set in the flags parameter when calling 989 sendto() or sendmsg() when the call is used to initiate a connection. 990 MSG_EOF is not an acceptable flag with an SCTP socket. 992 4.1.6. close() 994 Applications use close() to gracefully close down an association. 996 The function prototype is 998 int close(int sd); 1000 and the argument is 1002 sd: The socket descriptor of the association to be closed. 1004 It returns 0 on success and -1 in case of an error. 1006 After an application calls close() on a socket descriptor, no further 1007 socket operations will succeed on that descriptor. 1009 4.1.7. shutdown() 1011 SCTP differs from TCP in that it does not have half closed semantics. 1012 Hence the shutdown() call for SCTP is an approximation of the TCP 1013 shutdown() call, and solves some different problems. Full TCP- 1014 compatibility is not provided, so developers porting TCP applications 1015 to SCTP may need to recode sections that use shutdown(). (Note that 1016 it is possible to achieve the same results as half close in SCTP 1017 using SCTP streams.) 1019 The function prototype is 1021 int shutdown(int sd, 1022 int how); 1024 and the arguments are 1026 sd: The socket descriptor of the association to be closed. 1028 how: Specifies the type of shutdown. The values are as follows: 1030 SHUT_RD: Disables further receive operations. No SCTP protocol 1031 action is taken. 1033 SHUT_WR: Disables further send operations, and initiates the SCTP 1034 shutdown sequence. 1036 SHUT_RDWR: Disables further send and receive operations and 1037 initiates the SCTP shutdown sequence. 1039 It returns 0 on success and -1 in case of an error. 1041 The major difference between SCTP and TCP shutdown() is that SCTP 1042 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 1043 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 1044 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 1045 the SCTP association while still leaving the socket descriptor open. 1046 This allows the caller to receive back any data which SCTP is unable 1047 to deliver (see Section 6.1.4 for more information) and receive event 1048 notifications. 1050 To perform the ABORT operation described in [RFC4960] Section 10.1, 1051 an application can use the socket option SO_LINGER. It is described 1052 in Section 8.1.4. 1054 4.1.8. sendmsg() and recvmsg() 1056 With a one-to-one style socket, the application can also use 1057 sendmsg() and recvmsg() to transmit data to and receive data from its 1058 peer. The semantics is similar to those used in the one-to-many 1059 style (see Section 3.1.3), with the following differences: 1061 1. When sending, the msg_name field in the msghdr is not used to 1062 specify the intended receiver, rather it is used to indicate a 1063 preferred peer address if the sender wishes to discourage the 1064 stack from sending the message to the primary address of the 1065 receiver. If the socket is connected and the transport address 1066 given is not part of the current association, the data will not 1067 be sent and an SCTP_SEND_FAILED_EVENT event will be delivered to 1068 the application if send failure events are enabled. 1070 2. Using sendmsg() on a non-connected one-to-one style socket for 1071 implicit connection setup may or may not work depending on the 1072 SCTP implementation. 1074 4.1.9. getpeername() 1076 Applications use getpeername() to retrieve the primary socket address 1077 of the peer. This call is for TCP compatibility, and is not multi- 1078 homed. It may not work with one-to-many style sockets depending on 1079 the implementation. See Section 9.3 for a multi-homed style version 1080 of the call. 1082 The function prototype is 1083 int getpeername(int sd, 1084 struct sockaddr *address, 1085 socklen_t *len); 1087 and the arguments are: 1089 sd: The socket descriptor to be queried. 1091 address: On return, the peer primary address is stored in this 1092 buffer. If the socket is an IPv4 socket, the address will be 1093 IPv4. If the socket is an IPv6 socket, the address will be either 1094 an IPv6 or IPv4 address. 1096 len: The caller should set the length of address here. On return, 1097 this is set to the length of the returned address. 1099 It returns 0 on success and -1 in case of an error. 1101 If the actual length of the address is greater than the length of the 1102 supplied sockaddr structure, the stored address will be truncated. 1104 5. Data Structures 1106 This section discusses important data structures which are specific 1107 to SCTP and are used with sendmsg() and recvmsg() calls to control 1108 SCTP endpoint operations and to access ancillary information and 1109 notifications. 1111 5.1. The msghdr and cmsghdr Structures 1113 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1114 well as the ancillary data carried in the structure, is the key for 1115 the application to set and get various control information from the 1116 SCTP endpoint. 1118 The msghdr and the related cmsghdr structures are defined and 1119 discussed in detail in [RFC3542]. They are defined as: 1121 struct msghdr { 1122 void *msg_name; /* ptr to socket address structure */ 1123 socklen_t msg_namelen; /* size of socket address structure */ 1124 struct iovec *msg_iov; /* scatter/gather array */ 1125 int msg_iovlen; /* # elements in msg_iov */ 1126 void *msg_control; /* ancillary data */ 1127 socklen_t msg_controllen; /* ancillary data buffer length */ 1128 int msg_flags; /* flags on received message */ 1129 }; 1131 struct cmsghdr { 1132 socklen_t cmsg_len; /* #bytes, including this header */ 1133 int cmsg_level; /* originating protocol */ 1134 int cmsg_type; /* protocol-specific type */ 1135 /* followed by unsigned char cmsg_data[]; */ 1136 }; 1138 In the msghdr structure, the usage of msg_name has been discussed in 1139 previous sections (see Section 3.1.3 and Section 4.1.8). 1141 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1142 field) are treated by SCTP as a single user message for both 1143 sendmsg() and recvmsg(). 1145 SCTP stack uses the ancillary data (msg_control field) to communicate 1146 the attributes, such as SCTP_RCVINFO, of the message stored in 1147 msg_iov to the socket end point. The different ancillary data types 1148 are described in Section 5.3. 1150 The msg_flags are not used when sending a message with sendmsg(). 1152 If a notification has arrived, recvmsg() will return the notification 1153 in msg_iov field and set MSG_NOTIFICATION flag in msg_flags. If the 1154 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1155 Section 6 for more information about notifications. 1157 If all portions of a data frame or notification have been read, 1158 recvmsg() will return with MSG_EOR set in msg_flags. 1160 5.2. Ancillary Data Considerations and Semantics 1162 Programming with ancillary socket data (msg_control) contains some 1163 subtleties and pitfalls, which are discussed below. 1165 5.2.1. Multiple Items and Ordering 1167 Multiple ancillary data items may be included in any call to 1168 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP, 1169 such as IP level items, or both. 1171 The ordering of ancillary data items (either by SCTP or another 1172 protocol) is not significant and is implementation-dependent, so 1173 applications must not depend on any ordering. 1175 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 1176 correspond to the data in the msghdr's msg_iov member. There can be 1177 only one single such type ancillary data for each sendmsg() or 1178 recvmsg() call. 1180 5.2.2. Accessing and Manipulating Ancillary Data 1182 Applications can infer the presence of data or ancillary data by 1183 examining the msg_iovlen and msg_controllen msghdr members, 1184 respectively. 1186 Implementations may have different padding requirements for ancillary 1187 data, so portable applications should make use of the macros 1188 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1189 [RFC3542] and the SCTP implementation's documentation for more 1190 information. The following is an example, from [RFC3542], 1191 demonstrating the use of these macros to access ancillary data: 1193 struct msghdr msg; 1194 struct cmsghdr *cmsgptr; 1196 /* fill in msg */ 1198 /* call recvmsg() */ 1200 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1201 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1202 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1203 u_char *ptr; 1205 ptr = CMSG_DATA(cmsgptr); 1206 /* process data pointed to by ptr */ 1207 } 1208 } 1210 5.2.3. Control Message Buffer Sizing 1212 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1213 ancillary data will often be fundamental to the correct and sane 1214 operation of the sockets application. This is particularly true of 1215 the one-to-many semantics, but also of the one-to-one semantics. For 1216 example, if an application needs to send and receive data on 1217 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 1218 ancillary data is indispensable. 1220 Given that some ancillary data is critical, and that multiple 1221 ancillary data items may appear in any order, applications should be 1222 carefully written to always provide a large enough buffer to contain 1223 all possible ancillary data that can be presented by recvmsg(). If 1224 the buffer is too small, and crucial data is truncated, it may pose a 1225 fatal error condition. 1227 Thus, it is essential that applications be able to deterministically 1228 calculate the maximum required buffer size to pass to recvmsg(). One 1229 constraint imposed on this specification that makes this possible is 1230 that all ancillary data definitions are of a fixed length. One way 1231 to calculate the maximum required buffer size might be to take the 1232 sum the sizes of all enabled ancillary data item structures, as 1233 calculated by CMSG_SPACE. For example, if we enabled 1234 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 1235 and allocate the buffer size as follows: 1237 size_t total; 1238 void *buf; 1240 total = CMSG_SPACE(sizeof(struct sctp_sndrcvinfo)) + 1241 CMSG_SPACE(sizeof(struct in6_pktinfo)); 1243 buf = malloc(total); 1245 We could then use this buffer (buf) for msg_control on each call to 1246 recvmsg() and be assured that we would not lose any ancillary data to 1247 truncation. 1249 5.3. SCTP msg_control Structures 1251 A key element of all SCTP specific socket extensions is the use of 1252 ancillary data to specify and access SCTP specific data via the 1253 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1254 Fine-grained control over initialization and sending parameters are 1255 handled with ancillary data. 1257 Each ancillary data item is proceeded by a struct cmsghdr (see 1258 Section 5.1), which defines the function and purpose of the data 1259 contained in the cmsg_data[] member. 1261 By default on either style socket, SCTP will pass no ancillary data; 1262 Specific ancillary data items can be enabled with socket options 1263 defined for SCTP; see Section 6.2. 1265 Note that all ancillary types are fixed length; see Section 5.2 for 1266 further discussion on this. These data structures use struct 1267 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1268 address format. 1270 Other protocols may also provide ancillary data to the socket layer 1271 consumer. These ancillary data items from other protocols may 1272 intermingle with SCTP data. For example, the IPv6 socket API 1273 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1274 data items. If a socket API consumer enables delivery of both SCTP 1275 and IPv6 ancillary data, they both may appear in the same msg_control 1276 buffer in any order. An application may thus need to handle other 1277 types of ancillary data besides those passed by SCTP. 1279 The sockets application must provide a buffer large enough to 1280 accommodate all ancillary data provided via recvmsg(). If the buffer 1281 is not large enough, the ancillary data will be truncated and the 1282 msghdr's msg_flags will include MSG_CTRUNC. 1284 5.3.1. SCTP Initiation Structure (SCTP_INIT) 1286 This cmsghdr structure provides information for initializing new SCTP 1287 associations with sendmsg(). The SCTP_INITMSG socket option uses 1288 this same data structure. This structure is not used for recvmsg(). 1290 +--------------+-----------+---------------------+ 1291 | cmsg_level | cmsg_type | cmsg_data[] | 1292 +--------------+-----------+---------------------+ 1293 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1294 +--------------+-----------+---------------------+ 1296 The sctp_initmsg structure is defined below: 1298 struct sctp_initmsg { 1299 uint16_t sinit_num_ostreams; 1300 uint16_t sinit_max_instreams; 1301 uint16_t sinit_max_attempts; 1302 uint16_t sinit_max_init_timeo; 1303 }; 1305 sinit_num_ostreams: This is an integer number representing the 1306 number of streams that the application wishes to be able to send 1307 to. This number is confirmed in the SCTP_COMM_UP notification and 1308 must be verified since it is a negotiated number with the remote 1309 endpoint. The default value of 0 indicates to use the endpoint 1310 default value. 1312 sinit_max_instreams: This value represents the maximum number of 1313 inbound streams the application is prepared to support. This 1314 value is bounded by the actual implementation. In other words the 1315 user may be able to support more streams than the Operating 1316 System. In such a case, the Operating System limit overrides the 1317 value requested by the user. The default value of 0 indicates to 1318 use the endpoints default value. 1320 sinit_max_attempts: This integer specifies how many attempts the 1321 SCTP endpoint should make at resending the INIT. This value 1322 overrides the system SCTP 'Max.Init.Retransmits' value. The 1323 default value of 0 indicates to use the endpoints default value. 1324 This is normally set to the system's default 'Max.Init.Retransmit' 1325 value. 1327 sinit_max_init_timeo: This value represents the largest Time-Out or 1328 RTO value (in milliseconds) to use in attempting an INIT. 1329 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1330 upon timeout. For the INIT message this value may override 1331 'RTO.Max'. This value must not influence 'RTO.Max' during data 1332 transmission and is only used to bound the initial setup time. A 1333 default value of 0 indicates to use the endpoints default value. 1334 This is normally set to the system's 'RTO.Max' value (60 seconds). 1336 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - DEPRECATED 1338 This cmsghdr structure specifies SCTP options for sendmsg() and 1339 describes SCTP header information about a received message through 1340 recvmsg(). This structure mixes the send and receive path. 1341 SCTP_SNDINFO described in Section 5.3.4 and SCTP_RCVINFO described in 1342 Section 5.3.5 split this information. These structures should be 1343 used, when possible, since SCTP_SNDRCV is deprecated. 1345 +--------------+-------------+------------------------+ 1346 | cmsg_level | cmsg_type | cmsg_data[] | 1347 +--------------+-------------+------------------------+ 1348 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1349 +--------------+-------------+------------------------+ 1351 The sctp_sndrcvinfo structure is defined below: 1353 struct sctp_sndrcvinfo { 1354 uint16_t sinfo_stream; 1355 uint16_t sinfo_ssn; 1356 uint16_t sinfo_flags; 1357 uint32_t sinfo_ppid; 1358 uint32_t sinfo_context; 1359 uint32_t sinfo_timetolive; 1360 uint32_t sinfo_tsn; 1361 uint32_t sinfo_cumtsn; 1362 sctp_assoc_t sinfo_assoc_id; 1363 }; 1365 sinfo_stream: For recvmsg() the SCTP stack places the message's 1366 stream number in this value. For sendmsg() this value holds the 1367 stream number that the application wishes to send this message to. 1368 If a sender specifies an invalid stream number an error indication 1369 is returned and the call fails. 1371 sinfo_ssn: For recvmsg() this value contains the stream sequence 1372 number that the remote endpoint placed in the DATA chunk. For 1373 fragmented messages this is the same number for all deliveries of 1374 the message (if more than one recvmsg() is needed to read the 1375 message). The sendmsg() call will ignore this parameter. 1377 sinfo_flags: This field may contain any of the following flags and 1378 is composed of a bitwise OR of these values. 1380 recvmsg() flags: 1382 SCTP_UNORDERED: This flag is present when the message was sent 1383 un-ordered. 1385 sendmsg() flags: 1387 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1388 the message. If this flag is clear the datagram is 1389 considered an ordered send. 1391 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1392 the SCTP stack to override the primary destination address 1393 with the address found with the sendto/sendmsg call. 1395 SCTP_ABORT: Setting this flag causes the specified association 1396 to abort by sending an ABORT message to the peer. The ABORT 1397 chunk will contain an error cause 'User Initiated Abort' 1398 with cause code 12. The cause specific information of this 1399 error cause is provided in msg_iov. 1401 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1402 procedure on the specified association. Graceful shutdown 1403 assures that all data queued by both endpoints is 1404 successfully transmitted before closing the association. 1406 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1407 model socket to send the message to all associations that 1408 are currently established on this socket. For the one-to- 1409 one socket, this flag has no effect. 1411 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1412 passed to the remote end in each user message. In recvmsg() this 1413 value is the same information that was passed by the upper layer 1414 in the peer application. Please note that the SCTP stack performs 1415 no byte order modification of this field. For example, if the 1416 DATA chunk has to contain a given value in network byte order, the 1417 SCTP user has to perform the htonl() computation. 1419 sinfo_context: This value is an opaque 32 bit context datum that is 1420 used in the sendmsg() function. This value is passed back to the 1421 upper layer if an error occurs on the send of a message and is 1422 retrieved with each undelivered message. 1424 sinfo_timetolive: For the sending side, this field contains the 1425 message time to live in milliseconds. The sending side will 1426 expire the message within the specified time period if the message 1427 as not been sent to the peer within this time period. This value 1428 will override any default value set using any socket option. Also 1429 note that the value of 0 is special in that it indicates no 1430 timeout should occur on this message. 1432 sinfo_tsn: For the receiving side, this field holds a TSN that was 1433 assigned to one of the SCTP Data Chunks. For the sending side it 1434 is ignored. 1436 sinfo_cumtsn: This field will hold the current cumulative TSN as 1437 known by the underlying SCTP layer. Note this field is ignored 1438 when sending. 1440 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1441 the identifier for the association announced in the SCTP_COMM_UP 1442 notification. All notifications for a given association have the 1443 same identifier. Ignored for one-to-one style sockets. 1445 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1447 5.3.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) - 1448 DEPRECATED 1450 This cmsghdr structure specifies SCTP options for SCTP header 1451 information about a received message via recvmsg(). Note that this 1452 structure is an extended version of SCTP_SNDRCV (see Section 5.3.2) 1453 and will only be received if the user has set the socket option 1454 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1455 needed to receive ancillary data. See Section 8.1.22 on this socket 1456 option. Note that next message data is not valid unless the current 1457 message is completely read, i.e. the MSG_EOR is set, in other words 1458 if the application has more data to read from the current message 1459 then no next message information will be available. 1461 SCTP_NXTINFO described in Section 5.3.6 should be used when possible, 1462 since SCTP_EXTRCV is considered deprecated. 1464 +--------------+-------------+------------------------+ 1465 | cmsg_level | cmsg_type | cmsg_data[] | 1466 +--------------+-------------+------------------------+ 1467 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1468 +--------------+-------------+------------------------+ 1470 The sctp_extrcvinfo structure is defined below: 1472 struct sctp_extrcvinfo { 1473 uint16_t sinfo_stream; 1474 uint16_t sinfo_ssn; 1475 uint16_t sinfo_flags; 1476 uint32_t sinfo_ppid; 1477 uint32_t sinfo_context; 1478 uint32_t sinfo_pr_value; 1479 uint32_t sinfo_tsn; 1480 uint32_t sinfo_cumtsn; 1481 uint16_t serinfo_next_flags; 1482 uint16_t serinfo_next_stream; 1483 uint32_t serinfo_next_aid; 1484 uint32_t serinfo_next_length; 1485 uint32_t serinfo_next_ppid; 1486 sctp_assoc_t sinfo_assoc_id; 1487 }; 1489 sinfo_*: Please see Section 5.3.2 for the details for these fields. 1491 serinfo_next_flags: This bitmask will hold one or more of the 1492 following values: 1494 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1495 message information is available i.e.: next_stream, 1496 next_asocid, next_length and next_ppid fields all have valid 1497 values. If this bit is set to 0, then these fields are not 1498 valid and should be ignored. 1500 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1501 next message is completely in the receive buffer. The 1502 next_length field thus contains the entire message size. If 1503 this flag is set to 0, then the next_length field only contains 1504 part of the message size since the message is still being 1505 received (it is being partially delivered). 1507 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1508 the next message to be received was sent by the peer as 1509 unordered. If this bit is not set (i.e. the bit is 0) the next 1510 message to be read is an ordered message in the stream 1511 specified. 1513 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1514 the next message to be received is not a message from the peer, 1515 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1517 serinfo_next_stream: This value, when valid (see 1518 serinfo_next_flags), contains the next stream number that will be 1519 received on a subsequent call to one of the receive message 1520 functions. 1522 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1523 contains the next association identification that will be received 1524 on a subsequent call to one of the receive message functions. 1526 serinfo_next_length: This value, when valid (see 1527 serinfo_next_flags), contains the length of the next message that 1528 will be received on a subsequent call to one of the receive 1529 message functions. Note that this length may be a partial length 1530 depending on the settings of next_flags. 1532 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1533 contains the ppid of the next message that will be received on a 1534 subsequent call to one of the receive message functions. 1536 5.3.4. SCTP Send Information Structure (SCTP_SNDINFO) 1538 This cmsghdr structure specifies SCTP options for sendmsg(). 1540 +--------------+--------------+---------------------+ 1541 | cmsg_level | cmsg_type | cmsg_data[] | 1542 +--------------+--------------+---------------------+ 1543 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1544 +--------------+--------------+---------------------+ 1546 The sctp_sndinfo structure is defined below: 1548 struct sctp_sndinfo { 1549 uint16_t snd_sid; 1550 uint16_t snd_flags; 1551 uint32_t snd_ppid; 1552 uint32_t snd_context; 1553 sctp_assoc_t snd_assoc_id; 1554 }; 1556 snd_sid: This value holds the stream number that the application 1557 wishes to send this message to. If a sender specifies an invalid 1558 stream number an error indication is returned and the call fails. 1560 snd_flags: This field may contain any of the following flags and is 1561 composed of a bitwise OR of these values. 1563 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1564 message. If this flag is clear the datagram is considered an 1565 ordered send. 1567 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1568 SCTP stack to override the primary destination address with the 1569 address found with the sendto()/sendmsg call. 1571 SCTP_ABORT: Setting this flag causes the specified association to 1572 abort by sending an ABORT message to the peer. The ABORT chunk 1573 will contain an error cause 'User Initiated Abort' with cause 1574 code 12. The cause specific information of this error cause is 1575 provided in msg_iov. 1577 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1578 procedures on the specified association. Graceful shutdown 1579 assures that all data queued by both endpoints is successfully 1580 transmitted before closing the association. 1582 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1583 socket to send the message to all associations that are 1584 currently established on this socket. For the one-to-one 1585 socket, this flag has no effect. 1587 snd_ppid: This value in sendmsg() is an unsigned integer that is 1588 passed to the remote end in each user message. Please note that 1589 the SCTP stack performs no byte order modification of this field. 1590 For example, if the DATA chunk has to contain a given value in 1591 network byte order, the SCTP user has to perform the htonl() 1592 computation. 1594 snd_context: This value is an opaque 32 bit context datum that is 1595 used in the sendmsg() function. This value is passed back to the 1596 upper layer if an error occurs on the send of a message and is 1597 retrieved with each undelivered message. 1599 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1600 the identifier for the association announced in the SCTP_COMM_UP 1601 notification. All notifications for a given association have the 1602 same identifier. Ignored for one-to-one style sockets. 1604 An sctp_sndinfo item always corresponds to the data in msg_iov. 1606 5.3.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1608 This cmsghdr structure describes SCTP receive information about a 1609 received message through recvmsg(). 1611 To enable the delivery of this information an application must use 1612 the SCTP_RECVRCVINFO socket option (see Section 8.1.29). 1614 +--------------+--------------+---------------------+ 1615 | cmsg_level | cmsg_type | cmsg_data[] | 1616 +--------------+--------------+---------------------+ 1617 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1618 +--------------+--------------+---------------------+ 1620 The sctp_rcvinfo structure is defined below: 1622 struct sctp_rcvinfo { 1623 uint16_t rcv_sid; 1624 uint16_t rcv_ssn; 1625 uint16_t rcv_flags; 1626 uint32_t rcv_ppid; 1627 uint32_t rcv_tsn; 1628 uint32_t rcv_cumtsn; 1629 uint32_t rcv_context; 1630 sctp_assoc_t rcv_assoc_id; 1631 }; 1632 rcv_sid: The SCTP stack places the message's stream number in this 1633 value. 1635 rcv_ssn: This value contains the stream sequence number that the 1636 remote endpoint placed in the DATA chunk. For fragmented messages 1637 this is the same number for all deliveries of the message (if more 1638 than one recvmsg() is needed to read the message). 1640 rcv_flags: This field may contain any of the following flags and is 1641 composed of a bitwise OR of these values. 1643 SCTP_UNORDERED: This flag is present when the message was sent 1644 un-ordered. 1646 rcv_ppid: This value is the same information that was passed by the 1647 upper layer in the peer application. Please note that the SCTP 1648 stack performs no byte order modification of this field. For 1649 example, if the DATA chunk has to contain a given value in network 1650 byte order, the SCTP user has to perform the ntohl() computation. 1652 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1653 Data Chunks. 1655 rcv_cumtsn: This field will hold the current cumulative TSN as known 1656 by the underlying SCTP layer. 1658 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1659 the identifier for the association announced in the SCTP_COMM_UP 1660 notification. All notifications for a given association have the 1661 same identifier. Ignored for one-to-one style sockets. 1663 rcv_context: This value is an opaque 32 bit context datum that was 1664 set by the user with the SCTP_CONTEXT socket option. This value 1665 is passed back to the upper layer if an error occurs on the send 1666 of a message and is retrieved with each undelivered message. 1668 An sctp_rcvinfo item always corresponds to the data in msg_iov. 1670 5.3.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1672 This cmsghdr structure describes SCTP receive information of the next 1673 message which will be delivered through recvmsg() if this information 1674 is already available when delivering the current message. 1676 To enable the delivery of this information an application must use 1677 the SCTP_RECVNXTINFO socket option (see Section 8.1.30). 1679 +--------------+--------------+---------------------+ 1680 | cmsg_level | cmsg_type | cmsg_data[] | 1681 +--------------+--------------+---------------------+ 1682 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_nxtinfo | 1683 +--------------+--------------+---------------------+ 1685 The sctp_nxtinfo structure is defined below: 1687 struct sctp_nxtinfo { 1688 uint16_t nxt_sid; 1689 uint16_t nxt_flags; 1690 uint32_t nxt_ppid; 1691 size_t nxt_length; 1692 sctp_assoc_t nxt_assoc_id; 1693 }; 1695 nxt_sid: The SCTP stack places the next message's stream number in 1696 this value. 1698 nxt_flags: This field may contain any of the following flags and is 1699 composed of a bitwise OR of these values. 1701 SCTP_UNORDERED: This flag is present when the next message was 1702 sent un-ordered. 1704 SCTP_COMPLETE: This flag indicates that the entire message has 1705 been received and is in the socket buffer. Note that this has 1706 special implications with respect to the nxt_length field, see 1707 nxt_length description below. 1709 SCTP_NOTIFICATION: This flag is present when the next message is 1710 not a user message but instead is a notification. 1712 nxt_ppid: This value is the same information that was passed by the 1713 upper layer in the peer application for the next message. Please 1714 note that the SCTP stack performs no byte order modification of 1715 this field. For example, if the DATA chunk has to contain a given 1716 value in network byte order, the SCTP user has to perform the 1717 ntohl() computation. 1719 nxt_length: This value is the length of the message currently within 1720 the socket buffer. This might NOT be the entire length of the 1721 message since a partial delivery may be in progress. Only if the 1722 flag SCTP_COMPLETE is set in the nxt_flags field does this field 1723 represent the entire next message size. 1725 nxt_assoc_id: The association handle field of the next message, 1726 nxt_assoc_id, holds the identifier for the association announced 1727 in the SCTP_COMM_UP notification. All notifications for a given 1728 association have the same identifier. Ignored for one-to-one 1729 style sockets. 1731 5.3.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1733 This cmsghdr structure specifies SCTP options for sendmsg(). 1735 +--------------+-------------+--------------------+ 1736 | cmsg_level | cmsg_type | cmsg_data[] | 1737 +--------------+-------------+--------------------+ 1738 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1739 +--------------+-------------+--------------------+ 1741 The sctp_prinfo structure is defined below: 1743 struct sctp_prinfo { 1744 uint16_t pr_policy; 1745 uint32_t pr_value; 1746 }; 1748 pr_policy: This specifies which PR-SCTP policy is used. Using 1749 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1750 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1751 defined in [RFC3758] is used. In this case, the lifetime is 1752 provided in pr_value. 1754 pr_value: The meaning of this field depends on the PR-SCTP policy 1755 specified by the pr_policy field. It is ignored when 1756 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1757 lifetime in milliseconds is specified. 1759 An sctp_prinfo item always corresponds to the data in msg_iov. 1761 5.3.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1763 This cmsghdr structure specifies SCTP options for sendmsg(). 1765 +--------------+---------------+----------------------+ 1766 | cmsg_level | cmsg_type | cmsg_data[] | 1767 +--------------+---------------+----------------------+ 1768 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1769 +--------------+---------------+----------------------+ 1771 The sctp_authinfo structure is defined below: 1773 struct sctp_authinfo { 1774 uint16_t auth_keyid; 1775 }; 1777 auth_keyid: This specifies the shared key identifier used for 1778 sending the user message. 1780 An sctp_authinfo item always corresponds to the data in msg_iov. 1781 Please note that the SCTP implementation must not bundle user 1782 messages that needs to be authenticated using different shared key 1783 identifiers. 1785 5.3.9. SCTP Destination Address Structure (IPv4) (SCTP_DSTADDRV4) 1787 This cmsghdr structure specifies SCTP options for sendmsg(). 1789 +--------------+----------------+----------------+ 1790 | cmsg_level | cmsg_type | cmsg_data[] | 1791 +--------------+----------------+----------------+ 1792 | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | 1793 +--------------+----------------+----------------+ 1795 This ancillary data can be used to provide more than one destination 1796 address to sendmsg(). It can be used to implement sctp_sendv() using 1797 send_msg(). 1799 5.3.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6) 1801 This cmsghdr structure specifies SCTP options for sendmsg(). 1803 +--------------+----------------+-----------------+ 1804 | cmsg_level | cmsg_type | cmsg_data[] | 1805 +--------------+----------------+-----------------+ 1806 | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | 1807 +--------------+----------------+-----------------+ 1809 This ancillary data can be used to provide more than one destination 1810 address to sendmsg(). It can be used to implement sctp_sendv() using 1811 send_msg(). 1813 6. SCTP Events and Notifications 1815 An SCTP application may need to understand and process events and 1816 errors that happen on the SCTP stack. These events include network 1817 status changes, association startups, remote operational errors and 1818 undeliverable messages. All of these can be essential for the 1819 application. 1821 When an SCTP application layer does a recvmsg() the message read is 1822 normally a data message from a peer endpoint. If the application 1823 wishes to have the SCTP stack deliver notifications of non-data 1824 events, it sets the appropriate socket option for the notifications 1825 it wants. See Section 6.2 for these socket options. When a 1826 notification arrives, recvmsg() returns the notification in the 1827 application-supplied data buffer via msg_iov, and sets 1828 MSG_NOTIFICATION in msg_flags. 1830 This section details the notification structures. Every notification 1831 structure carries some common fields which provide general 1832 information. 1834 A recvmsg() call will return only one notification at a time. Just 1835 as when reading normal data, it may return part of a notification if 1836 the msg_iov buffer is not large enough. If a single read is not 1837 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1838 reading the notification before subsequent data can arrive. 1840 6.1. SCTP Notification Structure 1842 The notification structure is defined as the union of all 1843 notification types. 1845 union sctp_notification { 1846 struct sctp_tlv { 1847 uint16_t sn_type; /* Notification type. */ 1848 uint16_t sn_flags; 1849 uint32_t sn_length; 1850 } sn_header; 1851 struct sctp_assoc_change sn_assoc_change; 1852 struct sctp_paddr_change sn_paddr_change; 1853 struct sctp_remote_error sn_remote_error; 1854 struct sctp_send_failed sn_send_failed; 1855 struct sctp_shutdown_event sn_shutdown_event; 1856 struct sctp_adaptation_event sn_adaptation_event; 1857 struct sctp_pdapi_event sn_pdapi_event; 1858 struct sctp_authkey_event sn_auth_event; 1859 struct sctp_sender_dry_event sn_sender_dry_event; 1860 struct sctp_send_failed_event sn_send_failed_event; 1861 }; 1863 sn_type: The following list describes the SCTP notification and 1864 event types for the field sn_type. 1866 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1867 either been opened or closed. Refer to Section 6.1.1 for 1868 details. 1870 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1871 part of an existing association has experienced a change of 1872 state (e.g. a failure or return to service of the reachability 1873 of an endpoint via a specific transport address). Please see 1874 Section 6.1.2 for data structure details. 1876 SCTP_REMOTE_ERROR: The attached error message is an Operational 1877 Error received from the remote peer. It includes the complete 1878 TLV sent by the remote endpoint. See Section 6.1.3 for the 1879 detailed format. 1881 SCTP_SEND_FAILED_EVENT: The attached datagram could not be sent 1882 to the remote endpoint. This structure includes the original 1883 SCTP_SNDINFO that was used in sending this message i.e. this 1884 structure uses the sctp_sndinfo per Section 6.1.11. 1886 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1887 data should be sent on this socket. 1889 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1890 indicated adaptation layer. Please see Section 6.1.6. 1892 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1893 receiver that the partial delivery has been aborted. This may 1894 indicate the association is about to be aborted. Please see 1895 Section 6.1.7. 1897 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1898 receiver that either an error occurred on authentication, or a 1899 new key was made active. See Section 6.1.8. 1901 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1902 application that the sender has no more user data queued for 1903 transmission nor retransmission. See Section 6.1.9. 1905 sn_flags: These are notification-specific flags. 1907 sn_length: This is the length of the whole sctp_notification 1908 structure including the sn_type, sn_flags, and sn_length fields. 1910 6.1.1. SCTP_ASSOC_CHANGE 1912 Communication notifications inform the application that an SCTP 1913 association has either begun or ended. The identifier for a new 1914 association is provided by this notification. The notification 1915 information has the following format: 1917 struct sctp_assoc_change { 1918 uint16_t sac_type; 1919 uint16_t sac_flags; 1920 uint32_t sac_length; 1921 uint16_t sac_state; 1922 uint16_t sac_error; 1923 uint16_t sac_outbound_streams; 1924 uint16_t sac_inbound_streams; 1925 sctp_assoc_t sac_assoc_id; 1926 uint8_t sac_info[]; 1927 }; 1929 sac_type: It should be SCTP_ASSOC_CHANGE. 1931 sac_flags: Currently unused. 1933 sac_length: This field is the total length of the notification data, 1934 including the notification header. 1936 sac_state: This field holds one of a number of values that 1937 communicate the event that happened to the association. They 1938 include: 1940 SCTP_COMM_UP: A new association is now ready and data may be 1941 exchanged with this peer. When an association has been 1942 established successfully, this notification should be the first 1943 one. 1945 SCTP_COMM_LOST: The association has failed. The association is 1946 now in the closed state. If SEND_FAILED notifications are 1947 turned on, an SCTP_COMM_LOST is accompanied by a series of 1948 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1949 message. 1951 SCTP_RESTART: SCTP has detected that the peer has restarted. 1953 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1955 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1956 blocking mode is set and data was sent (on a one-to-many style 1957 socket), an SCTP_CANT_STR_ASSOC is accompanied by a series of 1958 SCTP_SEND_FAILED_EVENT events, one for each outstanding 1959 message. 1961 sac_error: If the state was reached due to an error condition (e.g. 1962 SCTP_COMM_LOST) any relevant error information is available in 1963 this field. This corresponds to the protocol error codes defined 1964 in [RFC4960]. 1966 sac_outbound_streams: 1968 sac_inbound_streams: The maximum number of streams allowed in each 1969 direction are available in sac_outbound_streams and sac_inbound 1970 streams. 1972 sac_assoc_id: The association id field holds the identifier for the 1973 association. All notifications for a given association have the 1974 same association identifier. For a one-to-one style socket, this 1975 field is ignored. 1977 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1978 received for this association, sac_info[] contains the complete 1979 ABORT chunk as defined in the SCTP specification [RFC4960] Section 1980 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1981 may contain an array of uint8_t describing the features that the 1982 current association supports. Features may include 1984 SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol 1985 extension described in [RFC3758]. 1987 SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol 1988 extension described in [RFC4895]. 1990 SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol 1991 extension described in [RFC5061]. 1993 SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the 1994 local endpoints use separate send and/or receive buffers for 1995 each SCTP association. 1997 6.1.2. SCTP_PEER_ADDR_CHANGE 1999 When a destination address of a multi-homed peer encounters a state 2000 change a peer address change event is sent. The notification has the 2001 following format: 2003 struct sctp_paddr_change { 2004 uint16_t spc_type; 2005 uint16_t spc_flags; 2006 uint32_t spc_length; 2007 struct sockaddr_storage spc_aaddr; 2008 uint32_t spc_state; 2009 uint32_t spc_error; 2010 sctp_assoc_t spc_assoc_id; 2011 } 2013 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 2015 spc_flags: Currently unused. 2017 spc_length: This field is the total length of the notification data, 2018 including the notification header. 2020 spc_aaddr: The affected address field holds the remote peer's 2021 address that is encountering the change of state. 2023 spc_state: This field holds one of a number of values that 2024 communicate the event that happened to the address. They include: 2026 SCTP_ADDR_AVAILABLE: This address is now reachable. This 2027 notification is provided whenever an address becomes reachable. 2029 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 2030 reached. Any data sent to this address is rerouted to an 2031 alternate until this address becomes reachable. This 2032 notification is provided whenever an address becomes 2033 unreachable. 2035 SCTP_ADDR_REMOVED: The address is no longer part of the 2036 association. 2038 SCTP_ADDR_ADDED: The address is now part of the association. 2040 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 2041 primary destination address. This notification is provided 2042 whenever an address is made primary. 2044 spc_error: If the state was reached due to any error condition (e.g. 2045 SCTP_ADDR_UNREACHABLE) any relevant error information is available 2046 in this field. 2048 spc_assoc_id: The association id field holds the identifier for the 2049 association. All notifications for a given association have the 2050 same association identifier. For a one-to-one style socket, this 2051 field is ignored. 2053 6.1.3. SCTP_REMOTE_ERROR 2055 A remote peer may send an Operational Error message to its peer. 2056 This message indicates a variety of error conditions on an 2057 association. The entire ERROR chunk as it appears on the wire is 2058 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 2059 specification [RFC4960] and any extensions for a list of possible 2060 error formats. An SCTP error notification has the following format: 2062 struct sctp_remote_error { 2063 uint16_t sre_type; 2064 uint16_t sre_flags; 2065 uint32_t sre_length; 2066 uint16_t sre_error; 2067 sctp_assoc_t sre_assoc_id; 2068 uint8_t sre_data[]; 2069 }; 2071 sre_type: It should be SCTP_REMOTE_ERROR. 2073 sre_flags: Currently unused. 2075 sre_length: This field is the total length of the notification data, 2076 including the notification header and the contents of sre_data. 2078 sre_error: This value represents one of the Operational Error causes 2079 defined in the SCTP specification, in network byte order. 2081 sre_assoc_id: The association id field holds the identifier for the 2082 association. All notifications for a given association have the 2083 same association identifier. For a one-to-one style socket, this 2084 field is ignored. 2086 sre_data: This contains the ERROR chunk as defined in the SCTP 2087 specification [RFC4960] Section 3.3.10. 2089 6.1.4. SCTP_SEND_FAILED - DEPRECATED 2091 Please note that this notification is deprecated. Use 2092 SCTP_SEND_FAILED_EVENT instead. 2094 If SCTP cannot deliver a message, it can return back the message as a 2095 notification if the SCTP_SEND_FAILED event is enabled. The 2096 notification has the following format: 2098 struct sctp_send_failed { 2099 uint16_t ssf_type; 2100 uint16_t ssf_flags; 2101 uint32_t ssf_length; 2102 uint32_t ssf_error; 2103 struct sctp_sndrcvinfo ssf_info; 2104 sctp_assoc_t ssf_assoc_id; 2105 uint8_t ssf_data[]; 2106 }; 2108 ssf_type: It should be SCTP_SEND_FAILED. 2110 ssf_flags: The flag value will take one of the following values: 2112 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2113 wire. 2115 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2116 Note that this does not necessarily mean that the data was (or 2117 was not) successfully delivered. 2119 ssf_length: This field is the total length of the notification data, 2120 including the notification header and the payload in ssf_data. 2122 ssf_error: This value represents the reason why the send failed, and 2123 if set, will be an SCTP protocol error code as defined in 2124 [RFC4960] Section 3.3.10. 2126 ssf_info: The ancillary data (struct sctp_sndrcvinfo) used to send 2127 the undelivered message. Regardless of if ancillary data is used 2128 or not, the ssf_info.sinfo_flags field indicates if the complete 2129 message or only part of the message is returned in ssf_data. If 2130 only part of the message is returned, it means that the part which 2131 is not present has been sent successfully to the peer. 2133 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2134 flags is set in ssf_info.sinfo_flags. If the first part of the 2135 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2136 This means that the tail end of the message is returned in 2137 ssf_data. 2139 ssf_assoc_id: The association id field, ssf_assoc_id, holds the 2140 identifier for the association. All notifications for a given 2141 association have the same association identifier. For a one-to- 2142 one style socket, this field is ignored. 2144 ssf_data: The undelivered message or part of the undelivered message 2145 will be present in the ssf_data field. Note that the 2146 ssf_info.sinfo_flags field as noted above should be used to 2147 determine if a complete message is present or just a piece of the 2148 message. Note that only user data is present in this field, any 2149 chunk headers or SCTP common headers must be removed by the SCTP 2150 stack. 2152 6.1.5. SCTP_SHUTDOWN_EVENT 2154 When a peer sends a SHUTDOWN, SCTP delivers this notification to 2155 inform the application that it should cease sending data. 2157 struct sctp_shutdown_event { 2158 uint16_t sse_type; 2159 uint16_t sse_flags; 2160 uint32_t sse_length; 2161 sctp_assoc_t sse_assoc_id; 2162 }; 2164 sse_type: It should be SCTP_SHUTDOWN_EVENT. 2166 sse_flags: Currently unused. 2168 sse_length: This field is the total length of the notification data, 2169 including the notification header. It will generally be 2170 sizeof(struct sctp_shutdown_event). 2172 sse_flags: Currently unused. 2174 sse_assoc_id: The association id field holds the identifier for the 2175 association. All notifications for a given association have the 2176 same association identifier. For a one-to-one style socket, this 2177 field is ignored. 2179 6.1.6. SCTP_ADAPTATION_INDICATION 2181 When a peer sends an Adaptation Layer Indication parameter as 2182 described in [RFC5061], SCTP delivers this notification to inform the 2183 application about the peer's adaptation layer indication. 2185 struct sctp_adaptation_event { 2186 uint16_t sai_type; 2187 uint16_t sai_flags; 2188 uint32_t sai_length; 2189 uint32_t sai_adaptation_ind; 2190 sctp_assoc_t sai_assoc_id; 2191 }; 2192 sai_type: It should be SCTP_ADAPTATION_INDICATION. 2194 sai_flags: Currently unused. 2196 sai_length: This field is the total length of the notification data, 2197 including the notification header. It will generally be 2198 sizeof(struct sctp_adaptation_event). 2200 sai_adaptation_ind: This field holds the bit array sent by the peer 2201 in the adaptation layer indication parameter. 2203 sai_assoc_id: The association id field holds the identifier for the 2204 association. All notifications for a given association have the 2205 same association identifier. For a one-to-one style socket, this 2206 field is ignored. 2208 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT 2210 When a receiver is engaged in a partial delivery of a message this 2211 notification will be used to indicate various events. 2213 struct sctp_pdapi_event { 2214 uint16_t pdapi_type; 2215 uint16_t pdapi_flags; 2216 uint32_t pdapi_length; 2217 uint32_t pdapi_indication; 2218 uint32_t pdapi_stream; 2219 uint32_t pdapi_seq; 2220 sctp_assoc_t pdapi_assoc_id; 2221 }; 2223 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 2225 pdapi_flags: Currently unused. 2227 pdapi_length: This field is the total length of the notification 2228 data, including the notification header. It will generally be 2229 sizeof(struct sctp_pdapi_event). 2231 pdapi_indication: This field holds the indication being sent to the 2232 application. Currently there is only one defined value: 2234 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 2235 delivery of a user message has been aborted. This happens, for 2236 example, if an association is aborted while a partial delivery 2237 is going on or the user message gets abandoned using PR-SCTP 2238 while the partial delivery of this message is going on. 2240 pdapi_stream: This field holds the stream on which the partial 2241 delivery event happened. 2243 pdapi_seq: This field holds the stream sequence number which was 2244 being partially delivered. 2246 pdapi_assoc_id: The association id field holds the identifier for 2247 the association. All notifications for a given association have 2248 the same association identifier. For a one-to-one style socket 2249 this field is ignored. 2251 6.1.8. SCTP_AUTHENTICATION_EVENT 2253 [RFC4895] defines an extension to authenticate SCTP messages. The 2254 following notification is used to report different events relating to 2255 the use of this extension. 2257 struct sctp_authkey_event { 2258 uint16_t auth_type; 2259 uint16_t auth_flags; 2260 uint32_t auth_length; 2261 uint16_t auth_keynumber; 2262 uint32_t auth_indication; 2263 sctp_assoc_t auth_assoc_id; 2264 }; 2266 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 2268 auth_flags: Currently unused. 2270 auth_length: This field is the total length of the notification 2271 data, including the notification header. It will generally be 2272 sizeof(struct sctp_authkey_event). 2274 auth_keynumber: This field holds the keynumber for the affected key 2275 indicated in the event (depends on auth_indication). 2277 auth_indication: This field holds the error or indication being 2278 reported. The following values are currently defined: 2280 SCTP_AUTH_NEW_KEY: This report indicates that a new key has been 2281 made active (used for the first time by the peer) and is now 2282 the active key. The auth_keynumber field holds the user 2283 specified key number. 2285 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 2286 support SCTP AUTH as defined in [RFC4895]. 2288 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 2289 implementation will no longer use the key identifier specified 2290 in auth_keynumber. 2292 auth_assoc_id: The association id field holds the identifier for the 2293 association. All notifications for a given association have the 2294 same association identifier. For a one-to-one style socket this 2295 field is ignored. 2297 6.1.9. SCTP_SENDER_DRY_EVENT 2299 When the SCTP stack has no more user data to send or retransmit, this 2300 notification is given to the user. Also, at the time when a user app 2301 subscribes to this event, if there is no data to be sent or 2302 retransmit, the stack will immediately send up this notification. 2304 struct sctp_sender_dry_event { 2305 uint16_t sender_dry_type; 2306 uint16_t sender_dry_flags; 2307 uint32_t sender_dry_length; 2308 sctp_assoc_t sender_dry_assoc_id; 2309 }; 2311 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 2313 sender_dry_flags: Currently unused. 2315 sender_dry_length: This field is the total length of the 2316 notification data, including the notification header. It will 2317 generally be sizeof(struct sctp_sender_dry_event). 2319 sender_dry_assoc_id: The association id field holds the identifier 2320 for the association. All notifications for a given association 2321 have the same association identifier. For a one-to-one style 2322 socket this field is ignored. 2324 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT 2326 SCTP notifications, when subscribed to, are reliable. They are 2327 always delivered as long as there is space in the socket receive 2328 buffer. However, if an implementation experiences a notification 2329 storm, it may run out of socket buffer space. When this occurs it 2330 may wish to disable notifications. If the implementation chooses to 2331 do this, it will append a final notification 2332 SCTP_NOTIFICATIONS_STOPPED_EVENT. This notification is a union 2333 sctp_notification, where only the struct sctp_tlv (see the union 2334 above) is used. It only contains this type in the sn_type field, the 2335 sn_length field set to the sizeof an sctp_tlv structure and the 2336 sn_flags set to 0. If an application receives this notification, it 2337 will need to re-subscribe to any notifications of interest to it, 2338 except for the sctp_data_io_event (note that SCTP_EVENTS is 2339 deprecated). 2341 An endpoint is automatically subscribed to this event as soon as it 2342 is subscribed to any event other than data io events. 2344 6.1.11. SCTP_SEND_FAILED_EVENT 2346 If SCTP cannot deliver a message, it can return back the message as a 2347 notification if the SCTP_SEND_FAILED_EVENT event is enabled. The 2348 notification has the following format: 2350 struct sctp_send_failed_event { 2351 uint16_t ssfe_type; 2352 uint16_t ssfe_flags; 2353 uint32_t ssfe_length; 2354 uint32_t ssfe_error; 2355 struct sctp_sndinfo ssfe_info; 2356 sctp_assoc_t ssfe_assoc_id; 2357 uint8_t ssfe_data[]; 2358 }; 2360 ssfe_type: It should be SCTP_SEND_FAILED_EVENT. 2362 ssfe_flags: The flag value will take one of the following values: 2364 SCTP_DATA_UNSENT: Indicates that the data was never put on the 2365 wire. 2367 SCTP_DATA_SENT: Indicates that the data was put on the wire. 2368 Note that this does not necessarily mean that the data was (or 2369 was not) successfully delivered. 2371 ssfe_length: This field is the total length of the notification 2372 data, including the notification header and the payload in 2373 ssf_data. 2375 ssfe_error: This value represents the reason why the send failed, 2376 and if set, will be an SCTP protocol error code as defined in 2377 [RFC4960] Section 3.3.10. 2379 ssfe_info: The ancillary data (struct sctp_sndinfo) used to send the 2380 undelivered message. Regardless of if ancillary data is used or 2381 not, the ssfe_info.sinfo_flags field indicates if the complete 2382 message or only part of the message is returned in ssf_data. If 2383 only part of the message is returned, it means that the part which 2384 is not present has been sent successfully to the peer. 2386 If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG 2387 flags is set in ssfe_info.sinfo_flags. If the first part of the 2388 message is sent successfully, the SCTP_DATA_LAST_FRAG is set. 2389 This means that the tail end of the message is returned in 2390 ssf_data. 2392 ssfe_assoc_id: The association id field, ssf_assoc_id, holds the 2393 identifier for the association. All notifications for a given 2394 association have the same association identifier. For a one-to- 2395 one style socket, this field is ignored. 2397 ssfe_data: The undelivered message or part of the undelivered 2398 message will be present in the ssf_data field. Note that the 2399 ssf_info.sinfo_flags field as noted above should be used to 2400 determine if a complete message is present or just a piece of the 2401 message. Note that only user data is present in this field, any 2402 chunk headers or SCTP common headers must be removed by the SCTP 2403 stack. 2405 6.2. Notification Interest Options 2407 6.2.1. SCTP_EVENTS option - DEPRECATED 2409 To receive SCTP event notifications, an application registers its 2410 interest by setting the SCTP_EVENTS socket option. The application 2411 then uses recvmsg() to retrieve notifications. A notification is 2412 stored in the data part (msg_iov) of the struct msghdr. The socket 2413 option uses the following structure: 2415 struct sctp_event_subscribe { 2416 uint8_t sctp_data_io_event; 2417 uint8_t sctp_association_event; 2418 uint8_t sctp_address_event; 2419 uint8_t sctp_send_failure_event; 2420 uint8_t sctp_peer_error_event; 2421 uint8_t sctp_shutdown_event; 2422 uint8_t sctp_partial_delivery_event; 2423 uint8_t sctp_adaptation_layer_event; 2424 uint8_t sctp_authentication_event; 2425 uint8_t sctp_sender_dry_event; 2426 }; 2427 sctp_data_io_event: Setting this flag to 1 will cause the reception 2428 of SCTP_SNDRCV information on a per message basis. The 2429 application will need to use the recvmsg() interface so that it 2430 can receive the event information contained in the msg_control 2431 field. Setting the flag to 0 will disable the reception of the 2432 message control information. Note that this is not really a 2433 notification and this is stored in the ancillary data 2434 (msg_control), not in the data part (msg_iov). 2436 sctp_association_event: Setting this flag to 1 will enable the 2437 reception of association event notifications. Setting the flag to 2438 0 will disable association event notifications. 2440 sctp_address_event: Setting this flag to 1 will enable the reception 2441 of address event notifications. Setting the flag to 0 will 2442 disable address event notifications. 2444 sctp_send_failure_event: Setting this flag to 1 will enable the 2445 reception of send failure event notifications. Setting the flag 2446 to 0 will disable send failure event notifications. 2448 sctp_peer_error_event: Setting this flag to 1 will enable the 2449 reception of peer error event notifications. Setting the flag to 2450 0 will disable peer error event notifications. 2452 sctp_shutdown_event: Setting this flag to 1 will enable the 2453 reception of shutdown event notifications. Setting the flag to 0 2454 will disable shutdown event notifications. 2456 sctp_partial_delivery_event: Setting this flag to 1 will enable the 2457 reception of partial delivery notifications. Setting the flag to 2458 0 will disable partial delivery event notifications. 2460 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 2461 reception of adaptation layer notifications. Setting the flag to 2462 0 will disable adaptation layer event notifications. 2464 sctp_authentication_event: Setting this flag to 1 will enable the 2465 reception of authentication layer notifications. Setting the flag 2466 to 0 will disable authentication layer event notifications. 2468 sctp_sender_dry_event: Setting this flag to 1 will enable the 2469 reception of sender dry notifications. Setting the flag to 0 will 2470 disable sender dry event notifications. 2472 An example where an application would like to receive data io events 2473 and association events but no others would be as follows: 2475 { 2476 struct sctp_event_subscribe events; 2478 memset(&events,0,sizeof(events)); 2480 events.sctp_data_io_event = 1; 2481 events.sctp_association_event = 1; 2483 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 2484 } 2486 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2487 receives ancillary data and notifications for all associations bound 2488 to the file descriptor. For one-to-one style SCTP sockets, the 2489 caller receives ancillary data and notifications only for the single 2490 association bound to the file descriptor. 2492 By default both the one-to-one style and the one-to-many style socket 2493 do not subscribe to any notification. 2495 6.2.2. SCTP_EVENT option 2497 The SCTP_EVENTS socket option has one issue for future compatibility. 2498 As new features are added the structure (sctp_event_subscribe) must 2499 be expanded. This can cause an application binary interface (ABI) 2500 issue unless an implementation has added padding at the end of the 2501 structure. To avoid this problem, SCTP_EVENTS has been deprecated 2502 and a new socket option SCTP_EVENT has taken its place. The option 2503 is used with the following structure: 2505 struct sctp_event { 2506 sctp_assoc_t se_assoc_id; 2507 uint16_t se_type; 2508 uint8_t se_on; 2509 }; 2511 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 2512 sockets. For one-to-many style sockets this field can be a 2513 particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. 2515 se_type: The se_type field can be filled with any value that would 2516 show up in the respective sn_type field (in the sctp_tlv structure 2517 of the notification). 2519 se_on: The se_on field is set to 1 to turn on an event and set to 0 2520 to turn off an event. 2522 To use this option the user fills in this structure and then calls 2523 the setsockopt to turn on or off an individual event. The following 2524 is an example use of this option: 2526 { 2527 struct sctp_event event; 2529 memset(&event, 0, sizeof(event)); 2531 event.se_assoc_id = SCTP_FUTURE_ASSOC; 2532 event.se_type = SCTP_SENDER_DRY_EVENT; 2533 event.se_on = 1; 2534 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2535 } 2537 By default both the one-to-one style and the one-to-many style socket 2538 do not subscribe to any notification. 2540 7. Common Operations for Both Styles 2542 7.1. send(), recv(), sendto(), and recvfrom() 2544 Applications can use send() and sendto() to transmit data to the peer 2545 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2546 data from the peer. 2548 The function prototypes are 2550 ssize_t send(int sd, 2551 const void *msg, 2552 size_t len, 2553 int flags); 2555 ssize_t sendto(int sd, 2556 const void *msg, 2557 size_t len, 2558 int flags, 2559 const struct sockaddr *to, 2560 socklen_t tolen); 2562 ssize_t recv(int sd, 2563 void *buf, 2564 size_t len, 2565 int flags); 2567 ssize_t recvfrom(int sd, 2568 void *buf, 2569 size_t len, 2570 int flags, 2571 struct sockaddr *from, 2572 socklen_t *fromlen); 2574 and the arguments are 2576 sd: The socket descriptor of an SCTP endpoint. 2578 msg: The message to be sent. 2580 len: the size of the message or the size of the buffer. 2582 to: one of the peer addresses of the association to be used to send 2583 the message. 2585 tolen: The size of the address. 2587 buf: The buffer to store a received message. 2589 from: The buffer to store the peer address used to send the received 2590 message. 2592 fromlen: The size of the from address. 2594 flags: (described below). 2596 These calls give access to only basic SCTP protocol features. If 2597 either peer in the association uses multiple streams, or sends 2598 unordered data, these calls will usually be inadequate, and may 2599 deliver the data in unpredictable ways. 2601 SCTP has the concept of multiple streams in one association. The 2602 above calls do not allow the caller to specify on which stream a 2603 message should be sent. The system uses stream 0 as the default 2604 stream for send() and sendto(). recv() and recvfrom() return data 2605 from any stream, but the caller can not distinguish the different 2606 streams. This may result in data seeming to arrive out of order. 2607 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2608 provide no indication. 2610 SCTP is message based. The msg buffer above in send() and sendto() 2611 is considered to be a single message. This means that if the caller 2612 wants to send a message that is composed by several buffers, the 2613 caller needs to combine them before calling send() or sendto(). 2614 Alternately, the caller can use sendmsg() to do that without 2615 combining them. Sending a message using send() or sendto() is atomic 2616 unless explicit EOR marking is enabled on the socket specified by sd. 2617 Using sendto() on a non-connected one-to-one style socket for 2618 implicit connection setup may or may not work depending on the SCTP 2619 implementation. recv() and recvfrom() cannot distinguish message 2620 boundaries (i.e. there is no way to observe the MSG_EOR flag to 2621 detect partial delivery). 2623 In receiving, if the buffer supplied is not large enough to hold a 2624 complete message, the receive call acts like a stream socket and 2625 returns as much data as will fit in the buffer. 2627 Note, the send() and recv() calls may not be used for a one-to-many 2628 style socket. 2630 Note, if an application calls a send() or sendto() function with no 2631 user data the SCTP implementation should reject the request with an 2632 appropriate error message. An implementation is not allowed to send 2633 a DATA chunk with no user data [RFC4960]. 2635 7.2. setsockopt() and getsockopt() 2637 Applications use setsockopt() and getsockopt() to set or retrieve 2638 socket options. Socket options are used to change the default 2639 behavior of socket calls. They are described in Section 8. 2641 The function prototypes are 2643 int getsockopt(int sd, 2644 int level, 2645 int optname, 2646 void *optval, 2647 socklen_t *optlen); 2649 and 2651 int setsockopt(int sd, 2652 int level, 2653 int optname, 2654 const void *optval, 2655 socklen_t optlen); 2657 and the arguments are 2659 sd: The socket descriptor. 2661 level: Set to IPPROTO_SCTP for all SCTP options. 2663 optname: The option name. 2665 optval: The buffer to store the value of the option. 2667 optlen: The size of the buffer (or the length of the option 2668 returned). 2670 They return 0 on success and -1 in case of an error. 2672 All socket options set on a one-to-one style listening socket also 2673 apply to all future accepted sockets. For one-to-many style sockets 2674 often a socket option will pass a structure that includes an assoc_id 2675 field. This field can be filled with the association id of a 2676 particular association and unless otherwise specified can be filled 2677 with one of the following constants: 2679 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2680 after this socket option will be affected by this call. 2682 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2683 associations will be affected by this call, future associations 2684 will still receive the previous default value. 2686 SCTP_ALL_ASSOC: Specifies that all current and future associations 2687 will be affected by this call. 2689 7.3. read() and write() 2691 Applications can use read() and write() to send and receive data to 2692 and from a peer. They have the same semantics as send() and recv() 2693 except that the flags parameter cannot be used. 2695 7.4. getsockname() 2697 Applications use getsockname() to retrieve the locally-bound socket 2698 address of the specified socket. This is especially useful if the 2699 caller let SCTP choose a local port. This call is for single homed 2700 endpoints. It does not work well with multi-homed endpoints. See 2701 Section 9.5 for a multi-homed version of the call. 2703 The function prototype is 2705 int getsockname(int sd, 2706 struct sockaddr *address, 2707 socklen_t *len); 2709 and the arguments are 2711 sd: The socket descriptor to be queried. 2713 address: On return, one locally bound address (chosen by the SCTP 2714 stack) is stored in this buffer. If the socket is an IPv4 socket, 2715 the address will be IPv4. If the socket is an IPv6 socket, the 2716 address will be either an IPv6 or IPv4 address. 2718 len: The caller should set the length of the address here. On 2719 return, this is set to the length of the returned address. 2721 It returns 0 on success and -1 in case of an error. 2723 If the actual length of the address is greater than the length of the 2724 supplied sockaddr structure, the stored address will be truncated. 2726 If the socket has not been bound to a local name, the value stored in 2727 the object pointed to by address is unspecified. 2729 7.5. Implicit Association Setup 2731 The application can begin sending and receiving data using the 2732 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 2733 through any explicit association setup procedures (i.e., no connect() 2734 calls required). 2736 Whenever sendmsg() or sendto() is called and the SCTP stack at the 2737 sender finds that no association exists between the sender and the 2738 intended receiver (identified by the address passed either in the 2739 msg_name field of msghdr structure in the sendmsg() call or the 2740 dest_addr field in the sendto() call), the SCTP stack will 2741 automatically setup an association to the intended receiver. 2743 Upon the successful association setup an SCTP_COMM_UP notification 2744 will be dispatched to the socket at both the sender and receiver 2745 side. This notification can be read by the recvmsg() system call 2746 (see Section 3.1.3). 2748 Note, if the SCTP stack at the sender side supports bundling, the 2749 first user message may be bundled with the COOKIE ECHO message 2750 [RFC4960]. 2752 When the SCTP stack sets up a new association implicitly, the 2753 SCTP_INIT type ancillary data may also be passed along (see 2754 Section 5.3.1 for details of the data structures) to change some 2755 parameters used in setting up a new association. 2757 If this information is not present in the sendmsg() call, or if the 2758 implicit association setup is triggered by a sendto() call, the 2759 default association initialization parameters will be used. These 2760 default association parameters may be set with respective 2761 setsockopt() calls or be left to the system defaults. 2763 Implicit association setup cannot be initiated by send() calls. 2765 8. Socket Options 2767 The following sub-section describes various SCTP level socket options 2768 that are common to both styles. SCTP associations can be multi- 2769 homed. Therefore, certain option parameters include a 2770 sockaddr_storage structure to select which peer address the option 2771 should be applied to. 2773 For the one-to-many style sockets, an sctp_assoc_t (association ID) 2774 parameter is used to identify the association instance that the 2775 operation affects. So it must be set when using this style. 2777 For the one-to-one style sockets and branched off one-to-many style 2778 sockets (see Section 9.2) this association ID parameter is ignored. 2780 Note that socket or IP level options are set or retrieved per socket. 2781 This means that for one-to-many style sockets, the options will be 2782 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2783 association ID) belonging to the socket. For one-to-one style, these 2784 options will be applied to all peer addresses of the association 2785 controlled by the socket. Applications should be careful in setting 2786 those options. 2788 For some IP stacks getsockopt() is read-only; so a new interface will 2789 be needed when information must be passed both into and out of the 2790 SCTP stack. The syntax for sctp_opt_info() is 2792 int sctp_opt_info(int sd, 2793 sctp_assoc_t id, 2794 int opt, 2795 void *arg, 2796 socklen_t *size); 2798 The sctp_opt_info() call is a replacement for getsockopt() only and 2799 will not set any options associated with the specified socket. A 2800 setsockopt() must be used to set any writeable option. 2802 For one-to-many style sockets, id specifies the association to query. 2803 For one-to-one style sockets, id is ignored. For one-to-many 2804 sockets, any association identifier in the structure provided as arg 2805 is ignored and id takes precedence. 2807 Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used with 2808 sctp_opt_info() or in getsockopt() calls. Using them will result in 2809 an error (returning -1 and errno set to EINVAL). SCTP_FUTURE_ASSOC 2810 can be used to query information for future associations. 2812 The field opt specifies which SCTP socket option to get. It can get 2813 any socket option currently supported that requests information 2814 (either read/write options or read only) such as: 2816 SCTP_RTOINFO 2818 SCTP_ASSOCINFO 2820 SCTP_DEFAULT_SEND_PARAM 2822 SCTP_GET_PEER_ADDR_INFO 2824 SCTP_PRIMARY_ADDR 2826 SCTP_PEER_ADDR_PARAMS 2828 SCTP_STATUS 2830 SCTP_CONTEXT 2832 SCTP_AUTH_ACTIVE_KEY 2834 SCTP_PEER_AUTH_CHUNKS 2836 SCTP_LOCAL_AUTH_CHUNKS 2838 The arg field is an option-specific structure buffer provided by the 2839 caller. See the rest of this sections subsections for more 2840 information on these options and option-specific structures. 2842 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2843 sets errno to the appropriate error code. 2845 8.1. Read / Write Options 2847 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2849 The protocol parameters used to initialize and limit the 2850 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2851 information on how these parameters are used in RTO calculation. 2853 The following structure is used to access and modify these 2854 parameters: 2856 struct sctp_rtoinfo { 2857 sctp_assoc_t srto_assoc_id; 2858 uint32_t srto_initial; 2859 uint32_t srto_max; 2860 uint32_t srto_min; 2861 }; 2863 srto_initial: This contains the initial RTO value. 2865 srto_max and srto_min: These contain the maximum and minimum bounds 2866 for all RTOs. 2868 srto_assoc_id: This parameter is ignored for one-to-one style 2869 sockets. For one-to-many style sockets the application may fill 2870 in an association identification or SCTP_FUTURE_ASSOC. It is an 2871 error to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id. 2873 All times are given in milliseconds. A value of 0, when modifying 2874 the parameters, indicates that the current value should not be 2875 changed. 2877 To access or modify these parameters, the application should call 2878 getsockopt() or setsockopt() respectively with the option name 2879 SCTP_RTOINFO. 2881 8.1.2. Association Parameters (SCTP_ASSOCINFO) 2883 This option is used to both examine and set various association and 2884 endpoint parameters. See [RFC4960] for more information on how this 2885 parameter is used. 2887 The following structure is used to access and modify these 2888 parameters: 2890 struct sctp_assocparams { 2891 sctp_assoc_t sasoc_assoc_id; 2892 uint16_t sasoc_asocmaxrxt; 2893 uint16_t sasoc_number_peer_destinations; 2894 uint32_t sasoc_peer_rwnd; 2895 uint32_t sasoc_local_rwnd; 2896 uint32_t sasoc_cookie_life; 2897 }; 2898 sasoc_assoc_id: This parameter is ignored for one-to-one style 2899 sockets. For one-to-many style sockets the application may fill 2900 in an association identification or SCTP_FUTURE_ASSOC. It is an 2901 error to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id. 2903 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2904 to make for the association. 2906 sasoc_number_peer_destinations: This is the number of destination 2907 addresses that the peer has. 2909 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2910 (reported in the last SACK) minus any outstanding data (i.e. data 2911 in flight). 2913 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2914 the peer. 2916 sasoc_cookie_life: This is the association's cookie life value used 2917 when issuing cookies. 2919 The values of the sasoc_peer_rwnd is meaningless when examining 2920 endpoint information (i.e. it is only valid when examining 2921 information on a specific association). 2923 All time values are given in milliseconds. A value of 0, when 2924 modifying the parameters, indicates that the current value should not 2925 be changed. 2927 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2928 on either an endpoint or association basis. The rwnd and destination 2929 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2930 sasoc_local_rwnd) are not settable and any value placed in these is 2931 ignored. 2933 To access or modify these parameters, the application should call 2934 getsockopt() or setsockopt() respectively with the option name 2935 SCTP_ASSOCINFO. 2937 The maximum number of retransmissions before an address is considered 2938 unreachable is also tunable, but is address-specific, so it is 2939 covered in a separate option. If an application attempts to set the 2940 value of the association maximum retransmission parameter to more 2941 than the sum of all maximum retransmission parameters, setsockopt() 2942 may return an error. The reason for this, from [RFC4960] Section 2943 8.2: 2945 Note: When configuring the SCTP endpoint, the user should avoid 2946 having the value of 'Association.Max.Retrans' (sasoc_maxrxt in this 2947 option) larger than the summation of the 'Path.Max.Retrans' (see 2948 Section 8.1.2 on spp_pathmaxrxt) of all the destination addresses for 2949 the remote endpoint. Otherwise, all the destination addresses may 2950 become inactive while the endpoint still considers the peer endpoint 2951 reachable. 2953 8.1.3. Initialization Parameters (SCTP_INITMSG) 2955 Applications can specify protocol parameters for the default 2956 association initialization. The structure used to access and modify 2957 these parameters is defined in Section 5.3.1. The option name 2958 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2960 Setting initialization parameters is effective only on an unconnected 2961 socket (for one-to-many style sockets only future associations are 2962 affected by the change). 2964 8.1.4. SO_LINGER 2966 An application can use this option to perform the SCTP ABORT 2967 primitive. This option affects all associations related to the 2968 socket. 2970 The linger option structure is: 2972 struct linger { 2973 int l_onoff; /* option on/off */ 2974 int l_linger; /* linger time */ 2975 }; 2977 To enable the option, set l_onoff to 1. If the l_linger value is set 2978 to 0, calling close() is the same as the ABORT primitive. If the 2979 value is set to a negative value, the setsockopt() call will return 2980 an error. If the value is set to a positive value linger_time, the 2981 close() can be blocked for at most linger_time. Please note that the 2982 time unit is ms according to Posix, but might be different on 2983 specific platforms. If the graceful shutdown phase does not finish 2984 during this period, close() will return but the graceful shutdown 2985 phase will continue in the system. 2987 Note, this is a socket level option, not an SCTP level option. When 2988 using this option, an application must specify a level of SOL_SOCKET 2989 in the call. 2991 8.1.5. SCTP_NODELAY 2993 Turn on/off any Nagle-like algorithm. This means that packets are 2994 generally sent as soon as possible and no unnecessary delays are 2995 introduced, at the cost of more packets in the network. Turning this 2996 option on disables any Nagle-like algorithm. 2998 This option expects an integer boolean flag, where a non-zero value 2999 turns on the option, and a zero value turns off the option. 3001 8.1.6. SO_RCVBUF 3003 Sets the receive buffer size in octets. For SCTP one-to-one style 3004 sockets, this controls the receiver window size. For one-to-many 3005 style sockets the meaning is implementation dependent. It might 3006 control the receive buffer for each association bound to the socket 3007 descriptor or it might control the receive buffer for the whole 3008 socket. This option expects an integer. 3010 Note, this is a socket level option, not an SCTP level option. When 3011 using this option, an application must specify a level of SOL_SOCKET 3012 in the call. 3014 8.1.7. SO_SNDBUF 3016 Sets the send buffer size. For SCTP one-to-one style sockets, this 3017 controls the amount of data SCTP may have waiting in internal buffers 3018 to be sent. This option therefore bounds the maximum size of data 3019 that can be sent in a single send call. For one-to-many style 3020 sockets, the effect is the same, except that it applies to one or all 3021 associations (see Section 3.3) bound to the socket descriptor used in 3022 the setsockopt() or getsockopt() call. The option applies to each 3023 association's window size separately. This option expects an 3024 integer. 3026 Note, this is a socket level option, not an SCTP level option. When 3027 using this option, an application must specify a level of SOL_SOCKET 3028 in the call. 3030 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 3032 This socket option is applicable to the one-to-many style socket 3033 only. When set it will cause associations that are idle for more 3034 than the specified number of seconds to automatically close using the 3035 graceful shutdown procedure. An association being idle is defined as 3036 an association that has not sent or received user data. The special 3037 value of '0' indicates that no automatic close of any association 3038 should be performed, this is the default value. This option expects 3039 an integer defining the number of seconds of idle time before an 3040 association is closed. 3042 An application using this option should enable receiving the 3043 association change notification. This is the only mechanism an 3044 application is informed about the closing of an association. After 3045 an association is closed, the association ID assigned to it can be 3046 reused. An application should be aware of this to avoid the possible 3047 problem of sending data to an incorrect peer endpoint. 3049 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 3051 Requests that the local SCTP stack uses the enclosed peer address as 3052 the association's primary. The enclosed address must be one of the 3053 association peer's addresses. 3055 The following structure is used to make a set peer primary request: 3057 struct sctp_setprim { 3058 sctp_assoc_t ssp_assoc_id; 3059 struct sockaddr_storage ssp_addr; 3060 }; 3062 ssp_addr: The address to set as primary. No wildcard address is 3063 allowed. 3065 ssp_assoc_id: This parameter is ignored for one-to-one style 3066 sockets. For one-to-many style sockets it identifies the 3067 association for this request. Note that the special sctp_assoc_t 3068 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 3070 8.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 3072 Requests that the local endpoint set the specified Adaptation Layer 3073 Indication parameter for all future INIT and INIT-ACK exchanges. 3075 The following structure is used to access and modify this parameter: 3077 struct sctp_setadaptation { 3078 uint32_t ssb_adaptation_ind; 3079 }; 3081 ssb_adaptation_ind: The adaptation layer indicator that will be 3082 included in any outgoing Adaptation Layer Indication parameter. 3084 8.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 3086 This option is a on/off flag and is passed as an integer where a non- 3087 zero is on and a zero is off. If enabled no SCTP message 3088 fragmentation will be performed. The effect of enabling this option 3089 are that if a message being sent exceeds the current PMTU size, the 3090 message will not be sent and instead an error will be indicated to 3091 the user. If this option is disabled (the default) then a message 3092 exceeding the size of the PMTU will be fragmented and reassembled by 3093 the peer. 3095 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 3097 Applications can enable or disable heartbeats for any peer address of 3098 an association, modify an address's heartbeat interval, force a 3099 heartbeat to be sent immediately, and adjust the address's maximum 3100 number of retransmissions sent before an address is considered 3101 unreachable. 3103 The following structure is used to access and modify an address's 3104 parameters: 3106 struct sctp_paddrparams { 3107 sctp_assoc_t spp_assoc_id; 3108 struct sockaddr_storage spp_address; 3109 uint32_t spp_hbinterval; 3110 uint16_t spp_pathmaxrxt; 3111 uint32_t spp_pathmtu; 3112 uint32_t spp_flags; 3113 uint32_t spp_ipv6_flowlabel; 3114 uint8_t spp_ipv4_tos; 3115 }; 3117 spp_assoc_id: This parameter is ignored for one-to-one style 3118 sockets. For one-to-many style sockets it identifies the 3119 association for this query. Note that the predefined constants 3120 are not allowed. 3122 spp_address: This specifies which address is of interest. If a 3123 wildcard address is provided it applies to all current and future 3124 paths. 3126 spp_hbinterval: This contains the value of the heartbeat interval, 3127 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 3128 spp_flag is set to SPP_HB_ENABLE the value of this field is 3129 ignored. Note also that a value of zero indicates the current 3130 setting should be left unchanged. To set an actual value of zero 3131 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 3132 it is set to 0, it does not mean that SCTP will continuously send 3133 out heartbeat since the actual interval also includes the current 3134 RTO and jitter (see Section 8.3 in [RFC4960]). 3136 spp_pathmaxrxt: This contains the maximum number of retransmissions 3137 before this address shall be considered unreachable. Note that a 3138 value of zero indicates the current setting should be left 3139 unchanged. 3141 spp_pathmtu: The current path MTU of the peer address. It is the 3142 number of bytes available in an SCTP packet for chunks. Providing 3143 a value of 0 does not change the current setting. If a positive 3144 value is provided and SPP_PMTUD_DISABLE is set in the spp_flags, 3145 the given value is used as the path MTU. If SPP_PMTUD_ENABLE is 3146 set in the spp_flags, the spp_pathmtu field is ignored. 3148 spp_ipv6_flowlabel: This field is used in conjunction with the 3149 SPP_IPV6_FLOWLABEL flag. This setting has precedence over any 3150 IPv6 layer setting. 3152 spp_ipv4_tos: This field is used in conjunction with the 3153 SPP_IPV4_TOS flag. This setting has precedence over any IPv4 3154 layer setting. 3156 spp_flags: These flags are used to control various features on an 3157 association. The flag field is a bit mask which may contain zero 3158 or more of the following options: 3160 SPP_HB_ENABLE: Enable heartbeats on the specified address. 3162 SPP_HB_DISABLE: Disable heartbeats on the specified address. 3163 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 3164 exclusive, only one of these two should be specified. Enabling 3165 both fields will have undetermined results. 3167 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 3168 immediately. This must not be used in conjunction with a 3169 wildcard address. 3171 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 3172 is to be set to the value of 0 milliseconds. 3174 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 3175 specified address. 3177 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 3178 the specified address. Note that if the address field is empty 3179 then all addresses on the association are affected. Note also 3180 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 3181 exclusive. Enabling both will have undetermined results. 3183 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 3184 IPV6 flowlabel value. The value is obtained in the 3185 spp_ipv6_flowlabel field. 3187 Upon retrieval, this flag will be set to indicate that the 3188 spp_ipv6_flowlabel field has a valid value returned. If a 3189 specific destination address is set (in the spp_address field), 3190 then the value returned is that of the address. If just an 3191 association is specified (and no address), then the 3192 association's default flowlabel is returned. If neither an 3193 association nor a destination is specified, then the socket's 3194 default flowlabel is returned. For non IPv6 sockets, this flag 3195 will be left cleared. 3197 SPP_IPV4_TOS: Setting this flag enables the setting of the IPV4 3198 TOS value associated with either the association or a specific 3199 address. The value is obtained in the spp_ipv4_tos field. 3201 Upon retrieval, this flag will be set to indicate that the 3202 spp_ipv4_tos field has a valid value returned. If a specific 3203 destination address is set when called (in the spp_address 3204 field) then that specific destination address' TOS value is 3205 returned. If just an association is specified then the 3206 association default TOS is returned. If neither an association 3207 nor a destination is specified, then the sockets default TOS is 3208 returned. 3210 To read or modify these parameters, the application should call 3211 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 3213 8.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) - 3214 DEPRECATED 3216 Please note that this options is deprecated. Section 8.1.31 should 3217 be used instead. 3219 Applications that wish to use the sendto() system call may wish to 3220 specify a default set of parameters that would normally be supplied 3221 through the inclusion of ancillary data. This socket option allows 3222 such an application to set the default sctp_sndrcvinfo structure. 3223 The application that wishes to use this socket option simply passes 3224 the sctp_sndrcvinfo structure defined in Section 5.3.2 to this call. 3226 The input parameters accepted by this call include sinfo_stream, 3227 sinfo_flags, sinfo_ppid, sinfo_context, and sinfo_timetolive. The 3228 sinfo_flags is composed of a bitwise OR of SCTP_UNORDERED, SCTP_EOF, 3229 and SCTP_SENDALL. The sinfo_assoc_id field specifies the association 3230 to apply the parameters to. For a one-to-many style socket any of 3231 the predefined constants are also allowed in this field. The field 3232 is ignored on the one-to-one style. 3234 8.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) - 3235 DEPRECATED 3237 This socket option is used to specify various notifications and 3238 ancillary data the user wishes to receive. Please see Section 6.2.1 3239 for a full description of this option and its usage. Note that this 3240 option is considered deprecated and present for backward 3241 compatibility. New applications should use the SCTP_EVENT option. 3242 See Section 6.2.2 for a full description of that option as well. 3244 8.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 3246 This socket option is a boolean flag which turns on or off the 3247 mapping of IPv4 addresses. If this option is turned on, then IPv4 3248 addresses will be mapped to V6 representation. If this option is 3249 turned off, then no mapping will be done of V4 addresses and a user 3250 will receive both PF_INET6 and PF_INET type addresses on the socket. 3251 See [RFC3542] for more details on mapped V6 addresses. 3253 If this socket option is used on a socket of type PF_INET an error is 3254 returned. 3256 By default this option is turned off and expects an integer to be 3257 passed where a non-zero value turns on the option and a zero value 3258 turns off the option. 3260 8.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 3262 This option will get or set the maximum size to put in any outgoing 3263 SCTP DATA chunk. If a message is larger than this size it will be 3264 fragmented by SCTP into the specified size. Note that the underlying 3265 SCTP implementation may fragment into smaller sized chunks when the 3266 PMTU of the underlying association is smaller than the value set by 3267 the user. The default value for this option is '0' which indicates 3268 the user is not limiting fragmentation and only the PMTU will affect 3269 SCTP's choice of DATA chunk size. Note also that values set larger 3270 than the maximum size of an IP datagram will effectively let SCTP 3271 control fragmentation (i.e. the same as setting this option to 0). 3273 The following structure is used to access and modify this parameter: 3275 struct sctp_assoc_value { 3276 sctp_assoc_t assoc_id; 3277 uint32_t assoc_value; 3278 }; 3280 assoc_id: This parameter is ignored for one-to-one style sockets. 3281 For one-to-many style sockets this parameter indicates which 3282 association the user is performing an action upon. It is an error 3283 to use SCTP_{CURRENT|ALL}_ASSOC in assoc_id. 3285 assoc_value: This parameter specifies the maximum size in bytes. 3287 8.1.17. Get or Set the List of Supported HMAC Identifiers 3288 (SCTP_HMAC_IDENT) 3290 This option gets or sets the list of HMAC algorithms that the local 3291 endpoint requires the peer to use. 3293 The following structure is used to get or set these identifiers: 3295 struct sctp_hmacalgo { 3296 uint32_t shmac_number_of_idents; 3297 uint16_t shmac_idents[]; 3298 }; 3300 shmac_number_of_idents: This field gives the number of elements 3301 present in the array shmac_idents. 3303 shmac_idents: This parameter contains an array of HMAC identifiers 3304 that the local endpoint is requesting the peer to use, in priority 3305 order. The following identifiers are valid: 3307 * SCTP_AUTH_HMAC_ID_SHA1 3309 * SCTP_AUTH_HMAC_ID_SHA256 3311 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 3312 may include any of the other values in its preferred order (lowest 3313 list position has the highest preference in algorithm selection). 3314 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 3315 of an unknown HMAC identifier (including optional identifiers unknown 3316 to the implementation) will cause the set option to fail and return 3317 an error. 3319 8.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 3321 This option will get or set the active shared key to be used to build 3322 the association shared key. 3324 The following structure is used to access and modify these 3325 parameters: 3327 struct sctp_authkeyid { 3328 sctp_assoc_t scact_assoc_id; 3329 uint16_t scact_keynumber; 3330 }; 3332 scact_assoc_id: This parameter sets the active key of the specified 3333 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 3334 used. For one-to-one sockets, this parameter is ignored. Note, 3335 however, that this option will set the active key on the 3336 association if the socket is connected, otherwise this will set 3337 the default active key for the endpoint. 3339 scact_keynumber: This parameter is the shared key identifier which 3340 the application is requesting to become the active shared key to 3341 be used for sending authenticated chunks. The key identifier must 3342 correspond to an existing shared key. Note that shared key 3343 identifier '0' defaults to a null key. 3345 When used with setsockopt() the SCTP implementation must use the 3346 indicated shared key identifier for all messages being given to an 3347 SCTP implementation via a send call after the setsockopt() call until 3348 changed again. Therefore, the SCTP implementation must not bundle 3349 user messages which should be authenticated using different shared 3350 key identifiers. 3352 Initially the key with key identifier 0 is the active key. 3354 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 3356 This option will affect the way delayed sacks are performed. This 3357 option allows the application to get or set the delayed sack time, in 3358 milliseconds. It also allows changing the delayed sack frequency. 3359 Changing the frequency to 1 disables the delayed sack algorithm. 3360 Note that if sack_delay or sack_freq are 0 when setting this option, 3361 the current values will remain unchanged. 3363 The following structure is used to access and modify these 3364 parameters: 3366 struct sctp_sack_info { 3367 sctp_assoc_t sack_assoc_id; 3368 uint32_t sack_delay; 3369 uint32_t sack_freq; 3370 }; 3371 sack_assoc_id: This parameter is ignored for one-to-one style 3372 sockets. For one-to-many style sockets this parameter indicates 3373 which association the user is performing an action upon. The 3374 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3376 sack_delay: This parameter contains the number of milliseconds that 3377 the user is requesting the delayed SACK timer to be set to. Note 3378 that this value is defined in the standard to be between 200 and 3379 500 milliseconds. 3381 sack_freq: This parameter contains the number of packets that must 3382 be received before a sack is sent without waiting for the delay 3383 timer to expire. The default value is 2, setting this value to 1 3384 will disable the delayed sack algorithm. 3386 8.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 3388 Fragmented interleave controls how the presentation of messages 3389 occurs for the message receiver. There are three levels of fragment 3390 interleave defined. Two of the levels affect the one-to-one model, 3391 while the one-to-many model is affected by all three levels. 3393 This option takes an integer value. It can be set to a value of 0, 1 3394 or 2. Attempting to set this level to other values will return an 3395 error. 3397 Setting the three levels provides the following receiver 3398 interactions: 3400 level 0: Prevents the interleaving of any messages. This means that 3401 when a partial delivery begins, no other messages will be received 3402 except the message being partially delivered. If another message 3403 arrives on a different stream (or association) that could be 3404 delivered, it will be blocked waiting for the user to read all of 3405 the partially delivered message. 3407 level 1: Allows interleaving of messages that are from different 3408 associations. For the one-to-one model, level 0 and level 1 thus 3409 have the same meaning since a one-to-one socket always receives 3410 messages from the same association. Note that setting the one-to- 3411 many model to this level may cause multiple partial deliveries 3412 from different associations but for any given association, only 3413 one message will be delivered until all parts of a message have 3414 been delivered. This means that one large message, being read 3415 with an association identification of "X", will block other 3416 messages from association "X" from being delivered. 3418 level 2: Allows complete interleaving of messages. This level 3419 requires that the sender carefully observes not only the peer 3420 association identification (or address) but must also pay careful 3421 attention to the stream number. With this option enabled a 3422 partially delivered message may begin being delivered for 3423 association "X" stream "Y" and the next subsequent receive may 3424 return a message from association "X" stream "Z". Note that no 3425 other messages would be delivered for association "X" stream "Y" 3426 until all of stream "Y"'s partially delivered message was read. 3427 Note that this option also affects the one-to-one model. Also 3428 note that for the one-to-many model not only another stream's 3429 message from the same association may be delivered upon the next 3430 receive, some other association's message may be delivered upon 3431 the next receive. 3433 An implementation should default the one-to-many model to level 1. 3434 The reason for this is that otherwise it is possible that a peer 3435 could begin sending a partial message and thus block all other peers 3436 from sending data. However a setting of level 2 requires the 3437 application to not only be aware of the association (via the 3438 association id or peer's address) but also the stream number. The 3439 stream number is not present unless the user has subscribed to the 3440 sctp_data_io_events (see Section 6.2). This is also why we recommend 3441 that the one-to-one model be defaulted to level 0 (level 1 for the 3442 one-to-one model has no effect). Note that an implementation should 3443 return an error if an application attempts to set the level to 2 and 3444 has not subscribed to the sctp_data_io_events. 3446 For applications that have subscribed to events, those events appear 3447 in the normal socket buffer data stream. This means that unless the 3448 user has set the fragmentation interleave level to 0, notifications 3449 may also be interleaved with partially delivered messages. 3451 8.1.21. Set or Get the SCTP Partial Delivery Point 3452 (SCTP_PARTIAL_DELIVERY_POINT) 3454 This option will set or get the SCTP partial delivery point. This 3455 point is the size of a message where the partial delivery API will be 3456 invoked to help free up rwnd space for the peer. Setting this to a 3457 lower value will cause partial deliveries to happen more often. This 3458 option expects an integer that sets or gets the partial delivery 3459 point in bytes. Note also that the call will fail if the user 3460 attempts to set this value larger than the socket receive buffer 3461 size. 3463 Note that any single message having a length smaller than or equal to 3464 the SCTP partial delivery point will be delivered in one single read 3465 call as long as the user provided buffer is large enough to hold the 3466 message. 3468 8.1.22. Set or Get the Use of Extended Receive Info 3469 (SCTP_USE_EXT_RCVINFO) - DEPRECATED 3471 This option will enable or disable the use of the extended version of 3472 the sctp_sndrcvinfo structure. If this option is disabled, then the 3473 normal sctp_sndrcvinfo structure is returned in all receive message 3474 calls. If this option is enabled then the sctp_extrcvinfo structure 3475 is returned in all receive message calls. The default is off. 3477 Note that the sctp_extrcvinfo structure is never used in any send 3478 call. 3480 This option is present for compatibility with older applications and 3481 is deprecated. Future applications should use SCTP_NXTINFO to 3482 retrieve this same information via ancillary data. 3484 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 3486 This option will enable or disable the use of the automatic 3487 generation of ASCONF chunks to add and delete addresses to an 3488 existing association. Note that this option has two caveats namely: 3489 a) it only affects sockets that are bound to all addresses available 3490 to the SCTP stack, and b) the system administrator may have an 3491 overriding control that turns the ASCONF feature off no matter what 3492 setting the socket option may have. 3494 This option expects an integer boolean flag, where a non-zero value 3495 turns on the option, and a zero value turns off the option. 3497 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 3499 This option will allow a user to change the maximum burst of packets 3500 that can be emitted by this association. Note that the default value 3501 is 4, and some implementations may restrict this setting so that it 3502 can only be lowered to positive values. 3504 To set or get this option the user fills in the following structure: 3506 struct sctp_assoc_value { 3507 sctp_assoc_t assoc_id; 3508 uint32_t assoc_value; 3509 }; 3510 assoc_id: This parameter is ignored for one-to-one style sockets. 3511 For one-to-many style sockets this parameter indicates which 3512 association the user is performing an action upon. The special 3513 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3515 assoc_value: This parameter contains the maximum burst. Setting the 3516 value to 0 disables burst mitigation. 3518 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) 3520 The context field in the sctp_sndrcvinfo structure is normally only 3521 used when a failed message is retrieved holding the value that was 3522 sent down on the actual send call. This option allows the setting of 3523 a default context on an association basis that will be received on 3524 reading messages from the peer. This is especially helpful in the 3525 one-to-many model for an application to keep some reference to an 3526 internal state machine that is processing messages on the 3527 association. Note that the setting of this value only affects 3528 received messages from the peer and does not affect the value that is 3529 saved with outbound messages. 3531 To set or get this option the user fills in the following structure: 3533 struct sctp_assoc_value { 3534 sctp_assoc_t assoc_id; 3535 uint32_t assoc_value; 3536 }; 3538 assoc_id: This parameter is ignored for one-to-one style sockets. 3539 For one-to-many style sockets this parameter indicates which 3540 association the user is performing an action upon. The special 3541 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 3543 assoc_value: This parameter contains the context. 3545 8.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 3547 This boolean flag is used to enable or disable explicit end of record 3548 (EOR) marking. When this option is enabled, a user may make multiple 3549 send system calls to send a record and must indicate that they are 3550 finished sending a particular record by including the SCTP_EOR flag. 3551 If this boolean flag is disabled then each individual send system 3552 call is considered to have an SCTP_EOR indicator set on it implicitly 3553 without the user having to explicitly add this flag. The default is 3554 off. 3556 This option expects an integer boolean flag, where a non-zero value 3557 turns on the option, and a zero value turns off the option. 3559 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 3561 This option only supports one-to-one style SCTP sockets. If used on 3562 a one-to-many style SCTP socket an error is indicated. 3564 This option expects an integer boolean flag, where a non-zero value 3565 turns on the option, and a zero value turns off the option. 3567 This socket option must not be used after calling bind() or 3568 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 3569 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3570 SCTP sockets bound to the same port must have set the 3571 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3572 having set the SCTP_REUSE_PORT option will fail if there are other 3573 sockets bound to the same port. At most one socket being bound to 3574 the same port may be listening. 3576 It should be noted that the behavior of the socket level socket 3577 option to reuse ports and/or addresses for SCTP sockets is 3578 unspecified. 3580 8.1.28. Set Notification Event (SCTP_EVENT) 3582 This socket option is used to set a specific notification option. 3583 Please see Section 6.2.2 for a full description of this option and 3584 its usage. 3586 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary 3587 Data (SCTP_RECVRCVINFO) 3589 Setting this option specifies that SCTP_RCVINFO defined in 3590 Section 5.3.5 is returned as ancillary data by recvmsg(). 3592 This option expects an integer boolean flag, where a non-zero value 3593 turns on the option, and a zero value turns off the option. 3595 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary 3596 Data (SCTP_RECVNXTINFO) 3598 Setting this option specifies that SCTP_NXTINFO defined in 3599 Section 5.3.6 is returned as ancillary data by recvmsg(). 3601 This option expects an integer boolean flag, where a non-zero value 3602 turns on the option, and a zero value turns off the option. 3604 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) 3606 Applications that wish to use the sendto() system call may wish to 3607 specify a default set of parameters that would normally be supplied 3608 through the inclusion of ancillary data. This socket option allows 3609 such an application to set the default sctp_sndinfo structure. The 3610 application that wishes to use this socket option simply passes the 3611 sctp_sndinfo structure defined in Section 5.3.4 to this call. The 3612 input parameters accepted by this call include snd_sid, snd_flags, 3613 snd_ppid, snd_context. The snd_flags is composed of a bitwise OR of 3614 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The snd_assoc_id field 3615 specifies the association to apply the parameters to. For a one-to- 3616 many style socket any of the predefined constants are also allowed in 3617 this field. The field is ignored on the one-to-one style. 3619 8.2. Read-Only Options 3621 The options defined in this subsection are read-only. Using this 3622 option in a setsockopt() call will result in an error indicating 3623 EOPNOTSUPP. 3625 8.2.1. Association Status (SCTP_STATUS) 3627 Applications can retrieve current status information about an 3628 association, including association state, peer receiver window size, 3629 number of unacked data chunks, and number of data chunks pending 3630 receipt. This information is read-only. 3632 The following structure is used to access this information: 3634 struct sctp_status { 3635 sctp_assoc_t sstat_assoc_id; 3636 int32_t sstat_state; 3637 uint32_t sstat_rwnd; 3638 uint16_t sstat_unackdata; 3639 uint16_t sstat_penddata; 3640 uint16_t sstat_instrms; 3641 uint16_t sstat_outstrms; 3642 uint32_t sstat_fragmentation_point; 3643 struct sctp_paddrinfo sstat_primary; 3644 }; 3646 sstat_assoc_id: This parameter is ignored for one-to-one style 3647 sockets. For one-to-many style sockets it holds the identifier 3648 for the association. All notifications for a given association 3649 have the same association identifier. The special SCTP_{FUTURE| 3650 CURRENT|ALL}_ASSOC cannot be used. 3652 sstat_state: This contains the association's current state, i.e. one 3653 of the following values: 3655 * SCTP_CLOSED 3657 * SCTP_BOUND 3659 * SCTP_LISTEN 3661 * SCTP_COOKIE_WAIT 3663 * SCTP_COOKIE_ECHOED 3665 * SCTP_ESTABLISHED 3667 * SCTP_SHUTDOWN_PENDING 3669 * SCTP_SHUTDOWN_SENT 3671 * SCTP_SHUTDOWN_RECEIVED 3673 * SCTP_SHUTDOWN_ACK_SENT 3675 sstat_rwnd: This contains the association peer's current receiver 3676 window size. 3678 sstat_unackdata: This is the number of unacked data chunks. 3680 sstat_penddata: This is the number of data chunks pending receipt. 3682 sstat_instrms: The number of streams that the peer will be using 3683 outbound. 3685 sstat_outstrms: The number of streams that the endpoint is allowed 3686 to use outbound. 3688 sstat_fragmentation_point: The size at which SCTP fragmentation will 3689 occur. 3691 sstat_primary: This is information on the current primary peer 3692 address. 3694 To access these status values, the application calls getsockopt() 3695 with the option name SCTP_STATUS. 3697 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3699 Applications can retrieve information about a specific peer address 3700 of an association, including its reachability state, congestion 3701 window, and retransmission timer values. This information is read- 3702 only. 3704 The following structure is used to access this information: 3706 struct sctp_paddrinfo { 3707 sctp_assoc_t spinfo_assoc_id; 3708 struct sockaddr_storage spinfo_address; 3709 int32_t spinfo_state; 3710 uint32_t spinfo_cwnd; 3711 uint32_t spinfo_srtt; 3712 uint32_t spinfo_rto; 3713 uint32_t spinfo_mtu; 3714 }; 3716 spinfo_assoc_id: This parameter is ignored for one-to-one style 3717 sockets. For one-to-many style sockets the following applies: 3718 This field may be filled by the application, if so, this field 3719 will have priority in looking up the association instead of using 3720 the address specified in spinfo_address. Note that if the address 3721 does not belong to the association specified then this call will 3722 fail. If the application does not fill in the spinfo_assoc_id, 3723 then the address will be used to lookup the association and on 3724 return this field will have the valid association id. In other 3725 words, this call can be used to translate an address into an 3726 association id. Note that the predefined constants are not 3727 allowed on this option. 3729 spinfo_address: This is filled by the application, and contains the 3730 peer address of interest. 3732 spinfo_state: This contains the peer address' state: 3734 SCTP_UNCONFIRMED: The initial state of a peer address. 3736 SCTP_ACTIVE: The state is entered the first time after path 3737 verification. It can also be entered if the state is 3738 SCTP_INACTIVE and the path supervision detects that the peer 3739 address is reachable again. 3741 SCTP_INACTIVE: This state is entered whenever a path failure is 3742 detected. 3744 spinfo_cwnd: This contains the peer address' current congestion 3745 window. 3747 spinfo_srtt: This contains the peer address' current smoothed round- 3748 trip time calculation in milliseconds. 3750 spinfo_rto: This contains the peer address' current retransmission 3751 timeout value in milliseconds. 3753 spinfo_mtu: The current path MTU of the peer address. It is the 3754 number of bytes available in an SCTP packet for chunks. 3756 8.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3757 (SCTP_PEER_AUTH_CHUNKS) 3759 This option gets a list of chunk types (see [RFC4960]) for a 3760 specified association that the peer requires to be received 3761 authenticated only. 3763 The following structure is used to access these parameters: 3765 struct sctp_authchunks { 3766 sctp_assoc_t gauth_assoc_id; 3767 uint32_t gauth_number_of_chunks 3768 uint8_t gauth_chunks[]; 3769 }; 3771 gauth_assoc_id: This parameter indicates for which association the 3772 user is requesting the list of peer authenticated chunks. For 3773 one-to-one sockets, this parameter is ignored. Note that the 3774 predefined constants are not allowed with this option. 3776 gauth_number_of_chunks: This parameter gives the number of elements 3777 in the array gauth_chunks. 3779 gauth_chunks: This parameter contains an array of chunk types that 3780 the peer is requesting to be authenticated. If the passed in 3781 buffer size is not large enough to hold the list of chunk types, 3782 ENOBUFS is returned. 3784 8.2.4. Get the List of Chunks the Local Endpoint Requires to be 3785 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3787 This option gets a list of chunk types (see [RFC4960]) for a 3788 specified association that the local endpoint requires to be received 3789 authenticated only. 3791 The following structure is used to access these parameters: 3793 struct sctp_authchunks { 3794 sctp_assoc_t gauth_assoc_id; 3795 uint32_t gauth_number_of_chunks; 3796 uint8_t gauth_chunks[]; 3797 }; 3799 gauth_assoc_id: This parameter indicates for which association the 3800 user is requesting the list of local authenticated chunks. For 3801 one-to-one sockets, this parameter is ignored. 3803 gauth_number_of_chunks: This parameter gives the number of elements 3804 in the array gauth_chunks. 3806 gauth_chunks: This parameter contains an array of chunk types that 3807 the local endpoint is requesting to be authenticated. If the 3808 passed in buffer is not large enough to hold the list of chunk 3809 types, ENOBUFS is returned. 3811 8.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3813 This option gets the current number of associations that are attached 3814 to a one-to-many style socket. The option value is an uint32_t. 3815 Note that this number is only a snap shot. This means that the 3816 number of associations may have changed when the caller gets back the 3817 option result. 3819 For a one-to-one style socket, this socket option results in an 3820 error. 3822 8.2.6. Get the Current Identifiers of Associations 3823 (SCTP_GET_ASSOC_ID_LIST) 3825 This option gets the current list of SCTP association identifiers of 3826 the SCTP associations handled by a one-to-many style socket. 3828 The option value has the structure 3830 struct sctp_assoc_ids { 3831 uint32_t gaids_number_of_ids; 3832 sctp_assoc_t gaids_assoc_id[]; 3833 }; 3835 The caller must provide a large enough buffer to hold all association 3836 identifiers. If the buffer is too small, an error must be returned. 3837 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3838 idea how large the buffer has to be. gaids_number_of_ids gives the 3839 number of elements in the array gaids_assoc_id. Note also that some 3840 or all of sctp_assoc_t returned in the array may become invalid by 3841 the time the caller gets back the result. 3843 For a one-to-one style socket, this socket option results in an 3844 error. 3846 8.3. Write-Only Options 3848 The options defined in this subsection are write-only. Using this 3849 option in a getsockopt() or sctp_opt_info() call will result in an 3850 error indicating EOPNOTSUPP. 3852 8.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3854 Requests that the peer marks the enclosed address as the association 3855 primary (see [RFC5061]). The enclosed address must be one of the 3856 association's locally bound addresses. 3858 The following structure is used to make a set peer primary request: 3860 struct sctp_setpeerprim { 3861 sctp_assoc_t sspp_assoc_id; 3862 struct sockaddr_storage sspp_addr; 3863 }; 3865 sspp_addr: The address to set as primary. 3867 sspp_assoc_id: This parameter is ignored for one-to-one style 3868 sockets. For one-to-many style sockets it identifies the 3869 association for this request. Note that the predefined constants 3870 are not allowed on this option. 3872 8.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) 3874 This set option adds a chunk type that the user is requesting to be 3875 received only in an authenticated way. Changes to the list of chunks 3876 will only affect future associations on the socket. 3878 The following structure is used to add a chunk: 3880 struct sctp_authchunk { 3881 uint8_t sauth_chunk; 3882 }; 3884 sauth_chunk: This parameter contains a chunk type that the user is 3885 requesting to be authenticated. 3887 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3888 chunks must not be used. If they are used, an error must be 3889 returned. The usage of this option enables SCTP AUTH in cases where 3890 it is not required by other means (for example the use of dynamic 3891 address reconfiguration). 3893 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3895 This option will set a shared secret key that is used to build an 3896 association shared key. 3898 The following structure is used to access and modify these 3899 parameters: 3901 struct sctp_authkey { 3902 sctp_assoc_t sca_assoc_id; 3903 uint16_t sca_keynumber; 3904 uint16_t sca_keylength; 3905 uint8_t sca_key[]; 3906 }; 3908 sca_assoc_id: This parameter indicates what association the shared 3909 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3910 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3911 ignored. Note, however on one to one sockets, that this option 3912 will set a key on the association if the socket is connected, 3913 otherwise this will set a key on the endpoint. 3915 sca_keynumber: This parameter is the shared key identifier by which 3916 the application will refer to this shared key. If a key of the 3917 specified index already exists, then this new key will replace the 3918 old existing key. Note that shared key identifier '0' defaults to 3919 a null key. 3921 sca_keylength: This parameter is the length of the array sca_key. 3923 sca_key: This parameter contains an array of bytes that is to be 3924 used by the endpoint (or association) as the shared secret key. 3925 Note, if the length of this field is zero, a null key is set. 3927 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3929 This set option indicates that the application will no longer send 3930 user messages using the indicated key identifier. 3932 struct sctp_authkeyid { 3933 sctp_assoc_t scact_assoc_id; 3934 uint16_t scact_keynumber; 3935 }; 3936 scact_assoc_id: This parameter indicates which association the 3937 shared key identifier is being deleted from. The special 3938 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3939 sockets, this parameter is ignored. Note, however, that this 3940 option will deactivate the key from the association if the socket 3941 is connected, otherwise this will deactivate the key from the 3942 endpoint. 3944 scact_keynumber: This parameter is the shared key identifier which 3945 the application is requesting to be deactivated. The key 3946 identifier must correspond to an existing shared key. Note if 3947 this parameter is zero, use of the null key identifier '0' is 3948 deactivated on the endpoint and/or association. 3950 The currently active key cannot be deactivated. 3952 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3954 This set option will delete a shared secret key which has been 3955 deactivated of an SCTP association. 3957 struct sctp_authkeyid { 3958 sctp_assoc_t scact_assoc_id; 3959 uint16_t scact_keynumber; 3960 }; 3962 scact_assoc_id: This parameter indicates which association the 3963 shared key identifier is being deleted from. The special 3964 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3965 sockets, this parameter is ignored. Note, however, that this 3966 option will delete the key from the association if the socket is 3967 connected, otherwise this will delete the key from the endpoint. 3969 scact_keynumber: This parameter is the shared key identifier which 3970 the application is requesting to be deleted. The key identifier 3971 must correspond to an existing shared key and must not be in use 3972 for any packet being sent by the SCTP implementation. This means 3973 in particular, that it must be deactivated first. Note if this 3974 parameter is zero, use of the null key identifier '0' is deleted 3975 from the endpoint and/or association. 3977 Only deactivated keys that are no longer used by an association can 3978 be deleted. 3980 9. New Functions 3982 Depending on the system, the following interface can be implemented 3983 as a system call or library function. 3985 9.1. sctp_bindx() 3987 This function allows the user to bind a specific subset of addresses 3988 or, if the SCTP extension described in [RFC5061] is supported, add or 3989 delete specific addresses. 3991 The function prototype is 3993 int sctp_bindx(int sd, 3994 struct sockaddr *addrs, 3995 int addrcnt, 3996 int flags); 3998 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3999 If the sd is an IPv6 socket, the addresses passed can either be IPv4 4000 or IPv6 addresses. 4002 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 4003 Section 3.1.2 for this usage. 4005 addrs is a pointer to an array of one or more socket addresses. Each 4006 address is contained in its appropriate structure. For an IPv6 4007 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 4008 array of sockaddr_in is used. The caller specifies the number of 4009 addresses in the array with addrcnt. Note that the wildcard 4010 addresses cannot be used in combination with non wildcard addresses 4011 on a socket with this function, doing so will result in an error. 4013 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 4014 -1 and sets errno to the appropriate error code. 4016 For SCTP, the port given in each socket address must be the same, or 4017 sctp_bindx() will fail, setting errno to EINVAL. 4019 The flags parameter is formed from the bitwise OR of zero or more of 4020 the following currently defined flags: 4022 o SCTP_BINDX_ADD_ADDR 4024 o SCTP_BINDX_REM_ADDR 4026 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 4027 socket (i.e. endpoint), and SCTP_BINDX_REM_ADDR directs SCTP to 4028 remove the given addresses from the socket. The two flags are 4029 mutually exclusive; if both are given, sctp_bindx() will fail with 4030 EINVAL. A caller may not remove all addresses from a socket; 4031 sctp_bindx() will reject such an attempt with EINVAL. 4033 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 4034 additional addresses with an endpoint after calling bind(). Or use 4035 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 4036 socket is associated with, so that no new association accepted will 4037 be associated with these addresses. If the endpoint supports dynamic 4038 address reconfiguration, an SCTP_BINDX_REM_ADDR or 4039 SCTP_BINDX_ADD_ADDR may cause an endpoint to send the appropriate 4040 message to its peers to change the peers' address lists. 4042 Adding and removing addresses from established associations is an 4043 optional functionality. Implementations that do not support this 4044 functionality should return -1 and set errno to EOPNOTSUPP. 4046 sctp_bindx() can be called on an already bound socket or on an 4047 unbound socket. If the socket is unbound and the first port number 4048 in the addrs is zero, the kernel will choose a port number. All port 4049 numbers after the first one being 0 must also be zero. If the first 4050 port number is not zero, the following port numbers must be zero or 4051 have the same value as the first one. For an already bound socket, 4052 all port numbers provided must be the bound one or 0. 4054 sctp_bindx() is an atomic operation. Therefore, the binding will be 4055 either successful on all addresses or fail on all addresses. If 4056 multiple addresses are provided and the sctp_bindx() call fails there 4057 is no indication which address is responsible for the failure. The 4058 only way to identify the specific error indication is to call 4059 sctp_bindx() sequentially with only one address per call. 4061 9.2. sctp_peeloff() 4063 After an association is established on a one-to-many style socket, 4064 the application may wish to branch off the association into a 4065 separate socket/file descriptor. 4067 This is particularly desirable when, for instance, the application 4068 wishes to have a number of sporadic message senders/receivers remain 4069 under the original one-to-many style socket, but branch off these 4070 associations carrying high volume data traffic into their own 4071 separate socket descriptors. 4073 The application uses the sctp_peeloff() call to branch off an 4074 association into a separate socket (Note the semantics are somewhat 4075 changed from the traditional one-to-one style accept() call). Note 4076 that the new socket is a one-to-one style socket. Thus it will be 4077 confined to operations allowed for a one-to-one style socket. 4079 The function prototype is 4081 int sctp_peeloff(int sd, 4082 sctp_assoc_t assoc_id); 4084 and the arguments are 4086 sd: The original one-to-many style socket descriptor returned from 4087 the socket() system call (see Section 3.1.1). 4089 assoc_id: the specified identifier of the association that is to be 4090 branched off to a separate file descriptor (Note, in a traditional 4091 one-to-one style accept() call, this would be an out parameter, 4092 but for the one-to-many style call, this is an in parameter). 4094 The function returns a non-negative file descriptor representing the 4095 branched-off association, or -1 if an error occurred. The variable 4096 errno is then set appropriately. 4098 9.3. sctp_getpaddrs() 4100 sctp_getpaddrs() returns all peer addresses in an association. 4102 The function prototype is: 4104 int sctp_getpaddrs(int sd, 4105 sctp_assoc_t id, 4106 struct sockaddr **addrs); 4108 On return, addrs will point to a dynamically allocated array of 4109 sockaddr structures of the appropriate type for the socket type. The 4110 caller should use sctp_freepaddrs() to free the memory. Note that 4111 the in/out parameter addrs must not be NULL. 4113 If sd is an IPv4 socket, the addresses returned will be all IPv4 4114 addresses. If sd is an IPv6 socket, the addresses returned can be a 4115 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4116 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4118 For one-to-many style sockets, id specifies the association to query. 4119 For one-to-one style sockets, id is ignored. 4121 On success, sctp_getpaddrs() returns the number of peer addresses in 4122 the association. If there is no association on this socket, 4123 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 4124 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 4125 is undefined. 4127 9.4. sctp_freepaddrs() 4129 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 4131 The function prototype is 4133 void sctp_freepaddrs(struct sockaddr *addrs); 4135 and addrs is the array of peer addresses returned by 4136 sctp_getpaddrs(). 4138 9.5. sctp_getladdrs() 4140 sctp_getladdrs() returns all locally bound address(es) on a socket. 4142 The function prototype is 4144 int sctp_getladdrs(int sd, 4145 sctp_assoc_t id, 4146 struct sockaddr **addrs); 4148 On return, addrs will point to a dynamically allocated array of 4149 sockaddr structures of the appropriate type for the socket type. The 4150 caller should use sctp_freeladdrs() to free the memory. Note that 4151 the in/out parameter addrs must not be NULL. 4153 If sd is an IPv4 socket, the addresses returned will be all IPv4 4154 addresses. If sd is an IPv6 socket, the addresses returned can be a 4155 mix of IPv4 or IPv6 addresses, with IPv4 addresses returned according 4156 to the SCTP_I_WANT_MAPPED_V4_ADDR option setting. 4158 For one-to-many style sockets, id specifies the association to query. 4159 For one-to-one style sockets, id is ignored. 4161 If the id field is set to the value '0' then the locally bound 4162 addresses are returned without regard to any particular association. 4164 On success, sctp_getladdrs() returns the number of local addresses 4165 bound to the socket. If the socket is unbound, sctp_getladdrs() 4166 returns 0, and the value of *addrs is undefined. If an error occurs, 4167 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 4169 9.6. sctp_freeladdrs() 4171 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 4173 The function prototype is 4174 void sctp_freeladdrs(struct sockaddr *addrs); 4176 and addrs is the array of local addresses returned by 4177 sctp_getladdrs(). 4179 9.7. sctp_sendmsg() - DEPRECATED 4181 This function is deprecated, sctp_sendv() (see Section 9.13) should 4182 be used instead. 4184 An implementation may provide a library function (or possibly system 4185 call) to assist the user with the advanced features of SCTP. 4187 The function prototype is 4189 ssize_t sctp_sendmsg(int sd, 4190 const void *msg, 4191 size_t len, 4192 const struct sockaddr *to, 4193 socklen_t tolen, 4194 uint32_t ppid, 4195 uint32_t flags, 4196 uint16_t stream_no, 4197 uint32_t timetolive, 4198 uint32_t context); 4200 and the arguments are: 4202 sd: The socket descriptor. 4204 msg: The message to be sent. 4206 len: The length of the message. 4208 to: The destination address of the message. 4210 tolen: The length of the destination address. 4212 ppid: The same as sinfo_ppid (see Section 5.3.2). 4214 flags: The same as sinfo_flags (see Section 5.3.2). 4216 stream_no: The same as sinfo_stream (see Section 5.3.2). 4218 timetolive: The same as sinfo_timetolive (see Section 5.3.2). 4220 context: The same as sinfo_context (see Section 5.3.2). 4222 The call returns the number of characters sent, or -1 if an error 4223 occurred. The variable errno is then set appropriately. 4225 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 4226 marking is enabled on the socket specified by sd). 4228 Using sctp_sendmsg() on a non-connected one-to-one style socket for 4229 implicit connection setup may or may not work depending on the SCTP 4230 implementation. 4232 9.8. sctp_recvmsg() - DEPRECATED 4234 This function is deprecated, sctp_recvv() (see Section 9.12) should 4235 be used instead. 4237 An implementation may provide a library function (or possibly system 4238 call) to assist the user with the advanced features of SCTP. Note 4239 that in order for the sctp_sndrcvinfo structure to be filled in by 4240 sctp_recvmsg() the caller must enable the sctp_data_io_events with 4241 the SCTP_EVENTS option. Note that the setting of the 4242 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 4243 sctp_sndrcvinfo information to be extended. 4245 The function prototype is 4247 ssize_t sctp_recvmsg(int sd, 4248 void *msg, 4249 size_t len, 4250 struct sockaddr *from, 4251 socklen_t *fromlen 4252 struct sctp_sndrcvinfo *sinfo 4253 int *msg_flags); 4255 and the arguments are 4257 sd: The socket descriptor. 4259 msg: The message buffer to be filled. 4261 len: The length of the message buffer. 4263 from: A pointer to an address to be filled with the sender of this 4264 messages address. 4266 fromlen: An in/out parameter describing the from length. 4268 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 4269 receipt of the message. 4271 msg_flags: A pointer to an integer to be filled with any message 4272 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 4273 field. Options for the receive may also be passed into the value 4274 (e.g. MSG_PEEK). On return from the call, the msg_flags value 4275 will be different than what was sent in to the call. If 4276 implemented via a recvmsg() call, the msg_flags should only 4277 contain the value of the flags from the recvmsg() call. 4279 The call returns the number of bytes received, or -1 if an error 4280 occurred. The variable errno is then set appropriately. 4282 9.9. sctp_connectx() 4284 An implementation may provide a library function (or possibly system 4285 call) to assist the user with associating to an endpoint that is 4286 multi-homed. Much like sctp_bindx() this call allows a caller to 4287 specify multiple addresses at which a peer can be reached. The way 4288 the SCTP stack uses the list of addresses to set up the association 4289 is implementation dependent. This function only specifies that the 4290 stack will try to make use of all the addresses in the list when 4291 needed. 4293 Note that the list of addresses passed in is only used for setting up 4294 the association. It does not necessarily equal the set of addresses 4295 the peer uses for the resulting association. If the caller wants to 4296 find out the set of peer addresses, it must use sctp_getpaddrs() to 4297 retrieve them after the association has been set up. 4299 The function prototype is 4301 int sctp_connectx(int sd, 4302 struct sockaddr *addrs, 4303 int addrcnt, 4304 sctp_assoc_t *id); 4306 and the arguments are: 4308 sd: The socket descriptor. 4310 addrs: An array of addresses. 4312 addrcnt: The number of addresses in the array. 4314 id: An output parameter that if passed in as a non-NULL will return 4315 the association identification for the newly created association 4316 (if successful). 4318 The call returns 0 on success or -1 if an error occurred. The 4319 variable errno is then set appropriately. 4321 9.10. sctp_send() - DEPRECATED 4323 This function is deprecated, sctp_sendv() should be used instead. 4325 An implementation may provide another alternative function or system 4326 call to assist an application with the sending of data without the 4327 use of the CMSG header structures. 4329 The function prototype is 4331 ssize_t sctp_send(int sd, 4332 const void *msg, 4333 size_t len, 4334 const struct sctp_sndrcvinfo *sinfo, 4335 int flags); 4337 and the arguments are 4339 sd: The socket descriptor. 4341 msg: The message to be sent. 4343 len: The length of the message. 4345 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4346 in Section 5.3.2 for a sendmsg() call. 4348 flags: The same flags as used by the sendmsg() call flags (e.g. 4349 MSG_DONTROUTE). 4351 The call returns the number of bytes sent, or -1 if an error 4352 occurred. The variable errno is then set appropriately. 4354 This function call may also be used to terminate an association using 4355 an association identification by setting the sinfo.sinfo_flags to 4356 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4357 to be terminated. In such a case the len of the message can be zero. 4359 Using sctp_send() on a non-connected one-to-one style socket for 4360 implicit connection setup may or may not work depending on the SCTP 4361 implementation. 4363 Sending a message using sctp_send() is atomic unless explicit EOR 4364 marking is enabled on the socket specified by sd. 4366 9.11. sctp_sendx() - DEPRECATED 4368 This function is deprecated, sctp_sendv() should be used instead. 4370 An implementation may provide another alternative function or system 4371 call to assist an application with the sending of data without the 4372 use of the CMSG header structures that also gives a list of 4373 addresses. The list of addresses is provided for implicit 4374 association setup. In such a case the list of addresses serves the 4375 same purpose as the addresses given in sctp_connectx() (see 4376 Section 9.9). 4378 The function prototype is 4380 ssize_t sctp_sendx(int sd, 4381 const void *msg, 4382 size_t len, 4383 struct sockaddr *addrs, 4384 int addrcnt, 4385 struct sctp_sndrcvinfo *sinfo, 4386 int flags); 4388 and the arguments are: 4390 sd: The socket descriptor. 4392 msg: The message to be sent. 4394 len: The length of the message. 4396 addrs: is an array of addresses. 4398 addrcnt: The number of addresses in the array. 4400 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 4401 in Section 5.3.2 for a sendmsg() call. 4403 flags: The same flags as used by the sendmsg() call flags (e.g. 4404 MSG_DONTROUTE). 4406 The call returns the number of bytes sent, or -1 if an error 4407 occurred. The variable errno is then set appropriately. 4409 Note that in case of implicit connection setup, on return from this 4410 call the sinfo_assoc_id field of the sinfo structure will contain the 4411 new association id. 4413 This function call may also be used to terminate an association using 4414 an association identification by setting the sinfo.sinfo_flags to 4415 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 4416 to be terminated. In such a case the len of the message would be 4417 zero. 4419 Sending a message using sctp_sendx() is atomic unless explicit EOR 4420 marking is enabled on the socket specified by sd. 4422 Using sctp_sendx() on a non-connected one-to-one style socket for 4423 implicit connection setup may or may not work depending on the SCTP 4424 implementation. 4426 9.12. sctp_recvv() 4428 The function prototype is 4430 ssize_t sctp_recvv(int sd, 4431 const struct iovec *iov, 4432 int iovlen, 4433 struct sockaddr *from, 4434 socklen_t *fromlen, 4435 void *info, 4436 socklen_t *infolen, 4437 unsigned int *infotype, 4438 int *flags); 4440 The function sctp_recvv() provides an extensible way for the SCTP 4441 stack to pass up different SCTP attributes associated with a received 4442 message to an application. An implementation may provide 4443 sctp_recvv() as a library function or as a system call. 4445 This document defines two types of attributes which can be returned 4446 by this call, the attribute of the received message and the attribute 4447 of the next message in receive buffer. The caller enables the 4448 SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these 4449 attributes respectively. Attributes of the received message are 4450 returned in struct sctp_rcvinfo (Section 5.3.5) and attributes of the 4451 next message are returned in struct sctp_nxtinfo (Section 5.3.6). If 4452 both options are enabled, both attributes are returned using the 4453 following structure. 4455 struct sctp_recvv_rn { 4456 struct sctp_rcvinfo recvv_rcvinfo; 4457 struct sctp_nxtinfo recvv_nxtinfo; 4458 }; 4460 In future, new structures can be defined to hold new types of 4461 attributes. The new structures do not need to be based on struct 4462 sctp_recvv_rn or struct sctp_rcvinfo. 4464 This function takes the following arguments: 4466 sd: The socket descriptor. 4468 iov: The scatter buffer. Only one user message is returned in this 4469 buffer. 4471 iovlen: The number of elements in iov. 4473 from: A pointer to an address to be filled with the sender of the 4474 received message's address. 4476 fromlen: An in/out parameter describing the from length. 4478 info: A pointer to the buffer to hold the attributes of the received 4479 message. The structure type of info is determined by the 4480 info_type parameter. 4482 infolen: An in/out parameter describing the size of the info buffer. 4484 infotype: In return, *info_type is set to the type of the info 4485 buffer. The current defined values are: 4487 SCTP_RECVV_NOINFO: If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO 4488 options are not enabled, no attribute will be returned. If 4489 only the SCTP_RECVNXTINFO option is enabled but there is no 4490 next message in the buffer, there will also no attribute be 4491 returned. In these cases *info_type will be set to 4492 SCTP_RECVV_NOINFO. 4494 SCTP_RECVV_RCVINFO: The type of info is struct sctp_rcvinfo and 4495 the attribute is about the received message. 4497 SCTP_RECVV_NXTINFO: The type of info is struct sctp_nxtinfo and 4498 the attribute is about the next message in receive buffer. 4499 This is the case when only the SCTP_RECVNXTINFO option is 4500 enabled and there is a next message in buffer. 4502 SCTP_RECVV_RN: The type of info is struct sctp_recvv_rn. The 4503 recvv_rcvinfo field is the attribute of the received message 4504 and the recvv_nxtinfo field is the attribute of the next 4505 message in buffer. This is the case when both SCTP_RECVRCVINFO 4506 and SCTP_RECVNXTINFO options are enabled and there is a next 4507 message in the receive buffer. 4509 flags: A pointer to an integer to be filled with any message flags 4510 (e.g. MSG_NOTIFICATION). Note that this field is an in/out 4511 parameter. Options for the receive may also be passed into the 4512 value (e.g. MSG_PEEK). On return from the call, the flags value 4513 will be different than what was sent in to the call. If 4514 implemented via a recvmsg() call, the flags should only contain 4515 the value of the flags from the recvmsg() call when calling 4516 sctp_recvv() and on return it has the value from msg_flags. 4518 The call returns the number of bytes received, or -1 if an error 4519 occurred. The variable errno is then set appropriately. 4521 9.13. sctp_sendv() 4523 The function prototype is 4525 ssize_t sctp_sendv(int sd, 4526 const struct iovec *iov, 4527 int iovcnt, 4528 struct sockaddr *addrs, 4529 int addrcnt, 4530 void *info, 4531 socklen_t infolen, 4532 unsigned int infotype, 4533 int flags); 4535 The function sctp_sendv() provides an extensible way for an 4536 application to communicate different send attributes to the SCTP 4537 stack when sending a message. An implementation may provide 4538 sctp_sendv() as a library function or a system call. 4540 This document defines three types of attributes which can be used to 4541 describe a message to be sent. They are struct sctp_sndinfo 4542 (Section 5.3.4), struct sctp_prinfo (Section 5.3.7), and struct 4543 sctp_authinfo (Section 5.3.8). The following structure 4544 sctp_sendv_spa is defined to be used when more than one of the above 4545 attributes are needed to describe a message to be sent. 4547 struct sctp_sendv_spa { 4548 uint32_t sendv_flags; 4549 struct sctp_sndinfo sendv_sndinfo; 4550 struct sctp_prinfo sendv_prinfo; 4551 struct sctp_authinfo sendv_authinfo; 4552 }; 4554 The sendv_flags field holds a bit wise OR of SCTP_SEND_SNDINFO_VALID, 4555 SCTP_SEND_PRINFO_VALID and SCTP_SEND_AUTHINFO_VALID indicating if the 4556 sendv_sndinfo/sendv_prinfo/sendv_authinfo fields contain valid 4557 information. 4559 In future, when new send attributes are needed, new structures can be 4560 defined. But those new structures do not need to be based on any of 4561 the above defined structures. 4563 The function takes the following arguments: 4565 sd: The socket descriptor. 4567 iov: The gather buffer. The data in the buffer is treated as one 4568 single user message. 4570 iovcnt: The number of elements in iov. 4572 addrs: An array of addresses to be used to set up an association or 4573 one single address to be used to send the message. Pass in NULL 4574 if the caller does not want to set up an association nor want to 4575 send the message to a specific address. 4577 addrcnt: The number of addresses in the addrs array. 4579 info: A pointer to the buffer containing the attribute associated 4580 with the message to be sent. The type is indicated by info_type 4581 parameter. 4583 infolen: The length in bytes of info. 4585 infotype: Identifies the type of the information provided in info. 4586 The current defined values are: 4588 SCTP_SENDV_SNDINFO: The type of info is struct sctp_sndinfo. 4590 SCTP_SENDV_PRINFO: The type of info is struct sctp_prinfo. 4592 SCTP_SENDV_AUTHINFO: The type of info is struct sctp_authinfo. 4594 SCTP_SENDV_SPA: The type of info is struct sctp_sendv_spa. 4596 flags: The same flags as used by the sendmsg() call flags (e.g. 4597 MSG_DONTROUTE). 4599 The call returns the number of bytes sent, or -1 if an error 4600 occurred. The variable errno is then set appropriately. 4602 A note on one-to-many style socket. The struct sctp_sndinfo 4603 attribute must always be used in order to specify the association the 4604 message is to be sent on. The only case where it is not needed is 4605 when this call is used to set up a new association. 4607 The caller provides a list of addresses in the addrs parameter to set 4608 up an association. This function will behave like calling 4609 sctp_connectx() (see Section 9.9) first using the list of addresses 4610 and then calling sendmsg() with the given message and attributes. 4611 For an one-to-many style socket, if struct sctp_sndinfo attribute is 4612 provided, the snd_assoc_id field must be 0. When this function 4613 returns, the snd_assoc_id field will contain the association ID of 4614 the newly established association. Note that struct sctp_sndinfo 4615 attribute is not required to set up an association for one-to-many 4616 style socket. If this attribute is not provided, the caller can 4617 enable the SCTP_ASSOC_CHANGE notification and use the SCTP_COMM_UP 4618 message to find out the association ID. 4620 If the caller wants to send the message to a specific peer address 4621 (hence overriding the primary address), it can provide the specific 4622 address in the addrs parameter and provide a struct sctp_sndinfo 4623 attribute with the field snd_flags set to SCTP_ADDR_OVER. 4625 This function call may also be used to terminate an association. The 4626 caller provides an sctp_sndinfo attribute with the snd_flags set to 4627 SCTP_EOF. In this case the len of the message would be zero. 4629 Sending a message using sctp_sendv() is atomic unless explicit EOR 4630 marking is enabled on the socket specified by sd. 4632 10. IANA Considerations 4634 This document requires no actions from IANA. 4636 11. Security Considerations 4638 Many TCP and UDP implementations reserve port numbers below 1024 for 4639 privileged users. If the target platform supports privileged users, 4640 the SCTP implementation should restrict the ability to call bind() or 4641 sctp_bindx() on these port numbers to privileged users. 4643 Similarly unprivileged users should not be able to set protocol 4644 parameters that could result in the congestion control algorithm 4645 being more aggressive than permitted on the public Internet. These 4646 parameters are: 4648 o struct sctp_rtoinfo 4650 If an unprivileged user inherits a one-to-many style socket with open 4651 associations on a privileged port, it may be permitted to accept new 4652 associations, but it should not be permitted to open new 4653 associations. This could be relevant for the r* family of protocols. 4655 Applications using the one-to-many style sockets and using the 4656 interleave level if 0 are subject to denial of service attacks as 4657 described in Section 8.1.20. 4659 12. Acknowledgments 4661 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 4662 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 4663 early formation of this document. 4665 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 4666 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 4667 Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG 4668 mailing list for contributing valuable comments. 4670 A special thanks to Phillip Conrad, for his suggested text, quick and 4671 constructive insights, and most of all his persistent fighting to 4672 keep the interface to SCTP usable for the application programmer. 4674 13. References 4676 13.1. Normative References 4678 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 4679 Stevens, "Basic Socket Interface Extensions for IPv6", 4680 RFC 3493, February 2003. 4682 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4683 "Advanced Sockets Application Program Interface (API) for 4684 IPv6", RFC 3542, May 2003. 4686 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 4687 Conrad, "Stream Control Transmission Protocol (SCTP) 4688 Partial Reliability Extension", RFC 3758, May 2004. 4690 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 4691 "Authenticated Chunks for the Stream Control Transmission 4692 Protocol (SCTP)", RFC 4895, August 2007. 4694 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 4695 RFC 4960, September 2007. 4697 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 4698 Kozuka, "Stream Control Transmission Protocol (SCTP) 4699 Dynamic Address Reconfiguration", RFC 5061, 4700 September 2007. 4702 13.2. Informative References 4704 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4705 RFC 793, September 1981. 4707 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4708 August 1980. 4710 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 4711 Functional Specification", RFC 1644, July 1994. 4713 Appendix A. One-to-One Style Code Example 4715 The following code is an implementation of a simple client which 4716 sends a number of messages marked for unordered delivery to an echo 4717 server making use of all outgoing streams. The example shows how to 4718 use some features of one-to-one style IPv4 SCTP sockets, including: 4720 o Creating and connecting an SCTP socket. 4722 o Requesting to negotiate a number of outgoing streams. 4724 o Determining the negotiated number of outgoing streams. 4726 o Setting an adaptation layer indication. 4728 o Sending messages with a given payload protocol identifier on a 4729 particular stream using sctp_sendv(). 4731 #include 4732 #include 4733 #include 4734 #include 4735 #include 4736 #include 4737 #include 4738 #include 4739 #include 4741 #define PORT 9 4742 #define ADDR "127.0.0.1" 4743 #define SIZE_OF_MESSAGE 1000 4744 #define NUMBER_OF_MESSAGES 10 4745 #define PPID 1234 4747 int 4748 main(void) { 4749 unsigned int i; 4750 int sd; 4751 struct sockaddr_in addr; 4752 char buffer[SIZE_OF_MESSAGE]; 4753 struct iovec iov; 4754 struct sctp_status status; 4755 struct sctp_initmsg init; 4756 struct sctp_sndinfo info; 4757 struct sctp_setadaptation ind; 4758 socklen_t opt_len; 4760 /* Create a one-to-one style SCTP socket. */ 4761 if ((sd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) < 0) { 4762 perror("socket"); 4763 exit(1); 4764 } 4766 /* Prepare for requesting 2048 outgoing streams. */ 4767 memset(&init, 0, sizeof(init)); 4768 init.sinit_num_ostreams = 2048; 4769 if (setsockopt(sd, IPPROTO_SCTP, SCTP_INITMSG, 4770 &init, (socklen_t)sizeof(init)) < 0) { 4771 perror("setsockopt"); 4772 exit(1); 4773 } 4774 ind.ssb_adaptation_ind = 0x01020304; 4775 if (setsockopt(sd, IPPROTO_SCTP, SCTP_ADAPTATION_LAYER, 4776 &ind, (socklen_t)sizeof(ind)) < 0) { 4777 perror("setsockopt"); 4778 exit(1); 4779 } 4781 /* Connect to the discard server. */ 4782 memset(&addr, 0, sizeof(addr)); 4783 #ifdef HAVE_SIN_LEN 4784 addr.sin_len = sizeof(struct sockaddr_in); 4785 #endif 4786 addr.sin_family = AF_INET; 4787 addr.sin_port = htons(PORT); 4788 addr.sin_addr.s_addr = inet_addr(ADDR); 4789 if (connect(sd, 4790 (const struct sockaddr *)&addr, 4791 sizeof(struct sockaddr_in)) < 0) { 4792 perror("connect"); 4793 exit(1); 4794 } 4796 /* Get the actual number of outgoing streams. */ 4797 memset(&status, 0, sizeof(status)); 4798 opt_len = (socklen_t)sizeof(status); 4799 if (getsockopt(sd, IPPROTO_SCTP, SCTP_STATUS, 4800 &status, &opt_len) < 0) { 4801 perror("getsockopt"); 4802 exit(1); 4803 } 4805 memset(&info, 0, sizeof(info)); 4806 info.snd_ppid = htonl(PPID); 4807 info.snd_flags = SCTP_UNORDERED; 4808 memset(buffer, 'A', SIZE_OF_MESSAGE); 4809 iov.iov_base = buffer; 4810 iov.iov_len = SIZE_OF_MESSAGE; 4811 for (i = 0; i < NUMBER_OF_MESSAGES; i++) { 4812 info.snd_sid = i % status.sstat_outstrms; 4813 if (sctp_sendv(sd, 4814 (const struct iovec *)&iov, 1, 4815 NULL, 0, 4816 &info, sizeof(info), SCTP_SENDV_SNDINFO, 4817 0) < 0) { 4818 perror("sctp_sendv"); 4819 exit(1); 4820 } 4821 } 4822 if (close(sd) < 0) { 4823 perror("close"); 4824 exit(1); 4825 } 4826 return(0); 4827 } 4829 Appendix B. One-to-Many Style Code Example 4831 The following code is a simple implementation of a discard server 4832 over SCTP. The example shows how to use some features of one-to-many 4833 style IPv6 SCTP sockets, including: 4835 o Opening and binding of a socket. 4837 o Enabling notifications. 4839 o Handling notifications. 4841 o Configuring the auto close timer. 4843 o Using sctp_recvv() to receive messages. 4845 Please note that this server can be used in combination with the 4846 client described in Appendix A. 4848 #include 4849 #include 4850 #include 4851 #include 4852 #include 4853 #include 4854 #include 4855 #include 4856 #include 4858 #define BUFFER_SIZE (1<<16) 4859 #define PORT 9 4860 #define ADDR "0.0.0.0" 4861 #define TIMEOUT 5 4863 static void 4864 print_notification(void *buf) 4865 { 4866 struct sctp_assoc_change *sac; 4867 struct sctp_paddr_change *spc; 4868 struct sctp_adaptation_event *sad; 4869 union sctp_notification *snp; 4870 char addrbuf[INET6_ADDRSTRLEN]; 4871 const char *ap; 4872 struct sockaddr_in *sin; 4873 struct sockaddr_in6 *sin6; 4875 snp = buf; 4877 switch (snp->sn_header.sn_type) { 4878 case SCTP_ASSOC_CHANGE: 4879 sac = &snp->sn_assoc_change; 4880 printf("^^^ Association change: "); 4881 switch (sac->sac_state) { 4882 case SCTP_COMM_UP: 4883 printf("Communication up (streams (in/out)=(%u/%u)).\n", 4884 sac->sac_inbound_streams, sac->sac_outbound_streams); 4885 break; 4886 case SCTP_COMM_LOST: 4887 printf("Communication lost (error=%d).\n", sac->sac_error); 4888 break; 4889 case SCTP_RESTART: 4890 printf("Communication restarted (streams (in/out)=(%u/%u).\n", 4891 sac->sac_inbound_streams, sac->sac_outbound_streams); 4892 break; 4893 case SCTP_SHUTDOWN_COMP: 4894 printf("Communication completed.\n"); 4895 break; 4896 case SCTP_CANT_STR_ASSOC: 4897 printf("Communication couldn't be started.\n"); 4898 break; 4899 default: 4900 printf("Unknown state: %d.\n", sac->sac_state); 4901 break; 4902 } 4903 break; 4904 case SCTP_PEER_ADDR_CHANGE: 4905 spc = &snp->sn_paddr_change; 4906 if (spc->spc_aaddr.ss_family == AF_INET) { 4907 sin = (struct sockaddr_in *)&spc->spc_aaddr; 4908 ap = inet_ntop(AF_INET, &sin->sin_addr, 4909 addrbuf, INET6_ADDRSTRLEN); 4910 } else { 4911 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 4912 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 4913 addrbuf, INET6_ADDRSTRLEN); 4914 } 4915 printf("^^^ Peer Address change: %s ", ap); 4916 switch (spc->spc_state) { 4917 case SCTP_ADDR_AVAILABLE: 4918 printf("is available.\n"); 4919 break; 4920 case SCTP_ADDR_UNREACHABLE: 4921 printf("is not available (error=%d).\n", spc->spc_error); 4922 break; 4923 case SCTP_ADDR_REMOVED: 4924 printf("was removed.\n"); 4925 break; 4926 case SCTP_ADDR_ADDED: 4927 printf("was added.\n"); 4928 break; 4929 case SCTP_ADDR_MADE_PRIM: 4930 printf("is primary.\n"); 4931 break; 4932 default: 4933 printf("unknown state (%d).\n", spc->spc_state); 4934 break; 4935 } 4936 break; 4937 case SCTP_SHUTDOWN_EVENT: 4938 printf("^^^ Shutdown received.\n"); 4939 break; 4940 case SCTP_ADAPTATION_INDICATION: 4941 sad = &snp->sn_adaptation_event; 4942 printf("^^^ Adaptation indication 0x%08x received.\n", 4943 sad->sai_adaptation_ind); 4944 break; 4945 default: 4946 printf("^^^ Unknown event of type: %u.\n", 4947 snp->sn_header.sn_type); 4948 break; 4949 }; 4950 } 4952 int 4953 main(void) { 4954 int sd, flags, timeout; 4955 ssize_t n; 4956 unsigned int i; 4957 union { 4958 struct sockaddr sa; 4959 struct sockaddr_in sin; 4960 struct sockaddr_in6 sin6; 4961 } addr; 4962 socklen_t fromlen, infolen; 4963 struct sctp_rcvinfo info; 4964 unsigned int infotype; 4965 struct iovec iov; 4966 char buffer[BUFFER_SIZE]; 4967 struct sctp_event event; 4968 uint16_t event_types[] = {SCTP_ASSOC_CHANGE, 4969 SCTP_PEER_ADDR_CHANGE, 4970 SCTP_SHUTDOWN_EVENT, 4971 SCTP_ADAPTATION_INDICATION }; 4973 /* Create a 1-to-many style SCTP socket. */ 4974 if ((sd = socket(AF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP)) < 0) { 4975 perror("socket"); 4976 exit(1); 4977 } 4979 /* Enable the events of interest. */ 4980 memset(&event, 0, sizeof(event)); 4981 event.se_assoc_id = SCTP_FUTURE_ASSOC; 4982 event.se_on = 1; 4983 for (i = 0; i < sizeof(event_types)/sizeof(uint16_t); i++) { 4984 event.se_type = event_types[i]; 4985 if (setsockopt(sd, IPPROTO_SCTP, SCTP_EVENT, 4986 &event, sizeof(event)) < 0) { 4987 perror("setsockopt"); 4988 exit(1); 4989 } 4990 } 4992 /* Configure auto-close timer. */ 4993 timeout = TIMEOUT; 4994 if (setsockopt(sd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 4995 &timeout, 4) < 0) { 4996 perror("setsockopt SCTP_AUTOCLOSE"); 4997 exit(1); 4998 } 5000 /* Bind the socket to all local addresses. */ 5001 memset(&addr, 0, sizeof(addr)); 5002 #ifdef HAVE_SIN6_LEN 5003 addr.sin6.sin6_len = sizeof(addr.sin6); 5004 #endif 5005 addr.sin6.sin6_family = AF_INET6; 5006 addr.sin6.sin6_port = htons(PORT); 5007 addr.sin6.sin6_addr = in6addr_any; 5008 if (bind(sd, &addr.sa, sizeof(addr.sin6)) < 0) { 5009 perror("bind"); 5010 exit(1); 5011 } 5012 /* Enable accepting associations. */ 5013 if (listen(sd, 1) < 0) { 5014 perror("listen"); 5015 exit(1); 5016 } 5018 for (;;) { 5019 flags = 0; 5020 memset(&addr, 0, sizeof(addr)); 5021 fromlen = (socklen_t)sizeof(addr); 5022 memset(&info, 0, sizeof(info)); 5023 infolen = (socklen_t)sizeof(info); 5024 infotype = 0; 5025 iov.iov_base = buffer; 5026 iov.iov_len = BUFFER_SIZE; 5028 n = sctp_recvv(sd, &iov, 1, 5029 &addr.sa, &fromlen, 5030 &info, &infolen, &infotype, 5031 &flags); 5033 if (flags & MSG_NOTIFICATION) { 5034 print_notification(iov.iov_base); 5035 } else { 5036 char addrbuf[INET6_ADDRSTRLEN]; 5037 const char *ap; 5038 in_port_t port; 5040 if (addr.sa.sa_family == AF_INET) { 5041 ap = inet_ntop(AF_INET, &addr.sin.sin_addr, 5042 addrbuf, INET6_ADDRSTRLEN); 5043 port = ntohs(addr.sin.sin_port); 5044 } else { 5045 ap = inet_ntop(AF_INET6, &addr.sin6.sin6_addr, 5046 addrbuf, INET6_ADDRSTRLEN); 5047 port = ntohs(addr.sin6.sin6_port); 5048 } 5049 printf("Message received from %s:%u: len=%d", 5050 ap, port, (int)n); 5051 switch (infotype) { 5052 case SCTP_RECVV_RCVINFO: 5053 printf(", sid=%u", info.rcv_sid); 5054 if (info.rcv_flags & SCTP_UNORDERED) { 5055 printf(", unordered"); 5056 } else { 5057 printf(", ssn=%u", info.rcv_ssn); 5058 } 5059 printf(", tsn=%u", info.rcv_tsn); 5060 printf(", ppid=%u.\n", ntohl(info.rcv_ppid)); 5061 break; 5062 case SCTP_RECVV_NOINFO: 5063 case SCTP_RECVV_NXTINFO: 5064 case SCTP_RECVV_RN: 5065 printf(".\n"); 5066 break; 5067 default: 5068 printf(" unknown infotype.\n"); 5069 } 5070 } 5071 } 5073 if (close(sd) < 0) { 5074 perror("close"); 5075 exit(1); 5076 } 5078 return (0); 5079 } 5081 Authors' Addresses 5083 Randall R. Stewart 5084 Huawei 5085 Chapin, SC 29036 5086 USA 5088 Email: randall@lakerest.net 5090 Michael Tuexen 5091 Muenster University of Applied Sciences 5092 Stegerwaldstr. 39 5093 48565 Steinfurt 5094 Germany 5096 Email: tuexen@fh-muenster.de 5098 Kacheong Poon 5099 Oracle Corporation 5101 Email: ka-cheong.poon@oracle.com 5102 Peter Lei 5103 Cisco Systems, Inc. 5104 9501 Technology Blvd 5105 West Office Center 5106 Rosemont, IL 60018 5107 USA 5109 Email: peterlei@cisco.com 5111 Vladislav Yasevich 5112 HP 5113 110 Spitrook Rd 5114 Nashua, NH 03062 5115 USA 5117 Email: vladislav.yasevich@hp.com