idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-14.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 3954. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3965. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3972. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3978. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard 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 1054 has weird spacing: '...g_level cms...' == Line 1108 has weird spacing: '...g_level cms...' == Line 1237 has weird spacing: '...g_level cms...' == Line 1449 has weird spacing: '...n_event sn_s...' == Line 1452 has weird spacing: '...y_event sn_...' == (2 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH chunks MUST not be used. If they are used an error MUST be returned. -- 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 (December 11, 2006) is 6347 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 1705 -- Looks like a reference, but probably isn't: '1' on line 3841 == Unused Reference: 'RFC2026' is defined on line 3563, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 3566, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 2292 (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2553 (Obsoleted by RFC 3493) ** Obsolete normative reference: RFC 2960 (Obsoleted by RFC 4960) Summary: 6 errors (**), 0 flaws (~~), 12 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Cisco Systems, Inc. 4 Expires: June 14, 2007 Q. Xie 5 Motorola, Inc. 6 L. Yarroll 7 TimeSys Corp 8 K. Poon 9 Sun Microsystems, Inc. 10 M. Tuexen 11 Univ. of Applied Sciences Muenster 12 December 11, 2006 14 Sockets API Extensions for Stream Control Transmission Protocol (SCTP) 15 draft-ietf-tsvwg-sctpsocket-14.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 June 14, 2007. 42 Copyright Notice 44 Copyright (C) The IETF Trust (2006). 46 Abstract 48 This document describes a mapping of the Stream Control Transmission 49 Protocol SCTP into a sockets API. The benefits of this mapping 50 include compatibility for TCP applications, access to new SCTP 51 features and a consolidated error and event notification scheme. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.1. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3. one-to-many style Interface . . . . . . . . . . . . . . . . . 6 59 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6 60 3.1.1. socket() - one-to-many style socket . . . . . . . . . 7 61 3.1.2. bind() - one-to-many style socket . . . . . . . . . . 8 62 3.1.3. listen() - One-to-many style socket . . . . . . . . . 9 63 3.1.4. sendmsg() and recvmsg() - one-to-many style socket . . 9 64 3.1.5. close() - one-to-many style socket . . . . . . . . . . 11 65 3.1.6. connect() - one-to-many style socket . . . . . . . . . 11 66 3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12 67 3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 68 3.4. Special considerations . . . . . . . . . . . . . . . . . . 13 69 4. one-to-one style Interface . . . . . . . . . . . . . . . . . . 15 70 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 15 71 4.1.1. socket() - one-to-one style socket . . . . . . . . . . 16 72 4.1.2. bind() - one-to-one style socket . . . . . . . . . . . 16 73 4.1.3. listen() - one-to-one style socket . . . . . . . . . . 17 74 4.1.4. accept() - one-to-one style socket . . . . . . . . . . 18 75 4.1.5. connect() - one-to-one style socket . . . . . . . . . 18 76 4.1.6. close() - one-to-one style socket . . . . . . . . . . 19 77 4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 19 78 4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20 79 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 20 80 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21 81 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21 82 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22 83 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23 84 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 24 85 5.2.3. Extended SCTP Header Information Structure 86 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 27 87 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 31 88 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 31 89 5.4. Ancillary Data Considerations and Semantics . . . . . . . 42 90 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 42 91 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 42 92 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 43 93 6. Common Operations for Both Styles . . . . . . . . . . . . . . 44 94 6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 44 95 6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 45 96 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 46 97 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 46 98 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 47 99 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 48 100 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 48 101 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 49 102 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 51 103 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 51 104 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 51 105 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 51 106 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 52 107 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 52 108 7.1.9. Set Peer Primary Address 109 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 52 110 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 53 111 7.1.11. Set Adaptation Layer Indicator 112 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 53 113 7.1.12. Enable/Disable message fragmentation 114 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 53 115 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 54 116 7.1.14. Set default send parameters 117 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 56 118 7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 57 119 7.1.16. Set/clear IPv4 mapped addresses 120 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 57 121 7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG) . . . 57 122 7.1.18. Add a chunk that must be authenticated 123 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 57 124 7.1.19. Get or set the list of supported HMAC Identifiers 125 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 58 126 7.1.20. Set a shared key (SCTP_AUTH_KEY) . . . . . . . . . . . 58 127 7.1.21. Get or set the active shared key 128 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 59 129 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) . . . . . . 59 130 7.1.23. Get or set delayed ack timer 131 (SCTP_DELAYED_ACK_TIME) . . . . . . . . . . . . . . . 60 132 7.1.24. Get or set fragmented interleave 133 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 60 134 7.1.25. Set or Get the sctp partial delivery point 135 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 61 136 7.1.26. Set or Get the use of extended receive info 137 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 61 138 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) . . 61 139 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) . . . . 61 140 7.1.29. Set or Get the default context (SCTP_CONTEXT) . . . . 62 141 7.1.30. Enable or disable explicit EOR marking 142 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 62 143 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 62 144 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 62 145 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 64 146 7.2.3. Get the list of chunks the peer requires to be 147 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 65 148 7.2.4. Get the list of chunks the local endpoint requires 149 to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 65 150 7.2.5. Get the list of current associations 151 (SCTP_GET_ASOC_ID_LIST) . . . . . . . . . . . . . . . 65 152 7.3. Ancillary Data and Notification Interest Options . . . . . 66 153 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 68 154 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 69 155 8.2. Branched-off Association . . . . . . . . . . . . . . . . . 70 156 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 70 157 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 71 158 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 71 159 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 72 160 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 72 161 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 73 162 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 73 163 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 74 164 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 75 165 8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 76 166 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . . 76 167 10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 77 168 11. Security Considerations . . . . . . . . . . . . . . . . . . . 77 169 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 77 170 13. Normative references . . . . . . . . . . . . . . . . . . . . . 78 171 Appendix A. one-to-one style Code Example . . . . . . . . . . . . 78 172 Appendix B. one-to-many style Code Example . . . . . . . . . . . 84 173 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 85 174 Intellectual Property and Copyright Statements . . . . . . . . . . 87 176 1. Introduction 178 The sockets API has provided a standard mapping of the Internet 179 Protocol suite to many operating systems. Both TCP RFC793 [RFC0793] 180 and UDP RFC768 [RFC0768] have benefited from this standard 181 representation and access method across many diverse platforms. SCTP 182 is a new protocol that provides many of the characteristics of TCP 183 but also incorporates semantics more akin to UDP. This document 184 defines a method to map the existing sockets API for use with SCTP, 185 providing both a base for access to new features and compatibility so 186 that most existing TCP applications can be migrated to SCTP with few 187 (if any) changes. 189 There are three basic design objectives: 191 1) Maintain consistency with existing sockets APIs: 192 We define a sockets mapping for SCTP that is consistent with other 193 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 194 IPv6). 195 2) Support a one-to-many style interface 196 This set of semantics is similar to that defined for connection- 197 less protocols, such as UDP. A one-to-many style SCTP socket 198 should be able to control multiple SCTP associations. This is 199 similar to an UDP socket, which can communicate with many peer end 200 points. Each of these associations is assigned an association ID 201 so that an applications can use the ID to differentiate them. 202 Note that SCTP is connection-oriented in nature, and it does not 203 support broadcast or multicast communications, as UDP does. 204 3) Support a one-to-one style interface 205 This interface supports a similar semantics as sockets for 206 connection-oriented protocols, such as TCP. A one-to-one style 207 SCTP socket should only control one SCTP association. 208 One purpose of defining this interface is to allow existing 209 applications built on other connection-oriented protocols be 210 ported to use SCTP with very little effort. And developers 211 familiar with those semantics can easily adapt to SCTP. Another 212 purpose is to make sure that existing mechanisms in most OSes to 213 deal with socket, such as select(), should continue to work with 214 this style of socket. 215 Extensions are added to this mapping to provide mechanisms to 216 exploit new features of SCTP. 218 Goals 2 and 3 are not compatible, so in this document we define two 219 modes of mapping, namely the one-to-many style mapping and the one- 220 to-one style mapping. These two modes share some common data 221 structures and operations, but will require the use of two different 222 application programming styles. Note that all new SCTP features can 223 be used with both styles of socket. The decision on which one to use 224 depends mainly on the nature of applications. 226 A mechanism is defined to extract a one-to-many style SCTP 227 association into a one-to-one style socket. 229 Some of the SCTP mechanisms cannot be adequately mapped to existing 230 socket interface. In some cases, it is more desirable to have new 231 interface instead of using existing socket calls. Section 8 of this 232 document describes those new interface. 234 2. Conventions 236 2.1. Data Types 238 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 239 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 240 (e.g., uint16_t). We also assume the argument data types from 241 1003.1g when possible (e.g., the final argument to setsockopt() is a 242 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 243 size_t data type is used. 245 3. one-to-many style Interface 247 The one-to-many style interface has the following characteristics: 249 A) Outbound association setup is implicit. 251 B) Messages are delivered in complete messages (with one notable 252 exception). 254 C) There is a 1 to MANY relationship between socket and association. 256 3.1. Basic Operation 258 A typical server in this style uses the following socket calls in 259 sequence to prepare an endpoint for servicing requests: 261 1. socket() 262 2. bind() 263 3. listen() 264 4. recvmsg() 265 5. sendmsg() 266 6. close() 268 A typical client uses the following calls in sequence to setup an 269 association with a server to request services: 271 1. socket() 272 2. sendmsg() 273 3. recvmsg() 274 4. close() 276 In this style, by default, all the associations connected to the 277 endpoint are represented with a single socket. Each associations is 278 assigned an association ID (type is sctp_assoc_t) so that an 279 application can use it to differentiate between them. In some 280 implementations, the peer endpoints addresses can also be used for 281 this purpose. But this is not required for performance reasons. If 282 an implementation does not support using addresses to differentiate 283 between different associations, the sendto() call can only be used to 284 setup an association implicitly. It cannot be used to send data to 285 an established association as the association ID cannot be specified. 287 Once as association ID is assigned to an SCTP association, that ID 288 will not be reused until the application explicitly terminates the 289 association. The resources belonged to that association will not be 290 freed until that happens. This is similar to the close() operation 291 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 292 option (section 7.1.8) is set. In this case, after the association 293 is terminated gracefully automatically, the association ID assigned 294 to it can be reused. All applications using this option should be 295 aware of this to avoid the possible problem of sending data to an 296 incorrect peer end point. 298 If the server or client wishes to branch an existing association off 299 to a separate socket, it is required to call sctp_peeloff() and in 300 the parameter specifies the association identification. The 301 sctp_peeloff() call will return a new socket which can then be used 302 with recv() and send() functions for message passing. See 303 Section 8.2 for more on branched-off associations. 305 Once an association is branched off to a separate socket, it becomes 306 completely separated from the original socket. All subsequent 307 control and data operations to that association must be done through 308 the new socket. For example, the close operation on the original 309 socket will not terminate any associations that have been branched 310 off to a different socket. 312 We will discuss the one-to-many style socket calls in more details in 313 the following subsections. 315 3.1.1. socket() - one-to-many style socket 317 Applications use socket() to create a socket descriptor to represent 318 an SCTP endpoint. 320 The syntax is, 322 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 324 or, 326 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 328 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 329 socket. 331 The first form creates an endpoint which can use only IPv4 addresses, 332 while, the second form creates an endpoint which can use both IPv6 333 and IPv4 addresses. 335 3.1.2. bind() - one-to-many style socket 337 Applications use bind() to specify which local address the SCTP 338 endpoint should associate itself with. 340 An SCTP endpoint can be associated with multiple addresses. To do 341 this, sctp_bindx() is introduced in section Section 8.1 to help 342 applications do the job of associating multiple addresses. 344 These addresses associated with a socket are the eligible transport 345 addresses for the endpoint to send and receive data. The endpoint 346 will also present these addresses to its peers during the association 347 initialization process, see RFC2960 [RFC2960]. 349 After calling bind(), if the endpoint wishes to accept new 350 associations on the socket, it must call listen() (see section 351 Section 3.1.3). 353 The syntax of bind() is, 355 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 357 sd - the socket descriptor returned by socket(). 358 addr - the address structure (struct sockaddr_in or struct 359 sockaddr_in6 RFC2553 [RFC2553]). 360 addrlen - the size of the address structure. 362 If sd is an IPv4 socket, the address passed must be an IPv4 address. 363 If the sd is an IPv6 socket, the address passed can either be an IPv4 364 or an IPv6 address. 366 Applications cannot call bind() multiple times to associate multiple 367 addresses to an endpoint. After the first call to bind(), all 368 subsequent calls will return an error. 370 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 371 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 372 operating system will associate the endpoint with an optimal address 373 set of the available interfaces. 375 If a bind() is not called prior to a sendmsg() call that initiates a 376 new association, the system picks an ephemeral port and will choose 377 an address set equivalent to binding with a wildcard address. One of 378 those addresses will be the primary address for the association. 379 This automatically enables the multi-homing capability of SCTP. 381 3.1.3. listen() - One-to-many style socket 383 By default, new associations are not accepted for one-to-many style 384 sockets. An application uses listen() to mark a socket as being able 385 to accept new associations. The syntax is, 387 int listen(int sd, int backlog); 389 sd - the socket descriptor of the endpoint. 390 backlog - if backlog is non-zero, enable listening else disable 391 listening. 393 Note that one-to-many style socket consumers do not need to call 394 accept to retrieve new associations. Calling accept() on a one-to- 395 many style socket should return EOPNOTSUPP. Rather, new associations 396 are accepted automatically, and notifications of the new associations 397 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if 398 these notifications are enabled). Clients will typically not call 399 listen(), so that they can be assured that the only associations on 400 the socket will be ones they actively initiated. Server or peer-to- 401 peer sockets, on the other hand, will always accept new associations, 402 so a well-written application using server one-to-many style sockets 403 must be prepared to handle new associations from unwanted peers. 405 Also note that the SCTP_ASSOC_CHANGE event provides the association 406 ID for a new association, so if applications wish to use the 407 association ID as input to other socket calls, they should ensure 408 that the SCTP_ASSOC_CHANGE event is enabled. 410 3.1.4. sendmsg() and recvmsg() - one-to-many style socket 412 An application uses sendmsg() and recvmsg() call to transmit data to 413 and receive data from its peer. 415 ssize_t sendmsg(int sd, const struct msghdr *message, int flags); 417 ssize_t recvmsg(int sd, struct msghdr *message, int flags); 419 sd - the socket descriptor of the endpoint. 420 message: pointer to the msghdr structure which contains a single 421 user message and possibly some ancillary data. See Section 5 for 422 complete description of the data structures. 423 flags - No new flags are defined for SCTP at this level. See 424 Section 5 for SCTP-specific flags used in the msghdr structure. 426 As we will see in Section 5, along with the user data, the ancillary 427 data field is used to carry the sctp_sndrcvinfo and/or the 428 sctp_initmsg structures to perform various SCTP functions including 429 specifying options for sending each user message. Those options, 430 depending on whether sending or receiving, include stream number, 431 stream sequence number, various flags, context and payload protocol 432 Id, etc. 434 When sending user data with sendmsg(), the msg_name field in msghdr 435 structure will be filled with one of the transport addresses of the 436 intended receiver. If there is no association existing between the 437 sender and the intended receiver, the sender's SCTP stack will set up 438 a new association and then send the user data (see Section 3.2 for 439 more on implicit association setup). 441 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 442 be delivered if that notification has been enabled, and no more data 443 can be sent to that association. Any attempt to send more data will 444 cause sendmsg() to return with an ESHUTDOWN error. Note that the 445 socket is still open for reading at this point so it is possible to 446 retrieve notifications. 448 When receiving a user message with recvmsg(), the msg_name field in 449 msghdr structure will be populated with the source transport address 450 of the user data. The caller of recvmsg() can use this address 451 information to determine to which association the received user 452 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 453 applications must use the peer transport address provided in the 454 msg_name field by recvmsg() to perform correlation to an association, 455 since they will not have the association ID. 457 If all data in a single message has been delivered, MSG_EOR will be 458 set in the msg_flags field of the msghdr structure (see section 459 Section 5.1). 461 If the application does not provide enough buffer space to completely 462 receive a data message, MSG_EOR will not be set in msg_flags. 464 Successive reads will consume more of the same message until the 465 entire message has been delivered, and MSG_EOR will be set. 467 If the SCTP stack is running low on buffers, it may partially deliver 468 a message. In this case, MSG_EOR will not be set, and more calls to 469 recvmsg() will be necessary to completely consume the message. Only 470 one message at a time per stream can be partially delivered. 472 Note, if the socket is a branched-off socket that only represents one 473 association (see Section 3.1), the msg_name field can be used to 474 override the primary address when sending data. 476 3.1.5. close() - one-to-many style socket 478 Applications use close() to perform graceful shutdown (as described 479 in Section 10.1 of RFC2960 [RFC2960]) on ALL the associations 480 currently represented by a one-to-many style socket. 482 The syntax is: 484 ret = close(int sd); 486 sd - the socket descriptor of the associations to be closed. 488 To gracefully shutdown a specific association represented by the one- 489 to-many style socket, an application should use the sendmsg() call, 490 and including the SCTP_EOF flag. A user may optionally terminate an 491 association non-gracefully by sending with the SCTP_ABORT flag and 492 possibly passing a user specified abort code in the data field. Both 493 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see 494 Section 5.2.2) in the sendmsg call. 496 If sd in the close() call is a branched-off socket representing only 497 one association, the shutdown is performed on that association only. 499 3.1.6. connect() - one-to-many style socket 501 An application may use the connect() call in the one-to-many style to 502 initiate an association without sending data. 504 The syntax is: 506 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 507 sd - the socket descriptor to have a new association added to. 508 nam - the address structure (either struct sockaddr_in or struct 509 sockaddr_in6 defined in RFC2553 [RFC2553]). 510 len - the size of the address. 511 Multiple connect() calls can be made on the same socket to create 512 multiple associations. This is different from the semantics of 513 connect() on a UDP socket. 515 3.2. Implicit Association Setup 517 Once the bind() call is complete on a one-to-many style socket, the 518 application can begin sending and receiving data using the sendmsg()/ 519 recvmsg() or sendto()/recvfrom() calls, without going through any 520 explicit association setup procedures (i.e., no connect() calls 521 required). 523 Whenever sendmsg() or sendto() is called and the SCTP stack at the 524 sender finds that there is no association existing between the sender 525 and the intended receiver (identified by the address passed either in 526 the msg_name field of msghdr structure in the sendmsg() call or the 527 dest_addr field in the sendto() call), the SCTP stack will 528 automatically setup an association to the intended receiver. 530 Upon the successful association setup a SCTP_COMM_UP notification 531 will be dispatched to the socket at both the sender and receiver 532 side. This notification can be read by the recvmsg() system call 533 (see Section 3.1.3). 535 Note, if the SCTP stack at the sender side supports bundling, the 536 first user message may be bundled with the COOKIE ECHO message 537 RFC2960 [RFC2960]. 539 When the SCTP stack sets up a new association implicitly, it first 540 consults the sctp_initmsg structure, which is passed along within the 541 ancillary data in the sendmsg() call (see Section 5.2.1 for details 542 of the data structures), for any special options to be used on the 543 new association. 545 If this information is not present in the sendmsg() call, or if the 546 implicit association setup is triggered by a sendto() call, the 547 default association initialization parameters will be used. These 548 default association parameters may be set with respective 549 setsockopt() calls or be left to the system defaults. 551 Implicit association setup cannot be initiated by send()/recv() 552 calls. 554 3.3. Non-blocking mode 556 Some SCTP users might want to avoid blocking when they call socket 557 interface function. 559 Once all bind() calls are complete on a one-to-many style socket, the 560 application must set the non-blocking option by a fcntl() (such as 561 O_NONBLOCK). After which the sendmsg() function returns immediately, 562 and the success or failure of the data message (and possible 563 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 564 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 565 be sent (due to a CANT_START_ASSOC), the sender will also receive a 566 SCTP_SEND_FAILED event. Those event(s) can be received by the user 567 calling of recvmsg(). A server (having called listen()) is also 568 notified of an association up event by the reception of a 569 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 570 possibly the reception of the first data message. 572 In order to shutdown the association gracefully, the user must call 573 sendmsg() with no data and with the SCTP_EOF flag set. The function 574 returns immediately, and completion of the graceful shutdown is 575 indicated by an SCTP_ASSOC_CHANGE notification of type 576 SHUTDOWN_COMPLETE (see Section 5.3.1.1). Note that this can also be 577 done using the sctp_send() call described in Section 8.10. 579 An application is recommended to use caution when using select() (or 580 poll()) for writing on a one-to-many style socket. The reason being 581 that interpretation of select on write is implementation specific. 582 Generally a positive return on a select on write would only indicate 583 that one of the associations represented by the one-to-many socket is 584 writable. An application that writes after the select return may 585 still block since the association that was writeable is not the 586 destination association of the write call. Likewise select (or 587 poll()) for reading from a one-to-many socket will only return an 588 indication that one of the associations represented by the socket has 589 data to be read. 591 An application that wishes to know that a particular association is 592 ready for reading or writing should either use the one-to-one style 593 or use the sctp_peeloff() (see Section 8.2) function to separate the 594 association of interest from the one-to-many socket. 596 3.4. Special considerations 598 The fact that a one-to-many style socket can provide access to many 599 SCTP associations through a single socket descriptor has important 600 implications for both application programmers and system programmers 601 implementing this API. A key issue is how buffer space inside the 602 sockets layer is managed. Because this implementation detail 603 directly affects how application programmers must write their code to 604 ensure correct operation and portability, this section provides some 605 guidance to both implementors and application programmers. 607 An important feature that SCTP shares with TCP is flow control: 608 specifically, a sender may not send data faster than the receiver can 609 consume it. 611 For TCP, flow control is typically provided for in the sockets API as 612 follows. If the reader stops reading, the sender queues messages in 613 the socket layer until it uses all of its socket buffer space 614 allocation creating a "stalled connection". Further attempts to 615 write to the socket will block or return the error EAGAIN or 616 EWOULDBLOCK for a non-blocking socket. At some point, either the 617 connection is closed, or the receiver begins to read again freeing 618 space in the output queue. 620 For one-to-one style SCTP sockets (this includes sockets descriptors 621 that were separated from a one-to-many style socket with 622 sctp_peeloff()) the behavior is identical. For one-to-many style 623 SCTP sockets, the fact that we have multiple associations on a single 624 socket makes the situation more complicated. If the implementation 625 uses a single buffer space allocation shared by all associations, a 626 single stalled association can prevent the further sending of data on 627 all associations active on a particular one-to-many style socket. 629 For a blocking socket, it should be clear that a single stalled 630 association can block the entire socket. For this reason, 631 application programmers may want to use non-blocking one-to-many 632 style sockets. The application should at least be able to send 633 messages to the non-stalled associations. 635 But a non-blocking socket is not sufficient if the API implementor 636 has chosen a single shared buffer allocation for the socket. A 637 single stalled association would eventually cause the shared 638 allocation to fill, and it would become impossible to send even to 639 non-stalled associations. 641 The API implementor can solve this problem by providing each 642 association with its own allocation of outbound buffer space. Each 643 association should conceptually have as much buffer space as it would 644 have if it had its own socket. As a bonus, this simplifies the 645 implementation of sctp_peeloff(). 647 To ensure that a given stalled association will not prevent other 648 non-stalled associations from being writable, application programmers 649 should either: 651 (a) demand that the underlying implementation dedicates independent 652 buffer space allotments to each association (as suggested above), 653 or 654 (b) verify that their application layer protocol does not permit 655 large amounts of unread data at the receiver (this is true of some 656 request-response protocols, for example), or 657 (c) use one-to-one style sockets for association which may 658 potentially stall (either from the beginning, or by using 659 sctp_peeloff before sending large amounts of data that may cause a 660 stalled condition). 661 An implementation which dedicates independent buffer space for 662 each association should define HAVE_SCTP_MULTIBUF to 1. 664 4. one-to-one style Interface 666 The goal of this style is to follow as closely as possible the 667 current practice of using the sockets interface for a connection 668 oriented protocol, such as TCP. This style enables existing 669 applications using connection oriented protocols to be ported to SCTP 670 with very little effort. 672 Note that some new SCTP features and some new SCTP socket options can 673 only be utilized through the use of sendmsg() and recvmsg() calls, 674 see Section 4.1.8. Also note that some socket interfaces may not be 675 able to provide data on the third leg of the association set up with 676 this interface style. 678 4.1. Basic Operation 680 A typical server in one-to-one style uses the following system call 681 sequence to prepare an SCTP endpoint for servicing requests: 683 1. socket() 685 2. bind() 687 3. listen() 689 4. accept() 691 The accept() call blocks until a new association is set up. It 692 returns with a new socket descriptor. The server then uses the new 693 socket descriptor to communicate with the client, using recv() and 694 send() calls to get requests and send back responses. 696 Then it calls 697 5. close() 699 to terminate the association. 701 A typical client uses the following system call sequence to setup an 702 association with a server to request services: 704 1. socket() 706 2. connect() 708 After returning from connect(), the client uses send() and recv() 709 calls to send out requests and receive responses from the server. 711 The client calls 713 3. close() 715 to terminate this association when done. 717 4.1.1. socket() - one-to-one style socket 719 Applications calls socket() to create a socket descriptor to 720 represent an SCTP endpoint. 722 The syntax is: 724 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 726 or, 728 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 730 Here, SOCK_STREAM indicates the creation of a one-to-one style 731 socket. 733 The first form creates an endpoint which can use only IPv4 addresses, 734 while the second form creates an endpoint which can use both IPv6 and 735 IPv4 addresses. 737 4.1.2. bind() - one-to-one style socket 739 Applications use bind() to pass an address to be associated with an 740 SCTP endpoint to the system. bind() allows only either a single 741 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 742 endpoint can be associated with multiple addresses. To do this, 743 sctp_bindx() is introduced in Section 8.1 to help applications do the 744 job of associating multiple addresses. 746 These addresses associated with a socket are the eligible transport 747 addresses for the endpoint to send and receive data. The endpoint 748 will also present these addresses to its peers during the association 749 initialization process, see RFC2960 [RFC2960]. 751 The syntax is: 753 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 755 sd: the socket descriptor returned by socket() call. 756 addr: the address structure (either struct sockaddr_in or struct 757 sockaddr_in6 defined in RFC2553 [RFC2553]). 758 addrlen: the size of the address structure. 760 If sd is an IPv4 socket, the address passed must be an IPv4 address. 761 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 762 either be an IPv4 or an IPv6 address. 764 Applications cannot call bind() multiple times to associate multiple 765 addresses to the endpoint. After the first call to bind(), all 766 subsequent calls will return an error. 768 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 769 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 770 operating system will associate the endpoint with an optimal address 771 set of the available interfaces. 773 If a bind() is not called prior to the connect() call, the system 774 picks an ephemeral port and will choose an address set equivalent to 775 binding with a wildcard address. One of those addresses will be the 776 primary address for the association. This automatically enables the 777 multi-homing capability of SCTP. 779 The completion of this bind() process does not ready the SCTP 780 endpoint to accept inbound SCTP association requests. Until a 781 listen() system call, described below, is performed on the socket, 782 the SCTP endpoint will promptly reject an inbound SCTP INIT request 783 with an SCTP ABORT. 785 4.1.3. listen() - one-to-one style socket 787 Applications use listen() to ready the SCTP endpoint for accepting 788 inbound associations. 790 The syntax is: 792 int listen(int sd, int backlog); 793 sd: the socket descriptor of the SCTP endpoint. 794 backlog: this specifies the max number of outstanding associations 795 allowed in the socket's accept queue. These are the associations 796 that have finished the four-way initiation handshake (see Section 797 5 of RFC2960 [RFC2960]) and are in the ESTABLISHED state. Note, a 798 backlog of '0' indicates that the caller no longer wishes to 799 receive new associations. 801 4.1.4. accept() - one-to-one style socket 803 Applications use accept() call to remove an established SCTP 804 association from the accept queue of the endpoint. A new socket 805 descriptor will be returned from accept() to represent the newly 806 formed association. 808 The syntax is: 810 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 812 new_sd - the socket descriptor for the newly formed association. 813 sd - the listening socket descriptor. 814 addr - on return, will contain the primary address of the peer 815 endpoint. 816 addrlen - on return, will contain the size of addr. 818 4.1.5. connect() - one-to-one style socket 820 Applications use connect() to initiate an association to a peer. 822 The syntax is: 824 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 826 sd - the socket descriptor of the endpoint. 827 addr - the peer's address. 828 addrlen - the size of the address. 830 This operation corresponds to the ASSOCIATE primitive described in 831 section 10.1 of RFC2960 [RFC2960]. 833 By default, the new association created has only one outbound stream. 834 The SCTP_INITMSG option described in Section 7.1.3 should be used 835 before connecting to change the number of outbound streams. 837 If a bind() is not called prior to the connect() call, the system 838 picks an ephemeral port and will choose an address set equivalent to 839 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket 840 respectively. One of those addresses will be the primary address for 841 the association. This automatically enables the multi-homing 842 capability of SCTP. 844 Note that SCTP allows data exchange, similar to T/TCP RFC1644 845 [RFC1644], during the association set up phase. If an application 846 wants to do this, it cannot use connect() call. Instead, it should 847 use sendto() or sendmsg() to initiate an association. If it uses 848 sendto() and it wants to change initialization behavior, it needs to 849 use the SCTP_INITMSG socket option before calling sendto(). Or it 850 can use SCTP_INIT type sendmsg() to initiate an association without 851 doing the setsockopt(). Note that some sockets implementations may 852 not support the sending of data to initiate an association with the 853 one-to-one style (implementations that do not support T/TCP normally 854 have this restriction). Implementations which allow sending of data 855 to initiate an association without calling connect() define the 856 preprocessor constant HAVE_SCTP_NOCONNECT to 1. 858 SCTP does not support half close semantics. This means that unlike 859 T/TCP, MSG_EOF should not be set in the flags parameter when calling 860 sendto() or sendmsg() when the call is used to initiate a connection. 861 MSG_EOF is not an acceptable flag with SCTP socket. 863 4.1.6. close() - one-to-one style socket 865 Applications use close() to gracefully close down an association. 867 The syntax is: 869 int close(int sd); 871 sd - the socket descriptor of the association to be closed. 873 After an application calls close() on a socket descriptor, no further 874 socket operations will succeed on that descriptor. 876 4.1.7. shutdown() - one-to-one style socket 878 SCTP differs from TCP in that it does not have half closed semantics. 879 Hence the shutdown() call for SCTP is an approximation of the TCP 880 shutdown() call, and solves some different problems. Full TCP- 881 compatibility is not provided, so developers porting TCP applications 882 to SCTP may need to recode sections that use shutdown(). (Note that 883 it is possible to achieve the same results as half close in SCTP 884 using SCTP streams.) 886 The syntax is: 888 int shutdown(int sd, int how); 890 sd - the socket descriptor of the association to be closed. 891 how - Specifies the type of shutdown. The values are as follows: 892 SHUT_RD - Disables further receive operations. No SCTP protocol 893 action is taken. 894 SHUT_WR - Disables further send operations, and initiates the 895 SCTP shutdown sequence. 896 SHUT_RDWR - Disables further send and receive operations and 897 initiates the SCTP shutdown sequence. 899 The major difference between SCTP and TCP shutdown() is that SCTP 900 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 901 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 902 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 903 the SCTP association while still leaving the socket descriptor open, 904 so that the caller can receive back any data SCTP was unable to 905 deliver (see Section 5.3.1.4 for more information). 907 To perform the ABORT operation described in RFC2960 [RFC2960] section 908 10.1, an application can use the socket option SO_LINGER. It is 909 described in Section 7.1.4. 911 4.1.8. sendmsg() and recvmsg() - one-to-one style socket 913 With a one-to-one style socket, the application can also use 914 sendmsg() and recvmsg() to transmit data to and receive data from its 915 peer. The semantics is similar to those used in the one-to-many 916 style (section Section 3.1.3), with the following differences: 918 1) When sending, the msg_name field in the msghdr is not used to 919 specify the intended receiver, rather it is used to indicate a 920 preferred peer address if the sender wishes to discourage the stack 921 from sending the message to the primary address of the receiver. If 922 the transport address given is not part of the current association, 923 the data will not be sent and a SCTP_SEND_FAILED event will be 924 delivered to the application if send failure events are enabled. 926 4.1.9. getpeername() 928 Applications use getpeername() to retrieve the primary socket address 929 of the peer. This call is for TCP compatibility, and is not multi- 930 homed. It does not work with one-to-many style sockets. See 931 Section 8.3 for a multi-homed/one-to-many style version of the call. 933 The syntax is: 935 int getpeername(int sd, struct sockaddr *address, 936 socklen_t *len); 938 sd - the socket descriptor to be queried. 939 address - On return, the peer primary address is stored in this 940 buffer. If the socket is an IPv4 socket, the address will be 941 IPv4. If the socket is an IPv6 socket, the address will be either 942 an IPv6 or IPv4 address. 943 len - The caller should set the length of address here. On return, 944 this is set to the length of the returned address. 946 If the actual length of the address is greater than the length of the 947 supplied sockaddr structure, the stored address will be truncated. 949 5. Data Structures 951 We discuss in this section important data structures which are 952 specific to SCTP and are used with sendmsg() and recvmsg() calls to 953 control SCTP endpoint operations and to access ancillary information 954 and notifications. 956 5.1. The msghdr and cmsghdr Structures 958 The msghdr structure used in the sendmsg() and recvmsg() calls, as 959 well as the ancillary data carried in the structure, is the key for 960 the application to set and get various control information from the 961 SCTP endpoint. 963 The msghdr and the related cmsghdr structures are defined and 964 discussed in details in RFC2292 [RFC2292]. Here we will cite their 965 definitions from RFC2292 [RFC2292]. 967 The msghdr structure: 969 struct msghdr { 970 void *msg_name; /* ptr to socket address structure */ 971 socklen_t msg_namelen; /* size of socket address structure */ 972 struct iovec *msg_iov; /* scatter/gather array */ 973 size_t msg_iovlen; /* # elements in msg_iov */ 974 void *msg_control; /* ancillary data */ 975 socklen_t msg_controllen; /* ancillary data buffer length */ 976 int msg_flags; /* flags on received message */ 977 }; 979 The cmsghdr structure: 981 struct cmsghdr { 982 socklen_t cmsg_len; /* #bytes, including this header */ 983 int cmsg_level; /* originating protocol */ 984 int cmsg_type; /* protocol-specific type */ 985 /* followed by unsigned char cmsg_data[]; */ 986 }; 988 In the msghdr structure, the usage of msg_name has been discussed in 989 previous sections (see Section 3.1.3 and Section 4.1.8). 991 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 992 field) are treated as a single SCTP data chunk, rather than multiple 993 chunks, for both sendmsg() and recvmsg(). 995 The msg_flags are not used when sending a message with sendmsg(). 997 If a notification has arrived, recvmsg() will return the notification 998 with the MSG_NOTIFICATION flag set in msg_flags. If the 999 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1000 Section 5.3 for more information about notifications. 1002 If all portions of a data frame or notification have been read, 1003 recvmsg() will return with MSG_EOR set in msg_flags. 1005 5.2. SCTP msg_control Structures 1007 A key element of all SCTP-specific socket extensions is the use of 1008 ancillary data to specify and access SCTP-specific data via the 1009 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1010 Fine-grained control over initialization and sending parameters are 1011 handled with ancillary data. 1013 Each ancillary data item is proceeded by a struct cmsghdr (see 1014 Section 5.1), which defines the function and purpose of the data 1015 contained in in the cmsg_data[] member. 1017 There are two kinds of ancillary data used by SCTP: initialization 1018 data, and, header information (SNDRCV). Initialization data (one-to- 1019 many style only) sets protocol parameters for new associations. 1020 Section 5.2.1 provides more details. Header information can set or 1021 report parameters on individual messages in a stream. See 1022 Section 5.2.2 for how to use SNDRCV ancillary data. 1024 By default on a one-to-one style socket, SCTP will pass no ancillary 1025 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1026 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1027 be enabled with socket options defined for SCTP; see Section 7.3. 1029 Note that all ancillary types are fixed length; see Section 5.4 for 1030 further discussion on this. These data structures use struct 1031 sockaddr_storage (defined in RFC2553 [RFC2553]) as a portable, fixed 1032 length address format. 1034 Other protocols may also provide ancillary data to the socket layer 1035 consumer. These ancillary data items from other protocols may 1036 intermingle with SCTP data. For example, the IPv6 socket API 1037 definitions (RFC2292 [RFC2292] and RFC2553 [RFC2553]) define a number 1038 of ancillary data items. If a socket API consumer enables delivery 1039 of both SCTP and IPv6 ancillary data, they both may appear in the 1040 same msg_control buffer in any order. An application may thus need 1041 to handle other types of ancillary data besides that passed by SCTP. 1043 The sockets application must provide a buffer large enough to 1044 accommodate all ancillary data provided via recvmsg(). If the buffer 1045 is not large enough, the ancillary data will be truncated and the 1046 msghdr's msg_flags will include MSG_CTRUNC. 1048 5.2.1. SCTP Initiation Structure (SCTP_INIT) 1050 This cmsghdr structure provides information for initializing new SCTP 1051 associations with sendmsg(). The SCTP_INITMSG socket option uses 1052 this same data structure. This structure is not used for recvmsg(). 1054 cmsg_level cmsg_type cmsg_data[] 1055 ------------ ------------ ---------------------- 1056 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1058 Here is the definition of the sctp_initmsg structure: 1060 struct sctp_initmsg { 1061 uint16_t sinit_num_ostreams; 1062 uint16_t sinit_max_instreams; 1063 uint16_t sinit_max_attempts; 1064 uint16_t sinit_max_init_timeo; 1065 }; 1067 sinit_num_ostreams: 16 bits (unsigned integer) 1069 This is an integer number representing the number of streams that the 1070 application wishes to be able to send to. This number is confirmed 1071 in the SCTP_COMM_UP notification and must be verified since it is a 1072 negotiated number with the remote endpoint. The default value of 0 1073 indicates to use the endpoint default value. 1075 sinit_max_instreams: 16 bits (unsigned integer) 1076 This value represents the maximum number of inbound streams the 1077 application is prepared to support. This value is bounded by the 1078 actual implementation. In other words the user MAY be able to 1079 support more streams than the Operating System. In such a case, the 1080 Operating System limit overrides the value requested by the user. 1081 The default value of 0 indicates to use the endpoints default value. 1083 sinit_max_attempts: 16 bits (unsigned integer) 1085 This integer specifies how many attempts the SCTP endpoint should 1086 make at resending the INIT. This value overrides the system SCTP 1087 'Max.Init.Retransmits' value. The default value of 0 indicates to 1088 use the endpoints default value. This is normally set to the 1089 system's default 'Max.Init.Retransmit' value. 1091 sinit_max_init_timeo: 16 bits (unsigned integer) 1093 This value represents the largest Time-Out or RTO value (in 1094 milliseconds) to use in attempting an INIT. Normally the 'RTO.Max' 1095 is used to limit the doubling of the RTO upon timeout. For the INIT 1096 message this value MAY override 'RTO.Max'. This value MUST NOT 1097 influence 'RTO.Max' during data transmission and is only used to 1098 bound the initial setup time. A default value of 0 indicates to use 1099 the endpoints default value. This is normally set to the system's 1100 'RTO.Max' value (60 seconds). 1102 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 1104 This cmsghdr structure specifies SCTP options for sendmsg() and 1105 describes SCTP header information about a received message through 1106 recvmsg(). 1108 cmsg_level cmsg_type cmsg_data[] 1109 ------------ ------------ ---------------------- 1110 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1112 Here is the definition of sctp_sndrcvinfo: 1114 struct sctp_sndrcvinfo { 1115 uint16_t sinfo_stream; 1116 uint16_t sinfo_ssn; 1117 uint16_t sinfo_flags; 1118 uint32_t sinfo_ppid; 1119 uint32_t sinfo_context; 1120 uint32_t sinfo_timetolive; 1121 uint32_t sinfo_tsn; 1122 uint32_t sinfo_cumtsn; 1123 sctp_assoc_t sinfo_assoc_id; 1125 }; 1127 sinfo_stream: 16 bits (unsigned integer) 1129 For recvmsg() the SCTP stack places the message's stream number in 1130 this value. For sendmsg() this value holds the stream number that 1131 the application wishes to send this message to. If a sender 1132 specifies an invalid stream number an error indication is returned 1133 and the call fails. 1135 sinfo_ssn: 16 bits (unsigned integer) 1137 For recvmsg() this value contains the stream sequence number that the 1138 remote endpoint placed in the DATA chunk. For fragmented messages 1139 this is the same number for all deliveries of the message (if more 1140 than one recvmsg() is needed to read the message). The sendmsg() 1141 call will ignore this parameter. 1143 sinfo_ppid: 32 bits (unsigned integer) 1145 This value in sendmsg() is an unsigned integer that is passed to the 1146 remote end in each user message. In recvmsg() this value is the same 1147 information that was passed by the upper layer in the peer 1148 application. Please note that the SCTP stack performs no byte order 1149 modification of this field. For example, if the DATA chunk has to 1150 contain a given value in network byte order, the SCTP user has to 1151 perform the htonl() computation. 1153 sinfo_context: 32 bits (unsigned integer) 1155 This value is an opaque 32 bit context datum that is used in the 1156 sendmsg() function. This value is passed back to the upper layer if 1157 a error occurs on the send of a message and is retrieved with each 1158 undelivered message (Note: if a endpoint has done multiple sends, all 1159 of which fail, multiple different sinfo_context values will be 1160 returned. One with each user data message). 1162 sinfo_flags: 16 bits (unsigned integer) 1164 This field may contain any of the following flags and is composed of 1165 a bitwise OR of these values. 1167 recvmsg() flags: 1169 SCTP_UNORDERED - This flag is present when the message was sent non- 1170 ordered. 1172 sendmsg() flags: 1173 SCTP_UNORDERED - This flag requests the un-ordered delivery of the 1174 message. If this flag is clear the datagram is considered an 1175 ordered send. 1177 SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the 1178 SCTP stack to override the primary destination address with the 1179 address found with the sendto/sendmsg call. 1181 SCTP_ABORT - Setting this flag causes the specified association to 1182 abort by sending an ABORT message to the peer (one-to-many style 1183 only). The ABORT chunk will contain an error cause 'User 1184 Initiated Abort' with cause code 12. The cause specific 1185 information of this error cause is provided in msg_iov. 1187 SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown 1188 procedures on the specified association. Graceful shutdown 1189 assures that all data enqueued by both endpoints is successfully 1190 transmitted before closing the association (one-to-many style 1191 only). 1193 SCTP_SENDALL - This flag, if set, will cause a one-to-many model 1194 socket to send the message to all associations that are currently 1195 established on this socket. For the one-to-one socket, this flag 1196 has no effect. 1198 sinfo_timetolive: 32 bit (unsigned integer) 1200 For the sending side, this field contains the message time to live in 1201 milliseconds. The sending side will expire the message within the 1202 specified time period if the message as not been sent to the peer 1203 within this time period. This value will override any default value 1204 set using any socket option. Also note that the value of 0 is 1205 special in that it indicates no timeout should occur on this message. 1207 sinfo_tsn: 32 bit (unsigned integer) 1209 For the receiving side, this field holds a TSN that was assigned to 1210 one of the SCTP Data Chunks. 1212 sinfo_cumtsn: 32 bit (unsigned integer) 1214 This field will hold the current cumulative TSN as known by the 1215 underlying SCTP layer. Note this field is ignored when sending and 1216 only valid for a receive operation when sinfo_flags are set to 1217 SCTP_UNORDERED. 1219 sinfo_assoc_id: sizeof (sctp_assoc_t) 1221 The association handle field, sinfo_assoc_id, holds the identifier 1222 for the association announced in the SCTP_COMM_UP notification. All 1223 notifications for a given association have the same identifier. 1224 Ignored for one-to-one style sockets. 1226 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1228 5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV) 1230 This cmsghdr structure specifies SCTP options for SCTP header 1231 information about a received message via recvmsg(). Note that this 1232 structure is an extended version of SCTP_SNDRCV and will only be 1233 received if the user has set the socket option SCTP_USE_EXT_RCVINFO 1234 to true in addition to any event subscription needed to receive 1235 ancillary data.. 1237 cmsg_level cmsg_type cmsg_data[] 1238 ------------ ------------ ---------------------- 1239 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1241 Here is the definition of sctp_sndrcvinfo: 1243 struct sctp_extrcvinfo { 1244 uint16_t sinfo_stream; 1245 uint16_t sinfo_ssn; 1246 uint16_t sinfo_flags; 1247 uint32_t sinfo_ppid; 1248 uint32_t sinfo_context; 1249 uint32_t sinfo_timetolive; 1250 uint32_t sinfo_tsn; 1251 uint32_t sinfo_cumtsn; 1252 sctp_assoc_t sinfo_assoc_id; 1253 uint16_t next_flags; 1254 uint16_t next_stream; 1255 uint32_t next_asocid; 1256 uint32_t next_length; 1257 uint32_t next_ppid; 1258 }; 1260 sinfo_stream: 16 bits (unsigned integer) 1261 For recvmsg() the SCTP stack places the message's stream number in 1262 this value. For sendmsg() this value holds the stream number that 1263 the application wishes to send this message to. If a sender 1264 specifies an invalid stream number an error indication is returned 1265 and the call fails. 1267 sinfo_ssn: 16 bits (unsigned integer) 1269 For recvmsg() this value contains the stream sequence number that the 1270 remote endpoint placed in the DATA chunk. For fragmented messages 1271 this is the same number for all deliveries of the message (if more 1272 than one recvmsg() is needed to read the message). The sendmsg() 1273 call will ignore this parameter. 1275 sinfo_ppid: 32 bits (unsigned integer) 1277 This value in sendmsg() is an unsigned integer that is passed to the 1278 remote end in each user message. In recvmsg() this value is the same 1279 information that was passed by the upper layer in the peer 1280 application. Please note that the SCTP stack performs no byte order 1281 modification of this field. For example, if the DATA chunk has to 1282 contain a given value in network byte order, the SCTP user has to 1283 perform the htonl() computation. 1285 sinfo_context: 32 bits (unsigned integer) 1287 This value is an opaque 32 bit context datum that is used in the 1288 sendmsg() function. This value is passed back to the upper layer if 1289 a error occurs on the send of a message and is retrieved with each 1290 undelivered message (Note: if a endpoint has done multiple sends, all 1291 of which fail, multiple different sinfo_context values will be 1292 returned. One with each user data message). 1294 sinfo_flags: 16 bits (unsigned integer) 1296 This field may contain any of the following flags and is composed of 1297 a bitwise OR of these values. 1299 recvmsg() flags: 1300 SCTP_UNORDERED - This flag is present when the message was sent non- 1301 ordered. 1303 sendmsg() flags: 1304 SCTP_UNORDERED - This flag requests the un-ordered delivery of the 1305 message. If this flag is clear the datagram is considered an 1306 ordered send. 1308 SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the 1309 SCTP stack to override the primary destination address with the 1310 address found with the sendto/sendmsg call. 1312 SCTP_ABORT - Setting this flag causes the specified association to 1313 abort by sending an ABORT message to the peer (one-to-many style 1314 only). The ABORT chunk will contain an error cause 'User 1315 Initiated Abort' with cause code 12. The cause specific 1316 information of this error cause is provided in msg_iov. 1318 SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown 1319 procedures on the specified association. Graceful shutdown 1320 assures that all data enqueued by both endpoints is successfully 1321 transmitted before closing the association (one-to-many style 1322 only). 1324 SCTP_SENDALL - This flag, if set, will cause a one-to-many model 1325 socket to send the message to all associations that are currently 1326 established on this socket. For the one-to-one socket, this flag 1327 has no effect. 1328 SCTP_EOR - This flag, if set, will indicate that this send 1329 terminates the record. 1331 sinfo_timetolive: 32 bit (unsigned integer) 1333 For the sending side, this field contains the message time to live in 1334 milliseconds. The sending side will expire the message within the 1335 specified time period if the message as not been sent to the peer 1336 within this time period. This value will override any default value 1337 set using any socket option. Also note that the value of 0 is 1338 special in that it indicates no timeout should occur on this message. 1340 sinfo_tsn: 32 bit (unsigned integer) 1342 For the receiving side, this field holds a TSN that was assigned to 1343 one of the SCTP Data Chunks. 1345 sinfo_cumtsn: 32 bit (unsigned integer) 1347 This field will hold the current cumulative TSN as known by the 1348 underlying SCTP layer. Note this field is ignored when sending and 1349 only valid for a receive operation when sinfo_flags are set to 1350 SCTP_UNORDERED. 1352 sinfo_assoc_id: sizeof (sctp_assoc_t) 1354 The association handle field, sinfo_assoc_id, holds the identifier 1355 for the association announced in the SCTP_COMM_UP notification. All 1356 notifications for a given association have the same identifier. 1357 Ignored for one-to-one style sockets. 1359 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1361 next_flags: 16 bit (unsigned integer) 1363 This bitmask will hold one or more of the following values: 1364 SCTP_NEXT_MSG_AVAIL - This bit, when set to 1, indicates that next 1365 message information is available i.e.: next_stream, next_asocid, 1366 next_length and next_ppid fields all have valid values. If this 1367 bit is set to 0, then these fields are not valid and should be 1368 ignored. 1370 SCTP_NEXT_MSG_ISCOMPLETE - This bit, when set, indicates that the 1371 next message is completely in the receive buffer. The next_length 1372 field thus contains the entire message size. If this flag is set 1373 to 0, then the next_length field only contains part of the message 1374 size since the message is still being received (it is being 1375 partially delivered). 1377 SCTP_NEXT_MSG_IS_UNORDERED - This bit, when set, indicates that the 1378 next message to be received was sent by the peer as unordered. If 1379 this bit is not set (i.e the bit is 0) the next message to be read 1380 is an ordered message in the stream specified. 1382 next_stream: 16 bit (unsigned integer) 1384 This value, when valid (see next_flags), contains the next stream 1385 number that will be received on a subsequent call to one of the 1386 receive message functions. 1388 next_asocid: 32 bit (unsigned integer) 1390 This value, when valid (see next_flags), contains the next 1391 association identification that will be received on a subsequent call 1392 to one of the receive message functions. 1394 next_length: 32 bit (unsigned integer) 1396 This value, when valid (see next_flags), contains the length of the 1397 next message that will be received on a subsequent call to one of the 1398 receive message functions. Note that this length may be a partial 1399 length depending on the settings of next_flags. 1401 next_ppid: 32 bit (unsigned integer) 1403 This value, when valid (see next_flags), contains the ppid of the 1404 next message that will be received on a subsequent call to one of the 1405 receive message functions. 1407 5.3. SCTP Events and Notifications 1409 An SCTP application may need to understand and process events and 1410 errors that happen on the SCTP stack. These events include network 1411 status changes, association startups, remote operational errors and 1412 undeliverable messages. All of these can be essential for the 1413 application. 1415 When an SCTP application layer does a recvmsg() the message read is 1416 normally a data message from a peer endpoint. If the application 1417 wishes to have the SCTP stack deliver notifications of non-data 1418 events, it sets the appropriate socket option for the notifications 1419 it wants. See Section 7.3 for these socket options. When a 1420 notification arrives, recvmsg() returns the notification in the 1421 application-supplied data buffer via msg_iov, and sets 1422 MSG_NOTIFICATION in msg_flags. 1424 This section details the notification structures. Every notification 1425 structure carries some common fields which provides general 1426 information. 1428 A recvmsg() call will return only one notification at a time. Just 1429 as when reading normal data, it may return part of a notification if 1430 the msg_iov buffer is not large enough. If a single read is not 1431 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1432 reading the notification before subsequent data can arrive. 1434 5.3.1. SCTP Notification Structure 1436 The notification structure is defined as the union of all 1437 notification types. 1439 union sctp_notification { 1440 struct { 1441 uint16_t sn_type; /* Notification type. */ 1442 uint16_t sn_flags; 1443 uint32_t sn_length; 1444 } sn_header; 1445 struct sctp_assoc_change sn_assoc_change; 1446 struct sctp_paddr_change sn_paddr_change; 1447 struct sctp_remote_error sn_remote_error; 1448 struct sctp_send_failed sn_send_failed; 1449 struct sctp_shutdown_event sn_shutdown_event; 1450 struct sctp_adaptation_event sn_adaptation_event; 1451 struct sctp_pdapi_event sn_pdapi_event; 1452 struct sctp_authkey_event sn_auth_event; 1453 }; 1455 sn_type: 16 bits (unsigned integer) 1457 The following list describes the SCTP notification and event types 1458 for the field sn_type. 1460 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1461 been opened or closed. Refer to Section 5.3.1.1 for details. 1462 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1463 part of an existing association has experienced a change of state 1464 (e.g. a failure or return to service of the reachability of a 1465 endpoint via a specific transport address). Please see 1466 Section 5.3.1.2 for data structure details. 1467 SCTP_REMOTE_ERROR: The attached error message is an Operational 1468 Error received from the remote peer. It includes the complete TLV 1469 sent by the remote endpoint. See Section 5.3.1.3 for the detailed 1470 format. 1471 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1472 remote endpoint. This structure includes the original 1473 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1474 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1475 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1476 should be sent on this socket. 1477 SCTP_ADAPTATION_INDICATION: This notification holds the peers 1478 indicated adaptation layer. Please see Section 5.3.1.6. 1479 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1480 receiver that the partial delivery has been aborted. This may 1481 indicate the association is about to be aborted. Please see 1482 Section 5.3.1.7 1484 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a 1485 receiver that either an error occurred on authentication, or a new 1486 key was made active. Section 5.3.1.8 1488 All standard values for sn_type are greater than 2^15. Values from 1489 2^15 and down are reserved. 1491 sn_flags: 16 bits (unsigned integer) 1493 These are notification-specific flags. 1495 sn_length: 32 bits (unsigned integer) 1497 This is the length of the whole sctp_notification structure including 1498 the sn_type, sn_flags, and sn_length fields. 1500 5.3.1.1. SCTP_ASSOC_CHANGE 1502 Communication notifications inform the ULP that an SCTP association 1503 has either begun or ended. The identifier for a new association is 1504 provided by this notification. The notification information has the 1505 following format: 1507 struct sctp_assoc_change { 1508 uint16_t sac_type; 1509 uint16_t sac_flags; 1510 uint32_t sac_length; 1511 uint16_t sac_state; 1512 uint16_t sac_error; 1513 uint16_t sac_outbound_streams; 1514 uint16_t sac_inbound_streams; 1515 sctp_assoc_t sac_assoc_id; 1516 uint8_t sac_info[0]; 1517 }; 1519 sac_type: 1521 It should be SCTP_ASSOC_CHANGE. 1523 sac_flags: 16 bits (unsigned integer) 1525 Currently unused. 1527 sac_length: 32 bits (unsigned integer) 1529 This field is the total length of the notification data, including 1530 the notification header. 1532 sac_state: 16 bits (signed integer) 1534 This field holds one of a number of values that communicate the event 1535 that happened to the association. They include: 1537 Event Name Description 1539 ---------------- --------------- 1541 SCTP_COMM_UP - A new association is now ready and data may be 1542 exchanged with this peer. 1543 SCTP_COMM_LOST - The association has failed. The association is now 1544 in the closed state. If SEND FAILED notifications are turned on, 1545 a SCTP_COMM_LOST is followed by a series of SCTP_SEND_FAILED 1546 events, one for each outstanding message. 1547 SCTP_RESTART - SCTP has detected that the peer has restarted. 1548 SCTP_SHUTDOWN_COMP - The association has gracefully closed. 1549 SCTP_CANT_STR_ASSOC - The association failed to setup. If non 1550 blocking mode is set and data was sent (in the udp mode), a 1551 SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED 1552 events, one for each outstanding message. 1554 sac_error: 16 bits (signed integer) 1556 If the state was reached due to a error condition (e.g. 1557 SCTP_COMM_LOST) any relevant error information is available in this 1558 field. This corresponds to the protocol error codes defined in 1559 RFC2960 [RFC2960]. 1561 sac_outbound_streams: 16 bits (unsigned integer) 1563 sac_inbound_streams: 16 bits (unsigned integer) 1565 The maximum number of streams allowed in each direction are available 1566 in sac_outbound_streams and sac_inbound streams. 1568 sac_assoc_id: sizeof (sctp_assoc_t) 1570 The association id field, holds the identifier for the association. 1571 All notifications for a given association have the same association 1572 identifier. For one-to-one style socket, this field is ignored. 1574 sac_info: variable 1576 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1577 for this association, sac_info[] contains the complete ABORT chunk as 1578 defined in the SCTP specification RFC2960 [RFC2960] section 3.3.7. 1580 5.3.1.2. SCTP_PEER_ADDR_CHANGE 1582 When a destination address on a multi-homed peer encounters a change 1583 an interface details event is sent. The information has the 1584 following structure: 1586 struct sctp_paddr_change { 1587 uint16_t spc_type; 1588 uint16_t spc_flags; 1589 uint32_t spc_length; 1590 struct sockaddr_storage spc_aaddr; 1591 uint32_t spc_state; 1592 uint32_t spc_error; 1593 sctp_assoc_t spc_assoc_id; 1594 } 1596 spc_type: 1598 It should be SCTP_PEER_ADDR_CHANGE. 1600 spc_flags: 16 bits (unsigned integer) 1602 Currently unused. 1604 spc_length: 32 bits (unsigned integer) 1606 This field is the total length of the notification data, including 1607 the notification header. 1609 spc_aaddr: sizeof (struct sockaddr_storage) 1611 The affected address field, holds the remote peer's address that is 1612 encountering the change of state. 1614 spc_state: 32 bits (signed integer) 1616 This field holds one of a number of values that communicate the event 1617 that happened to the address. They include: 1619 Event Name Description 1621 ---------------- --------------- 1622 SCTP_ADDR_AVAILABLE - This address is now reachable. 1623 SCTP_ADDR_UNREACHABLE - The address specified can no longer be 1624 reached. Any data sent to this address is rerouted to an 1625 alternate until this address becomes reachable. 1626 SCTP_ADDR_REMOVED - The address is no longer part of the 1627 association. 1628 SCTP_ADDR_ADDED - The address is now part of the association. 1629 SCTP_ADDR_MADE_PRIM - This address has now been made to be the 1630 primary destination address. 1631 SCTP_ADDR_CONFIRMED - This address has now been confirmed as a valid 1632 address. 1634 spc_error: 32 bits (signed integer) 1636 If the state was reached due to any error condition (e.g. 1637 SCTP_ADDR_UNREACHABLE) any relevant error information is available in 1638 this field. 1640 spc_assoc_id: sizeof (sctp_assoc_t) 1642 The association id field, holds the identifier for the association. 1643 All notifications for a given association have the same association 1644 identifier. For one-to-one style socket, this field is ignored. 1646 5.3.1.3. SCTP_REMOTE_ERROR 1648 A remote peer may send an Operational Error message to its peer. 1649 This message indicates a variety of error conditions on an 1650 association. The entire ERROR chunk as it appears on the wire is 1651 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1652 specification RFC2960 [RFC2960] and any extensions for a list of 1653 possible error formats. SCTP error notifications have the format: 1655 struct sctp_remote_error { 1656 uint16_t sre_type; 1657 uint16_t sre_flags; 1658 uint32_t sre_length; 1659 uint16_t sre_error; 1660 sctp_assoc_t sre_assoc_id; 1661 uint8_t sre_data[0]; 1662 }; 1664 sre_type: 1666 It should be SCTP_REMOTE_ERROR. 1668 sre_flags: 16 bits (unsigned integer) 1670 Currently unused. 1672 sre_length: 32 bits (unsigned integer) 1674 This field is the total length of the notification data, including 1675 the notification header and the contents of sre_data. 1677 sre_error: 16 bits (unsigned integer) 1679 This value represents one of the Operational Error causes defined in 1680 the SCTP specification, in network byte order. 1682 sre_assoc_id: sizeof (sctp_assoc_t) 1684 The association id field, holds the identifier for the association. 1685 All notifications for a given association have the same association 1686 identifier. For one-to-one style socket, this field is ignored. 1688 sre_data: variable 1690 This contains the ERROR chunk as defined in the SCTP specification 1691 RFC2960 [RFC2960] section 3.3.10. 1693 5.3.1.4. SCTP_SEND_FAILED 1695 If SCTP cannot deliver a message it may return the message as a 1696 notification. 1698 struct sctp_send_failed { 1699 uint16_t ssf_type; 1700 uint16_t ssf_flags; 1701 uint32_t ssf_length; 1702 uint32_t ssf_error; 1703 struct sctp_sndrcvinfo ssf_info; 1704 sctp_assoc_t ssf_assoc_id; 1705 uint8_t ssf_data[0]; 1706 }; 1708 ssf_type: 1710 It should be SCTP_SEND_FAILED. 1712 ssf_flags: 16 bits (unsigned integer) 1713 The flag value will take one of the following values: 1715 SCTP_DATA_UNSENT - Indicates that the data was never put on the 1716 wire. 1717 SCTP_DATA_SENT - Indicates that the data was put on the wire. Note 1718 that this does not necessarily mean that the data was (or was not) 1719 successfully delivered. 1721 ssf_length: 32 bits (unsigned integer) 1723 This field is the total length of the notification data, including 1724 the notification header and the payload in ssf_data. 1726 ssf_error: 16 bits (unsigned integer) 1728 This value represents the reason why the send failed, and if set, 1729 will be a SCTP protocol error code as defined in RFC2960 [RFC2960] 1730 section 3.3.10. 1732 ssf_info: sizeof (struct sctp_sndrcvinfo) 1734 The original send information associated with the undelivered 1735 message. 1737 ssf_assoc_id: sizeof (sctp_assoc_t) 1739 The association id field, sf_assoc_id, holds the identifier for the 1740 association. All notifications for a given association have the same 1741 association identifier. For one-to-one style socket, this field is 1742 ignored. 1744 ssf_data: variable length 1746 The undelivered message, exactly as delivered by the caller to the 1747 original send*() call. 1749 5.3.1.5. SCTP_SHUTDOWN_EVENT 1751 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1752 inform the application that it should cease sending data. 1754 struct sctp_shutdown_event { 1755 uint16_t sse_type; 1756 uint16_t sse_flags; 1757 uint32_t sse_length; 1758 sctp_assoc_t sse_assoc_id; 1759 }; 1761 sse_type 1763 It should be SCTP_SHUTDOWN_EVENT 1765 sse_flags: 16 bits (unsigned integer) 1767 Currently unused. 1769 sse_length: 32 bits (unsigned integer) 1771 This field is the total length of the notification data, including 1772 the notification header. It will generally be sizeof (struct 1773 sctp_shutdown_event). 1775 sse_flags: 16 bits (unsigned integer) 1777 Currently unused. 1779 sse_assoc_id: sizeof (sctp_assoc_t) 1781 The association id field, holds the identifier for the association. 1782 All notifications for a given association have the same association 1783 identifier. For one-to-one style socket, this field is ignored. 1785 5.3.1.6. SCTP_ADAPTATION_INDICATION 1787 When a peer sends a Adaptation Layer Indication parameter , SCTP 1788 delivers this notification to inform the application that of the 1789 peers requested adaptation layer. 1791 struct sctp_adaptation_event { 1792 uint16_t sai_type; 1793 uint16_t sai_flags; 1794 uint32_t sai_length; 1795 uint32_t sai_adaptation_ind; 1796 sctp_assoc_t sai_assoc_id; 1797 }; 1799 sai_type 1801 It should be SCTP_ADAPTATION_INDICATION 1803 sai_flags: 16 bits (unsigned integer) 1805 Currently unused. 1807 sai_length: 32 bits (unsigned integer) 1808 This field is the total length of the notification data, including 1809 the notification header. It will generally be sizeof (struct 1810 sctp_adaptation_event). 1812 sai_adaptation_ind: 32 bits (unsigned integer) 1814 This field holds the bit array sent by the peer in the adaptation 1815 layer indication parameter. The bits are in network byte order. 1817 sai_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 5.3.1.7. SCTP_PARTIAL_DELIVERY_EVENT 1825 When a receiver is engaged in a partial delivery of a message this 1826 notification will be used to indicate various events. 1828 struct sctp_pdapi_event { 1829 uint16_t pdapi_type; 1830 uint16_t pdapi_flags; 1831 uint32_t pdapi_length; 1832 uint32_t pdapi_indication; 1833 sctp_assoc_t pdapi_assoc_id; 1834 }; 1836 pdapi_type 1838 It should be SCTP_PARTIAL_DELIVERY_EVENT 1840 pdapi_flags: 16 bits (unsigned integer) 1842 Currently unused. 1844 pdapi_length: 32 bits (unsigned integer) 1846 This field is the total length of the notification data, including 1847 the notification header. It will generally be sizeof (struct 1848 sctp_pdapi_event). 1850 pdapi_indication: 32 bits (unsigned integer) 1852 This field holds the indication being sent to the application 1853 possible values include: 1855 SCTP_PARTIAL_DELIVERY_ABORTED 1856 pdapi_assoc_id: sizeof (sctp_assoc_t) 1858 The association id field, holds the identifier for the association. 1859 All notifications for a given association have the same association 1860 identifier. For one-to-one style socket, this field is ignored. 1862 5.3.1.8. SCTP_AUTHENTICATION_EVENT 1864 When a receiver is using authentication this message will provide 1865 notifications regarding new keys being made active as well as errors. 1867 struct sctp_authkey_event { 1868 uint16_t auth_type; 1869 uint16_t auth_flags; 1870 uint32_t auth_length; 1871 uint16_t auth_keynumber; 1872 uint16_t auth_altkeynumber; 1873 uint32_t auth_indication; 1874 sctp_assoc_t auth_assoc_id; 1875 }; 1877 auth_type 1879 It should be SCTP_AUTHENTICATION_EVENT 1881 auth_flags: 16 bits (unsigned integer) 1883 Currently unused. 1885 auth_length: 32 bits (unsigned integer) 1887 This field is the total length of the notification data, including 1888 the notification header. It will generally be sizeof (struct 1889 sctp_authkey_event). 1891 auth_keynumber: 32 bits (unsigned integer) 1893 This field holds the keynumber set by the user for the effected key. 1894 If more than one key is involved, this will contain one of the keys 1895 involved in the notification. 1897 auth_altkeynumber: 32 bits (unsigned integer) 1899 This field holds an alternate keynumber which is used by some 1900 notifications. 1902 auth_indication: 32 bits (unsigned integer) 1903 This field hold the error or indication being reported. The 1904 following values are currently defined: 1905 SCTP_AUTH_NEWKEY - this report indicates that a new key has been 1906 made active (used for the first time by the peer) and is now the 1907 active key. The auth_keynumber field holds the user specified key 1908 number. 1910 auth_assoc_id: sizeof (sctp_assoc_t) 1912 The association id field, holds the identifier for the association. 1913 All notifications for a given association have the same association 1914 identifier. 1916 5.4. Ancillary Data Considerations and Semantics 1918 Programming with ancillary socket data contains some subtleties and 1919 pitfalls, which are discussed below. 1921 5.4.1. Multiple Items and Ordering 1923 Multiple ancillary data items may be included in any call to 1924 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1925 items, or both. 1927 The ordering of ancillary data items (either by SCTP or another 1928 protocol) is not significant and is implementation-dependent, so 1929 applications must not depend on any ordering. 1931 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1932 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1933 sendmsg() or recvmsg() call. 1935 5.4.2. Accessing and Manipulating Ancillary Data 1937 Applications can infer the presence of data or ancillary data by 1938 examining the msg_iovlen and msg_controllen msghdr members, 1939 respectively. 1941 Implementations may have different padding requirements for ancillary 1942 data, so portable applications should make use of the macros 1943 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1944 RFC2292 [RFC2292] and your SCTP implementation's documentation for 1945 more information. Following is an example, from RFC2292 [RFC2292], 1946 demonstrating the use of these macros to access ancillary data: 1948 struct msghdr msg; 1949 struct cmsghdr *cmsgptr; 1951 /* fill in msg */ 1953 /* call recvmsg() */ 1955 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1956 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1957 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1958 u_char *ptr; 1960 ptr = CMSG_DATA(cmsgptr); 1961 /* process data pointed to by ptr */ 1962 } 1963 } 1965 5.4.3. Control Message Buffer Sizing 1967 The information conveyed via SCTP_SNDRCV events will often be 1968 fundamental to the correct and sane operation of the sockets 1969 application. This is particularly true of the one-to-many semantics, 1970 but also of the one-ton-one semantics. For example, if an 1971 application needs to send and receive data on different SCTP streams, 1972 SCTP_SNDRCV events are indispensable. 1974 Given that some ancillary data is critical, and that multiple 1975 ancillary data items may appear in any order, applications should be 1976 carefully written to always provide a large enough buffer to contain 1977 all possible ancillary data that can be presented by recvmsg(). If 1978 the buffer is too small, and crucial data is truncated, it may pose a 1979 fatal error condition. 1981 Thus it is essential that applications be able to deterministically 1982 calculate the maximum required buffer size to pass to recvmsg(). One 1983 constraint imposed on this specification that makes this possible is 1984 that all ancillary data definitions are of a fixed length. One way 1985 to calculate the maximum required buffer size might be to take the 1986 sum the sizes of all enabled ancillary data item structures, as 1987 calculated by CMSG_SPACE. For example, if we enabled 1988 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [RFC2292], we would 1989 calculate and allocate the buffer size as follows: 1991 size_t total; 1992 void *buf; 1994 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1995 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1997 buf = malloc(total); 1999 We could then use this buffer for msg_control on each call to 2000 recvmsg() and be assured that we would not lose any ancillary data to 2001 truncation. 2003 6. Common Operations for Both Styles 2005 6.1. send(), recv(), sendto(), recvfrom() 2007 Applications can use send() and sendto() to transmit data to the peer 2008 of an SCTP endpoint. recv() and recvfrom() can be used to receive 2009 data from the peer. 2011 The syntax is: 2013 ssize_t send(int sd, const void *msg, size_t len, int flags); 2014 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 2015 const struct sockaddr *to, socklen_t tolen); 2016 ssize_t recv(int sd, void *buf, size_t len, int flags); 2017 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 2018 struct sockaddr *from, socklen_t *fromlen); 2020 sd - the socket descriptor of an SCTP endpoint. 2021 msg - the message to be sent. 2022 len - the size of the message or the size of buffer. 2023 to - one of the peer addresses of the association to be used to send 2024 the message. 2025 tolen - the size of the address. 2026 buf - the buffer to store a received message. 2027 from - the buffer to store the peer address used to send the 2028 received message. 2029 fromlen - the size of the from address 2030 flags - (described below). 2032 These calls give access to only basic SCTP protocol features. If 2033 either peer in the association uses multiple streams, or sends 2034 unordered data these calls will usually be inadequate, and may 2035 deliver the data in unpredictable ways. 2037 SCTP has the concept of multiple streams in one association. The 2038 above calls do not allow the caller to specify on which stream a 2039 message should be sent. The system uses stream 0 as the default 2040 stream for send() and sendto(). recv() and recvfrom() return data 2041 from any stream, but the caller can not distinguish the different 2042 streams. This may result in data seeming to arrive out of order. 2043 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 2044 provide no indication. 2046 SCTP is message based. The msg buffer above in send() and sendto() 2047 is considered to be a single message. This means that if the caller 2048 wants to send a message which is composed by several buffers, the 2049 caller needs to combine them before calling send() or sendto(). 2050 Alternately, the caller can use sendmsg() to do that without 2051 combining them. recv() and recvfrom() cannot distinguish message 2052 boundaries. 2054 In receiving, if the buffer supplied is not large enough to hold a 2055 complete message, the receive call acts like a stream socket and 2056 returns as much data as will fit in the buffer. 2058 Note, the send() and recv() calls may not be used for a one-to-many 2059 style socket. 2061 Note, if an application calls a send function with no user data and 2062 no ancillary data the SCTP implementation should reject the request 2063 with an appropriate error message. An implementation is NOT allowed 2064 to send a Data chunk with no user data RFC2960 [RFC2960]. 2066 6.2. setsockopt(), getsockopt() 2068 Applications use setsockopt() and getsockopt() to set or retrieve 2069 socket options. Socket options are used to change the default 2070 behavior of sockets calls. They are described in Section 7 2072 The syntax is: 2074 ret = getsockopt(int sd, int level, int optname, void *optval, 2075 socklen_t *optlen); 2076 ret = setsockopt(int sd, int level, int optname, const void *optval, 2077 socklen_t optlen); 2079 sd - the socket descriptor. 2080 level - set to IPPROTO_SCTP for all SCTP options. 2082 optname - the option name. 2083 optval - the buffer to store the value of the option. 2084 optlen - the size of the buffer (or the length of the option 2085 returned). 2087 All socket options set on a 1-to-1 listening sockets also apply all 2088 accepted sockets. All socket options set on a 1-to-many socket using 2089 the assoc_id 0 applies for all future assocs on the socket. 2091 6.3. read() and write() 2093 Applications can use read() and write() to send and receive data to 2094 and from peer. They have the same semantics as send() and recv() 2095 except that the flags parameter cannot be used. 2097 Note, these calls, when used in the one-to-many style, may only be 2098 used with branched off socket descriptors (see Section 8.2). 2100 6.4. getsockname() 2102 Applications use getsockname() to retrieve the locally-bound socket 2103 address of the specified socket. This is especially useful if the 2104 caller let SCTP chose a local port. This call is for where the 2105 endpoint is not multi-homed. It does not work well with multi-homed 2106 sockets. See Section 8.5 for a multi-homed version of the call. 2108 The syntax is: 2110 int getsockname(int sd, struct sockaddr *address, 2111 socklen_t *len); 2113 sd - the socket descriptor to be queried. 2114 address - On return, one locally bound address (chosen by the SCTP 2115 stack) is stored in this buffer. If the socket is an IPv4 socket, 2116 the address will be IPv4. If the socket is an IPv6 socket, the 2117 address will be either an IPv6 or IPv4 address. 2118 len - The caller should set the length of address here. On return, 2119 this is set to the length of the returned address. 2121 If the actual length of the address is greater than the length of the 2122 supplied sockaddr structure, the stored address will be truncated. 2124 If the socket has not been bound to a local name, the value stored in 2125 the object pointed to by address is unspecified. 2127 7. Socket Options 2129 The following sub-section describes various SCTP level socket options 2130 that are common to both styles. SCTP associations can be multi- 2131 homed. Therefore, certain option parameters include a 2132 sockaddr_storage structure to select which peer address the option 2133 should be applied to. 2135 For the one-to-many style sockets, an sctp_assoc_t structure 2136 (association ID) is used to identify the the association instance 2137 that the operation affects. So it must be set when using this style. 2139 For the one-to-one style sockets and branched off one-to-many style 2140 sockets (see Section 8.2) this association ID parameter is ignored. 2142 Note that socket or IP level options are set or retrieved per socket. 2143 This means that for one-to-many style sockets, those options will be 2144 applied to all associations belonging to the socket. And for one-to- 2145 one style, those options will be applied to all peer addresses of the 2146 association controlled by the socket. Applications should be very 2147 careful in setting those options. 2149 For some IP stacks getsockopt() is read-only; so a new interface will 2150 be needed when information must be passed both in to and out of the 2151 SCTP stack. The syntax for sctp_opt_info() is, 2153 int sctp_opt_info(int sd, 2154 sctp_assoc_t id, 2155 int opt, 2156 void *arg, 2157 socklen_t *size); 2159 The sctp_opt_info() call is a replacement for getsockopt() only and 2160 will not set any options associated with the specified socket. A 2161 setsockopt() must be used to set any writeable option. 2163 For one-to-many style sockets, id specifies the association to query. 2164 For one-to-one style sockets, id is ignored. 2166 opt specifies which SCTP socket option to get. It can get any socket 2167 option currently supported that requests information (either read/ 2168 write options or read only) such as: 2169 SCTP_RTOINFO 2170 SCTP_ASSOCINFO 2171 SCTP_DEFAULT_SEND_PARAM 2172 SCTP_GET_PEER_ADDR_INFO 2173 SCTP_PRIMARY_ADDR 2174 SCTP_PEER_ADDR_PARAMS 2175 SCTP_STATUS 2176 SCTP_AUTH_ACTIVE_KEY 2177 SCTP_PEER_AUTH_CHUNKS 2178 SCTP_LOCAL_AUTH_CHUNKS 2180 arg is an option-specific structure buffer provided by the caller. 2181 See Section 8.5) subsections for more information on these options 2182 and option-specific structures. 2184 sctp_opt_info() returns 0 on success, or on failure returns -1 and 2185 sets errno to the appropriate error code. 2187 All options that support specific settings on an association by 2188 filling in either an association id variable or a sockaddr_storage 2189 SHOULD also support setting of the same value for the entire endpoint 2190 (i.e. future associations). To accomplish this the following logic 2191 is used when setting one of these options: 2193 a) If an address is specified via a sockaddr_storage that is included 2194 in the structure, the address is used to lookup the association 2195 and the settings are applied to the specific address (if 2196 appropriate) or to the entire association. 2197 b) If an association identification is filled in but not a 2198 sockaddr_storage (if present), the association is found using the 2199 association identification and the settings should be applied to 2200 the entire association (since a specific address is not 2201 specified). Note this also applies to options that hold an 2202 association identification in their structure but do not have a 2203 sockaddr_storage field. 2204 c) If neither the sockaddr_storage or association identification is 2205 set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 2206 the association identification is 0, the settings are a default 2207 and to be applied to the endpoint (all future associations). 2209 7.1. Read / Write Options 2211 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 2213 The protocol parameters used to initialize and bound retransmission 2214 timeout (RTO) are tunable. See RFC2960 [RFC2960] for more 2215 information on how these parameters are used in RTO calculation. 2217 The following structure is used to access and modify these 2218 parameters: 2220 struct sctp_rtoinfo { 2221 sctp_assoc_t srto_assoc_id; 2222 uint32_t srto_initial; 2223 uint32_t srto_max; 2224 uint32_t srto_min; 2225 }; 2227 srto_initial - This contains the initial RTO value. 2228 srto_max and srto_min - These contain the maximum and minimum bounds 2229 for all RTOs. 2230 srto_assoc_id - (one-to-many style socket) This is filled in the 2231 application, and identifies the association for this query. If 2232 this parameter is '0' (on a one-to-many style socket), then the 2233 change effects the entire endpoint. 2235 All parameters are time values, in milliseconds. A value of 0, when 2236 modifying the parameters, indicates that the current value should not 2237 be changed. 2239 To access or modify these parameters, the application should call 2240 getsockopt or setsockopt() respectively with the option name 2241 SCTP_RTOINFO. 2243 7.1.2. Association Parameters (SCTP_ASSOCINFO) 2245 This option is used to both examine and set various association and 2246 endpoint parameters. 2248 See RFC2960 [RFC2960] for more information on how this parameter is 2249 used. The peer address parameter is ignored for one-to-one style 2250 socket. 2252 The following structure is used to access and modify this parameters: 2254 struct sctp_assocparams { 2255 sctp_assoc_t sasoc_assoc_id; 2256 uint16_t sasoc_asocmaxrxt; 2257 uint16_t sasoc_number_peer_destinations; 2258 uint32_t sasoc_peer_rwnd; 2259 uint32_t sasoc_local_rwnd; 2260 uint32_t sasoc_cookie_life; 2261 }; 2263 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2264 to make for the association. 2266 sasoc_number_peer_destinations - This is the number of destination 2267 addresses that the peer has. 2268 sasoc_peer_rwnd - This holds the current value of the peers rwnd 2269 (reported in the last SACK) minus any outstanding data (i.e. data 2270 inflight). 2271 sasoc_local_rwnd - This holds the last reported rwnd that was sent 2272 to the peer. 2273 sasoc_cookie_life - This is the associations cookie life value used 2274 when issuing cookies. 2275 sasoc_assoc_id - This is filled in the application, and identifies 2276 the association for this query. 2278 This information may be examined for either the endpoint or a 2279 specific association. To examine a endpoints default parameters the 2280 association id (sasoc_assoc_id) should must be set to the value '0'. 2281 The values of the sasoc_peer_rwnd is meaningless when examining 2282 endpoint information. 2284 All parameters are time values, in milliseconds. A value of 0, when 2285 modifying the parameters, indicates that the current value should not 2286 be changed. 2288 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2289 on either an endpoint or association basis. The rwnd and destination 2290 counts (sasoc_number_peer_destinations, 2291 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2292 placed in these is ignored. 2294 To access or modify these parameters, the application should call 2295 getsockopt or setsockopt() respectively with the option name 2296 SCTP_ASSOCINFO. 2298 The maximum number of retransmissions before an address is considered 2299 unreachable is also tunable, but is address-specific, so it is 2300 covered in a separate option. If an application attempts to set the 2301 value of the association maximum retransmission parameter to more 2302 than the sum of all maximum retransmission parameters, setsockopt() 2303 shall return an error. The reason for this, from RFC2960 [RFC2960] 2304 section 8.2: 2306 Note: When configuring the SCTP endpoint, the user should avoid 2307 having the value of 'Association.Max.Retrans' larger than the 2308 summation of the 'Path.Max.Retrans' of all the destination addresses 2309 for the remote endpoint. Otherwise, all the destination addresses 2310 may become inactive while the endpoint still considers the peer 2311 endpoint reachable. 2313 7.1.3. Initialization Parameters (SCTP_INITMSG) 2315 Applications can specify protocol parameters for the default 2316 association initialization. The structure used to access and modify 2317 these parameters is defined in Section 5.2.1). The option name 2318 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2320 Setting initialization parameters is effective only on an unconnected 2321 socket (for one-to-many style sockets only future associations are 2322 effected by the change). With one-to-one style sockets, this option 2323 is inherited by sockets derived from a listener socket. 2325 7.1.4. SO_LINGER 2327 An application using the one-to-one style socket can use this option 2328 to perform the SCTP ABORT primitive. The linger option structure is: 2330 struct linger { 2331 int l_onoff; /* option on/off */ 2332 int l_linger; /* linger time */ 2333 }; 2335 To enable the option, set l_onoff to 1. If the l_linger value is set 2336 to 0, calling close() is the same as the ABORT primitive. If the 2337 value is set to a negative value, the setsockopt() call will return 2338 an error. If the value is set to a positive value linger_time, the 2339 close() can be blocked for at most linger_time ms. If the graceful 2340 shutdown phase does not finish during this period, close() will 2341 return but the graceful shutdown phase continues in the system. 2343 Note, this is a socket level option NOT an SCTP level option. So 2344 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2345 setsockopt() call. 2347 7.1.5. SCTP_NODELAY 2349 Turn on/off any Nagle-like algorithm. This means that packets are 2350 generally sent as soon as possible and no unnecessary delays are 2351 introduced, at the cost of more packets in the network. Expects an 2352 integer boolean flag. 2354 7.1.6. SO_RCVBUF 2356 Sets receive buffer size in octets. For SCTP one-to-one style 2357 sockets, this controls the receiver window size. For one-to-many 2358 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF 2359 (see Section 3.4). If the implementation defines HAVE_SCTP_MULTIBUF 2360 as 1, this controls the receiver window size for each association 2361 bound to the socket descriptor. If the implementation defines 2362 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive 2363 buffer for the whole socket. The call expects an integer. 2365 7.1.7. SO_SNDBUF 2367 Sets send buffer size. For SCTP one-to-one style sockets, this 2368 controls the amount of data SCTP may have waiting in internal buffers 2369 to be sent. This option therefore bounds the maximum size of data 2370 that can be sent in a single send call. For one-to-many style 2371 sockets, the effect is the same, except that it applies to one or all 2372 associations (see Section 3.4) bound to the socket descriptor used in 2373 the setsockopt() or getsockopt() call. The option applies to each 2374 association's window size separately. The call expects an integer. 2376 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) 2378 This socket option is applicable to the one-to-many style socket 2379 only. When set it will cause associations that are idle for more 2380 than the specified number of seconds to automatically close using the 2381 graceful shutdown procedure. An association being idle is defined as 2382 an association that has NOT sent or received user data. The special 2383 value of '0' indicates that no automatic close of any associations 2384 should be performed, this is the default value. The option expects 2385 an integer defining the number of seconds of idle time before an 2386 association is closed. 2388 An application using this option should enable receiving the 2389 association change notification. This is the only mechanism an 2390 application is informed about the closing of an association. After 2391 an association is closed, the association ID assigned to it can be 2392 reused. An application should be aware of this to avoid the possible 2393 problem of sending data to an incorrect peer end point. 2395 7.1.9. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2397 Requests that the peer mark the enclosed address as the association 2398 primary. The enclosed address must be one of the association's 2399 locally bound addresses. The following structure is used to make a 2400 set primary request: 2402 struct sctp_setpeerprim { 2403 sctp_assoc_t sspp_assoc_id; 2404 struct sockaddr_storage sspp_addr; 2405 }; 2406 sspp_addr - The address to set as primary 2407 sspp_assoc_id - This is filled in by the application, and identifies 2408 the association for this request. 2410 This functionality is optional. Implementations that do not support 2411 this functionality should return EOPNOTSUPP. 2413 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) 2415 Requests that the local SCTP stack use the enclosed peer address as 2416 the association primary. The enclosed address must be one of the 2417 association peer's addresses. The following structure is used to 2418 make a set peer primary request: 2420 struct sctp_setprim { 2421 sctp_assoc_t ssp_assoc_id; 2422 struct sockaddr_storage ssp_addr; 2423 }; 2425 ssp_addr - The address to set as primary 2426 ssp_assoc_id - This is filled in by the application, and identifies 2427 the association for this request. 2429 7.1.11. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER) 2431 Requests that the local endpoint set the specified Adaptation Layer 2432 Indication parameter for all future INIT and INIT-ACK exchanges. 2434 struct sctp_setadaptation { 2435 uint32_t ssb_adaptation_ind; 2436 }; 2438 ssb_adaptation_ind - The adaptation layer indicator that will be 2439 included in any outgoing Adaptation Layer Indication parameter. 2441 7.1.12. Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2443 This option is a on/off flag and is passed an integer where a non- 2444 zero is on and a zero is off. If enabled no SCTP message 2445 fragmentation will be performed. Instead if a message being sent 2446 exceeds the current PMTU size, the message will NOT be sent and 2447 instead a error will be indicated to the user. 2449 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2451 Applications can enable or disable heartbeats for any peer address of 2452 an association, modify an address's heartbeat interval, force a 2453 heartbeat to be sent immediately, and adjust the address's maximum 2454 number of retransmissions sent before an address is considered 2455 unreachable. The following structure is used to access and modify an 2456 address's parameters: 2458 struct sctp_paddrparams { 2459 sctp_assoc_t spp_assoc_id; 2460 struct sockaddr_storage spp_address; 2461 uint32_t spp_hbinterval; 2462 uint16_t spp_pathmaxrxt; 2463 uint32_t spp_pathmtu; 2464 uint32_t spp_sackdelay; 2465 uint32_t spp_flags; 2466 uint32_t spp_ipv6_flowlabel; 2467 uint8_t spp_ipv4_tos; 2468 }; 2470 spp_assoc_id - (one-to-many style socket) This is filled in the 2471 application, and identifies the association for this query. 2472 spp_address - This specifies which address is of interest. 2473 spp_hbinterval - This contains the value of the heartbeat interval, 2474 in milliseconds. Note that unless the spp_flag is set to 2475 SPP_HB_ENABLE the value of this field is ignored. Note also that 2476 a value of zero indicates the current setting should be left 2477 unchanged. To set an actual value of zero the use of the flag 2478 SPP_HB_TIME_IS_ZERO should be used. 2479 spp_pathmaxrxt - This contains the maximum number of retransmissions 2480 before this address shall be considered unreachable. Note that 2481 unless the spp_flag is set to SPP_PMTUD_ENABLE the value of this 2482 field is ignored. Note also that a value of zero indicates the 2483 current setting should be left unchanged. 2484 spp_pathmtu - When Path MTU discovery is disabled the value 2485 specified here will be the "fixed" path mtu (i.e. the value of the 2486 spp_flags field must include the flag SPP_PMTUD_DISABLE for this 2487 field to have any effect). Note that if the spp_address field is 2488 empty then all associations on this address will have this fixed 2489 path mtu set upon them. If an address is specified, then only 2490 that address will be effected. 2491 spp_sackdelay - When delayed sack is enabled, this value specifies 2492 the number of milliseconds that sacks will be delayed for. This 2493 value will apply to all addresses of an association if the 2494 spp_address field is empty. Note that unless the spp_flag is set 2495 to SPP_SACKDELAY_ENABLE the value of this field is ignored. Note 2496 also that a value of zero indicates the current setting should be 2497 left unchanged. 2498 spp_ipv6_flowlabel- This field is used in conjunction with the 2499 SPP_IPV4_FLOWLABEL flag. 2500 spp_ipv4_tos- This field is used in conjunction with the 2501 SPP_IPV4_TOS flag. 2502 spp_flags- These flags are used to control various features on an 2503 association. The flag field is a bit mask which may contain zero 2504 or more of the following options: 2505 SPP_HB_ENABLE - Enable heartbeats on the specified address. Note 2506 that if the address field is empty all addresses for the 2507 association have heartbeats enabled upon them. 2508 SPP_HB_DISABLE - Disable heartbeats on the specified address. 2509 Note that if the address field is empty all addresses for the 2510 association will have their heartbeats disabled. Note also 2511 that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive, 2512 only one of these two should be specified. Enabling both 2513 fields will have undetermined results. 2514 SPP_HB_DEMAND - Request a user initiated heartbeat to be made 2515 immediately. 2516 SPP_HB_TIME_IS_ZERO - Specify's that the time for heartbeat delay 2517 is to be set to the value of 0 milliseconds. 2518 SPP_PMTUD_ENABLE - This field will enable PMTU discovery upon the 2519 specified address. Note that if the address field is empty 2520 then all addresses on the association are effected. 2521 SPP_PMTUD_DISABLE - This field will disable PMTU discovery upon 2522 the specified address. Note that if the address field is empty 2523 then all addresses on the association are effected. Not also 2524 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2525 exclusive. Enabling both will have undetermined results. 2526 SPP_SACKDELAY_ENABLE - Setting this flag turns on delayed sack. 2527 The time specified in spp_sackdelay is used to specify the sack 2528 delay for this address. Note that if spp_address is empty then 2529 all addresses will enable delayed sack and take on the sack 2530 delay value specified in spp_sackdelay. 2531 SPP_SACKDELAY_DISABLE - Setting this flag turns off delayed sack. 2532 If the spp_address field is blank then delayed sack is disabled 2533 for the entire association. Note also that this field is 2534 mutually exclusive to SPP_SACKDELAY_ENABLE, setting both will 2535 have undefined results. 2536 SPP_IPV6_FLOWLABEL - Setting this flag enables setting of the 2537 IPV6 flowlabel value associated with either the association or 2538 the specific address. If the address field is filled in, then 2539 the specific destination address has this value set upon it. 2540 If the association is specified, but not the address, then the 2541 flowlabel value is set for any future destination addresses 2542 that may be added. The value is obtained in the 2543 spp_ipv6_flowlabel field. 2545 Upon retrieval, this flag will be set to indicate that the 2546 spp_ipv6_flowlabel field has a valid value returned. If a 2547 specific destination addresses is set (in the spp_address 2548 field) when called then the value returned is that of the 2549 address. If just an association is specified (and no address) 2550 then the association default flowlabel is returned. If neither 2551 an association nor an destination is specified, then the 2552 sockets default flowlabel is returned. For non IPv6 sockets, 2553 then this flag will be left cleared. 2554 SPP_IPV4_TOS - Setting this flag enables setting of the IPV4 tos 2555 value associated with either the association or specific 2556 address. If the address field is filled in, then the specific 2557 destination address has this value set upon it. If the 2558 association is specified, but not the address, then the tos 2559 value is set for any future destination addresses that may be 2560 added. The value is obtained in the spp_ipv4_tos field. 2562 Upon retrieval, this flag will be set to indicate that the 2563 spp_ipv4_tos field has a valid value returned. If a specific 2564 destination addresses is set when called (in the spp_address 2565 field) then that specific destination addresses tos value is 2566 returned. If just an association is specified then the 2567 association default tos is returned. If neither an association 2568 nor an destination is specified, then the sockets default tos 2569 is returned. For non IPv4 sockets, then this flag will be left 2570 cleared. 2572 To read or modify these parameters, the application should call 2573 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2575 7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 2577 Applications that wish to use the sendto() system call may wish to 2578 specify a default set of parameters that would normally be supplied 2579 through the inclusion of ancillary data. This socket option allows 2580 such an application to set the default sctp_sndrcvinfo structure. 2581 The application that wishes to use this socket option simply passes 2582 in to this call the sctp_sndrcvinfo structure defined in 2583 Section 5.2.2) The input parameters accepted by this call include 2584 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, 2585 sinfo_timetolive. The sinfo_assoc_id field specifies the default 2586 association used for send operations on one-to-many style sockets. 2587 It is ignored on the one-to-one style. Note that setting the 2588 sinfo_assoc_id field to zero indicates that the users wishes to set 2589 the endpoint default send parameters for all future associations. 2591 7.1.15. Set notification and ancillary events (SCTP_EVENTS) 2593 This socket option is used to specify various notifications and 2594 ancillary data the user wishes to receive. Please see Section 7.3) 2595 for a full description of this option and its usage. 2597 7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2599 This socket option is a boolean flag which turns on or off mapped V4 2600 addresses. If this option is turned on and the socket is type 2601 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2602 If this option is turned off, then no mapping will be done of V4 2603 addresses and a user will receive both PF_INET6 and PF_INET type 2604 addresses on the socket. 2606 By default this option is turned on and expects an integer to be 2607 passed where non-zero turns on the option and zero turns off the 2608 option. 2610 7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG) 2612 This socket option specifies the maximum size to put in any outgoing 2613 SCTP DATA chunk. If a message is larger than this size it will be 2614 fragmented by SCTP into the specified size. Note that the underlying 2615 SCTP implementation may fragment into smaller sized chunks when the 2616 PMTU of the underlying association is smaller than the value set by 2617 the user. The option expects an integer. 2619 The default value for this option is '0' which indicates the user is 2620 NOT limiting fragmentation and only the PMTU will effect SCTP's 2621 choice of DATA chunk size. 2623 7.1.18. Add a chunk that must be authenticated (SCTP_AUTH_CHUNK) 2625 This option adds a chunk type that the user is requesting to be 2626 received only in an authenticated way. Changes to the list of chunks 2627 will only effect future associations on the socket. 2629 struct sctp_authchunk { 2630 uint8_t sauth_chunk; 2631 }; 2633 sauth_chunks - This parameter contains a chunk type 2634 that the user is requesting to be authenticated. 2636 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH 2637 chunks MUST not be used. If they are used an error MUST be returned. 2639 The usage of this option enables SCTP-AUTH in cases where it is not 2640 required by other means (for example the use of ADD-IP). 2642 7.1.19. Get or set the list of supported HMAC Identifiers 2643 (SCTP_HMAC_IDENT) 2645 This option gets or sets the list of HMAC algorithms that the local 2646 endpoint requires the peer to use. 2648 struct sctp_hmacalgo { 2649 uint16_t shmac_idents[]; 2650 }; 2652 shmac_idents - This parameter contains an array of HMAC Identifiers 2653 that the local endpoint is requesting the peer to use, in priority 2654 order. 2656 7.1.20. Set a shared key (SCTP_AUTH_KEY) 2658 This option will set a shared secret key which is used to build an 2659 association shared key. 2661 struct sctp_authkey { 2662 sctp_assoc_t sca_assoc_id; 2663 uint16_t sca_keynumber; 2664 uint8_t sca_key[]; 2665 }; 2667 sca_assoc_id - This parameter, if non-zero, indicates what 2668 association that the shared key is being set upon. Note that if 2669 this element contains zero, then the shared key is set upon the 2670 endpoint and all future associations will use this key (if not 2671 changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one 2672 sockets, this parameter is ignored. Note, however, that this 2673 option will set a key on the association if the socket is 2674 connected, otherwise this will set a key on the endpoint. 2675 sca_keynumber - this parameter is the shared key identifier by which 2676 the application will refer to this key. If a key of the specified 2677 index already exists, then this new key will replace the old 2678 existing key. Note that shared key identifier '0' defaults to a 2679 null key. 2681 sca_key - This parameter contains an array of bytes that is to be 2682 used by the endpoint (or association) as the shared secret key. 2683 Note, if the length of this field is zero, a null key is set. 2685 7.1.21. Get or set the active shared key (SCTP_AUTH_ACTIVE_KEY) 2687 This option will get or set the active shared key to be used to build 2688 the association shared key. 2690 struct sctp_authkeyid { 2691 sctp_assoc_t scact_assoc_id; 2692 uint16_t scact_keynumber; 2693 }; 2695 scact_assoc_id - This parameter, if non-zero, indicates what 2696 association that the shared key identifier is being set active 2697 upon. Note that if this element contains zero, then the 2698 activation applies to the endpoint and all future associations 2699 will use the specified shared key identifier. For one-to-one 2700 sockets, this parameter is ignored. Note, however, that this 2701 option will set the active key on the association if the socket is 2702 connected, otherwise this will set the default active key for the 2703 endpoint. 2704 scact_keynumber - this parameter is the shared key identifier which 2705 the application is requesting to become the active shared key to 2706 be used for sending authenticated chunks. The key identifier MUST 2707 correspond to an existing shared key. Note that shared key 2708 identifier '0' defaults to a null key. 2710 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) 2712 This option will delete a shared secret key from use. 2714 struct sctp_authkeyid { 2715 sctp_assoc_t scact_assoc_id; 2716 uint16_t scact_keynumber; 2717 }; 2719 scact_assoc_id - This parameter, if non-zero, indicates what 2720 association that the shared key identifier is being deleted from. 2721 Note that if this element contains zero, then the shared key is 2722 deleted from the endpoint and all associations will no longer use 2723 the specified shared key identifier (unless otherwise set on the 2724 association using SCTP_AUTH_KEY). For one-to-one sockets, this 2725 parameter is ignored. Note, however, that this option will delete 2726 the key from the association if the socket is connected, otherwise 2727 this will delete the key from the endpoint. 2728 scact_keynumber - this parameter is the shared key identifier which 2729 the application is requesting to be deleted. The key identifier 2730 MUST correspond to an existing shared key and MUST NOT be the 2731 current active key. Note if this parameter is zero, use of the 2732 null key identifier '0' is disabled on the endpoint and/or 2733 association. 2735 7.1.23. Get or set delayed ack timer (SCTP_DELAYED_ACK_TIME) 2737 This options will get or set the delayed ack timer. The time is set 2738 in milliseconds. If the assoc_id is 0, then this sets or gets the 2739 endpoints default delayed ack timer value. If the assoc_id field is 2740 non-zero, then the set or get effects the specified association. 2742 struct sctp_assoc_value { 2743 sctp_assoc_t assoc_id; 2744 uint32_t assoc_value; 2745 }; 2747 assoc_id - This parameter, indicates which association the user is 2748 performing an action upon. Note that if this field's value is 2749 zero then the endpoints default value is changed (effecting future 2750 associations only). 2751 assoc_value - This parameter contains the number of milliseconds 2752 that the user is requesting the delayed ACK timer be set to. Note 2753 that this value is defined in the standard to be between 200 and 2754 500 milliseconds. 2756 7.1.24. Get or set fragmented interleave (SCTP_FRAGMENT_INTERLEAVE) 2758 This options will at a minimum specify if the implementation is doing 2759 fragmented interleave. Fragmented interleave, for a one to many 2760 socket, is when subsequent calls to receive a message may return 2761 parts of messages from different associations. Some implementations 2762 may allow you to turn this value on or off. If so, when turned off, 2763 no fragment interleave will occur (which will cause a head of line 2764 blocking amongst multiple associations sharing the same one to many 2765 socket). When this option is turned on, then each receive call may 2766 come from a different association (thus the user must receive data 2767 with the extended calls (e.g. sctp_recvmsg) to keep track of which 2768 association each receive belongs to. 2770 This option takes a boolean value. A non-zero value indicates that 2771 fragmented interleave is on. A value of zero indicates that 2772 fragmented interleave is off. 2774 Note that it is important that an implementation that allows this 2775 option to be turned on, have it off by default. Otherwise an unaware 2776 application using the one to many model may become confused and act 2777 incorrectly. 2779 7.1.25. Set or Get the sctp partial delivery point 2780 (SCTP_PARTIAL_DELIVERY_POINT) 2782 This option will set or get the SCTP partial delivery point. This 2783 point is the size of a message where the partial delivery API will be 2784 invoked to help free up rwnd space for the peer. Setting this to a 2785 lower value will cause partial delivery's to happen more often. The 2786 calls argument is an integer that sets or gets the partial delivery 2787 point. 2789 7.1.26. Set or Get the use of extended receive info 2790 (SCTP_USE_EXT_RCVINFO) 2792 This option will enable or disable the use of the extended version of 2793 the sctp_sndrcvinfo structure. If this option is disabled, then the 2794 normal sctp_sndrcvinfo structure is returned in all receive message 2795 calls. If this option is enabled then the sctp_extrcvinfo structure 2796 is returned in all receive message calls. 2798 Note that the sctp_extrcvinfo structure is never used in any send 2799 call. 2801 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) 2803 This option will enable or disable the use of the automatic 2804 generation of ASCONF chunks to add and delete addresses to an 2805 existing association. Note that this option has two caveats namely: 2806 a) it only effects sockets that are bound to all addresses on the 2807 machine, and b) the system administrator may have an overriding 2808 control that turns the asconf feature off no matter what setting the 2809 socket option may have. 2811 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) 2813 This option will allow a user to change the maximum burst of packets 2814 that can be emitted by this association. Note that the default value 2815 is 4, and some implementations may restrict this setting so that it 2816 can only be lowered. 2818 7.1.29. Set or Get the default context (SCTP_CONTEXT) 2820 The context field in the sctp_sndrcvinfo structure is normally only 2821 used when a failed message is retrieved holding the value that was 2822 sent down on the actual send call. This option allows the setting of 2823 a default context on an association basis that will be received on 2824 reading messages from the peer. This is especially helpful in the 2825 one-2-many model for an application to keep some reference to an 2826 internal state machine that is processing messages on the 2827 association. Note that the setting of this value only effects 2828 received messages from the peer and does not effect the value that is 2829 saved with outbound messages. 2831 To set or get this option the user fills in the following structure: 2833 struct sctp_assoc_value { 2834 sctp_assoc_t assoc_id; 2835 uint32_t assoc_value; 2836 }; 2838 assoc_id - This parameter, indicates which association the user is 2839 performing an action upon. Note that if this field's value is 2840 zero then the endpoints default value is changed (effecting future 2841 associations only). 2842 assoc_value - This parameter contains the context. 2844 7.1.30. Enable or disable explicit EOR marking (SCTP_EXPLICIT_EOR) 2846 This boolean flag is used to enable or disable explict end of record 2847 (EOR) marking. When this option is enabled, a user may make multiple 2848 send system calls to send a record and must indicate that they are 2849 finished sending a particular record by including on the send the 2850 SCTP_EOR flag. If this boolean flag is disabled then each individual 2851 send system call is considered to have a SCTP_EOR indicator set on it 2852 implicitly without the user having to explicitly add this flag. 2854 7.2. Read-Only Options 2856 7.2.1. Association Status (SCTP_STATUS) 2858 Applications can retrieve current status information about an 2859 association, including association state, peer receiver window size, 2860 number of unacked data chunks, and number of data chunks pending 2861 receipt. This information is read-only. The following structure is 2862 used to access this information: 2864 struct sctp_status { 2865 sctp_assoc_t sstat_assoc_id; 2866 int32_t sstat_state; 2867 uint32_t sstat_rwnd; 2868 uint16_t sstat_unackdata; 2869 uint16_t sstat_penddata; 2870 uint16_t sstat_instrms; 2871 uint16_t sstat_outstrms; 2872 uint32_t sstat_fragmentation_point; 2873 struct sctp_paddrinfo sstat_primary; 2874 }; 2876 sstat_state - This contains the association's current state one of 2877 the following values: 2878 SCTP_CLOSED 2879 SCTP_BOUND 2880 SCTP_LISTEN 2881 SCTP_COOKIE_WAIT 2882 SCTP_COOKIE_ECHOED 2883 SCTP_ESTABLISHED 2884 SCTP_SHUTDOWN_PENDING 2885 SCTP_SHUTDOWN_SENT 2886 SCTP_SHUTDOWN_RECEIVED 2887 SCTP_SHUTDOWN_ACK_SENT 2888 sstat_rwnd - This contains the association peer's current receiver 2889 window size. 2890 sstat_unackdata - This is the number of unacked data chunks. 2891 sstat_penddata - This is the number of data chunks pending receipt. 2892 sstat_primary - This is information on the current primary peer 2893 address. 2894 sstat_assoc_id - (one-to-many style socket) This holds the an 2895 identifier for the association. All notifications for a given 2896 association have the same association identifier. 2897 sstat_instrms - The number of streams that the peer will be using 2898 inbound. 2899 sstat_outstrms - The number of streams that the endpoint is allowed 2900 to use outbound. 2901 sstat_fragmentation_point - The size at which SCTP fragmentation 2902 will occur. 2904 To access these status values, the application calls getsockopt() 2905 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2906 ignored for one-to-one style socket. 2908 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2910 Applications can retrieve information about a specific peer address 2911 of an association, including its reachability state, congestion 2912 window, and retransmission timer values. This information is read- 2913 only. The following structure is used to access this information: 2915 struct sctp_paddrinfo { 2916 sctp_assoc_t spinfo_assoc_id; 2917 struct sockaddr_storage spinfo_address; 2918 int32_t spinfo_state; 2919 uint32_t spinfo_cwnd; 2920 uint32_t spinfo_srtt; 2921 uint32_t spinfo_rto; 2922 uint32_t spinfo_mtu; 2923 }; 2925 spinfo_address - This is filled in the application, and contains the 2926 peer address of interest. 2928 On return from getsockopt(): 2930 spinfo_state - This contains the peer addresses's state (either 2931 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier 2932 SCTP_UNCONFIRMED) 2933 spinfo_cwnd - This contains the peer addresses's current congestion 2934 window. 2935 spinfo_srtt - This contains the peer addresses's current smoothed 2936 round-trip time calculation in milliseconds. 2937 spinfo_rto - This contains the peer addresses's current 2938 retransmission timeout value in milliseconds. 2939 spinfo_mtu - The current P-MTU of this address. 2940 spinfo_assoc_id - This is field may be filled in by the application, 2941 if so, this field will have priority in looking up the association 2942 over the address specified in spinfo_address. Note that if the 2943 address does not belong to the association specified then this 2944 call will fail. If the application does NOT fill in the 2945 spinfo_assoc_id, then the address will be used to lookup the 2946 association and on return this field will have the valid 2947 association id. In other words, this call can be used to 2948 translate a address into an association id. 2950 To retrieve this information, use sctp_opt_info() with the 2951 SCTP_GET_PEER_ADDR_INFO options. 2953 7.2.3. Get the list of chunks the peer requires to be authenticated 2954 (SCTP_PEER_AUTH_CHUNKS) 2956 This option gets a list of chunks for a specified association that 2957 the peer requires to be received authenticated only. 2959 struct sctp_authchunks { 2960 sctp_assoc_t gauth_assoc_id; 2961 uint8_t gauth_chunks[]; 2962 }; 2964 gauth_assoc_id - This parameter, indicates which association the 2965 user is requesting the list of peer authenticated chunks. For 2966 one-to-one sockets, this parameter is ignored. 2967 gauth_chunks - This parameter contains an array of chunks that the 2968 peer is requesting to be authenticated. 2970 7.2.4. Get the list of chunks the local endpoint requires to be 2971 authenticated (SCTP_LOCAL_AUTH_CHUNKS) 2973 This option gets a list of chunks for a specified association that 2974 the local endpoint requires to be received authenticated only. 2976 struct sctp_authchunks { 2977 sctp_assoc_t gauth_assoc_id; 2978 uint8_t gauth_chunks[]; 2979 }; 2981 gauth_assoc_id - This parameter, indicates which association the 2982 user is requesting the list of local authenticated chunks. For 2983 one-to-one sockets, this parameter is ignored. 2984 gauth_chunks - This parameter contains an array of chunks that the 2985 local endpoint is requesting to be authenticated. 2987 7.2.5. Get the list of current associations (SCTP_GET_ASOC_ID_LIST) 2989 This option gets a list of current associations that are associated 2990 with a socket. 2992 struct sctp_assoc_ids { 2993 uint16_t asls_assoc_start; /* array of index's start at 0 */ 2994 uint8_t asls_numb_present; 2995 uint8_t asls_more_to_get; 2996 sctp_assoc_t asls_assoc_id[MAX_ASOC_IDS_RET]; 2997 }; 2999 asls_assoc_start - This parameter gives an initial starting place to 3000 begin collecting association information. Normally a user sets 3001 this initially to 0. Subsequent calls that need to get more 3002 association identifications (in cases where the socket has more 3003 than MAX_ASOC_IDS_RET established i.e asls_more_to_get returns set 3004 to false) are made by incrementing the asls_assoc_start by the 3005 number of previous association id's seen. This cycle is repeated 3006 until the asls_more_to_get field becomes true, indicating that all 3007 association id's have been retrieved. 3008 asls_numb_present - This field holds the total number of 3009 associations that have been copied into the asls_assoc_id array. 3010 This value will NOT be larger than MAX_ASOC_IDS_RET. 3011 asls_more_to_get - This field holds a boolean flag indicating to the 3012 caller if more association id's are available then asked for. 3013 Subsequent calls to this option will be needed to gather these 3014 association id's. 3015 asls_assoc_id - an array of association id's that are currently 3016 active under this socket. 3017 MAX_ASOC_IDS_RET This value is a constant defined to limit the 3018 number of association identifications returned with each call. 3019 This value can be no larger than 255.. 3021 7.3. Ancillary Data and Notification Interest Options 3023 Applications can receive per-message ancillary information and 3024 notifications of certain SCTP events with recvmsg(). 3026 The following optional information is available to the application: 3028 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 3029 stream number, TSN, SSN, etc. described in Section 5.2.2) 3030 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in 3031 Section 5.3.1.1) 3032 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in 3033 Section 5.3.1.2) 3034 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in 3035 Section 5.3.1.4) 3036 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in 3037 Section 5.3.1.3) 3038 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in 3039 Section 5.3.1.5) 3040 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 3041 (described in Section 5.3.1.7) 3043 8. SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event): 3044 (described in Section 5.3.1.6) 3045 9. SCTP_AUTHENTICATION_INDICATION (sctp_authentication_event): 3046 (described in Section 5.3.1.8) 3048 To receive any ancillary data or notifications, first the application 3049 registers it's interest by calling the SCTP_EVENTS setsockopt() with 3050 the following structure. 3052 struct sctp_event_subscribe{ 3053 uint8_t sctp_data_io_event; 3054 uint8_t sctp_association_event; 3055 uint8_t sctp_address_event; 3056 uint8_t sctp_send_failure_event; 3057 uint8_t sctp_peer_error_event; 3058 uint8_t sctp_shutdown_event; 3059 uint8_t sctp_partial_delivery_event; 3060 uint8_t sctp_adaptation_layer_event; 3061 uint8_t sctp_authentication_event; 3062 }; 3064 sctp_data_io_event - Setting this flag to 1 will cause the reception 3065 of SCTP_SNDRCV information on a per message basis. The application 3066 will need to use the recvmsg() interface so that it can receive the 3067 event information contained in the msg_control field. Please see 3068 Section 5.2 for further details. Setting the flag to 0 will disable 3069 reception of the message control information. 3071 sctp_association_event - Setting this flag to 1 will enable the 3072 reception of association event notifications. Setting the flag to 0 3073 will disable association event notifications. For more information 3074 on event notifications please see Section 5.3. 3076 sctp_address_event - Setting this flag to 1 will enable the reception 3077 of address event notifications. Setting the flag to 0 will disable 3078 address event notifications. For more information on event 3079 notifications please see Section 5.3. 3081 sctp_send_failure_event - Setting this flag to 1 will enable the 3082 reception of send failure event notifications. Setting the flag to 0 3083 will disable send failure event notifications. For more information 3084 on event notifications please see Section 5.3. 3086 sctp_peer_error_event - Setting this flag to 1 will enable the 3087 reception of peer error event notifications. Setting the flag to 0 3088 will disable peer error event notifications. For more information on 3089 event notifications please see Section 5.3. 3091 sctp_shutdown_event - Setting this flag to 1 will enable the 3092 reception of shutdown event notifications. Setting the flag to 0 3093 will disable shutdown event notifications. For more information on 3094 event notifications please see Section 5.3. 3096 sctp_partial_delivery_event - Setting this flag to 1 will enable the 3097 reception of partial delivery notifications. Setting the flag to 0 3098 will disable partial delivery event notifications. For more 3099 information on event notifications please see Section 5.3. 3101 sctp_adaptation_layer_event - Setting this flag to 1 will enable the 3102 reception of adaptation layer notifications. Setting the flag to 0 3103 will disable adaptation layer event notifications. For more 3104 information on event notifications please see Section 5.3. 3106 sctp_authentication_event - Setting this flag to 1 will enable the 3107 reception of authentication layer notifications. Setting the flag to 3108 0 will disable authentication layer event notifications. For More 3109 information please see Section 5.3. 3111 An example where an application would like to receive data io events 3112 and association events but no others would be as follows: 3114 { 3115 struct sctp_event_subscribe event; 3117 memset(&event,0,sizeof(event)); 3119 event.sctp_data_io_event = 1; 3120 event.sctp_association_event = 1; 3122 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event)); 3123 } 3125 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 3126 receives ancillary data and notifications for ALL associations bound 3127 to the file descriptor. For one-to-one style SCTP sockets, the 3128 caller receives ancillary data and notifications for only the single 3129 association bound to the file descriptor. 3131 By default both the one-to-one style and one-to-many style socket has 3132 all options off. 3134 8. New Interfaces 3136 Depending on the system, the following interface can be implemented 3137 as a system call or library function. 3139 8.1. sctp_bindx() 3141 The syntax of sctp_bindx() is, 3143 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt, 3144 int flags); 3146 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 3147 If the sd is an IPv6 socket, the addresses passed can either be IPv4 3148 or IPv6 addresses. 3150 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 3151 Section 3.1.2 for this usage. 3153 addrs is a pointer to an array of one or more socket addresses. Each 3154 address is contained in its appropriate structure. For an IPv6 3155 socket, an array of sockaddr_in6 would be returned. For a IPv4 3156 socket, an array of sockaddr_in would be returned. The caller 3157 specifies the number of addresses in the array with addrcnt. Note 3158 that the wildcard addresses cannot be used with this function, doing 3159 so will result in an error. 3161 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 3162 -1, and sets errno to the appropriate error code. 3164 For SCTP, the port given in each socket address must be the same, or 3165 sctp_bindx() will fail, setting errno to EINVAL. 3167 The flags parameter is formed from the bitwise OR of zero or more of 3168 the following currently defined flags: 3170 SCTP_BINDX_ADD_ADDR 3172 SCTP_BINDX_REM_ADDR 3174 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 3175 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 3176 addresses from the association. The two flags are mutually 3177 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 3178 caller may not remove all addresses from an association; sctp_bindx() 3179 will reject such an attempt with EINVAL. 3181 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 3182 additional addresses with an endpoint after calling bind(). Or use 3183 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 3184 socket is associated with so that no new association accepted will be 3185 associated with those addresses. If the endpoint supports dynamic 3186 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 3187 endpoint to send the appropriate message to the peer to change the 3188 peers address lists. 3190 Adding and removing addresses from a connected association is 3191 optional functionality. Implementations that do not support this 3192 functionality should return EOPNOTSUPP. 3194 8.2. Branched-off Association 3196 After an association is established on a one-to-many style socket, 3197 the application may wish to branch off the association into a 3198 separate socket/file descriptor. 3200 This is particularly desirable when, for instance, the application 3201 wishes to have a number of sporadic message senders/receivers remain 3202 under the original one-to-many style socket but branch off those 3203 associations carrying high volume data traffic into their own 3204 separate socket descriptors. 3206 The application uses sctp_peeloff() call to branch off an association 3207 into a separate socket (Note the semantics are somewhat changed from 3208 the traditional one-to-one style accept() call). Note that the new 3209 socket is a one-to-one style socket. Thus it will be confined to 3210 operations allowed for a one-to-one style socket. 3212 The syntax is: 3214 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id); 3216 new_sd: the new socket descriptor representing the branched-off 3217 association. 3218 sd: the original one-to-many style socket descriptor returned from 3219 the socket() system call (see Section 3.1.1). 3220 assoc_id: the specified identifier of the association that is to be 3221 branched off to a separate file descriptor (Note, in a traditional 3222 one-to-one style accept() call, this would be an out parameter, 3223 but for the one-to-many style call, this is an in parameter). 3225 8.3. sctp_getpaddrs() 3227 sctp_getpaddrs() returns all peer addresses in an association. The 3228 syntax is, 3230 int sctp_getpaddrs(int sd, sctp_assoc_t id, 3231 struct sockaddr **addrs); 3233 On return, addrs will point to an array dynamically allocated 3234 sockaddr structures of the appropriate type for the socket type. The 3235 caller should use sctp_freepaddrs() to free the memory. Note that 3236 the in/out parameter addrs must not be NULL. 3238 If sd is an IPv4 socket, the addresses returned will be all IPv4 3239 addresses. If sd is an IPv6 socket, the addresses returned can be a 3240 mix of IPv4 or IPv6 addresses. 3242 For one-to-many style sockets, id specifies the association to query. 3243 For one-to-one style sockets, id is ignored. 3245 On success, sctp_getpaddrs() returns the number of peer addresses in 3246 the association. If there is no association on this socket, 3247 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 3248 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 3249 is undefined. 3251 8.4. sctp_freepaddrs() 3253 sctp_freepaddrs() frees all resources allocated by 3254 sctp_getpaddrs(). Its syntax is, 3256 void sctp_freepaddrs(struct sockaddr *addrs); 3257 addrs is the array of peer addresses returned by sctp_getpaddrs(). 3259 8.5. sctp_getladdrs() 3261 sctp_getladdrs() returns all locally bound address(es) on a socket. 3262 The syntax is, 3264 int sctp_getladdrs(int sd, sctp_assoc_t id, 3265 struct sockaddr **ss); 3267 On return, addrs will point to a dynamically allocated array of 3268 sockaddr structures of the appropriate type for the socket type. The 3269 caller should use sctp_freeladdrs() to free the memory. Note that 3270 the in/out parameter addrs must not be NULL. 3272 If sd is an IPv4 socket, the addresses returned will be all IPv4 3273 addresses. If sd is an IPv6 socket, the addresses returned can be a 3274 mix of IPv4 or IPv6 addresses. 3276 For one-to-many style sockets, id specifies the association to query. 3277 For one-to-one style sockets, id is ignored. 3279 If the id field is set to the value '0' then the locally bound 3280 addresses are returned without regard to any particular association. 3282 On success, sctp_getladdrs() returns the number of local addresses 3283 bound to the socket. If the socket is unbound, sctp_getladdrs() 3284 returns 0, and the value of *addrs is undefined. If an error occurs, 3285 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 3287 8.6. sctp_freeladdrs() 3289 sctp_freeladdrs() frees all resources allocated by 3290 sctp_getladdrs(). Its syntax is, 3292 void sctp_freeladdrs(struct sockaddr *addrs); 3294 addrs is the array of peer addresses returned by sctp_getladdrs(). 3296 8.7. sctp_sendmsg() 3298 An implementation may provide a library function (or possibly system 3299 call) to assist the user with the advanced features of SCTP. 3301 sctp_sendmsg(). Its syntax is, 3303 ssize_t sctp_sendmsg(int sd, 3304 const void *msg, 3305 size_t len, 3306 const struct sockaddr *to, 3307 socklen_t tolen, 3308 uint32_t ppid, 3309 uint32_t flags, 3310 uint16_t stream_no, 3311 uint32_t timetolive, 3312 uint32_t context) 3314 sd - is the socket descriptor 3315 msg - is the message to be sent. 3316 len - is the length of the message. 3317 to - is the destination address of the message. 3318 tolen - is the length of the destination address. 3319 ppid - is the same as sinfo_ppid (see section 5.2.2) 3320 flags - is the same as sinfo_flags (see section 5.2.2) 3321 stream_no - is the same as sinfo_stream (see section 5.2.2) 3322 timetolive - is the same as sinfo_timetolive (see section 5.2.2) 3323 context - is the same as sinfo_context (see section 5.2.2) 3324 The call returns the number of characters sent, or -1 if an error 3325 occurred. The variable errno is then set appropriately. 3327 8.8. sctp_recvmsg() 3329 An implementation may provide a library function (or possibly system 3330 call) to assist the user with the advanced features of SCTP. Note 3331 that in order for the sctp_sndrcvinfo structure to be filled in by 3332 sctp_recvmsg() the caller must enable the sctp_data_io_events with 3333 the SCTP_EVENTS option. Note that the setting of the 3334 SCTP_USE_EXT_RCVINFO will effect this function as well, causing the 3335 sctp_sndrcvinfo information to be extended. 3337 sctp_recvmsg(). Its syntax is, 3339 ssize_t sctp_recvmsg(int sd, 3340 void *msg, 3341 size_t len, 3342 struct sockaddr *from, 3343 socklen_t *fromlen 3344 struct sctp_sndrcvinfo *sinfo 3345 int *msg_flags) 3347 sd - is the socket descriptor 3348 msg - is a message buffer to be filled. 3349 len - is the length of the message buffer. 3350 from - is a pointer to a address to be filled with the sender of 3351 this messages address. 3352 fromlen - is the from length. 3353 sinfo - A pointer to a sctp_sndrcvinfo structure to be filled upon 3354 receipt of the message. 3355 msg_flags - A pointer to a integer to be filled with any message 3356 flags (e.g. MSG_NOTIFICATION). 3357 The call returns the number of bytes received, or -1 if an error 3358 occurred. The variable errno is then set appropriately. 3360 8.9. sctp_connectx() 3362 An implementation may provide a library function (or possibly system 3363 call) to assist the user with associating to an endpoint that is 3364 multi-homed. Much like sctp_bindx() this call allows a caller to 3365 specify multiple addresses at which a peer can be reached. The way 3366 the SCTP stack uses the list of addresses to set up the association 3367 is implementation dependent. This function only specifies that the 3368 stack will try to make use of all the addresses in the list when 3369 needed. 3371 Note that the list of addresses passed in is only used for setting up 3372 the association. It does not necessarily equal the set of addresses 3373 the peer uses for the resulting association. If the caller wants to 3374 find out the set of peer addresses, it must use sctp_getpaddrs() to 3375 retrieve them after the association has been set up. 3377 sctp_connectx(). Its syntax is, 3379 int sctp_connectx(int sd, 3380 struct sockaddr *addrs, 3381 int addrcnt, 3382 sctp_assoc_t *id) 3384 sd - is the socket descriptor 3385 addrs - is an array of addresses. 3386 addrcnt - is the number of addresses in the array. 3387 id - is an output parameter that if passed in as a non-NULL will 3388 return the association identification for the newly created 3389 association (if successful). 3391 The call returns 0 on success or -1 if an error occured. The 3392 variable errno is then set appropriately. 3394 8.10. sctp_send() 3396 An implementation may provide another alternative function or system 3397 call to assist an application with the sending of data without the 3398 use of the CMSG header structures. The function takes the following 3399 form: 3401 sctp_send(). Its syntax is, 3403 int sctp_send(int sd, 3404 const void *msg, 3405 size_t len, 3406 const struct sctp_sndrcvinfo *sinfo, 3407 int flags); 3409 sd - is the socket descriptor 3410 msg - The message to be sent 3411 len - The length of the message 3412 sinfo - A pointer to a sctp_sndrcvinfo structure used as described 3413 in 5.2.2 for a sendmsg call. 3414 flags - is used in the same format as the sendmsg call flags (e.g. 3415 MSG_DONTROUTE). 3417 This function call may also be used to terminate an association using 3418 an association identification by setting the sinfo.sinfo_flags to 3419 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3420 to be terminated. In such a case the len of the message would be 3421 zero. 3423 The call returns the number of characters sent, or -1 if an error 3424 occurred. The variable errno is then set appropriately. 3426 8.11. sctp_sendx() 3428 An implementation may provide another alternative function or system 3429 call to assist an application with the sending of data without the 3430 use of the CMSG header structures that also gives a list of 3431 addresses. The list of addresses is provided for implicit 3432 association setup. In such a case the list of addresses serves the 3433 same purpose as the addresses given in sctp_connectx (see 3434 Section 8.9). 3436 sctp_sendx(). Its syntax is, 3438 int sctp_sendx(int sd, 3439 const void *msg, 3440 size_t len, 3441 struct sockaddr *addrs, 3442 int addrcnt, 3443 struct sctp_sndrcvinfo *sinfo, 3444 int flags); 3446 sd - is the socket descriptor 3447 msg - The message to be sent 3448 len - The length of the message 3449 addrs - is an array of addresses. 3450 addrcnt - is the number of addresses in the array. 3451 sinfo - A pointer to a sctp_sndrcvinfo structure used as described 3452 in 5.2.2 for a sendmsg call. 3454 flags - is used in the same format as the sendmsg call flags (e.g. 3455 MSG_DONTROUTE). 3457 Note that on return from this call the sinfo structure will have 3458 changed in that the sinfo_assoc_id will be filled in with the new 3459 association id. 3461 This function call may also be used to terminate an association using 3462 an association identification by setting the sinfo.sinfo_flags to 3463 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs 3464 to be terminated. In such a case the len of the message would be 3465 zero. 3467 The call returns the number of characters sent, or -1 if an error 3468 occurred. The variable errno is then set appropriately. 3470 8.12. sctp_getaddrlen 3472 For application binary portability it is sometimes desirable to know 3473 what the kernel thinks is the length of a socket address family. 3474 This function, when called with a valid family type will return the 3475 length that the operating system uses in the specified family's 3476 socket address structure. 3478 int sctp_getaddrlen(sa_family_t family); 3480 9. Preprocessor Constants 3482 For application portability it is desirable to define pre-processor 3483 constants for determination if sctp is present and supports various 3484 features. The following pre-processor constants should be defined in 3485 a include file, sctp.h. 3487 HAVE_SCTP - If this constant is defined to 1, then an implementation 3488 of SCTP is available. 3489 HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel 3490 SCTP implementation is available through the sockets interface. 3491 HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP 3492 implementation supports the partial reliability extension to SCTP. 3493 HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP 3494 implementation supports the dynamic address extension to SCTP. 3495 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then 3496 the SCTP implementation supports the ability to request setting of 3497 the remote primary address. 3499 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1, 3500 then the SCTP implementation supports the satellite network 3501 extension to SCTP. 3502 HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP 3503 implementation dedicates separate buffer space to each association 3504 on a one-to-many socket. If this constant is defined to 0, then 3505 the implementation provides a single block of shared buffer space 3506 for a one-to-many socket. 3507 HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the 3508 SCTP implementation supports initiating an association on a one- 3509 to-one style socket without the use of connect(), as outlined in 3510 Section 4.1.5. 3511 HAVE_SCTP_EXT_RCVINFO - If this constant is defined to 1, then the 3512 SCTP implementation supports the use of the extended style 3513 sndrecinfo structure, sctp_extrcvinfo. 3515 10. IANA considerations 3517 This document contains no IANA considerations. 3519 11. Security Considerations 3521 Many TCP and UDP implementations reserve port numbers below 1024 for 3522 privileged users. If the target platform supports privileged users, 3523 the SCTP implementation SHOULD restrict the ability to call bind() or 3524 sctp_bindx() on these port numbers to privileged users. 3526 Similarly unprivileged users should not be able to set protocol 3527 parameters which could result in the congestion control algorithm 3528 being more aggressive than permitted on the public Internet. These 3529 parameters are: 3531 struct sctp_rtoinfo 3533 If an unprivileged user inherits a one-to-many style socket with open 3534 associations on a privileged port, it MAY be permitted to accept new 3535 associations, but it SHOULD NOT be permitted to open new 3536 associations. This could be relevant for the r* family of protocols. 3538 12. Acknowledgments 3540 Special acknowledgment is given to Ken Fujita and Jonathan Woods who 3541 helped extensively in the early formation of this document. 3543 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 3544 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, and 3545 many others on the TSVWG mailing list for contributing valuable 3546 comments. 3548 A special thanks to Phillip Conrad, for his suggested text, quick and 3549 constructive insights, and most of all his persistent fighting to 3550 keep the interface to SCTP usable for the application programmer. 3552 13. Normative references 3554 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3555 RFC 793, September 1981. 3557 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 3558 August 1980. 3560 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 3561 Functional Specification", RFC 1644, July 1994. 3563 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3564 3", BCP 9, RFC 2026, October 1996. 3566 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3567 Requirement Levels", BCP 14, RFC 2119, March 1997. 3569 [RFC2292] Stevens, W. and M. Thomas, "Advanced Sockets API for 3570 IPv6", RFC 2292, February 1998. 3572 [RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens, 3573 "Basic Socket Interface Extensions for IPv6", RFC 2553, 3574 March 1999. 3576 [RFC2960] Stewart, R., Xie, Q., Morneault, K., Sharp, C., 3577 Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., 3578 Zhang, L., and V. Paxson, "Stream Control Transmission 3579 Protocol", RFC 2960, October 2000. 3581 Appendix A. one-to-one style Code Example 3583 The following code is a simple implementation of an echo server over 3584 SCTP. The example shows how to use some features of one-to-one style 3585 IPv4 SCTP sockets, including: 3587 o Opening, binding, and listening for new associations on a socket; 3588 o Enabling ancillary data 3589 o Enabling notifications 3590 o Using ancillary data with sendmsg() and recvmsg() 3591 o Using MSG_EOR to determine if an entire message has been read 3592 o Handling notifications 3594 #include 3595 #include 3596 #include 3597 #include 3598 #include 3599 #include 3600 #include 3601 #include 3602 #include 3604 #define BUFLEN 100 3606 static void 3607 handle_event(void *buf) 3608 { 3609 struct sctp_assoc_change *sac; 3610 struct sctp_send_failed *ssf; 3611 struct sctp_paddr_change *spc; 3612 struct sctp_remote_error *sre; 3613 union sctp_notification *snp; 3614 char addrbuf[INET6_ADDRSTRLEN]; 3615 const char *ap; 3616 struct sockaddr_in *sin; 3617 struct sockaddr_in6 *sin6; 3619 snp = buf; 3621 switch (snp->sn_header.sn_type) { 3622 case SCTP_ASSOC_CHANGE: 3623 sac = &snp->sn_assoc_change; 3624 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3625 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3626 sac->sac_inbound_streams, sac->sac_outbound_streams); 3627 break; 3628 case SCTP_SEND_FAILED: 3629 ssf = &snp->sn_send_failed; 3630 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3631 ssf->ssf_error); 3632 break; 3634 case SCTP_PEER_ADDR_CHANGE: 3636 spc = &snp->sn_paddr_change; 3637 if (spc->spc_aaddr.ss_family == AF_INET) { 3638 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3639 ap = inet_ntop(AF_INET, &sin->sin_addr, 3640 addrbuf, INET6_ADDRSTRLEN); 3641 } else { 3642 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3643 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3644 addrbuf, INET6_ADDRSTRLEN); 3645 } 3646 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3647 spc->spc_state, spc->spc_error); 3648 break; 3649 case SCTP_REMOTE_ERROR: 3650 sre = &snp->sn_remote_error; 3651 printf("^^^ remote_error: err=%hu len=%hu\n", 3652 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3653 break; 3654 case SCTP_SHUTDOWN_EVENT: 3655 printf("^^^ shutdown event\n"); 3656 break; 3657 default: 3658 printf("unknown type: %hu\n", snp->sn_header.sn_type); 3659 break; 3660 }; 3661 } 3663 static void * 3664 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 3665 ssize_t *nrp, size_t cmsglen) 3666 { 3667 ssize_t nr = 0, nnr = 0; 3668 struct iovec iov[1]; 3670 *nrp = 0; 3671 iov->iov_base = buf; 3672 iov->iov_len = *buflen; 3673 msg->msg_iov = iov; 3674 msg->msg_iovlen = 1; 3676 for (;;) { 3677 #ifndef MSG_XPG4_2 3678 #define MSG_XPG4_2 0 3679 #endif 3680 msg->msg_flags = MSG_XPG4_2; 3681 msg->msg_controllen = cmsglen; 3682 nnr = recvmsg(fd, msg, 0); 3683 if (nnr <= 0) { 3684 /* EOF or error */ 3685 *nrp = nr; 3686 return (NULL); 3687 } 3688 nr += nnr; 3690 if ((msg->msg_flags & MSG_EOR) != 0) { 3691 *nrp = nr; 3692 return (buf); 3693 } 3695 /* Realloc the buffer? */ 3696 if (*buflen == (size_t)nr) { 3697 buf = realloc(buf, *buflen * 2); 3698 if (buf == 0) { 3699 fprintf(stderr, "out of memory\n"); 3700 exit(1); 3701 } 3702 *buflen *= 2; 3703 } 3704 /* Set the next read offset */ 3705 iov->iov_base = (char *)buf + nr; 3706 iov->iov_len = *buflen - nr; 3707 } 3708 } 3710 static void 3711 echo(int fd, int socketModeone_to_many) 3712 { 3713 ssize_t nr; 3714 struct sctp_sndrcvinfo *sri; 3715 struct msghdr msg[1]; 3716 struct cmsghdr *cmsg; 3717 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3718 char *buf; 3719 size_t buflen; 3720 struct iovec iov[1]; 3721 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3722 /* Allocate the initial data buffer */ 3723 buflen = BUFLEN; 3724 if (!(buf = malloc(BUFLEN))) { 3725 fprintf(stderr, "out of memory\n"); 3726 exit(1); 3727 } 3729 /* Set up the msghdr structure for receiving */ 3730 memset(msg, 0, sizeof (*msg)); 3731 msg->msg_control = cbuf; 3732 msg->msg_controllen = cmsglen; 3733 msg->msg_flags = 0; 3734 cmsg = (struct cmsghdr *)cbuf; 3735 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3737 /* Wait for something to echo */ 3738 while (buf = mysctp_recvmsg(fd, msg, 3739 buf, &buflen, &nr, cmsglen)) { 3741 /* Intercept notifications here */ 3742 if (msg->msg_flags & MSG_NOTIFICATION) { 3743 handle_event(buf); 3744 continue; 3745 } 3747 iov->iov_base = buf; 3748 iov->iov_len = nr; 3749 msg->msg_iov = iov; 3750 msg->msg_iovlen = 1; 3752 printf("got %u bytes on stream %hu:\n", nr, 3753 sri->sinfo_stream); 3754 write(0, buf, nr); 3756 /* Echo it back */ 3757 msg->msg_flags = MSG_XPG4_2; 3758 if (sendmsg(fd, msg, 0) < 0) { 3759 perror("sendmsg"); 3760 exit(1); 3761 } 3762 } 3764 if (nr < 0) { 3765 perror("recvmsg"); 3766 } 3767 if(socketModeone_to_many == 0) 3768 close(fd); 3769 } 3771 int main() 3772 { 3773 struct sctp_event_subscribe event; 3774 int lfd, cfd; 3775 int onoff = 1; 3776 struct sockaddr_in sin[1]; 3777 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3778 perror("socket"); 3779 exit(1); 3780 } 3782 sin->sin_family = AF_INET; 3783 sin->sin_port = htons(7); 3784 sin->sin_addr.s_addr = INADDR_ANY; 3785 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3786 perror("bind"); 3787 exit(1); 3788 } 3790 if (listen(lfd, 1) == -1) { 3791 perror("listen"); 3792 exit(1); 3793 } 3795 /* Wait for new associations */ 3796 for (;;) { 3797 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3798 perror("accept"); 3799 exit(1); 3800 } 3802 /* Enable all events */ 3803 event.sctp_data_io_event = 1; 3804 event.sctp_association_event = 1; 3805 event.sctp_address_event = 1; 3806 event.sctp_send_failure_event = 1; 3807 event.sctp_peer_error_event = 1; 3808 event.sctp_shutdown_event = 1; 3809 event.sctp_partial_delivery_event = 1; 3810 event.sctp_adaptation_layer_event = 1; 3811 if (setsockopt(cfd, IPPROTO_SCTP, 3812 SCTP_EVENTS, &event, 3813 sizeof(event)) != 0) { 3814 perror("setevent failed"); 3815 exit(1); 3816 } 3817 /* Echo back any and all data */ 3818 echo(cfd,0); 3819 } 3820 } 3822 Appendix B. one-to-many style Code Example 3824 The following code is a simple implementation of an echo server over 3825 SCTP. The example shows how to use some features of one-to-many 3826 style IPv4 SCTP sockets, including: 3828 o Opening and binding of a socket; 3829 o Enabling ancillary data 3830 o Enabling notifications 3831 o Using ancillary data with sendmsg() and recvmsg() 3832 o Using MSG_EOR to determine if an entire message has been read 3833 o Handling notifications 3835 Note most functions defined in Appendix A are reused in this example. 3837 int main() 3838 { 3839 int fd; 3840 int idleTime = 2; 3841 struct sockaddr_in sin[1]; 3842 struct sctp_event_subscribe event; 3844 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3845 perror("socket"); 3846 exit(1); 3847 } 3849 sin->sin_family = AF_INET; 3850 sin->sin_port = htons(7); 3851 sin->sin_addr.s_addr = INADDR_ANY; 3852 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3853 perror("bind"); 3854 exit(1); 3855 } 3857 /* Enable all notifications and events */ 3858 event.sctp_data_io_event = 1; 3859 event.sctp_association_event = 1; 3860 event.sctp_address_event = 1; 3861 event.sctp_send_failure_event = 1; 3862 event.sctp_peer_error_event = 1; 3863 event.sctp_shutdown_event = 1; 3864 event.sctp_partial_delivery_event = 1; 3865 event.sctp_adaptation_layer_event = 1; 3866 if (setsockopt(fd, IPPROTO_SCTP, 3867 SCTP_EVENTS, &event, 3868 sizeof(event)) != 0) { 3869 perror("setevent failed"); 3870 exit(1); 3871 } 3872 /* Set associations to auto-close in 2 seconds of 3873 * inactivity 3874 */ 3875 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3876 &idleTime, 4) < 0) { 3877 perror("setsockopt SCTP_AUTOCLOSE"); 3878 exit(1); 3879 } 3881 /* Allow new associations to be accepted */ 3882 if (listen(fd, 1) < 0) { 3883 perror("listen"); 3884 exit(1); 3885 } 3887 /* Wait for new associations */ 3888 while(1){ 3889 /* Echo back any and all data */ 3890 echo(fd,1); 3891 } 3892 } 3894 Authors' Addresses 3896 Randall R. Stewart 3897 Cisco Systems, Inc. 3898 4875 Forest Drive 3899 Suite 200 3900 Columbia, SC 29206 3901 USA 3903 Phone: 3904 Email: rrs@cisco.com 3906 Qiaobing Xie 3907 Motorola, Inc. 3908 1501 W. Shure Drive, #2309 3909 Arlington Heights, IL 60004 3910 USA 3912 Phone: 3913 Email: qxie1@email.mot.com 3914 La Monte H.P. Yarroll 3915 TimeSys Corp 3916 925 Liberty Ave. 3917 Pittsburgh, PA 15222 3918 USA 3920 Phone: 3921 Email: piggy@acm.org 3923 Kacheong Poon 3924 Sun Microsystems, Inc. 3925 4150 Network Circle 3926 Santa Clara, CA 95054 3927 USA 3929 Phone: 3930 Email: kacheong.poon@sun.com 3932 Michael Tuexen 3933 Univ. of Applied Sciences Muenster 3934 Stegerwaldstr. 39 3935 48565 Steinfurt 3936 Germany 3938 Email: tuexen@fh-muenster.de 3940 Full Copyright Statement 3942 Copyright (C) The IETF Trust (2006). 3944 This document is subject to the rights, licenses and restrictions 3945 contained in BCP 78, and except as set forth therein, the authors 3946 retain all their rights. 3948 This document and the information contained herein are provided on an 3949 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3950 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 3951 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 3952 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 3953 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3954 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3956 Intellectual Property 3958 The IETF takes no position regarding the validity or scope of any 3959 Intellectual Property Rights or other rights that might be claimed to 3960 pertain to the implementation or use of the technology described in 3961 this document or the extent to which any license under such rights 3962 might or might not be available; nor does it represent that it has 3963 made any independent effort to identify any such rights. Information 3964 on the procedures with respect to rights in RFC documents can be 3965 found in BCP 78 and BCP 79. 3967 Copies of IPR disclosures made to the IETF Secretariat and any 3968 assurances of licenses to be made available, or the result of an 3969 attempt made to obtain a general license or permission for the use of 3970 such proprietary rights by implementers or users of this 3971 specification can be obtained from the IETF on-line IPR repository at 3972 http://www.ietf.org/ipr. 3974 The IETF invites any interested party to bring to its attention any 3975 copyrights, patents or patent applications, or other proprietary 3976 rights that may cover technology that may be required to implement 3977 this standard. Please address the information to the IETF at 3978 ietf-ipr@ietf.org. 3980 Acknowledgment 3982 Funding for the RFC Editor function is provided by the IETF 3983 Administrative Support Activity (IASA).