idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-22.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 (March 7, 2010) is 5157 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 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 3 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 K. Poon 5 Expires: September 8, 2010 Sun Microsystems, Inc. 6 M. Tuexen 7 Muenster Univ. of Applied Sciences 8 V. Yasevich 9 HP 10 P. Lei 11 Cisco Systems, Inc. 12 March 7, 2010 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-22.txt 17 Abstract 19 This document describes a mapping of the Stream Control Transmission 20 Protocol SCTP into a sockets API. The benefits of this mapping 21 include compatibility for TCP applications, access to new SCTP 22 features and a consolidated error and event notification scheme. 24 Status of this Memo 26 This Internet-Draft is submitted to IETF in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF), its areas, and its working groups. Note that 31 other groups may also distribute working documents as Internet- 32 Drafts. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 The list of current Internet-Drafts can be accessed at 40 http://www.ietf.org/ietf/1id-abstracts.txt. 42 The list of Internet-Draft Shadow Directories can be accessed at 43 http://www.ietf.org/shadow.html. 45 This Internet-Draft will expire on September 8, 2010. 47 Copyright Notice 48 Copyright (c) 2010 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the BSD License. 61 This document may contain material from IETF Documents or IETF 62 Contributions published or made publicly available before November 63 10, 2008. The person(s) controlling the copyright in some of this 64 material may not have granted the IETF Trust the right to allow 65 modifications of such material outside the IETF Standards Process. 66 Without obtaining an adequate license from the person(s) controlling 67 the copyright in such materials, this document may not be modified 68 outside the IETF Standards Process, and derivative works of it may 69 not be created outside the IETF Standards Process, except to format 70 it for publication as an RFC or to translate it into languages other 71 than English. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 7 77 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 7 78 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 7 79 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 8 80 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 9 81 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 10 82 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 10 83 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 12 84 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 13 85 3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 13 86 3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14 87 3.4. Special considerations . . . . . . . . . . . . . . . . . . 15 88 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . . 16 89 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 16 90 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 17 91 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 18 92 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 19 93 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . . 19 94 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 20 95 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 21 96 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . . 21 97 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 22 98 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 22 99 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 23 100 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 23 101 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 24 102 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 24 103 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 25 104 5.2.3. Extended SCTP Header Information Structure 105 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 28 106 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) . . . . 29 107 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 31 108 5.2.6. SCTP Next Receive Information Structure 109 (SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . . 32 110 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . . 32 111 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) . . . 33 112 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 33 113 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 34 114 5.3.2. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 35 115 5.3.3. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 37 116 5.3.4. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 38 117 5.3.5. SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . 38 118 5.3.6. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 39 119 5.3.7. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . . 40 120 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 41 121 5.3.9. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 41 122 5.3.10. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 42 123 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . . 43 124 5.4. Ancillary Data Considerations and Semantics . . . . . . . 43 125 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 43 126 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 43 127 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 44 128 6. Common Operations for Both Styles . . . . . . . . . . . . . . 45 129 6.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . . 45 130 6.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 47 131 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 48 132 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 48 133 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 49 134 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 50 135 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 50 136 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 51 137 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 53 138 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 53 139 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 53 140 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 54 141 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 54 142 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . . 54 143 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 54 144 7.1.10. Set Adaptation Layer Indicator 145 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 55 146 7.1.11. Enable/Disable Message Fragmentation 147 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 55 148 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 55 149 7.1.13. Set Default Send Parameters 150 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 58 151 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) . 58 152 7.1.15. Set/Clear IPv4 Mapped Addresses 153 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 58 154 7.1.16. Get or Set the Maximum Fragmentation Size 155 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 58 156 7.1.17. Get or Set the List of Supported HMAC Identifiers 157 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 59 158 7.1.18. Get or Set the Active Shared Key 159 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 60 160 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 60 161 7.1.20. Get or Set Fragmented Interleave 162 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 61 163 7.1.21. Set or Get the SCTP Partial Delivery Point 164 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 62 165 7.1.22. Set or Get the Use of Extended Receive Info 166 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 63 167 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . . 63 168 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 63 169 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 64 170 7.1.26. Enable or Disable Explicit EOR Marking 171 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 64 172 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . . 64 173 7.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 65 174 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 65 175 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 65 176 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 66 177 7.2.3. Get the List of Chunks the Peer Requires to be 178 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 67 179 7.2.4. Get the List of Chunks the Local Endpoint Requires 180 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 68 181 7.2.5. Get the Current Number of Associations 182 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 68 183 7.2.6. Get the Current Identifiers of Associations 184 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 68 185 7.3. Write-Only Options . . . . . . . . . . . . . . . . . . . . 69 186 7.3.1. Set Peer Primary Address 187 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 69 188 7.3.2. Add a Chunk That Must Be Authenticated 189 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 69 190 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . . 70 191 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . . 70 192 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . . 71 193 7.4. Ancillary Data and Notification Interest Options . . . . . 71 194 8. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 74 195 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 75 196 8.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . . 76 197 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 77 198 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 77 199 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 78 200 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 78 201 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 78 202 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 79 203 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 80 204 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 81 205 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 82 206 8.12. sctp_getaddrlen() . . . . . . . . . . . . . . . . . . . . 83 207 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83 208 10. Security Considerations . . . . . . . . . . . . . . . . . . . 83 209 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 84 210 12. Normative References . . . . . . . . . . . . . . . . . . . . . 84 211 Appendix A. One-to-One Style Code Example . . . . . . . . . . . . 85 212 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 90 213 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 91 215 1. Introduction 217 The sockets API has provided a standard mapping of the Internet 218 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 219 [RFC0768] have benefited from this standard representation and access 220 method across many diverse platforms. SCTP is a new protocol that 221 provides many of the characteristics of TCP but also incorporates 222 semantics more akin to UDP. This document defines a method to map 223 the existing sockets API for use with SCTP, providing both a base for 224 access to new features and compatibility so that most existing TCP 225 applications can be migrated to SCTP with few (if any) changes. 227 There are three basic design objectives: 228 1. Maintain consistency with existing sockets APIs: We define a 229 sockets mapping for SCTP that is consistent with other sockets 230 API protocol mappings (for instance UDP, TCP, IPv4, and IPv6). 231 2. Support a one-to-many style interface: This set of semantics is 232 similar to that defined for connection-less protocols, such as 233 UDP. A one-to-many style SCTP socket should be able to control 234 multiple SCTP associations. This is similar to a UDP socket, 235 which can communicate with many peer endpoints. Each of these 236 associations is assigned an association ID so that an application 237 can use the ID to differentiate them. Note that SCTP is 238 connection-oriented in nature, and it does not support broadcast 239 or multicast communications, as UDP does. 240 3. Support a one-to-one style interface: This interface supports a 241 similar semantics as sockets for connection-oriented protocols, 242 such as TCP. A one-to-one style SCTP socket should only control 243 one SCTP association. One purpose of defining this interface is 244 to allow existing applications built on other connection-oriented 245 protocols be ported to use SCTP with very little effort. And 246 developers familiar with those semantics can easily adapt to 247 SCTP. Another purpose is to make sure that existing mechanisms 248 in most operating systems dealing with sockets, such as select(), 249 should continue to work with this style of socket. Extensions 250 are added to this mapping to provide mechanisms to exploit new 251 features of SCTP. 253 Goals 2 and 3 are not compatible, so in this document we define two 254 modes of mapping, namely the one-to-many style mapping and the one- 255 to-one style mapping. These two modes share some common data 256 structures and operations, but will require the use of two different 257 application programming styles. Note that all new SCTP features can 258 be used with both styles of socket. The decision on which one to use 259 depends mainly on the nature of applications. 261 A mechanism is defined to extract a one-to-many style SCTP 262 association into a one-to-one style socket. 264 Some of the SCTP mechanisms cannot be adequately mapped to an 265 existing socket interface. In some cases, it is more desirable to 266 have a new interface instead of using existing socket calls. 267 Section 8 of this document describes those new interfaces. 269 2. Data Types 271 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 272 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 273 (e.g. uint16_t). We also assume the argument data types from 1003.1g 274 when possible (e.g. the final argument to setsockopt() is a size_t 275 value). Whenever buffer sizes are specified, the POSIX 1003.1 size_t 276 data type is used. 278 3. One-to-Many Style Interface 280 The one-to-many style interface has the following characteristics: 281 o Outbound association setup is implicit. 282 o Messages are delivered in complete messages (with one notable 283 exception). 284 o There is a 1 to MANY relationship between socket and association. 286 3.1. Basic Operation 288 A typical server in this style uses the following socket calls in 289 sequence to prepare an endpoint for servicing requests: 290 o socket() 291 o bind() 292 o listen() 293 o recvmsg() 294 o sendmsg() 295 o close() 297 A typical client uses the following calls in sequence to setup an 298 association with a server to request services: 299 o socket() 300 o sendmsg() 301 o recvmsg() 302 o close() 304 In this style, by default, all the associations connected to the 305 endpoint are represented with a single socket. Each association is 306 assigned an association ID (type is sctp_assoc_t) so that an 307 application can use it to differentiate between them. In some 308 implementations, the peer endpoints' addresses can also be used for 309 this purpose. But this is not required for performance reasons. If 310 an implementation does not support using addresses to differentiate 311 between different associations, the sendto() call can only be used to 312 setup an association implicitly. It cannot be used to send data to 313 an established association as the association ID cannot be specified. 315 Once as association ID is assigned to an SCTP association, that ID 316 will not be reused until the application explicitly terminates the 317 association. The resources belonging to that association will not be 318 freed until that happens. This is similar to the close() operation 319 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 320 option (section 7.1.8) is set. In this case, after the association 321 is terminated gracefully and automatically, the association ID 322 assigned to it can be reused. All applications using this option 323 should be aware of this to avoid the possible problem of sending data 324 to an incorrect peer endpoint. 326 If the server or client wishes to branch an existing association off 327 to a separate socket, it is required to call sctp_peeloff() and to 328 specify the association identifier. The sctp_peeloff() call will 329 return a new socket which can then be used with recv() and send() 330 functions for message passing. See Section 8.2 for more on branched- 331 off associations. The returned socket is a one-to-one style socket. 333 Once an association is branched off to a separate socket, it becomes 334 completely separated from the original socket. All subsequent 335 control and data operations to that association must be done through 336 the new socket. For example, the close operation on the original 337 socket will not terminate any associations that have been branched 338 off to a different socket. 340 We will discuss the one-to-many style socket calls in more detail in 341 the following subsections. 343 3.1.1. socket() 345 Applications use socket() to create a socket descriptor to represent 346 an SCTP endpoint. 348 The function prototype is 350 int socket(int domain, 351 int type, 352 int protocol); 354 and one uses PF_INET or PF_INET6 as the domain, SOCK_SEQPACKET as the 355 type and IPPROTO_SCTP as the protocol. 357 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 358 socket. 360 Using the PF_INET domain indicates the creation of an endpoint which 361 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 362 can use both IPv6 and IPv4 addresses. 364 3.1.2. bind() 366 Applications use bind() to specify which local address and port the 367 SCTP endpoint should associate itself with. 369 An SCTP endpoint can be associated with multiple addresses. To do 370 this, sctp_bindx() is introduced in Section 8.1 to help applications 371 do the job of associating multiple addresses. But note that an 372 endpoint can only be associated with one local port. 374 These addresses associated with a socket are the eligible transport 375 addresses for the endpoint to send and receive data. The endpoint 376 will also present these addresses to its peers during the association 377 initialization process, see [RFC4960]. 379 After calling bind(), if the endpoint wishes to accept new 380 associations on the socket, it must call listen() (see 381 Section 3.1.3). 383 The function prototype of bind() is 385 int bind(int sd, 386 struct sockaddr *addr, 387 socklen_t addrlen); 389 and the arguments are 390 sd: The socket descriptor returned by socket(). 391 addr: The address structure (struct sockaddr_in for an IPv4 address 392 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 393 addrlen: The size of the address structure. 395 If sd is an IPv4 socket, the address passed must be an IPv4 address. 396 If the sd is an IPv6 socket, the address passed can either be an IPv4 397 or an IPv6 address. 399 Applications cannot call bind() multiple times to associate multiple 400 addresses to an endpoint. After the first call to bind(), all 401 subsequent calls will return an error. 403 If the IP address part of addr is specified as a wildcard (INADDR_ANY 404 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 405 IPv6 address), the operating system will associate the endpoint with 406 an optimal address set of the available interfaces. If the IPv4 407 sin_port or IPv6 sin6_port is set to 0, the operating system will 408 choose an ephemeral port for the endpoint. 410 If a bind() is not called prior to a sendmsg() call that initiates a 411 new association, the system picks an ephemeral port and will choose 412 an address set equivalent to binding with a wildcard address. One of 413 those addresses will be the primary address for the association. 414 This automatically enables the multi-homing capability of SCTP. 416 3.1.3. listen() 418 By default, a one-to-many style socket does not accept new 419 association requests. An application uses listen() to mark a socket 420 as being able to accept new associations. 422 The function prototype is 424 int listen(int sd, 425 int backlog); 427 and the arguments are 428 sd: The socket descriptor of the endpoint. 429 backlog: If backlog is non-zero, enable listening else disable 430 listening. 432 Note that one-to-many style socket consumers do not need to call 433 accept to retrieve new associations. Calling accept() on a one-to- 434 many style socket should return EOPNOTSUPP. Rather, new associations 435 are accepted automatically, and notifications of the new associations 436 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 437 these notifications are enabled). Clients will typically not call 438 listen(), so that they can be assured that the only associations on 439 the socket will be the ones those actively initiated. Server or 440 peer-to-peer sockets, on the other hand, will always accept new 441 associations, so a well-written application using server one-to-many 442 style sockets must be prepared to handle new associations from 443 unwanted peers. 445 Also note that the SCTP_ASSOC_CHANGE event provides the association 446 ID for a new association, so if applications wish to use the 447 association ID as input to other socket calls, they should ensure 448 that the SCTP_ASSOC_CHANGE event is enabled. 450 3.1.4. sendmsg() and recvmsg() 452 An application uses the sendmsg() and recvmsg() call to transmit data 453 to and receive data from its peer. 455 The function prototypes are 457 ssize_t sendmsg(int sd, 458 const struct msghdr *message, 459 int flags); 461 and 463 ssize_t recvmsg(int sd, 464 struct msghdr *message, 465 int flags); 467 using the arguments: 468 sd: The socket descriptor of the endpoint. 469 message: Pointer to the msghdr structure which contains a single 470 user message and possibly some ancillary data. See Section 5 for 471 complete description of the data structures. 472 flags: No new flags are defined for SCTP at this level. See 473 Section 5 for SCTP specific flags used in the msghdr structure. 475 As described in Section 5, different types of ancillary data can be 476 sent and received along with user data. When sending, the ancillary 477 data is used to specify the sent behavior, such as the SCTP stream 478 number to use. When receiving, the ancillary data is used to 479 describe the received data, such as the SCTP stream sequence number 480 of the message. 482 When sending user data with sendmsg(), the msg_name field in the 483 msghdr structure will be filled with one of the transport addresses 484 of the intended receiver. If there is no existing association 485 between the sender and the intended receiver, the sender's SCTP stack 486 will set up a new association and then send the user data (see 487 Section 3.2 for more on implicit association setup). If sendmsg() is 488 called with no data and there is no existing assocation, a new one 489 will be established. The SCTP_INIT type ancillary data can be used 490 to change some of the parameters used to set up a new association. 491 If sendmsg() is called with NULL data, and there is no existing 492 association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is 493 retured and errno is set to EINVAL. Sending a message using 494 sendmsg() is atomic unless explicit EOR marking is enabled on the 495 socket specified by sd (see Section 7.1.26). 497 If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will 498 be delivered if that notification has been enabled, and no more data 499 can be sent to that association. Any attempt to send more data will 500 cause sendmsg() to return with an ESHUTDOWN error. Note that the 501 socket is still open for reading at this point so it is possible to 502 retrieve notifications. 504 When receiving a user message with recvmsg(), the msg_name field in 505 the msghdr structure will be populated with the source transport 506 address of the user data. The caller of recvmsg() can use this 507 address information to determine to which association the received 508 user message belongs. Note that if SCTP_ASSOC_CHANGE events are 509 disabled, applications must use the peer transport address provided 510 in the msg_name field by recvmsg() to perform correlation to an 511 association, since they will not have the association ID. 513 If all data in a single message has been delivered, MSG_EOR will be 514 set in the msg_flags field of the msghdr structure (see section 515 Section 5.1). 517 If the application does not provide enough buffer space to completely 518 receive a data message, MSG_EOR will not be set in msg_flags. 519 Successive reads will consume more of the same message until the 520 entire message has been delivered, and MSG_EOR will be set. 522 If the SCTP stack is running low on buffers, it may partially deliver 523 a message. In this case, MSG_EOR will not be set, and more calls to 524 recvmsg() will be necessary to completely consume the message. Only 525 one message at a time can be partially delivered in any stream. The 526 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 527 what interlacing of messages occurs for both the one-to-one and the 528 one-to-many model sockets. Please consult Section 7.1.20 for further 529 details on message delivery options. 531 Note, if the socket is a branched-off socket that only represents one 532 association (see Section 3.1), the msg_name field can be used to 533 override the primary address when sending data. 535 3.1.5. close() 537 Applications use close() to perform graceful shutdown (as described 538 in Section 10.1 of [RFC4960]) on ALL the associations currently 539 represented by a one-to-many style socket. 541 The function prototype is 543 int close(int sd); 545 and the argument is 546 sd: The socket descriptor of the associations to be closed. 548 To gracefully shutdown a specific association represented by the one- 549 to-many style socket, an application should use the sendmsg() call, 550 and include the SCTP_EOF flag. A user may optionally terminate an 551 association non-gracefully by sending with the SCTP_ABORT flag and 552 possibly passing a user specified abort code in the data field. Both 553 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 554 Section 5.2.2) in the sendmsg() call. 556 If sd in the close() call is a branched-off socket representing only 557 one association, the shutdown is performed on that association only. 559 3.1.6. connect() 561 An application may use the connect() call in the one-to-many style to 562 initiate an association without sending data. 564 The function prototype is 566 int connect(int sd, 567 const struct sockaddr *nam, 568 socklen_t len); 570 and the arguments are 571 sd: The socket descriptor to have a new association added to. 572 nam: The address structure (struct sockaddr_in for an IPv4 address 573 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 574 len: The size of the address. 576 Multiple connect() calls can be made on the same socket to create 577 multiple associations. This is different from the semantics of 578 connect() on a UDP socket. 580 3.2. Implicit Association Setup 582 Implicit association setup applies only to one-to-many style sockets. 583 For one-to-one style sockets implicit association setup must not be 584 used. 586 Once the bind() call is complete on a one-to-many style socket, the 587 application can begin sending and receiving data using the sendmsg()/ 588 recvmsg() or sendto()/recvfrom() calls, without going through any 589 explicit association setup procedures (i.e., no connect() calls 590 required). 592 Whenever sendmsg() or sendto() is called and the SCTP stack at the 593 sender finds that there is no association existing between the sender 594 and the intended receiver (identified by the address passed either in 595 the msg_name field of msghdr structure in the sendmsg() call or the 596 dest_addr field in the sendto() call), the SCTP stack will 597 automatically setup an association to the intended receiver. 599 Upon the successful association setup an SCTP_COMM_UP notification 600 will be dispatched to the socket at both the sender and receiver 601 side. This notification can be read by the recvmsg() system call 602 (see Section 3.1.3). 604 Note, if the SCTP stack at the sender side supports bundling, the 605 first user message may be bundled with the COOKIE ECHO message 606 [RFC4960]. 608 When the SCTP stack sets up a new association implicitly, the 609 SCTP_INIT type ancillary data may also be passed along (see 610 Section 5.2.1 for details of the data structures) to change some 611 parameters used in setting up new association. 613 If this information is not present in the sendmsg() call, or if the 614 implicit association setup is triggered by a sendto() call, the 615 default association initialization parameters will be used. These 616 default association parameters may be set with respective 617 setsockopt() calls or be left to the system defaults. 619 Implicit association setup cannot be initiated by send() calls. 621 3.3. Non-blocking mode 623 Some SCTP users might want to avoid blocking when they call socket 624 interface function. 626 Once a bind() and/or subsequent sctp_bindx() calls are complete on a 627 one-to-many style socket, an application may set the non-blocking 628 option by a fcntl() (such as O_NONBLOCK). After setting the socket 629 to non-blocking mode, the sendmsg() function returns immediately. 630 The success or failure of sending the data message (with possible 631 SCTP_INITMSG ancillary data) will be signaled by the 632 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or CANT_START_ASSOC. If 633 user data could not be sent (due to a CANT_START_ASSOC), the sender 634 will also receive an SCTP_SEND_FAILED event. Events can be received 635 by the user calling recvmsg(). A server (having called listen()) is 636 also notified of an association up event by the reception of an 637 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 638 possibly the reception of the first data message. 640 In order to shutdown the association gracefully, the user must call 641 sendmsg() with no data and with the SCTP_EOF flag set. The function 642 returns immediately, and completion of the graceful shutdown is 643 indicated by an SCTP_ASSOC_CHANGE notification of type 644 SHUTDOWN_COMPLETE (see Section 5.3.2). Note that this can also be 645 done using the sctp_send() call described in Section 8.10. 647 An application is recommended to use caution when using select() (or 648 poll()) for writing on a one-to-many style socket. The reason being 649 that the interpretation of select on write is implementation 650 specific. Generally a positive return on a select on write would 651 only indicate that one of the associations represented by the one-to- 652 many socket is writable. An application that writes after the 653 select() returns may still block since the association that was 654 writeable is not the destination association of the write call. 655 Likewise select() (or poll()) for reading from a one-to-many socket 656 will only return an indication that one of the associations 657 represented by the socket has data to be read. 659 An application that wishes to know that a particular association is 660 ready for reading or writing should either use the one-to-one style 661 or use the sctp_peeloff() (see Section 8.2) function to separate the 662 association of interest from the one-to-many socket. 664 3.4. Special considerations 666 The fact that a one-to-many style socket can provide access to many 667 SCTP associations through a single socket descriptor has important 668 implications for both application programmers and system programmers 669 implementing this API. A key issue is how buffer space inside the 670 sockets layer is managed. Because this implementation detail 671 directly affects how application programmers must write their code to 672 ensure correct operation and portability, this section provides some 673 guidance to both implementers and application programmers. 675 An important feature that SCTP shares with TCP is flow control. 676 Specifically, a sender may not send data faster than the receiver can 677 consume it. 679 For TCP, flow control is typically provided for in the sockets API as 680 follows. If the reader stops reading, the sender queues messages in 681 the socket layer until it uses all of its socket buffer space 682 allocation creating a "stalled connection". Further attempts to 683 write to the socket will block or return the error EAGAIN or 684 EWOULDBLOCK for a non-blocking socket. At some point, either the 685 connection is closed, or the receiver begins to read again freeing 686 space in the output queue. 688 For one-to-one style SCTP sockets (this includes sockets descriptors 689 that were separated from a one-to-many style socket with 690 sctp_peeloff()) the behavior is identical. For one-to-many style 691 SCTP sockets, the fact that we have multiple associations on a single 692 socket makes the situation more complicated. If the implementation 693 uses a single buffer space allocation shared by all associations, a 694 single stalled association can prevent the further sending of data on 695 all associations active on a particular one-to-many style socket. 697 For a blocking socket, it should be clear that a single stalled 698 association can block the entire socket. For this reason, 699 application programmers may want to use non-blocking one-to-many 700 style sockets. The application should at least be able to send 701 messages to the non-stalled associations. 703 But a non-blocking socket is not sufficient if the API implementer 704 has chosen a single shared buffer allocation for the socket. A 705 single stalled association would eventually cause the shared 706 allocation to fill, and it would become impossible to send even to 707 non-stalled associations. 709 The API implementer can solve this problem by providing each 710 association with its own allocation of outbound buffer space. Each 711 association should conceptually have as much buffer space as it would 712 have if it had its own socket. As a bonus, this simplifies the 713 implementation of sctp_peeloff(). 715 To ensure that a given stalled association will not prevent other 716 non-stalled associations from being writable, application programmers 717 should either: 718 o demand that the underlying implementation dedicates independent 719 buffer space allotments to each association (as suggested above), 720 or 721 o verify that their application layer protocol does not permit large 722 amounts of unread data at the receiver (this is true of some 723 request-response protocols, for example), or 724 o use one-to-one style sockets for association which may potentially 725 stall (either from the beginning, or by using sctp_peeloff before 726 sending large amounts of data that may cause a stalled condition). 728 4. One-to-One Style Interface 730 The goal of this style is to follow as closely as possible the 731 current practice of using the sockets interface for a connection 732 oriented protocol, such as TCP. This style enables existing 733 applications using connection oriented protocols to be ported to SCTP 734 with very little effort. 736 Note that some new SCTP features and some new SCTP socket options can 737 only be utilized through the use of sendmsg() and recvmsg() calls, 738 see Section 4.1.8. 740 4.1. Basic Operation 742 A typical server in one-to-one style uses the following system call 743 sequence to prepare an SCTP endpoint for servicing requests: 745 o socket() 746 o bind() 747 o listen() 748 o accept() 750 The accept() call blocks until a new association is set up. It 751 returns with a new socket descriptor. The server then uses the new 752 socket descriptor to communicate with the client, using recv() and 753 send() calls to get requests and send back responses. 755 Then it calls 756 o close() 757 to terminate the association. 759 A typical client uses the following system call sequence to setup an 760 association with a server to request services: 761 o socket() 762 o connect() 764 After returning from connect(), the client uses send()/sendmsg() and 765 recv()/recvmsg() calls to send out requests and receive responses 766 from the server. 768 The client calls 769 o close() 770 to terminate this association when done. 772 4.1.1. socket() 774 Applications call socket() to create a socket descriptor to represent 775 an SCTP endpoint. 777 The function prototype is 779 int socket(int domain, 780 int type, 781 int protocol); 783 and one uses PF_INET or PF_INET6 as the domain, SOCK_STREAM as the 784 type and IPPROTO_SCTP as the protocol. 786 Here, SOCK_STREAM indicates the creation of a one-to-one style 787 socket. 789 Using the PF_INET domain indicates the creation of an endpoint which 790 can use only IPv4 addresses, while PF_INET6 creates an endpoint which 791 can use both IPv6 and IPv4 addresses. 793 4.1.2. bind() 795 Applications use bind() to specify which local address and port the 796 SCTP endpoint should associate itself with. 798 An SCTP endpoint can be associated with multiple addresses. To do 799 this, sctp_bindx() is introduced in Section 8.1 to help applications 800 do the job of associating multiple addresses. But note that an 801 endpoint can only be associated with one local port. 803 These addresses associated with a socket are the eligible transport 804 addresses for the endpoint to send and receive data. The endpoint 805 will also present these addresses to its peers during the association 806 initialization process, see [RFC4960]. 808 The function prototype of bind() is 810 int bind(int sd, 811 struct sockaddr *addr, 812 socklen_t addrlen); 814 and the arguments are 815 sd: The socket descriptor returned by socket(). 816 addr: The address structure (struct sockaddr_in for an IPv4 address 817 or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). 818 addrlen: The size of the address structure. 820 If sd is an IPv4 socket, the address passed must be an IPv4 address. 821 If the sd is an IPv6 socket, the address passed can either be an IPv4 822 or an IPv6 address. 824 Applications cannot call bind() multiple times to associate multiple 825 addresses to the endpoint. After the first call to bind(), all 826 subsequent calls will return an error. 828 If the IP address part of addr is specified as a wildcard (INADDR_ANY 829 for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an 830 IPv6 address), the operating system will associate the endpoint with 831 an optimal address set of the available interfaces. If the IPv4 832 sin_port or IPv6 sin6_port is set to 0, the operating system will 833 choose an ephemeral port for the endpoint. 835 If a bind() is not called prior to the connect() call, the system 836 picks an ephemeral port and will choose an address set equivalent to 837 binding with a wildcard address. One of those addresses will be the 838 primary address for the association. This automatically enables the 839 multi-homing capability of SCTP. 841 The completion of this bind() process does not ready the SCTP 842 endpoint to accept inbound SCTP association requests. Until a 843 listen() system call, described below, is performed on the socket, 844 the SCTP endpoint will promptly reject an inbound SCTP INIT request 845 with an SCTP ABORT. 847 4.1.3. listen() 849 Applications use listen() to ready the SCTP endpoint for accepting 850 inbound associations. 852 The function prototype is 854 int listen(int sd, 855 int backlog); 857 and the arguments are 858 sd: the socket descriptor of the SCTP endpoint. 859 backlog: this specifies the max number of outstanding associations 860 allowed in the socket's accept queue. These are the associations 861 that have finished the four-way initiation handshake (see Section 862 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 863 of '0' indicates that the caller no longer wishes to receive new 864 associations. 866 4.1.4. accept() 868 Applications use the accept() call to remove an established SCTP 869 association from the accept queue of the endpoint. A new socket 870 descriptor will be returned from accept() to represent the newly 871 formed association. 873 The function prototype is 875 int accept(int sd, 876 struct sockaddr *addr, 877 socklen_t *addrlen); 879 and the arguments are 880 sd: The listening socket descriptor. 881 addr: On return, addr (struct sockaddr_in for an IPv4 address or 882 struct sockaddr_in6 for an IPv6 address, see [RFC3493]) will 883 contain the primary address of the peer endpoint. 884 addrlen: On return, addrlen will contain the size of addr. 885 The functions returns the socket descriptor for the newly formed 886 association. 888 4.1.5. connect() 890 Applications use connect() to initiate an association to a peer. 892 The function prototype is 894 int connect(int sd, 895 const struct sockaddr *addr, 896 socklen_t addrlen); 898 and the arguments are 899 sd: The socket descriptor of the endpoint. 900 addr: The peer's (struct sockaddr_in for an IPv4 address or struct 901 sockaddr_in6 for an IPv6 address, see [RFC3493]) address. 902 addrlen: The size of the address. 904 This operation corresponds to the ASSOCIATE primitive described in 905 section 10.1 of [RFC4960]. 907 The number of outbound streams the new association has is stack 908 dependent. Applications can use the SCTP_INITMSG option described in 909 Section 7.1.3 should be used before connecting to change the number 910 of outbound streams. 912 If a bind() is not called prior to the connect() call, the system 913 picks an ephemeral port and will choose an address set equivalent to 914 binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket 915 respectively. One of those addresses will be the primary address for 916 the association. This automatically enables the multi-homing 917 capability of SCTP. 919 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 920 during the association set up phase. If an application wants to do 921 this, it cannot use the connect() call. Instead, it should use 922 sendto() or sendmsg() to initiate an association. If it uses 923 sendto() and it wants to change the initialization behavior, it needs 924 to use the SCTP_INITMSG socket option before calling sendto(). Or it 925 can use sendmsg() with SCTP_INIT type ancillary data to initiate an 926 association without doing the setsockopt(). Note that the implicit 927 setup is supported for the one-to-many style sockets. 929 SCTP does not support half close semantics. This means that unlike 930 T/TCP, MSG_EOF should not be set in the flags parameter when calling 931 sendto() or sendmsg() when the call is used to initiate a connection. 932 MSG_EOF is not an acceptable flag with an SCTP socket. 934 4.1.6. close() 936 Applications use close() to gracefully close down an association. 938 The function prototype is 940 int close(int sd); 942 and the argument is 943 sd: The socket descriptor of the association to be closed. 945 After an application calls close() on a socket descriptor, no further 946 socket operations will succeed on that descriptor. 948 4.1.7. shutdown() 950 SCTP differs from TCP in that it does not have half closed semantics. 951 Hence the shutdown() call for SCTP is an approximation of the TCP 952 shutdown() call, and solves some different problems. Full TCP- 953 compatibility is not provided, so developers porting TCP applications 954 to SCTP may need to recode sections that use shutdown(). (Note that 955 it is possible to achieve the same results as half close in SCTP 956 using SCTP streams.) 958 The function prototype is 960 int shutdown(int sd, 961 int how); 963 and the arguments are 964 sd: The socket descriptor of the association to be closed. 965 how: Specifies the type of shutdown. The values are as follows: 966 SHUT_RD: Disables further receive operations. No SCTP protocol 967 action is taken. 968 SHUT_WR: Disables further send operations, and initiates the SCTP 969 shutdown sequence. 970 SHUT_RDWR: Disables further send and receive operations and 971 initiates the SCTP shutdown sequence. 973 The major difference between SCTP and TCP shutdown() is that SCTP 974 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 975 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 976 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 977 the SCTP association while still leaving the socket descriptor open. 978 This allows the caller to receive back any data which SCTP is unable 979 to deliver (see Section 5.3.5 for more information) and receive event 980 notifications. 982 To perform the ABORT operation described in [RFC4960] section 10.1, 983 an application can use the socket option SO_LINGER. It is described 984 in Section 7.1.4. 986 4.1.8. sendmsg() and recvmsg() 988 With a one-to-one style socket, the application can also use 989 sendmsg() and recvmsg() to transmit data to and receive data from its 990 peer. The semantics is similar to those used in the one-to-many 991 style (section Section 3.1.3), with the following differences: 992 1. When sending, the msg_name field in the msghdr is not used to 993 specify the intended receiver, rather it is used to indicate a 994 preferred peer address if the sender wishes to discourage the 995 stack from sending the message to the primary address of the 996 receiver. If the socket is connected and the transport address 997 given is not part of the current association, the data will not 998 be sent and an SCTP_SEND_FAILED event will be delivered to the 999 application if send failure events are enabled. 1000 2. Using sendmsg() on a non-connected one-to-one style socket for 1001 implicit connection setup may or may not work depending on the 1002 SCTP implementation. 1004 4.1.9. getpeername() 1006 Applications use getpeername() to retrieve the primary socket address 1007 of the peer. This call is for TCP compatibility, and is not multi- 1008 homed. It does not work with one-to-many style sockets. See 1009 Section 8.3 for a multi-homed/one-to-many style version of the call. 1011 The function prototype is 1013 int getpeername(int sd, 1014 struct sockaddr *address, 1015 socklen_t *len); 1017 and the arguments are: 1018 sd: The socket descriptor to be queried. 1019 address: On return, the peer primary address is stored in this 1020 buffer. If the socket is an IPv4 socket, the address will be 1021 IPv4. If the socket is an IPv6 socket, the address will be either 1022 an IPv6 or IPv4 address. 1023 len: The caller should set the length of address here. On return, 1024 this is set to the length of the returned address. 1026 If the actual length of the address is greater than the length of the 1027 supplied sockaddr structure, the stored address will be truncated. 1029 5. Data Structures 1031 In this section we discuss important data structures which are 1032 specific to SCTP and are used with sendmsg() and recvmsg() calls to 1033 control SCTP endpoint operations and to access ancillary information 1034 and notifications. 1036 5.1. The msghdr and cmsghdr Structures 1038 The msghdr structure used in the sendmsg() and recvmsg() calls, as 1039 well as the ancillary data carried in the structure, is the key for 1040 the application to set and get various control information from the 1041 SCTP endpoint. 1043 The msghdr and the related cmsghdr structures are defined and 1044 discussed in detail in [RFC3542]. Here we will cite their 1045 definitions from [RFC3542]. 1047 The msghdr structure: 1049 struct msghdr { 1050 void *msg_name; /* ptr to socket address structure */ 1051 socklen_t msg_namelen; /* size of socket address structure */ 1052 struct iovec *msg_iov; /* scatter/gather array */ 1053 size_t msg_iovlen; /* # elements in msg_iov */ 1054 void *msg_control; /* ancillary data */ 1055 socklen_t msg_controllen; /* ancillary data buffer length */ 1056 int msg_flags; /* flags on received message */ 1057 }; 1059 and the cmsghdr structure: 1061 struct cmsghdr { 1062 socklen_t cmsg_len; /* #bytes, including this header */ 1063 int cmsg_level; /* originating protocol */ 1064 int cmsg_type; /* protocol-specific type */ 1065 /* followed by unsigned char cmsg_data[]; */ 1066 }; 1068 In the msghdr structure, the usage of msg_name has been discussed in 1069 previous sections (see Section 3.1.3 and Section 4.1.8). 1071 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1072 field) are treated as a single SCTP data chunk, rather than multiple 1073 chunks, for both sendmsg() and recvmsg(). 1075 The msg_flags are not used when sending a message with sendmsg(). 1077 If a notification has arrived, recvmsg() will return the notification 1078 with the MSG_NOTIFICATION flag set in msg_flags. If the 1079 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1080 Section 5.3 for more information about notifications. 1082 If all portions of a data frame or notification have been read, 1083 recvmsg() will return with MSG_EOR set in msg_flags. 1085 5.2. SCTP msg_control Structures 1087 A key element of all SCTP specific socket extensions is the use of 1088 ancillary data to specify and access SCTP specific data via the 1089 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1090 Fine-grained control over initialization and sending parameters are 1091 handled with ancillary data. 1093 Each ancillary data item is proceeded by a struct cmsghdr (see 1094 Section 5.1), which defines the function and purpose of the data 1095 contained in the cmsg_data[] member. 1097 By default on either style socket, SCTP will pass no ancillary data; 1098 Specific ancillary data items can be enabled with socket options 1099 defined for SCTP; see Section 7.4. 1101 Note that all ancillary types are fixed length; see Section 5.4 for 1102 further discussion on this. These data structures use struct 1103 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1104 address format. 1106 Other protocols may also provide ancillary data to the socket layer 1107 consumer. These ancillary data items from other protocols may 1108 intermingle with SCTP data. For example, the IPv6 socket API 1109 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1110 data items. If a socket API consumer enables delivery of both SCTP 1111 and IPv6 ancillary data, they both may appear in the same msg_control 1112 buffer in any order. An application may thus need to handle other 1113 types of ancillary data besides those passed by SCTP. 1115 The sockets application must provide a buffer large enough to 1116 accommodate all ancillary data provided via recvmsg(). If the buffer 1117 is not large enough, the ancillary data will be truncated and the 1118 msghdr's msg_flags will include MSG_CTRUNC. 1120 5.2.1. SCTP Initiation Structure (SCTP_INIT) 1122 This cmsghdr structure provides information for initializing new SCTP 1123 associations with sendmsg(). The SCTP_INITMSG socket option uses 1124 this same data structure. This structure is not used for recvmsg(). 1126 +--------------+-----------+---------------------+ 1127 | cmsg_level | cmsg_type | cmsg_data[] | 1128 +--------------+-----------+---------------------+ 1129 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1130 +--------------+-----------+---------------------+ 1132 Here is the definition of the sctp_initmsg structure: 1134 struct sctp_initmsg { 1135 uint16_t sinit_num_ostreams; 1136 uint16_t sinit_max_instreams; 1137 uint16_t sinit_max_attempts; 1138 uint16_t sinit_max_init_timeo; 1139 }; 1141 sinit_num_ostreams: This is an integer number representing the 1142 number of streams that the application wishes to be able to send 1143 to. This number is confirmed in the SCTP_COMM_UP notification and 1144 must be verified since it is a negotiated number with the remote 1145 endpoint. The default value of 0 indicates to use the endpoint 1146 default value. 1147 sinit_max_instreams: This value represents the maximum number of 1148 inbound streams the application is prepared to support. This 1149 value is bounded by the actual implementation. In other words the 1150 user may be able to support more streams than the Operating 1151 System. In such a case, the Operating System limit overrides the 1152 value requested by the user. The default value of 0 indicates to 1153 use the endpoints default value. 1154 sinit_max_attempts: This integer specifies how many attempts the 1155 SCTP endpoint should make at resending the INIT. This value 1156 overrides the system SCTP 'Max.Init.Retransmits' value. The 1157 default value of 0 indicates to use the endpoints default value. 1158 This is normally set to the system's default 'Max.Init.Retransmit' 1159 value. 1160 sinit_max_init_timeo: This value represents the largest Time-Out or 1161 RTO value (in milliseconds) to use in attempting an INIT. 1162 Normally the 'RTO.Max' is used to limit the doubling of the RTO 1163 upon timeout. For the INIT message this value may override 1164 'RTO.Max'. This value must not influence 'RTO.Max' during data 1165 transmission and is only used to bound the initial setup time. A 1166 default value of 0 indicates to use the endpoints default value. 1167 This is normally set to the system's 'RTO.Max' value (60 seconds). 1169 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1171 This cmsghdr structure specifies SCTP options for sendmsg() and 1172 describes SCTP header information about a received message through 1173 recvmsg(). This structure mixes the send and receive path. 1175 SCTP_SNDINFO described in Section 5.2.4 and SCTP_RCVINFO described in 1176 Section 5.2.5 split this information. These structures should be 1177 used, when possible, since SCTP_SNDRCV might be deprecated in the 1178 future. 1180 +--------------+-------------+------------------------+ 1181 | cmsg_level | cmsg_type | cmsg_data[] | 1182 +--------------+-------------+------------------------+ 1183 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1184 +--------------+-------------+------------------------+ 1186 Here is the definition of sctp_sndrcvinfo: 1188 struct sctp_sndrcvinfo { 1189 uint16_t sinfo_stream; 1190 uint16_t sinfo_ssn; 1191 uint16_t sinfo_flags; 1192 uint32_t sinfo_ppid; 1193 uint32_t sinfo_context; 1194 uint32_t sinfo_pr_value; 1195 uint32_t sinfo_tsn; 1196 uint32_t sinfo_cumtsn; 1197 sctp_assoc_t sinfo_assoc_id; 1198 }; 1200 sinfo_stream: For recvmsg() the SCTP stack places the message's 1201 stream number in this value. For sendmsg() this value holds the 1202 stream number that the application wishes to send this message to. 1203 If a sender specifies an invalid stream number an error indication 1204 is returned and the call fails. 1205 sinfo_ssn: For recvmsg() this value contains the stream sequence 1206 number that the remote endpoint placed in the DATA chunk. For 1207 fragmented messages this is the same number for all deliveries of 1208 the message (if more than one recvmsg() is needed to read the 1209 message). The sendmsg() call will ignore this parameter. 1210 sinfo_flags: This field may contain any of the following flags and 1211 is composed of a bitwise OR of these values. 1212 recvmsg() flags: 1213 SCTP_UNORDERED: This flag is present when the message was sent 1214 non-ordered. 1215 sendmsg() flags: 1216 SCTP_UNORDERED: This flag requests the un-ordered delivery of 1217 the message. If this flag is clear the datagram is 1218 considered an ordered send. 1220 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests 1221 the SCTP stack to override the primary destination address 1222 with the address found with the sendto/sendmsg call. 1223 SCTP_ABORT: Setting this flag causes the specified association 1224 to abort by sending an ABORT message to the peer (one-to- 1225 many style only). The ABORT chunk will contain an error 1226 cause 'User Initiated Abort' with cause code 12. The cause 1227 specific information of this error cause is provided in 1228 msg_iov. 1229 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1230 procedure on the specified association. Graceful shutdown 1231 assures that all data queued by both endpoints is 1232 successfully transmitted before closing the association 1233 (one-to-many style only). 1234 SCTP_SENDALL: This flag, if set, will cause a one-to-many 1235 model socket to send the message to all associations that 1236 are currently established on this socket. For the one-to- 1237 one socket, this flag has no effect. 1238 sinfo_ppid: This value in sendmsg() is an unsigned integer that is 1239 passed to the remote end in each user message. In recvmsg() this 1240 value is the same information that was passed by the upper layer 1241 in the peer application. Please note that the SCTP stack performs 1242 no byte order modification of this field. For example, if the 1243 DATA chunk has to contain a given value in network byte order, the 1244 SCTP user has to perform the htonl() computation. 1245 sinfo_context: This value is an opaque 32 bit context datum that is 1246 used in the sendmsg() function. This value is passed back to the 1247 upper layer if an error occurs on the send of a message and is 1248 retrieved with each undelivered message (Note: if an endpoint has 1249 done multiple sends, all of which fail, multiple different 1250 sinfo_context values will be returned. One with each user data 1251 message). 1252 sinfo_pr_value: The meaning of this field depends on the PR-SCTP 1253 policy specified by the sinfo_pr_policy field. It is ignored when 1254 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1255 lifetime is specified. 1256 sinfo_tsn: For the receiving side, this field holds a TSN that was 1257 assigned to one of the SCTP Data Chunks. 1258 sinfo_cumtsn: This field will hold the current cumulative TSN as 1259 known by the underlying SCTP layer. Note this field is ignored 1260 when sending. 1261 sinfo_assoc_id: The association handle field, sinfo_assoc_id, holds 1262 the identifier for the association announced in the SCTP_COMM_UP 1263 notification. All notifications for a given association have the 1264 same identifier. Ignored for one-to-one style sockets. 1266 An sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1268 5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1270 This cmsghdr structure specifies SCTP options for SCTP header 1271 information about a received message via recvmsg(). Note that this 1272 structure is an extended version of SCTP_SNDRCV (see Section 5.2.2) 1273 and will only be received if the user has set the socket option 1274 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1275 needed to receive ancillary data. See Section 7.1.22 on this socket 1276 option. Note that next message data is not valid unless the current 1277 message is completely read, i.e. the MSG_EOR is set, in other words 1278 if the application has more data to read from the current message 1279 then no next message information will be available. 1281 SCTP_NXTINFO described in Section 5.2.6 should be used when possible, 1282 since SCTP_EXTRCV is considered deprecated. 1284 +--------------+-------------+------------------------+ 1285 | cmsg_level | cmsg_type | cmsg_data[] | 1286 +--------------+-------------+------------------------+ 1287 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1288 +--------------+-------------+------------------------+ 1290 Here is the definition of sctp_extrcvinfo structure: 1292 struct sctp_extrcvinfo { 1293 uint16_t sinfo_stream; 1294 uint16_t sinfo_ssn; 1295 uint16_t sinfo_flags; 1296 uint32_t sinfo_ppid; 1297 uint32_t sinfo_context; 1298 uint32_t sinfo_pr_value; 1299 uint32_t sinfo_tsn; 1300 uint32_t sinfo_cumtsn; 1301 uint16_t serinfo_next_flags; 1302 uint16_t serinfo_next_stream; 1303 uint32_t serinfo_next_aid; 1304 uint32_t serinfo_next_length; 1305 uint32_t serinfo_next_ppid; 1306 sctp_assoc_t sinfo_assoc_id; 1307 }; 1309 sinfo_*: Please see Section 5.2.2 for the details for these fields. 1310 serinfo_next_flags: This bitmask will hold one or more of the 1311 following values: 1313 SCTP_NEXT_MSG_AVAIL: This bit, when set to 1, indicates that next 1314 message information is available i.e.: next_stream, 1315 next_asocid, next_length and next_ppid fields all have valid 1316 values. If this bit is set to 0, then these fields are not 1317 valid and should be ignored. 1318 SCTP_NEXT_MSG_ISCOMPLETE: This bit, when set, indicates that the 1319 next message is completely in the receive buffer. The 1320 next_length field thus contains the entire message size. If 1321 this flag is set to 0, then the next_length field only contains 1322 part of the message size since the message is still being 1323 received (it is being partially delivered). 1324 SCTP_NEXT_MSG_IS_UNORDERED: This bit, when set, indicates that 1325 the next message to be received was sent by the peer as 1326 unordered. If this bit is not set (i.e the bit is 0) the next 1327 message to be read is an ordered message in the stream 1328 specified. 1329 SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that 1330 the next message to be received is not a message from the peer, 1331 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1332 serinfo_next_stream: This value, when valid (see 1333 serinfo_next_flags), contains the next stream number that will be 1334 received on a subsequent call to one of the receive message 1335 functions. 1336 serinfo_next_aid: This value, when valid (see serinfo_next_flags), 1337 contains the next association identification that will be received 1338 on a subsequent call to one of the receive message functions. 1339 serinfo_next_length: This value, when valid (see 1340 serinfo_next_flags), contains the length of the next message that 1341 will be received on a subsequent call to one of the receive 1342 message functions. Note that this length may be a partial length 1343 depending on the settings of next_flags. 1344 serinfo_next_ppid: This value, when valid (see serinfo_next_flags), 1345 contains the ppid of the next message that will be received on a 1346 subsequent call to one of the receive message functions. 1348 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) 1350 This cmsghdr structure specifies SCTP options for sendmsg(). 1352 +--------------+--------------+---------------------+ 1353 | cmsg_level | cmsg_type | cmsg_data[] | 1354 +--------------+--------------+---------------------+ 1355 | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | 1356 +--------------+--------------+---------------------+ 1358 Here is the definition of the sctp_sndinfo structure: 1360 struct sctp_sndinfo { 1361 uint16_t snd_sid; 1362 uint16_t snd_flags; 1363 uint32_t snd_ppid; 1364 uint32_t snd_context; 1365 sctp_assoc_t snd_assoc_id; 1366 }; 1368 snd_sid: This value holds the stream number that the application 1369 wishes to send this message to. If a sender specifies an invalid 1370 stream number an error indication is returned and the call fails. 1371 snd_flags: This field may contain any of the following flags and is 1372 composed of a bitwise OR of these values. 1374 SCTP_UNORDERED: This flag requests the un-ordered delivery of the 1375 message. If this flag is clear the datagram is considered an 1376 ordered send. 1377 SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the 1378 SCTP stack to override the primary destination address with the 1379 address found with the sendto/sendmsg call. 1380 SCTP_ABORT: Setting this flag causes the specified association to 1381 abort by sending an ABORT message to the peer (one-to-many 1382 style only). The ABORT chunk will contain an error cause 'User 1383 Initiated Abort' with cause code 12. The cause specific 1384 information of this error cause is provided in msg_iov. 1385 SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown 1386 procedures on the specified association. Graceful shutdown 1387 assures that all data queued by both endpoints is successfully 1388 transmitted before closing the association (one-to-many style 1389 only). 1390 SCTP_SENDALL: This flag, if set, will cause a one-to-many model 1391 socket to send the message to all associations that are 1392 currently established on this socket. For the one-to-one 1393 socket, this flag has no effect. 1394 snd_ppid: This value in sendmsg() is an unsigned integer that is 1395 passed to the remote end in each user message. Please note that 1396 the SCTP stack performs no byte order modification of this field. 1397 For example, if the DATA chunk has to contain a given value in 1398 network byte order, the SCTP user has to perform the htonl() 1399 computation. 1400 snd_context: This value is an opaque 32 bit context datum that is 1401 used in the sendmsg() function. This value is passed back to the 1402 upper layer if an error occurs on the send of a message and is 1403 retrieved with each undelivered message (Note: if an endpoint has 1404 done multiple sends, all of which fail, multiple different 1405 sinfo_context values will be returned. One with each user data 1406 message). 1408 snd_assoc_id: The association handle field, sinfo_assoc_id, holds 1409 the identifier for the association announced in the SCTP_COMM_UP 1410 notification. All notifications for a given association have the 1411 same identifier. Ignored for one-to-one style sockets. 1413 An sctp_sndinfo item always corresponds to the data in msg_iov. 1415 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) 1417 This cmsghdr structure describes SCTP header information about a 1418 received message through recvmsg(). 1420 To receive this information an application must subscribe to the 1421 SCTP_RCV_EVENT using the SCTP_EVENT option (see Section 5.4. 1423 +--------------+--------------+---------------------+ 1424 | cmsg_level | cmsg_type | cmsg_data[] | 1425 +--------------+--------------+---------------------+ 1426 | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | 1427 +--------------+--------------+---------------------+ 1429 Here is the definition of the sctp_rcvinfo structure: 1431 struct sctp_rcvinfo { 1432 uint16_t rcv_sid; 1433 uint16_t rcv_ssn; 1434 uint16_t rcv_flags; 1435 uint32_t rcv_ppid; 1436 uint32_t rcv_tsn; 1437 uint32_t rcv_cumtsn; 1438 sctp_assoc_t rcv_assoc_id; 1439 }; 1441 rcv_sid: The SCTP stack places the message's stream number in this 1442 value. 1443 rcv_ssn: This value contains the stream sequence number that the 1444 remote endpoint placed in the DATA chunk. For fragmented messages 1445 this is the same number for all deliveries of the message (if more 1446 than one recvmsg() is needed to read the message). 1447 rcv_flags: This field may contain any of the following flags and is 1448 composed of a bitwise OR of these values. 1450 SCTP_UNORDERED: This flag is present when the message was sent 1451 non-ordered. 1453 rcv_ppid: This value is the same information that was passed by the 1454 upper layer in the peer application. Please note that the SCTP 1455 stack performs no byte order modification of this field. For 1456 example, if the DATA chunk has to contain a given value in network 1457 byte order, the SCTP user has to perform the htonl() computation. 1458 rcv_tsn: This field holds a TSN that was assigned to one of the SCTP 1459 Data Chunks. 1460 rcv_cumtsn: This field will hold the current cumulative TSN as known 1461 by the underlying SCTP layer. 1462 rcv_assoc_id: The association handle field, sinfo_assoc_id, holds 1463 the identifier for the association announced in the SCTP_COMM_UP 1464 notification. All notifications for a given association have the 1465 same identifier. Ignored for one-to-one style sockets. 1467 A sctp_rcvinfo item always corresponds to the data in msg_iov. 1469 5.2.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 1471 This cmsghdr structure describes SCTP receive information of the next 1472 message which will be delivered through recvmsg() if this information 1473 is available. It uses the same structure as the SCTP Receive 1474 Information Structure. 1476 To receive this information an application must subscribe to the 1477 SCTP_NXT_EVENT using the SCTP_EVENT option (see Section 5.4). 1479 +--------------+--------------+---------------------+ 1480 | cmsg_level | cmsg_type | cmsg_data[] | 1481 +--------------+--------------+---------------------+ 1482 | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_rcvinfo | 1483 +--------------+--------------+---------------------+ 1485 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 1487 This cmsghdr structure specifies SCTP options for sendmsg(). 1489 +--------------+-------------+--------------------+ 1490 | cmsg_level | cmsg_type | cmsg_data[] | 1491 +--------------+-------------+--------------------+ 1492 | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | 1493 +--------------+-------------+--------------------+ 1495 Here is the definition of the sctp_prinfo structure: 1497 struct sctp_prinfo { 1498 uint16_t pr_policy; 1499 uint32_t pr_value; 1500 }; 1501 pr_policy: This specifies which PR-SCTP policy is used. Using 1502 SCTP_PR_SCTP_NONE results in a reliable transmission. When 1503 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" 1504 defined in [RFC3758] is used. In this case, the lifetime is 1505 provided in pr_value. 1506 pr_value: The meaning of this field depends on the PR-SCTP policy 1507 specified by the sinfo_pr_policy field. It is ignored when 1508 SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the 1509 lifetime in milliseconds is specified. 1511 An sctp_prinfo item always corresponds to the data in msg_iov. 1513 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 1515 This cmsghdr structure specifies SCTP options for sendmsg(). 1517 +--------------+---------------+----------------------+ 1518 | cmsg_level | cmsg_type | cmsg_data[] | 1519 +--------------+---------------+----------------------+ 1520 | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | 1521 +--------------+---------------+----------------------+ 1523 Here is the definition of the sctp_authinfo structure: 1525 struct sctp_authinfo { 1526 uint16_t auth_keyid; 1527 }; 1529 auth_keyid: This specifies the shared key identifier used for 1530 sending the user message. 1532 An sctp_authinfo item always corresponds to the data in msg_iov. 1533 Please note that the SCTP implementation must not bundle user 1534 messages which should be authenticated using different shared key 1535 identifiers. 1537 5.3. SCTP Events and Notifications 1539 An SCTP application may need to understand and process events and 1540 errors that happen on the SCTP stack. These events include network 1541 status changes, association startups, remote operational errors and 1542 undeliverable messages. All of these can be essential for the 1543 application. 1545 When an SCTP application layer does a recvmsg() the message read is 1546 normally a data message from a peer endpoint. If the application 1547 wishes to have the SCTP stack deliver notifications of non-data 1548 events, it sets the appropriate socket option for the notifications 1549 it wants. See Section 7.4 for these socket options. When a 1550 notification arrives, recvmsg() returns the notification in the 1551 application-supplied data buffer via msg_iov, and sets 1552 MSG_NOTIFICATION in msg_flags. 1554 This section details the notification structures. Every notification 1555 structure carries some common fields which provide general 1556 information. 1558 A recvmsg() call will return only one notification at a time. Just 1559 as when reading normal data, it may return part of a notification if 1560 the msg_iov buffer is not large enough. If a single read is not 1561 sufficient, msg_flags will have MSG_EOR clear. The user must finish 1562 reading the notification before subsequent data can arrive. 1564 5.3.1. SCTP Notification Structure 1566 The notification structure is defined as the union of all 1567 notification types. 1569 union sctp_notification { 1570 struct sctp_tlv { 1571 uint16_t sn_type; /* Notification type. */ 1572 uint16_t sn_flags; 1573 uint32_t sn_length; 1574 } sn_header; 1575 struct sctp_assoc_change sn_assoc_change; 1576 struct sctp_paddr_change sn_paddr_change; 1577 struct sctp_remote_error sn_remote_error; 1578 struct sctp_send_failed sn_send_failed; 1579 struct sctp_shutdown_event sn_shutdown_event; 1580 struct sctp_adaptation_event sn_adaptation_event; 1581 struct sctp_pdapi_event sn_pdapi_event; 1582 struct sctp_authkey_event sn_auth_event; 1583 struct sctp_sender_dry_event sn_sender_dry_event; 1584 }; 1586 sn_type: The following list describes the SCTP notification and 1587 event types for the field sn_type. 1588 SCTP_ASSOC_CHANGE: This tag indicates that an association has 1589 either been opened or closed. Refer to Section 5.3.2 for 1590 details. 1591 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1592 part of an existing association has experienced a change of 1593 state (e.g. a failure or return to service of the reachability 1594 of an endpoint via a specific transport address). Please see 1595 Section 5.3.3 for data structure details. 1597 SCTP_REMOTE_ERROR: The attached error message is an Operational 1598 Error received from the remote peer. It includes the complete 1599 TLV sent by the remote endpoint. See Section 5.3.4 for the 1600 detailed format. 1601 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1602 remote endpoint. This structure includes the original 1603 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1604 structure uses the sctp_sndrcvinfo per Section 5.3.5. 1605 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further 1606 data should be sent on this socket. 1607 SCTP_ADAPTATION_INDICATION: This notification holds the peer's 1608 indicated adaptation layer. Please see Section 5.3.7. 1609 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1610 receiver that the partial delivery has been aborted. This may 1611 indicate the association is about to be aborted. Please see 1612 Section 5.3.8. 1613 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1614 receiver that either an error occurred on authentication, or a 1615 new key was made active. See Section 5.3.9. 1616 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1617 application that the sender has no user data queued anymore, 1618 neither for transmission nor retransmission. See 1619 Section 5.3.10. 1620 sn_flags: These are notification-specific flags. 1621 sn_length: This is the length of the whole sctp_notification 1622 structure including the sn_type, sn_flags, and sn_length fields. 1624 5.3.2. SCTP_ASSOC_CHANGE 1626 Communication notifications inform the ULP that an SCTP association 1627 has either begun or ended. The identifier for a new association is 1628 provided by this notification. The notification information has the 1629 following format: 1631 struct sctp_assoc_change { 1632 uint16_t sac_type; 1633 uint16_t sac_flags; 1634 uint32_t sac_length; 1635 uint16_t sac_state; 1636 uint16_t sac_error; 1637 uint16_t sac_outbound_streams; 1638 uint16_t sac_inbound_streams; 1639 sctp_assoc_t sac_assoc_id; 1640 uint8_t sac_info[]; 1641 }; 1642 sac_type: It should be SCTP_ASSOC_CHANGE. 1643 sac_flags: Currently unused. 1644 sac_length: This field is the total length of the notification data, 1645 including the notification header. 1646 sac_state: This field holds one of a number of values that 1647 communicate the event that happened to the association. They 1648 include: 1649 SCTP_COMM_UP: A new association is now ready and data may be 1650 exchanged with this peer. When an association has been 1651 established successfully, this notification should be the first 1652 one. 1653 SCTP_COMM_LOST: The association has failed. The association is 1654 now in the closed state. If SEND FAILED notifications are 1655 turned on, a SCTP_COMM_LOST is accompanied by a series of 1656 SCTP_SEND_FAILED events, one for each outstanding message. 1657 SCTP_RESTART: SCTP has detected that the peer has restarted. 1658 SCTP_SHUTDOWN_COMP: The association has gracefully closed. 1659 SCTP_CANT_STR_ASSOC: The association failed to setup. If non 1660 blocking mode is set and data was sent (on a one-to-many style 1661 socket), a SCTP_CANT_STR_ASSOC is accompanied by a series of 1662 SCTP_SEND_FAILED events, one for each outstanding message. 1663 sac_error: If the state was reached due to an error condition (e.g. 1664 SCTP_COMM_LOST) any relevant error information is available in 1665 this field. This corresponds to the protocol error codes defined 1666 in [RFC4960]. 1667 sac_outbound_streams: 1668 sac_inbound_streams: The maximum number of streams allowed in each 1669 direction are available in sac_outbound_streams and sac_inbound 1670 streams. 1671 sac_assoc_id: The association id field holds the identifier for the 1672 association. All notifications for a given association have the 1673 same association identifier. For a one-to-one style socket, this 1674 field is ignored. 1675 sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was 1676 received for this association, sac_info[] contains the complete 1677 ABORT chunk as defined in the SCTP specification [RFC4960] section 1678 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 1679 may contain an array of features that the current association 1680 supports. Features may include 1681 SCTP_PR: Both endpoints support the protocol extension described 1682 in [RFC3758]. 1683 SCTP_AUTH: Both endpoints support the protocol extension 1684 described in [RFC4895]. 1685 SCTP_ASCONF: Both endpoints support the protocol extension 1686 described in [RFC5061]. 1688 SCTP_MULTIBUF: For a one-to-many style socket, the local 1689 endpoints use separate send and/or receive buffers for each 1690 SCTP association. 1692 5.3.3. SCTP_PEER_ADDR_CHANGE 1694 When a destination address of a multi-homed peer encounters a state 1695 change a peer address change event is sent. The notification has the 1696 following format: 1698 struct sctp_paddr_change { 1699 uint16_t spc_type; 1700 uint16_t spc_flags; 1701 uint32_t spc_length; 1702 struct sockaddr_storage spc_aaddr; 1703 uint32_t spc_state; 1704 uint32_t spc_error; 1705 sctp_assoc_t spc_assoc_id; 1706 } 1708 spc_type: It should be SCTP_PEER_ADDR_CHANGE. 1709 spc_flags: Currently unused. 1710 spc_length: This field is the total length of the notification data, 1711 including the notification header. 1712 spc_aaddr: The affected address field holds the remote peer's 1713 address that is encountering the change of state. 1714 spc_state: This field holds one of a number of values that 1715 communicate the event that happened to the address. They include: 1716 SCTP_ADDR_AVAILABLE: This address is now reachable. 1717 SCTP_ADDR_UNREACHABLE: The address specified can no longer be 1718 reached. Any data sent to this address is rerouted to an 1719 alternate until this address becomes reachable. 1720 SCTP_ADDR_REMOVED: The address is no longer part of the 1721 association. 1722 SCTP_ADDR_ADDED: The address is now part of the association. 1723 SCTP_ADDR_MADE_PRIM: This address has now been made to be the 1724 primary destination address. 1725 SCTP_ADDR_CONFIRMED: This address has now been confirmed as a 1726 valid address. 1727 spc_error: If the state was reached due to any error condition (e.g. 1728 SCTP_ADDR_UNREACHABLE) any relevant error information is available 1729 in this field. 1730 spc_assoc_id: The association id field holds the identifier for the 1731 association. All notifications for a given association have the 1732 same association identifier. For a one-to-one style socket, this 1733 field is ignored. 1735 5.3.4. SCTP_REMOTE_ERROR 1737 A remote peer may send an Operational Error message to its peer. 1738 This message indicates a variety of error conditions on an 1739 association. The entire ERROR chunk as it appears on the wire is 1740 included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP 1741 specification [RFC4960] and any extensions for a list of possible 1742 error formats. An SCTP error notification has the following format: 1744 struct sctp_remote_error { 1745 uint16_t sre_type; 1746 uint16_t sre_flags; 1747 uint32_t sre_length; 1748 uint16_t sre_error; 1749 sctp_assoc_t sre_assoc_id; 1750 uint8_t sre_data[]; 1751 }; 1753 sre_type: It should be SCTP_REMOTE_ERROR. 1754 sre_flags: Currently unused. 1755 sre_length: This field is the total length of the notification data, 1756 including the notification header and the contents of sre_data. 1757 sre_error: This value represents one of the Operational Error causes 1758 defined in the SCTP specification, in network byte order. 1759 sre_assoc_id: The association id field holds the identifier for the 1760 association. All notifications for a given association have the 1761 same association identifier. For a one-to-one style socket, this 1762 field is ignored. 1763 sre_data: This contains the ERROR chunk as defined in the SCTP 1764 specification [RFC4960] section 3.3.10. 1766 5.3.5. SCTP_SEND_FAILED 1768 If SCTP cannot deliver a message, it can return back the message as a 1769 notification if the SCTP_SEND_FAILED event is enabled. The 1770 notification has the following format: 1772 struct sctp_send_failed { 1773 uint16_t ssf_type; 1774 uint16_t ssf_flags; 1775 uint32_t ssf_length; 1776 uint32_t ssf_error; 1777 struct sctp_sndrcvinfo ssf_info; 1778 sctp_assoc_t ssf_assoc_id; 1779 uint8_t ssf_data[]; 1780 }; 1781 ssf_type: It should be SCTP_SEND_FAILED. 1782 ssf_flags: The flag value will take one of the following values: 1783 SCTP_DATA_UNSENT: Indicates that the data was never put on the 1784 wire. 1785 SCTP_DATA_SENT: Indicates that the data was put on the wire. 1786 Note that this does not necessarily mean that the data was (or 1787 was not) successfully delivered. 1788 ssf_length: This field is the total length of the notification data, 1789 including the notification header and the payload in ssf_data. 1790 ssf_error: This value represents the reason why the send failed, and 1791 if set, will be an SCTP protocol error code as defined in 1792 [RFC4960] section 3.3.10. 1793 ssf_info: The send information associated with the undelivered 1794 message. The ssf_info.sinfo_flags field will also contain an 1795 indication if the beginning of the message and/or end of the 1796 message is present. In cases where no data has been sent on the 1797 wire, this field will have or'ed in the value SCTP_DATA_NOT_FRAG, 1798 which is a composition of both a "BEGIN" and "END" fragmentation 1799 bit. In cases where only part of the data has been sent, this 1800 field will have or'ed in the value SCTP_DATA_LAST_FRAG, which 1801 corresponds to the "END" bit. Note that the message itself may be 1802 more than one chunk. If the ssf_info.sinfo_flags field holds 1803 neither of these two values then a piece that has been fragmented 1804 and sent but not acknowledged is present. This piece is from an 1805 unspecified position in the message and the application can make 1806 no assumptions about the data itself. Applications wanting to 1807 examine a recovered message should look for the 1808 SCTP_DATA_NOT_FRAG. Without this flag the application should 1809 assume part of the message arrived and take appropriate steps to 1810 audit and recover any lost or missing data. 1811 ssf_assoc_id: The association id field, ssf_assoc_id, holds the 1812 identifier for the association. All notifications for a given 1813 association have the same association identifier. For a one-to- 1814 one style socket, this field is ignored. 1815 ssf_data: The undelivered message or part of the undelivered message 1816 will be present in the ssf_data field. Note that the 1817 ssf_info.sinfo_flags field as noted above should be used to 1818 determine if a complete message is present or just a piece of the 1819 message. Note that only user data is present in this field, any 1820 chunk headers or SCTP common headers must be removed by the SCTP 1821 stack. 1823 5.3.6. SCTP_SHUTDOWN_EVENT 1825 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1826 inform the application that it should cease sending data. 1828 struct sctp_shutdown_event { 1829 uint16_t sse_type; 1830 uint16_t sse_flags; 1831 uint32_t sse_length; 1832 sctp_assoc_t sse_assoc_id; 1833 }; 1835 sse_type: It should be SCTP_SHUTDOWN_EVENT. 1836 sse_flags: Currently unused. 1837 sse_length: This field is the total length of the notification data, 1838 including the notification header. It will generally be sizeof 1839 (struct sctp_shutdown_event). 1840 sse_flags: Currently unused. 1841 sse_assoc_id: The association id field holds the identifier for the 1842 association. All notifications for a given association have the 1843 same association identifier. For a one-to-one style socket, this 1844 field is ignored. 1846 5.3.7. SCTP_ADAPTATION_INDICATION 1848 When a peer sends an Adaptation Layer Indication parameter as 1849 described in [RFC5061], SCTP delivers this notification to inform the 1850 application about the peer's adaptation layer indication. 1852 struct sctp_adaptation_event { 1853 uint16_t sai_type; 1854 uint16_t sai_flags; 1855 uint32_t sai_length; 1856 uint32_t sai_adaptation_ind; 1857 sctp_assoc_t sai_assoc_id; 1858 }; 1860 sai_type: It should be SCTP_ADAPTATION_INDICATION. 1861 sai_flags: Currently unused. 1862 sai_length: This field is the total length of the notification data, 1863 including the notification header. It will generally be sizeof 1864 (struct sctp_adaptation_event). 1865 sai_adaptation_ind: This field holds the bit array sent by the peer 1866 in the adaptation layer indication parameter. The bits are in 1867 network byte order. 1868 sai_assoc_id: The association id field holds the identifier for the 1869 association. All notifications for a given association have the 1870 same association identifier. For a one-to-one style socket, this 1871 field is ignored. 1873 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT 1875 When a receiver is engaged in a partial delivery of a message this 1876 notification will be used to indicate various events. 1878 struct sctp_pdapi_event { 1879 uint16_t pdapi_type; 1880 uint16_t pdapi_flags; 1881 uint32_t pdapi_length; 1882 uint32_t pdapi_indication; 1883 uint32_t pdapi_stream; 1884 uint32_t pdapi_seq; 1885 sctp_assoc_t pdapi_assoc_id; 1886 }; 1888 pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. 1889 pdapi_flags: Currently unused. 1890 pdapi_length: This field is the total length of the notification 1891 data, including the notification header. It will generally be 1892 sizeof(struct sctp_pdapi_event). 1893 pdapi_indication: This field holds the indication being sent to the 1894 application. Currently there is only one defined value: 1895 SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial 1896 delivery of a user message has been aborted. 1897 pdapi_stream: This field holds the stream on which the partial 1898 delivery event happened. 1899 pdapi_seq: This field holds the stream sequence number which was 1900 being partially delivered. 1901 pdapi_assoc_id: The association id field holds the identifier for 1902 the association. All notifications for a given association have 1903 the same association identifier. For a one-to-one style socket 1904 this field is ignored. 1906 5.3.9. SCTP_AUTHENTICATION_EVENT 1908 [RFC4895] defines an extension to authenticate SCTP messages. The 1909 following notification is used to report different events relating to 1910 the use of this extension. 1912 struct sctp_authkey_event { 1913 uint16_t auth_type; 1914 uint16_t auth_flags; 1915 uint32_t auth_length; 1916 uint16_t auth_keynumber; 1917 uint16_t auth_altkeynumber; 1918 uint32_t auth_indication; 1919 sctp_assoc_t auth_assoc_id; 1920 }; 1921 auth_type: It should be SCTP_AUTHENTICATION_EVENT. 1922 auth_flags: Currently unused. 1923 auth_length: This field is the total length of the notification 1924 data, including the notification header. It will generally be 1925 sizeof (struct sctp_authkey_event). 1926 auth_keynumber: This field holds the keynumber for the affected key 1927 indicated in the event (depends on auth_indication). If more than 1928 one key is involved, this will contain one of the keys involved in 1929 the notification. 1930 auth_altkeynumber: This field holds an alternate keynumber which is 1931 used by some notifications. 1932 auth_indication: This field holds the error or indication being 1933 reported. The following values are currently defined: 1934 SCTP_AUTH_NEWKEY: This report indicates that a new key has been 1935 made active (used for the first time by the peer) and is now 1936 the active key. The auth_keynumber field holds the user 1937 specified key number. 1938 SCTP_AUTH_NO_AUTH: This report indicates that the peer does not 1939 support SCTP AUTH as defined in [RFC4895]. 1940 SCTP_AUTH_FREE_KEY: This report indicates that the SCTP 1941 implementation will not use the key identifier specified in 1942 auth_keynumber anymore. 1943 auth_assoc_id: The association id field holds the identifier for the 1944 association. All notifications for a given association have the 1945 same association identifier. For a one-to-one style socket this 1946 field is ignored. 1948 5.3.10. SCTP_SENDER_DRY_EVENT 1950 When the SCTP implementation has no user data anymore to send or 1951 retransmit, this notification is given to the user. If the user 1952 subscribes to this event and SCTP has at this point of time no user 1953 data to send or retransmit, this notification is also given to the 1954 user. 1956 struct sctp_sender_dry_event { 1957 uint16_t sender_dry_type; 1958 uint16_t sender_dry_flags; 1959 uint32_t sender_dry_length; 1960 sctp_assoc_t sender_dry_assoc_id; 1961 }; 1963 sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. 1964 sender_dry_flags: Currently unused. 1966 sender_dry_length: This field is the total length of the 1967 notification data, including the notification header. It will 1968 generally be sizeof(struct sctp_sender_dry_event). 1970 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT 1972 Notifications, when subscribed to, are reliable. They are always 1973 delivered as long as there is space in the socket receive buffer. 1974 However, if an implementation experiences a notification storm, it 1975 may run out of socket buffer space. When this occurs it may wish to 1976 disable notifications. If the implementation chooses to do this, it 1977 will append a final notification SCTP_NOTIFICATIONS_STOPPED_EVENT. 1978 This notification is an union sctp_notification, where only the 1979 struct sctp_tlv (see the union above) is used. That merely has this 1980 type in the sn_type field, the sn_length field set to the sizeof an 1981 sctp_tlv structure and the sn_flags set to 0. If an application 1982 receives this notification, it will need to resubscribe to any 1983 notifications of interest to it, except for the data io event. 1985 An endpoint is automatically subscribed to this event as soon as it 1986 is subscribed to any event other than data io events. 1988 5.4. Ancillary Data Considerations and Semantics 1990 Programming with ancillary socket data contains some subtleties and 1991 pitfalls, which are discussed below. 1993 5.4.1. Multiple Items and Ordering 1995 Multiple ancillary data items may be included in any call to 1996 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1997 items, or both. 1999 The ordering of ancillary data items (either by SCTP or another 2000 protocol) is not significant and is implementation-dependent, so 2001 applications must not depend on any ordering. 2003 SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO type ancillary data always 2004 correspond to the data in the msghdr's msg_iov member. There can be 2005 only one single such type ancillary data for each sendmsg() or 2006 recvmsg() call. 2008 5.4.2. Accessing and Manipulating Ancillary Data 2010 Applications can infer the presence of data or ancillary data by 2011 examining the msg_iovlen and msg_controllen msghdr members, 2012 respectively. 2014 Implementations may have different padding requirements for ancillary 2015 data, so portable applications should make use of the macros 2016 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 2017 [RFC3542] and the SCTP implementation's documentation for more 2018 information. The following is an example, from [RFC3542], 2019 demonstrating the use of these macros to access ancillary data: 2021 struct msghdr msg; 2022 struct cmsghdr *cmsgptr; 2024 /* fill in msg */ 2026 /* call recvmsg() */ 2028 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 2029 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 2030 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 2031 u_char *ptr; 2033 ptr = CMSG_DATA(cmsgptr); 2034 /* process data pointed to by ptr */ 2035 } 2036 } 2038 5.4.3. Control Message Buffer Sizing 2040 The information conveyed via SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 2041 ancillary data will often be fundamental to the correct and sane 2042 operation of the sockets application. This is particularly true of 2043 the one-to-many semantics, but also of the one-to-one semantics. For 2044 example, if an application needs to send and receive data on 2045 different SCTP streams, SCTP_SNDRCV/SCTP_SNDINFO/SCTP_RCVINFO 2046 ancillary data is indispensable. 2048 Given that some ancillary data is critical, and that multiple 2049 ancillary data items may appear in any order, applications should be 2050 carefully written to always provide a large enough buffer to contain 2051 all possible ancillary data that can be presented by recvmsg(). If 2052 the buffer is too small, and crucial data is truncated, it may pose a 2053 fatal error condition. 2055 Thus, it is essential that applications be able to deterministically 2056 calculate the maximum required buffer size to pass to recvmsg(). One 2057 constraint imposed on this specification that makes this possible is 2058 that all ancillary data definitions are of a fixed length. One way 2059 to calculate the maximum required buffer size might be to take the 2060 sum the sizes of all enabled ancillary data item structures, as 2061 calculated by CMSG_SPACE. For example, if we enabled 2062 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 2063 and allocate the buffer size as follows: 2065 size_t total; 2066 void *buf; 2068 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 2069 CMSG_SPACE(sizeof (struct in6_pktinfo)); 2071 buf = malloc(total); 2073 We could then use this buffer (buf) for msg_control on each call to 2074 recvmsg() and be assured that we would not lose any ancillary data to 2075 truncation. 2077 6. Common Operations for Both Styles 2079 6.1. send(), recv(), sendto(), and recvfrom() 2081 Applications can use send() and sendto() to transmit data to the peer 2082 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2083 data from the peer. 2085 The function prototypes are 2087 ssize_t send(int sd, 2088 const void *msg, 2089 size_t len, 2090 int flags); 2092 ssize_t sendto(int sd, 2093 const void *msg, 2094 size_t len, 2095 int flags, 2096 const struct sockaddr *to, 2097 socklen_t tolen); 2099 ssize_t recv(int sd, 2100 void *buf, 2101 size_t len, 2102 int flags); 2104 ssize_t recvfrom(int sd, 2105 void *buf, 2106 size_t len, 2107 int flags, 2108 struct sockaddr *from, 2109 socklen_t *fromlen); 2111 and the arguments are 2112 sd: The socket descriptor of an SCTP endpoint. 2113 msg: The message to be sent. 2114 len: the size of the message or the size of the buffer. 2115 to: one of the peer addresses of the association to be used to send 2116 the message. 2117 tolen: The size of the address. 2118 buf: The buffer to store a received message. 2119 from: The buffer to store the peer address used to send the received 2120 message. 2121 fromlen: The size of the from address. 2122 flags: (described below). 2124 These calls give access to only basic SCTP protocol features. If 2125 either peer in the association uses multiple streams, or sends 2126 unordered data, these calls will usually be inadequate, and may 2127 deliver the data in unpredictable ways. 2129 SCTP has the concept of multiple streams in one association. The 2130 above calls do not allow the caller to specify on which stream a 2131 message should be sent. The system uses stream 0 as the default 2132 stream for send() and sendto(). recv() and recvfrom() return data 2133 from any stream, but the caller can not distinguish the different 2134 streams. This may result in data seeming to arrive out of order. 2135 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2136 provide no indication. 2138 SCTP is message based. The msg buffer above in send() and sendto() 2139 is considered to be a single message. This means that if the caller 2140 wants to send a message which is composed by several buffers, the 2141 caller needs to combine them before calling send() or sendto(). 2142 Alternately, the caller can use sendmsg() to do that without 2143 combining them. Sending a message using send() or sendto() is atomic 2144 unless explicit EOR marking is enabled on the socket specified by sd. 2145 Using sendto() on a non-connected one-to-one style socket for 2146 implicit connection setup may or may not work depending on the SCTP 2147 implementation. recv() and recvfrom() cannot distinguish message 2148 boundaries. 2150 In receiving, if the buffer supplied is not large enough to hold a 2151 complete message, the receive call acts like a stream socket and 2152 returns as much data as will fit in the buffer. 2154 Note, the send() and recv() calls may not be used for a one-to-many 2155 style socket. 2157 Note, if an application calls a send function with no user data and 2158 no ancillary data the SCTP implementation should reject the request 2159 with an appropriate error message. An implementation is NOT allowed 2160 to send a DATA chunk with no user data [RFC4960]. 2162 6.2. setsockopt() and getsockopt() 2164 Applications use setsockopt() and getsockopt() to set or retrieve 2165 socket options. Socket options are used to change the default 2166 behavior of socket calls. They are described in Section 7. 2168 The function prototypes are 2170 int getsockopt(int sd, 2171 int level, 2172 int optname, 2173 void *optval, 2174 socklen_t *optlen); 2176 and 2178 int setsockopt(int sd, 2179 int level, 2180 int optname, 2181 const void *optval, 2182 socklen_t optlen); 2184 and the arguments are 2185 sd: The socket descriptor. 2186 level: Set to IPPROTO_SCTP for all SCTP options. 2187 optname: The option name. 2188 optval: The buffer to store the value of the option. 2189 optlen: The size of the buffer (or the length of the option 2190 returned). 2192 All socket options set on a one-to-one style listening socket also 2193 apply to all accepted sockets. For one-to-many style sockets often a 2194 socket option will pass a structure that includes an assoc_id field. 2195 This field can be filled with the association id of a particular 2196 association and unless otherwise specified can be filled with one of 2197 the following constants: 2199 SCTP_FUTURE_ASSOC: Specifies that only future associations created 2200 after this socket option will be affected by this call. 2201 SCTP_CURRENT_ASSOC: Specifies that only currently existing 2202 associations will be affected by this call, future associations 2203 will still receive the previous default value. 2204 SCTP_ALL_ASSOC: Specifies that all current and future associations 2205 will be affected by this call. 2207 6.3. read() and write() 2209 Applications can use read() and write() to send and receive data to 2210 and from a peer. They have the same semantics as send() and recv() 2211 except that the flags parameter cannot be used. 2213 Note, these calls, when used in the one-to-many style, should only be 2214 used with branched off socket descriptors (see Section 8.2). 2216 6.4. getsockname() 2218 Applications use getsockname() to retrieve the locally-bound socket 2219 address of the specified socket. This is especially useful if the 2220 caller let SCTP choose a local port. This call is for single homed 2221 endpoints. It does not work well with multi-homed endpoints. See 2222 Section 8.5 for a multi-homed version of the call. 2224 The function prototype is 2226 int getsockname(int sd, 2227 struct sockaddr *address, 2228 socklen_t *len); 2230 and the arguments are 2231 sd: The socket descriptor to be queried. 2232 address: On return, one locally bound address (chosen by the SCTP 2233 stack) is stored in this buffer. If the socket is an IPv4 socket, 2234 the address will be IPv4. If the socket is an IPv6 socket, the 2235 address will be either an IPv6 or IPv4 address. 2236 len: The caller should set the length of the address here. On 2237 return, this is set to the length of the returned address. 2239 If the actual length of the address is greater than the length of the 2240 supplied sockaddr structure, the stored address will be truncated. 2242 If the socket has not been bound to a local name, the value stored in 2243 the object pointed to by address is unspecified. 2245 7. Socket Options 2247 The following sub-section describes various SCTP level socket options 2248 that are common to both styles. SCTP associations can be multi- 2249 homed. Therefore, certain option parameters include a 2250 sockaddr_storage structure to select which peer address the option 2251 should be applied to. 2253 For the one-to-many style sockets, an sctp_assoc_t (association ID) 2254 parameter is used to identify the association instance that the 2255 operation affects. So it must be set when using this style. 2257 For the one-to-one style sockets and branched off one-to-many style 2258 sockets (see Section 8.2) this association ID parameter is ignored. 2260 Note that socket or IP level options are set or retrieved per socket. 2261 This means that for one-to-many style sockets, those options will be 2262 applied to all associations (similar to using SCTP_ALL_ASSOC as the 2263 association ID) belonging to the socket. And for one-to-one style, 2264 those options will be applied to all peer addresses of the 2265 association controlled by the socket. Applications should be very 2266 careful in setting those options. 2268 For some IP stacks getsockopt() is read-only; so a new interface will 2269 be needed when information must be passed both into and out of the 2270 SCTP stack. The syntax for sctp_opt_info() is 2272 int sctp_opt_info(int sd, 2273 sctp_assoc_t id, 2274 int opt, 2275 void *arg, 2276 socklen_t *size); 2278 The sctp_opt_info() call is a replacement for getsockopt() only and 2279 will not set any options associated with the specified socket. A 2280 setsockopt() must be used to set any writeable option. 2282 For one-to-many style sockets, id specifies the association to query. 2283 For one-to-one style sockets, id is ignored. Note that 2284 SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used here. Using 2285 them will result in an error (returning -1 and errno set to EINVAL). 2286 SCTP_FUTURE_ASSOC can be used to query information for future 2287 associations. 2289 The field opt specifies which SCTP socket option to get. It can get 2290 any socket option currently supported that requests information 2291 (either read/write options or read only) such as: 2293 SCTP_RTOINFO 2294 SCTP_ASSOCINFO 2295 SCTP_DEFAULT_SEND_PARAM 2296 SCTP_GET_PEER_ADDR_INFO 2297 SCTP_PRIMARY_ADDR 2298 SCTP_PEER_ADDR_PARAMS 2299 SCTP_STATUS 2300 SCTP_CONTEXT 2301 SCTP_AUTH_ACTIVE_KEY 2302 SCTP_PEER_AUTH_CHUNKS 2303 SCTP_LOCAL_AUTH_CHUNKS 2305 The arg field is an option-specific structure buffer provided by the 2306 caller. See Section 8.5 subsections for more information on these 2307 options and option-specific structures. 2309 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2310 sets errno to the appropriate error code. 2312 All options that support specific settings on an association by 2313 filling in either an association id variable or a sockaddr_storage 2314 should also support the setting of the same value for the entire 2315 endpoint (i.e. future associations). To accomplish this the 2316 following logic is used when setting one of these options: 2317 o If an address is specified via a sockaddr_storage that is included 2318 in the structure, the address is used to lookup the association 2319 and the settings are applied to the specific address (if 2320 appropriate) or to the entire association. 2321 o If an association identification is filled in but not a 2322 sockaddr_storage (if present), the association is found using the 2323 association identification and the settings should be applied to 2324 the specified association (since a specific address is not 2325 specified). Note this also applies to options that hold an 2326 association identification in their structure but do not have a 2327 sockaddr_storage field. 2328 o If neither the sockaddr_storage nor association identification is 2329 set, i.e. the sockaddr_storage is set to all 0 (INADDR_ANY) and 2330 the association identification is SCTP_FUTURE_ASSOC, the settings 2331 are a default and to be applied to the endpoint. 2333 7.1. Read / Write Options 2335 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2337 The protocol parameters used to initialize and limit the 2338 retransmission timeout (RTO) are tunable. See [RFC4960] for more 2339 information on how these parameters are used in RTO calculation. 2341 The following structure is used to access and modify these 2342 parameters: 2344 struct sctp_rtoinfo { 2345 sctp_assoc_t srto_assoc_id; 2346 uint32_t srto_initial; 2347 uint32_t srto_max; 2348 uint32_t srto_min; 2349 }; 2351 srto_initial: This contains the initial RTO value. 2352 srto_max and srto_min: These contain the maximum and minimum bounds 2353 for all RTOs. 2354 srto_assoc_id: This parameter is ignored for one-to-one style 2355 sockets. For one-to-many style sockets the application may fill 2356 in an association identification or SCTP_FUTURE_ASSOC. It is an 2357 error to use SCTP_{CURRENT|ALL}_ASSOC in srto_asssoc_id. 2359 All times are given in milliseconds. A value of 0, when modifying 2360 the parameters, indicates that the current value should not be 2361 changed. 2363 To access or modify these parameters, the application should call 2364 getsockopt() or setsockopt() respectively with the option name 2365 SCTP_RTOINFO. 2367 7.1.2. Association Parameters (SCTP_ASSOCINFO) 2369 This option is used to both examine and set various association and 2370 endpoint parameters. See [RFC4960] for more information on how this 2371 parameter is used. 2373 The following structure is used to access and modify these 2374 parameters: 2376 struct sctp_assocparams { 2377 sctp_assoc_t sasoc_assoc_id; 2378 uint16_t sasoc_asocmaxrxt; 2379 uint16_t sasoc_number_peer_destinations; 2380 uint32_t sasoc_peer_rwnd; 2381 uint32_t sasoc_local_rwnd; 2382 uint32_t sasoc_cookie_life; 2383 }; 2384 sasoc_assoc_id: This parameter is ignored for one-to-one style 2385 sockets. For one-to-many style sockets the application may fill 2386 in an association identification or SCTP_FUTURE_ASSOC. It is an 2387 error to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_asssoc_id. 2388 sasoc_asocmaxrxt: This contains the maximum retransmission attempts 2389 to make for the association. 2390 sasoc_number_peer_destinations: This is the number of destination 2391 addresses that the peer has. 2392 sasoc_peer_rwnd: This holds the current value of the peers rwnd 2393 (reported in the last SACK) minus any outstanding data (i.e. data 2394 in flight). 2395 sasoc_local_rwnd: This holds the last reported rwnd that was sent to 2396 the peer. 2397 sasoc_cookie_life: This is the association's cookie life value used 2398 when issuing cookies. 2400 The values of the sasoc_peer_rwnd is meaningless when examining 2401 endpoint information. 2403 All time values are given in milliseconds. A value of 0, when 2404 modifying the parameters, indicates that the current value should not 2405 be changed. 2407 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2408 on either an endpoint or association basis. The rwnd and destination 2409 counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, 2410 sasoc_local_rwnd) are NOT settable and any value placed in these is 2411 ignored. 2413 To access or modify these parameters, the application should call 2414 getsockopt() or setsockopt() respectively with the option name 2415 SCTP_ASSOCINFO. 2417 The maximum number of retransmissions before an address is considered 2418 unreachable is also tunable, but is address-specific, so it is 2419 covered in a separate option. If an application attempts to set the 2420 value of the association maximum retransmission parameter to more 2421 than the sum of all maximum retransmission parameters, setsockopt() 2422 may return an error. The reason for this, from [RFC4960] section 2423 8.2: 2425 Note: When configuring the SCTP endpoint, the user should avoid 2426 having the value of 'Association.Max.Retrans' (sasoc_maxrt in this 2427 option) larger than the summation of the 'Path.Max.Retrans' (see 2428 Section 7.1.2 on spp_pathmaxrxt) of all the destination addresses for 2429 the remote endpoint. Otherwise, all the destination addresses may 2430 become inactive while the endpoint still considers the peer endpoint 2431 reachable. 2433 7.1.3. Initialization Parameters (SCTP_INITMSG) 2435 Applications can specify protocol parameters for the default 2436 association initialization. The structure used to access and modify 2437 these parameters is defined in Section 5.2.1. The option name 2438 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2440 Setting initialization parameters is effective only on an unconnected 2441 socket (for one-to-many style sockets only future associations are 2442 affected by the change). With one-to-one style sockets, this option 2443 is inherited by sockets derived from a listening socket. 2445 7.1.4. SO_LINGER 2447 An application can use this option to perform the SCTP ABORT 2448 primitive. This option affects all associations related to the 2449 socket. 2451 The linger option structure is: 2453 struct linger { 2454 int l_onoff; /* option on/off */ 2455 int l_linger; /* linger time */ 2456 }; 2458 To enable the option, set l_onoff to 1. If the l_linger value is set 2459 to 0, calling close() is the same as the ABORT primitive. If the 2460 value is set to a negative value, the setsockopt() call will return 2461 an error. If the value is set to a positive value linger_time, the 2462 close() can be blocked for at most linger_time ms. If the graceful 2463 shutdown phase does not finish during this period, close() will 2464 return but the graceful shutdown phase will continue in the system. 2466 Note, this is a socket level option NOT an SCTP level option. So 2467 when setting SO_LINGER an application must specify a level of 2468 SOL_SOCKET in the setsockopt() call. 2470 7.1.5. SCTP_NODELAY 2472 Turn on/off any Nagle-like algorithm. This means that packets are 2473 generally sent as soon as possible and no unnecessary delays are 2474 introduced, at the cost of more packets in the network. Expects an 2475 integer boolean flag. Turning this option on disables any Nagle-like 2476 algorithm. 2478 7.1.6. SO_RCVBUF 2480 Sets the receive buffer size in octets. For SCTP one-to-one style 2481 sockets, this controls the receiver window size. For one-to-many 2482 style sockets the meaning is implementation dependent. It might 2483 control the receive buffer for each association bound to the socket 2484 descriptor or it might control the receive buffer for the whole 2485 socket. The call expects an integer. 2487 7.1.7. SO_SNDBUF 2489 Sets the send buffer size. For SCTP one-to-one style sockets, this 2490 controls the amount of data SCTP may have waiting in internal buffers 2491 to be sent. This option therefore bounds the maximum size of data 2492 that can be sent in a single send call. For one-to-many style 2493 sockets, the effect is the same, except that it applies to one or all 2494 associations (see Section 3.4) bound to the socket descriptor used in 2495 the setsockopt() or getsockopt() call. The option applies to each 2496 association's window size separately. The call expects an integer. 2498 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 2500 This socket option is applicable to the one-to-many style socket 2501 only. When set it will cause associations that are idle for more 2502 than the specified number of seconds to automatically close using the 2503 graceful shutdown procedure. An association being idle is defined as 2504 an association that has NOT sent or received user data. The special 2505 value of '0' indicates that no automatic close of any association 2506 should be performed, this is the default value. The option expects 2507 an integer defining the number of seconds of idle time before an 2508 association is closed. 2510 An application using this option should enable receiving the 2511 association change notification. This is the only mechanism an 2512 application is informed about the closing of an association. After 2513 an association is closed, the association ID assigned to it can be 2514 reused. An application should be aware of this to avoid the possible 2515 problem of sending data to an incorrect peer endpoint. 2517 7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 2519 Requests that the local SCTP stack uses the enclosed peer address as 2520 the association's primary. The enclosed address must be one of the 2521 association peer's addresses. 2523 The following structure is used to make a set peer primary request: 2525 struct sctp_setprim { 2526 sctp_assoc_t ssp_assoc_id; 2527 struct sockaddr_storage ssp_addr; 2528 }; 2530 ssp_addr: The address to set as primary. 2531 ssp_assoc_id: This parameter is ignored for one-to-one style 2532 sockets. For one-to-many style sockets it identifies the 2533 association for this request. Note that the special sctp_assoc_t 2534 SCTP_{FUTURE|ALL|CURRENT}_ASSOC are not allowed. 2536 7.1.10. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2538 Requests that the local endpoint set the specified Adaptation Layer 2539 Indication parameter for all future INIT and INIT-ACK exchanges. 2541 The following structure is used to access and modify this parameter: 2543 struct sctp_setadaptation { 2544 uint32_t ssb_adaptation_ind; 2545 }; 2547 ssb_adaptation_ind: The adaptation layer indicator that will be 2548 included in any outgoing Adaptation Layer Indication parameter. 2550 7.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 2552 This option is a on/off flag and is passed as an integer where a non- 2553 zero is on and a zero is off. If enabled no SCTP message 2554 fragmentation will be performed. Instead, if a message being sent 2555 exceeds the current PMTU size, the message will NOT be sent and 2556 instead an error will be indicated to the user. 2558 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2560 Applications can enable or disable heartbeats for any peer address of 2561 an association, modify an address's heartbeat interval, force a 2562 heartbeat to be sent immediately, and adjust the address's maximum 2563 number of retransmissions sent before an address is considered 2564 unreachable. 2566 The following structure is used to access and modify an address's 2567 parameters: 2569 struct sctp_paddrparams { 2570 sctp_assoc_t spp_assoc_id; 2571 struct sockaddr_storage spp_address; 2572 uint32_t spp_hbinterval; 2573 uint16_t spp_pathmaxrxt; 2574 uint32_t spp_pathmtu; 2575 uint32_t spp_flags; 2576 uint32_t spp_ipv6_flowlabel; 2577 uint8_t spp_ipv4_tos; 2578 }; 2580 spp_assoc_id: This parameter is ignored for one-to-one style 2581 sockets. For one-to-many style sockets it identifies the 2582 association for this query. Note that the predefined constants 2583 are NOT allowed. 2584 spp_address: This specifies which address is of interest. If a 2585 wildcard address is provided it applies to all current and future 2586 paths. 2587 spp_hbinterval: This contains the value of the heartbeat interval, 2588 in milliseconds (HB.Interval in [RFC4960]). Note that unless the 2589 spp_flag is set to SPP_HB_ENABLE the value of this field is 2590 ignored. Note also that a value of zero indicates the current 2591 setting should be left unchanged. To set an actual value of zero 2592 the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when 2593 it is set to 0, it does not mean that SCTP will continuously send 2594 out heartbeat since the actual interval also includes a the 2595 current RTO and jitter (see Section 8.3 in [RFC4960]). 2596 spp_pathmaxrxt: This contains the maximum number of retransmissions 2597 before this address shall be considered unreachable. Note that a 2598 value of zero indicates the current setting should be left 2599 unchanged. 2600 spp_pathmtu: When Path MTU discovery is disabled the value specified 2601 here will be the "fixed" path MTU (i.e. the value of the spp_flags 2602 field must include the flag SPP_PMTUD_DISABLE). Note also that 2603 this option cannot be set on the endpoint, but must be set on each 2604 individual association. Also, when disabling PMTU discovery, the 2605 implementation may disallow this behavior if the "fixed" path MTU 2606 is below the constant value SCTP_SMALLEST_PMTU. 2607 spp_ipv6_flowlabel: This field is used in conjunction with the 2608 SPP_IPV6_FLOWLABEL flag. 2609 spp_ipv4_tos: This field is used in conjunction with the 2610 SPP_IPV4_TOS flag. 2611 spp_flags: These flags are used to control various features on an 2612 association. The flag field is a bit mask which may contain zero 2613 or more of the following options: 2615 SPP_HB_ENABLE: Enable heartbeats on the specified address. 2616 SPP_HB_DISABLE: Disable heartbeats on the specified address. 2617 Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually 2618 exclusive, only one of these two should be specified. Enabling 2619 both fields will have undetermined results. 2620 SPP_HB_DEMAND: Request a user initiated heartbeat to be made 2621 immediately. This must not be used in conjunction with a 2622 wildcard address. 2623 SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay 2624 is to be set to the value of 0 milliseconds. 2625 SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the 2626 specified address. 2627 SPP_PMTUD_DISABLE: This field will disable PMTU discovery upon 2628 the specified address. Note that if the address field is empty 2629 then all addresses on the association are affected. Note also 2630 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2631 exclusive. Enabling both will have undetermined results. 2632 SPP_IPV6_FLOWLABEL: Setting this flag enables the setting of the 2633 IPV6 flowlabel value. The value is obtained in the 2634 spp_ipv6_flowlabel field. 2636 Upon retrieval, this flag will be set to indicate that the 2637 spp_ipv6_flowlabel field has a valid value returned. If a 2638 specific destination address is set (in the spp_address field), 2639 then the value returned is that of the address. If just an 2640 association is specified (and no address), then the 2641 association's default flowlabel is returned. If neither an 2642 association nor a destination is specified, then the socket's 2643 default flowlabel is returned. For non IPv6 sockets, this flag 2644 will be left cleared. 2645 SPP_IPV4_TOS: Setting this flag enables the setting of the IPV4 2646 TOS value associated with either the association or a specific 2647 address. The value is obtained in the spp_ipv4_tos field. 2649 Upon retrieval, this flag will be set to indicate that the 2650 spp_ipv4_tos field has a valid value returned. If a specific 2651 destination address is set when called (in the spp_address 2652 field) then that specific destination address' TOS value is 2653 returned. If just an association is specified then the 2654 association default TOS is returned. If neither an association 2655 nor an destination is specified, then the sockets default TOS 2656 is returned. 2658 To read or modify these parameters, the application should call 2659 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2661 7.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) 2663 Applications that wish to use the sendto() system call may wish to 2664 specify a default set of parameters that would normally be supplied 2665 through the inclusion of ancillary data. This socket option allows 2666 such an application to set the default sctp_sndrcvinfo structure. 2667 The application that wishes to use this socket option simply passes 2668 the sctp_sndrcvinfo structure defined in Section 5.2.2 to this call. 2669 The input parameters accepted by this call include sinfo_stream, 2670 sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy and 2671 sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of 2672 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field 2673 specifies the association to apply the parameters to. In a one-to- 2674 many style sockets any of the predefined constants are also allowed 2675 in this field. The field is ignored on the one-to-one style. 2677 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) 2679 This socket option is used to specify various notifications and 2680 ancillary data the user wishes to receive. Please see Section 7.4 2681 for a full description of this option and its usage. Note that this 2682 option is considered deprecated and present for backward 2683 compatibility. New applications should use the SCTP_SET_EVENT 2684 option. See Section 7.4 for a full description of that option as 2685 well. 2687 7.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2689 This socket option is a boolean flag which turns on or off the 2690 mapping of IPv4 addresses. If this option is turned on and the 2691 socket is type PF_INET6, then IPv4 addresses will be mapped to V6 2692 representation. If this option is turned off, then no mapping will 2693 be done of V4 addresses and a user will receive both PF_INET6 and 2694 PF_INET type addresses on the socket. 2696 By default this option is turned off and expects an integer to be 2697 passed where non-zero turns on the option and zero turns off the 2698 option. 2700 7.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 2702 This option will get or set the maximum size to put in any outgoing 2703 SCTP DATA chunk. If a message is larger than this size it will be 2704 fragmented by SCTP into the specified size. Note that the underlying 2705 SCTP implementation may fragment into smaller sized chunks when the 2706 PMTU of the underlying association is smaller than the value set by 2707 the user. The default value for this option is '0' which indicates 2708 the user is NOT limiting fragmentation and only the PMTU will affect 2709 SCTP's choice of DATA chunk size. Note also that values set larger 2710 than the maximum size of an IP datagram will effectively let SCTP 2711 control fragmentation (i.e. the same as setting this option to 0). 2713 The following structure is used to access and modify this parameter: 2715 struct sctp_assoc_value { 2716 sctp_assoc_t assoc_id; 2717 uint32_t assoc_value; 2718 }; 2720 assoc_id: This parameter is ignored for one-to-one style sockets. 2721 For one-to-many style sockets this parameter indicates which 2722 association the user is performing an action upon. It is an error 2723 to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_asssoc_id. 2724 assoc_value: This parameter specifies the maximum size in bytes. 2726 7.1.17. Get or Set the List of Supported HMAC Identifiers 2727 (SCTP_HMAC_IDENT) 2729 This option gets or sets the list of HMAC algorithms that the local 2730 endpoint requires the peer to use. 2732 The following structure is used to get or set these identifiers: 2734 struct sctp_hmacalgo { 2735 uint32_t shmac_number_of_idents; 2736 uint16_t shmac_idents[]; 2737 }; 2739 shmac_number_of_idents: This field gives the number of elements 2740 present in the array shmac_idents. 2741 shmac_idents: This parameter contains an array of HMAC identifiers 2742 that the local endpoint is requesting the peer to use, in priority 2743 order. The following identifiers are valid: 2744 * SCTP_AUTH_HMAC_ID_SHA1 2745 * SCTP_AUTH_HMAC_ID_SHA256 2747 Note that the list supplied must include SCTP_AUTH_HMAC_ID_SHA1 and 2748 may include any of the other values in its preferred order (lowest 2749 list position has the highest preference in algorithm selection). 2750 Note also that the lack of SCTP_AUTH_HMAC_ID_SHA1, or the inclusion 2751 of an unknown HMAC identifier (including optional identifiers unknown 2752 to the implementation) will cause the set option to fail and return 2753 an error. 2755 7.1.18. Get or Set the Active Shared Key (SCTP_AUTH_ACTIVE_KEY) 2757 This option will get or set the active shared key to be used to build 2758 the association shared key. 2760 The following structure is used to access and modify these 2761 parameters: 2763 struct sctp_authkeyid { 2764 sctp_assoc_t scact_assoc_id; 2765 uint16_t scact_keynumber; 2766 }; 2768 scact_assoc_id: This parameter sets the active key of the specified 2769 association. The special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be 2770 used. For one-to-one sockets, this parameter is ignored. Note, 2771 however, that this option will set the active key on the 2772 association if the socket is connected, otherwise this will set 2773 the default active key for the endpoint. 2774 scact_keynumber: This parameter is the shared key identifier which 2775 the application is requesting to become the active shared key to 2776 be used for sending authenticated chunks. The key identifier must 2777 correspond to an existing shared key. Note that shared key 2778 identifier '0' defaults to a null key. 2780 When used with setsockopt() the SCTP implementation must use the 2781 indicated shared key identifier for all messages being given to an 2782 SCTP implementation via a send call after the setsockopt() call until 2783 changed again. Therefore, the SCTP implementation must not bundle 2784 user messages which should be authenticated using different shared 2785 key identifiers. 2787 Initially the key with key identifier 0 is the active key. 2789 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) 2791 This option will affect the way delayed acks are performed. This 2792 option allows the application to get or set the delayed ack time, in 2793 milliseconds. It also allows changing the delayed ack frequency. 2794 Changing the frequency to 1 disables the delayed sack algorithm. 2795 Note that if sack_delay or sack_freq are 0 when setting this option, 2796 the current values will remain unchanged. 2798 The following structure is used to access and modify these 2799 parameters: 2801 struct sctp_sack_info { 2802 sctp_assoc_t sack_assoc_id; 2803 uint32_t sack_delay; 2804 uint32_t sack_freq; 2805 }; 2807 sack_assoc_id: This parameter is ignored for one-to-one style 2808 sockets. For one-to-many style sockets this parameter indicates 2809 which association the user is performing an action upon. The 2810 special SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 2811 sack_delay: This parameter contains the number of milliseconds that 2812 the user is requesting the delayed ACK timer to be set to. Note 2813 that this value is defined in the standard to be between 200 and 2814 500 milliseconds. 2815 sack_freq: This parameter contains the number of packets that must 2816 be received before a sack is sent without waiting for the delay 2817 timer to expire. The default value is 2, setting this value to 1 2818 will disable the delayed sack algorithm. 2820 7.1.20. Get or Set Fragmented Interleave (SCTP_FRAGMENT_INTERLEAVE) 2822 Fragmented interleave controls how the presentation of messages 2823 occurs for the message receiver. There are three levels of fragment 2824 interleave defined. Two of the levels affect the one-to-one model, 2825 while the one-to-many model is affected by all three levels. 2827 This option takes an integer value. It can be set to a value of 0, 1 2828 or 2. Attempting to set this level to other values will return an 2829 error. 2831 Setting the three levels provides the following receiver 2832 interactions: 2834 level 0: Prevents the interleaving of any messages. This means that 2835 when a partial delivery begins, no other messages will be received 2836 except the message being partially delivered. If another message 2837 arrives on a different stream (or association) that could be 2838 delivered, it will be blocked waiting for the user to read all of 2839 the partially delivered message. 2840 level 1: Allows interleaving of messages that are from different 2841 associations. For the one-to-one model, level 0 and level 1 thus 2842 have the same meaning since a one-to-one socket always receives 2843 messages from the same association. Note that setting the one-to- 2844 many model to this level may cause multiple partial deliveries 2845 from different associations but for any given association, only 2846 one message will be delivered until all parts of a message have 2847 been delivered. This means that one large message, being read 2848 with an association identification of "X", will block other 2849 messages from association "X" from being delivered. 2850 level 2: Allows complete interleaving of messages. This level 2851 requires that the sender carefully observes not only the peer 2852 association identification (or address) but must also pay careful 2853 attention to the stream number. With this option enabled a 2854 partially delivered message may begin being delivered for 2855 association "X" stream "Y" and the next subsequent receive may 2856 return a message from association "X" stream "Z". Note that no 2857 other messages would be delivered for association "X" stream "Y" 2858 until all of stream "Y"'s partially delivered message was read. 2859 Note that this option also affects the one-to-one model. Also 2860 note that for the one-to-many model not only may another streams 2861 message from the same association be delivered from the next 2862 receive, some other associations message may be delivered upon the 2863 next receive. 2865 An implementation should default the one-to-many model to level 1. 2866 The reason for this is that otherwise it is possible that a peer 2867 could begin sending a partial message and thus block all other peers 2868 from sending data. However a setting of level 2 requires the 2869 application to not only be aware of the association (via the 2870 association id or peer's address) but also the stream number. The 2871 stream number is NOT present unless the user has subscribed to the 2872 sctp_data_io_events (see Section 7.4). This is also why we recommend 2873 that the one-to-one model be defaulted to level 0 (level 1 for the 2874 one-to-one model has no effect). Note that an implementation should 2875 return an error if an application attempts to set the level to 2 and 2876 has NOT subscribed to the sctp_data_io_events. 2878 For applications that have subscribed to events those events appear 2879 in the normal socket buffer data stream. This means that unless the 2880 user has set the fragmentation interleave level to 0, notifications 2881 may also be interleaved with partially delivered messages. 2883 7.1.21. Set or Get the SCTP Partial Delivery Point 2884 (SCTP_PARTIAL_DELIVERY_POINT) 2886 This option will set or get the SCTP partial delivery point. This 2887 point is the size of a message where the partial delivery API will be 2888 invoked to help free up rwnd space for the peer. Setting this to a 2889 lower value will cause partial deliveries to happen more often. The 2890 call's argument is an integer that sets or gets the partial delivery 2891 point in bytes. Note also that the call will fail if the user 2892 attempts to set this value larger than the socket receive buffer 2893 size. 2895 Note that any single message having a length smaller than or equal to 2896 the SCTP partial delivery point will be delivered in one single read 2897 call as long as the user provided buffer is large enough to hold the 2898 message. 2900 7.1.22. Set or Get the Use of Extended Receive Info 2901 (SCTP_USE_EXT_RCVINFO) 2903 This option will enable or disable the use of the extended version of 2904 the sctp_sndrcvinfo structure. If this option is disabled, then the 2905 normal sctp_sndrcvinfo structure is returned in all receive message 2906 calls. If this option is enabled then the sctp_extrcvinfo structure 2907 is returned in all receive message calls. This option is present for 2908 compatibility with older applications and is deprecated. Future 2909 applications should use SCTP_NXTINFO to retrieve this same 2910 information via ancillary data. 2912 Note that the sctp_extrcvinfo structure is never used in any send 2913 call. 2915 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) 2917 This option will enable or disable the use of the automatic 2918 generation of ASCONF chunks to add and delete addresses to an 2919 existing association. Note that this option has two caveats namely: 2920 a) it only affects sockets that are bound to all addresses on the 2921 machine, and b) the system administrator may have an overriding 2922 control that turns the ASCONF feature off no matter what setting the 2923 socket option may have. 2925 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) 2927 This option will allow a user to change the maximum burst of packets 2928 that can be emitted by this association. Note that the default value 2929 is 4, and some implementations may restrict this setting so that it 2930 can only be lowered. 2932 To set or get this option the user fills in the following structure: 2934 struct sctp_assoc_value { 2935 sctp_assoc_t assoc_id; 2936 uint32_t assoc_value; 2937 }; 2939 assoc_id: This parameter is ignored for one-to-one style sockets. 2940 For one-to-many style sockets this parameter indicates which 2941 association the user is performing an action upon. The special 2942 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 2944 assoc_value: This parameter contains the maximum burst. 2946 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) 2948 The context field in the sctp_sndrcvinfo structure is normally only 2949 used when a failed message is retrieved holding the value that was 2950 sent down on the actual send call. This option allows the setting of 2951 a default context on an association basis that will be received on 2952 reading messages from the peer. This is especially helpful in the 2953 one-to-many model for an application to keep some reference to an 2954 internal state machine that is processing messages on the 2955 association. Note that the setting of this value only affects 2956 received messages from the peer and does not affect the value that is 2957 saved with outbound messages. 2959 To set or get this option the user fills in the following structure: 2961 struct sctp_assoc_value { 2962 sctp_assoc_t assoc_id; 2963 uint32_t assoc_value; 2964 }; 2966 assoc_id: This parameter is ignored for one-to-one style sockets. 2967 For one-to-many style sockets this parameter indicates which 2968 association the user is performing an action upon. The special 2969 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can also be used. 2970 assoc_value: This parameter contains the context. 2972 7.1.26. Enable or Disable Explicit EOR Marking (SCTP_EXPLICIT_EOR) 2974 This boolean flag is used to enable or disable explicit end of record 2975 (EOR) marking. When this option is enabled, a user may make multiple 2976 send system calls to send a record and must indicate that they are 2977 finished sending a particular record by including the SCTP_EOR flag. 2978 If this boolean flag is disabled then each individual send system 2979 call is considered to have an SCTP_EOR indicator set on it implicitly 2980 without the user having to explicitly add this flag. 2982 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) 2984 This option only supports one-to-one style SCTP sockets. If used on 2985 a one-to-many style SCTP socket an error is indicated. 2987 This setsockopt() call must not be used after calling bind() or 2988 sctp_bindx() for a one-to-one style SCTP socket. If using bind() or 2989 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 2990 SCTP sockets bound to the same port must have set the 2991 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 2992 having set the SCTP_REUSE_PORT option will fail if there are other 2993 sockets bound to the same port. At most one socket being bound to 2994 the same port may be listening. 2996 It should be noted that the behavior of the socket level socket 2997 option to reuse ports and/or addresses for SCTP sockets is 2998 unspecified. 3000 7.1.28. Set Notification Event (SCTP_EVENT) 3002 This socket option is used to set a specific notification or 3003 ancillary data option. Please see Section 7.4 for a full description 3004 of this option and its usage. 3006 7.2. Read-Only Options 3008 The options defined in this subsection are read-only. Using this 3009 option in a setsockopt() call will result in an error indicating 3010 EOPNOTSUPP. 3012 7.2.1. Association Status (SCTP_STATUS) 3014 Applications can retrieve current status information about an 3015 association, including association state, peer receiver window size, 3016 number of unacked data chunks, and number of data chunks pending 3017 receipt. This information is read-only. 3019 The following structure is used to access this information: 3021 struct sctp_status { 3022 sctp_assoc_t sstat_assoc_id; 3023 int32_t sstat_state; 3024 uint32_t sstat_rwnd; 3025 uint16_t sstat_unackdata; 3026 uint16_t sstat_penddata; 3027 uint16_t sstat_instrms; 3028 uint16_t sstat_outstrms; 3029 uint32_t sstat_fragmentation_point; 3030 struct sctp_paddrinfo sstat_primary; 3031 }; 3033 sstat_assoc_id: This parameter is ignored for one-to-one style 3034 sockets. For one-to-many style sockets it holds the identifier 3035 for the association. All notifications for a given association 3036 have the same association identifier. The special SCTP_{FUTURE| 3037 CURRENT|ALL}_ASSOC cannot be used. 3039 sstat_state: This contains the association's current state one of 3040 the following values: 3041 * SCTP_CLOSED 3042 * SCTP_BOUND 3043 * SCTP_LISTEN 3044 * SCTP_COOKIE_WAIT 3045 * SCTP_COOKIE_ECHOED 3046 * SCTP_ESTABLISHED 3047 * SCTP_SHUTDOWN_PENDING 3048 * SCTP_SHUTDOWN_SENT 3049 * SCTP_SHUTDOWN_RECEIVED 3050 * SCTP_SHUTDOWN_ACK_SENT 3051 sstat_rwnd: This contains the association peer's current receiver 3052 window size. 3053 sstat_unackdata: This is the number of unacked data chunks. 3054 sstat_penddata: This is the number of data chunks pending receipt. 3055 sstat_instrms: The number of streams that the peer will be using 3056 outbound. 3057 sstat_outstrms: The number of streams that the endpoint is allowed 3058 to use outbound. 3059 sstat_fragmentation_point: The size at which SCTP fragmentation will 3060 occur. 3061 sstat_primary: This is information on the current primary peer 3062 address. 3064 To access these status values, the application calls getsockopt() 3065 with the option name SCTP_STATUS. 3067 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3069 Applications can retrieve information about a specific peer address 3070 of an association, including its reachability state, congestion 3071 window, and retransmission timer values. This information is read- 3072 only. 3074 The following structure is used to access this information: 3076 struct sctp_paddrinfo { 3077 sctp_assoc_t spinfo_assoc_id; 3078 struct sockaddr_storage spinfo_address; 3079 int32_t spinfo_state; 3080 uint32_t spinfo_cwnd; 3081 uint32_t spinfo_srtt; 3082 uint32_t spinfo_rto; 3083 uint32_t spinfo_mtu; 3084 }; 3085 spinfo_assoc_id: This parameter is ignored for one-to-one style 3086 sockets. For one-to-many style sockets the following applies: 3087 This field may be filled by the application, if so, this field 3088 will have priority in looking up the association using the address 3089 specified in spinfo_address. Note that if the address does not 3090 belong to the association specified then this call will fail. If 3091 the application does NOT fill in the spinfo_assoc_id, then the 3092 address will be used to lookup the association and on return this 3093 field will have the valid association id. In other words, this 3094 call can be used to translate an address into an association id. 3095 Note that the predefined constants are not allowed on this option. 3096 spinfo_address: This is filled by the application, and contains the 3097 peer address of interest. 3098 spinfo_state: This contains the peer address' state (either 3099 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 3100 SCTP_UNCONFIRMED). 3101 spinfo_cwnd: This contains the peer address' current congestion 3102 window. 3103 spinfo_srtt: This contains the peer address' current smoothed round- 3104 trip time calculation in milliseconds. 3105 spinfo_rto: This contains the peer address' current retransmission 3106 timeout value in milliseconds. 3107 spinfo_mtu: The current P-MTU of this address. 3109 7.2.3. Get the List of Chunks the Peer Requires to be Authenticated 3110 (SCTP_PEER_AUTH_CHUNKS) 3112 This option gets a list of chunk types (see [RFC4960] for a specified 3113 association that the peer requires to be received authenticated only. 3115 The following structure is used to access these parameters: 3117 struct sctp_authchunks { 3118 sctp_assoc_t gauth_assoc_id; 3119 uint32_t gauth_number_of_chunks 3120 uint8_t gauth_chunks[]; 3121 }; 3123 gauth_assoc_id: This parameter indicates for which association the 3124 user is requesting the list of peer authenticated chunks. For 3125 one-to-one sockets, this parameter is ignored. Note that the 3126 predefined constants are not allowed with this option. 3127 gauth_number_of_chunks: This parameter gives the number of elements 3128 in the array gauth_chunks. 3130 gauth_chunks: This parameter contains an array of chunk types that 3131 the peer is requesting to be authenticated. 3133 7.2.4. Get the List of Chunks the Local Endpoint Requires to be 3134 Authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3136 This option gets a list of chunk types (see [RFC4960]) for a 3137 specified association that the local endpoint requires to be received 3138 authenticated only. 3140 The following structure is used to access these parameters: 3142 struct sctp_authchunks { 3143 sctp_assoc_t gauth_assoc_id; 3144 uint32_t gauth_number_of_chunks; 3145 uint8_t gauth_chunks[]; 3146 }; 3148 gauth_assoc_id: This parameter indicates for which association the 3149 user is requesting the list of local authenticated chunks. For 3150 one-to-one sockets, this parameter is ignored. 3151 gauth_number_of_chunks: This parameter gives the number of elements 3152 in the array gauth_chunks. 3153 gauth_chunks: This parameter contains an array of chunk types that 3154 the local endpoint is requesting to be authenticated. 3156 7.2.5. Get the Current Number of Associations (SCTP_GET_ASSOC_NUMBER) 3158 This option gets the current number of associations that are attached 3159 to a one-to-many style socket. The option value is an uint32_t. 3160 Note that this number is only a snap shot. This means that the 3161 number of associations may have changed when the caller gets back the 3162 option result. 3164 7.2.6. Get the Current Identifiers of Associations 3165 (SCTP_GET_ASSOC_ID_LIST) 3167 This option gets the current list of SCTP association identifiers of 3168 the SCTP associations handled by a one-to-many style socket. 3170 The option value has the structure 3172 struct sctp_assoc_ids { 3173 uint32_t gaids_number_of_ids; 3174 sctp_assoc_t gaids_assoc_id[]; 3175 }; 3177 The caller must provide a large enough buffer to hold all association 3178 identifiers. If the buffer is too small, an error must be returned. 3179 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3180 idea how large the buffer has to be. gaids_number_of_ids gives the 3181 number of elements in the array gaids_assoc_id. Note also that the 3182 some or all of sctp_assoc_t returned in the array may become invalid 3183 by the time the caller gets back the result. 3185 7.3. Write-Only Options 3187 The options defined in this subsection are write-only. Using this 3188 option in a getsockopt() or sctp_opt_info() call will result in an 3189 error indicating EOPNOTSUPP. 3191 7.3.1. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 3193 Requests that the peer marks the enclosed address as the association 3194 primary (see [RFC5061]). The enclosed address must be one of the 3195 association's locally bound addresses. 3197 The following structure is used to make a set peer primary request: 3199 struct sctp_setpeerprim { 3200 sctp_assoc_t sspp_assoc_id; 3201 struct sockaddr_storage sspp_addr; 3202 }; 3204 sspp_addr: The address to set as primary. 3205 sspp_assoc_id: This parameter is ignored for one-to-one style 3206 sockets. For one-to-many style sockets it identifies the 3207 association for this request. Note that the predefined constants 3208 are not allowed on this option. 3210 7.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) 3212 This set option adds a chunk type that the user is requesting to be 3213 received only in an authenticated way. Changes to the list of chunks 3214 will only affect future associations on the socket. 3216 The following structure is used to add a chunk: 3218 struct sctp_authchunk { 3219 uint8_t sauth_chunk; 3220 }; 3221 sauth_chunk: This parameter contains a chunk type that the user is 3222 requesting to be authenticated. 3224 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 3225 chunks must not be used. If they are used, an error must be 3226 returned. The usage of this option enables SCTP AUTH in cases where 3227 it is not required by other means (for example the use of dynamic 3228 address reconfiguration). 3230 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) 3232 This option will set a shared secret key which is used to build an 3233 association shared key. 3235 The following structure is used to access and modify these 3236 parameters: 3238 struct sctp_authkey { 3239 sctp_assoc_t sca_assoc_id; 3240 uint16_t sca_keynumber; 3241 uint16_t sca_keylength; 3242 uint8_t sca_key[]; 3243 }; 3245 sca_assoc_id: This parameter indicates what association the shared 3246 key is being set upon. The special SCTP_{FUTURE|CURRENT| 3247 ALL}_ASSOC can be used. For one-to-one sockets, this parameter is 3248 ignored. Note, however, that this option will set a key on the 3249 association if the socket is connected, otherwise this will set a 3250 key on the endpoint. 3251 sca_keynumber: This parameter is the shared key identifier by which 3252 the application will refer to this shared key. If a key of the 3253 specified index already exists, then this new key will replace the 3254 old existing key. Note that shared key identifier '0' defaults to 3255 a null key. 3256 sca_keylength: This parameter is the length of the array sca_key. 3257 sca_key: This parameter contains an array of bytes that is to be 3258 used by the endpoint (or association) as the shared secret key. 3259 Note, if the length of this field is zero, a null key is set. 3261 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) 3263 This set option indicates that the application will not send user 3264 messages anymore using the indicated key identifier. 3266 struct sctp_authkeyid { 3267 sctp_assoc_t scact_assoc_id; 3268 uint16_t scact_keynumber; 3270 }; 3272 scact_assoc_id: This parameter indicates which association the 3273 shared key identifier is being deleted from. The special 3274 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3275 sockets, this parameter is ignored. Note, however, that this 3276 option will deactivate the key from the association if the socket 3277 is connected, otherwise this will deactivate the key from the 3278 endpoint. 3279 scact_keynumber: This parameter is the shared key identifier which 3280 the application is requesting to be deactivated. The key 3281 identifier must correspond to an existing shared key. Note if 3282 this parameter is zero, use of the null key identifier '0' is 3283 deactivated on the endpoint and/or association. 3285 The currently active key cannot be deactivated. 3287 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) 3289 This set option will delete a shared secret key which has been 3290 deactivated of an SCTP association. 3292 struct sctp_authkeyid { 3293 sctp_assoc_t scact_assoc_id; 3294 uint16_t scact_keynumber; 3295 }; 3297 scact_assoc_id: This parameter indicates which association the 3298 shared key identifier is being deleted from. The special 3299 SCTP_{FUTURE|CURRENT|ALL}_ASSOC can be used. For one-to-one 3300 sockets, this parameter is ignored. Note, however, that this 3301 option will delete the key from the association if the socket is 3302 connected, otherwise this will delete the key from the endpoint. 3303 scact_keynumber: This parameter is the shared key identifier which 3304 the application is requesting to be deleted. The key identifier 3305 must correspond to an existing shared key and must not be in use 3306 for any packet being sent by the SCTP implementation. This means 3307 in particular, that it must be deactivated first. Note if this 3308 parameter is zero, use of the null key identifier '0' is deleted 3309 from the endpoint and/or association. 3311 Only deactivated keys which are no longer used by the association can 3312 be deleted. 3314 7.4. Ancillary Data and Notification Interest Options 3316 Applications can receive per-message ancillary information and 3317 notifications of certain SCTP events with recvmsg(). 3319 The following optional information is available to the application: 3320 SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3321 stream number, TSN, SSN, etc. described in Section 5.2.2) 3322 SCTP_ASSOC_CHANGE (sctp_association_event): described in 3323 Section 5.3.2 3324 SCTP_PEER_ADDR_CHANGE (sctp_address_event): described in 3325 Section 5.3.3 3326 SCTP_SEND_FAILED (sctp_send_failure_event): described in 3327 Section 5.3.5 3328 SCTP_REMOTE_ERROR (sctp_peer_error_event): described in 3329 Section 5.3.4 3330 SCTP_SHUTDOWN_EVENT (sctp_shutdown_event): described in 3331 Section 5.3.6 3332 SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): described 3333 in Section 5.3.8 3334 SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): described 3335 in Section 5.3.7 3336 SCTP_AUTHENTICATION_EVENT (sctp_authentication_event): described in 3337 Section 5.3.9) 3338 SCTP_SENDER_DRY_EVENT (sctp_sender_dry_event): described in 3339 Section 5.3.10 3340 SCTP_NOTIFICATIONS_STOPPED_EVENT (): described in Section 5.3.11 3342 To receive any ancillary data or notifications, first the application 3343 registers its interest by calling the SCTP_EVENTS (deprecated, see 3344 below) setsockopt() with the following structure: 3346 struct sctp_event_subscribe{ 3347 uint8_t sctp_data_io_event; 3348 uint8_t sctp_association_event; 3349 uint8_t sctp_address_event; 3350 uint8_t sctp_send_failure_event; 3351 uint8_t sctp_peer_error_event; 3352 uint8_t sctp_shutdown_event; 3353 uint8_t sctp_partial_delivery_event; 3354 uint8_t sctp_adaptation_layer_event; 3355 uint8_t sctp_authentication_event; 3356 uint8_t sctp_sender_dry_event; 3357 }; 3359 sctp_data_io_event: Setting this flag to 1 will cause the reception 3360 of SCTP_SNDRCV information on a per message basis. The 3361 application will need to use the recvmsg() interface so that it 3362 can receive the event information contained in the msg_control 3363 field. Setting the flag to 0 will disable the reception of the 3364 message control information. 3366 sctp_association_event: Setting this flag to 1 will enable the 3367 reception of association event notifications. Setting the flag to 3368 0 will disable association event notifications. 3369 sctp_address_event: Setting this flag to 1 will enable the reception 3370 of address event notifications. Setting the flag to 0 will 3371 disable address event notifications. 3372 sctp_send_failure_event: Setting this flag to 1 will enable the 3373 reception of send failure event notifications. Setting the flag 3374 to 0 will disable send failure event notifications. 3375 sctp_peer_error_event: Setting this flag to 1 will enable the 3376 reception of peer error event notifications. Setting the flag to 3377 0 will disable peer error event notifications. 3378 sctp_shutdown_event: Setting this flag to 1 will enable the 3379 reception of shutdown event notifications. Setting the flag to 0 3380 will disable shutdown event notifications. 3381 sctp_partial_delivery_event: Setting this flag to 1 will enable the 3382 reception of partial delivery notifications. Setting the flag to 3383 0 will disable partial delivery event notifications. 3384 sctp_adaptation_layer_event: Setting this flag to 1 will enable the 3385 reception of adaptation layer notifications. Setting the flag to 3386 0 will disable adaptation layer event notifications. 3387 sctp_authentication_event: Setting this flag to 1 will enable the 3388 reception of authentication layer notifications. Setting the flag 3389 to 0 will disable authentication layer event notifications. 3390 sctp_sender_dry_event: Setting this flag to 1 will enable the 3391 reception of sender dry notifications. Setting the flag to 0 will 3392 disable sender dry event notifications. 3394 An example where an application would like to receive data io events 3395 and association events but no others would be as follows: 3397 { 3398 struct sctp_event_subscribe events; 3400 memset(&events,0,sizeof(events)); 3402 events.sctp_data_io_event = 1; 3403 events.sctp_association_event = 1; 3405 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); 3406 } 3408 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3409 receives ancillary data and notifications for ALL associations bound 3410 to the file descriptor. For one-to-one style SCTP sockets, the 3411 caller receives ancillary data and notifications only for the single 3412 association bound to the file descriptor. 3414 The SCTP_EVENTS socket option has one issue for future compatibility. 3415 As new features are added the structure (sctp_event_subscribe) must 3416 be expanded. This can cause an ABI issue unless an implementation 3417 has added padding at the end of the structure. To avoid this 3418 problem, SCTP_EVENTS has been deprecated and a new option SCTP_EVENT 3419 socket option has taken its place. The option is used with the 3420 following structure: 3422 struct sctp_event { 3423 sctp_assoc_t se_assoc_id; 3424 uint16_t se_type; 3425 uint8_t se_on; 3426 }; 3428 se_assoc_id: The se_assoc_id field is ignored for one-to-one style 3429 sockets. For one-to-many style sockets any this field can be a 3430 particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. 3431 se_type: The se_type field can be filled with any value that would 3432 show up in the respective sn_type field (in the sctp_tlv structure 3433 of the notification). In addition SCTP_SNDRCV_EVENT, 3434 SCTP_RCV_EVENT, and SCTP_NXT_EVENT can be used. 3435 se_on: The se_on field is set to 1 to turn on an event and set to 0 3436 to turn off an event. 3438 To use this option the user fills in this structure and then calls 3439 the setsockopt to turn on or off an individual event. The following 3440 is an example use of this option: 3442 { 3443 struct sctp_event event; 3445 memset(&event, 0, sizeof(event)); 3447 event.se_assoc_id = SCTP_FUTURE_ASSOC; 3448 event.se_type = SCTP_SENDER_DRY_EVENT; 3449 event.se_on = 1; 3450 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 3451 } 3453 By default both the one-to-one style and the one-to-many style socket 3454 has all options off. 3456 8. New Functions 3458 Depending on the system, the following interface can be implemented 3459 as a system call or library function. 3461 8.1. sctp_bindx() 3463 This function allows the user to bind a specific subset of addresses 3464 or, if the SCTP extension described in [RFC5061] is supported, add or 3465 delete specific addresses. 3467 The function prototype is 3469 int sctp_bindx(int sd, 3470 struct sockaddr *addrs, 3471 int addrcnt, 3472 int flags); 3474 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3475 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3476 or IPv6 addresses. 3478 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3479 Section 3.1.2 for this usage. 3481 addrs is a pointer to an array of one or more socket addresses. Each 3482 address is contained in its appropriate structure. For an IPv6 3483 socket, an array of sockaddr_in6 is used. For a IPv4 socket, an 3484 array of sockaddr_in would is used. The caller specifies the number 3485 of addresses in the array with addrcnt. Note that the wildcard 3486 addresses cannot be used in combination with non wildcard addresses 3487 on a socket with this function, doing so will result in an error. 3489 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3490 -1 and sets errno to the appropriate error code. 3492 For SCTP, the port given in each socket address must be the same, or 3493 sctp_bindx() will fail, setting errno to EINVAL. 3495 The flags parameter is formed from the bitwise OR of zero or more of 3496 the following currently defined flags: 3497 o SCTP_BINDX_ADD_ADDR 3498 o SCTP_BINDX_REM_ADDR 3499 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3500 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3501 addresses from the association. The two flags are mutually 3502 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3503 caller may not remove all addresses from an association; sctp_bindx() 3504 will reject such an attempt with EINVAL. 3506 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3507 additional addresses with an endpoint after calling bind(). Or use 3508 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3509 socket is associated with, so that no new association accepted will 3510 be associated with those addresses. If the endpoint supports dynamic 3511 address reconfiguration an SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR 3512 may cause an endpoint to send the appropriate message to the peer to 3513 change the peer's address lists. 3515 Adding and removing addresses from a connected association is an 3516 optional functionality. Implementations that do not support this 3517 functionality should return EOPNOTSUPP. 3519 sctp_bindx() can be called on an already bound socket or on an 3520 unbound socket. If the socket is unbound and the first port number 3521 in the addrs is zero, the kernel will choose a port number. All port 3522 numbers after the first one being 0 must also be zero. If the first 3523 port number is not zero, the following port numbers must be zero or 3524 have the same value as the first one. For an already bound socket, 3525 all port numbers provided must be the bound one or 0. 3527 sctp_bindx() is an atomic operation. Therefore, the binding will be 3528 either successful on all addresses or fail on all addresses. If 3529 multiple addresses are provided and the sctp_bindx() call fails there 3530 is no indication which address is responsible for the failure. The 3531 only way to get a specific error indication is to call sctp_bindx() 3532 with only one address sequentially. 3534 8.2. sctp_peeloff() 3536 After an association is established on a one-to-many style socket, 3537 the application may wish to branch off the association into a 3538 separate socket/file descriptor. 3540 This is particularly desirable when, for instance, the application 3541 wishes to have a number of sporadic message senders/receivers remain 3542 under the original one-to-many style socket but branch off those 3543 associations carrying high volume data traffic into their own 3544 separate socket descriptors. 3546 The application uses the sctp_peeloff() call to branch off an 3547 association into a separate socket (Note the semantics are somewhat 3548 changed from the traditional one-to-one style accept() call). Note 3549 that the new socket is a one-to-one style socket. Thus it will be 3550 confined to operations allowed for a one-to-one style socket. 3552 The function prototype is 3554 int sctp_peeloff(int sd, 3555 sctp_assoc_t assoc_id); 3557 and the arguments are 3558 sd: The original one-to-many style socket descriptor returned from 3559 the socket() system call (see Section 3.1.1). 3560 assoc_id: the specified identifier of the association that is to be 3561 branched off to a separate file descriptor (Note, in a traditional 3562 one-to-one style accept() call, this would be an out parameter, 3563 but for the one-to-many style call, this is an in parameter). 3564 The function returns a non-negative file descriptor representing the 3565 branched-off association, or -1 if an error occurred. The variable 3566 errno is then set appropriately. 3568 8.3. sctp_getpaddrs() 3570 sctp_getpaddrs() returns all peer addresses in an association. 3572 The function protoype is: 3574 int sctp_getpaddrs(int sd, 3575 sctp_assoc_t id, 3576 struct sockaddr **addrs); 3578 On return, addrs will point to an array dynamically allocated 3579 sockaddr structures of the appropriate type for the socket type. The 3580 caller should use sctp_freepaddrs() to free the memory. Note that 3581 the in/out parameter addrs must not be NULL. 3583 If sd is an IPv4 socket, the addresses returned will be all IPv4 3584 addresses. If sd is an IPv6 socket, the addresses returned can be a 3585 mix of IPv4 or IPv6 addresses. 3587 For one-to-many style sockets, id specifies the association to query. 3588 For one-to-one style sockets, id is ignored. 3590 On success, sctp_getpaddrs() returns the number of peer addresses in 3591 the association. If there is no association on this socket, 3592 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3593 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3594 is undefined. 3596 8.4. sctp_freepaddrs() 3598 sctp_freepaddrs() frees all resources allocated by sctp_getpaddrs(). 3600 The function prototype is 3602 void sctp_freepaddrs(struct sockaddr *addrs); 3604 and addrs is the array of peer addresses returned by 3605 sctp_getpaddrs(). 3607 8.5. sctp_getladdrs() 3609 sctp_getladdrs() returns all locally bound address(es) on a socket. 3611 The function prototype is 3613 int sctp_getladdrs(int sd, 3614 sctp_assoc_t id, 3615 struct sockaddr **ss); 3617 On return, addrs will point to a dynamically allocated array of 3618 sockaddr structures of the appropriate type for the socket type. The 3619 caller should use sctp_freeladdrs() to free the memory. Note that 3620 the in/out parameter addrs must not be NULL. 3622 If sd is an IPv4 socket, the addresses returned will be all IPv4 3623 addresses. If sd is an IPv6 socket, the addresses returned can be a 3624 mix of IPv4 or IPv6 addresses. 3626 For one-to-many style sockets, id specifies the association to query. 3627 For one-to-one style sockets, id is ignored. 3629 If the id field is set to the value '0' then the locally bound 3630 addresses are returned without regard to any particular association. 3632 On success, sctp_getladdrs() returns the number of local addresses 3633 bound to the socket. If the socket is unbound, sctp_getladdrs() 3634 returns 0, and the value of *addrs is undefined. If an error occurs, 3635 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3637 8.6. sctp_freeladdrs() 3639 sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). 3641 The function prototype is 3643 void sctp_freeladdrs(struct sockaddr *addrs); 3645 and addrs is the array of peer addresses returned by 3646 sctp_getladdrs(). 3648 8.7. sctp_sendmsg() 3650 An implementation may provide a library function (or possibly system 3651 call) to assist the user with the advanced features of SCTP. 3653 The function prototype is 3655 ssize_t sctp_sendmsg(int sd, 3656 const void *msg, 3657 size_t len, 3658 const struct sockaddr *to, 3659 socklen_t tolen, 3660 uint32_t ppid, 3661 uint32_t flags, 3662 uint16_t stream_no, 3663 uint32_t pr_value, 3664 uint32_t context); 3666 and the arguments are: 3667 sd: The socket descriptor 3668 msg: The message to be sent. 3669 len: The length of the message. 3670 to: The destination address of the message. 3671 tolen: The length of the destination address. 3672 ppid: The same as sinfo_ppid (see Section 5.2.2) 3673 flags: The same as sinfo_flags (see Section 5.2.2) 3674 stream_no: The same as sinfo_stream (see Section 5.2.2) 3675 pr_value: The same as sinfo_pr_value (see Section 5.2.2). 3676 context: The same as sinfo_context (see Section 5.2.2) 3677 The call returns the number of characters sent, or -1 if an error 3678 occurred. The variable errno is then set appropriately. 3680 Sending a message using sctp_sendmsg() is atomic (unless explicit EOR 3681 marking is enabled on the socket specified by sd). 3683 Using sctp_sendmsg() on a non-connected one-to-one style socket for 3684 implicit connection setup may or may not work depending on the SCTP 3685 implementation. 3687 8.8. sctp_recvmsg() 3689 An implementation may provide a library function (or possibly system 3690 call) to assist the user with the advanced features of SCTP. Note 3691 that in order for the sctp_sndrcvinfo structure to be filled in by 3692 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3693 the SCTP_EVENTS option. Note that the setting of the 3694 SCTP_USE_EXT_RCVINFO will affect this function as well, causing the 3695 sctp_sndrcvinfo information to be extended. 3697 The function prototype is 3698 ssize_t sctp_recvmsg(int sd, 3699 void *msg, 3700 size_t len, 3701 struct sockaddr *from, 3702 socklen_t *fromlen 3703 struct sctp_sndrcvinfo *sinfo 3704 int *msg_flags); 3706 and the arguments are 3707 sd: The socket descriptor. 3708 msg: The message buffer to be filled. 3709 len: The length of the message buffer. 3710 from: A pointer to an address to be filled with the sender of this 3711 messages address. 3712 fromlen: An in/out parameter describing the from length. 3713 sinfo: A pointer to an sctp_sndrcvinfo structure to be filled upon 3714 receipt of the message. 3715 msg_flags: A pointer to an integer to be filled with any message 3716 flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out 3717 field. Options for the receive may also be passed into the value 3718 (e.g. MSG_PEEK). On return from the call, the msg_flags value 3719 will be different than what was sent in to the call. If 3720 implemented via a recvmsg() call, the msg_flags should only 3721 contain the value of the flags from the recvmsg() call. 3722 The call returns the number of bytes received, or -1 if an error 3723 occurred. The variable errno is then set appropriately. 3725 8.9. sctp_connectx() 3727 An implementation may provide a library function (or possibly system 3728 call) to assist the user with associating to an endpoint that is 3729 multi-homed. Much like sctp_bindx() this call allows a caller to 3730 specify multiple addresses at which a peer can be reached. The way 3731 the SCTP stack uses the list of addresses to set up the association 3732 is implementation dependent. This function only specifies that the 3733 stack will try to make use of all the addresses in the list when 3734 needed. 3736 Note that the list of addresses passed in is only used for setting up 3737 the association. It does not necessarily equal the set of addresses 3738 the peer uses for the resulting association. If the caller wants to 3739 find out the set of peer addresses, it must use sctp_getpaddrs() to 3740 retrieve them after the association has been set up. 3742 The function prototype is 3743 int sctp_connectx(int sd, 3744 struct sockaddr *addrs, 3745 int addrcnt, 3746 sctp_assoc_t *id); 3748 and the arguments are: 3749 sd: The socket descriptor. 3750 addrs: An (packed) array of addresses. 3751 addrcnt: The number of addresses in the array. 3752 id: An output parameter that if passed in as a non-NULL will return 3753 the association identification for the newly created association 3754 (if successful). 3756 The call returns 0 on success or -1 if an error occurred. The 3757 variable errno is then set appropriately. 3759 8.10. sctp_send() 3761 An implementation may provide another alternative function or system 3762 call to assist an application with the sending of data without the 3763 use of the CMSG header structures. 3765 The function prototype is 3767 ssize_t sctp_send(int sd, 3768 const void *msg, 3769 size_t len, 3770 const struct sctp_sndrcvinfo *sinfo, 3771 int flags); 3773 and the arguments are 3774 sd: The socket descriptor. 3775 msg: The message to be sent. 3776 len: The length of the message. 3777 sinfo: A pointer to an sctp_sndrcvinfo structure used as described 3778 in Section 5.2.2 for a sendmsg call. 3779 flags: The same flags as used by the sendmsg call flags (e.g. 3780 MSG_DONTROUTE). 3781 The call returns the number of bytes sent, or -1 if an error 3782 occurred. The variable errno is then set appropriately. 3784 This function call may also be used to terminate an association using 3785 an association identification by setting the sinfo.sinfo_flags to 3786 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3787 to be terminated. In such a case the len of the message would be 3788 zero. 3790 Using sctp_send() on a non-connected one-to-one style socket for 3791 implicit connection setup may or may not work depending on the SCTP 3792 implementation. 3794 Sending a message using sctp_send() is atomic unless explicit EOR 3795 marking is enabled on the socket specified by sd. 3797 8.11. sctp_sendx() 3799 An implementation may provide another alternative function or system 3800 call to assist an application with the sending of data without the 3801 use of the CMSG header structures that also gives a list of 3802 addresses. The list of addresses is provided for implicit 3803 association setup. In such a case the list of addresses serves the 3804 same purpose as the addresses given in sctp_connectx() (see 3805 Section 8.9). 3807 The function prototype is 3809 ssize_t sctp_sendx(int sd, 3810 const void *msg, 3811 size_t len, 3812 struct sockaddr *addrs, 3813 int addrcnt, 3814 struct sctp_sndrcvinfo *sinfo, 3815 int flags); 3817 and the arguments are: 3818 sd: The socket descriptor. 3819 msg: The message to be sent. 3820 len: The length of the message. 3821 addrs: is an array of addresses. 3822 addrcnt: The number of addresses in the array. 3823 sinfo: A pointer to a sctp_sndrcvinfo structure used as described in 3824 Section 5.2.2 for a sendmsg call. 3825 flags: The same flags as used by the sendmsg call flags (e.g. 3826 MSG_DONTROUTE). 3827 The call returns the number of bytes sent, or -1 if an error 3828 occurred. The variable errno is then set appropriately. 3830 Note that on return from this call the sinfo structure will have 3831 changed in that the sinfo_assoc_id will be filled in with the new 3832 association id. 3834 This function call may also be used to terminate an association using 3835 an association identification by setting the sinfo.sinfo_flags to 3836 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3837 to be terminated. In such a case the len of the message would be 3838 zero. 3840 Sending a message using sctp_send() is atomic unless explicit EOR 3841 marking is enabled on the socket specified by sd. 3843 Using sctp_sendx() on a non-connected one-to-one style socket for 3844 implicit connection setup may or may not work depending on the SCTP 3845 implementation. 3847 8.12. sctp_getaddrlen() 3849 For application binary portability it is sometimes desirable to know 3850 what the kernel thinks is the length of a socket address family. 3852 The function prototype is: 3854 int sctp_getaddrlen(sa_family_t family); 3856 This function, when called with a valid family type returns the 3857 length that the operating system uses in the specified family's 3858 socket address structure. In case of an error, -1 is returned and 3859 the variable errno is then set appropriately. 3861 9. IANA Considerations 3863 This document requires no actions from IANA. 3865 10. Security Considerations 3867 Many TCP and UDP implementations reserve port numbers below 1024 for 3868 privileged users. If the target platform supports privileged users, 3869 the SCTP implementation should restrict the ability to call bind() or 3870 sctp_bindx() on these port numbers to privileged users. 3872 Similarly unprivileged users should not be able to set protocol 3873 parameters which could result in the congestion control algorithm 3874 being more aggressive than permitted on the public Internet. These 3875 parameters are: 3876 o struct sctp_rtoinfo 3878 If an unprivileged user inherits a one-to-many style socket with open 3879 associations on a privileged port, it may be permitted to accept new 3880 associations, but it should not be permitted to open new 3881 associations. This could be relevant for the r* family of protocols. 3883 Applications using the one-to-many style sockets and using the 3884 interleave level if 0 are subject to denial of service attacks as 3885 described in Section 7.1.20. 3887 11. Acknowledgments 3889 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 3890 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 3891 early formation of this document. 3893 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 3894 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 3895 Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG 3896 mailing list for contributing valuable comments. 3898 A special thanks to Phillip Conrad, for his suggested text, quick and 3899 constructive insights, and most of all his persistent fighting to 3900 keep the interface to SCTP usable for the application programmer. 3902 12. Normative References 3904 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3905 RFC 793, September 1981. 3907 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 3908 August 1980. 3910 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 3911 Functional Specification", RFC 1644, July 1994. 3913 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 3914 Stevens, "Basic Socket Interface Extensions for IPv6", 3915 RFC 3493, February 2003. 3917 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 3918 "Advanced Sockets Application Program Interface (API) for 3919 IPv6", RFC 3542, May 2003. 3921 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 3922 Conrad, "Stream Control Transmission Protocol (SCTP) 3923 Partial Reliability Extension", RFC 3758, May 2004. 3925 [RFC4895] Tuexen, M., Stewart, R., Lei, P., and E. Rescorla, 3926 "Authenticated Chunks for the Stream Control Transmission 3927 Protocol (SCTP)", RFC 4895, August 2007. 3929 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 3930 RFC 4960, September 2007. 3932 [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. 3933 Kozuka, "Stream Control Transmission Protocol (SCTP) 3934 Dynamic Address Reconfiguration", RFC 5061, 3935 September 2007. 3937 Appendix A. One-to-One Style Code Example 3939 The following code is a simple implementation of an echo server over 3940 SCTP. The example shows how to use some features of one-to-one style 3941 IPv4 SCTP sockets, including: 3942 o Opening, binding, and listening for new associations on a socket 3943 o Enabling ancillary data 3944 o Enabling notifications 3945 o Using ancillary data with sendmsg() and recvmsg() 3946 o Using MSG_EOR to determine if an entire message has been read 3947 o Handling notifications 3949 #include 3950 #include 3951 #include 3952 #include 3953 #include 3954 #include 3955 #include 3956 #include 3957 #include 3959 #define BUFLEN 100 3961 static void 3962 handle_event(void *buf) 3963 { 3964 struct sctp_assoc_change *sac; 3965 struct sctp_send_failed *ssf; 3966 struct sctp_paddr_change *spc; 3967 struct sctp_remote_error *sre; 3968 union sctp_notification *snp; 3969 char addrbuf[INET6_ADDRSTRLEN]; 3970 const char *ap; 3971 struct sockaddr_in *sin; 3972 struct sockaddr_in6 *sin6; 3974 snp = buf; 3976 switch (snp->sn_header.sn_type) { 3977 case SCTP_ASSOC_CHANGE: 3978 sac = &snp->sn_assoc_change; 3979 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3980 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3981 sac->sac_inbound_streams, sac->sac_outbound_streams); 3982 break; 3983 case SCTP_SEND_FAILED: 3984 ssf = &snp->sn_send_failed; 3985 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3986 ssf->ssf_error); 3987 break; 3989 case SCTP_PEER_ADDR_CHANGE: 3990 spc = &snp->sn_paddr_change; 3991 if (spc->spc_aaddr.ss_family == AF_INET) { 3992 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3993 ap = inet_ntop(AF_INET, &sin->sin_addr, 3994 addrbuf, INET6_ADDRSTRLEN); 3995 } else { 3996 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3997 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3998 addrbuf, INET6_ADDRSTRLEN); 3999 } 4000 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 4001 spc->spc_state, spc->spc_error); 4002 break; 4003 case SCTP_REMOTE_ERROR: 4004 sre = &snp->sn_remote_error; 4005 printf("^^^ remote_error: err=%hu len=%hu\n", 4006 ntohs(sre->sre_error), ntohs(sre->sre_length)); 4007 break; 4008 case SCTP_SHUTDOWN_EVENT: 4009 printf("^^^ shutdown event\n"); 4010 break; 4011 default: 4012 printf("unknown type: %hu\n", snp->sn_header.sn_type); 4013 break; 4014 }; 4015 } 4017 static void * 4018 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 4019 ssize_t *nrp, size_t cmsglen) 4020 { 4021 ssize_t nr = 0, nnr = 0; 4022 struct iovec iov; 4024 *nrp = 0; 4025 iov.iov_base = buf; 4026 iov.iov_len = *buflen; 4027 msg->msg_iov = � 4028 msg->msg_iovlen = 1; 4029 for (;;) { 4030 #ifndef MSG_XPG4_2 4031 #define MSG_XPG4_2 0 4032 #endif 4033 msg->msg_flags = MSG_XPG4_2; 4034 msg->msg_controllen = cmsglen; 4036 nnr = recvmsg(fd, msg, 0); 4037 if (nnr <= 0) { 4038 /* EOF or error */ 4039 *nrp = nr; 4040 return (NULL); 4041 } 4042 nr += nnr; 4044 if ((msg->msg_flags & MSG_EOR) != 0) { 4045 *nrp = nr; 4046 return (buf); 4047 } 4049 /* Realloc the buffer? */ 4050 if (*buflen == (size_t)nr) { 4051 buf = realloc(buf, *buflen * 2); 4052 if (buf == 0) { 4053 fprintf(stderr, "out of memory\n"); 4054 exit(1); 4055 } 4056 *buflen *= 2; 4057 } 4058 /* Set the next read offset */ 4059 iov.iov_base = (char *)buf + nr; 4060 iov.iov_len = *buflen - nr; 4061 } 4062 } 4064 static void 4065 echo(int fd, int socketModeone_to_many) 4066 { 4067 ssize_t nr; 4068 struct sctp_sndrcvinfo *sri; 4069 struct msghdr msg; 4070 struct cmsghdr *cmsg; 4071 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 4072 char *buf; 4073 size_t buflen; 4074 struct iovec iov; 4075 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 4076 /* Allocate the initial data buffer */ 4077 buflen = BUFLEN; 4078 if (!(buf = malloc(BUFLEN))) { 4079 fprintf(stderr, "out of memory\n"); 4080 exit(1); 4081 } 4083 /* Set up the msghdr structure for receiving */ 4084 memset(&msg, 0, sizeof (msg)); 4085 msg.msg_control = cbuf; 4086 msg.msg_controllen = cmsglen; 4087 msg.msg_flags = 0; 4088 cmsg = (struct cmsghdr *)cbuf; 4089 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 4091 /* Wait for something to echo */ 4092 while (buf = mysctp_recvmsg(fd, &msg, 4093 buf, &buflen, &nr, cmsglen)) { 4095 /* Intercept notifications here */ 4096 if (msg.msg_flags & MSG_NOTIFICATION) { 4097 handle_event(buf); 4098 continue; 4099 } 4101 iov.iov_base = buf; 4102 iov.iov_len = nr; 4103 msg.msg_iov = � 4104 msg.msg_iovlen = 1; 4106 printf("got %u bytes on stream %hu:\n", nr, 4107 sri->sinfo_stream); 4108 write(0, buf, nr); 4110 /* Echo it back */ 4111 msg.msg_flags = MSG_XPG4_2; 4112 if (sendmsg(fd, &msg, 0) < 0) { 4113 perror("sendmsg"); 4114 exit(1); 4115 } 4116 } 4118 if (nr < 0) { 4119 perror("recvmsg"); 4120 } 4121 if(socketModeone_to_many == 0) 4122 close(fd); 4123 } 4124 int main() 4125 { 4126 struct sctp_event_subscribe event; 4127 int lfd, cfd; 4128 int onoff = 1; 4129 struct sockaddr_in sin; 4130 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 4131 perror("socket"); 4132 exit(1); 4133 } 4135 sin.sin_family = AF_INET; 4136 sin.sin_port = htons(7); 4137 sin.sin_addr.s_addr = INADDR_ANY; 4138 if (bind(lfd, (struct sockaddr *)&sin, sizeof (sin)) == -1) { 4139 perror("bind"); 4140 exit(1); 4141 } 4143 if (listen(lfd, 1) == -1) { 4144 perror("listen"); 4145 exit(1); 4146 } 4148 /* Wait for new associations */ 4149 for (;;) { 4150 if ((cfd = accept(lfd, NULL, 0)) == -1) { 4151 perror("accept"); 4152 exit(1); 4153 } 4155 /* Enable all events */ 4156 event.sctp_data_io_event = 1; 4157 event.sctp_association_event = 1; 4158 event.sctp_address_event = 1; 4159 event.sctp_send_failure_event = 1; 4160 event.sctp_peer_error_event = 1; 4161 event.sctp_shutdown_event = 1; 4162 event.sctp_partial_delivery_event = 1; 4163 event.sctp_adaptation_layer_event = 1; 4164 if (setsockopt(cfd, IPPROTO_SCTP, 4165 SCTP_EVENTS, &event, 4166 sizeof(event)) != 0) { 4167 perror("setevent failed"); 4168 exit(1); 4169 } 4170 /* Echo back any and all data */ 4171 echo(cfd,0); 4173 } 4174 } 4176 Appendix B. One-to-Many Style Code Example 4178 The following code is a simple implementation of an echo server over 4179 SCTP. The example shows how to use some features of one-to-many 4180 style IPv4 SCTP sockets, including: 4181 o Opening and binding of a socket 4182 o Enabling ancillary data 4183 o Enabling notifications 4184 o Using ancillary data with sendmsg() and recvmsg() 4185 o Using MSG_EOR to determine if an entire message has been read 4186 o Handling notifications 4188 Note most functions defined in Appendix A are reused in this example. 4190 int main() 4191 { 4192 int fd; 4193 int idleTime = 2; 4194 struct sockaddr_in sin; 4195 struct sctp_event_subscribe event; 4197 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 4198 perror("socket"); 4199 exit(1); 4200 } 4202 sin.sin_family = AF_INET; 4203 sin.sin_port = htons(7); 4204 sin.sin_addr.s_addr = INADDR_ANY; 4205 if (bind(fd, (struct sockaddr *)&sin, sizeof (sin)) == -1) { 4206 perror("bind"); 4207 exit(1); 4208 } 4210 /* Enable all notifications and events */ 4211 event.sctp_data_io_event = 1; 4212 event.sctp_association_event = 1; 4213 event.sctp_address_event = 1; 4214 event.sctp_send_failure_event = 1; 4215 event.sctp_peer_error_event = 1; 4216 event.sctp_shutdown_event = 1; 4217 event.sctp_partial_delivery_event = 1; 4218 event.sctp_adaptation_layer_event = 1; 4219 if (setsockopt(fd, IPPROTO_SCTP, 4220 SCTP_EVENTS, &event, 4221 sizeof(event)) != 0) { 4222 perror("setevent failed"); 4223 exit(1); 4224 } 4225 /* Set associations to auto-close in 2 seconds of 4226 * inactivity 4227 */ 4228 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 4229 &idleTime, 4) < 0) { 4230 perror("setsockopt SCTP_AUTOCLOSE"); 4231 exit(1); 4232 } 4234 /* Allow new associations to be accepted */ 4235 if (listen(fd, 1) < 0) { 4236 perror("listen"); 4237 exit(1); 4238 } 4240 /* Wait for new associations */ 4241 while(1){ 4242 /* Echo back any and all data */ 4243 echo(fd,1); /* from appendix a */ 4244 } 4245 } 4247 Authors' Addresses 4249 Randall R. Stewart 4250 Huawei 4251 Chapin, SC 29036 4252 USA 4254 Email: rstewart@huawei.com 4256 Kacheong Poon 4257 Sun Microsystems, Inc. 4258 4150 Network Circle 4259 Santa Clara, CA 95054 4260 USA 4262 Email: kacheong.poon@sun.com 4263 Michael Tuexen 4264 Muenster Univ. of Applied Sciences 4265 Stegerwaldstr. 39 4266 48565 Steinfurt 4267 Germany 4269 Email: tuexen@fh-muenster.de 4271 Vladislav Yasevich 4272 HP 4273 110 Spitrook Rd 4274 Nashua, NH, 03062 4275 USA 4277 Email: vladislav.yasevich@hp.com 4279 Peter Lei 4280 Cisco Systems, Inc. 4281 8735 West Higgins Road 4282 Suite 300 4283 Chicago, IL 60631 4284 USA 4286 Email: peterlei@cisco.com