idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 22. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 4151. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4162. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4169. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4175. 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 Copyright Line does not match the current year == Line 1385 has weird spacing: '...n_event sn_s...' == Line 1388 has weird spacing: '...y_event sn_...' == Line 1389 has weird spacing: '...h_event sn_...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 14, 2008) is 5765 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 ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 4039 ** 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 (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft The Resource Group 4 Intended status: Informational K. Poon 5 Expires: January 15, 2009 Sun Microsystems, Inc. 6 M. Tuexen 7 Univ. of Applied Sciences Muenster 8 V. Yasevich 9 HP 10 P. Lei 11 Cisco Systems, Inc. 12 July 14, 2008 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-17.txt 17 Status of this Memo 19 By submitting this Internet-Draft, each author represents that any 20 applicable patent or other IPR claims of which he or she is aware 21 have been or will be disclosed, and any of which he or she becomes 22 aware will be disclosed, in accordance with Section 6 of BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on January 15, 2009. 42 Abstract 44 This document describes a mapping of the Stream Control Transmission 45 Protocol SCTP into a sockets API. The benefits of this mapping 46 include compatibility for TCP applications, access to new SCTP 47 features and a consolidated error and event notification scheme. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 52 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6 53 3. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 6 54 4. one-to-many style Interface . . . . . . . . . . . . . . . . . 6 55 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6 56 4.1.1. socket() - one-to-many style socket . . . . . . . . . 8 57 4.1.2. bind() - one-to-many style socket . . . . . . . . . . 8 58 4.1.3. listen() - One-to-many style socket . . . . . . . . . 9 59 4.1.4. sendmsg() and recvmsg() - one-to-many style socket . . 10 60 4.1.5. close() - one-to-many style socket . . . . . . . . . . 11 61 4.1.6. connect() - one-to-many style socket . . . . . . . . . 12 62 4.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12 63 4.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 64 4.4. Special considerations . . . . . . . . . . . . . . . . . . 14 65 5. one-to-one style Interface . . . . . . . . . . . . . . . . . . 15 66 5.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 16 67 5.1.1. socket() - one-to-one style socket . . . . . . . . . . 16 68 5.1.2. bind() - one-to-one style socket . . . . . . . . . . . 17 69 5.1.3. listen() - one-to-one style socket . . . . . . . . . . 18 70 5.1.4. accept() - one-to-one style socket . . . . . . . . . . 18 71 5.1.5. connect() - one-to-one style socket . . . . . . . . . 19 72 5.1.6. close() - one-to-one style socket . . . . . . . . . . 20 73 5.1.7. shutdown() - one-to-one style socket . . . . . . . . . 20 74 5.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 21 75 5.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 21 76 6. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21 77 6.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 22 78 6.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 23 79 6.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 24 80 6.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 25 81 6.2.3. Extended SCTP Header Information Structure 82 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 28 83 6.3. SCTP Events and Notifications . . . . . . . . . . . . . . 29 84 6.3.1. SCTP Notification Structure . . . . . . . . . . . . . 30 85 6.4. Ancillary Data Considerations and Semantics . . . . . . . 42 86 6.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 42 87 6.4.2. Accessing and Manipulating Ancillary Data . . . . . . 43 88 6.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 43 89 7. Common Operations for Both Styles . . . . . . . . . . . . . . 44 90 7.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 44 91 7.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 46 92 7.3. read() and write() . . . . . . . . . . . . . . . . . . . . 46 93 7.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 46 94 8. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 47 95 8.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 49 96 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 49 97 8.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 49 98 8.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 51 99 8.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 51 100 8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 51 101 8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 52 102 8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 52 103 8.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 52 104 8.1.9. Set Peer Primary Address 105 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 52 106 8.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 53 107 8.1.11. Set Adaptation Layer Indicator 108 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 53 109 8.1.12. Enable/Disable message fragmentation 110 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 54 111 8.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 54 112 8.1.14. Set default send parameters 113 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 56 114 8.1.15. Set notification and ancillary events (SCTP_EVENTS) . 57 115 8.1.16. Set/clear IPv4 mapped addresses 116 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 57 117 8.1.17. Get or set the maximum fragmentation size 118 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 57 119 8.1.18. Add a chunk that must be authenticated 120 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 58 121 8.1.19. Get or set the list of supported HMAC Identifiers 122 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 58 123 8.1.20. Set a shared key (SCTP_AUTH_KEY) . . . . . . . . . . . 59 124 8.1.21. Get or set the active shared key 125 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 59 126 8.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) . . . . . . 60 127 8.1.23. Delete a shared key (SCTP_AUTH_DEACTIVATE_KEY) . . . . 61 128 8.1.24. Get or set delayed ack timer (SCTP_DELAYED_SACK) . . . 61 129 8.1.25. Get or set fragmented interleave 130 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 62 131 8.1.26. Set or Get the sctp partial delivery point 132 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 63 133 8.1.27. Set or Get the use of extended receive info 134 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 64 135 8.1.28. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) . . 64 136 8.1.29. Set or Get the maximum burst (SCTP_MAX_BURST) . . . . 64 137 8.1.30. Set or Get the default context (SCTP_CONTEXT) . . . . 65 138 8.1.31. Enable or disable explicit EOR marking 139 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 65 140 8.1.32. Enable SCTP port reusage (SCTP_REUSE_PORT) . . . . . . 65 141 8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 66 142 8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 66 143 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 67 144 8.2.3. Get the list of chunks the peer requires to be 145 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 68 146 8.2.4. Get the list of chunks the local endpoint requires 147 to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 69 148 8.2.5. Get the current number of associations 149 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 69 150 8.2.6. Get the current identifiers of associations 151 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 69 152 8.3. Ancillary Data and Notification Interest Options . . . . . 70 153 9. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 72 154 9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 72 155 9.2. Branched-off Association . . . . . . . . . . . . . . . . . 74 156 9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 74 157 9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 75 158 9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 75 159 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 76 160 9.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 76 161 9.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 77 162 9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 77 163 9.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 78 164 9.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 79 165 9.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 80 166 10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 80 167 11. Security Considerations . . . . . . . . . . . . . . . . . . . 80 168 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 81 169 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 81 170 14. Normative references . . . . . . . . . . . . . . . . . . . . . 81 171 Appendix A. one-to-one style Code Example . . . . . . . . . . . . 82 172 Appendix B. one-to-many style Code Example . . . . . . . . . . . 87 173 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 89 174 Intellectual Property and Copyright Statements . . . . . . . . . . 91 176 1. Introduction 178 The sockets API has provided a standard mapping of the Internet 179 Protocol suite to many operating systems. Both TCP [RFC0793] and UDP 180 [RFC0768] have benefited from this standard representation and access 181 method across many diverse platforms. SCTP is a new protocol that 182 provides many of the characteristics of TCP but also incorporates 183 semantics more akin to UDP. This document defines a method to map 184 the existing sockets API for use with SCTP, providing both a base for 185 access to new features and compatibility so that most existing TCP 186 applications can be migrated to SCTP with few (if any) changes. 188 There are three basic design objectives: 190 1) Maintain consistency with existing sockets APIs: 191 We define a sockets mapping for SCTP that is consistent with other 192 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 193 IPv6). 194 2) Support a one-to-many style interface 195 This set of semantics is similar to that defined for connection- 196 less protocols, such as UDP. A one-to-many style SCTP socket 197 should be able to control multiple SCTP associations. This is 198 similar to an UDP socket, which can communicate with many peer end 199 points. Each of these associations is assigned an association ID 200 so that an applications can use the ID to differentiate them. 201 Note that SCTP is connection-oriented in nature, and it does not 202 support broadcast or multicast communications, as UDP does. 203 3) Support a one-to-one style interface 204 This interface supports a similar semantics as sockets for 205 connection-oriented protocols, such as TCP. A one-to-one style 206 SCTP socket should only control one SCTP association. 207 One purpose of defining this interface is to allow existing 208 applications built on other connection-oriented protocols be 209 ported to use SCTP with very little effort. And developers 210 familiar with those semantics can easily adapt to SCTP. Another 211 purpose is to make sure that existing mechanisms in most OSes to 212 deal with socket, such as select(), should continue to work with 213 this style of socket. 214 Extensions are added to this mapping to provide mechanisms to 215 exploit new features of SCTP. 217 Goals 2 and 3 are not compatible, so in this document we define two 218 modes of mapping, namely the one-to-many style mapping and the one- 219 to-one style mapping. These two modes share some common data 220 structures and operations, but will require the use of two different 221 application programming styles. Note that all new SCTP features can 222 be used with both styles of socket. The decision on which one to use 223 depends mainly on the nature of applications. 225 A mechanism is defined to extract a one-to-many style SCTP 226 association into a one-to-one style socket. 228 Some of the SCTP mechanisms cannot be adequately mapped to existing 229 socket interface. In some cases, it is more desirable to have new 230 interface instead of using existing socket calls. Section 9 of this 231 document describes those new interface. 233 2. Conventions 235 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 236 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 237 document are to be interpreted as described in [RFC2119]. 239 3. Data Types 241 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 242 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 243 (e.g., uint16_t). We also assume the argument data types from 244 1003.1g when possible (e.g., the final argument to setsockopt() is a 245 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 246 size_t data type is used. 248 4. one-to-many style Interface 250 The one-to-many style interface has the following characteristics: 252 A) Outbound association setup is implicit. 254 B) Messages are delivered in complete messages (with one notable 255 exception). 257 C) There is a 1 to MANY relationship between socket and association. 259 4.1. Basic Operation 261 A typical server in this style uses the following socket calls in 262 sequence to prepare an endpoint for servicing requests: 264 1. socket() 265 2. bind() 266 3. listen() 267 4. recvmsg() 268 5. sendmsg() 269 6. close() 271 A typical client uses the following calls in sequence to setup an 272 association with a server to request services: 274 1. socket() 275 2. sendmsg() 276 3. recvmsg() 277 4. close() 279 In this style, by default, all the associations connected to the 280 endpoint are represented with a single socket. Each associations is 281 assigned an association ID (type is sctp_assoc_t) so that an 282 application can use it to differentiate between them. In some 283 implementations, the peer endpoints addresses can also be used for 284 this purpose. But this is not required for performance reasons. If 285 an implementation does not support using addresses to differentiate 286 between different associations, the sendto() call can only be used to 287 setup an association implicitly. It cannot be used to send data to 288 an established association as the association ID cannot be specified. 290 Once as association ID is assigned to an SCTP association, that ID 291 will not be reused until the application explicitly terminates the 292 association. The resources belonged to that association will not be 293 freed until that happens. This is similar to the close() operation 294 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 295 option (section 7.1.8) is set. In this case, after the association 296 is terminated gracefully automatically, the association ID assigned 297 to it can be reused. All applications using this option should be 298 aware of this to avoid the possible problem of sending data to an 299 incorrect peer end point. 301 If the server or client wishes to branch an existing association off 302 to a separate socket, it is required to call sctp_peeloff() and in 303 the parameter specifies the association identification. The 304 sctp_peeloff() call will return a new socket which can then be used 305 with recv() and send() functions for message passing. See 306 Section 9.2 for more on branched-off associations. 308 Once an association is branched off to a separate socket, it becomes 309 completely separated from the original socket. All subsequent 310 control and data operations to that association must be done through 311 the new socket. For example, the close operation on the original 312 socket will not terminate any associations that have been branched 313 off to a different socket. 315 We will discuss the one-to-many style socket calls in more details in 316 the following subsections. 318 4.1.1. socket() - one-to-many style socket 320 Applications use socket() to create a socket descriptor to represent 321 an SCTP endpoint. 323 The syntax is, 325 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 327 or, 329 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 331 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 332 socket. 334 The first form creates an endpoint which can use only IPv4 addresses, 335 while, the second form creates an endpoint which can use both IPv6 336 and IPv4 addresses. 338 4.1.2. bind() - one-to-many style socket 340 Applications use bind() to specify which local address the SCTP 341 endpoint should associate itself with. 343 An SCTP endpoint can be associated with multiple addresses. To do 344 this, sctp_bindx() is introduced in section Section 9.1 to help 345 applications do the job of associating multiple addresses. 347 These addresses associated with a socket are the eligible transport 348 addresses for the endpoint to send and receive data. The endpoint 349 will also present these addresses to its peers during the association 350 initialization process, see [RFC4960]. 352 After calling bind(), if the endpoint wishes to accept new 353 associations on the socket, it must call listen() (see section 354 Section 4.1.3). 356 The syntax of bind() is, 358 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 359 sd - the socket descriptor returned by socket(). 360 addr - the address structure (struct sockaddr_in or struct 361 sockaddr_in6 [RFC3493]). 362 addrlen - the size of the address structure. 364 If sd is an IPv4 socket, the address passed must be an IPv4 address. 365 If the sd is an IPv6 socket, the address passed can either be an IPv4 366 or an IPv6 address. 368 Applications cannot call bind() multiple times to associate multiple 369 addresses to an endpoint. After the first call to bind(), all 370 subsequent calls will return an error. 372 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 373 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 374 operating system will associate the endpoint with an optimal address 375 set of the available interfaces. 377 If a bind() is not called prior to a sendmsg() call that initiates a 378 new association, the system picks an ephemeral port and will choose 379 an address set equivalent to binding with a wildcard address. One of 380 those addresses will be the primary address for the association. 381 This automatically enables the multi-homing capability of SCTP. 383 4.1.3. listen() - One-to-many style socket 385 By default, new associations are not accepted for one-to-many style 386 sockets. An application uses listen() to mark a socket as being able 387 to accept new associations. The syntax is, 389 int listen(int sd, int backlog); 391 sd - the socket descriptor of the endpoint. 392 backlog - if backlog is non-zero, enable listening else disable 393 listening. 395 Note that one-to-many style socket consumers do not need to call 396 accept to retrieve new associations. Calling accept() on a one-to- 397 many style socket should return EOPNOTSUPP. Rather, new associations 398 are accepted automatically, and notifications of the new associations 399 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 400 these notifications are enabled). Clients will typically not call 401 listen(), so that they can be assured that the only associations on 402 the socket will be ones they actively initiated. Server or peer-to- 403 peer sockets, on the other hand, will always accept new associations, 404 so a well-written application using server one-to-many style sockets 405 must be prepared to handle new associations from unwanted peers. 407 Also note that the SCTP_ASSOC_CHANGE event provides the association 408 ID for a new association, so if applications wish to use the 409 association ID as input to other socket calls, they should ensure 410 that the SCTP_ASSOC_CHANGE event is enabled. 412 4.1.4. sendmsg() and recvmsg() - one-to-many style socket 414 An application uses sendmsg() and recvmsg() call to transmit data to 415 and receive data from its peer. 417 ssize_t sendmsg(int sd, const struct msghdr *message, int flags); 419 ssize_t recvmsg(int sd, struct msghdr *message, int flags); 421 sd - the socket descriptor of the endpoint. 422 message: pointer to the msghdr structure which contains a single 423 user message and possibly some ancillary data. See Section 6 for 424 complete description of the data structures. 425 flags - No new flags are defined for SCTP at this level. See 426 Section 5 for SCTP-specific flags used in the msghdr structure. 428 As we will see in Section 6, along with the user data, the ancillary 429 data field is used to carry the sctp_sndrcvinfo and/or the 430 sctp_initmsg structures to perform various SCTP functions including 431 specifying options for sending each user message. Those options, 432 depending on whether sending or receiving, include stream number, 433 stream sequence number, various flags, context and payload protocol 434 Id, etc. 436 When sending user data with sendmsg(), the msg_name field in msghdr 437 structure will be filled with one of the transport addresses of the 438 intended receiver. If there is no association existing between the 439 sender and the intended receiver, the sender's SCTP stack will set up 440 a new association and then send the user data (see Section 4.2 for 441 more on implicit association setup). If an SCTP_INIT cmsg structure 442 is used with NULL data, an association will be established using the 443 parameters from the struct sctp_initmsg structure. If no SCTP_INIT 444 cmsg structure is used in combination with NULL data, an association 445 is established using the default parameters. If NULL data is used, 446 no association exists and the SCTP_ABORT or SCTP_EOF -1 MUST be 447 returned and an errno SHOULD be set to something like EDONOTBESTUPID. 448 Sending a message using sendmsg() is atomic unless explicit EOR 449 marking is enabled on the socket specified by sd. 451 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 452 be delivered if that notification has been enabled, and no more data 453 can be sent to that association. Any attempt to send more data will 454 cause sendmsg() to return with an ESHUTDOWN error. Note that the 455 socket is still open for reading at this point so it is possible to 456 retrieve notifications. 458 When receiving a user message with recvmsg(), the msg_name field in 459 msghdr structure will be populated with the source transport address 460 of the user data. The caller of recvmsg() can use this address 461 information to determine to which association the received user 462 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 463 applications must use the peer transport address provided in the 464 msg_name field by recvmsg() to perform correlation to an association, 465 since they will not have the association ID. 467 If all data in a single message has been delivered, MSG_EOR will be 468 set in the msg_flags field of the msghdr structure (see section 469 Section 6.1). 471 If the application does not provide enough buffer space to completely 472 receive a data message, MSG_EOR will not be set in msg_flags. 473 Successive reads will consume more of the same message until the 474 entire message has been delivered, and MSG_EOR will be set. 476 If the SCTP stack is running low on buffers, it may partially deliver 477 a message. In this case, MSG_EOR will not be set, and more calls to 478 recvmsg() will be necessary to completely consume the message. Only 479 one message at a time can be partially delivered in any stream. The 480 socket option SCTP_FRAGMENT_INTERLEAVE controls various aspects of 481 what interlacing of messages occurs for both the one-to-one and the 482 one-to-many model sockets. Please consult Section 8.1.25 for further 483 details on message delivery options. 485 Note, if the socket is a branched-off socket that only represents one 486 association (see Section 4.1), the msg_name field can be used to 487 override the primary address when sending data. 489 4.1.5. close() - one-to-many style socket 491 Applications use close() to perform graceful shutdown (as described 492 in Section 10.1 of [RFC4960]) on ALL the associations currently 493 represented by a one-to-many style socket. 495 The syntax is: 497 ret = close(int sd); 499 sd - the socket descriptor of the associations to be closed. 501 To gracefully shutdown a specific association represented by the one- 502 to-many style socket, an application should use the sendmsg() call, 503 and including the SCTP_EOF flag. A user may optionally terminate an 504 association non-gracefully by sending with the SCTP_ABORT flag and 505 possibly passing a user specified abort code in the data field. Both 506 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 507 Section 6.2.2) in the sendmsg call. 509 If sd in the close() call is a branched-off socket representing only 510 one association, the shutdown is performed on that association only. 512 4.1.6. connect() - one-to-many style socket 514 An application may use the connect() call in the one-to-many style to 515 initiate an association without sending data. 517 The syntax is: 519 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 521 sd - the socket descriptor to have a new association added to. 522 nam - the address structure (either struct sockaddr_in or struct 523 sockaddr_in6 defined in [RFC3493]). 524 len - the size of the address. 525 Multiple connect() calls can be made on the same socket to create 526 multiple associations. This is different from the semantics of 527 connect() on a UDP socket. 529 4.2. Implicit Association Setup 531 Implicit association setup applies only to one-to-many style sockets. 532 For one-to-one style sockets implicit association setup MUST NOT be 533 used. 535 Once the bind() call is complete on a one-to-many style socket, the 536 application can begin sending and receiving data using the sendmsg()/ 537 recvmsg() or sendto()/recvfrom() calls, without going through any 538 explicit association setup procedures (i.e., no connect() calls 539 required). 541 Whenever sendmsg() or sendto() is called and the SCTP stack at the 542 sender finds that there is no association existing between the sender 543 and the intended receiver (identified by the address passed either in 544 the msg_name field of msghdr structure in the sendmsg() call or the 545 dest_addr field in the sendto() call), the SCTP stack will 546 automatically setup an association to the intended receiver. 548 Upon the successful association setup a SCTP_COMM_UP notification 549 will be dispatched to the socket at both the sender and receiver 550 side. This notification can be read by the recvmsg() system call 551 (see Section 4.1.3). 553 Note, if the SCTP stack at the sender side supports bundling, the 554 first user message may be bundled with the COOKIE ECHO message 555 [RFC4960]. 557 When the SCTP stack sets up a new association implicitly, it first 558 consults the sctp_initmsg structure, which is passed along within the 559 ancillary data in the sendmsg() call (see Section 6.2.1 for details 560 of the data structures), for any special options to be used on the 561 new association. 563 If this information is not present in the sendmsg() call, or if the 564 implicit association setup is triggered by a sendto() call, the 565 default association initialization parameters will be used. These 566 default association parameters may be set with respective 567 setsockopt() calls or be left to the system defaults. 569 Implicit association setup cannot be initiated by send()/recv() 570 calls. 572 4.3. Non-blocking mode 574 Some SCTP users might want to avoid blocking when they call socket 575 interface function. 577 Once all bind() calls are complete on a one-to-many style socket, the 578 application must set the non-blocking option by a fcntl() (such as 579 O_NONBLOCK). After which the sendmsg() function returns immediately, 580 and the success or failure of the data message (and possible 581 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 582 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 583 be sent (due to a CANT_START_ASSOC), the sender will also receive a 584 SCTP_SEND_FAILED event. Those event(s) can be received by the user 585 calling of recvmsg(). A server (having called listen()) is also 586 notified of an association up event by the reception of a 587 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 588 possibly the reception of the first data message. 590 In order to shutdown the association gracefully, the user must call 591 sendmsg() with no data and with the SCTP_EOF flag set. The function 592 returns immediately, and completion of the graceful shutdown is 593 indicated by an SCTP_ASSOC_CHANGE notification of type 594 SHUTDOWN_COMPLETE (see Section 6.3.1.1). Note that this can also be 595 done using the sctp_send() call described in Section 9.10. 597 An application is recommended to use caution when using select() (or 598 poll()) for writing on a one-to-many style socket. The reason being 599 that interpretation of select on write is implementation specific. 600 Generally a positive return on a select on write would only indicate 601 that one of the associations represented by the one-to-many socket is 602 writable. An application that writes after the select return may 603 still block since the association that was writeable is not the 604 destination association of the write call. Likewise select (or 605 poll()) for reading from a one-to-many socket will only return an 606 indication that one of the associations represented by the socket has 607 data to be read. 609 An application that wishes to know that a particular association is 610 ready for reading or writing should either use the one-to-one style 611 or use the sctp_peeloff() (see Section 9.2) function to separate the 612 association of interest from the one-to-many socket. 614 4.4. Special considerations 616 The fact that a one-to-many style socket can provide access to many 617 SCTP associations through a single socket descriptor has important 618 implications for both application programmers and system programmers 619 implementing this API. A key issue is how buffer space inside the 620 sockets layer is managed. Because this implementation detail 621 directly affects how application programmers must write their code to 622 ensure correct operation and portability, this section provides some 623 guidance to both implementors and application programmers. 625 An important feature that SCTP shares with TCP is flow control: 626 specifically, a sender may not send data faster than the receiver can 627 consume it. 629 For TCP, flow control is typically provided for in the sockets API as 630 follows. If the reader stops reading, the sender queues messages in 631 the socket layer until it uses all of its socket buffer space 632 allocation creating a "stalled connection". Further attempts to 633 write to the socket will block or return the error EAGAIN or 634 EWOULDBLOCK for a non-blocking socket. At some point, either the 635 connection is closed, or the receiver begins to read again freeing 636 space in the output queue. 638 For one-to-one style SCTP sockets (this includes sockets descriptors 639 that were separated from a one-to-many style socket with 640 sctp_peeloff()) the behavior is identical. For one-to-many style 641 SCTP sockets, the fact that we have multiple associations on a single 642 socket makes the situation more complicated. If the implementation 643 uses a single buffer space allocation shared by all associations, a 644 single stalled association can prevent the further sending of data on 645 all associations active on a particular one-to-many style socket. 647 For a blocking socket, it should be clear that a single stalled 648 association can block the entire socket. For this reason, 649 application programmers may want to use non-blocking one-to-many 650 style sockets. The application should at least be able to send 651 messages to the non-stalled associations. 653 But a non-blocking socket is not sufficient if the API implementor 654 has chosen a single shared buffer allocation for the socket. A 655 single stalled association would eventually cause the shared 656 allocation to fill, and it would become impossible to send even to 657 non-stalled associations. 659 The API implementor can solve this problem by providing each 660 association with its own allocation of outbound buffer space. Each 661 association should conceptually have as much buffer space as it would 662 have if it had its own socket. As a bonus, this simplifies the 663 implementation of sctp_peeloff(). 665 To ensure that a given stalled association will not prevent other 666 non-stalled associations from being writable, application programmers 667 should either: 669 (a) demand that the underlying implementation dedicates independent 670 buffer space allotments to each association (as suggested above), 671 or 672 (b) verify that their application layer protocol does not permit 673 large amounts of unread data at the receiver (this is true of some 674 request-response protocols, for example), or 675 (c) use one-to-one style sockets for association which may 676 potentially stall (either from the beginning, or by using 677 sctp_peeloff before sending large amounts of data that may cause a 678 stalled condition). 679 An implementation which dedicates independent buffer space for 680 each association should define HAVE_SCTP_MULTIBUF to 1. 682 5. one-to-one style Interface 684 The goal of this style is to follow as closely as possible the 685 current practice of using the sockets interface for a connection 686 oriented protocol, such as TCP. This style enables existing 687 applications using connection oriented protocols to be ported to SCTP 688 with very little effort. 690 Note that some new SCTP features and some new SCTP socket options can 691 only be utilized through the use of sendmsg() and recvmsg() calls, 692 see Section 5.1.8. Also note that some socket interfaces may not be 693 able to provide data on the third leg of the association set up with 694 this interface style. 696 5.1. Basic Operation 698 A typical server in one-to-one style uses the following system call 699 sequence to prepare an SCTP endpoint for servicing requests: 701 1. socket() 703 2. bind() 705 3. listen() 707 4. accept() 709 The accept() call blocks until a new association is set up. It 710 returns with a new socket descriptor. The server then uses the new 711 socket descriptor to communicate with the client, using recv() and 712 send() calls to get requests and send back responses. 714 Then it calls 716 5. close() 718 to terminate the association. 720 A typical client uses the following system call sequence to setup an 721 association with a server to request services: 723 1. socket() 725 2. connect() 727 After returning from connect(), the client uses send() and recv() 728 calls to send out requests and receive responses from the server. 730 The client calls 732 3. close() 734 to terminate this association when done. 736 5.1.1. socket() - one-to-one style socket 738 Applications calls socket() to create a socket descriptor to 739 represent an SCTP endpoint. 741 The syntax is: 743 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 745 or, 747 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 749 Here, SOCK_STREAM indicates the creation of a one-to-one style 750 socket. 752 The first form creates an endpoint which can use only IPv4 addresses, 753 while the second form creates an endpoint which can use both IPv6 and 754 IPv4 addresses. 756 5.1.2. bind() - one-to-one style socket 758 Applications use bind() to pass an address to be associated with an 759 SCTP endpoint to the system. bind() allows only either a single 760 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 761 endpoint can be associated with multiple addresses. To do this, 762 sctp_bindx() is introduced in Section 9.1 to help applications do the 763 job of associating multiple addresses. 765 These addresses associated with a socket are the eligible transport 766 addresses for the endpoint to send and receive data. The endpoint 767 will also present these addresses to its peers during the association 768 initialization process, see [RFC4960]. 770 The syntax is: 772 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 774 sd: the socket descriptor returned by socket() call. 775 addr: the address structure (either struct sockaddr_in or struct 776 sockaddr_in6 defined in [RFC3493]). 777 addrlen: the size of the address structure. 779 If sd is an IPv4 socket, the address passed must be an IPv4 address. 780 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 781 either be an IPv4 or an IPv6 address. 783 Applications cannot call bind() multiple times to associate multiple 784 addresses to the endpoint. After the first call to bind(), all 785 subsequent calls will return an error. 787 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 788 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 789 operating system will associate the endpoint with an optimal address 790 set of the available interfaces. 792 If a bind() is not called prior to the connect() call, the system 793 picks an ephemeral port and will choose an address set equivalent to 794 binding with a wildcard address. One of those addresses will be the 795 primary address for the association. This automatically enables the 796 multi-homing capability of SCTP. 798 The completion of this bind() process does not ready the SCTP 799 endpoint to accept inbound SCTP association requests. Until a 800 listen() system call, described below, is performed on the socket, 801 the SCTP endpoint will promptly reject an inbound SCTP INIT request 802 with an SCTP ABORT. 804 5.1.3. listen() - one-to-one style socket 806 Applications use listen() to ready the SCTP endpoint for accepting 807 inbound associations. 809 The syntax is: 811 int listen(int sd, int backlog); 813 sd: the socket descriptor of the SCTP endpoint. 814 backlog: this specifies the max number of outstanding associations 815 allowed in the socket's accept queue. These are the associations 816 that have finished the four-way initiation handshake (see Section 817 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog 818 of '0' indicates that the caller no longer wishes to receive new 819 associations. 821 5.1.4. accept() - one-to-one style socket 823 Applications use accept() call to remove an established SCTP 824 association from the accept queue of the endpoint. A new socket 825 descriptor will be returned from accept() to represent the newly 826 formed association. 828 The syntax is: 830 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 832 new_sd - the socket descriptor for the newly formed association. 834 sd - the listening socket descriptor. 835 addr - on return, will contain the primary address of the peer 836 endpoint. 837 addrlen - on return, will contain the size of addr. 839 5.1.5. connect() - one-to-one style socket 841 Applications use connect() to initiate an association to a peer. 843 The syntax is: 845 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 847 sd - the socket descriptor of the endpoint. 848 addr - the peer's address. 849 addrlen - the size of the address. 851 This operation corresponds to the ASSOCIATE primitive described in 852 section 10.1 of [RFC4960]. 854 By default, the new association created has only one outbound stream. 855 The SCTP_INITMSG option described in Section 8.1.3 should be used 856 before connecting to change the number of outbound streams. 858 If a bind() is not called prior to the connect() call, the system 859 picks an ephemeral port and will choose an address set equivalent to 860 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket 861 respectively. One of those addresses will be the primary address for 862 the association. This automatically enables the multi-homing 863 capability of SCTP. 865 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 866 during the association set up phase. If an application wants to do 867 this, it cannot use connect() call. Instead, it should use sendto() 868 or sendmsg() to initiate an association. If it uses sendto() and it 869 wants to change initialization behavior, it needs to use the 870 SCTP_INITMSG socket option before calling sendto(). Or it can use 871 SCTP_INIT type sendmsg() to initiate an association without doing the 872 setsockopt(). Note that some sockets implementations may not support 873 the sending of data to initiate an association with the one-to-one 874 style (implementations that do not support T/TCP normally have this 875 restriction). Implementations which allow sending of data to 876 initiate an association without calling connect() define the 877 preprocessor constant HAVE_SCTP_NOCONNECT to 1. 879 SCTP does not support half close semantics. This means that unlike 880 T/TCP, MSG_EOF should not be set in the flags parameter when calling 881 sendto() or sendmsg() when the call is used to initiate a connection. 883 MSG_EOF is not an acceptable flag with SCTP socket. 885 5.1.6. close() - one-to-one style socket 887 Applications use close() to gracefully close down an association. 889 The syntax is: 891 int close(int sd); 893 sd - the socket descriptor of the association to be closed. 895 After an application calls close() on a socket descriptor, no further 896 socket operations will succeed on that descriptor. 898 5.1.7. shutdown() - one-to-one style socket 900 SCTP differs from TCP in that it does not have half closed semantics. 901 Hence the shutdown() call for SCTP is an approximation of the TCP 902 shutdown() call, and solves some different problems. Full TCP- 903 compatibility is not provided, so developers porting TCP applications 904 to SCTP may need to recode sections that use shutdown(). (Note that 905 it is possible to achieve the same results as half close in SCTP 906 using SCTP streams.) 908 The syntax is: 910 int shutdown(int sd, int how); 912 sd - the socket descriptor of the association to be closed. 913 how - Specifies the type of shutdown. The values are as follows: 914 SHUT_RD - Disables further receive operations. No SCTP protocol 915 action is taken. 916 SHUT_WR - Disables further send operations, and initiates the 917 SCTP shutdown sequence. 918 SHUT_RDWR - Disables further send and receive operations and 919 initiates the SCTP shutdown sequence. 921 The major difference between SCTP and TCP shutdown() is that SCTP 922 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 923 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 924 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 925 the SCTP association while still leaving the socket descriptor open, 926 so that the caller can receive back any data SCTP was unable to 927 deliver (see Section 6.3.1.4 for more information). 929 To perform the ABORT operation described in [RFC4960] section 10.1, 930 an application can use the socket option SO_LINGER. It is described 931 in Section 8.1.4. 933 5.1.8. sendmsg() and recvmsg() - one-to-one style socket 935 With a one-to-one style socket, the application can also use 936 sendmsg() and recvmsg() to transmit data to and receive data from its 937 peer. The semantics is similar to those used in the one-to-many 938 style (section Section 4.1.3), with the following differences: 939 1. When sending, the msg_name field in the msghdr is not used to 940 specify the intended receiver, rather it is used to indicate a 941 preferred peer address if the sender wishes to discourage the 942 stack from sending the message to the primary address of the 943 receiver. If the socket is connected and the transport address 944 given is not part of the current association, the data will not 945 be sent and a SCTP_SEND_FAILED event will be delivered to the 946 application if send failure events are enabled. 947 2. Using sendmsg() on a non-connected one-to-one style socket for 948 implicit connection setup may or may not work depending on the 949 SCTP implementation. 951 5.1.9. getpeername() 953 Applications use getpeername() to retrieve the primary socket address 954 of the peer. This call is for TCP compatibility, and is not multi- 955 homed. It does not work with one-to-many style sockets. See 956 Section 9.3 for a multi-homed/one-to-many style version of the call. 958 The syntax is: 960 int getpeername(int sd, struct sockaddr *address, 961 socklen_t *len); 963 sd - the socket descriptor to be queried. 964 address - On return, the peer primary address is stored in this 965 buffer. If the socket is an IPv4 socket, the address will be 966 IPv4. If the socket is an IPv6 socket, the address will be either 967 an IPv6 or IPv4 address. 968 len - The caller should set the length of address here. On return, 969 this is set to the length of the returned address. 971 If the actual length of the address is greater than the length of the 972 supplied sockaddr structure, the stored address will be truncated. 974 6. Data Structures 976 We discuss in this section important data structures which are 977 specific to SCTP and are used with sendmsg() and recvmsg() calls to 978 control SCTP endpoint operations and to access ancillary information 979 and notifications. 981 6.1. The msghdr and cmsghdr Structures 983 The msghdr structure used in the sendmsg() and recvmsg() calls, as 984 well as the ancillary data carried in the structure, is the key for 985 the application to set and get various control information from the 986 SCTP endpoint. 988 The msghdr and the related cmsghdr structures are defined and 989 discussed in details in [RFC3542]. Here we will cite their 990 definitions from [RFC3542]. 992 The msghdr structure: 994 struct msghdr { 995 void *msg_name; /* ptr to socket address structure */ 996 socklen_t msg_namelen; /* size of socket address structure */ 997 struct iovec *msg_iov; /* scatter/gather array */ 998 size_t msg_iovlen; /* # elements in msg_iov */ 999 void *msg_control; /* ancillary data */ 1000 socklen_t msg_controllen; /* ancillary data buffer length */ 1001 int msg_flags; /* flags on received message */ 1002 }; 1004 The cmsghdr structure: 1006 struct cmsghdr { 1007 socklen_t cmsg_len; /* #bytes, including this header */ 1008 int cmsg_level; /* originating protocol */ 1009 int cmsg_type; /* protocol-specific type */ 1010 /* followed by unsigned char cmsg_data[]; */ 1011 }; 1013 In the msghdr structure, the usage of msg_name has been discussed in 1014 previous sections (see Section 4.1.3 and Section 5.1.8). 1016 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1017 field) are treated as a single SCTP data chunk, rather than multiple 1018 chunks, for both sendmsg() and recvmsg(). 1020 The msg_flags are not used when sending a message with sendmsg(). 1022 If a notification has arrived, recvmsg() will return the notification 1023 with the MSG_NOTIFICATION flag set in msg_flags. If the 1024 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1025 Section 6.3 for more information about notifications. 1027 If all portions of a data frame or notification have been read, 1028 recvmsg() will return with MSG_EOR set in msg_flags. 1030 6.2. SCTP msg_control Structures 1032 A key element of all SCTP-specific socket extensions is the use of 1033 ancillary data to specify and access SCTP-specific data via the 1034 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1035 Fine-grained control over initialization and sending parameters are 1036 handled with ancillary data. 1038 Each ancillary data item is proceeded by a struct cmsghdr (see 1039 Section 6.1), which defines the function and purpose of the data 1040 contained in in the cmsg_data[] member. 1042 There are two kinds of ancillary data used by SCTP: initialization 1043 data, and, header information (SNDRCV). Initialization data (one-to- 1044 many style only) sets protocol parameters for new associations. 1045 Section 6.2.1 provides more details. Header information can set or 1046 report parameters on individual messages in a stream. See 1047 Section 6.2.2 for how to use SNDRCV ancillary data. 1049 By default on a one-to-one style socket, SCTP will pass no ancillary 1050 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1051 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1052 be enabled with socket options defined for SCTP; see Section 8.3. 1054 Note that all ancillary types are fixed length; see Section 6.4 for 1055 further discussion on this. These data structures use struct 1056 sockaddr_storage (defined in [RFC3493]) as a portable, fixed length 1057 address format. 1059 Other protocols may also provide ancillary data to the socket layer 1060 consumer. These ancillary data items from other protocols may 1061 intermingle with SCTP data. For example, the IPv6 socket API 1062 definitions ([RFC3542] and [RFC3493]) define a number of ancillary 1063 data items. If a socket API consumer enables delivery of both SCTP 1064 and IPv6 ancillary data, they both may appear in the same msg_control 1065 buffer in any order. An application may thus need to handle other 1066 types of ancillary data besides that passed by SCTP. 1068 The sockets application must provide a buffer large enough to 1069 accommodate all ancillary data provided via recvmsg(). If the buffer 1070 is not large enough, the ancillary data will be truncated and the 1071 msghdr's msg_flags will include MSG_CTRUNC. 1073 6.2.1. SCTP Initiation Structure (SCTP_INIT) 1075 This cmsghdr structure provides information for initializing new SCTP 1076 associations with sendmsg(). The SCTP_INITMSG socket option uses 1077 this same data structure. This structure is not used for recvmsg(). 1079 +--------------+-----------+---------------------+ 1080 | cmsg_level | cmsg_type | cmsg_data[] | 1081 +--------------+-----------+---------------------+ 1082 | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | 1083 +--------------+-----------+---------------------+ 1085 Here is the definition of the sctp_initmsg structure: 1087 struct sctp_initmsg { 1088 uint16_t sinit_num_ostreams; 1089 uint16_t sinit_max_instreams; 1090 uint16_t sinit_max_attempts; 1091 uint16_t sinit_max_init_timeo; 1092 }; 1094 sinit_num_ostreams: 16 bits (unsigned integer) 1096 This is an integer number representing the number of streams that the 1097 application wishes to be able to send to. This number is confirmed 1098 in the SCTP_COMM_UP notification and must be verified since it is a 1099 negotiated number with the remote endpoint. The default value of 0 1100 indicates to use the endpoint default value. 1102 sinit_max_instreams: 16 bits (unsigned integer) 1104 This value represents the maximum number of inbound streams the 1105 application is prepared to support. This value is bounded by the 1106 actual implementation. In other words the user MAY be able to 1107 support more streams than the Operating System. In such a case, the 1108 Operating System limit overrides the value requested by the user. 1109 The default value of 0 indicates to use the endpoints default value. 1111 sinit_max_attempts: 16 bits (unsigned integer) 1113 This integer specifies how many attempts the SCTP endpoint should 1114 make at resending the INIT. This value overrides the system SCTP 1115 'Max.Init.Retransmits' value. The default value of 0 indicates to 1116 use the endpoints default value. This is normally set to the 1117 system's default 'Max.Init.Retransmit' value. 1119 sinit_max_init_timeo: 16 bits (unsigned integer) 1120 This value represents the largest Time-Out or RTO value (in 1121 milliseconds) to use in attempting an INIT. Normally the 'RTO.Max' 1122 is used to limit the doubling of the RTO upon timeout. For the INIT 1123 message this value MAY override 'RTO.Max'. This value MUST NOT 1124 influence 'RTO.Max' during data transmission and is only used to 1125 bound the initial setup time. A default value of 0 indicates to use 1126 the endpoints default value. This is normally set to the system's 1127 'RTO.Max' value (60 seconds). 1129 6.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1131 This cmsghdr structure specifies SCTP options for sendmsg() and 1132 describes SCTP header information about a received message through 1133 recvmsg(). 1135 +--------------+-------------+------------------------+ 1136 | cmsg_level | cmsg_type | cmsg_data[] | 1137 +--------------+-------------+------------------------+ 1138 | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | 1139 +--------------+-------------+------------------------+ 1141 Here is the definition of sctp_sndrcvinfo: 1143 struct sctp_sndrcvinfo { 1144 uint16_t sinfo_stream; 1145 uint16_t sinfo_ssn; 1146 uint16_t sinfo_flags; 1147 uint16_t sinfo_pr_policy; 1148 uint32_t sinfo_ppid; 1149 uint32_t sinfo_context; 1150 uint32_t sinfo_pr_value; 1151 uint32_t sinfo_tsn; 1152 uint32_t sinfo_cumtsn; 1153 sctp_assoc_t sinfo_assoc_id; 1154 }; 1156 sinfo_stream: 16 bits (unsigned integer) 1158 For recvmsg() the SCTP stack places the message's stream number in 1159 this value. For sendmsg() this value holds the stream number that 1160 the application wishes to send this message to. If a sender 1161 specifies an invalid stream number an error indication is returned 1162 and the call fails. 1164 sinfo_ssn: 16 bits (unsigned integer) 1166 For recvmsg() this value contains the stream sequence number that the 1167 remote endpoint placed in the DATA chunk. For fragmented messages 1168 this is the same number for all deliveries of the message (if more 1169 than one recvmsg() is needed to read the message). The sendmsg() 1170 call will ignore this parameter. 1172 sinfo_ppid: 32 bits (unsigned integer) 1174 This value in sendmsg() is an unsigned integer that is passed to the 1175 remote end in each user message. In recvmsg() this value is the same 1176 information that was passed by the upper layer in the peer 1177 application. Please note that the SCTP stack performs no byte order 1178 modification of this field. For example, if the DATA chunk has to 1179 contain a given value in network byte order, the SCTP user has to 1180 perform the htonl() computation. 1182 sinfo_context: 32 bits (unsigned integer) 1184 This value is an opaque 32 bit context datum that is used in the 1185 sendmsg() function. This value is passed back to the upper layer if 1186 a error occurs on the send of a message and is retrieved with each 1187 undelivered message (Note: if a endpoint has done multiple sends, all 1188 of which fail, multiple different sinfo_context values will be 1189 returned. One with each user data message). 1191 sinfo_flags: 16 bits (unsigned integer) 1193 This field may contain any of the following flags and is composed of 1194 a bitwise OR of these values. 1196 recvmsg() flags: 1197 SCTP_UNORDERED - This flag is present when the message was sent non- 1198 ordered. 1200 sendmsg() flags: 1201 SCTP_UNORDERED - This flag requests the un-ordered delivery of the 1202 message. If this flag is clear the datagram is considered an 1203 ordered send. 1205 SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the 1206 SCTP stack to override the primary destination address with the 1207 address found with the sendto/sendmsg call. 1209 SCTP_ABORT - Setting this flag causes the specified association to 1210 abort by sending an ABORT message to the peer (one-to-many style 1211 only). The ABORT chunk will contain an error cause 'User 1212 Initiated Abort' with cause code 12. The cause specific 1213 information of this error cause is provided in msg_iov. 1215 SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown 1216 procedures on the specified association. Graceful shutdown 1217 assures that all data enqueued by both endpoints is successfully 1218 transmitted before closing the association (one-to-many style 1219 only). 1221 SCTP_SENDALL - This flag, if set, will cause a one-to-many model 1222 socket to send the message to all associations that are currently 1223 established on this socket. For the one-to-one socket, this flag 1224 has no effect. 1226 sinfo_pr_policy: 16 bits (unsigned integer) 1228 For the sending side, this specifies which PR-SCTP policy is used. 1229 Using SCTP_PR_SCTP_NONE results in a reliable transmission. When 1230 SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliabilility" 1231 defined in [RFC3758] is used. In this case, the lifetime is provided 1232 in sinfo_pr_value. 1234 sinfo_pr_value: 32 bit (unsigned integer) 1236 The meaning of this field depends of the PR-SCTP policy specified by 1237 the sinfo_pr_policy field. It is ignored when SCTP_PR_SCTP_NONE is 1238 specified. In case of SCTP_PR_SCTP_TTL the lifetime is specified. 1240 sinfo_tsn: 32 bit (unsigned integer) 1242 For the receiving side, this field holds a TSN that was assigned to 1243 one of the SCTP Data Chunks. 1245 sinfo_cumtsn: 32 bit (unsigned integer) 1247 This field will hold the current cumulative TSN as known by the 1248 underlying SCTP layer. Note this field is ignored when sending and 1249 only valid for a receive operation when sinfo_flags are set to 1250 SCTP_UNORDERED. 1252 sinfo_assoc_id: sizeof (sctp_assoc_t) 1254 The association handle field, sinfo_assoc_id, holds the identifier 1255 for the association announced in the SCTP_COMM_UP notification. All 1256 notifications for a given association have the same identifier. 1257 Ignored for one-to-one style sockets. 1259 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1261 6.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1263 This cmsghdr structure specifies SCTP options for SCTP header 1264 information about a received message via recvmsg(). Note that this 1265 structure is an extended version of SCTP_SNDRCV (see Section 6.2.2) 1266 and will only be received if the user has set the socket option 1267 SCTP_USE_EXT_RCVINFO to true in addition to any event subscription 1268 needed to receive ancillary data. Note that next message data is not 1269 valid unless the current message is completely read, i.e. the MSG_EOR 1270 is set, in other words if you have more data to read from the current 1271 message then no next message information will be available. 1273 +--------------+-------------+------------------------+ 1274 | cmsg_level | cmsg_type | cmsg_data[] | 1275 +--------------+-------------+------------------------+ 1276 | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | 1277 +--------------+-------------+------------------------+ 1279 Here is the definition of sctp_extrcvinfo structure: 1281 struct sctp_extrcvinfo { 1282 struct sctp_sndrcvinfo serinfo_sinfo; 1283 uint16_t serinfo_next_flags; 1284 uint16_t serinfo_next_stream; 1285 uint32_t serinfo_next_aid; 1286 uint32_t serinfo_next_length; 1287 uint32_t serinfo_next_ppid; 1288 }; 1290 serinfo_sinfo: structure 1292 Please see Section 6.2.2 for the details for this structure. 1294 serinfo_next_flags: 16 bit (unsigned integer) 1296 This bitmask will hold one or more of the following values: 1297 SCTP_NEXT_MSG_AVAIL - This bit, when set to 1, indicates that next 1298 message information is available i.e.: next_stream, next_asocid, 1299 next_length and next_ppid fields all have valid values. If this 1300 bit is set to 0, then these fields are not valid and should be 1301 ignored. 1303 SCTP_NEXT_MSG_ISCOMPLETE - This bit, when set, indicates that the 1304 next message is completely in the receive buffer. The next_length 1305 field thus contains the entire message size. If this flag is set 1306 to 0, then the next_length field only contains part of the message 1307 size since the message is still being received (it is being 1308 partially delivered). 1310 SCTP_NEXT_MSG_IS_UNORDERED - This bit, when set, indicates that the 1311 next message to be received was sent by the peer as unordered. If 1312 this bit is not set (i.e the bit is 0) the next message to be read 1313 is an ordered message in the stream specified. 1314 SCTP_NEXT_MSG_IS_NOTIFICATION - This bit, when set, indicates that 1315 the next message to be received is not a message from the peer, 1316 but instead is a MSG_NOTIFICATION from the local SCTP stack. 1318 serinfo_next_stream: 16 bit (unsigned integer) 1320 This value, when valid (see sreinfo_next_flags), contains the next 1321 stream number that will be received on a subsequent call to one of 1322 the receive message functions. 1324 serinfo_next_aid: 32 bit (unsigned integer) 1326 This value, when valid (see next_flags), contains the next 1327 association identification that will be received on a subsequent call 1328 to one of the receive message functions. 1330 sreinfo_next_length: 32 bit (unsigned integer) 1332 This value, when valid (see sreinfo_next_flags), contains the length 1333 of the next message that will be received on a subsequent call to one 1334 of the receive message functions. Note that this length may be a 1335 partial length depending on the settings of next_flags. 1337 sreinfo_next_ppid: 32 bit (unsigned integer) 1339 This value, when valid (see sreinfo_next_flags), contains the ppid of 1340 the next message that will be received on a subsequent call to one of 1341 the receive message functions. 1343 6.3. SCTP Events and Notifications 1345 An SCTP application may need to understand and process events and 1346 errors that happen on the SCTP stack. These events include network 1347 status changes, association startups, remote operational errors and 1348 undeliverable messages. All of these can be essential for the 1349 application. 1351 When an SCTP application layer does a recvmsg() the message read is 1352 normally a data message from a peer endpoint. If the application 1353 wishes to have the SCTP stack deliver notifications of non-data 1354 events, it sets the appropriate socket option for the notifications 1355 it wants. See Section 8.3 for these socket options. When a 1356 notification arrives, recvmsg() returns the notification in the 1357 application-supplied data buffer via msg_iov, and sets 1358 MSG_NOTIFICATION in msg_flags. 1360 This section details the notification structures. Every notification 1361 structure carries some common fields which provides general 1362 information. 1364 A recvmsg() call will return only one notification at a time. Just 1365 as when reading normal data, it may return part of a notification if 1366 the msg_iov buffer is not large enough. If a single read is not 1367 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1368 reading the notification before subsequent data can arrive. 1370 6.3.1. SCTP Notification Structure 1372 The notification structure is defined as the union of all 1373 notification types. 1375 union sctp_notification { 1376 struct { 1377 uint16_t sn_type; /* Notification type. */ 1378 uint16_t sn_flags; 1379 uint32_t sn_length; 1380 } sn_header; 1381 struct sctp_assoc_change sn_assoc_change; 1382 struct sctp_paddr_change sn_paddr_change; 1383 struct sctp_remote_error sn_remote_error; 1384 struct sctp_send_failed sn_send_failed; 1385 struct sctp_shutdown_event sn_shutdown_event; 1386 struct sctp_adaptation_event sn_adaptation_event; 1387 struct sctp_pdapi_event sn_pdapi_event; 1388 struct sctp_authkey_event sn_auth_event; 1389 struct sctp_no_auth_event sn_no_auth_event; 1390 }; 1392 sn_type: 16 bits (unsigned integer) 1394 The following list describes the SCTP notification and event types 1395 for the field sn_type. 1397 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1398 been opened or closed. Refer to Section 6.3.1.1 for details. 1399 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1400 part of an existing association has experienced a change of state 1401 (e.g. a failure or return to service of the reachability of a 1402 endpoint via a specific transport address). Please see 1403 Section 6.3.1.2 for data structure details. 1405 SCTP_REMOTE_ERROR: The attached error message is an Operational 1406 Error received from the remote peer. It includes the complete TLV 1407 sent by the remote endpoint. See Section 6.3.1.3 for the detailed 1408 format. 1409 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1410 remote endpoint. This structure includes the original 1411 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1412 structure uses the sctp_sndrecvinfo per Section 6.3.1.4. 1413 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1414 should be sent on this socket. 1415 SCTP_ADAPTATION_INDICATION: This notification holds the peers 1416 indicated adaptation layer. Please see Section 6.3.1.6. 1417 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1418 receiver that the partial delivery has been aborted. This may 1419 indicate the association is about to be aborted. Please see 1420 Section 6.3.1.7 1421 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1422 receiver that either an error occurred on authentication, or a new 1423 key was made active. Section 6.3.1.8 1424 SCTP_NO_AUTHENTICATION_EVENT: This notification is used to tell a 1425 receiver that the peer does not support SCTP-AUTH. 1426 Section 6.3.1.9 1427 SCTP_AUTHENTICATION_KEY_FREE_EVENT: This notification is used to 1428 tell a receiver that a key is not used anymore for sending. 1429 Section 6.3.1.11 1430 SCTP_SENDER_DRY_EVENT: This notification is used to inform the 1431 application that the sender has no user data queued anymore, 1432 neither for transmission or retransmission. Section 6.3.1.10 1434 All standard values for sn_type are greater than 2^15. Values from 1435 2^15 and down are reserved. 1437 sn_flags: 16 bits (unsigned integer) 1439 These are notification-specific flags. 1441 sn_length: 32 bits (unsigned integer) 1443 This is the length of the whole sctp_notification structure including 1444 the sn_type, sn_flags, and sn_length fields. 1446 6.3.1.1. SCTP_ASSOC_CHANGE 1448 Communication notifications inform the ULP that an SCTP association 1449 has either begun or ended. The identifier for a new association is 1450 provided by this notification. The notification information has the 1451 following format: 1453 struct sctp_assoc_change { 1454 uint16_t sac_type; 1455 uint16_t sac_flags; 1456 uint32_t sac_length; 1457 uint16_t sac_state; 1458 uint16_t sac_error; 1459 uint16_t sac_outbound_streams; 1460 uint16_t sac_inbound_streams; 1461 sctp_assoc_t sac_assoc_id; 1462 uint8_t sac_info[]; 1463 }; 1465 sac_type: 1467 It should be SCTP_ASSOC_CHANGE. 1469 sac_flags: 16 bits (unsigned integer) 1471 Currently unused. 1473 sac_length: 32 bits (unsigned integer) 1475 This field is the total length of the notification data, including 1476 the notification header. 1478 sac_state: 16 bits (signed integer) 1480 This field holds one of a number of values that communicate the event 1481 that happened to the association. They include: 1483 Event Name Description 1485 ---------------- --------------- 1487 SCTP_COMM_UP - A new association is now ready and data may be 1488 exchanged with this peer. 1489 SCTP_COMM_LOST - The association has failed. The association is now 1490 in the closed state. If SEND FAILED notifications are turned on, 1491 a SCTP_COMM_LOST is followed by a series of SCTP_SEND_FAILED 1492 events, one for each outstanding message. 1493 SCTP_RESTART - SCTP has detected that the peer has restarted. 1494 SCTP_SHUTDOWN_COMP - The association has gracefully closed. 1495 SCTP_CANT_STR_ASSOC - The association failed to setup. If non 1496 blocking mode is set and data was sent (in the udp mode), a 1497 SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED 1498 events, one for each outstanding message. 1500 sac_error: 16 bits (signed integer) 1501 If the state was reached due to a error condition (e.g. 1502 SCTP_COMM_LOST) any relevant error information is available in this 1503 field. This corresponds to the protocol error codes defined in 1504 [RFC4960]. 1506 sac_outbound_streams: 16 bits (unsigned integer) 1508 sac_inbound_streams: 16 bits (unsigned integer) 1510 The maximum number of streams allowed in each direction are available 1511 in sac_outbound_streams and sac_inbound streams. 1513 sac_assoc_id: sizeof (sctp_assoc_t) 1515 The association id field, holds the identifier for the association. 1516 All notifications for a given association have the same association 1517 identifier. For one-to-one style socket, this field is ignored. 1519 sac_info: variable 1521 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1522 for this association, sac_info[] contains the complete ABORT chunk as 1523 defined in the SCTP specification [RFC4960] section 3.3.7. 1525 6.3.1.2. SCTP_PEER_ADDR_CHANGE 1527 When a destination address on a multi-homed peer encounters a change 1528 an interface details event is sent. The information has the 1529 following structure: 1531 struct sctp_paddr_change { 1532 uint16_t spc_type; 1533 uint16_t spc_flags; 1534 uint32_t spc_length; 1535 struct sockaddr_storage spc_aaddr; 1536 uint32_t spc_state; 1537 uint32_t spc_error; 1538 sctp_assoc_t spc_assoc_id; 1539 } 1541 spc_type: 1543 It should be SCTP_PEER_ADDR_CHANGE. 1545 spc_flags: 16 bits (unsigned integer) 1547 Currently unused. 1549 spc_length: 32 bits (unsigned integer) 1551 This field is the total length of the notification data, including 1552 the notification header. 1554 spc_aaddr: sizeof (struct sockaddr_storage) 1556 The affected address field, holds the remote peer's address that is 1557 encountering the change of state. 1559 spc_state: 32 bits (signed integer) 1561 This field holds one of a number of values that communicate the event 1562 that happened to the address. They include: 1564 Event Name Description 1566 ---------------- --------------- 1568 SCTP_ADDR_AVAILABLE - This address is now reachable. 1569 SCTP_ADDR_UNREACHABLE - The address specified can no longer be 1570 reached. Any data sent to this address is rerouted to an 1571 alternate until this address becomes reachable. 1572 SCTP_ADDR_REMOVED - The address is no longer part of the 1573 association. 1574 SCTP_ADDR_ADDED - The address is now part of the association. 1575 SCTP_ADDR_MADE_PRIM - This address has now been made to be the 1576 primary destination address. 1577 SCTP_ADDR_CONFIRMED - This address has now been confirmed as a valid 1578 address. 1580 spc_error: 32 bits (signed integer) 1582 If the state was reached due to any error condition (e.g. 1583 SCTP_ADDR_UNREACHABLE) any relevant error information is available in 1584 this field. 1586 spc_assoc_id: sizeof (sctp_assoc_t) 1588 The association id field, holds the identifier for the association. 1589 All notifications for a given association have the same association 1590 identifier. For one-to-one style socket, this field is ignored. 1592 6.3.1.3. SCTP_REMOTE_ERROR 1594 A remote peer may send an Operational Error message to its peer. 1595 This message indicates a variety of error conditions on an 1596 association. The entire ERROR chunk as it appears on the wire is 1597 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1598 specification [RFC4960] and any extensions for a list of possible 1599 error formats. SCTP error notifications have the format: 1601 struct sctp_remote_error { 1602 uint16_t sre_type; 1603 uint16_t sre_flags; 1604 uint32_t sre_length; 1605 uint16_t sre_error; 1606 sctp_assoc_t sre_assoc_id; 1607 uint8_t sre_data[]; 1608 }; 1610 sre_type: 1612 It should be SCTP_REMOTE_ERROR. 1614 sre_flags: 16 bits (unsigned integer) 1616 Currently unused. 1618 sre_length: 32 bits (unsigned integer) 1620 This field is the total length of the notification data, including 1621 the notification header and the contents of sre_data. 1623 sre_error: 16 bits (unsigned integer) 1625 This value represents one of the Operational Error causes defined in 1626 the SCTP specification, in network byte order. 1628 sre_assoc_id: sizeof (sctp_assoc_t) 1630 The association id field, holds the identifier for the association. 1631 All notifications for a given association have the same association 1632 identifier. For one-to-one style socket, this field is ignored. 1634 sre_data: variable 1636 This contains the ERROR chunk as defined in the SCTP specification 1637 [RFC4960] section 3.3.10. 1639 6.3.1.4. SCTP_SEND_FAILED 1641 If SCTP cannot deliver a message it may return the message as a 1642 notification. 1644 struct sctp_send_failed { 1645 uint16_t ssf_type; 1646 uint16_t ssf_flags; 1647 uint32_t ssf_length; 1648 uint32_t ssf_error; 1649 struct sctp_sndrcvinfo ssf_info; 1650 sctp_assoc_t ssf_assoc_id; 1651 uint8_t ssf_data[]; 1652 }; 1654 ssf_type: 1656 It should be SCTP_SEND_FAILED. 1658 ssf_flags: 16 bits (unsigned integer) 1660 The flag value will take one of the following values: 1662 SCTP_DATA_UNSENT - Indicates that the data was never put on the 1663 wire. 1664 SCTP_DATA_SENT - Indicates that the data was put on the wire. Note 1665 that this does not necessarily mean that the data was (or was not) 1666 successfully delivered. 1668 ssf_length: 32 bits (unsigned integer) 1670 This field is the total length of the notification data, including 1671 the notification header and the payload in ssf_data. 1673 ssf_error: 16 bits (unsigned integer) 1675 This value represents the reason why the send failed, and if set, 1676 will be a SCTP protocol error code as defined in [RFC4960] section 1677 3.3.10. 1679 ssf_info: sizeof (struct sctp_sndrcvinfo) 1681 The original send information associated with the undelivered 1682 message. 1684 ssf_assoc_id: sizeof (sctp_assoc_t) 1686 The association id field, sf_assoc_id, holds the identifier for the 1687 association. All notifications for a given association have the same 1688 association identifier. For one-to-one style socket, this field is 1689 ignored. 1691 ssf_data: variable length 1693 The undelivered message, exactly as delivered by the caller to the 1694 original send*() call. 1696 6.3.1.5. SCTP_SHUTDOWN_EVENT 1698 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1699 inform the application that it should cease sending data. 1701 struct sctp_shutdown_event { 1702 uint16_t sse_type; 1703 uint16_t sse_flags; 1704 uint32_t sse_length; 1705 sctp_assoc_t sse_assoc_id; 1706 }; 1708 sse_type 1710 It should be SCTP_SHUTDOWN_EVENT 1712 sse_flags: 16 bits (unsigned integer) 1714 Currently unused. 1716 sse_length: 32 bits (unsigned integer) 1718 This field is the total length of the notification data, including 1719 the notification header. It will generally be sizeof (struct 1720 sctp_shutdown_event). 1722 sse_flags: 16 bits (unsigned integer) 1724 Currently unused. 1726 sse_assoc_id: sizeof (sctp_assoc_t) 1728 The association id field, holds the identifier for the association. 1729 All notifications for a given association have the same association 1730 identifier. For one-to-one style socket, this field is ignored. 1732 6.3.1.6. SCTP_ADAPTATION_INDICATION 1734 When a peer sends a Adaptation Layer Indication parameter , SCTP 1735 delivers this notification to inform the application that of the 1736 peers requested adaptation layer. 1738 struct sctp_adaptation_event { 1739 uint16_t sai_type; 1740 uint16_t sai_flags; 1741 uint32_t sai_length; 1742 uint32_t sai_adaptation_ind; 1743 sctp_assoc_t sai_assoc_id; 1744 }; 1746 sai_type 1748 It should be SCTP_ADAPTATION_INDICATION 1750 sai_flags: 16 bits (unsigned integer) 1752 Currently unused. 1754 sai_length: 32 bits (unsigned integer) 1756 This field is the total length of the notification data, including 1757 the notification header. It will generally be sizeof (struct 1758 sctp_adaptation_event). 1760 sai_adaptation_ind: 32 bits (unsigned integer) 1762 This field holds the bit array sent by the peer in the adaptation 1763 layer indication parameter. The bits are in network byte order. 1765 sai_assoc_id: sizeof (sctp_assoc_t) 1767 The association id field, holds the identifier for the association. 1768 All notifications for a given association have the same association 1769 identifier. For one-to-one style socket, this field is ignored. 1771 6.3.1.7. SCTP_PARTIAL_DELIVERY_EVENT 1773 When a receiver is engaged in a partial delivery of a message this 1774 notification will be used to indicate various events. 1776 struct sctp_pdapi_event { 1777 uint16_t pdapi_type; 1778 uint16_t pdapi_flags; 1779 uint32_t pdapi_length; 1780 uint32_t pdapi_indication; 1781 uint32_t pdapi_stream; 1782 uint32_t pdapi_seq; 1783 sctp_assoc_t pdapi_assoc_id; 1784 }; 1786 pdapi_type 1788 It should be SCTP_PARTIAL_DELIVERY_EVENT 1790 pdapi_flags: 16 bits (unsigned integer) 1792 Currently unused. 1794 pdapi_length: 32 bits (unsigned integer) 1796 This field is the total length of the notification data, including 1797 the notification header. It will generally be sizeof (struct 1798 sctp_pdapi_event). 1800 pdapi_indication: 32 bits (unsigned integer) 1802 This field holds the indication being sent to the application 1803 possible values include: 1805 SCTP_PARTIAL_DELIVERY_ABORTED 1807 pdapi_stream: 16 bits (unsigned integer) 1809 This field holds the stream on which the partial delivery event 1810 happened. 1812 pdapi_seq: 16 bits (unsigned integer) 1814 This field holds the stream sequence number which was being partially 1815 delivered. 1817 pdapi_assoc_id: sizeof (sctp_assoc_t) 1819 The association id field, holds the identifier for the association. 1820 All notifications for a given association have the same association 1821 identifier. For one-to-one style socket, this field is ignored. 1823 6.3.1.8. SCTP_AUTHENTICATION_EVENT 1825 When a receiver is using authentication this message will provide 1826 notifications regarding new keys being made active as well as errors. 1828 struct sctp_authkey_event { 1829 uint16_t auth_type; 1830 uint16_t auth_flags; 1831 uint32_t auth_length; 1832 uint16_t auth_keynumber; 1833 uint16_t auth_altkeynumber; 1834 uint32_t auth_indication; 1835 sctp_assoc_t auth_assoc_id; 1836 }; 1838 auth_type 1840 It should be SCTP_AUTHENTICATION_EVENT 1842 auth_flags: 16 bits (unsigned integer) 1844 Currently unused. 1846 auth_length: 32 bits (unsigned integer) 1848 This field is the total length of the notification data, including 1849 the notification header. It will generally be sizeof (struct 1850 sctp_authkey_event). 1852 auth_keynumber: 32 bits (unsigned integer) 1854 This field holds the keynumber set by the user for the effected key. 1855 If more than one key is involved, this will contain one of the keys 1856 involved in the notification. 1858 auth_altkeynumber: 32 bits (unsigned integer) 1860 This field holds an alternate keynumber which is used by some 1861 notifications. 1863 auth_indication: 32 bits (unsigned integer) 1865 This field hold the error or indication being reported. The 1866 following values are currently defined: 1867 SCTP_AUTH_NEWKEY - this report indicates that a new key has been 1868 made active (used for the first time by the peer) and is now the 1869 active key. The auth_keynumber field holds the user specified key 1870 number. 1872 auth_assoc_id: sizeof (sctp_assoc_t) 1874 The association id field, holds the identifier for the association. 1875 All notifications for a given association have the same association 1876 identifier. 1878 6.3.1.9. SCTP_AUTHENTICATION_EVENT 1880 When an association is set up and the peer does not support SCTP-AUTH 1881 this notification is provided by the kernel to the user. 1883 struct sctp_no_auth_event { 1884 uint16_t no_auth_type; 1885 uint16_t no_auth_flags; 1886 uint32_t no_auth_length; 1887 sctp_assoc_t no_auth_assoc_id; 1888 }; 1890 no_auth_type 1892 It should be SCTP_NO_AUTHENTICATION_EVENT 1894 no_auth_flags: 16 bits (unsigned integer) 1896 Currently unused. 1898 no_auth_length: 32 bits (unsigned integer) 1900 This field is the total length of the notification data, including 1901 the notification header. It will generally be sizeof (struct 1902 sctp_no_auth_event). 1904 6.3.1.10. SCTP_SENDER_DRY_EVENT 1906 When an association is set up and the peer does not support SCTP-AUTH 1907 this notification is provided by the kernel to the user. 1909 struct sctp_sender_dry_event { 1910 uint16_t sender_dry_type; 1911 uint16_t sender_dry_flags; 1912 uint32_t sender_dry_length; 1913 sctp_assoc_t sender_dry_assoc_id; 1914 }; 1916 sender_dry_type: 1918 It should be SCTP_SENDER_DRY_EVENT 1920 sender_dry_flags: 16 bits (unsigned integer) 1922 Currently unused. 1924 sender_dry_length: 32 bits (unsigned integer) 1926 This field is the total length of the notification data, including 1927 the notification header. It will generally be sizeof (struct 1928 sctp_sender_dry_event). 1930 6.3.1.11. SCTP_AUTHENTICATION_FREE_KEY_EVENT 1932 When SCTP-AUTH wik not use a key identifier for sending packets 1933 anymore, this notification is provided by the kernel to the user. 1935 struct sctp_auth_free_key_event { 1936 uint16_t type; 1937 uint16_t flags; 1938 uint32_t length; 1939 uint16_t keynumber; 1940 sctp_assoc_t assoc_id; 1941 }; 1943 type: 1945 It should be SCTP_AUTHENTICATION_FREE_KEY_EVENT 1947 flags: 16 bits (unsigned integer) 1949 Currently unused. 1951 length: 32 bits (unsigned integer) 1953 This field is the total length of the notification data, including 1954 the notification header. It will generally be sizeof (struct 1955 sctp_auth_free_key_event). 1957 keynumber: 16 bits (unsigned integer) 1959 This field holds the keynumber set by the user for the effected key. 1961 6.4. Ancillary Data Considerations and Semantics 1963 Programming with ancillary socket data contains some subtleties and 1964 pitfalls, which are discussed below. 1966 6.4.1. Multiple Items and Ordering 1968 Multiple ancillary data items may be included in any call to 1969 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1970 items, or both. 1972 The ordering of ancillary data items (either by SCTP or another 1973 protocol) is not significant and is implementation-dependent, so 1974 applications must not depend on any ordering. 1976 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1977 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1978 sendmsg() or recvmsg() call. 1980 6.4.2. Accessing and Manipulating Ancillary Data 1982 Applications can infer the presence of data or ancillary data by 1983 examining the msg_iovlen and msg_controllen msghdr members, 1984 respectively. 1986 Implementations may have different padding requirements for ancillary 1987 data, so portable applications should make use of the macros 1988 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1989 [RFC3542] and your SCTP implementation's documentation for more 1990 information. Following is an example, from [RFC3542], demonstrating 1991 the use of these macros to access ancillary data: 1993 struct msghdr msg; 1994 struct cmsghdr *cmsgptr; 1996 /* fill in msg */ 1998 /* call recvmsg() */ 2000 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 2001 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 2002 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 2003 u_char *ptr; 2005 ptr = CMSG_DATA(cmsgptr); 2006 /* process data pointed to by ptr */ 2007 } 2008 } 2010 6.4.3. Control Message Buffer Sizing 2012 The information conveyed via SCTP_SNDRCV events will often be 2013 fundamental to the correct and sane operation of the sockets 2014 application. This is particularly true of the one-to-many semantics, 2015 but also of the one-ton-one semantics. For example, if an 2016 application needs to send and receive data on different SCTP streams, 2017 SCTP_SNDRCV events are indispensable. 2019 Given that some ancillary data is critical, and that multiple 2020 ancillary data items may appear in any order, applications should be 2021 carefully written to always provide a large enough buffer to contain 2022 all possible ancillary data that can be presented by recvmsg(). If 2023 the buffer is too small, and crucial data is truncated, it may pose a 2024 fatal error condition. 2026 Thus it is essential that applications be able to deterministically 2027 calculate the maximum required buffer size to pass to recvmsg(). One 2028 constraint imposed on this specification that makes this possible is 2029 that all ancillary data definitions are of a fixed length. One way 2030 to calculate the maximum required buffer size might be to take the 2031 sum the sizes of all enabled ancillary data item structures, as 2032 calculated by CMSG_SPACE. For example, if we enabled 2033 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC3542], we would calculate 2034 and allocate the buffer size as follows: 2036 size_t total; 2037 void *buf; 2039 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 2040 CMSG_SPACE(sizeof (struct in6_pktinfo)); 2042 buf = malloc(total); 2044 We could then use this buffer for msg_control on each call to 2045 recvmsg() and be assured that we would not lose any ancillary data to 2046 truncation. 2048 7. Common Operations for Both Styles 2050 7.1. send(), recv(), sendto(), recvfrom() 2052 Applications can use send() and sendto() to transmit data to the peer 2053 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2054 data from the peer. 2056 The syntax is: 2058 ssize_t send(int sd, const void *msg, size_t len, int flags); 2059 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 2060 const struct sockaddr *to, socklen_t tolen); 2061 ssize_t recv(int sd, void *buf, size_t len, int flags); 2062 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 2063 struct sockaddr *from, socklen_t *fromlen); 2065 sd - the socket descriptor of an SCTP endpoint. 2066 msg - the message to be sent. 2067 len - the size of the message or the size of buffer. 2068 to - one of the peer addresses of the association to be used to send 2069 the message. 2070 tolen - the size of the address. 2071 buf - the buffer to store a received message. 2072 from - the buffer to store the peer address used to send the 2073 received message. 2074 fromlen - the size of the from address 2075 flags - (described below). 2077 These calls give access to only basic SCTP protocol features. If 2078 either peer in the association uses multiple streams, or sends 2079 unordered data these calls will usually be inadequate, and may 2080 deliver the data in unpredictable ways. 2082 SCTP has the concept of multiple streams in one association. The 2083 above calls do not allow the caller to specify on which stream a 2084 message should be sent. The system uses stream 0 as the default 2085 stream for send() and sendto(). recv() and recvfrom() return data 2086 from any stream, but the caller can not distinguish the different 2087 streams. This may result in data seeming to arrive out of order. 2088 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2089 provide no indication. 2091 SCTP is message based. The msg buffer above in send() and sendto() 2092 is considered to be a single message. This means that if the caller 2093 wants to send a message which is composed by several buffers, the 2094 caller needs to combine them before calling send() or sendto(). 2095 Alternately, the caller can use sendmsg() to do that without 2096 combining them. Sending a message using send() or sendto() is atomic 2097 unless explicit EOR marking is enabled on the socket specified by sd. 2098 Using sendto() on a non-connected one-to-one style socket for 2099 implicit connection setup may or may not work depending on the SCTP 2100 implementation. recv() and recvfrom() cannot distinguish message 2101 boundaries. 2103 In receiving, if the buffer supplied is not large enough to hold a 2104 complete message, the receive call acts like a stream socket and 2105 returns as much data as will fit in the buffer. 2107 Note, the send() and recv() calls may not be used for a one-to-many 2108 style socket. 2110 Note, if an application calls a send function with no user data and 2111 no ancillary data the SCTP implementation should reject the request 2112 with an appropriate error message. An implementation is NOT allowed 2113 to send a Data chunk with no user data [RFC4960]. 2115 7.2. setsockopt(), getsockopt() 2117 Applications use setsockopt() and getsockopt() to set or retrieve 2118 socket options. Socket options are used to change the default 2119 behavior of sockets calls. They are described in Section 8 2121 The syntax is: 2123 ret = getsockopt(int sd, int level, int optname, void *optval, 2124 socklen_t *optlen); 2125 ret = setsockopt(int sd, int level, int optname, const void *optval, 2126 socklen_t optlen); 2128 sd - the socket descriptor. 2129 level - set to IPPROTO_SCTP for all SCTP options. 2130 optname - the option name. 2131 optval - the buffer to store the value of the option. 2132 optlen - the size of the buffer (or the length of the option 2133 returned). 2135 All socket options set on a 1-to-1 listening sockets also apply all 2136 accepted sockets. All socket options set on a 1-to-many socket using 2137 the assoc_id 0 applies for all future assocs on the socket. 2139 7.3. read() and write() 2141 Applications can use read() and write() to send and receive data to 2142 and from peer. They have the same semantics as send() and recv() 2143 except that the flags parameter cannot be used. 2145 Note, these calls, when used in the one-to-many style, may only be 2146 used with branched off socket descriptors (see Section 9.2). 2148 7.4. getsockname() 2150 Applications use getsockname() to retrieve the locally-bound socket 2151 address of the specified socket. This is especially useful if the 2152 caller let SCTP chose a local port. This call is for where the 2153 endpoint is not multi-homed. It does not work well with multi-homed 2154 sockets. See Section 9.5 for a multi-homed version of the call. 2156 The syntax is: 2158 int getsockname(int sd, struct sockaddr *address, 2159 socklen_t *len); 2161 sd - the socket descriptor to be queried. 2162 address - On return, one locally bound address (chosen by the SCTP 2163 stack) is stored in this buffer. If the socket is an IPv4 socket, 2164 the address will be IPv4. If the socket is an IPv6 socket, the 2165 address will be either an IPv6 or IPv4 address. 2166 len - The caller should set the length of address here. On return, 2167 this is set to the length of the returned address. 2169 If the actual length of the address is greater than the length of the 2170 supplied sockaddr structure, the stored address will be truncated. 2172 If the socket has not been bound to a local name, the value stored in 2173 the object pointed to by address is unspecified. 2175 8. Socket Options 2177 The following sub-section describes various SCTP level socket options 2178 that are common to both styles. SCTP associations can be multi- 2179 homed. Therefore, certain option parameters include a 2180 sockaddr_storage structure to select which peer address the option 2181 should be applied to. 2183 For the one-to-many style sockets, an sctp_assoc_t structure 2184 (association ID) is used to identify the association instance that 2185 the operation affects. So it must be set when using this style. 2187 For the one-to-one style sockets and branched off one-to-many style 2188 sockets (see Section 9.2) this association ID parameter is ignored. 2190 Note that socket or IP level options are set or retrieved per socket. 2191 This means that for one-to-many style sockets, those options will be 2192 applied to all associations belonging to the socket. And for one-to- 2193 one style, those options will be applied to all peer addresses of the 2194 association controlled by the socket. Applications should be very 2195 careful in setting those options. 2197 For some IP stacks getsockopt() is read-only; so a new interface will 2198 be needed when information must be passed both in to and out of the 2199 SCTP stack. The syntax for sctp_opt_info() is, 2201 int sctp_opt_info(int sd, 2202 sctp_assoc_t id, 2203 int opt, 2204 void *arg, 2205 socklen_t *size); 2207 The sctp_opt_info() call is a replacement for getsockopt() only and 2208 will not set any options associated with the specified socket. A 2209 setsockopt() must be used to set any writeable option. 2211 For one-to-many style sockets, id specifies the association to query. 2212 For one-to-one style sockets, id is ignored. 2214 opt specifies which SCTP socket option to get. It can get any socket 2215 option currently supported that requests information (either read/ 2216 write options or read only) such as: 2217 SCTP_RTOINFO 2218 SCTP_ASSOCINFO 2219 SCTP_DEFAULT_SEND_PARAM 2220 SCTP_GET_PEER_ADDR_INFO 2221 SCTP_PRIMARY_ADDR 2222 SCTP_PEER_ADDR_PARAMS 2223 SCTP_STATUS 2224 SCTP_CONTEXT 2225 SCTP_AUTH_ACTIVE_KEY 2226 SCTP_PEER_AUTH_CHUNKS 2227 SCTP_LOCAL_AUTH_CHUNKS 2229 arg is an option-specific structure buffer provided by the caller. 2230 See Section 9.5) subsections for more information on these options 2231 and option-specific structures. 2233 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2234 sets errno to the appropriate error code. 2236 All options that support specific settings on an association by 2237 filling in either an association id variable or a sockaddr_storage 2238 SHOULD also support setting of the same value for the entire endpoint 2239 (i.e. future associations). To accomplish this the following logic 2240 is used when setting one of these options: 2242 a) If an address is specified via a sockaddr_storage that is included 2243 in the structure, the address is used to lookup the association 2244 and the settings are applied to the specific address (if 2245 appropriate) or to the entire association. 2246 b) If an association identification is filled in but not a 2247 sockaddr_storage (if present), the association is found using the 2248 association identification and the settings should be applied to 2249 the entire association (since a specific address is not 2250 specified). Note this also applies to options that hold an 2251 association identification in their structure but do not have a 2252 sockaddr_storage field. 2254 c) If neither the sockaddr_storage or association identification is 2255 set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 2256 the association identification is 0, the settings are a default 2257 and to be applied to the endpoint (all future associations). 2259 8.1. Read / Write Options 2261 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2263 The protocol parameters used to initialize and bound retransmission 2264 timeout (RTO) are tunable. See [RFC4960] for more information on how 2265 these parameters are used in RTO calculation. 2267 The following structure is used to access and modify these 2268 parameters: 2270 struct sctp_rtoinfo { 2271 sctp_assoc_t srto_assoc_id; 2272 uint32_t srto_initial; 2273 uint32_t srto_max; 2274 uint32_t srto_min; 2275 }; 2277 srto_initial - This contains the initial RTO value. 2278 srto_max and srto_min - These contain the maximum and minimum bounds 2279 for all RTOs. 2280 srto_assoc_id - (one-to-many style socket) This is filled in the 2281 application, and identifies the association for this query. If 2282 this parameter is '0' (on a one-to-many style socket), then the 2283 change effects the entire endpoint. 2285 All parameters are time values, in milliseconds. A value of 0, when 2286 modifying the parameters, indicates that the current value should not 2287 be changed. 2289 To access or modify these parameters, the application should call 2290 getsockopt or setsockopt() respectively with the option name 2291 SCTP_RTOINFO. 2293 8.1.2. Association Parameters (SCTP_ASSOCINFO) 2295 This option is used to both examine and set various association and 2296 endpoint parameters. 2298 See [RFC4960] for more information on how this parameter is used. 2299 The sasoc_assoc_id parameter is ignored for one-to-one style socket. 2301 The following structure is used to access and modify this parameters: 2303 struct sctp_assocparams { 2304 sctp_assoc_t sasoc_assoc_id; 2305 uint16_t sasoc_asocmaxrxt; 2306 uint16_t sasoc_number_peer_destinations; 2307 uint32_t sasoc_peer_rwnd; 2308 uint32_t sasoc_local_rwnd; 2309 uint32_t sasoc_cookie_life; 2310 }; 2312 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2313 to make for the association. 2314 sasoc_number_peer_destinations - This is the number of destination 2315 addresses that the peer has. 2316 sasoc_peer_rwnd - This holds the current value of the peers rwnd 2317 (reported in the last SACK) minus any outstanding data (i.e. data 2318 inflight). 2319 sasoc_local_rwnd - This holds the last reported rwnd that was sent 2320 to the peer. 2321 sasoc_cookie_life - This is the associations cookie life value used 2322 when issuing cookies. 2323 sasoc_assoc_id - This is filled in the application, and identifies 2324 the association for this query. 2326 This information may be examined for either the endpoint or a 2327 specific association. To examine a endpoints default parameters the 2328 association id (sasoc_assoc_id) should must be set to the value '0'. 2329 The values of the sasoc_peer_rwnd is meaningless when examining 2330 endpoint information. 2332 All parameters are time values, in milliseconds. A value of 0, when 2333 modifying the parameters, indicates that the current value should not 2334 be changed. 2336 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2337 on either an endpoint or association basis. The rwnd and destination 2338 counts (sasoc_number_peer_destinations, 2339 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2340 placed in these is ignored. 2342 To access or modify these parameters, the application should call 2343 getsockopt or setsockopt() respectively with the option name 2344 SCTP_ASSOCINFO. 2346 The maximum number of retransmissions before an address is considered 2347 unreachable is also tunable, but is address-specific, so it is 2348 covered in a separate option. If an application attempts to set the 2349 value of the association maximum retransmission parameter to more 2350 than the sum of all maximum retransmission parameters, setsockopt() 2351 shall return an error. The reason for this, from [RFC4960] section 2352 8.2: 2354 Note: When configuring the SCTP endpoint, the user should avoid 2355 having the value of 'Association.Max.Retrans' larger than the 2356 summation of the 'Path.Max.Retrans' of all the destination addresses 2357 for the remote endpoint. Otherwise, all the destination addresses 2358 may become inactive while the endpoint still considers the peer 2359 endpoint reachable. 2361 8.1.3. Initialization Parameters (SCTP_INITMSG) 2363 Applications can specify protocol parameters for the default 2364 association initialization. The structure used to access and modify 2365 these parameters is defined in Section 6.2.1). The option name 2366 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2368 Setting initialization parameters is effective only on an unconnected 2369 socket (for one-to-many style sockets only future associations are 2370 effected by the change). With one-to-one style sockets, this option 2371 is inherited by sockets derived from a listener socket. 2373 8.1.4. SO_LINGER 2375 An application using the one-to-one style socket can use this option 2376 to perform the SCTP ABORT primitive. The linger option structure is: 2378 struct linger { 2379 int l_onoff; /* option on/off */ 2380 int l_linger; /* linger time */ 2381 }; 2383 To enable the option, set l_onoff to 1. If the l_linger value is set 2384 to 0, calling close() is the same as the ABORT primitive. If the 2385 value is set to a negative value, the setsockopt() call will return 2386 an error. If the value is set to a positive value linger_time, the 2387 close() can be blocked for at most linger_time ms. If the graceful 2388 shutdown phase does not finish during this period, close() will 2389 return but the graceful shutdown phase continues in the system. 2391 Note, this is a socket level option NOT an SCTP level option. So 2392 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2393 setsockopt() call. 2395 8.1.5. SCTP_NODELAY 2397 Turn on/off any Nagle-like algorithm. This means that packets are 2398 generally sent as soon as possible and no unnecessary delays are 2399 introduced, at the cost of more packets in the network. Expects an 2400 integer boolean flag. 2402 8.1.6. SO_RCVBUF 2404 Sets receive buffer size in octets. For SCTP one-to-one style 2405 sockets, this controls the receiver window size. For one-to-many 2406 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF 2407 (see Section 4.4). If the implementation defines HAVE_SCTP_MULTIBUF 2408 as 1, this controls the receiver window size for each association 2409 bound to the socket descriptor. If the implementation defines 2410 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive 2411 buffer for the whole socket. The call expects an integer. 2413 8.1.7. SO_SNDBUF 2415 Sets send buffer size. For SCTP one-to-one style sockets, this 2416 controls the amount of data SCTP may have waiting in internal buffers 2417 to be sent. This option therefore bounds the maximum size of data 2418 that can be sent in a single send call. For one-to-many style 2419 sockets, the effect is the same, except that it applies to one or all 2420 associations (see Section 4.4) bound to the socket descriptor used in 2421 the setsockopt() or getsockopt() call. The option applies to each 2422 association's window size separately. The call expects an integer. 2424 8.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) 2426 This socket option is applicable to the one-to-many style socket 2427 only. When set it will cause associations that are idle for more 2428 than the specified number of seconds to automatically close using the 2429 graceful shutdown procedure. An association being idle is defined as 2430 an association that has NOT sent or received user data. The special 2431 value of '0' indicates that no automatic close of any associations 2432 should be performed, this is the default value. The option expects 2433 an integer defining the number of seconds of idle time before an 2434 association is closed. 2436 An application using this option should enable receiving the 2437 association change notification. This is the only mechanism an 2438 application is informed about the closing of an association. After 2439 an association is closed, the association ID assigned to it can be 2440 reused. An application should be aware of this to avoid the possible 2441 problem of sending data to an incorrect peer end point. 2443 8.1.9. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2445 Requests that the peer mark the enclosed address as the association 2446 primary. The enclosed address must be one of the association's 2447 locally bound addresses. The following structure is used to make a 2448 set primary request: 2450 struct sctp_setpeerprim { 2451 sctp_assoc_t sspp_assoc_id; 2452 struct sockaddr_storage sspp_addr; 2453 }; 2455 sspp_addr - The address to set as primary 2456 sspp_assoc_id - This is filled in by the application, and identifies 2457 the association for this request. 2459 Note that this option really should be considered a write only option 2460 (not a read/write option) since it can NOT be passed to a 2461 getsockopt() call and is only valid when used with setsockopt() if 2462 the implementation supports this feature since this functionality is 2463 optional. Implementations that do not support this functionality 2464 should return EOPNOTSUPP. 2466 8.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) 2468 Requests that the local SCTP stack use the enclosed peer address as 2469 the association primary. The enclosed address must be one of the 2470 association peer's addresses. The following structure is used to 2471 make a set peer primary request: 2473 struct sctp_setprim { 2474 sctp_assoc_t ssp_assoc_id; 2475 struct sockaddr_storage ssp_addr; 2476 }; 2478 ssp_addr - The address to set as primary 2479 ssp_assoc_id - This is filled in by the application, and identifies 2480 the association for this request. 2482 8.1.11. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2484 Requests that the local endpoint set the specified Adaptation Layer 2485 Indication parameter for all future INIT and INIT-ACK exchanges. 2487 struct sctp_setadaptation { 2488 uint32_t ssb_adaptation_ind; 2489 }; 2491 ssb_adaptation_ind - The adaptation layer indicator that will be 2492 included in any outgoing Adaptation Layer Indication parameter. 2494 8.1.12. Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2496 This option is a on/off flag and is passed an integer where a non- 2497 zero is on and a zero is off. If enabled no SCTP message 2498 fragmentation will be performed. Instead if a message being sent 2499 exceeds the current PMTU size, the message will NOT be sent and 2500 instead a error will be indicated to the user. 2502 8.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2504 Applications can enable or disable heartbeats for any peer address of 2505 an association, modify an address's heartbeat interval, force a 2506 heartbeat to be sent immediately, and adjust the address's maximum 2507 number of retransmissions sent before an address is considered 2508 unreachable. The following structure is used to access and modify an 2509 address's parameters: 2511 struct sctp_paddrparams { 2512 sctp_assoc_t spp_assoc_id; 2513 struct sockaddr_storage spp_address; 2514 uint32_t spp_hbinterval; 2515 uint16_t spp_pathmaxrxt; 2516 uint32_t spp_pathmtu; 2517 uint32_t spp_flags; 2518 uint32_t spp_ipv6_flowlabel; 2519 uint8_t spp_ipv4_tos; 2520 }; 2522 spp_assoc_id - (one-to-many style socket) This is filled in the 2523 application, and identifies the association for this query. 2524 spp_address - This specifies which address is of interest. 2525 spp_hbinterval - This contains the value of the heartbeat interval, 2526 in milliseconds. Note that unless the spp_flag is set to 2527 SPP_HB_ENABLE the value of this field is ignored. Note also that 2528 a value of zero indicates the current setting should be left 2529 unchanged. To set an actual value of zero the use of the flag 2530 SPP_HB_TIME_IS_ZERO should be used. 2531 spp_pathmaxrxt - This contains the maximum number of retransmissions 2532 before this address shall be considered unreachable. Note that a 2533 value of zero indicates the current setting should be left 2534 unchanged. 2536 spp_pathmtu - When Path MTU discovery is disabled the value 2537 specified here will be the "fixed" path mtu (i.e. the value of the 2538 spp_flags field must include the flag SPP_PMTUD_DISABLE for this 2539 field to have any effect). Note that if the spp_address field is 2540 empty then all destinations for this association will have this 2541 fixed path mtu set upon them. If an address is specified, then 2542 only that address will be effected. Note also that this option 2543 cannot be set on the endpoint, but must be set on each individual 2544 association. Also, when disabling PMTU discovery, the 2545 implementation may disallow this behavior if the "fixed" path mtu 2546 is below the constant value SCTP_SMALLEST_PMTU. 2547 spp_ipv6_flowlabel- This field is used in conjunction with the 2548 SPP_IPV6_FLOWLABEL flag. 2549 spp_ipv4_tos- This field is used in conjunction with the 2550 SPP_IPV4_TOS flag. 2551 spp_flags- These flags are used to control various features on an 2552 association. The flag field is a bit mask which may contain zero 2553 or more of the following options: 2554 SPP_HB_ENABLE - Enable heartbeats on the specified address. Note 2555 that if the address field is empty all addresses for the 2556 association have heartbeats enabled upon them. 2557 SPP_HB_DISABLE - Disable heartbeats on the specified address. 2558 Note that if the address field is empty all addresses for the 2559 association will have their heartbeats disabled. Note also 2560 that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, 2561 only one of these two should be specified. Enabling both 2562 fields will have undetermined results. 2563 SPP_HB_DEMAND - Request a user initiated heartbeat to be made 2564 immediately. 2565 SPP_HB_TIME_IS_ZERO - Specify's that the time for heartbeat delay 2566 is to be set to the value of 0 milliseconds. 2567 SPP_PMTUD_ENABLE - This field will enable PMTU discovery upon the 2568 specified address. Note that if the address field is empty 2569 then all addresses on the association are effected. 2570 SPP_PMTUD_DISABLE - This field will disable PMTU discovery upon 2571 the specified address. Note that if the address field is empty 2572 then all addresses on the association are effected. Not also 2573 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2574 exclusive. Enabling both will have undetermined results. 2575 SPP_IPV6_FLOWLABEL - Setting this flag enables setting of the 2576 IPV6 flowlabel value associated with either the association or 2577 the specific address. If the address field is filled in, then 2578 the specific destination address has this value set upon it. 2579 If the association is specified, but not the address, then the 2580 flowlabel value is set for any future destination addresses 2581 that may be added. The value is obtained in the 2582 spp_ipv6_flowlabel field. 2584 Upon retrieval, this flag will be set to indicate that the 2585 spp_ipv6_flowlabel field has a valid value returned. If a 2586 specific destination addresses is set (in the spp_address 2587 field) when called then the value returned is that of the 2588 address. If just an association is specified (and no address) 2589 then the association default flowlabel is returned. If neither 2590 an association nor an destination is specified, then the 2591 sockets default flowlabel is returned. For non IPv6 sockets, 2592 then this flag will be left cleared. 2593 SPP_IPV4_TOS - Setting this flag enables setting of the IPV4 tos 2594 value associated with either the association or specific 2595 address. If the address field is filled in, then the specific 2596 destination address has this value set upon it. If the 2597 association is specified, but not the address, then the tos 2598 value is set for any future destination addresses that may be 2599 added. The value is obtained in the spp_ipv4_tos field. 2601 Upon retrieval, this flag will be set to indicate that the 2602 spp_ipv4_tos field has a valid value returned. If a specific 2603 destination addresses is set when called (in the spp_address 2604 field) then that specific destination addresses tos value is 2605 returned. If just an association is specified then the 2606 association default tos is returned. If neither an association 2607 nor an destination is specified, then the sockets default tos 2608 is returned. For non IPv4 sockets, then this flag will be left 2609 cleared. 2611 To read or modify these parameters, the application should call 2612 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2614 8.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 2616 Applications that wish to use the sendto() system call may wish to 2617 specify a default set of parameters that would normally be supplied 2618 through the inclusion of ancillary data. This socket option allows 2619 such an application to set the default sctp_sndrcvinfo structure. 2620 The application that wishes to use this socket option simply passes 2621 in to this call the sctp_sndrcvinfo structure defined in 2622 Section 6.2.2. The input parameters accepted by this call include 2623 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy 2624 and sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of 2625 SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field 2626 specifies the association to apply the parameters to in a one-to-many 2627 style sockets. It is ignored on the one-to-one style. Note that 2628 setting the sinfo_assoc_id field to zero indicates that the users 2629 wishes to set the endpoint default send parameters for all future 2630 associations. 2632 8.1.15. Set notification and ancillary events (SCTP_EVENTS) 2634 This socket option is used to specify various notifications and 2635 ancillary data the user wishes to receive. Please see Section 8.3) 2636 for a full description of this option and its usage. 2638 8.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2640 This socket option is a boolean flag which turns on or off mapped V4 2641 addresses. If this option is turned on and the socket is type 2642 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2643 If this option is turned off, then no mapping will be done of V4 2644 addresses and a user will receive both PF_INET6 and PF_INET type 2645 addresses on the socket. 2647 By default this option is turned off and expects an integer to be 2648 passed where non-zero turns on the option and zero turns off the 2649 option. 2651 8.1.17. Get or set the maximum fragmentation size (SCTP_MAXSEG) 2653 This option will get or set the maximum size to put in any outgoing 2654 SCTP DATA chunk. If a message is larger than this size it will be 2655 fragmented by SCTP into the specified size. Note that the underlying 2656 SCTP implementation may fragment into smaller sized chunks when the 2657 PMTU of the underlying association is smaller than the value set by 2658 the user. The default value for this option is '0' which indicates 2659 the user is NOT limiting fragmentation and only the PMTU will effect 2660 SCTP's choice of DATA chunk size. Note also that values set larger 2661 than the maximum size of an IP datagram will effectively let SCTP 2662 control fragmentation (i.e. the same as setting this option to 0). 2664 struct sctp_assoc_value { 2665 sctp_assoc_t assoc_id; 2666 uint32_t assoc_value; 2667 }; 2669 assoc_id - This parameter, indicates which association the user is 2670 performing an action upon. Note that if this field's value is 2671 zero then the endpoints default value is changed (effecting future 2672 associations only). 2673 assoc_value - This parameter specifies the maximum size in bytes. 2675 8.1.18. Add a chunk that must be authenticated (SCTP_AUTH_CHUNK) 2677 This set option adds a chunk type that the user is requesting to be 2678 received only in an authenticated way. Changes to the list of chunks 2679 will only effect future associations on the socket. 2681 struct sctp_authchunk { 2682 uint8_t sauth_chunk; 2683 }; 2685 sauth_chunks - This parameter contains a chunk type 2686 that the user is requesting to be authenticated. 2688 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 2689 chunks MUST NOT be used. If they are used an error MUST be returned. 2690 The usage of this option enables SCTP-AUTH in cases where it is not 2691 required by other means (for example the use of ADD-IP). 2693 Note that this option is write-only. Using this option in a 2694 getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. 2696 8.1.19. Get or set the list of supported HMAC Identifiers 2697 (SCTP_HMAC_IDENT) 2699 This option gets or sets the list of HMAC algorithms that the local 2700 endpoint requires the peer to use. 2702 struct sctp_hmacalgo { 2703 uint32_t shmac_number_of_idents; 2704 uint16_t shmac_idents[]; 2705 }; 2707 shmac_number_of_idents - This field gives the number of elements 2708 present in the array shmac_idents. 2709 shmac_idents - This parameter contains an array of HMAC Identifiers 2710 that the local endpoint is requesting the peer to use, in priority 2711 order. The following identifiers are valid: 2713 1) SCTP_AUTH_HMAC_ID_SHA1 2714 2) SCTP_AUTH_HMAC_ID_SHA256 (optional) 2715 3) SCTP_AUTH_HMAC_ID_SHA224 (optional) 2716 4) SCTP_AUTH_HMAC_ID_SHA384 (optional) 2717 4) SCTP_AUTH_HMAC_ID_SHA512 (optional) 2719 Note that the list supplied must include SHA1 and may include any 2720 of the other values in its preferred order (lowest list postion 2721 has the most preference in algorithm selection). Note also that 2722 the lack of SHA1, or the inclusion of an unknown HMAC identifier 2723 (including optional identifers unknown to the implementation) will 2724 cause the set option to fail and return an error. 2726 8.1.20. Set a shared key (SCTP_AUTH_KEY) 2728 This option will set a shared secret key which is used to build an 2729 association shared key. 2731 struct sctp_authkey { 2732 sctp_assoc_t sca_assoc_id; 2733 uint16_t sca_keynumber; 2734 uint16_t sca_keylength; 2735 uint8_t sca_key[]; 2736 }; 2738 sca_assoc_id - This parameter, if non-zero, indicates what 2739 association that the shared key is being set upon. Note that if 2740 this element contains zero, then the shared key is set upon the 2741 endpoint and all future associations will use this key (if not 2742 changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one 2743 sockets, this parameter is ignored. Note, however, that this 2744 option will set a key on the association if the socket is 2745 connected, otherwise this will set a key on the endpoint. 2746 sca_keynumber - this parameter is the shared key identifier by which 2747 the application will refer to this key. If a key of the specified 2748 index already exists, then this new key will replace the old 2749 existing key. Note that shared key identifier '0' defaults to a 2750 null key. 2751 sca_keylength - this parameter is the length of the array sca_key. 2752 sca_key - This parameter contains an array of bytes that is to be 2753 used by the endpoint (or association) as the shared secret key. 2754 Note, if the length of this field is zero, a null key is set. 2756 Note that this option is write-only. Using this option in a 2757 getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. 2759 8.1.21. Get or set the active shared key (SCTP_AUTH_ACTIVE_KEY) 2761 This option will get or set the active shared key to be used to build 2762 the association shared key. 2764 struct sctp_authkeyid { 2765 sctp_assoc_t scact_assoc_id; 2766 uint16_t scact_keynumber; 2767 }; 2769 scact_assoc_id - This parameter, if non-zero, indicates what 2770 association that the shared key identifier is being set active 2771 upon. Note that if this element contains zero, then the 2772 activation applies to the endpoint and all future associations 2773 will use the specified shared key identifier. For one-to-one 2774 sockets, this parameter is ignored. Note, however, that this 2775 option will set the active key on the association if the socket is 2776 connected, otherwise this will set the default active key for the 2777 endpoint. 2778 scact_keynumber - this parameter is the shared key identifier which 2779 the application is requesting to become the active shared key to 2780 be used for sending authenticated chunks. The key identifier MUST 2781 correspond to an existing shared key. Note that shared key 2782 identifier '0' defaults to a null key. 2783 When used with setsockopt() the SCTP implementation MUST use the 2784 indicated shared key identifier for all messages being sent after 2785 the setsockopt() call until changed again. Therefore the SCTP 2786 implementation MUST NOT bundle user messages which should be 2787 authenticated using different shared key identifiers. 2789 8.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) 2791 This set option will delete a shared secret key in the SCTP 2792 implementation. 2794 struct sctp_authkeyid { 2795 sctp_assoc_t scact_assoc_id; 2796 uint16_t scact_keynumber; 2797 }; 2799 scact_assoc_id - This parameter, if non-zero, indicates what 2800 association that the shared key identifier is being deleted from. 2801 Note that if this element contains zero, then the shared key is 2802 deleted from the endpoint and all associations will no longer use 2803 the specified shared key identifier (unless otherwise set on the 2804 association using SCTP_AUTH_KEY). For one-to-one sockets, this 2805 parameter is ignored. Note, however, that this option will delete 2806 the key from the association if the socket is connected, otherwise 2807 this will delete the key from the endpoint. 2809 scact_keynumber - this parameter is the shared key identifier which 2810 the application is requesting to be deleted. The key identifier 2811 MUST correspond to an existing shared key and MUST NOT be in use 2812 for any packet being sent by the SCTP implementation. This means 2813 in particular, that it MUST be deactivated first. Note if this 2814 parameter is zero, use of the null key identifier '0' is deleted 2815 from the endpoint and/or association. 2817 Note that this option is write-only. Using this option in a 2818 getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. 2820 8.1.23. Delete a shared key (SCTP_AUTH_DEACTIVATE_KEY) 2822 This set option indicates that the application will not send user 2823 messages anymore requiring the usage of the indicated key identifier. 2825 struct sctp_authkeyid { 2826 sctp_assoc_t scact_assoc_id; 2827 uint16_t scact_keynumber; 2828 }; 2830 scact_assoc_id - This parameter, if non-zero, indicates what 2831 association that the shared key identifier is being deactivated. 2832 Note that if this element contains zero, then the shared key is 2833 deactivated for the endpoint and all associations will no longer 2834 use the specified shared key identifier (unless otherwise set on 2835 the association using SCTP_AUTH_KEY). For one-to-one sockets, 2836 this parameter is ignored. Note, however, that this option will 2837 deactivate the key from the association if the socket is 2838 connected, otherwise this will deactivate the key from the 2839 endpoint. 2840 scact_keynumber - this parameter is the shared key identifier which 2841 the application is requesting to be deactivated. The key 2842 identifier MUST correspond to an existing shared key. Note if 2843 this parameter is zero, use of the null key identifier '0' is 2844 deactivated on the endpoint and/or association. 2846 Note that this option is write-only. Using this option in a 2847 getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. 2849 8.1.24. Get or set delayed ack timer (SCTP_DELAYED_SACK) 2851 This option will effect the way delayed acks are performed. This 2852 option allows you to get or set the delayed ack time, in 2853 milliseconds. It also allows changing the delayed ack frequency. 2854 Changing the frequency to 1 disables the delayed sack algorithm. If 2855 the assoc_id is 0, then this sets or gets the endpoints default 2856 values. If the assoc_id field is non-zero, then the set or get 2857 effects the specified association for the one to many model (the 2858 assoc_id field is ignored by the one to one model). Note that if 2859 sack_delay or sack_freq are 0 when setting this option, then the 2860 current values will remain unchanged. 2862 struct sctp_sack_info { 2863 sctp_assoc_t sack_assoc_id; 2864 uint32_t sack_delay; 2865 uint32_t sack_freq; 2866 }; 2868 sack_assoc_id - This parameter, indicates which association the user 2869 is performing an action upon. Note that if this field's value is 2870 zero then the endpoints default value is changed (effecting future 2871 associations only). 2872 sack_delay - This parameter contains the number of milliseconds that 2873 the user is requesting the delayed ACK timer be set to. Note that 2874 this value is defined in the standard to be between 200 and 500 2875 milliseconds. 2876 sack_freq - This parameter contains the number of packets that must 2877 be received before a sack is sent without waiting for the delay 2878 timer to expire. The default value for this is 2, setting this 2879 value to 1 will disable the delayed sack algorithm. 2881 8.1.25. Get or set fragmented interleave (SCTP_FRAGMENT_INTERLEAVE) 2883 Fragmented interleave controls how the presentation of messages 2884 occurs for the message receiver. There are three levels of fragment 2885 interleave defined. Two of the levels effect the one-to-one model, 2886 while the one-to-many model is effected by all three levels. 2888 This option takes an integer value. It can be set to a value of 0, 1 2889 or 2. Attempting to set this level to other values will return an 2890 error. 2892 Setting the three levels provides the following receiver 2893 interactions: 2895 level 0 - Prevents the interleaving of any messages. This means 2896 that when a partial delivery begins, no other messages will be 2897 received except the message being partially delivered. If another 2898 message arrives on a different stream (or association) that could 2899 be delivered, it will be blocked waiting for the user to read all 2900 of the partially delivered message. 2902 level 1 - Allows interleaving of messages that are from different 2903 associations. For the one-to-one model, level 0 and level 1 thus 2904 have the same meaning since a one-to-one socket always receives 2905 messages from the same association. Note that setting the one-to- 2906 many model to this level may cause multiple partial delivers from 2907 different associations but for any given association, only one 2908 message will be delivered until all parts of a message have been 2909 delivered. This means that one large message, being read with an 2910 association identification of "X", will block other messages from 2911 association "X" from being delivered. 2912 level 2 - Allows complete interleaving of messages. This level 2913 requires that the sender carefully observe not only the peer 2914 association identification (or address) but also must pay careful 2915 attention to the stream number. With this option enabled a 2916 partially delivered message may begin being delivered for 2917 association "X" stream "Y" and the next subsequent receive may 2918 return a message from association "X" stream "Z". Note that no 2919 other messages would be delivered for association "X" stream "Y" 2920 until all of stream "Y"'s partially delivered message was read. 2921 Note that this option also effects the one-to-one model. Also 2922 note that for the one-to-many model not only may another streams 2923 message from the same association be delivered from the next 2924 receive, some other associations message may be delivered upon the 2925 next receive. 2927 An implementation should default the one-to-many model to level 1. 2928 The reason for this is that otherwise it is possible that a peer 2929 could begin sending a partial message and thus block all other peers 2930 from sending data. However a setting of level 2 requires the 2931 application to not only be aware of the association (via the 2932 association id or peers address) but also the stream number. The 2933 stream number is NOT present unless the user has subscribed to the 2934 sctp_data_io_events (see Section 8.3). This is also why we recommend 2935 that the one-to-one model be defaulted to level 0 (level 1 for the 2936 one-to-one model has no effect). Note that an implementation should 2937 return an error if a application attempts to set the level to 2 and 2938 has NOT subscribed to the sctp_data_io_events. 2940 8.1.26. Set or Get the sctp partial delivery point 2941 (SCTP_PARTIAL_DELIVERY_POINT) 2943 This option will set or get the SCTP partial delivery point. This 2944 point is the size of a message where the partial delivery API will be 2945 invoked to help free up rwnd space for the peer. Setting this to a 2946 lower value will cause partial deliveries to happen more often. The 2947 calls argument is an integer that sets or gets the partial delivery 2948 point. Note also that the call will fail if the user attempts to set 2949 this value larger than the socket receive buffer size. 2951 Note that any single message having a length smaller than or equal to 2952 the SCTP partial delivery point will be delivered in one single read 2953 call as long as the user provided buffer is large enough to hold the 2954 message. 2956 8.1.27. Set or Get the use of extended receive info 2957 (SCTP_USE_EXT_RCVINFO) 2959 This option will enable or disable the use of the extended version of 2960 the sctp_sndrcvinfo structure. If this option is disabled, then the 2961 normal sctp_sndrcvinfo structure is returned in all receive message 2962 calls. If this option is enabled then the sctp_extrcvinfo structure 2963 is returned in all receive message calls. 2965 Note that the sctp_extrcvinfo structure is never used in any send 2966 call. 2968 8.1.28. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) 2970 This option will enable or disable the use of the automatic 2971 generation of ASCONF chunks to add and delete addresses to an 2972 existing association. Note that this option has two caveats namely: 2973 a) it only effects sockets that are bound to all addresses on the 2974 machine, and b) the system administrator may have an overriding 2975 control that turns the asconf feature off no matter what setting the 2976 socket option may have. 2978 8.1.29. Set or Get the maximum burst (SCTP_MAX_BURST) 2980 This option will allow a user to change the maximum burst of packets 2981 that can be emitted by this association. Note that the default value 2982 is 4, and some implementations may restrict this setting so that it 2983 can only be lowered. 2985 To set or get this option the user fills in the following structure: 2987 struct sctp_assoc_value { 2988 sctp_assoc_t assoc_id; 2989 uint32_t assoc_value; 2990 }; 2992 assoc_id - This parameter, indicates which association the user is 2993 performing an action upon. Note that if this field's value is 2994 zero then the endpoints default value is changed (effecting future 2995 associations only). 2997 assoc_value - This parameter contains the maximum burst. 2999 8.1.30. Set or Get the default context (SCTP_CONTEXT) 3001 The context field in the sctp_sndrcvinfo structure is normally only 3002 used when a failed message is retrieved holding the value that was 3003 sent down on the actual send call. This option allows the setting of 3004 a default context on an association basis that will be received on 3005 reading messages from the peer. This is especially helpful in the 3006 one-2-many model for an application to keep some reference to an 3007 internal state machine that is processing messages on the 3008 association. Note that the setting of this value only effects 3009 received messages from the peer and does not effect the value that is 3010 saved with outbound messages. 3012 To set or get this option the user fills in the following structure: 3014 struct sctp_assoc_value { 3015 sctp_assoc_t assoc_id; 3016 uint32_t assoc_value; 3017 }; 3019 assoc_id - This parameter, indicates which association the user is 3020 performing an action upon. Note that if this field's value is 3021 zero then the endpoints default value is changed (effecting future 3022 associations only). 3023 assoc_value - This parameter contains the context. 3025 8.1.31. Enable or disable explicit EOR marking (SCTP_EXPLICIT_EOR) 3027 This boolean flag is used to enable or disable explict end of record 3028 (EOR) marking. When this option is enabled, a user may make multiple 3029 send system calls to send a record and must indicate that they are 3030 finished sending a particular record by including on the send the 3031 SCTP_EOR flag. If this boolean flag is disabled then each individual 3032 send system call is considered to have a SCTP_EOR indicator set on it 3033 implicitly without the user having to explicitly add this flag. 3035 8.1.32. Enable SCTP port reusage (SCTP_REUSE_PORT) 3037 This option only supports one-to-one style SCTP sockets. If used on 3038 a one-to-many style SCTP socket an error is indicated. 3040 The setsockopt() call MUST NOT be used after calling bind() or 3041 sctp_bindx() for an one-to-one style SCTP socket. If using bind() or 3042 sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other 3043 SCTP sockets bound to the same port MUST have set the 3044 SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without 3045 having set the SCTP_REUSE_PORT option will fail if there are other 3046 sockets bound to the same port. At most one socket being bound to 3047 the same port may be listening. 3049 It should be noted that the behaviour of the socket level socket 3050 option to reuse ports and/or addresses for SCTP sockets in 3051 unspecified. 3053 8.2. Read-Only Options 3055 8.2.1. Association Status (SCTP_STATUS) 3057 Applications can retrieve current status information about an 3058 association, including association state, peer receiver window size, 3059 number of unacked data chunks, and number of data chunks pending 3060 receipt. This information is read-only. The following structure is 3061 used to access this information: 3063 struct sctp_status { 3064 sctp_assoc_t sstat_assoc_id; 3065 int32_t sstat_state; 3066 uint32_t sstat_rwnd; 3067 uint16_t sstat_unackdata; 3068 uint16_t sstat_penddata; 3069 uint16_t sstat_instrms; 3070 uint16_t sstat_outstrms; 3071 uint32_t sstat_fragmentation_point; 3072 struct sctp_paddrinfo sstat_primary; 3073 }; 3075 sstat_state - This contains the association's current state one of 3076 the following values: 3077 SCTP_CLOSED 3078 SCTP_BOUND 3079 SCTP_LISTEN 3080 SCTP_COOKIE_WAIT 3081 SCTP_COOKIE_ECHOED 3082 SCTP_ESTABLISHED 3083 SCTP_SHUTDOWN_PENDING 3084 SCTP_SHUTDOWN_SENT 3085 SCTP_SHUTDOWN_RECEIVED 3086 SCTP_SHUTDOWN_ACK_SENT 3087 sstat_rwnd - This contains the association peer's current receiver 3088 window size. 3089 sstat_unackdata - This is the number of unacked data chunks. 3090 sstat_penddata - This is the number of data chunks pending receipt. 3091 sstat_primary - This is information on the current primary peer 3092 address. 3093 sstat_assoc_id - (one-to-many style socket) This holds the an 3094 identifier for the association. All notifications for a given 3095 association have the same association identifier. 3096 sstat_instrms - The number of streams that the peer will be using 3097 inbound. 3098 sstat_outstrms - The number of streams that the endpoint is allowed 3099 to use outbound. 3100 sstat_fragmentation_point - The size at which SCTP fragmentation 3101 will occur. 3103 To access these status values, the application calls getsockopt() 3104 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 3105 ignored for one-to-one style socket. 3107 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 3109 Applications can retrieve information about a specific peer address 3110 of an association, including its reachability state, congestion 3111 window, and retransmission timer values. This information is read- 3112 only. The following structure is used to access this information: 3114 struct sctp_paddrinfo { 3115 sctp_assoc_t spinfo_assoc_id; 3116 struct sockaddr_storage spinfo_address; 3117 int32_t spinfo_state; 3118 uint32_t spinfo_cwnd; 3119 uint32_t spinfo_srtt; 3120 uint32_t spinfo_rto; 3121 uint32_t spinfo_mtu; 3122 }; 3124 spinfo_address - This is filled in the application, and contains the 3125 peer address of interest. 3127 On return from getsockopt(): 3129 spinfo_state - This contains the peer addresses's state (either 3130 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 3131 SCTP_UNCONFIRMED) 3132 spinfo_cwnd - This contains the peer addresses's current congestion 3133 window. 3134 spinfo_srtt - This contains the peer addresses's current smoothed 3135 round-trip time calculation in milliseconds. 3136 spinfo_rto - This contains the peer addresses's current 3137 retransmission timeout value in milliseconds. 3138 spinfo_mtu - The current P-MTU of this address. 3139 spinfo_assoc_id - This is field may be filled in by the application, 3140 if so, this field will have priority in looking up the association 3141 over the address specified in spinfo_address. Note that if the 3142 address does not belong to the association specified then this 3143 call will fail. If the application does NOT fill in the 3144 spinfo_assoc_id, then the address will be used to lookup the 3145 association and on return this field will have the valid 3146 association id. In other words, this call can be used to 3147 translate a address into an association id. 3149 To retrieve this information, use sctp_opt_info() with the 3150 SCTP_GET_PEER_ADDR_INFO options. 3152 8.2.3. Get the list of chunks the peer requires to be authenticated 3153 (SCTP_PEER_AUTH_CHUNKS) 3155 This option gets a list of chunks for a specified association that 3156 the peer requires to be received authenticated only. 3158 struct sctp_authchunks { 3159 sctp_assoc_t gauth_assoc_id; 3160 guint32_t gauth_number_of_chunks 3161 uint8_t gauth_chunks[]; 3162 }; 3164 gauth_assoc_id - This parameter, indicates which association the 3165 user is requesting the list of peer authenticated chunks. For 3166 one-to-one sockets, this parameter is ignored. 3167 gauth_number_of_chunks - This parameter gives the number of elements 3168 in the array gauth_chunks. 3169 gauth_chunks - This parameter contains an array of chunks that the 3170 peer is requesting to be authenticated. 3172 8.2.4. Get the list of chunks the local endpoint requires to be 3173 authenticated (SCTP_LOCAL_AUTH_CHUNKS) 3175 This option gets a list of chunks for a specified association that 3176 the local endpoint requires to be received authenticated only. 3178 struct sctp_authchunks { 3179 sctp_assoc_t gauth_assoc_id; 3180 uint32_t gauth_number_of_chunks; 3181 uint8_t gauth_chunks[]; 3182 }; 3184 gauth_assoc_id - This parameter, indicates which association the 3185 user is requesting the list of local authenticated chunks. For 3186 one-to-one sockets, this parameter is ignored. 3187 gauth_number_of_chunks - This parameter gives the number of elements 3188 in the array gauth_chunks. 3189 gauth_chunks - This parameter contains an array of chunks that the 3190 local endpoint is requesting to be authenticated. 3192 8.2.5. Get the current number of associations (SCTP_GET_ASSOC_NUMBER) 3194 This option gets the current number of associations that are attached 3195 to a one-to-many style socket. The option value is an uint32_t. 3197 8.2.6. Get the current identifiers of associations 3198 (SCTP_GET_ASSOC_ID_LIST) 3200 This option gets the current list of SCTP association identifiers of 3201 the SCTP associations handled by a one-to-many style socket. The 3202 option value has the structure 3204 struct sctp_assoc_ids { 3205 uint32_t gaids_number_of_ids; 3206 sctp_assoc_t gaids_assoc_id[]; 3207 }; 3209 The caller MUST provide a large enough buffer to hold all association 3210 identifiers. If the buffer is too small, an error MUST be returned. 3211 The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an 3212 idea how large the buffer has to be. gaids_number_of_ids gives the 3213 number of elements in the array gaids_assoc_id. 3215 8.3. Ancillary Data and Notification Interest Options 3217 Applications can receive per-message ancillary information and 3218 notifications of certain SCTP events with recvmsg(). 3220 The following optional information is available to the application: 3222 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3223 stream number, TSN, SSN, etc. described in Section 6.2.2) 3224 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in 3225 Section 6.3.1.1) 3226 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in 3227 Section 6.3.1.2) 3228 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in 3229 Section 6.3.1.4) 3230 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in 3231 Section 6.3.1.3) 3232 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in 3233 Section 6.3.1.5) 3234 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 3235 (described in Section 6.3.1.7) 3236 8. SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): 3237 (described in Section 6.3.1.6) 3238 9. SCTP_AUTHENTICATION_INDICATION (sctp_authentication_event): 3239 (described in Section 6.3.1.8) 3241 To receive any ancillary data or notifications, first the application 3242 registers it's interest by calling the SCTP_EVENTS setsockopt() with 3243 the following structure. 3245 struct sctp_event_subscribe{ 3246 uint8_t sctp_data_io_event; 3247 uint8_t sctp_association_event; 3248 uint8_t sctp_address_event; 3249 uint8_t sctp_send_failure_event; 3250 uint8_t sctp_peer_error_event; 3251 uint8_t sctp_shutdown_event; 3252 uint8_t sctp_partial_delivery_event; 3253 uint8_t sctp_adaptation_layer_event; 3254 uint8_t sctp_authentication_event; 3255 }; 3257 sctp_data_io_event - Setting this flag to 1 will cause the reception 3258 of SCTP_SNDRCV information on a per message basis. The application 3259 will need to use the recvmsg() interface so that it can receive the 3260 event information contained in the msg_control field. Please see 3261 Section 6.2 for further details. Setting the flag to 0 will disable 3262 reception of the message control information. 3264 sctp_association_event - Setting this flag to 1 will enable the 3265 reception of association event notifications. Setting the flag to 0 3266 will disable association event notifications. For more information 3267 on event notifications please see Section 6.3. 3269 sctp_address_event - Setting this flag to 1 will enable the reception 3270 of address event notifications. Setting the flag to 0 will disable 3271 address event notifications. For more information on event 3272 notifications please see Section 6.3. 3274 sctp_send_failure_event - Setting this flag to 1 will enable the 3275 reception of send failure event notifications. Setting the flag to 0 3276 will disable send failure event notifications. For more information 3277 on event notifications please see Section 6.3. 3279 sctp_peer_error_event - Setting this flag to 1 will enable the 3280 reception of peer error event notifications. Setting the flag to 0 3281 will disable peer error event notifications. For more information on 3282 event notifications please see Section 6.3. 3284 sctp_shutdown_event - Setting this flag to 1 will enable the 3285 reception of shutdown event notifications. Setting the flag to 0 3286 will disable shutdown event notifications. For more information on 3287 event notifications please see Section 6.3. 3289 sctp_partial_delivery_event - Setting this flag to 1 will enable the 3290 reception of partial delivery notifications. Setting the flag to 0 3291 will disable partial delivery event notifications. For more 3292 information on event notifications please see Section 6.3. 3294 sctp_adaptation_layer_event - Setting this flag to 1 will enable the 3295 reception of adaptation layer notifications. Setting the flag to 0 3296 will disable adaptation layer event notifications. For more 3297 information on event notifications please see Section 6.3. 3299 sctp_authentication_event - Setting this flag to 1 will enable the 3300 reception of authentication layer notifications. Setting the flag to 3301 0 will disable authentication layer event notifications. For More 3302 information please see Section 6.3. 3304 An example where an application would like to receive data io events 3305 and association events but no others would be as follows: 3307 { 3308 struct sctp_event_subscribe event; 3310 memset(&event,0,sizeof(event)); 3312 event.sctp_data_io_event = 1; 3313 event.sctp_association_event = 1; 3315 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event)); 3316 } 3318 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3319 receives ancillary data and notifications for ALL associations bound 3320 to the file descriptor. For one-to-one style SCTP sockets, the 3321 caller receives ancillary data and notifications for only the single 3322 association bound to the file descriptor. 3324 By default both the one-to-one style and one-to-many style socket has 3325 all options off. 3327 9. New Interfaces 3329 Depending on the system, the following interface can be implemented 3330 as a system call or library function. 3332 9.1. sctp_bindx() 3334 The syntax of sctp_bindx() is, 3336 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt, 3337 int flags); 3339 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3340 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3341 or IPv6 addresses. 3343 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3344 Section 4.1.2 for this usage. 3346 addrs is a pointer to an array of one or more socket addresses. Each 3347 address is contained in its appropriate structure. For an IPv6 3348 socket, an array of sockaddr_in6 would be returned. For a IPv4 3349 socket, an array of sockaddr_in would be returned. The caller 3350 specifies the number of addresses in the array with addrcnt. Note 3351 that the wildcard addresses cannot be used in combination with non 3352 wildcard addresses on a socket with this function, doing so will 3353 result in an error. 3355 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3356 -1, and sets errno to the appropriate error code. 3358 For SCTP, the port given in each socket address must be the same, or 3359 sctp_bindx() will fail, setting errno to EINVAL. 3361 The flags parameter is formed from the bitwise OR of zero or more of 3362 the following currently defined flags: 3364 SCTP_BINDX_ADD_ADDR 3366 SCTP_BINDX_REM_ADDR 3368 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3369 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3370 addresses from the association. The two flags are mutually 3371 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3372 caller may not remove all addresses from an association; sctp_bindx() 3373 will reject such an attempt with EINVAL. 3375 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3376 additional addresses with an endpoint after calling bind(). Or use 3377 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3378 socket is associated with so that no new association accepted will be 3379 associated with those addresses. If the endpoint supports dynamic 3380 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 3381 endpoint to send the appropriate message to the peer to change the 3382 peers address lists. 3384 Adding and removing addresses from a connected association is 3385 optional functionality. Implementations that do not support this 3386 functionality should return EOPNOTSUPP. 3388 sctp_bindx() can be called on an already bound socket or on an 3389 unbound socket. If the socket is unbound and the first port number 3390 in the addrs is zero, the kernel will chose a port number. All port 3391 numbers after the first one being 0 MUST also be zero. If the first 3392 port number is not zero, the following port numbers MUST be zero or 3393 have the same value as the first one. For an already bound socket, 3394 all port numbers provided MUST be the bound one or 0. 3396 bindx() is an atomic operation. Therefore the binding will be either 3397 successful on all addresses or fail on all addresses. If multiple 3398 addresses are provided and the bindx() call fails there is no 3399 indication which address is responsable for the failure. The only 3400 way to get an specific error indication is to call bindx() with only 3401 one address sequentially. 3403 9.2. Branched-off Association 3405 After an association is established on a one-to-many style socket, 3406 the application may wish to branch off the association into a 3407 separate socket/file descriptor. 3409 This is particularly desirable when, for instance, the application 3410 wishes to have a number of sporadic message senders/receivers remain 3411 under the original one-to-many style socket but branch off those 3412 associations carrying high volume data traffic into their own 3413 separate socket descriptors. 3415 The application uses sctp_peeloff() call to branch off an association 3416 into a separate socket (Note the semantics are somewhat changed from 3417 the traditional one-to-one style accept() call). Note that the new 3418 socket is a one-to-one style socket. Thus it will be confined to 3419 operations allowed for a one-to-one style socket. 3421 The syntax is: 3423 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id); 3425 new_sd: the new socket descriptor representing the branched-off 3426 association. 3427 sd: the original one-to-many style socket descriptor returned from 3428 the socket() system call (see Section 4.1.1). 3429 assoc_id: the specified identifier of the association that is to be 3430 branched off to a separate file descriptor (Note, in a traditional 3431 one-to-one style accept() call, this would be an out parameter, 3432 but for the one-to-many style call, this is an in parameter). 3434 9.3. sctp_getpaddrs() 3436 sctp_getpaddrs() returns all peer addresses in an association. The 3437 syntax is, 3439 int sctp_getpaddrs(int sd, sctp_assoc_t id, 3440 struct sockaddr **addrs); 3442 On return, addrs will point to an array dynamically allocated 3443 sockaddr structures of the appropriate type for the socket type. The 3444 caller should use sctp_freepaddrs() to free the memory. Note that 3445 the in/out parameter addrs must not be NULL. 3447 If sd is an IPv4 socket, the addresses returned will be all IPv4 3448 addresses. If sd is an IPv6 socket, the addresses returned can be a 3449 mix of IPv4 or IPv6 addresses. 3451 For one-to-many style sockets, id specifies the association to query. 3452 For one-to-one style sockets, id is ignored. 3454 On success, sctp_getpaddrs() returns the number of peer addresses in 3455 the association. If there is no association on this socket, 3456 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3457 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3458 is undefined. 3460 9.4. sctp_freepaddrs() 3462 sctp_freepaddrs() frees all resources allocated by 3463 sctp_getpaddrs(). Its syntax is, 3465 void sctp_freepaddrs(struct sockaddr *addrs); 3466 addrs is the array of peer addresses returned by sctp_getpaddrs(). 3468 9.5. sctp_getladdrs() 3470 sctp_getladdrs() returns all locally bound address(es) on a socket. 3471 The syntax is, 3473 int sctp_getladdrs(int sd, sctp_assoc_t id, 3474 struct sockaddr **ss); 3476 On return, addrs will point to a dynamically allocated array of 3477 sockaddr structures of the appropriate type for the socket type. The 3478 caller should use sctp_freeladdrs() to free the memory. Note that 3479 the in/out parameter addrs must not be NULL. 3481 If sd is an IPv4 socket, the addresses returned will be all IPv4 3482 addresses. If sd is an IPv6 socket, the addresses returned can be a 3483 mix of IPv4 or IPv6 addresses. 3485 For one-to-many style sockets, id specifies the association to query. 3486 For one-to-one style sockets, id is ignored. 3488 If the id field is set to the value '0' then the locally bound 3489 addresses are returned without regard to any particular association. 3491 On success, sctp_getladdrs() returns the number of local addresses 3492 bound to the socket. If the socket is unbound, sctp_getladdrs() 3493 returns 0, and the value of *addrs is undefined. If an error occurs, 3494 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3496 9.6. sctp_freeladdrs() 3498 sctp_freeladdrs() frees all resources allocated by 3499 sctp_getladdrs(). Its syntax is, 3501 void sctp_freeladdrs(struct sockaddr *addrs); 3503 addrs is the array of peer addresses returned by sctp_getladdrs(). 3505 9.7. sctp_sendmsg() 3507 An implementation may provide a library function (or possibly system 3508 call) to assist the user with the advanced features of SCTP. 3510 sctp_sendmsg(). Its syntax is, 3512 ssize_t sctp_sendmsg(int sd, 3513 const void *msg, 3514 size_t len, 3515 const struct sockaddr *to, 3516 socklen_t tolen, 3517 uint32_t ppid, 3518 uint32_t flags, 3519 uint16_t stream_no, 3520 uint32_t pr_value, 3521 uint32_t context) 3523 sd - is the socket descriptor 3524 msg - is the message to be sent. 3525 len - is the length of the message. 3526 to - is the destination address of the message. 3527 tolen - is the length of the destination address. 3528 ppid - is the same as sinfo_ppid (see section 5.2.2) 3529 flags - is the same as sinfo_flags (see section 5.2.2) 3530 stream_no - is the same as sinfo_stream (see section 5.2.2) 3531 pr_value - is the same as sinfo_pr_value (see section 5.2.2). 3532 context - is the same as sinfo_context (see section 5.2.2) 3533 The call returns the number of characters sent, or -1 if an error 3534 occurred. The variable errno is then set appropriately. Sending a 3535 message using sctp_sendmsg() is atomic unless explicit EOR marking is 3536 enabled on the socket specified by sd. Using sendto() on a non- 3537 connected one-to-one style socket for implicit connection setup may 3538 or may not work depending on the SCTP implementation. 3540 9.8. sctp_recvmsg() 3542 An implementation may provide a library function (or possibly system 3543 call) to assist the user with the advanced features of SCTP. Note 3544 that in order for the sctp_sndrcvinfo structure to be filled in by 3545 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3546 the SCTP_EVENTS option. Note that the setting of the 3547 SCTP_USE_EXT_RCVINFO will effect this function as well, causing the 3548 sctp_sndrcvinfo information to be extended. 3550 sctp_recvmsg(). Its syntax is, 3552 ssize_t sctp_recvmsg(int sd, 3553 void *msg, 3554 size_t len, 3555 struct sockaddr *from, 3556 socklen_t *fromlen 3557 struct sctp_sndrcvinfo *sinfo 3558 int *msg_flags) 3560 sd - is the socket descriptor 3561 msg - is a message buffer to be filled. 3562 len - is the length of the message buffer. 3563 from - is a pointer to a address to be filled with the sender of 3564 this messages address. 3565 fromlen - is the from length. 3566 sinfo - A pointer to a sctp_sndrcvinfo structure to be filled upon 3567 receipt of the message. 3568 msg_flags - A pointer to a integer to be filled with any message 3569 flags (e.g. MSG_NOTIFICATION). 3570 The call returns the number of bytes received, or -1 if an error 3571 occurred. The variable errno is then set appropriately. 3573 9.9. sctp_connectx() 3575 An implementation may provide a library function (or possibly system 3576 call) to assist the user with associating to an endpoint that is 3577 multi-homed. Much like sctp_bindx() this call allows a caller to 3578 specify multiple addresses at which a peer can be reached. The way 3579 the SCTP stack uses the list of addresses to set up the association 3580 is implementation dependent. This function only specifies that the 3581 stack will try to make use of all the addresses in the list when 3582 needed. 3584 Note that the list of addresses passed in is only used for setting up 3585 the association. It does not necessarily equal the set of addresses 3586 the peer uses for the resulting association. If the caller wants to 3587 find out the set of peer addresses, it must use sctp_getpaddrs() to 3588 retrieve them after the association has been set up. 3590 sctp_connectx(). Its syntax is, 3592 int sctp_connectx(int sd, 3593 struct sockaddr *addrs, 3594 int addrcnt, 3595 sctp_assoc_t *id) 3597 sd - is the socket descriptor 3598 addrs - is an array of addresses. 3599 addrcnt - is the number of addresses in the array. 3600 id - is an output parameter that if passed in as a non-NULL will 3601 return the association identification for the newly created 3602 association (if successful). 3604 The call returns 0 on success or -1 if an error occurred. The 3605 variable errno is then set appropriately. 3607 9.10. sctp_send() 3609 An implementation may provide another alternative function or system 3610 call to assist an application with the sending of data without the 3611 use of the CMSG header structures. The function takes the following 3612 form: 3614 sctp_send(). Its syntax is, 3616 int sctp_send(int sd, 3617 const void *msg, 3618 size_t len, 3619 const struct sctp_sndrcvinfo *sinfo, 3620 int flags); 3622 sd - is the socket descriptor 3623 msg - The message to be sent 3624 len - The length of the message 3625 sinfo - A pointer to a sctp_sndrcvinfo structure used as described 3626 in 5.2.2 for a sendmsg call. 3628 flags - is used in the same format as the sendmsg call flags (e.g. 3629 MSG_DONTROUTE). 3631 This function call may also be used to terminate an association using 3632 an association identification by setting the sinfo.sinfo_flags to 3633 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3634 to be terminated. In such a case the len of the message would be 3635 zero. 3637 Using sctp_send() on a non-connected one-to-one style socket for 3638 implicit connection setup may or may not work depending on the SCTP 3639 implementation. 3641 Sending a message using sctp_send() is atomic unless explicit EOR 3642 marking is enabled on the socket specified by sd. The call returns 3643 the number of characters sent, or -1 if an error occurred. The 3644 variable errno is then set appropriately. 3646 9.11. sctp_sendx() 3648 An implementation may provide another alternative function or system 3649 call to assist an application with the sending of data without the 3650 use of the CMSG header structures that also gives a list of 3651 addresses. The list of addresses is provided for implicit 3652 association setup. In such a case the list of addresses serves the 3653 same purpose as the addresses given in sctp_connectx (see 3654 Section 9.9). 3656 sctp_sendx(). Its syntax is, 3658 int sctp_sendx(int sd, 3659 const void *msg, 3660 size_t len, 3661 struct sockaddr *addrs, 3662 int addrcnt, 3663 struct sctp_sndrcvinfo *sinfo, 3664 int flags); 3666 sd - is the socket descriptor 3667 msg - The message to be sent 3668 len - The length of the message 3669 addrs - is an array of addresses. 3670 addrcnt - is the number of addresses in the array. 3672 sinfo - A pointer to a sctp_sndrcvinfo structure used as described 3673 in 5.2.2 for a sendmsg call. 3674 flags - is used in the same format as the sendmsg call flags (e.g. 3675 MSG_DONTROUTE). 3677 Note that on return from this call the sinfo structure will have 3678 changed in that the sinfo_assoc_id will be filled in with the new 3679 association id. 3681 This function call may also be used to terminate an association using 3682 an association identification by setting the sinfo.sinfo_flags to 3683 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3684 to be terminated. In such a case the len of the message would be 3685 zero. 3687 Sending a message using sctp_send() is atomic unless explicit EOR 3688 marking is enabled on the socket specified by sd. The call returns 3689 the number of characters sent, or -1 if an error occurred. The 3690 variable errno is then set appropriately. 3692 Using sctp_sendx() on a non-connected one-to-one style socket for 3693 implicit connection setup may or may not work depending on the SCTP 3694 implementation. 3696 9.12. sctp_getaddrlen 3698 For application binary portability it is sometimes desirable to know 3699 what the kernel thinks is the length of a socket address family. 3700 This function, when called with a valid family type will return the 3701 length that the operating system uses in the specified family's 3702 socket address structure. 3704 int sctp_getaddrlen(sa_family_t family); 3706 10. IANA considerations 3708 This document contains no IANA considerations. 3710 11. Security Considerations 3712 Many TCP and UDP implementations reserve port numbers below 1024 for 3713 privileged users. If the target platform supports privileged users, 3714 the SCTP implementation SHOULD restrict the ability to call bind() or 3715 sctp_bindx() on these port numbers to privileged users. 3717 Similarly unprivileged users should not be able to set protocol 3718 parameters which could result in the congestion control algorithm 3719 being more aggressive than permitted on the public Internet. These 3720 parameters are: 3721 o struct sctp_rtoinfo 3723 If an unprivileged user inherits a one-to-many style socket with open 3724 associations on a privileged port, it MAY be permitted to accept new 3725 associations, but it SHOULD NOT be permitted to open new 3726 associations. This could be relevant for the r* family of protocols. 3728 Applications using the one-to-many style sockets and using the 3729 interleave level if 0 are subject to denial of service attacks as 3730 described in Section 8.1.25. 3732 12. IANA Considerations 3734 There are no actions required from IANA. 3736 13. Acknowledgments 3738 Special acknowledgment is given to Ken Fujita, Jonathan Woods, 3739 Qiaobing Xie, and La Monte Yarroll, who helped extensively in the 3740 early formation of this document. 3742 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 3743 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, 3744 Jonathan Leighton and many others on the TSVWG mailing list for 3745 contributing valuable comments. 3747 A special thanks to Phillip Conrad, for his suggested text, quick and 3748 constructive insights, and most of all his persistent fighting to 3749 keep the interface to SCTP usable for the application programmer. 3751 14. Normative references 3753 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3754 RFC 793, September 1981. 3756 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 3757 August 1980. 3759 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 3760 Functional Specification", RFC 1644, July 1994. 3762 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3763 Requirement Levels", BCP 14, RFC 2119, March 1997. 3765 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 3766 Stevens, "Basic Socket Interface Extensions for IPv6", 3767 RFC 3493, February 2003. 3769 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 3770 "Advanced Sockets Application Program Interface (API) for 3771 IPv6", RFC 3542, May 2003. 3773 [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. 3774 Conrad, "Stream Control Transmission Protocol (SCTP) 3775 Partial Reliability Extension", RFC 3758, May 2004. 3777 [RFC4960] Stewart, R., "Stream Control Transmission Protocol", 3778 RFC 4960, September 2007. 3780 Appendix A. one-to-one style Code Example 3782 The following code is a simple implementation of an echo server over 3783 SCTP. The example shows how to use some features of one-to-one style 3784 IPv4 SCTP sockets, including: 3786 o Opening, binding, and listening for new associations on a socket; 3787 o Enabling ancillary data 3788 o Enabling notifications 3789 o Using ancillary data with sendmsg() and recvmsg() 3790 o Using MSG_EOR to determine if an entire message has been read 3791 o Handling notifications 3793 #include 3794 #include 3795 #include 3796 #include 3797 #include 3798 #include 3799 #include 3800 #include 3801 #include 3803 #define BUFLEN 100 3805 static void 3806 handle_event(void *buf) 3807 { 3808 struct sctp_assoc_change *sac; 3809 struct sctp_send_failed *ssf; 3810 struct sctp_paddr_change *spc; 3811 struct sctp_remote_error *sre; 3812 union sctp_notification *snp; 3813 char addrbuf[INET6_ADDRSTRLEN]; 3814 const char *ap; 3815 struct sockaddr_in *sin; 3816 struct sockaddr_in6 *sin6; 3818 snp = buf; 3820 switch (snp->sn_header.sn_type) { 3821 case SCTP_ASSOC_CHANGE: 3822 sac = &snp->sn_assoc_change; 3823 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3824 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3825 sac->sac_inbound_streams, sac->sac_outbound_streams); 3826 break; 3827 case SCTP_SEND_FAILED: 3828 ssf = &snp->sn_send_failed; 3829 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3830 ssf->ssf_error); 3831 break; 3833 case SCTP_PEER_ADDR_CHANGE: 3834 spc = &snp->sn_paddr_change; 3835 if (spc->spc_aaddr.ss_family == AF_INET) { 3836 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3837 ap = inet_ntop(AF_INET, &sin->sin_addr, 3838 addrbuf, INET6_ADDRSTRLEN); 3839 } else { 3840 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3841 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3842 addrbuf, INET6_ADDRSTRLEN); 3843 } 3844 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3845 spc->spc_state, spc->spc_error); 3846 break; 3847 case SCTP_REMOTE_ERROR: 3848 sre = &snp->sn_remote_error; 3849 printf("^^^ remote_error: err=%hu len=%hu\n", 3850 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3851 break; 3852 case SCTP_SHUTDOWN_EVENT: 3853 printf("^^^ shutdown event\n"); 3854 break; 3855 default: 3856 printf("unknown type: %hu\n", snp->sn_header.sn_type); 3857 break; 3858 }; 3859 } 3861 static void * 3862 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 3863 ssize_t *nrp, size_t cmsglen) 3864 { 3865 ssize_t nr = 0, nnr = 0; 3866 struct iovec iov[1]; 3868 *nrp = 0; 3869 iov->iov_base = buf; 3870 iov->iov_len = *buflen; 3871 msg->msg_iov = iov; 3872 msg->msg_iovlen = 1; 3874 for (;;) { 3875 #ifndef MSG_XPG4_2 3876 #define MSG_XPG4_2 0 3877 #endif 3878 msg->msg_flags = MSG_XPG4_2; 3879 msg->msg_controllen = cmsglen; 3881 nnr = recvmsg(fd, msg, 0); 3882 if (nnr <= 0) { 3883 /* EOF or error */ 3884 *nrp = nr; 3885 return (NULL); 3886 } 3887 nr += nnr; 3889 if ((msg->msg_flags & MSG_EOR) != 0) { 3890 *nrp = nr; 3891 return (buf); 3892 } 3894 /* Realloc the buffer? */ 3895 if (*buflen == (size_t)nr) { 3896 buf = realloc(buf, *buflen * 2); 3897 if (buf == 0) { 3898 fprintf(stderr, "out of memory\n"); 3899 exit(1); 3900 } 3901 *buflen *= 2; 3902 } 3903 /* Set the next read offset */ 3904 iov->iov_base = (char *)buf + nr; 3905 iov->iov_len = *buflen - nr; 3906 } 3907 } 3909 static void 3910 echo(int fd, int socketModeone_to_many) 3911 { 3912 ssize_t nr; 3913 struct sctp_sndrcvinfo *sri; 3914 struct msghdr msg[1]; 3915 struct cmsghdr *cmsg; 3916 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3917 char *buf; 3918 size_t buflen; 3919 struct iovec iov[1]; 3920 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3921 /* Allocate the initial data buffer */ 3922 buflen = BUFLEN; 3923 if (!(buf = malloc(BUFLEN))) { 3924 fprintf(stderr, "out of memory\n"); 3925 exit(1); 3926 } 3928 /* Set up the msghdr structure for receiving */ 3929 memset(msg, 0, sizeof (*msg)); 3930 msg->msg_control = cbuf; 3931 msg->msg_controllen = cmsglen; 3932 msg->msg_flags = 0; 3933 cmsg = (struct cmsghdr *)cbuf; 3934 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3936 /* Wait for something to echo */ 3937 while (buf = mysctp_recvmsg(fd, msg, 3938 buf, &buflen, &nr, cmsglen)) { 3940 /* Intercept notifications here */ 3941 if (msg->msg_flags & MSG_NOTIFICATION) { 3942 handle_event(buf); 3943 continue; 3944 } 3946 iov->iov_base = buf; 3947 iov->iov_len = nr; 3948 msg->msg_iov = iov; 3949 msg->msg_iovlen = 1; 3951 printf("got %u bytes on stream %hu:\n", nr, 3952 sri->sinfo_stream); 3953 write(0, buf, nr); 3955 /* Echo it back */ 3956 msg->msg_flags = MSG_XPG4_2; 3957 if (sendmsg(fd, msg, 0) < 0) { 3958 perror("sendmsg"); 3959 exit(1); 3960 } 3961 } 3963 if (nr < 0) { 3964 perror("recvmsg"); 3965 } 3966 if(socketModeone_to_many == 0) 3967 close(fd); 3968 } 3970 int main() 3971 { 3972 struct sctp_event_subscribe event; 3973 int lfd, cfd; 3974 int onoff = 1; 3975 struct sockaddr_in sin[1]; 3976 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3977 perror("socket"); 3978 exit(1); 3979 } 3981 sin->sin_family = AF_INET; 3982 sin->sin_port = htons(7); 3983 sin->sin_addr.s_addr = INADDR_ANY; 3984 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3985 perror("bind"); 3986 exit(1); 3987 } 3989 if (listen(lfd, 1) == -1) { 3990 perror("listen"); 3991 exit(1); 3992 } 3994 /* Wait for new associations */ 3995 for (;;) { 3996 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3997 perror("accept"); 3998 exit(1); 3999 } 4000 /* Enable all events */ 4001 event.sctp_data_io_event = 1; 4002 event.sctp_association_event = 1; 4003 event.sctp_address_event = 1; 4004 event.sctp_send_failure_event = 1; 4005 event.sctp_peer_error_event = 1; 4006 event.sctp_shutdown_event = 1; 4007 event.sctp_partial_delivery_event = 1; 4008 event.sctp_adaptation_layer_event = 1; 4009 if (setsockopt(cfd, IPPROTO_SCTP, 4010 SCTP_EVENTS, &event, 4011 sizeof(event)) != 0) { 4012 perror("setevent failed"); 4013 exit(1); 4014 } 4015 /* Echo back any and all data */ 4016 echo(cfd,0); 4017 } 4018 } 4020 Appendix B. one-to-many style Code Example 4022 The following code is a simple implementation of an echo server over 4023 SCTP. The example shows how to use some features of one-to-many 4024 style IPv4 SCTP sockets, including: 4026 o Opening and binding of a socket; 4027 o Enabling ancillary data 4028 o Enabling notifications 4029 o Using ancillary data with sendmsg() and recvmsg() 4030 o Using MSG_EOR to determine if an entire message has been read 4031 o Handling notifications 4033 Note most functions defined in Appendix A are reused in this example. 4035 int main() 4036 { 4037 int fd; 4038 int idleTime = 2; 4039 struct sockaddr_in sin[1]; 4040 struct sctp_event_subscribe event; 4042 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 4043 perror("socket"); 4044 exit(1); 4045 } 4046 sin->sin_family = AF_INET; 4047 sin->sin_port = htons(7); 4048 sin->sin_addr.s_addr = INADDR_ANY; 4049 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 4050 perror("bind"); 4051 exit(1); 4052 } 4054 /* Enable all notifications and events */ 4055 event.sctp_data_io_event = 1; 4056 event.sctp_association_event = 1; 4057 event.sctp_address_event = 1; 4058 event.sctp_send_failure_event = 1; 4059 event.sctp_peer_error_event = 1; 4060 event.sctp_shutdown_event = 1; 4061 event.sctp_partial_delivery_event = 1; 4062 event.sctp_adaptation_layer_event = 1; 4063 if (setsockopt(fd, IPPROTO_SCTP, 4064 SCTP_EVENTS, &event, 4065 sizeof(event)) != 0) { 4066 perror("setevent failed"); 4067 exit(1); 4068 } 4069 /* Set associations to auto-close in 2 seconds of 4070 * inactivity 4071 */ 4072 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 4073 &idleTime, 4) < 0) { 4074 perror("setsockopt SCTP_AUTOCLOSE"); 4075 exit(1); 4076 } 4078 /* Allow new associations to be accepted */ 4079 if (listen(fd, 1) < 0) { 4080 perror("listen"); 4081 exit(1); 4082 } 4084 /* Wait for new associations */ 4085 while(1){ 4086 /* Echo back any and all data */ 4087 echo(fd,1); 4088 } 4089 } 4091 Authors' Addresses 4093 Randall R. Stewart 4094 The Resource Group 4095 1700 Pennsylvania Ave NW 4096 Suite 56 4097 Washington, DC 20006 4098 USA 4100 Phone: 4101 Email: randall.stewart@trgworld.com 4103 Kacheong Poon 4104 Sun Microsystems, Inc. 4105 4150 Network Circle 4106 Santa Clara, CA 95054 4107 USA 4109 Phone: 4110 Email: kacheong.poon@sun.com 4112 Michael Tuexen 4113 Univ. of Applied Sciences Muenster 4114 Stegerwaldstr. 39 4115 48565 Steinfurt 4116 Germany 4118 Email: tuexen@fh-muenster.de 4120 Vladislav Yasevich 4121 HP 4122 110 Spitrook Rd 4123 Nashua, NH, 03062 4124 USA 4126 Email: vladislav.yasevich@hp.com 4127 Peter Lei 4128 Cisco Systems, Inc. 4129 8735 West Higgins Road 4130 Suite 300 4131 Chicago, IL 60631 4132 USA 4134 Phone: 4135 Email: peterlei@cisco.com 4137 Full Copyright Statement 4139 Copyright (C) The IETF Trust (2008). 4141 This document is subject to the rights, licenses and restrictions 4142 contained in BCP 78, and except as set forth therein, the authors 4143 retain all their rights. 4145 This document and the information contained herein are provided on an 4146 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4147 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4148 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4149 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4150 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4151 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4153 Intellectual Property 4155 The IETF takes no position regarding the validity or scope of any 4156 Intellectual Property Rights or other rights that might be claimed to 4157 pertain to the implementation or use of the technology described in 4158 this document or the extent to which any license under such rights 4159 might or might not be available; nor does it represent that it has 4160 made any independent effort to identify any such rights. Information 4161 on the procedures with respect to rights in RFC documents can be 4162 found in BCP 78 and BCP 79. 4164 Copies of IPR disclosures made to the IETF Secretariat and any 4165 assurances of licenses to be made available, or the result of an 4166 attempt made to obtain a general license or permission for the use of 4167 such proprietary rights by implementers or users of this 4168 specification can be obtained from the IETF on-line IPR repository at 4169 http://www.ietf.org/ipr. 4171 The IETF invites any interested party to bring to its attention any 4172 copyrights, patents or patent applications, or other proprietary 4173 rights that may cover technology that may be required to implement 4174 this standard. Please address the information to the IETF at 4175 ietf-ipr@ietf.org.