idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-10.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.a on line 26. -- Found old boilerplate from RFC 3978, Section 5.5 on line 3427. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3404. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3411. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3417. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == It seems as if not all pages are separated by form feeds - found 0 form feeds but 83 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 43 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([8]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 873 has weird spacing: '...n. The value...' == Line 885 has weird spacing: '...er send and ...' == Line 1048 has weird spacing: '...g_level cms...' == Line 1102 has weird spacing: '...g_level cms...' == Line 1261 has weird spacing: '..._change sn_a...' == (8 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). -- 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 (February 21, 2005) is 6997 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) == Missing Reference: '0' is mentioned on line 1525, but not defined == Unused Reference: '4' is defined on line 3007, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 3010, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (ref. '1') (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (ref. '3') (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 2292 (ref. '6') (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2553 (ref. '7') (Obsoleted by RFC 3493) ** Obsolete normative reference: RFC 2960 (ref. '8') (Obsoleted by RFC 4960) Summary: 14 errors (**), 0 flaws (~~), 13 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group R. Stewart 2 Internet-Draft Cisco Systems, Inc. 3 Expires: August 25, 2005 Q. Xie 4 Motorola, Inc. 5 L. Yarroll 6 TimeSys Corp 7 J. Wood 8 DoCoMo USA Labs 9 K. Poon 10 Sun Microsystems, Inc. 11 M. Tuexen 12 Univ. of Applied Sciences Muenster 13 February 21, 2005 15 Sockets API Extensions for Stream Control Transmission Protocol 16 (SCTP) 17 draft-ietf-tsvwg-sctpsocket-10.txt 19 Status of this Memo 21 This document is an Internet-Draft and is subject to all provisions 22 of Section 3 of RFC 3667. By submitting this Internet-Draft, each 23 author represents that any applicable patent or other IPR claims of 24 which he or she is aware have been or will be disclosed, and any of 25 which he or she become aware will be disclosed, in accordance with 26 RFC 3668. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF), its areas, and its working groups. Note that 30 other groups may also distribute working documents as 31 Internet-Drafts. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 The list of current Internet-Drafts can be accessed at 39 http://www.ietf.org/ietf/1id-abstracts.txt. 41 The list of Internet-Draft Shadow Directories can be accessed at 42 http://www.ietf.org/shadow.html. 44 This Internet-Draft will expire on August 25, 2005. 46 Copyright Notice 47 Copyright (C) The Internet Society (2005). 49 Abstract 51 This document describes a mapping of the Stream Control Transmission 52 Protocol SCTP RFC2960 [8] into a sockets API. The benefits of this 53 mapping include compatibility for TCP applications, access to new 54 SCTP features and a consolidated error and event notification scheme. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . 7 60 2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 7 61 3. one-to-many style Interface . . . . . . . . . . . . . . . . 8 62 3.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 8 63 3.1.1 socket() - one-to-many style socket . . . . . . . . . 9 64 3.1.2 bind() - one-to-many style socket . . . . . . . . . . 9 65 3.1.3 listen() - One-to-many style socket . . . . . . . . . 10 66 3.1.4 sendmsg() and recvmsg() - one-to-many style socket . . 11 67 3.1.5 close() - one-to-many style socket . . . . . . . . . . 12 68 3.1.6 connect() - one-to-many style socket . . . . . . . . . 13 69 3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 13 70 3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14 71 3.4 Special considerations . . . . . . . . . . . . . . . . . . 15 72 4. one-to-one style Interface . . . . . . . . . . . . . . . . . 17 73 4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 17 74 4.1.1 socket() - one-to-one style socket . . . . . . . . . . 18 75 4.1.2 bind() - one-to-one style socket . . . . . . . . . . . 18 76 4.1.3 listen() - one-to-one style socket . . . . . . . . . . 19 77 4.1.4 accept() - one-to-one style socket . . . . . . . . . . 20 78 4.1.5 connect() - one-to-one style socket . . . . . . . . . 20 79 4.1.6 close() - one-to-one style socket . . . . . . . . . . 21 80 4.1.7 shutdown() - one-to-one style socket . . . . . . . . . 21 81 4.1.8 sendmsg() and recvmsg() - one-to-one style socket . . 22 82 4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . 23 83 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . 24 84 5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 24 85 5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 25 86 5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 26 87 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . 27 88 5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 30 89 5.3.1 SCTP Notification Structure . . . . . . . . . . . . . 30 90 5.4 Ancillary Data Considerations and Semantics . . . . . . . 40 91 5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . 40 92 5.4.2 Accessing and Manipulating Ancillary Data . . . . . . 40 93 5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . 41 94 6. Common Operations for Both Styles . . . . . . . . . . . . . 43 95 6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 43 96 6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 44 97 6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 44 98 6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 44 99 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . 46 100 7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 47 101 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 47 102 7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . 48 103 7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . 50 104 7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 50 105 7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 50 106 7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 51 107 7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 51 108 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . 51 109 7.1.9 Set Peer Primary Address 110 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 51 111 7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . 52 112 7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) . 52 113 7.1.12 Enable/Disable message fragmentation 114 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . 53 115 7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . 53 116 7.1.14 Set default send parameters 117 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . 55 118 7.1.15 Set notification and ancillary events 119 (SCTP_EVENTS) . . . . . . . . . . . . . . . . . . . 55 120 7.1.16 Set/clear IPv4 mapped addresses 121 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . 55 122 7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) . . 55 123 7.1.18 Set/Get the list of chunks that must be 124 authenticated (SCTP_AUTH_CHUNKS) . . . . . . . . . . 56 125 7.1.19 Set/Get the current authentication shared secret 126 (SCTP_AUTH_SECRET) . . . . . . . . . . . . . . . . . 56 127 7.1.20 Get the list of chunks that peer requires to be 128 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . 57 129 7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 57 130 7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . 57 131 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 58 132 7.3 Ancillary Data and Notification Interest Options . . . . . 59 133 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . 62 134 8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 62 135 8.2 Branched-off Association . . . . . . . . . . . . . . . . . 63 136 8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 63 137 8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 64 138 8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 64 139 8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 65 140 8.7 sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 65 141 8.8 sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 66 142 8.9 sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 67 143 8.10 sctp_send() . . . . . . . . . . . . . . . . . . . . . . 68 144 8.11 sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . 68 145 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . 70 146 10. Security Considerations . . . . . . . . . . . . . . . . . . 71 147 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 72 148 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 149 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 73 150 A. one-to-one style Code Example . . . . . . . . . . . . . . . 75 151 B. one-to-many style Code Example . . . . . . . . . . . . . . . 81 152 Intellectual Property and Copyright Statements . . . . . . . 83 154 1. Introduction 156 The sockets API has provided a standard mapping of the Internet 157 Protocol suite to many operating systems. Both TCP RFC793 [1] and 158 UDP RFC768 [2] have benefited from this standard representation and 159 access method across many diverse platforms. SCTP is a new protocol 160 that provides many of the characteristics of TCP but also 161 incorporates semantics more akin to UDP. This document defines a 162 method to map the existing sockets API for use with SCTP, providing 163 both a base for access to new features and compatibility so that most 164 existing TCP applications can be migrated to SCTP with few (if any) 165 changes. 167 There are three basic design objectives: 169 1) Maintain consistency with existing sockets APIs: 170 We define a sockets mapping for SCTP that is consistent with other 171 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 172 IPv6). 173 2) Support a one-to-many style interface 174 This set of semantics is similar to that defined for 175 connection-less protocols, such as UDP. A one-to-many style SCTP 176 socket should be able to control multiple SCTP associations. This 177 is similar to an UDP socket, which can communicate with many peer 178 end points. Each of these associations is assigned an association 179 ID so that an applications can use the ID to differentiate them. 180 Note that SCTP is connection-oriented in nature, and it does not 181 support broadcast or multicast communications, as UDP does. 182 3) Support a one-to-one style interface 183 This interface supports a similar semantics as sockets for 184 connection-oriented protocols, such as TCP. A one-to-one style 185 SCTP socket should only control one SCTP association. 186 One purpose of defining this interface is to allow existing 187 applications built on other connection-oriented protocols be 188 ported to use SCTP with very little effort. And developers 189 familiar with those semantics can easily adapt to SCTP. Another 190 purpose is to make sure that existing mechanisms in most OSes to 191 deal with socket, such as select(), should continue to work with 192 this style of socket. 193 Extensions are added to this mapping to provide mechanisms to 194 exploit new features of SCTP. 196 Goals 2 and 3 are not compatible, so in this document we define two 197 modes of mapping, namely the one-to-many style mapping and the 198 one-to-one style mapping. These two modes share some common data 199 structures and operations, but will require the use of two different 200 application programming styles. Note that all new SCTP features can 201 be used with both styles of socket. The decision on which one to use 202 depends mainly on the nature of applications. 204 A mechanism is defined to extract a one-to-many style SCTP 205 association into a one-to-one style socket. 207 Some of the SCTP mechanisms cannot be adequately mapped to existing 208 socket interface. In some cases, it is more desirable to have new 209 interface instead of using existing socket calls. Section 8 of this 210 document describes those new interface. 212 2. Conventions 214 2.1 Data Types 216 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 217 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 218 (e.g., uint16_t). We also assume the argument data types from 219 1003.1g when possible (e.g., the final argument to setsockopt() is a 220 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 221 size_t data type is used. 223 3. one-to-many style Interface 225 The one-to-many style interface has the following characteristics: 227 A) Outbound association setup is implicit. 229 B) Messages are delivered in complete messages (with one notable 230 exception). 232 C) There is a 1 to MANY relationship between socket and association. 234 3.1 Basic Operation 236 A typical server in this style uses the following socket calls in 237 sequence to prepare an endpoint for servicing requests: 239 1. socket() 240 2. bind() 241 3. listen() 242 4. recvmsg() 243 5. sendmsg() 244 6. close() 246 A typical client uses the following calls in sequence to setup an 247 association with a server to request services: 249 1. socket() 250 2. sendmsg() 251 3. recvmsg() 252 4. close() 254 In this style, by default, all the associations connected to the 255 endpoint are represented with a single socket. Each associations is 256 assigned an association ID (type is sctp_assoc_t) so that an 257 application can use it to differentiate between them. In some 258 implementations, the peer end point's addresses can also be used for 259 this purpose. But this is not required for performance reasons. If 260 an implementation does not support using addresses to differentiate 261 between different associations, the sendto() call can only be used to 262 setup an association implicitly. It cannot be used to send data to 263 an established association as the association ID cannot be specified. 265 Once as association ID is assigned to an SCTP association, that ID 266 will not be reused until the application explicitly terminates the 267 association. The resources belonged to that association will not be 268 freed until that happens. This is similar to the close() operation 269 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 270 option (section 7.1.8) is set. In this case, after the association 271 is terminated automatically, the association ID assigned to it can be 272 reused. All applications using this option should be aware of this 273 to avoid the possible problem of sending data to an incorrect peer 274 end point. 276 If the server or client wishes to branch an existing association off 277 to a separate socket, it is required to call sctp_peeloff() and in 278 the parameter specifies the association identification. The 279 sctp_peeloff() call will return a new socket which can then be used 280 with recv() and send() functions for message passing. See 281 Section 8.2 for more on branched-off associations. 283 Once an association is branched off to a separate socket, it becomes 284 completely separated from the original socket. All subsequent 285 control and data operations to that association must be done through 286 the new socket. For example, the close operation on the original 287 socket will not terminate any associations that have been branched 288 off to a different socket. 290 We will discuss the one-to-many style socket calls in more details in 291 the following subsections. 293 3.1.1 socket() - one-to-many style socket 295 Applications use socket() to create a socket descriptor to represent 296 an SCTP endpoint. 298 The syntax is, 300 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 302 or, 304 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 306 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 307 socket. 309 The first form creates an endpoint which can use only IPv4 addresses, 310 while, the second form creates an endpoint which can use both IPv6 311 and IPv4 addresses. 313 3.1.2 bind() - one-to-many style socket 315 Applications use bind() to specify which local address the SCTP 316 endpoint should associate itself with. 318 An SCTP endpoint can be associated with multiple addresses. To do 319 this, sctp_bindx() is introduced in section Section 8.1 to help 320 applications do the job of associating multiple addresses. 322 These addresses associated with a socket are the eligible transport 323 addresses for the endpoint to send and receive data. The endpoint 324 will also present these addresses to its peers during the association 325 initialization process, see RFC2960 [8]. 327 After calling bind(), if the endpoint wishes to accept new 328 associations on the socket, it must call listen() (see section 329 Section 3.1.3). 331 The syntax of bind() is, 333 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 335 sd: the socket descriptor returned by socket(). 336 addr: the address structure (struct sockaddr_in or struct 337 sockaddr_in6 RFC2553 [7]). 338 addrlen: the size of the address structure. 340 If sd is an IPv4 socket, the address passed must be an IPv4 address. 341 If the sd is an IPv6 socket, the address passed can either be an IPv4 342 or an IPv6 address. 344 Applications cannot call bind() multiple times to associate multiple 345 addresses to an endpoint. After the first call to bind(), all 346 subsequent calls will return an error. 348 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 349 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 350 operating system will associate the endpoint with an optimal address 351 set of the available interfaces. 353 If a bind() is not called prior to a sendmsg() call that initiates a 354 new association, the system picks an ephemeral port and will choose 355 an address set equivalent to binding with a wildcard address. One of 356 those addresses will be the primary address for the association. 357 This automatically enables the multi-homing capability of SCTP. 359 3.1.3 listen() - One-to-many style socket 361 By default, new associations are not accepted for one-to-many style 362 sockets. An application uses listen() to mark a socket as being able 363 to accept new associations. The syntax is, 365 int listen(int sd, int backlog); 366 sd - the socket descriptor of the endpoint. 368 backlog - if backlog is non-zero, enable listening else 369 disable listening. 371 Note that one-to-many style socket consumers do not need to call 372 accept to retrieve new associations. Calling accept() on a 373 one-to-many style socket should return EOPNOTSUPP. Rather, new 374 associations are accepted automatically, and notifications of the new 375 associations are delivered via recvmsg() with the SCTP_ASSOC_CHANGE 376 event (if these notifications are enabled). Clients will typically 377 not call listen(), so that they can be assured that the only 378 associations on the socket will be ones they actively initiated. 379 Server or peer-to-peer sockets, on the other hand, will always accept 380 new associations, so a well-written application using server 381 one-to-many style sockets must be prepared to handle new associations 382 from unwanted peers. 384 Also note that the SCTP_ASSOC_CHANGE event provides the association 385 ID for a new association, so if applications wish to use the 386 association ID as input to other socket calls, they should ensure 387 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 388 default). 390 3.1.4 sendmsg() and recvmsg() - one-to-many style socket 392 An application uses sendmsg() and recvmsg() call to transmit data to 393 and receive data from its peer. 395 ssize_t sendmsg(int sd, const struct msghdr *message, int flags); 397 ssize_t recvmsg(int sd, struct msghdr *message, int flags); 399 sd: the socket descriptor of the endpoint. 400 message: pointer to the msghdr structure which contains a single user 401 message and possibly some ancillary data. See Section 5 for 402 complete description of the data structures. 403 flags: No new flags are defined for SCTP at this level. See Section 404 5 for SCTP-specific flags used in the msghdr structure. 406 As we will see in Section 5, along with the user data, the ancillary 407 data field is used to carry the sctp_sndrcvinfo and/or the 408 sctp_initmsg structures to perform various SCTP functions including 409 specifying options for sending each user message. Those options, 410 depending on whether sending or receiving, include stream number, 411 stream sequence number, various flags, context and payload protocol 412 Id, etc. 414 When sending user data with sendmsg(), the msg_name field in msghdr 415 structure will be filled with one of the transport addresses of the 416 intended receiver. If there is no association existing between the 417 sender and the intended receiver, the sender's SCTP stack will set up 418 a new association and then send the user data (see Section 3.2 for 419 more on implicit association setup). 421 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 422 be delivered if that notification has been enabled, and no more data 423 can be sent to that association. Any attempt to send more data will 424 cause sendmsg() to return with an ESHUTDOWN error. Note that the 425 socket is still open for reading at this point so it is possible to 426 retrieve notifications. 428 When receiving a user message with recvmsg(), the msg_name field in 429 msghdr structure will be populated with the source transport address 430 of the user data. The caller of recvmsg() can use this address 431 information to determine to which association the received user 432 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 433 applications must use the peer transport address provided in the 434 msg_name field by recvmsg() to perform correlation to an association, 435 since they will not have the association ID. 437 If all data in a single message has been delivered, MSG_EOR will be 438 set in the msg_flags field of the msghdr structure (see section 439 Section 5.1). 441 If the application does not provide enough buffer space to completely 442 receive a data message, MSG_EOR will not be set in msg_flags. 443 Successive reads will consume more of the same message until the 444 entire message has been delivered, and MSG_EOR will be set. 446 If the SCTP stack is running low on buffers, it may partially deliver 447 a message. In this case, MSG_EOR will not be set, and more calls to 448 recvmsg() will be necessary to completely consume the message. Only 449 one message at a time can be partially delivered. 451 Note, if the socket is a branched-off socket that only represents one 452 association (see Section 3.1), the msg_name field can be used to 453 override the primary address when sending data. 455 3.1.5 close() - one-to-many style socket 457 Applications use close() to perform graceful shutdown (as described 458 in Section 10.1 of RFC2960 [8]) on ALL the associations currently 459 represented by a one-to-many style socket. 461 The syntax is: 463 ret = close(int sd); 464 sd - the socket descriptor of the associations to be closed. 466 To gracefully shutdown a specific association represented by the 467 one-to-many style socket, an application should use the sendmsg() 468 call, and including the MSG_EOF flag. A user may optionally 469 terminate an association non-gracefully by sending with the MSG_ABORT 470 flag and possibly passing a user specified abort code in the data 471 field. Both flags MSG_EOF and MSG_ABORT are passwd with ancillary 472 data (see Section 5.2.2) in the sendmsg call. 474 If sd in the close() call is a branched-off socket representing only 475 one association, the shutdown is performed on that association only. 477 3.1.6 connect() - one-to-many style socket 479 An application may use the connect() call in the one-to-many style to 480 initiate an association without sending data. 482 The syntax is: 484 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 486 sd: the socket descriptor to have a new association added to. 487 nam: the address structure (either struct sockaddr_in or struct 488 sockaddr_in6 defined in RFC2553 [7]). 489 len: the size of the address. 490 Multiple connect() calls can be made on the same socket to create 491 multiple associations. This is different from the semantics of 492 connect() on a UDP socket. 494 3.2 Implicit Association Setup 496 Once the bind() call is complete on a one-to-many style socket, the 497 application can begin sending and receiving data using the 498 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 499 through any explicit association setup procedures (i.e., no connect() 500 calls required). 502 Whenever sendmsg() or sendto() is called and the SCTP stack at the 503 sender finds that there is no association existing between the sender 504 and the intended receiver (identified by the address passed either in 505 the msg_name field of msghdr structure in the sendmsg() call or the 506 dest_addr field in the sendto() call), the SCTP stack will 507 automatically setup an association to the intended receiver. 509 Upon the successful association setup a SCTP_COMM_UP notification 510 will be dispatched to the socket at both the sender and receiver 511 side. This notification can be read by the recvmsg() system call 512 (see Section 3.1.3). 514 Note, if the SCTP stack at the sender side supports bundling, the 515 first user message may be bundled with the COOKIE ECHO message 516 RFC2960 [8]. 518 When the SCTP stack sets up a new association implicitly, it first 519 consults the sctp_initmsg structure, which is passed along within the 520 ancillary data in the sendmsg() call (see Section 5.2.1 for details 521 of the data structures), for any special options to be used on the 522 new association. 524 If this information is not present in the sendmsg() call, or if the 525 implicit association setup is triggered by a sendto() call, the 526 default association initialization parameters will be used. These 527 default association parameters may be set with respective 528 setsockopt() calls or be left to the system defaults. 530 Implicit association setup cannot be initiated by send()/recv() 531 calls. 533 3.3 Non-blocking mode 535 Some SCTP users might want to avoid blocking when they call socket 536 interface function. 538 Once all bind() calls are complete on a one-to-many style socket, the 539 application must set the non-blocking option by a fcntl() (such as 540 O_NONBLOCK). After which the sendmsg() function returns immediately, 541 and the success or failure of the data message (and possible 542 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 543 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 544 be sent (due to a CANT_START_ASSOC), the sender will also receive a 545 SCTP_SEND_FAILED event. Those event(s) can be received by the user 546 calling of recvmsg(). A server (having called listen()) is also 547 notified of an association up event by the reception of a 548 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 549 possibly the reception of the first data message. 551 In order to shutdown the association gracefully, the user must call 552 sendmsg() with no data and with the MSG_EOF flag set. The function 553 returns immediately, and completion of the graceful shutdown is 554 indicated by an SCTP_ASSOC_CHANGE notification of type 555 SHUTDOWN_COMPLETE (see Section 5.3.1.1). Note that this can also be 556 done using the sctp_send() call described in Section 8.10. 558 An application is recommended to use caution when using select() (or 559 poll()) for writing on a one-to-many style socket. The reason being 560 that interpretation of select on write is implementation specific. 561 Generally a positive return on a select on write would only indicate 562 that one of the associations represented by the one-to-many socket is 563 writable. An application that writes after the select return may 564 still block since the association that was writeable is not the 565 destination association of the write call. Likewise select (or 566 poll()) for reading from a one-to-many socket will only return an 567 indication that one of the associations represented by the socket has 568 data to be read. 570 An application that wishes to know that a particular association is 571 ready for reading or writing should either use the one-to-one style 572 or use the sctp_peelloff() (see Section 8.2) function to seperate the 573 association of interest from the one-to-many socket. 575 3.4 Special considerations 577 The fact that a one-to-many style socket can provide access to many 578 SCTP associations through a single socket descriptor has important 579 implications for both application programmers and system programmers 580 implementing this API. A key issue is how buffer space inside the 581 sockets layer is managed. Because this implementation detail 582 directly affects how application programmers must write their code to 583 ensure correct operation and portability, this section provides some 584 guidance to both implementors and application programmers. 586 An important feature that SCTP shares with TCP is flow control: 587 specifically, a sender may not send data faster than the receiver can 588 consume it. 590 For TCP, flow control is typically provided for in the sockets API as 591 follows. If the reader stops reading, the sender queues messages in 592 the socket layer until it uses all of its socket buffer space 593 allocation creating a "stalled connection". Further attempts to 594 write to the socket will block or return the error EAGAIN or 595 EWOULDBLOCK for a non-blocking socket. At some point, either the 596 connection is closed, or the receiver begins to read again freeing 597 space in the output queue. 599 For one-to-one style SCTP sockets (this includes sockets descriptors 600 that were separated from a one-to-many style socket with 601 sctp_peeloff()) the behavior is identical. For one-to-many style 602 SCTP sockets, the fact that we have multiple associations on a single 603 socket makes the situation more complicated. If the implementation 604 uses a single buffer space allocation shared by all associations, a 605 single stalled association can prevent the further sending of data on 606 all associations active on a particular one-to-many style socket. 608 For a blocking socket, it should be clear that a single stalled 609 association can block the entire socket. For this reason, 610 application programmers may want to use non-blocking one-to-many 611 style sockets. The application should at least be able to send 612 messages to the non-stalled associations. 614 But a non-blocking socket is not sufficient if the API implementor 615 has chosen a single shared buffer allocation for the socket. A 616 single stalled association would eventually cause the shared 617 allocation to fill, and it would become impossible to send even to 618 non-stalled associations. 620 The API implementor can solve this problem by providing each 621 association with its own allocation of outbound buffer space. Each 622 association should conceptually have as much buffer space as it would 623 have if it had its own socket. As a bonus, this simplifies the 624 implementation of sctp_peeloff(). 626 To ensure that a given stalled association will not prevent other 627 non-stalled associations from being writable, application programmers 628 should either: 629 (a) demand that the underlying implementation dedicates independent 630 buffer space allotments to each association (as suggested above), 631 or 632 (b) verify that their application layer protocol does not permit 633 large amounts of unread data at the receiver (this is true of some 634 request-response protocols, for example), or 635 (c) use one-to-one style sockets for association which may 636 potentially stall (either from the beginning, or by using 637 sctp_peeloff before sending large amounts of data that may cause a 638 stalled condition). 639 An implemenation which dedicates independent buffer space for each 640 association should define HAVE_SCTP_MULTIBUF to 1. 642 4. one-to-one style Interface 644 The goal of this style is to follow as closely as possible the 645 current practice of using the sockets interface for a connection 646 oriented protocol, such as TCP. This style enables existing 647 applications using connection oriented protocols to be ported to SCTP 648 with very little effort. 650 Note that some new SCTP features and some new SCTP socket options can 651 only be utilized through the use of sendmsg() and recvmsg() calls, 652 see Section 4.1.8. Also note that some socket interfaces may not be 653 able to provide data on the third leg of the association set up with 654 this interface style. 656 4.1 Basic Operation 658 A typical server in one-to-one style uses the following system call 659 sequence to prepare an SCTP endpoint for servicing requests: 661 1. socket() 663 2. bind() 665 3. listen() 667 4. accept() 669 The accept() call blocks until a new association is set up. It 670 returns with a new socket descriptor. The server then uses the new 671 socket descriptor to communicate with the client, using recv() and 672 send() calls to get requests and send back responses. 674 Then it calls 676 5. close() 678 to terminate the association. 680 A typical client uses the following system call sequence to setup an 681 association with a server to request services: 683 1. socket() 685 2. connect() 687 After returning from connect(), the client uses send() and recv() 688 calls to send out requests and receive responses from the server. 690 The client calls 692 3. close() 694 to terminate this association when done. 696 4.1.1 socket() - one-to-one style socket 698 Applications calls socket() to create a socket descriptor to 699 represent an SCTP endpoint. 701 The syntax is: 703 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 705 or, 707 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 709 Here, SOCK_STREAM indicates the creation of a one-to-one style 710 socket. 712 The first form creates an endpoint which can use only IPv4 addresses, 713 while the second form creates an endpoint which can use both IPv6 and 714 IPv4 addresses. 716 4.1.2 bind() - one-to-one style socket 718 Applications use bind() to pass an address to be associated with an 719 SCTP endpoint to the system. bind() allows only either a single 720 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 721 endpoint can be associated with multiple addresses. To do this, 722 sctp_bindx() is introduced in Section 8.1 to help applications do 723 the job of associating multiple addresses. 725 These addresses associated with a socket are the eligible transport 726 addresses for the endpoint to send and receive data. The endpoint 727 will also present these addresses to its peers during the association 728 initialization process, see RFC2960 [8]. 730 The syntax is: 732 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 734 sd: the socket descriptor returned by socket() call. 736 addr: the address structure (either struct sockaddr_in or struct 737 sockaddr_in6 defined in RFC2553 [7]). 738 addrlen: the size of the address structure. 740 If sd is an IPv4 socket, the address passed must be an IPv4 address. 741 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 742 either be an IPv4 or an IPv6 address. 744 Applications cannot call bind() multiple times to associate multiple 745 addresses to the endpoint. After the first call to bind(), all 746 subsequent calls will return an error. 748 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 749 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 750 operating system will associate the endpoint with an optimal address 751 set of the available interfaces. 753 If a bind() is not called prior to the connect() call, the system 754 picks an ephemeral port and will choose an address set equivalent to 755 binding with a wildcard address. One of those addresses will be the 756 primary address for the association. This automatically enables the 757 multi-homing capability of SCTP. 759 The completion of this bind() process does not ready the SCTP 760 endpoint to accept inbound SCTP association requests. Until a 761 listen() system call, described below, is performed on the socket, 762 the SCTP endpoint will promptly reject an inbound SCTP INIT request 763 with an SCTP ABORT. 765 4.1.3 listen() - one-to-one style socket 767 Applications use listen() to ready the SCTP endpoint for accepting 768 inbound associations. 770 The syntax is: 772 int listen(int sd, int backlog); 774 sd: the socket descriptor of the SCTP endpoint. 775 backlog: this specifies the max number of outstanding associations 776 allowed in the socket's accept queue. These are the associations 777 that have finished the four-way initiation handshake (see Section 778 5 of RFC2960 [8]) and are in the ESTABLISHED state. Note, a 779 backlog of '0' indicates that the caller no longer wishes to 780 receive new associations. 782 4.1.4 accept() - one-to-one style socket 784 Applications use accept() call to remove an established SCTP 785 association from the accept queue of the endpoint. A new socket 786 descriptor will be returned from accept() to represent the newly 787 formed association. 789 The syntax is: 791 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 793 new_sd: the socket descriptor for the newly formed association. 794 sd the listening socket descriptor. 795 addr on return, will contain the primary address of the peer 796 endpoint. 797 addrlen on return, will contain the size of addr. 799 4.1.5 connect() - one-to-one style socket 801 Applications use connect() to initiate an association to a peer. 803 The syntax is: 805 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 807 sd: the socket descriptor of the endpoint. 808 addr the peer's address. 809 addrlen the size of the address. 811 This operation corresponds to the ASSOCIATE primitive described in 812 section 10.1 of RFC2960 [8]. 814 By default, the new association created has only one outbound stream. 815 The SCTP_INITMSG option described in Section 7.1.3 should be used 816 before connecting to change the number of outbound streams. 818 If a bind() is not called prior to the connect() call, the system 819 picks an ephemeral port and will choose an address set equivalent to 820 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket 821 respectively. One of those addresses will be the primary address for 822 the association. This automatically enables the multi-homing 823 capability of SCTP. 825 Note that SCTP allows data exchange, similar to T/TCP RFC1644 [3], 826 during the association set up phase. If an application wants to do 827 this, it cannot use connect() call. Instead, it should use sendto() 828 or sendmsg() to initiate an association. If it uses sendto() and it 829 wants to change initialization behavior, it needs to use the 830 SCTP_INITMSG socket option before calling sendto(). Or it can use 831 SCTP_INIT type sendmsg() to initiate an association without doing the 832 setsockopt(). Note that some sockets implementations may not support 833 the sending of data to initiate an assocation with the one-to-one 834 style (implementations that do not support T/TCP normally have this 835 restriction). Implementations which allow sending of data to 836 initiate an association without calling connect() define the 837 preprocessor constant HAVE_SCTP_NOCONNECT to 1. 839 SCTP does not support half close semantics. This means that unlike 840 T/TCP, MSG_EOF should not be set in the flags parameter when calling 841 sendto() or sendmsg() when the call is used to initiate a connection. 842 MSG_EOF is not an acceptable flag with SCTP socket. 844 4.1.6 close() - one-to-one style socket 846 Applications use close() to gracefully close down an association. 848 The syntax is: 850 int close(int sd); 852 sd - the socket descriptor of the association to be closed. 854 After an application calls close() on a socket descriptor, no further 855 socket operations will succeed on that descriptor. 857 4.1.7 shutdown() - one-to-one style socket 859 SCTP differs from TCP in that it does not have half closed semantics. 860 Hence the shutdown() call for SCTP is an approximation of the TCP 861 shutdown() call, and solves some different problems. Full 862 TCP-compatibility is not provided, so developers porting TCP 863 applications to SCTP may need to recode sections that use shutdown(). 864 (Note that it is possible to achieve the same results as half close 865 in SCTP using SCTP streams.) 867 The syntax is: 869 int shutdown(int sd, int how); 871 sd - the socket descriptor of the association to be closed. 873 how - Specifies the type of shutdown. The values are 874 as follows: 876 SHUT_RD 877 Disables further receive operations. No SCTP 878 protocol action is taken. 880 SHUT_WR 881 Disables further send operations, and initiates 882 the SCTP shutdown sequence. 884 SHUT_RDWR 885 Disables further send and receive operations 886 and initiates the SCTP shutdown sequence. 888 The major difference between SCTP and TCP shutdown() is that SCTP 889 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 890 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 891 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 892 the SCTP association while still leaving the socket descriptor open, 893 so that the caller can receive back any data SCTP was unable to 894 deliver (see Section 5.3.1.4 for more information). 896 To perform the ABORT operation described in RFC2960 [8] section 10.1, 897 an application can use the socket option SO_LINGER. It is described 898 in Section 7.1.4. 900 4.1.8 sendmsg() and recvmsg() - one-to-one style socket 902 With a one-to-one style socket, the application can also use 903 sendmsg() and recvmsg() to transmit data to and receive data from its 904 peer. The semantics is similar to those used in the one-to-many 905 style (section Section 3.1.3), with the following differences: 907 1) When sending, the msg_name field in the msghdr is not used to 908 specify the intended receiver, rather it is used to indicate a 909 preferred peer address if the sender wishes to discourage the stack 910 from sending the message to the primary address of the receiver. If 911 the transport address given is not part of the current association, 912 the data will not be sent and a SCTP_SEND_FAILED event will be 913 delivered to the application if send failure events are enabled. 915 4.1.9 getpeername() 917 Applications use getpeername() to retrieve the primary socket address 918 of the peer. This call is for TCP compatibility, and is not 919 multi-homed. It does not work with one-to-many style sockets. See 920 Section 8.3 for a multi-homed/one-to-many style version of the call 921 . 923 The syntax is: 925 int getpeername(int sd, struct sockaddr *address, 926 socklen_t *len); 928 sd - the socket descriptor to be queried. 930 address - On return, the peer primary address is stored in 931 this buffer. If the socket is an IPv4 socket, the 932 address will be IPv4. If the socket is an IPv6 socket, 933 the address will be either an IPv6 or IPv4 934 address. 936 len - The caller should set the length of address here. 937 On return, this is set to the length of the returned 938 address. 940 If the actual length of the address is greater than the length of the 941 supplied sockaddr structure, the stored address will be truncated. 943 5. Data Structures 945 We discuss in this section important data structures which are 946 specific to SCTP and are used with sendmsg() and recvmsg() calls to 947 control SCTP endpoint operations and to access ancillary information 948 and notifications. 950 5.1 The msghdr and cmsghdr Structures 952 The msghdr structure used in the sendmsg() and recvmsg() calls, as 953 well as the ancillary data carried in the structure, is the key for 954 the application to set and get various control information from the 955 SCTP endpoint. 957 The msghdr and the related cmsghdr structures are defined and 958 discussed in details in RFC2292 [6]. Here we will cite their 959 definitions from RFC2292 [6]. 961 The msghdr structure: 963 struct msghdr { 964 void *msg_name; /* ptr to socket address structure */ 965 socklen_t msg_namelen; /* size of socket address structure */ 966 struct iovec *msg_iov; /* scatter/gather array */ 967 size_t msg_iovlen; /* # elements in msg_iov */ 968 void *msg_control; /* ancillary data */ 969 socklen_t msg_controllen; /* ancillary data buffer length */ 970 int msg_flags; /* flags on received message */ 971 }; 973 The cmsghdr structure: 975 struct cmsghdr { 976 socklen_t cmsg_len; /* #bytes, including this header */ 977 int cmsg_level; /* originating protocol */ 978 int cmsg_type; /* protocol-specific type */ 979 /* followed by unsigned char cmsg_data[]; */ 980 }; 982 In the msghdr structure, the usage of msg_name has been discussed in 983 previous sections (see Section 3.1.3 and Section 4.1.8). 985 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 986 field) are treated as a single SCTP data chunk, rather than multiple 987 chunks, for both sendmsg() and recvmsg(). 989 The msg_flags are not used when sending a message with sendmsg(). 991 If a notification has arrived, recvmsg() will return the notification 992 with the MSG_NOTIFICATION flag set in msg_flags. If the 993 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 994 Section 5.3 for more information about notifications. 996 If all portions of a data frame or notification have been read, 997 recvmsg() will return with MSG_EOR set in msg_flags. 999 5.2 SCTP msg_control Structures 1001 A key element of all SCTP-specific socket extensions is the use of 1002 ancillary data to specify and access SCTP-specific data via the 1003 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1004 Fine-grained control over initialization and sending parameters are 1005 handled with ancillary data. 1007 Each ancillary data item is proceeded by a struct cmsghdr (see 1008 Section 5.1), which defines the function and purpose of the data 1009 contained in in the cmsg_data[] member. 1011 There are two kinds of ancillary data used by SCTP: initialization 1012 data, and, header information (SNDRCV). Initialization data 1013 (one-to-many style only) sets protocol parameters for new 1014 associations. Section 5.2.1 provides more details. Header 1015 information can set or report parameters on individual messages in a 1016 stream. See Section 5.2.2 for how to use SNDRCV ancillary data. 1018 By default on a one-to-one style socket, SCTP will pass no ancillary 1019 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1020 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1021 be enabled with socket options defined for SCTP; see Section 7.3. 1023 Note that all ancillary types are fixed length; see Section 5.4 for 1024 further discussion on this. These data structures use struct 1025 sockaddr_storage (defined in RFC2553 [7]) as a portable, fixed length 1026 address format. 1028 Other protocols may also provide ancillary data to the socket layer 1029 consumer. These ancillary data items from other protocols may 1030 intermingle with SCTP data. For example, the IPv6 socket API 1031 definitions (RFC2292 [6] and RFC2553 [7]) define a number of 1032 ancillary data items. If a socket API consumer enables delivery of 1033 both SCTP and IPv6 ancillary data, they both may appear in the same 1034 msg_control buffer in any order. An application may thus need to 1035 handle other types of ancillary data besides that passed by SCTP. 1037 The sockets application must provide a buffer large enough to 1038 accommodate all ancillary data provided via recvmsg(). If the buffer 1039 is not large enough, the ancillary data will be truncated and the 1040 msghdr's msg_flags will include MSG_CTRUNC. 1042 5.2.1 SCTP Initiation Structure (SCTP_INIT) 1044 This cmsghdr structure provides information for initializing new SCTP 1045 associations with sendmsg(). The SCTP_INITMSG socket option uses 1046 this same data structure. This structure is not used for recvmsg(). 1048 cmsg_level cmsg_type cmsg_data[] 1049 ------------ ------------ ---------------------- 1050 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1052 Here is the definition of the sctp_initmsg structure: 1054 struct sctp_initmsg { 1055 uint16_t sinit_num_ostreams; 1056 uint16_t sinit_max_instreams; 1057 uint16_t sinit_max_attempts; 1058 uint16_t sinit_max_init_timeo; 1059 }; 1061 sinit_num_ostreams: 16 bits (unsigned integer) 1063 This is an integer number representing the number of streams that the 1064 application wishes to be able to send to. This number is confirmed 1065 in the SCTP_COMM_UP notification and must be verified since it is a 1066 negotiated number with the remote endpoint. The default value of 0 1067 indicates to use the endpoint default value. 1069 sinit_max_instreams: 16 bits (unsigned integer) 1071 This value represents the maximum number of inbound streams the 1072 application is prepared to support. This value is bounded by the 1073 actual implementation. In other words the user MAY be able to 1074 support more streams than the Operating System. In such a case, the 1075 Operating System limit overrides the value requested by the user. 1076 The default value of 0 indicates to use the endpoint's default value. 1078 sinit_max_attempts: 16 bits (unsigned integer) 1080 This integer specifies how many attempts the SCTP endpoint should 1081 make at resending the INIT. This value overrides the system SCTP 1082 'Max.Init.Retransmits' value. The default value of 0 indicates to 1083 use the endpoint's default value. This is normally set to the 1084 system's default 'Max.Init.Retransmit' value. 1086 sinit_max_init_timeo: 16 bits (unsigned integer) 1087 This value represents the largest Time-Out or RTO value (in 1088 milliseconds) to use inattempting a INIT. Normally the 'RTO.Max' is 1089 used to limit the doubling of the RTO upon timeout. For the INIT 1090 message this value MAY override 'RTO.Max'. This value MUST NOT 1091 influence 'RTO.Max' during data transmission and is only used to 1092 bound the initial setup time. A default value of 0 indicates to use 1093 the endpoint's default value. This is normally set to the system's 1094 'RTO.Max' value (60 seconds). 1096 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 1098 This cmsghdr structure specifies SCTP options for sendmsg() and 1099 describes SCTP header information about a received message through 1100 recvmsg(). 1102 cmsg_level cmsg_type cmsg_data[] 1103 ------------ ------------ ---------------------- 1104 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1106 Here is the definition of sctp_sndrcvinfo: 1108 struct sctp_sndrcvinfo { 1109 uint16_t sinfo_stream; 1110 uint16_t sinfo_ssn; 1111 uint16_t sinfo_flags; 1112 uint32_t sinfo_ppid; 1113 uint32_t sinfo_context; 1114 uint32_t sinfo_timetolive; 1115 uint32_t sinfo_tsn; 1116 uint32_t sinfo_cumtsn; 1117 sctp_assoc_t sinfo_assoc_id; 1118 }; 1120 sinfo_stream: 16 bits (unsigned integer) 1122 For recvmsg() the SCTP stack places the message's stream number in 1123 this value. For sendmsg() this value holds the stream number that 1124 the application wishes to send this message to. If a sender 1125 specifies an invalid stream number an error indication is returned 1126 and the call fails. 1128 sinfo_ssn: 16 bits (unsigned integer) 1130 For recvmsg() this value contains the stream sequence number that the 1131 remote endpoint placed in the DATA chunk. For fragmented messages 1132 this is the same number for all deliveries of the message (if more 1133 than one recvmsg() is needed to read the message). The sendmsg() 1134 call will ignore this parameter. 1136 sinfo_ppid: 32 bits (unsigned integer) 1138 This value in sendmsg() is an opaque unsigned value that is passed to 1139 the remote end in each user message. In recvmsg() this value is the 1140 same information that was passed by the upper layer in the peer 1141 application. Please note that byte order issues are NOT accounted 1142 for and this information is passed opaquely by the SCTP stack from 1143 one end to the other. 1145 sinfo_context: 32 bits (unsigned integer) 1147 This value is an opaque 32 bit context datum that is used in the 1148 sendmsg() function. This value is passed back to the upper layer if 1149 a error occurs on the send of a message and is retrieved with each 1150 undelivered message (Note: if a endpoint has done multiple sends, all 1151 of which fail, multiple different sinfo_context values will be 1152 returned. One with each user data message). 1154 sinfo_flags: 16 bits (unsigned integer) 1156 This field may contain any of the following flags and is composed of 1157 a bitwise OR of these values. 1159 recvmsg() flags: 1161 MSG_UNORDERED - This flag is present when the message was sent 1162 non-ordered. 1164 sendmsg() flags: 1166 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1167 message. If this flag is clear the datagram is 1168 considered an ordered send. 1170 MSG_ADDR_OVER - This flag, in the one-to-many style, requests the SCTP 1171 stack to override the primary destination address 1172 with the address found with the sendto/sendmsg 1173 call. 1175 MSG_ABORT - Setting this flag causes the specified association 1176 to abort by sending an ABORT message to the peer 1177 (one-to-many style only). The ABORT chunk 1178 will contain an error cause 'User Initiated Abort' 1179 with cause code 12.The cause specific 1180 information of this error cause is provided in msg_iov. 1182 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1183 procedures on the specified association. Graceful 1184 shutdown assures that all data enqueued by both 1185 endpoints is successfully transmitted before closing 1186 the association (one-to-many style only). 1188 MSG_SENDALL - This flag, if set, will cause a one-to-many model 1189 socket to send the message to all associations 1190 that are currently established on this socket. For 1191 the one-to-one socket, this flag has no effect. 1193 sinfo_timetolive: 32 bit (unsigned integer) 1195 For the sending side, this field contains the message time to live in 1196 milliseconds. The sending side will expire the message within the 1197 specified time period if the message as not been sent to the peer 1198 within this time period. This value will override any default value 1199 set using any socket option. Also note that the value of 0 is 1200 special in that it indicates no timeout should occur on this message. 1202 sinfo_tsn: 32 bit (unsigned integer) 1204 For the receiving side, this field holds a TSN that was assigned to 1205 one of the SCTP Data Chunks. 1207 sinfo_cumtsn: 32 bit (unsigned integer) 1209 This field will hold the current cumulative TSN as known by the 1210 underlying SCTP layer. Note this field is ignored when sending and 1211 only valid for a receive operation when sinfo_flags are set to 1212 MSG_UNORDERED. 1214 sinfo_assoc_id: sizeof (sctp_assoc_t) 1216 The association handle field, sinfo_assoc_id, holds the identifier 1217 for the association announced in the SCTP_COMM_UP notification. All 1218 notifications for a given association have the same identifier. 1219 Ignored for one-to-one style sockets. 1221 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1223 5.3 SCTP Events and Notifications 1225 An SCTP application may need to understand and process events and 1226 errors that happen on the SCTP stack. These events include network 1227 status changes, association startups, remote operational errors and 1228 undeliverable messages. All of these can be essential for the 1229 application. 1231 When an SCTP application layer does a recvmsg() the message read is 1232 normally a data message from a peer endpoint. If the application 1233 wishes to have the SCTP stack deliver notifications of non-data 1234 events, it sets the appropriate socket option for the notifications 1235 it wants. See Section 7.3 for these socket options. When a 1236 notification arrives, recvmsg() returns the notification in the 1237 application-supplied data buffer via msg_iov, and sets 1238 MSG_NOTIFICATION in msg_flags. 1240 This section details the notification structures. Every notification 1241 structure carries some common fields which provides general 1242 information. 1244 A recvmsg() call will return only one notification at a time. Just 1245 as when reading normal data, it may return part of a notification if 1246 the msg_iov buffer is not large enough. If a single read is not 1247 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1248 reading the notification before subsequent data can arrive. 1250 5.3.1 SCTP Notification Structure 1252 The notification structure is defined as the union of all 1253 notification types. 1255 union sctp_notification { 1256 struct { 1257 uint16_t sn_type; /* Notification type. */ 1258 uint16_t sn_flags; 1259 uint32_t sn_length; 1260 } sn_header; 1261 struct sctp_assoc_change sn_assoc_change; 1262 struct sctp_paddr_change sn_paddr_change; 1263 struct sctp_remote_error sn_remote_error; 1264 struct sctp_send_failed sn_send_failed; 1265 struct sctp_shutdown_event sn_shutdown_event; 1266 struct sctp_adaption_event sn_adaption_event; 1267 struct sctp_pdapi_event sn_pdapi_event; 1268 }; 1270 sn_type: 16 bits (unsigned integer) 1272 The following list describes the SCTP notification and event types 1273 for the field sn_type. 1275 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1276 been opened or closed. Refer to Section 5.3.1.1 for details. 1277 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1278 part of an existing association has experienced a change of state 1279 (e.g. a failure or return to service of the reachability of a 1280 endpoint via a specific transport address). Please see 1281 Section 5.3.1.2 for data structure details. 1282 SCTP_REMOTE_ERROR: The attached error message is an Operational Error 1283 received from the remote peer. It includes the complete TLV sent 1284 by the remote endpoint. See Section 5.3.1.3 for the detailed 1285 format. 1286 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1287 remote endpoint. This structure includes the original 1288 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1289 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1290 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1291 should be sent on this socket. 1292 SCTP_ADAPTION_INDICATION: This notification holds the peers indicated 1293 adaption layer. Please see Section 5.3.1.6. 1294 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1295 receiver that the partial delivery has been aborted. This may 1296 indicate the association is about to be aborted. Please see 1297 Section 5.3.1.7 1299 All standard values for sn_type are greater than 2^15. Values from 1300 2^15 and down are reserved. 1302 sn_flags: 16 bits (unsigned integer) 1304 These are notification-specific flags. 1306 sn_length: 32 bits (unsigned integer) 1308 This is the length of the whole sctp_notification structure including 1309 the sn_type, sn_flags, and sn_length fields. 1311 5.3.1.1 SCTP_ASSOC_CHANGE 1313 Communication notifications inform the ULP that an SCTP association 1314 has either begun or ended. The identifier for a new association is 1315 provided by this notification. The notification information has the 1316 following format: 1318 struct sctp_assoc_change { 1319 uint16_t sac_type; 1320 uint16_t sac_flags; 1321 uint32_t sac_length; 1322 uint16_t sac_state; 1323 uint16_t sac_error; 1324 uint16_t sac_outbound_streams; 1325 uint16_t sac_inbound_streams; 1326 sctp_assoc_t sac_assoc_id; 1327 uint8_t sac_info[0]; 1328 }; 1330 sac_type: 1332 It should be SCTP_ASSOC_CHANGE. 1334 sac_flags: 16 bits (unsigned integer) 1336 Currently unused. 1338 sac_length: 32 bits (unsigned integer) 1340 This field is the total length of the notification data, including 1341 the notification header. 1343 sac_state: 16 bits (signed integer) 1345 This field holds one of a number of values that communicate the event 1346 that happened to the association. They include: 1348 Event Name Description 1349 ---------------- --------------- 1350 SCTP_COMM_UP A new association is now ready 1351 and data may be exchanged with this 1352 peer. 1354 SCTP_COMM_LOST The association has failed. The association 1355 is now in the closed state. If SEND FAILED 1356 notifications are turned on, a SCTP_COMM_LOST 1357 is followed by a series of SCTP_SEND_FAILED 1358 events, one for each outstanding message. 1360 SCTP_RESTART SCTP has detected that the peer has restarted. 1362 SCTP_SHUTDOWN_COMP The association has gracefully closed. 1364 SCTP_CANT_STR_ASSOC The association failed to setup. If non blocking 1365 mode is set and data was sent (in the udp mode), 1366 a SCTP_CANT_STR_ASSOC is followed by a series of 1367 SCTP_SEND_FAILED events, one for each outstanding 1368 message. 1370 sac_error: 16 bits (signed integer) 1372 If the state was reached due to a error condition (e.g. 1373 SCTP_COMM_LOST) any relevant error information is available in this 1374 field. This corresponds to the protocol error codes defined in 1375 RFC2960 [8]. 1377 sac_outbound_streams: 16 bits (unsigned integer) 1379 sac_inbound_streams: 16 bits (unsigned integer) 1381 The maximum number of streams allowed in each direction are available 1382 in sac_outbound_streams and sac_inbound streams. 1384 sac_assoc_id: sizeof (sctp_assoc_t) 1386 The association id field, holds the identifier for the association. 1387 All notifications for a given association have the same association 1388 identifier. For one-to-one style socket, this field is ignored. 1390 sac_info: variable 1392 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1393 for this association, sac_info[] contains the complete ABORT chunk as 1394 defined in the SCTP specification RFC2960 [8] section 3.3.7. 1396 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1398 When a destination address on a multi-homed peer encounters a change 1399 an interface details event is sent. The information has the 1400 following structure: 1402 struct sctp_paddr_change { 1403 uint16_t spc_type; 1404 uint16_t spc_flags; 1405 uint32_t spc_length; 1406 struct sockaddr_storage spc_aaddr; 1407 int spc_state; 1408 int spc_error; 1409 sctp_assoc_t spc_assoc_id; 1410 } 1412 spc_type: 1414 It should be SCTP_PEER_ADDR_CHANGE. 1416 spc_flags: 16 bits (unsigned integer) 1418 Currently unused. 1420 spc_length: 32 bits (unsigned integer) 1422 This field is the total length of the notification data, including 1423 the notification header. 1425 spc_aaddr: sizeof (struct sockaddr_storage) 1427 The affected address field, holds the remote peer's address that is 1428 encountering the change of state. 1430 spc_state: 32 bits (signed integer) 1432 This field holds one of a number of values that communicate the event 1433 that happened to the address. They include: 1435 Event Name Description 1436 ---------------- --------------- 1437 SCTP_ADDR_AVAILABLE This address is now reachable. 1439 SCTP_ADDR_UNREACHABLE The address specified can no 1440 longer be reached. Any data sent 1441 to this address is rerouted to an 1442 alternate until this address becomes 1443 reachable. 1445 SCTP_ADDR_REMOVED The address is no longer part of 1446 the association. 1448 SCTP_ADDR_ADDED The address is now part of the 1449 association. 1451 SCTP_ADDR_MADE_PRIM This address has now been made 1452 to be the primary destination address. 1454 spc_error: 32 bits (signed integer) 1456 If the state was reached due to any error condition (e.g. 1457 SCTP_ADDR_UNREACHABLE) any relevant error information is available in 1458 this field. 1460 spc_assoc_id: sizeof (sctp_assoc_t) 1462 The association id field, holds the identifier for the association. 1463 All notifications for a given association have the same association 1464 identifier. For one-to-one style socket, this field is ignored. 1466 5.3.1.3 SCTP_REMOTE_ERROR 1468 A remote peer may send an Operational Error message to its peer. 1469 This message indicates a variety of error conditions on an 1470 association. The entire ERROR chunk as it appears on the wire is 1471 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1472 specification RFC2960 [8] and any extensions for a list of possible 1473 error formats. SCTP error notifications have the format: 1475 struct sctp_remote_error { 1476 uint16_t sre_type; 1477 uint16_t sre_flags; 1478 uint32_t sre_length; 1479 uint16_t sre_error; 1480 sctp_assoc_t sre_assoc_id; 1481 uint8_t sre_data[0]; 1482 }; 1484 sre_type: 1486 It should be SCTP_REMOTE_ERROR. 1488 sre_flags: 16 bits (unsigned integer) 1490 Currently unused. 1492 sre_length: 32 bits (unsigned integer) 1494 This field is the total length of the notification data, including 1495 the notification header and the contents of sre_data. 1497 sre_error: 16 bits (unsigned integer) 1499 This value represents one of the Operational Error causes defined in 1500 the SCTP specification, in network byte order. 1502 sre_assoc_id: sizeof (sctp_assoc_t) 1504 The association id field, holds the identifier for the association. 1505 All notifications for a given association have the same association 1506 identifier. For one-to-one style socket, this field is ignored. 1508 sre_data: variable 1510 This contains the ERROR chunk as defined in the SCTP specification 1511 RFC2960 [8] section 3.3.10. 1513 5.3.1.4 SCTP_SEND_FAILED 1515 If SCTP cannot deliver a message it may return the message as a 1516 notification. 1518 struct sctp_send_failed { 1519 uint16_t ssf_type; 1520 uint16_t ssf_flags; 1521 uint32_t ssf_length; 1522 uint32_t ssf_error; 1523 struct sctp_sndrcvinfo ssf_info; 1524 sctp_assoc_t ssf_assoc_id; 1525 uint8_t ssf_data[0]; 1526 }; 1527 ssf_type: 1529 It should be SCTP_SEND_FAILED. 1531 The flag value will take one of the following values 1533 SCTP_DATA_UNSENT - Indicates that the data was never put on 1534 the wire. 1536 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1537 Note that this does not necessarily mean that the 1538 data was (or was not) successfully delivered. 1540 ssf_length: 32 bits (unsigned integer) 1542 This field is the total length of the notification data, including 1543 the notification header and the payload in ssf_data. 1545 ssf_error: 16 bits (unsigned integer) 1547 This value represents the reason why the send failed, and if set, 1548 will be a SCTP protocol error code as defined in RFC2960 [8] section 1549 3.3.10. 1551 ssf_info: sizeof (struct sctp_sndrcvinfo) 1553 The original send information associated with the undelivered 1554 message. 1556 ssf_assoc_id: sizeof (sctp_assoc_t) 1558 The association id field, sf_assoc_id, holds the identifier for the 1559 association. All notifications for a given association have the same 1560 association identifier. For one-to-one style socket, this field is 1561 ignored. 1563 ssf_data: variable length 1565 The undelivered message, exactly as delivered by the caller to the 1566 original send*() call. 1568 5.3.1.5 SCTP_SHUTDOWN_EVENT 1570 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1571 inform the application that it should cease sending data. 1573 struct sctp_shutdown_event { 1574 uint16_t sse_type; 1575 uint16_t sse_flags; 1576 uint32_t sse_length; 1577 sctp_assoc_t sse_assoc_id; 1578 }; 1580 sse_type 1582 It should be SCTP_SHUTDOWN_EVENT 1584 sse_flags: 16 bits (unsigned integer) 1586 Currently unused. 1588 sse_length: 32 bits (unsigned integer) 1590 This field is the total length of the notification data, including 1591 the notification header. It will generally be sizeof (struct 1592 sctp_shutdown_event). 1594 sse_flags: 16 bits (unsigned integer) 1596 Currently unused. 1598 sse_assoc_id: sizeof (sctp_assoc_t) 1600 The association id field, holds the identifier for the association. 1601 All notifications for a given association have the same association 1602 identifier. For one-to-one style socket, this field is ignored. 1604 5.3.1.6 SCTP_ADAPTION_INDICATION 1606 When a peer sends a Adaption Layer Indication parameter , SCTP 1607 delivers this notification to inform the application that of the 1608 peers requested adaption layer. 1610 struct sctp_adaption_event { 1611 uint16_t sai_type; 1612 uint16_t sai_flags; 1613 uint32_t sai_length; 1614 uint32_t sai_adaption_ind; 1615 sctp_assoc_t sai_assoc_id; 1616 }; 1618 sai_type 1620 It should be SCTP_ADAPTION_INDICATION 1621 sai_flags: 16 bits (unsigned integer) 1623 Currently unused. 1625 sai_length: 32 bits (unsigned integer) 1627 This field is the total length of the notification data, including 1628 the notification header. It will generally be sizeof (struct 1629 sctp_adaption_event). 1631 sai_adaption_ind: 32 bits (unsigned integer) 1633 This field holds the bit array sent by the peer in the adaption layer 1634 indication parameter. The bits are in network byte order. 1636 sai_assoc_id: sizeof (sctp_assoc_t) 1638 The association id field, holds the identifier for the association. 1639 All notifications for a given association have the same association 1640 identifier. For one-to-one style socket, this field is ignored. 1642 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT 1644 When a receiver is engaged in a partial delivery of a message this 1645 notification will be used to indicate various events. 1647 struct sctp_pdapi_event { 1648 uint16_t pdapi_type; 1649 uint16_t pdapi_flags; 1650 uint32_t pdapi_length; 1651 uint32_t pdapi_indication; 1652 sctp_assoc_t pdapi_assoc_id; 1653 }; 1655 pdapi_type 1657 It should be SCTP_PARTIAL_DELIVERY_EVENT 1659 pdapi_flags: 16 bits (unsigned integer) 1661 Currently unused. 1663 pdapi_length: 32 bits (unsigned integer) 1665 This field is the total length of the notification data, including 1666 the notification header. It will generally be sizeof (struct 1667 sctp_pdapi_event). 1669 pdapi_indication: 32 bits (unsigned integer) 1671 This field holds the indication being sent to the application 1672 possible values include: 1674 SCTP_PARTIAL_DELIVERY_ABORTED 1676 pdapi_assoc_id: sizeof (sctp_assoc_t) 1678 The association id field, holds the identifier for the association. 1679 All notifications for a given association have the same association 1680 identifier. For one-to-one style socket, this field is ignored. 1682 5.4 Ancillary Data Considerations and Semantics 1684 Programming with ancillary socket data contains some subtleties and 1685 pitfalls, which are discussed below. 1687 5.4.1 Multiple Items and Ordering 1689 Multiple ancillary data items may be included in any call to 1690 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1691 items, or both. 1693 The ordering of ancillary data items (either by SCTP or another 1694 protocol) is not significant and is implementation-dependent, so 1695 applications must not depend on any ordering. 1697 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1698 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1699 sendmsg() or recvmsg() call. 1701 5.4.2 Accessing and Manipulating Ancillary Data 1703 Applications can infer the presence of data or ancillary data by 1704 examining the msg_iovlen and msg_controllen msghdr members, 1705 respectively. 1707 Implementations may have different padding requirements for ancillary 1708 data, so portable applications should make use of the macros 1709 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1710 RFC2292 [6] and your SCTP implementation's documentation for more 1711 information. Following is an example, from RFC2292 [6], 1712 demonstrating the use of these macros to access ancillary data: 1714 struct msghdr msg; 1715 struct cmsghdr *cmsgptr; 1717 /* fill in msg */ 1719 /* call recvmsg() */ 1721 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1722 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1723 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1724 u_char *ptr; 1726 ptr = CMSG_DATA(cmsgptr); 1727 /* process data pointed to by ptr */ 1728 } 1729 } 1731 5.4.3 Control Message Buffer Sizing 1733 The information conveyed via SCTP_SNDRCV events will often be 1734 fundamental to the correct and sane operation of the sockets 1735 application. This is particularly true of the one-to-many semantics, 1736 but also of the one-ton-one semantics. For example, if an 1737 application needs to send and receive data on different SCTP streams, 1738 SCTP_SNDRCV events are indispensable. 1740 Given that some ancillary data is critical, and that multiple 1741 ancillary data items may appear in any order, applications should be 1742 carefully written to always provide a large enough buffer to contain 1743 all possible ancillary data that can be presented by recvmsg(). If 1744 the buffer is too small, and crucial data is truncated, it may pose a 1745 fatal error condition. 1747 Thus it is essential that applications be able to deterministically 1748 calculate the maximum required buffer size to pass to recvmsg(). One 1749 constraint imposed on this specification that makes this possible is 1750 that all ancillary data definitions are of a fixed length. One way 1751 to calculate the maximum required buffer size might be to take the 1752 sum the sizes of all enabled ancillary data item structures, as 1753 calculated by CMSG_SPACE. For example, if we enabled 1754 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [6], we would calculate 1755 and allocate the buffer size as follows: 1757 size_t total; 1758 void *buf; 1760 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1761 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1763 buf = malloc(total); 1765 We could then use this buffer for msg_control on each call to 1766 recvmsg() and be assured that we would not lose any ancillary data to 1767 truncation. 1769 6. Common Operations for Both Styles 1771 6.1 send(), recv(), sendto(), recvfrom() 1773 Applications can use send() and sendto() to transmit data to the peer 1774 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1775 data from the peer. 1777 The syntax is: 1779 ssize_t send(int sd, const void *msg, size_t len, int flags); 1780 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1781 const struct sockaddr *to, socklen_t tolen); 1782 ssize_t recv(int sd, void *buf, size_t len, int flags); 1783 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1784 struct sockaddr *from, socklen_t *fromlen); 1786 sd - the socket descriptor of an SCTP endpoint. 1787 msg - the message to be sent. 1788 len - the size of the message or the size of buffer. 1789 to - one of the peer addresses of the association to be 1790 used to send the message. 1791 tolen - the size of the address. 1792 buf - the buffer to store a received message. 1793 from - the buffer to store the peer address used to send the 1794 received message. 1795 fromlen - the size of the from address 1796 flags - (described below). 1798 These calls give access to only basic SCTP protocol features. If 1799 either peer in the association uses multiple streams, or sends 1800 unordered data these calls will usually be inadequate, and may 1801 deliver the data in unpredictable ways. 1803 SCTP has the concept of multiple streams in one association. The 1804 above calls do not allow the caller to specify on which stream a 1805 message should be sent. The system uses stream 0 as the default 1806 stream for send() and sendto(). recv() and recvfrom() return data 1807 from any stream, but the caller can not distinguish the different 1808 streams. This may result in data seeming to arrive out of order. 1809 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1810 provide no indication. 1812 SCTP is message based. The msg buffer above in send() and sendto() 1813 is considered to be a single message. This means that if the caller 1814 wants to send a message which is composed by several buffers, the 1815 caller needs to combine them before calling send() or sendto(). 1816 Alternately, the caller can use sendmsg() to do that without 1817 combining them. recv() and recvfrom() cannot distinguish message 1818 boundaries. 1820 In receiving, if the buffer supplied is not large enough to hold a 1821 complete message, the receive call acts like a stream socket and 1822 returns as much data as will fit in the buffer. 1824 Note, the send() and recv() calls may not be used for a one-to-many 1825 style socket. 1827 Note, if an application calls a send function with no user data and 1828 no ancillary data the SCTP implementation should reject the request 1829 with an appropriate error message. An implementation is NOT allowed 1830 to send a Data chunk with no user data RFC2960 [8]. 1832 6.2 setsockopt(), getsockopt() 1834 Applications use setsockopt() and getsockopt() to set or retrieve 1835 socket options. Socket options are used to change the default 1836 behavior of sockets calls. They are described in Section 7 1838 The syntax is: 1840 ret = getsockopt(int sd, int level, int optname, void *optval, 1841 socklen_t *optlen); 1842 ret = setsockopt(int sd, int level, int optname, const void *optval, 1843 socklen_t optlen); 1845 sd - the socket descript. 1846 level - set to IPPROTO_SCTP for all SCTP options. 1847 optname - the option name. 1848 optval - the buffer to store the value of the option. 1849 optlen - the size of the buffer (or the length of the option 1850 returned). 1852 6.3 read() and write() 1854 Applications can use read() and write() to send and receive data to 1855 and from peer. They have the same semantics as send() and recv() 1856 except that the flags parameter cannot be used. 1858 Note, these calls, when used in the one-to-many style, may only be 1859 used with branched off socket descriptors (see Section 8.2). 1861 6.4 getsockname() 1863 Applications use getsockname() to retrieve the locally-bound socket 1864 address of the specified socket. This is especially useful if the 1865 caller let SCTP chose a local port. This call is for where the 1866 endpoint is not multi-homed. It does not work well with multi-homed 1867 sockets. See Section 8.5 for a multi-homed version of the call. 1869 The syntax is: 1871 int getsockname(int sd, struct sockaddr *address, 1872 socklen_t *len); 1874 sd - the socket descriptor to be queried. 1876 address - On return, one locally bound address (chosen by 1877 the SCTP stack) is stored in this buffer. If the 1878 socket is an IPv4 socket, the address will be IPv4. 1879 If the socket is an IPv6 socket, the address will 1880 be either an IPv6 or IPv4 address. 1882 len - The caller should set the length of address here. 1883 On return, this is set to the length of the returned 1884 address. 1886 If the actual length of the address is greater than the length of the 1887 supplied sockaddr structure, the stored address will be truncated. 1889 If the socket has not been bound to a local name, the value stored in 1890 the object pointed to by address is unspecified. 1892 7. Socket Options 1894 The following sub-section describes various SCTP level socket options 1895 that are common to both styles. SCTP associations can be 1896 multi-homed. Therefore, certain option parameters include a 1897 sockaddr_storage structure to select which peer address the option 1898 should be applied to. 1900 For the one-to-many style sockets, an sctp_assoc_t structure 1901 (association ID) is used to identify the the association instance 1902 that the operation affects. So it must be set when using this style. 1904 For the one-to-one style sockets and branched off one-to-many style 1905 sockets (see Section 8.2) this association ID parameter is ignored. 1907 Note that socket or IP level options are set or retrieved per socket. 1908 This means that for one-to-many style sockets, those options will be 1909 applied to all associations belonging to the socket. And for 1910 one-to-one style, those options will be applied to all peer addresses 1911 of the association controlled by the socket. Applications should be 1912 very careful in setting those options. 1914 For some IP stacks getsockopt() is read-only; so a new interface will 1915 be needed when information must be passed both in to and out of the 1916 SCTP stack. The syntax for sctp_opt_info() is, 1918 int sctp_opt_info(int sd, 1919 sctp_assoc_t id, 1920 int opt, 1921 void *arg, 1922 socklen_t *size); 1924 The sctp_opt_info() call is a replacement for getsockopt() only and 1925 will not set any options associated with the specified socket. A 1926 setsockopt() must be used to set any writeable option. 1928 For one-to-many style sockets, id specifies the association to query. 1929 For one-to-one style sockets, id is ignored. 1931 opt specifies which SCTP socket option to get. It can get any socket 1932 option currently supported that requests information (either 1933 read/write options or read only) such as: 1935 SCTP_RTOINFO 1936 SCTP_ASSOCINFO 1937 SCTP_DEFAULT_SEND_PARAM 1938 SCTP_GET_PEER_ADDR_INFO 1939 SCTP_PRIMARY_ADDR 1940 SCTP_PEER_ADDR_PARAMS 1941 SCTP_STATUS 1942 SCTP_AUTH_CHUNKS 1943 SCTP_AUTH_SECRET 1945 arg is an option-specific structure buffer provided by the caller. 1946 See Section 8.5) subsections for more information on these options 1947 and option-specific structures. 1949 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1950 sets errno to the appropriate error code. 1952 All options that support specific settings on an association by 1953 filling in either an association id variable or a sockaddr_storage 1954 SHOULD also support setting of the same value for the entire endpoint 1955 (i.e. future associations). To accomplish this the following logic 1956 is used when setting one of these options: 1958 a) If an address is specified via a sockaddr_storage that is included 1959 in the structure, the address is used to lookup the association 1960 and the settings are applied to the specific address (if 1961 appropriate) or to the entire association. 1962 b) If an association identification is filled in but not a 1963 sockaddr_storage (if present), the association is found using the 1964 association identification and the settings should be applied to 1965 the entire association (since a specific address is not 1966 specified). Note this also applies to options that hold an 1967 association identification in their structure but do not have a 1968 sockaddr_storage field. 1969 c) If neither the sockaddr_storage or association identification is 1970 set i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 1971 the association identification is 0, the settings are a default 1972 and to be applied to the endpoint (all future associations). 1974 7.1 Read / Write Options 1976 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1978 The protocol parameters used to initialize and bound retransmission 1979 timeout (RTO) are tunable. See RFC2960 [8] for more information on 1980 how these parameters are used in RTO calculation. 1982 The following structure is used to access and modify these 1983 parameters: 1985 struct sctp_rtoinfo { 1986 sctp_assoc_t srto_assoc_id; 1987 uint32_t srto_initial; 1988 uint32_t srto_max; 1989 uint32_t srto_min; 1990 }; 1991 srto_initial - This contains the initial RTO value. 1992 srto_max and srto_min - These contain the maximum and minimum bounds 1993 for all RTOs. 1994 srto_assoc_id - (one-to-many style socket) This is filled in 1995 the application, and identifies the association 1996 for this query. If this parameter is '0' 1997 (on a one-to-many style socket), then the change 1998 effects the entire endpoint. 2000 All parameters are time values, in milliseconds. A value of 0, when 2001 modifying the parameters, indicates that the current value should not 2002 be changed. 2004 To access or modify these parameters, the application should call 2005 getsockopt or setsockopt() respectively with the option name 2006 SCTP_RTOINFO. 2008 7.1.2 Association Parameters (SCTP_ASSOCINFO) 2010 This option is used to both examine and set various association and 2011 endpoint parameters. 2013 See RFC2960 [8] for more information on how this parameter is used. 2014 The peer address parameter is ignored for one-to-one style socket. 2016 The following structure is used to access and modify this parameters: 2018 struct sctp_assocparams { 2019 sctp_assoc_t sasoc_assoc_id; 2020 uint16_t sasoc_asocmaxrxt; 2021 uint16_t sasoc_number_peer_destinations; 2022 uint32_t sasoc_peer_rwnd; 2023 uint32_t sasoc_local_rwnd; 2024 uint32_t sasoc_cookie_life; 2025 }; 2026 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2027 to make for the association. 2029 sasoc_number_peer_destinations - This is the number of destination 2030 addresses that the peer has. 2031 sasoc_peer_rwnd - This holds the current value of the peers 2032 rwnd (reported in the last SACK) minus any 2033 outstanding data (i.e. data inflight). 2034 sasoc_local_rwnd - This holds the last reported rwnd that was 2035 sent to the peer. 2036 sasoc_cookie_life - This is the associations cookie life value 2037 used when issuing cookies. 2038 sasoc_assoc_id - (one-to-many style socket) This is filled in the 2039 application, and identifies the association 2040 for this query. 2042 This information may be examined for either the endpoint or a 2043 specific association. To examine a endpoints default parameters the 2044 association id (sasoc_assoc_id) should must be set to the value '0'. 2045 The values of the sasoc_peer_rwnd is meaningless when examining 2046 endpoint information. 2048 All parameters are time values, in milliseconds. A value of 0, when 2049 modifying the parameters, indicates that the current value should not 2050 be changed. 2052 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2053 on either an endpoint or association basis. The rwnd and destination 2054 counts (sasoc_number_peer_destinations, 2055 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2056 placed in these is ignored. 2058 To access or modify these parameters, the application should call 2059 getsockopt or setsockopt() respectively with the option name 2060 SCTP_ASSOCINFO. 2062 The maximum number of retransmissions before an address is considered 2063 unreachable is also tunable, but is address-specific, so it is 2064 covered in a separate option. If an application attempts to set the 2065 value of the association maximum retransmission parameter to more 2066 than the sum of all maximum retransmission parameters, setsockopt() 2067 shall return an error. The reason for this, from RFC2960 [8] section 2068 8.2: 2070 Note: When configuring the SCTP endpoint, the user should avoid 2071 having the value of 'Association.Max.Retrans' larger than the 2072 summation of the 'Path.Max.Retrans' of all the destination addresses 2073 for the remote endpoint. Otherwise, all the destination addresses 2074 may become inactive while the endpoint still considers the peer 2075 endpoint reachable. 2077 7.1.3 Initialization Parameters (SCTP_INITMSG) 2079 Applications can specify protocol parameters for the default 2080 association initialization. The structure used to access and modify 2081 these parameters is defined in Section 5.2.1). The option name 2082 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2084 Setting initialization parameters is effective only on an unconnected 2085 socket (for one-to-many style sockets only future associations are 2086 effected by the change). With one-to-one style sockets, this option 2087 is inherited by sockets derived from a listener socket. 2089 7.1.4 SO_LINGER 2091 An application using the one-to-one style socket can use this option 2092 to perform the SCTP ABORT primitive. The linger option structure is: 2094 struct linger { 2095 int l_onoff; /* option on/off */ 2096 int l_linger; /* linger time */ 2097 }; 2099 To enable the option, set l_onoff to 1. If the l_linger value is set 2100 to 0, calling close() is the same as the ABORT primitive. If the 2101 value is set to a negative value, the setsockopt() call will return 2102 an error. If the value is set to a positive value linger_time, the 2103 close() can be blocked for at most linger_time ms. If the graceful 2104 shutdown phase does not finish during this period, close() will 2105 return but the graceful shutdown phase continues in the system. 2107 Note, this is a socket level option NOT an SCTP level option. So 2108 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2109 setsockopt() call. 2111 7.1.5 SCTP_NODELAY 2113 Turn on/off any Nagle-like algorithm. This means that packets are 2114 generally sent as soon as possible and no unnecessary delays are 2115 introduced, at the cost of more packets in the network. Expects an 2116 integer boolean flag. 2118 7.1.6 SO_RCVBUF 2120 Sets receive buffer size in octets. For SCTP one-to-one style 2121 sockets, this controls the receiver window size. For one-to-many 2122 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF 2123 (see Section 3.4). If the implementation defines HAVE_SCTP_MULTIBUF 2124 as 1, this controls the receiver window size for each association 2125 bound to the socket descriptor. If the implementation defines 2126 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive 2127 buffer for the whole socket. The call expects an integer. 2129 7.1.7 SO_SNDBUF 2131 Sets send buffer size. For SCTP one-to-one style sockets, this 2132 controls the amount of data SCTP may have waiting in internal buffers 2133 to be sent. This option therefore bounds the maximum size of data 2134 that can be sent in a single send call. For one-to-many style 2135 sockets, the effect is the same, except that it applies to one or all 2136 associations (see Section 3.4) bound to the socket descriptor 2137 used in the setsockopt() or getsockopt() call. The option applies to 2138 each association's window size separately. The call expects an 2139 integer. 2141 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 2143 This socket option is applicable to the one-to-many style socket 2144 only. When set it will cause associations that are idle for more 2145 than the specified number of seconds to automatically close. An 2146 association being idle is defined as an association that has NOT sent 2147 or received user data. The special value of '0' indicates that no 2148 automatic close of any associations should be performed, this is the 2149 default value. The option expects an integer defining the number of 2150 seconds of idle time before an association is closed. 2152 An application using this option should enable receiving the 2153 association change notification. This is the only mechanism an 2154 application is informed about the closing of an association. After 2155 an association is closed, the association ID assigned to it can be 2156 reused. An application should be aware of this to avoid the possible 2157 problem of sending data to an incorrect peer end point. 2159 7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2161 Requests that the peer mark the enclosed address as the association 2162 primary. The enclosed address must be one of the association's 2163 locally bound addresses. The following structure is used to make a 2164 set primary request: 2166 struct sctp_setpeerprim { 2167 sctp_assoc_t sspp_assoc_id; 2168 struct sockaddr_storage sspp_addr; 2169 }; 2171 sspp_addr The address to set as primary 2172 sspp_assoc_id (one-to-many style socket) This is filled in by the 2173 application, and identifies the association 2174 for this request. 2176 This functionality is optional. Implementations that do not support 2177 this functionality should return EOPNOTSUPP. 2179 7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) 2181 Requests that the local SCTP stack use the enclosed peer address as 2182 the association primary. The enclosed address must be one of the 2183 association peer's addresses. The following structure is used to 2184 make a set peer primary request: 2186 struct sctp_setprim { 2187 sctp_assoc_t ssp_assoc_id; 2188 struct sockaddr_storage ssp_addr; 2189 }; 2190 ssp_addr The address to set as primary 2191 ssp_assoc_id (one-to-many style socket) This is filled in by the 2192 application, and identifies the association 2193 for this request. 2195 7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) 2197 Requests that the local endpoint set the specified Adaption Layer 2198 Indication parameter for all future INIT and INIT-ACK exchanges. 2200 struct sctp_setadaption { 2201 uint32_t ssb_adaption_ind; 2202 }; 2204 ssb_adaption_ind The adaption layer indicator that will be included 2205 in any outgoing Adaption Layer Indication 2206 parameter. 2208 7.1.12 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2210 This option is a on/off flag and is passed an integer where a 2211 non-zero is on and a zero is off. If enabled no SCTP message 2212 fragmentation will be performed. Instead if a message being sent 2213 exceeds the current PMTU size, the message will NOT be sent and 2214 instead a error will be indicated to the user. 2216 7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2218 Applications can enable or disable heartbeats for any peer address of 2219 an association, modify an address's heartbeat interval, force a 2220 heartbeat to be sent immediately, and adjust the address's maximum 2221 number of retransmissions sent before an address is considered 2222 unreachable. The following structure is used to access and modify an 2223 address's parameters: 2225 struct sctp_paddrparams { 2226 sctp_assoc_t spp_assoc_id; 2227 struct sockaddr_storage spp_address; 2228 uint32_t spp_hbinterval; 2229 uint16_t spp_pathmaxrxt; 2230 uint32_t spp_pathmtu; 2231 uint32_t spp_sackdelay; 2232 uint32_t spp_flags; 2233 }; 2235 spp_assoc_id - (one-to-many style socket) This is filled in the 2236 application, and identifies the association for 2237 this query. 2238 spp_address - This specifies which address is of interest. 2239 spp_hbinterval - This contains the value of the heartbeat interval, 2240 in milliseconds. If a value of zero 2241 is present in this field then no changes are to 2242 be made to this parameter. 2243 spp_pathmaxrxt - This contains the maximum number of 2244 retransmissions before this address shall be 2245 considered unreachable. If a value of zero 2246 is present in this field then no changes are to 2247 be made to this parameter. 2248 spp_pathmtu - When Path MTU discovery is disabled the value 2249 specified here will be the "fixed" path mtu. 2250 Note that if the spp_address field is empty 2251 then all associations on this address will 2252 have this fixed path mtu set upon them. 2254 spp_sackdelay - When delayed sack is enabled, this value specifies 2255 the number of milliseconds that sacks will be delayed 2256 for. This value will apply to all addresses of an 2257 association if the spp_address field is empty. Note 2258 also, that if delayed sack is enabled and this 2259 value is set to 0, no change is made to the last 2260 recorded delayed sack timer value. 2262 spp_flags - These flags are used to control various features 2263 on an association. The flag field may contain 2264 zero or more of the following options. 2266 SPP_HB_ENABLED - Enable heartbeats on the 2267 specified address. Note that if the address 2268 field is empty all addresses for the association 2269 have heartbeats enabled upon them. 2271 SPP_HB_DISABLED - Disable heartbeats on the 2272 speicifed address. Note that if the address 2273 field is empty all addresses for the association 2274 will have their heartbeats disabled. Note also 2275 that SPP_HB_ENABLED and SPP_HB_DISABLED are 2276 mutually exclusive, only one of these two should 2277 be specified. Enabling both fields will have 2278 undetermined results. 2280 SPP_PMTUD_ENABLED - This field will enable PMTU 2281 discovery upon the specified address. Note that 2282 if the address feild is empty then all addresses 2283 on the association are effected. 2285 SPP_PMTUD_DISABLED - This field will disable PMTU 2286 discovery upon the specified address. Note that 2287 if the address feild is empty then all addresses 2288 on the association are effected. Not also that 2289 SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually 2290 exclusive. Enabling both will have undetermined 2291 results. 2293 SPP_SACKDELAY_ENABLED - Setting this flag turns 2294 on delayed sack. The time specified in spp_sackdelay 2295 is used to specify the sack delay for this address. Note 2296 that if spp_address is empty then all addresses will 2297 enable delayed sack and take on the sack delay 2298 value specified in spp_sackdelay. 2300 SPP_SACKDELAY_DISABLED - Setting this flag turns 2301 off delayed sack. If the spp_address field is blank then 2302 delayed sack is disabled for the entire association. Note 2303 also that this field is mutually exclusive to 2304 SPP_SACKDELAY_ENABLED, setting both will have undefined 2305 results. 2307 To read or modify these parameters, the application should call 2308 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2310 7.1.14 Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 2312 Applications that wish to use the sendto() system call may wish to 2313 specify a default set of parameters that would normally be supplied 2314 through the inclusion of ancillary data. This socket option allows 2315 such an application to set the default sctp_sndrcvinfo structure. 2316 The application that wishes to use this socket option simply passes 2317 in to this call the sctp_sndrcvinfo structure defined in 2318 Section 5.2.2) The input parameters accepted by this call include 2319 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, 2320 sinfo_timetolive. The user must set the sinfo_assoc_id field to 2321 identify the association to affect if the caller is using the 2322 one-to-many style. 2324 7.1.15 Set notification and ancillary events (SCTP_EVENTS) 2326 This socket option is used to specify various notifications and 2327 ancillary data the user wishes to receive. Please see Section 7.3) 2328 for a full description of this option and its usage. 2330 7.1.16 Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2332 This socket option is a boolean flag which turns on or off mapped V4 2333 addresses. If this option is turned on and the socket is type 2334 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2335 If this option is turned off, then no mapping will be done of V4 2336 addresses and a user will receive both PF_INET6 and PF_INET type 2337 addresses on the socket. 2339 By default this option is turned on and expects an integer to be 2340 passed where non-zero turns on the option and zero turns off the 2341 option. 2343 7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) 2345 This socket option specifies the maximum size to put in any outgoing 2346 SCTP DATA chunk. If a message is larger than this size it will be 2347 fragmented by SCTP into the specified size. Note that the underlying 2348 SCTP implementation may fragment into smaller sized chunks when the 2349 PMTU of the underlying association is smaller than the value set by 2350 the user. The option expects an integer. 2352 The default value for this option is '0' which indicates the user is 2353 NOT limiting fragmentation and only the PMTU will effect SCTP's 2354 choice of DATA chunk size. 2356 7.1.18 Set/Get the list of chunks that must be authenticated 2357 (SCTP_AUTH_CHUNKS) 2359 This options gets or sets a list of chunks that the user is 2360 requesting to be received only in an authenticated way. Changes to 2361 this list will only effect associations that have not been formed. 2363 struct sctp_authchunks { 2364 uint8_t sauth_chunks[]; 2365 }; 2367 sauth_chunks - This parameter contains an array of chunks 2368 that the user is requesting to be authenticated. 2370 7.1.19 Set/Get the current authentication shared secret 2371 (SCTP_AUTH_SECRET) 2373 This option will get or set the shared secret to be used with any 2374 authentication parameters. 2376 struct sctp_authsecrets { 2377 sctp_assoc_t sca_assoc_id; 2378 uint8_t sca_secret[]; 2379 }; 2381 sca_assoc_id - This parameter, if non-zero, indicates what 2382 association that the shared secret is being set 2383 upon. Note that if this element contains zero, then 2384 the secret is set upon the endpoint and all future 2385 associations will use this secret (if not changed by 2386 subsequent calls to SCTP_AUTH_SECRET). 2388 sca_secret - This parameter contains an array of bytes 2389 that is to be used by the endpoint (or association) 2390 as the shared secret. 2392 7.1.20 Get the list of chunks that peer requires to be authenticated 2393 (SCTP_PEER_AUTH_CHUNKS) 2395 This options gets a list of chunks for a specified association that 2396 the peer requires to be authenticated. The requesting to be received 2397 only in an authenticated way. Changes to this list will only effect 2398 associations that have not been formed. 2400 struct sctp_authchunks { 2401 sctp_assoc_t gpauth_assoc_id; 2402 uint8_t gpauth_chunks[]; 2403 }; 2405 sca_assoc_id - This parameter, indicates for which association the 2406 user is requesting the list of peer authenticated 2407 chunks. 2409 gputh_chunks - This parameter contains an array of chunks 2410 that the peer is requesting to be authenticated. 2412 7.2 Read-Only Options 2414 7.2.1 Association Status (SCTP_STATUS) 2416 Applications can retrieve current status information about an 2417 association, including association state, peer receiver window size, 2418 number of unacked data chunks, and number of data chunks pending 2419 receipt. This information is read-only. The following structure is 2420 used to access this information: 2422 struct sctp_status { 2423 sctp_assoc_t sstat_assoc_id; 2424 int32_t sstat_state; 2425 uint32_t sstat_rwnd; 2426 uint16_t sstat_unackdata; 2427 uint16_t sstat_penddata; 2428 uint16_t sstat_instrms; 2429 uint16_t sstat_outstrms; 2430 uint32_t sstat_fragmentation_point; 2431 struct sctp_paddrinfo sstat_primary; 2432 }; 2434 sstat_state - This contains the association's current state one 2435 of the following values: 2437 SCTP_CLOSED 2438 SCTP_BOUND 2439 SCTP_LISTEN 2440 SCTP_COOKIE_WAIT 2441 SCTP_COOKIE_ECHOED 2442 SCTP_ESTABLISHED 2443 SCTP_SHUTDOWN_PENDING 2444 SCTP_SHUTDOWN_SENT 2445 SCTP_SHUTDOWN_RECEIVED 2446 SCTP_SHUTDOWN_ACK_SENT 2448 sstat_rwnd - This contains the association peer's current 2449 receiver window size. 2450 sstat_unackdata - This is the number of unacked data chunks. 2451 sstat_penddata - This is the number of data chunks pending receipt. 2452 sstat_primary - This is information on the current primary peer 2453 address. 2454 sstat_assoc_id - (one-to-many style socket) This holds the an 2455 identifier for the association. All 2456 notifications for a given association 2457 have the same association identifier. 2459 sstat_instrms - The number of streams that the peer will 2460 be using inbound. 2462 sstat_outstrms - The number of streams that the endpoint is 2463 allowed to use outbound. 2465 sstat_fragmentation_point - The size at which SCTP fragmentation 2466 will occur. 2468 To access these status values, the application calls getsockopt() 2469 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2470 ignored for one-to-one style socket. 2472 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2474 Applications can retrieve information about a specific peer address 2475 of an association, including its reachability state, congestion 2476 window, and retransmission timer values. This information is 2477 read-only. The following structure is used to access this 2478 information: 2480 struct sctp_paddrinfo { 2481 sctp_assoc_t spinfo_assoc_id; 2482 struct sockaddr_storage spinfo_address; 2483 int32_t spinfo_state; 2484 uint32_t spinfo_cwnd; 2485 uint32_t spinfo_srtt; 2486 uint32_t spinfo_rto; 2487 uint32_t spinfo_mtu; 2488 }; 2490 spinfo_address - This is filled in the application, and contains 2491 the peer address of interest. 2493 On return from getsockopt(): 2495 spinfo_state - This contains the peer addresses's state (either 2496 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifer 2497 SCTP_UNCONFIRMED) 2499 spinfo_cwnd - This contains the peer addresses's current congestion 2500 window. 2501 spinfo_srtt - This contains the peer addresses's current smoothed 2502 round-trip time calculation in milliseconds. 2503 spinfo_rto - This contains the peer addresses's current 2504 retransmission timeout value in milliseconds. 2505 spinfo_mtu - The current P-MTU of this address. 2506 spinfo_assoc_id - (one-to-many style socket) This is filled in 2507 the application, and identifies the 2508 association for this query. 2510 To retrieve this information, use sctp_opt_info() with the 2511 SCTP_GET_PEER_ADDR_INFO options. 2513 7.3 Ancillary Data and Notification Interest Options 2515 Applications can receive per-message ancillary information and 2516 notifications of certain SCTP events with recvmsg(). 2518 The following optional information is available to the application: 2520 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 2521 stream number, TSN, SSN, etc. described in Section 5.2.2) 2522 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in 2523 Section 5.3.1.1) 2524 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in 2525 Section 5.3.1.2) 2526 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in 2527 Section 5.3.1.4) 2529 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in 2530 Section 5.3.1.3) 2531 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in 2532 Section 5.3.1.5) 2533 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 2534 (described in Section 5.3.1.7) 2535 8. SCTP_ADAPTION_INDICATION (sctp_adaption_layer_event): (described 2536 in Section 5.3.1.6) 2538 To receive any ancillary data or notifications, first the application 2539 registers it's interest by calling the SCTP_EVENTS setsockopt() with 2540 the following structure. 2542 struct sctp_event_subscribe{ 2543 uint8_t sctp_data_io_event; 2544 uint8_t sctp_association_event; 2545 uint8_t sctp_address_event; 2546 uint8_t sctp_send_failure_event; 2547 uint8_t sctp_peer_error_event; 2548 uint8_t sctp_shutdown_event; 2549 uint8_t sctp_partial_delivery_event; 2550 uint8_t sctp_adaption_layer_event; 2551 }; 2553 sctp_data_io_event - Setting this flag to 1 will cause the reception 2554 of SCTP_SNDRCV information on a per message basis. The application 2555 will need to use the recvmsg() interface so that it can receive the 2556 event information contained in the msg_control field. Please see 2557 Section 5.2 for further details. Setting the flag to 0 will disable 2558 reception of the message control information. 2560 sctp_association_event - Setting this flag to 1 will enable the 2561 reception of association event notifications. Setting the flag to 0 2562 will disable association event notifications. For more information 2563 on event notifications please see Section 5.3. 2565 sctp_address_event - Setting this flag to 1 will enable the reception 2566 of address event notifications. Setting the flag to 0 will disable 2567 address event notifications. For more information on event 2568 notifications please see Section 5.3. 2570 sctp_send_failure_event - Setting this flag to 1 will enable the 2571 reception of send failure event notifications. Setting the flag to 0 2572 will disable send failure event notifications. For more information 2573 on event notifications please see Section 5.3. 2575 sctp_peer_error_event - Setting this flag to 1 will enable the 2576 reception of peer error event notifications. Setting the flag to 0 2577 will disable peer error event notifications. For more information on 2578 event notifications please see Section 5.3. 2580 sctp_shutdown_event - Setting this flag to 1 will enable the 2581 reception of shutdown event notifications. Setting the flag to 0 2582 will disable shutdown event notifications. For more information on 2583 event notifications please see Section 5.3. 2585 sctp_partial_delivery_event - Setting this flag to 1 will enable the 2586 reception of partial delivery notifications. Setting the flag to 0 2587 will disable partial delivery event notifications. For more 2588 information on event notifications please see Section 5.3. 2590 sctp_adaption_layer_event - Setting this flag to 1 will enable the 2591 reception of adaption layer notifications. Setting the flag to 0 2592 will disable adaption layer event notifications. For more 2593 information on event notifications please see Section 5.3. 2595 An example where an application would like to receive data io events 2596 and association events but no others would be as follows: 2598 { 2599 struct sctp_event_subscribe event; 2601 memset(&event,0,sizeof(event)); 2603 event.sctp_data_io_event = 1; 2604 event.sctp_association_event = 1; 2606 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2607 } 2609 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2610 receives ancillary data and notifications for ALL associations bound 2611 to the file descriptor. For one-to-one style SCTP sockets, the 2612 caller receives ancillary data and notifications for only the single 2613 association bound to the file descriptor. 2615 By default both the one-to-one style and one-to-many style socket has 2616 all options off. 2618 8. New Interfaces 2620 Depending on the system, the following interface can be implemented 2621 as a system call or library function. 2623 8.1 sctp_bindx() 2625 The syntax of sctp_bindx() is, 2627 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt, 2628 int flags); 2630 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 2631 If the sd is an IPv6 socket, the addresses passed can either be IPv4 2632 or IPv6 addresses. 2634 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2635 Section 3.1.2 for this usage. 2637 addrs is a pointer to an array of one or more socket addresses. Each 2638 address is contained in its appropriate structure. For an IPv6 2639 socket, an array of sockaddr_in6 would be returned. For a IPv4 2640 socket, an array of sockaddr_in would be returned. The caller 2641 specifies the number of addresses in the array with addrcnt. Note 2642 that the wildcard addresses cannot be used with this function, doing 2643 so will result in an error. 2645 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2646 -1, and sets errno to the appropriate error code. 2648 For SCTP, the port given in each socket address must be the same, or 2649 sctp_bindx() will fail, setting errno to EINVAL. 2651 The flags parameter is formed from the bitwise OR of zero or more of 2652 the following currently defined flags: 2654 SCTP_BINDX_ADD_ADDR 2656 SCTP_BINDX_REM_ADDR 2658 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2659 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 2660 addresses from the association. The two flags are mutually 2661 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 2662 caller may not remove all addresses from an association; sctp_bindx() 2663 will reject such an attempt with EINVAL. 2665 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2666 additional addresses with an endpoint after calling bind(). Or use 2667 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2668 socket is associated with so that no new association accepted will be 2669 associated with those addresses. If the endpoint supports dynamic 2670 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 2671 endpoint to send the appropriate message to the peer to change the 2672 peers address lists. 2674 Adding and removing addresses from a connected association is 2675 optional functionality. Implementations that do not support this 2676 functionality should return EOPNOTSUPP. 2678 8.2 Branched-off Association 2680 After an association is established on a one-to-many style socket, 2681 the application may wish to branch off the association into a 2682 separate socket/file descriptor. 2684 This is particularly desirable when, for instance, the application 2685 wishes to have a number of sporadic message senders/receivers remain 2686 under the original one-to-many style socket but branch off those 2687 associations carrying high volume data traffic into their own 2688 separate socket descriptors. 2690 The application uses sctp_peeloff() call to branch off an association 2691 into a separate socket (Note the semantics are somewhat changed from 2692 the traditional one-to-one style accept() call). Note that the new 2693 socket is a one-to-one style socket. Thus it will be confined to 2694 operations allowed for a one-to-one style socket. 2696 The syntax is: 2698 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id); 2700 the new socket descriptor representing the branched-off 2701 association. 2702 the original one-to-many style socket descriptor returned from the 2703 socket() system call (see Section 3.1.1). 2704 the specified identifier of the association that is to be branched 2705 off to a separate file descriptor (Note, in a traditional 2706 one-to-one style accept() call, this would be an out parameter, 2707 but for the one-to-many style call, this is an in parameter). 2709 8.3 sctp_getpaddrs() 2711 sctp_getpaddrs() returns all peer addresses in an association. The 2712 syntax is, 2713 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2714 struct sockaddr **addrs); 2716 On return, addrs will point to an array dynamically allocated 2717 sockaddr structures of the appropriate type for the socket type. The 2718 caller should use sctp_freepaddrs() to free the memory. Note that 2719 the in/out parameter addrs must not be NULL. 2721 If sd is an IPv4 socket, the addresses returned will be all IPv4 2722 addresses. If sd is an IPv6 socket, the addresses returned can be a 2723 mix of IPv4 or IPv6 addresses. 2725 For one-to-many style sockets, id specifies the association to query. 2726 For one-to-one style sockets, id is ignored. 2728 On success, sctp_getpaddrs() returns the number of peer addresses in 2729 the association. If there is no association on this socket, 2730 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2731 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 2732 is undefined. 2734 8.4 sctp_freepaddrs() 2736 sctp_freepaddrs() frees all resources allocated by 2737 sctp_getpaddrs(). Its syntax is, 2739 void sctp_freepaddrs(struct sockaddr *addrs); 2741 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2743 8.5 sctp_getladdrs() 2745 sctp_getladdrs() returns all locally bound address(es) on a socket. 2746 The syntax is, 2748 int sctp_getladdrs(int sd, sctp_assoc_t id, 2749 struct sockaddr **ss); 2751 On return, addrs will point to a dynamically allocated array of 2752 sockaddr structures of the appropriate type for the socket type. The 2753 caller should use sctp_freeladdrs() to free the memory. Note that 2754 the in/out parameter addrs must not be NULL. 2756 If sd is an IPv4 socket, the addresses returned will be all IPv4 2757 addresses. If sd is an IPv6 socket, the addresses returned can be a 2758 mix of IPv4 or IPv6 addresses. 2760 For one-to-many style sockets, id specifies the association to query. 2761 For one-to-one style sockets, id is ignored. 2763 If the id field is set to the value '0' then the locally bound 2764 addresses are returned without regard to any particular association. 2766 On success, sctp_getladdrs() returns the number of local addresses 2767 bound to the socket. If the socket is unbound, sctp_getladdrs() 2768 returns 0, and the value of *addrs is undefined. If an error occurs, 2769 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2771 8.6 sctp_freeladdrs() 2773 sctp_freeladdrs() frees all resources allocated by 2774 sctp_getladdrs(). Its syntax is, 2776 void sctp_freeladdrs(struct sockaddr *addrs); 2778 addrs is the array of peer addresses returned by sctp_getladdrs(). 2780 8.7 sctp_sendmsg() 2782 An implementation may provide a library function (or possibly system 2783 call) to assist the user with the advanced features of SCTP. 2785 sctp_sendmsg(). Its syntax is, 2787 ssize_t sctp_sendmsg(int sd, 2788 const void *msg, 2789 size_t len, 2790 const struct sockaddr *to, 2791 socklen_t tolen, 2792 uint32_t ppid, 2793 uint32_t flags, 2794 uint16_t stream_no, 2795 uint32_t timetolive, 2796 uint32_t context) 2798 sd - is the socket descriptor 2799 msg - is the message to be sent. 2800 len - is the length of the message. 2801 to - is the destination address of the message. 2802 tolen - is the length of the destination address. 2803 ppid - is the same as sinfo_ppid (see section 5.2.2) 2804 flags - is the same as sinfo_flags (see section 5.2.2) 2805 stream_no - is the same as sinfo_stream (see section 5.2.2) 2806 timetolive - is the same as sinfo_timetolive (see section 5.2.2) 2807 context - is the same as sinfo_context (see section 5.2.2) 2809 8.8 sctp_recvmsg() 2811 An implementation may provide a library function (or possibly system 2812 call) to assist the user with the advanced features of SCTP. Note 2813 that in order for the sctp_sndrcvinfo structure to be filled in by 2814 sctp_recvmsg() the caller must enable the sctp_data_io_events with 2815 the SCTP_EVENTS option. 2817 sctp_recvmsg(). Its syntax is, 2819 ssize_t sctp_recvmsg(int sd, 2820 void *msg, 2821 size_t len, 2822 struct sockaddr *from, 2823 socklen_t *fromlen 2824 struct sctp_sndrcvinfo *sinfo 2825 int *msg_flags) 2827 sd - is the socket descriptor 2828 msg - is a message buffer to be filled. 2829 len - is the length of the message buffer. 2830 from - is a pointer to a address to be filled with 2831 the sender of this messages address. 2832 fromlen - is the from length. 2833 sinfo - A pointer to a sctp_sndrcvinfo structure 2834 to be filled upon receipt of the message. 2835 msg_flags - A pointer to a integer to be filled with 2836 any message flags (e.g. MSG_NOTIFICATION). 2838 8.9 sctp_connectx() 2840 An implementation may provide a library function (or possibly system 2841 call) to assist the user with associating to an endpoint that is 2842 multi-homed. Much like sctp_bindx() this call allows a caller to 2843 specify multiple addresses at which a peer can be reached. The way 2844 the SCTP stack uses the list of addresses to set up the association 2845 is implementation dependant. This function only specifies that the 2846 stack will try to make use of all the addresses in the list when 2847 needed. 2849 Note that the list of addresses passed in is only used for setting up 2850 the association. It does not necessarily equal the set of addresses 2851 the peer uses for the resulting association. If the caller wants to 2852 find out the set of peer addresses, it must use sctp_getpaddrs() to 2853 retrieve them after the association has been set up. 2855 sctp_connectx(). Its syntax is, 2857 int sctp_connectx(int sd, 2858 struct sockaddr *addrs, 2859 int addrcnt) 2861 sd - is the socket descriptor 2862 addrs - is an array of addresses. 2864 addrcnt - is the number of addresses in the array. 2866 8.10 sctp_send() 2868 An implementation may provide another alternative function or system 2869 call to assist an application with the sending of data without the 2870 use of the CMSG header structures. The function takes the following 2871 form: 2873 sctp_send(). Its syntax is, 2875 int sctp_send(int sd, 2876 const void *msg, 2877 size_t len, 2878 const struct sctp_sndrcvinfo *sinfo, 2879 int flags); 2881 sd - is the socket descriptor 2882 msg - The message to be sent 2883 len - The length of the message 2884 sinfo - A pointer to a sctp_sndrcvinfo struture used 2885 as described in 5.2.2 for a sendmsg call. 2886 flags - is used in the same format as the sendmsg call 2887 flags (e.g. MSG_DONTROUTE). 2889 This function call may also be used to terminate an association using 2890 an association identification by setting the sinfo.sinfo_flags to 2891 MSG_EOF and the sinfo.sinf_associd to the association that needs to 2892 be terminated. In such a case the len of the message would be zero. 2894 8.11 sctp_sendx() 2896 An implementation may provide another alternative function or system 2897 call to assist an application with the sending of data without the 2898 use of the CMSG header structures that also gives a list of 2899 addresses. The list of addresses is provided for implicit 2900 association setup. In such a case the list of addresses serves the 2901 same purpose as the addresses given in sctp_connectx (see 2902 Section 8.9). 2904 sctp_sendx(). Its syntax is, 2906 int sctp_sendx(int sd, 2907 const void *msg, 2908 size_t len, 2909 struct sockaddr *addrs, 2910 int addrcnt, 2911 struct sctp_sndrcvinfo *sinfo, 2912 int flags); 2914 sd - is the socket descriptor 2915 msg - The message to be sent 2916 len - The length of the message 2917 addrs - is an array of addresses. 2918 addrcnt - is the number of addresses in the array. 2919 sinfo - A pointer to a sctp_sndrcvinfo struture used 2920 as described in 5.2.2 for a sendmsg call. 2921 flags - is used in the same format as the sendmsg call 2922 flags (e.g. MSG_DONTROUTE). 2924 Note that on return from this call the sinfo structure will have 2925 changed in that the sinfo_assoc_id will be filled in with the new 2926 association id. 2928 This function call may also be used to terminate an association using 2929 an association identification by setting the sinfo.sinfo_flags to 2930 MSG_EOF and the sinfo.sinf_associd to the association that needs to 2931 be terminated. In such a case the len of the message would be zero. 2933 9. Preprocessor Constants 2935 For application portability it is desireable to define pre-processor 2936 constants for determination if sctp is present and supports various 2937 features. The following pre-processor constants should be defined in 2938 a include file, sctp.h. 2939 HAVE_SCTP - If this constant is defined to 1, then an implementation 2940 of SCTP is available. 2941 HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel 2942 SCTP implementation is available through the sockets interface. 2943 HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP 2944 implementation supports the partial reliablility extension to 2945 SCTP. 2946 HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP 2947 implementation supports the dynamic address extension to SCTP. 2948 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the 2949 SCTP implementation supports the ability to request setting of the 2950 remote primary address. 2951 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1, 2952 then the SCTP implementation supports the satellite network 2953 extension to SCTP. 2954 HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP 2955 implementation dedicates separate buffer space to each association 2956 on a one-to-many socket. If this constant is defined to 0, then 2957 the implementation provides a single block of shared buffer space 2958 for a one-to-many socket. 2959 HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the SCTP 2960 implementation supports initiating an association on a one-to-one 2961 style socket without the use of connect(), as outlined in 2962 Section 4.1.5. 2964 10. Security Considerations 2966 Many TCP and UDP implementations reserve port numbers below 1024 for 2967 privileged users. If the target platform supports privileged users, 2968 the SCTP implementation SHOULD restrict the ability to call bind() or 2969 sctp_bindx() on these port numbers to privileged users. 2971 Similarly unpriviledged users should not be able to set protocol 2972 parameters which could result in the congestion control algorithm 2973 being more aggressive than permitted on the public Internet. These 2974 parameters are: 2976 struct sctp_rtoinfo 2978 If an unprivileged user inherits a one-to-many style socket with open 2979 associations on a privileged port, it MAY be permitted to accept new 2980 associations, but it SHOULD NOT be permitted to open new 2981 associations. This could be relevant for the r* family of protocols. 2983 11. Acknowledgments 2985 Special acknowledgment is givne to Ken Fujita who helped extensively 2986 in the early formation of this document. 2988 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon 2989 Berger, Scott Kimble, Renee Revis, and many others on the TSVWG 2990 mailing list for contributing valuable comments. 2992 A special thanks to Phillip Conrad, for his suggested text, quick and 2993 constructive insights, and most of all his persistent fighting to 2994 keep the interface to SCTP usable for the application programmer. 2996 12. References 2998 [1] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2999 September 1981. 3001 [2] Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 3002 1980. 3004 [3] Braden, B., "T/TCP -- TCP Extensions for Transactions Functional 3005 Specification", RFC 1644, July 1994. 3007 [4] Bradner, S., "The Internet Standards Process -- Revision 3", 3008 BCP 9, RFC 2026, October 1996. 3010 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 3011 Levels", BCP 14, RFC 2119, March 1997. 3013 [6] Stevens, W. and M. Thomas, "Advanced Sockets API for IPv6", 3014 RFC 2292, February 1998. 3016 [7] Gilligan, R., Thomson, S., Bound, J. and W. Stevens, "Basic 3017 Socket Interface Extensions for IPv6", RFC 2553, March 1999. 3019 [8] Stewart, R., Xie, Q., Morneault, K., Sharp, C., Schwarzbauer, 3020 H., Taylor, T., Rytina, I., Kalla, M., Zhang, L. and V. Paxson, 3021 "Stream Control Transmission Protocol", RFC 2960, October 2000. 3023 Authors' Addresses 3025 Randall R. Stewart 3026 Cisco Systems, Inc. 3027 4875 Forest Drive 3028 Suite 200 3029 Columbia, SC 29206 3030 USA 3032 Phone: 3033 Email: rrs@cisco.com 3035 Qiaobing Xie 3036 Motorola, Inc. 3037 1501 W. Shure Drive, #2309 3038 Arlington Heights, IL 60004 3039 USA 3041 Phone: 3042 Email: qxie1@email.mot.com 3044 La Monte H.P. Yarroll 3045 TimeSys Corp 3046 925 Liberty Ave. 3047 Pittsburgh, PA 15222 3048 USA 3050 Phone: 3051 Email: piggy@acm.org 3053 Jonathan Wood 3054 DoCoMo USA Labs 3055 181 Metro Drive, Suite 300 3056 San Jose, CA 95110 3057 USA 3059 Phone: 3060 Email: jonwood@speakeasy.net 3061 Kacheong Poon 3062 Sun Microsystems, Inc. 3063 4150 Network Circle 3064 Santa Clara, CA 95054 3065 USA 3067 Phone: 3068 Email: kacheong.poon@sun.com 3070 Michael Tuexen 3071 Univ. of Applied Sciences Muenster 3072 Stegerwaldstr. 39 3073 48565 Steinfurt 3074 Germany 3076 Email: tuexen@fh-muenster.de 3078 Appendix A. one-to-one style Code Example 3080 The following code is a simple implementation of an echo server over 3081 SCTP. The example shows how to use some features of one-to-one style 3082 IPv4 SCTP sockets, including: 3084 o Opening, binding, and listening for new associations on a socket; 3085 o Enabling ancillary data 3086 o Enabling notifications 3087 o Using ancillary data with sendmsg() and recvmsg() 3088 o Using MSG_EOR to determine if an entire message has been read 3089 o Handling notifications 3091 #include 3092 #include 3093 #include 3094 #include 3095 #include 3096 #include 3097 #include 3098 #include 3099 #include 3101 #define BUFLEN 100 3103 static void 3104 handle_event(void *buf) 3105 { 3106 struct sctp_assoc_change *sac; 3107 struct sctp_send_failed *ssf; 3108 struct sctp_paddr_change *spc; 3109 struct sctp_remote_error *sre; 3110 union sctp_notification *snp; 3111 char addrbuf[INET6_ADDRSTRLEN]; 3112 const char *ap; 3113 struct sockaddr_in *sin; 3114 struct sockaddr_in6 *sin6; 3116 snp = buf; 3118 switch (snp->sn_header.sn_type) { 3119 case SCTP_ASSOC_CHANGE: 3120 sac = &snp->sn_assoc_change; 3121 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3122 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3123 sac->sac_inbound_streams, sac->sac_outbound_streams); 3124 break; 3125 case SCTP_SEND_FAILED: 3127 ssf = &snp->sn_send_failed; 3128 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3129 ssf->ssf_error); 3130 break; 3132 case SCTP_PEER_ADDR_CHANGE: 3133 spc = &snp->sn_paddr_change; 3134 if (spc->spc_aaddr.ss_family == AF_INET) { 3135 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3136 ap = inet_ntop(AF_INET, &sin->sin_addr, 3137 addrbuf, INET6_ADDRSTRLEN); 3138 } else { 3139 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3140 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3141 addrbuf, INET6_ADDRSTRLEN); 3142 } 3143 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3144 spc->spc_state, spc->spc_error); 3145 break; 3146 case SCTP_REMOTE_ERROR: 3147 sre = &snp->sn_remote_error; 3148 printf("^^^ remote_error: err=%hu len=%hu\n", 3149 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3150 break; 3151 case SCTP_SHUTDOWN_EVENT: 3152 printf("^^^ shutdown event\n"); 3153 break; 3154 default: 3155 printf("unknown type: %hu\n", snp->sn_header.sn_type); 3156 break; 3157 } 3158 } 3160 static void * 3161 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 3162 ssize_t *nrp, size_t cmsglen) 3163 { 3164 ssize_t nr = 0, nnr = 0; 3165 struct iovec iov[1]; 3167 *nrp = 0; 3168 iov->iov_base = buf; 3169 iov->iov_len = *buflen; 3170 msg->msg_iov = iov; 3171 msg->msg_iovlen = 1; 3173 for (;;) { 3175 #ifndef MSG_XPG4_2 3176 #define MSG_XPG4_2 0 3177 #endif 3178 msg->msg_flags = MSG_XPG4_2; 3179 msg->msg_controllen = cmsglen; 3181 nnr = recvmsg(fd, msg, 0); 3182 if (nnr <= 0) { 3183 /* EOF or error */ 3184 *nrp = nr; 3185 return (NULL); 3186 } 3187 nr += nnr; 3189 if ((msg->msg_flags & MSG_EOR) != 0) { 3190 *nrp = nr; 3191 return (buf); 3192 } 3194 /* Realloc the buffer? */ 3195 if (*buflen == (size_t)nr) { 3196 buf = realloc(buf, *buflen * 2); 3197 if (buf == 0) { 3198 fprintf(stderr, "out of memory\n"); 3199 exit(1); 3200 } 3201 *buflen *= 2; 3202 } 3204 /* Set the next read offset */ 3205 iov->iov_base = (char *)buf + nr; 3206 iov->iov_len = *buflen - nr; 3208 } 3209 } 3211 static void 3212 echo(int fd, int socketModeone_to_many) 3213 { 3214 ssize_t nr; 3215 struct sctp_sndrcvinfo *sri; 3216 struct msghdr msg[1]; 3217 struct cmsghdr *cmsg; 3218 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3219 char *buf; 3220 size_t buflen; 3221 struct iovec iov[1]; 3222 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3223 /* Allocate the initial data buffer */ 3224 buflen = BUFLEN; 3225 if (!(buf = malloc(BUFLEN))) { 3226 fprintf(stderr, "out of memory\n"); 3227 exit(1); 3228 } 3230 /* Set up the msghdr structure for receiving */ 3231 memset(msg, 0, sizeof (*msg)); 3232 msg->msg_control = cbuf; 3233 msg->msg_controllen = cmsglen; 3234 msg->msg_flags = 0; 3235 cmsg = (struct cmsghdr *)cbuf; 3236 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3238 /* Wait for something to echo */ 3239 while (buf = mysctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 3241 /* Intercept notifications here */ 3242 if (msg->msg_flags & MSG_NOTIFICATION) { 3243 handle_event(buf); 3244 continue; 3245 } 3247 iov->iov_base = buf; 3248 iov->iov_len = nr; 3249 msg->msg_iov = iov; 3250 msg->msg_iovlen = 1; 3252 printf("got %u bytes on stream %hu:\n", nr, 3253 sri->sinfo_stream); 3254 write(0, buf, nr); 3256 /* Echo it back */ 3257 msg->msg_flags = MSG_XPG4_2; 3258 if (sendmsg(fd, msg, 0) < 0) { 3259 perror("sendmsg"); 3260 exit(1); 3261 } 3262 } 3264 if (nr < 0) { 3265 perror("recvmsg"); 3266 } 3267 if(socketModeone_to_many == 0) 3268 close(fd); 3269 } 3270 int main() 3271 { 3272 struct sctp_event_subscribe event; 3273 int lfd, cfd; 3274 int onoff = 1; 3275 struct sockaddr_in sin[1]; 3277 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3278 perror("socket"); 3279 exit(1); 3280 } 3282 sin->sin_family = AF_INET; 3283 sin->sin_port = htons(7); 3284 sin->sin_addr.s_addr = INADDR_ANY; 3285 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3286 perror("bind"); 3287 exit(1); 3288 } 3290 if (listen(lfd, 1) == -1) { 3291 perror("listen"); 3292 exit(1); 3293 } 3295 /* Wait for new associations */ 3296 for (;;) { 3297 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3298 perror("accept"); 3299 exit(1); 3300 } 3302 /* Enable all events */ 3303 event.sctp_data_io_event = 1; 3304 event.sctp_association_event = 1; 3305 event.sctp_address_event = 1; 3306 event.sctp_send_failure_event = 1; 3307 event.sctp_peer_error_event = 1; 3308 event.sctp_shutdown_event = 1; 3309 event.sctp_partial_delivery_event = 1; 3310 event.sctp_adaption_layer_event = 1; 3311 if (setsockopt(cfd, IPPROTO_SCTP, 3312 SCTP_EVENTS, &event, 3313 sizeof(event)) != 0) { 3314 perror("setevent failed"); 3315 exit(1); 3316 } 3317 /* Echo back any and all data */ 3318 echo(cfd,0); 3319 } 3320 } 3322 Appendix B. one-to-many style Code Example 3324 The following code is a simple implementation of an echo server over 3325 SCTP. The example shows how to use some features of one-to-many 3326 style IPv4 SCTP sockets, including: 3328 o Opening and binding of a socket; 3329 o Enabling ancillary data 3330 o Enabling notifications 3331 o Using ancillary data with sendmsg() and recvmsg() 3332 o Using MSG_EOR to determine if an entire message has been read 3333 o Handling notifications 3335 Note most functions defined in Appendix A are reused in thi 3336 s example. 3338 int main() 3339 { 3340 int fd; 3341 int idleTime = 2; 3342 struct sockaddr_in sin[1]; 3343 struct sctp_event_subscribe event; 3345 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3346 perror("socket"); 3347 exit(1); 3348 } 3350 sin->sin_family = AF_INET; 3351 sin->sin_port = htons(7); 3352 sin->sin_addr.s_addr = INADDR_ANY; 3353 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3354 perror("bind"); 3355 exit(1); 3356 } 3358 /* Enable all notifications and events */ 3359 event.sctp_data_io_event = 1; 3360 event.sctp_association_event = 1; 3361 event.sctp_address_event = 1; 3362 event.sctp_send_failure_event = 1; 3363 event.sctp_peer_error_event = 1; 3364 event.sctp_shutdown_event = 1; 3365 event.sctp_partial_delivery_event = 1; 3366 event.sctp_adaption_layer_event = 1; 3367 if (setsockopt(fd, IPPROTO_SCTP, 3368 SCTP_EVENTS, &event, 3369 sizeof(event)) != 0) { 3370 perror("setevent failed"); 3371 exit(1); 3372 } 3373 /* Set associations to auto-close in 2 seconds of 3374 * inactivity 3375 */ 3376 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3377 &idleTime, 4) < 0) { 3378 perror("setsockopt SCTP_AUTOCLOSE"); 3379 exit(1); 3380 } 3382 /* Allow new associations to be accepted */ 3383 if (listen(fd, 1) < 0) { 3384 perror("listen"); 3385 exit(1); 3386 } 3388 /* Wait for new associations */ 3389 while(1){ 3390 /* Echo back any and all data */ 3391 echo(fd,1); 3392 } 3393 } 3395 Intellectual Property Statement 3397 The IETF takes no position regarding the validity or scope of any 3398 Intellectual Property Rights or other rights that might be claimed to 3399 pertain to the implementation or use of the technology described in 3400 this document or the extent to which any license under such rights 3401 might or might not be available; nor does it represent that it has 3402 made any independent effort to identify any such rights. Information 3403 on the procedures with respect to rights in RFC documents can be 3404 found in BCP 78 and BCP 79. 3406 Copies of IPR disclosures made to the IETF Secretariat and any 3407 assurances of licenses to be made available, or the result of an 3408 attempt made to obtain a general license or permission for the use of 3409 such proprietary rights by implementers or users of this 3410 specification can be obtained from the IETF on-line IPR repository at 3411 http://www.ietf.org/ipr. 3413 The IETF invites any interested party to bring to its attention any 3414 copyrights, patents or patent applications, or other proprietary 3415 rights that may cover technology that may be required to implement 3416 this standard. Please address the information to the IETF at 3417 ietf-ipr@ietf.org. 3419 Disclaimer of Validity 3421 This document and the information contained herein are provided on an 3422 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3423 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3424 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3425 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3426 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3427 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3429 Copyright Statement 3431 Copyright (C) The Internet Society (2005). This document is subject 3432 to the rights, licenses and restrictions contained in BCP 78, and 3433 except as set forth therein, the authors retain all their rights. 3435 Acknowledgment 3437 Funding for the RFC Editor function is currently provided by the 3438 Internet Society.