idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 39 instances of too long lines in the document, the longest one being 14 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. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 895 has weird spacing: '...n. The value...' == Line 907 has weird spacing: '...er send and ...' == Line 1075 has weird spacing: '...g_level cms...' == Line 1129 has weird spacing: '...g_level cms...' == Line 1283 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 (April 1, 2004) is 7327 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 1552, but not defined == Unused Reference: '4' is defined on line 2884, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 2887, 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: 10 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Cisco Systems, Inc. 4 Expires: September 30, 2004 Q. Xie 5 Motorola, Inc. 6 L. Yarroll 7 USACE ERDC-CERL. 8 J. Wood 9 DoCoMo USA Labs 10 K. Poon 11 Sun Microsystems, Inc. 12 K. Fujita 13 NEC USA, Inc. 14 M. Tuexen 15 Univ. of Applied Sciences Muenster 16 April 1, 2004 18 Sockets API Extensions for Stream Control Transmission Protocol 19 (SCTP) 20 draft-ietf-tsvwg-sctpsocket-08.txt 22 Status of this Memo 24 This document is an Internet-Draft and is in full conformance with 25 all provisions of Section 10 of RFC2026. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that other 29 groups may also distribute working documents as Internet-Drafts. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 The list of current Internet-Drafts can be accessed at http:// 37 www.ietf.org/ietf/1id-abstracts.txt. 39 The list of Internet-Draft Shadow Directories can be accessed at 40 http://www.ietf.org/shadow.html. 42 This Internet-Draft will expire on September 30, 2004. 44 Copyright Notice 46 Copyright (C) The Internet Society (2004). All Rights Reserved. 48 Abstract 49 This document describes a mapping of the Stream Control Transmission 50 Protocol SCTP RFC2960 [8] into a sockets API. The benefits of this 51 mapping include compatibility for TCP applications, access to new 52 SCTP features and a consolidated error and event notification scheme. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6 58 2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3. one-to-many style Interface . . . . . . . . . . . . . . . 7 60 3.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 7 61 3.1.1 socket() - one-to-many style socket . . . . . . . . . . . 8 62 3.1.2 bind() - one-to-many style socket . . . . . . . . . . . . 9 63 3.1.3 listen() - One-to-many style socket . . . . . . . . . . . 10 64 3.1.4 sendmsg() and recvmsg() - one-to-many style socket . . . . 10 65 3.1.5 close() - one-to-many style socket . . . . . . . . . . . . 12 66 3.1.6 connect() - one-to-many style socket . . . . . . . . . . . 12 67 3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 13 68 3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 69 3.4 Special considerations . . . . . . . . . . . . . . . . . . 14 70 4. one-to-one style Interface . . . . . . . . . . . . . . . . 17 71 4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 17 72 4.1.1 socket() - one-to-one style socket . . . . . . . . . . . . 18 73 4.1.2 bind() - one-to-one style socket . . . . . . . . . . . . . 18 74 4.1.3 listen() - one-to-one style socket . . . . . . . . . . . . 19 75 4.1.4 accept() - one-to-one style socket . . . . . . . . . . . . 20 76 4.1.5 connect() - one-to-one style socket . . . . . . . . . . . 20 77 4.1.6 close() - one-to-one style socket . . . . . . . . . . . . 21 78 4.1.7 shutdown() - one-to-one style socket . . . . . . . . . . . 21 79 4.1.8 sendmsg() and recvmsg() - one-to-one style socket . . . . 22 80 4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 23 81 5. Data Structures . . . . . . . . . . . . . . . . . . . . . 24 82 5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 24 83 5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 25 84 5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 26 85 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 27 86 5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 30 87 5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 30 88 5.4 Ancillary Data Considerations and Semantics . . . . . . . 40 89 5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 40 90 5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 40 91 5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 41 92 6. Common Operations for Both Styles . . . . . . . . . . . . 43 93 6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 43 94 6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 44 95 6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 44 96 6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 44 97 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 46 98 7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 47 99 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 47 100 7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 48 101 7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 50 102 7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 50 103 7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 50 104 7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 51 105 7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 51 106 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 51 107 7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 51 108 7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . . . 52 109 7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) . . . . 52 110 7.1.12 Enable/Disable message fragmentation 111 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 53 112 7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . . . 53 113 7.1.14 Set default send parameters (SCTP_DEFAULT_SEND_PARAM) . . 53 114 7.1.15 Set notification and ancillary events (SCTP_EVENTS) . . . 54 115 7.1.16 Set/clear IPv4 mapped addresses 116 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . . . 54 117 7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) . . . . . 54 118 7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 54 119 7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 54 120 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 56 121 7.3 Ancillary Data and Notification Interest Options . . . . . 57 122 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 60 123 8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 60 124 8.2 Branched-off Association . . . . . . . . . . . . . . . . . 61 125 8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 61 126 8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 62 127 8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 62 128 8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 63 129 8.7 sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 63 130 8.8 sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 64 131 8.9 sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 65 132 8.10 sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 66 133 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . 67 134 10. Security Considerations . . . . . . . . . . . . . . . . . 68 135 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 69 136 References . . . . . . . . . . . . . . . . . . . . . . . . 70 137 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 70 138 A. one-to-one style Code Example . . . . . . . . . . . . . . 73 139 B. one-to-many style Code Example . . . . . . . . . . . . . . 79 140 Intellectual Property and Copyright Statements . . . . . . 81 142 1. Introduction 144 The sockets API has provided a standard mapping of the Internet 145 Protocol suite to many operating systems. Both TCP RFC793 [1] and UDP 146 RFC768 [2] have benefited from this standard representation and 147 access method across many diverse platforms. SCTP is a new protocol 148 that provides many of the characteristics of TCP but also 149 incorporates semantics more akin to UDP. This document defines a 150 method to map the existing sockets API for use with SCTP, providing 151 both a base for access to new features and compatibility so that most 152 existing TCP applications can be migrated to SCTP with few (if any) 153 changes. 155 There are three basic design objectives: 157 1) Maintain consistency with existing sockets APIs: 159 We define a sockets mapping for SCTP that is consistent with other 160 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 161 IPv6). 163 2) Support a one-to-many style interface 165 This set of semantics is similar to that defined for 166 connection-less protocols, such as UDP. A one-to-many style SCTP 167 socket should be able to control multiple SCTP associations. This 168 is similar to an UDP socket, which can communicate with many peer 169 end points. Each of these associations is assigned an association 170 ID so that an applications can use the ID to differentiate them. 172 Note that SCTP is connection-oriented in nature, and it does not 173 support broadcast or multicast communications, as UDP does. 175 3) Support a one-to-one style interface 177 This interface supports a similar semantics as sockets for 178 connection-oriented protocols, such as TCP. A one-to-one style 179 SCTP socket should only control one SCTP association. 181 One purpose of defining this interface is to allow existing 182 applications built on other connection-oriented protocols be 183 ported to use SCTP with very little effort. And developers 184 familiar with those semantics can easily adapt to SCTP. Another 185 purpose is to make sure that existing mechanisms in most OSes to 186 deal with socket, such as select(), should continue to work with 187 this style of socket. 189 Extensions are added to this mapping to provide mechanisms to 190 exploit new features of SCTP. 192 Goals 2 and 3 are not compatible, so in this document we define two 193 modes of mapping, namely the one-to-many style mapping and the 194 one-to-one style mapping. These two modes share some common data 195 structures and operations, but will require the use of two different 196 application programming styles. Note that all new SCTP features can 197 be used with both styles of socket. The decision on which one to use 198 depends mainly on the nature of applications. 200 A mechanism is defined to extract a one-to-many style SCTP 201 association into a one-to-one style socket. 203 Some of the SCTP mechanisms cannot be adequately mapped to existing 204 socket interface. In some cases, it is more desirable to have new 205 interface instead of using existing socket calls. Section 8 of this 206 document describes those new interface. 208 2. Conventions 210 2.1 Data Types 212 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 213 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 214 (e.g., uint16_t). We also assume the argument data types from 215 1003.1g when possible (e.g., the final argument to setsockopt() is a 216 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 217 size_t data type is used. 219 3. one-to-many style Interface 221 The one-to-many style interface has the following characteristics: 223 A) Outbound association setup is implicit. 225 B) Messages are delivered in complete messages (with one notable 226 exception). 228 C) There is a 1 to MANY relationship between socket and association. 230 3.1 Basic Operation 232 A typical server in this style uses the following socket calls in 233 sequence to prepare an endpoint for servicing requests: 235 1. socket() 237 2. bind() 239 3. listen() 241 4. recvmsg() 243 5. sendmsg() 245 6. close() 247 A typical client uses the following calls in sequence to setup an 248 association with a server to request services: 250 1. socket() 252 2. sendmsg() 254 3. recvmsg() 256 4. close() 258 In this style, by default, all the associations connected to the 259 endpoint are represented with a single socket. Each associations is 260 assigned an association ID (type is sctp_assoc_t) so that an 261 application can use it to differentiate between them. In some 262 implementations, the peer end point's addresses can also be used for 263 this purpose. But this is not required for performance reasons. If 264 an implementation does not support using addresses to differentiate 265 between different associations, the sendto() call can only be used to 266 setup an association implicitly. It cannot be used to send data to 267 an established association as the association ID cannot be specified. 269 Once as association ID is assigned to an SCTP association, that ID 270 will not be reused until the application explicitly terminates the 271 association. The resources belonged to that association will not be 272 freed until that happens. This is similar to the close() operation 273 on a normal socket. The only exception is when the SCTP_AUTOCLOSE 274 option (section 7.1.8) is set. In this case, after the association 275 is terminated automatically, the association ID assigned to it can be 276 reused. All applications using this option should be aware of this 277 to avoid the possible problem of sending data to an incorrect peer 278 end point. 280 If the server or client wishes to branch an existing association off 281 to a separate socket, it is required to call sctp_peeloff() and in 282 the parameter specifies the association identification. The 283 sctp_peeloff() call will return a new socket which can then be used 284 with recv() and send() functions for message passing. See Section 8.2 285 for more on branched-off associations. 287 Once an association is branched off to a separate socket, it becomes 288 completely separated from the original socket. All subsequent 289 control and data operations to that association must be done through 290 the new socket. For example, the close operation on the original 291 socket will not terminate any associations that have been branched 292 off to a different socket. 294 We will discuss the one-to-many style socket calls in more details in 295 the following subsections. 297 3.1.1 socket() - one-to-many style socket 299 Applications use socket() to create a socket descriptor to represent 300 an SCTP endpoint. 302 The syntax is, 304 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 306 or, 308 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 310 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 311 socket. 313 The first form creates an endpoint which can use only IPv4 addresses, 314 while, the second form creates an endpoint which can use both IPv6 315 and IPv4 addresses. 317 3.1.2 bind() - one-to-many style socket 319 Applications use bind() to specify which local address the SCTP 320 endpoint should associate itself with. 322 An SCTP endpoint can be associated with multiple addresses. To do 323 this, sctp_bindx() is introduced in section Section 8.1 to help 324 applications do the job of associating multiple addresses. 326 These addresses associated with a socket are the eligible transport 327 addresses for the endpoint to send and receive data. The endpoint 328 will also present these addresses to its peers during the association 329 initialization process, see RFC2960 [8]. 331 After calling bind(), if the endpoint wishes to accept new 332 associations on the socket, it must call listen() (see section 333 Section 3.1.3). 335 The syntax of bind() is, 337 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 339 sd: the socket descriptor returned by socket(). 341 addr: the address structure (struct sockaddr_in or struct 342 sockaddr_in6 RFC2553 [7]). 344 addrlen: the size of the address structure. 346 If sd is an IPv4 socket, the address passed must be an IPv4 address. 347 If the sd is an IPv6 socket, the address passed can either be an IPv4 348 or an IPv6 address. 350 Applications cannot call bind() multiple times to associate multiple 351 addresses to an endpoint. After the first call to bind(), all 352 subsequent calls will return an error. 354 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 355 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 356 operating system will associate the endpoint with an optimal address 357 set of the available interfaces. 359 If a bind() is not called prior to a sendmsg() call that initiates a 360 new association, the system picks an ephemeral port and will choose 361 an address set equivalent to binding with a wildcard address. One of 362 those addresses will be the primary address for the association. This 363 automatically enables the multi-homing capability of SCTP. 365 3.1.3 listen() - One-to-many style socket 367 By default, new associations are not accepted for one-to-many style 368 sockets. An application uses listen() to mark a socket as being able 369 to accept new associations. The syntax is, 371 int listen(int sd, int backlog); 372 sd - the socket descriptor of the endpoint. 373 backlog - if backlog is non-zero, enable listening else 374 disable listening. 376 Note that one-to-many style socket consumers do not need to call 377 accept to retrieve new associations. Calling accept() on a 378 one-to-many style socket should return EOPNOTSUPP. Rather, new 379 associations are accepted automatically, and notifications of the new 380 associations are delivered via recvmsg() with the SCTP_ASSOC_CHANGE 381 event (if these notifications are enabled). Clients will typically 382 not call listen(), so that they can be assured that the only 383 associations on the socket will be ones they actively initiated. 384 Server or peer-to-peer sockets, on the other hand, will always accept 385 new associations, so a well-written application using server 386 one-to-many style sockets must be prepared to handle new associations 387 from unwanted peers. 389 Also note that the SCTP_ASSOC_CHANGE event provides the association 390 ID for a new association, so if applications wish to use the 391 association ID as input to other socket calls, they should ensure 392 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 393 default). 395 3.1.4 sendmsg() and recvmsg() - one-to-many style socket 397 An application uses sendmsg() and recvmsg() call to transmit data to 398 and receive data from its peer. 400 ssize_t sendmsg(int sd, const struct msghdr *message, int flags); 402 ssize_t recvmsg(int sd, struct msghdr *message, int flags); 404 sd: the socket descriptor of the endpoint. 406 message: pointer to the msghdr structure which contains a single user 407 message and possibly some ancillary data. See Section 5 for 408 complete description of the data structures. 410 flags: No new flags are defined for SCTP at this level. See Section 5 411 for SCTP-specific flags used in the msghdr structure. 413 As we will see in Section 5, along with the user data, the ancillary 414 data field is used to carry the sctp_sndrcvinfo and/or the 415 sctp_initmsg structures to perform various SCTP functions including 416 specifying options for sending each user message. Those options, 417 depending on whether sending or receiving, include stream number, 418 stream sequence number, various flags, context and payload protocol 419 Id, etc. 421 When sending user data with sendmsg(), the msg_name field in msghdr 422 structure will be filled with one of the transport addresses of the 423 intended receiver. If there is no association existing between the 424 sender and the intended receiver, the sender's SCTP stack will set up 425 a new association and then send the user data (see Section 3.2 for 426 more on implicit association setup). 428 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 429 be delivered if that notification has been enabled, and no more data 430 can be sent to that association. Any attempt to send more data will 431 cause sendmsg() to return with an ESHUTDOWN error. Note that the 432 socket is still open for reading at this point so it is possible to 433 retrieve notifications. 435 When receiving a user message with recvmsg(), the msg_name field in 436 msghdr structure will be populated with the source transport address 437 of the user data. The caller of recvmsg() can use this address 438 information to determine to which association the received user 439 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 440 applications must use the peer transport address provided in the 441 msg_name field by recvmsg() to perform correlation to an association, 442 since they will not have the association ID. 444 If all data in a single message has been delivered, MSG_EOR will be 445 set in the msg_flags field of the msghdr structure (see section 446 Section 5.1). 448 If the application does not provide enough buffer space to completely 449 receive a data message, MSG_EOR will not be set in msg_flags. 450 Successive reads will consume more of the same message until the 451 entire message has been delivered, and MSG_EOR will be set. 453 If the SCTP stack is running low on buffers, it may partially deliver 454 a message. In this case, MSG_EOR will not be set, and more calls to 455 recvmsg() will be necessary to completely consume the message. Only 456 one message at a time can be partially delivered. 458 Note, if the socket is a branched-off socket that only represents one 459 association (see Section 3.1), the msg_name field can be used to 460 override the primary address when sending data. 462 3.1.5 close() - one-to-many style socket 464 Applications use close() to perform graceful shutdown (as described 465 in Section 10.1 of RFC2960 [8]) on ALL the associations currently 466 represented by a one-to-many style socket. 468 The syntax is: 470 ret = close(int sd); 472 sd - the socket descriptor of the associations to be closed. 474 To gracefully shutdown a specific association represented by the 475 one-to-many style socket, an application should use the sendmsg() 476 call, and including the MSG_EOF flag. A user may optionally terminate 477 an association non-gracefully by sending with the MSG_ABORT flag and 478 possibly passing a user specified abort code in the data field. Both 479 flags MSG_EOF and MSG_ABORT are passwd with ancillary data (see 480 Section 5.2.2) in the sendmsg call. 482 If sd in the close() call is a branched-off socket representing only 483 one association, the shutdown is performed on that association only. 485 3.1.6 connect() - one-to-many style socket 487 An application may use the connect() call in the one-to-many style to 488 initiate an association without sending data. 490 The syntax is: 492 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 494 sd: the socket descriptor to have a new association added to. 496 nam: the address structure (either struct sockaddr_in or struct 497 sockaddr_in6 defined in RFC2553 [7]). 499 len: the size of the address. 501 Multiple connect() calls can be made on the same socket to create 502 multiple associations. This is different from the semantics of 503 connect() on a UDP socket. 505 3.2 Implicit Association Setup 507 Once the bind() call is complete on a one-to-many style socket, the 508 application can begin sending and receiving data using the sendmsg()/ 509 recvmsg() or sendto()/recvfrom() calls, without going through any 510 explicit association setup procedures (i.e., no connect() calls 511 required). 513 Whenever sendmsg() or sendto() is called and the SCTP stack at the 514 sender finds that there is no association existing between the sender 515 and the intended receiver (identified by the address passed either in 516 the msg_name field of msghdr structure in the sendmsg() call or the 517 dest_addr field in the sendto() call), the SCTP stack will 518 automatically setup an association to the intended receiver. 520 Upon the successful association setup a SCTP_COMM_UP notification 521 will be dispatched to the socket at both the sender and receiver 522 side. This notification can be read by the recvmsg() system call (see 523 Section 3.1.3). 525 Note, if the SCTP stack at the sender side supports bundling, the 526 first user message may be bundled with the COOKIE ECHO message 527 RFC2960 [8]. 529 When the SCTP stack sets up a new association implicitly, it first 530 consults the sctp_initmsg structure, which is passed along within the 531 ancillary data in the sendmsg() call (see Section 5.2.1 for details 532 of the data structures), for any special options to be used on the 533 new association. 535 If this information is not present in the sendmsg() call, or if the 536 implicit association setup is triggered by a sendto() call, the 537 default association initialization parameters will be used. These 538 default association parameters may be set with respective 539 setsockopt() calls or be left to the system defaults. 541 Implicit association setup cannot be initiated by send()/recv() 542 calls. 544 3.3 Non-blocking mode 546 Some SCTP users might want to avoid blocking when they call socket 547 interface function. 549 Once all bind() calls are complete on a one-to-many style socket, the 550 application must set the non-blocking option by a fcntl() (such as 551 O_NONBLOCK). After which the sendmsg() function returns immediately, 552 and the success or failure of the data message (and possible 553 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 554 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 555 be sent (due to a CANT_START_ASSOC), the sender will also receive a 556 SCTP_SEND_FAILED event. Those event(s) can be received by the user 557 calling of recvmsg(). A server (having called listen()) is also 558 notified of an association up event by the reception of a 559 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 560 possibly the reception of the first data message. 562 In order to shutdown the association gracefully, the user must call 563 sendmsg() with no data and with the MSG_EOF flag set. The function 564 returns immediately, and completion of the graceful shutdown is 565 indicated by an SCTP_ASSOC_CHANGE notification of type 566 SHUTDOWN_COMPLETE (see Section 5.3.1.1). Note that this can also be 567 done using the sctp_send() call described in Section 8.10. 569 An application is recommended to use caution when using select() (or 570 poll()) for writing on a one-to-many style socket. The reason being 571 that interpretation of select on write is implementation specific. 572 Generally a positive return on a select on write would only indicate 573 that one of the associations represented by the one-to-many socket is 574 writable. An application that writes after the select return may 575 still block since the association that was writeable is not the 576 destination association of the write call. Likewise select (or 577 poll()) for reading from a one-to-many socket will only return an 578 indication that one of the associations represented by the socket has 579 data to be read. 581 An application that wishes to know that a particular association is 582 ready for reading or writing should either use the one-to-one style 583 or use the sctp_peelloff() (see Section 8.2) function to seperate the 584 association of interest from the one-to-many socket. 586 3.4 Special considerations 588 The fact that a one-to-many style socket can provide access to many 589 SCTP associations through a single socket descriptor has important 590 implications for both application programmers and system programmers 591 implementing this API. A key issue is how buffer space inside the 592 sockets layer is managed. Because this implementation detail directly 593 affects how application programmers must write their code to ensure 594 correct operation and portability, this section provides some 595 guidance to both implementors and application programmers. 597 An important feature that SCTP shares with TCP is flow control: 598 specifically, a sender may not send data faster than the receiver can 599 consume it. 601 For TCP, flow control is typically provided for in the sockets API as 602 follows. If the reader stops reading, the sender queues messages in 603 the socket layer until it uses all of its socket buffer space 604 allocation creating a "stalled connection". Further attempts to 605 write to the socket will block or return the error EAGAIN or 606 EWOULDBLOCK for a non-blocking socket. At some point, either the 607 connection is closed, or the receiver begins to read again freeing 608 space in the output queue. 610 For one-to-one style SCTP sockets (this includes sockets descriptors 611 that were separated from a one-to-many style socket with 612 sctp_peeloff()) the behavior is identical. For one-to-many style 613 SCTP sockets, the fact that we have multiple associations on a single 614 socket makes the situation more complicated. If the implementation 615 uses a single buffer space allocation shared by all associations, a 616 single stalled association can prevent the further sending of data on 617 all associations active on a particular one-to-many style socket. 619 For a blocking socket, it should be clear that a single stalled 620 association can block the entire socket. For this reason, 621 application programmers may want to use non-blocking one-to-many 622 style sockets. The application should at least be able to send 623 messages to the non-stalled associations. 625 But a non-blocking socket is not sufficient if the API implementor 626 has chosen a single shared buffer allocation for the socket. A single 627 stalled association would eventually cause the shared allocation to 628 fill, and it would become impossible to send even to non-stalled 629 associations. 631 The API implementor can solve this problem by providing each 632 association with its own allocation of outbound buffer space. Each 633 association should conceptually have as much buffer space as it would 634 have if it had its own socket. As a bonus, this simplifies the 635 implementation of sctp_peeloff(). 637 To ensure that a given stalled association will not prevent other 638 non-stalled associations from being writable, application programmers 639 should either: 641 (a) demand that the underlying implementation dedicates independent 642 buffer space allotments to each association (as suggested above), 643 or 645 (b) verify that their application layer protocol does not permit 646 large amounts of unread data at the receiver (this is true of some 647 request-response protocols, for example), or 649 (c) use one-to-one style sockets for association which may 650 potentially stall (either from the beginning, or by using 651 sctp_peeloff before sending large amounts of data that may cause a 652 stalled condition). 654 An implemenation which dedicates independent buffer space for each 655 association should define HAVE_SCTP_MULTIBUF to 1. 657 4. one-to-one style Interface 659 The goal of this style is to follow as closely as possible the 660 current practice of using the sockets interface for a connection 661 oriented protocol, such as TCP. This style enables existing 662 applications using connection oriented protocols to be ported to SCTP 663 with very little effort. 665 Note that some new SCTP features and some new SCTP socket options can 666 only be utilized through the use of sendmsg() and recvmsg() calls, 667 see Section 4.1.8. Also note that some socket interfaces may not be 668 able to provide data on the third leg of the association set up with 669 this interface style. 671 4.1 Basic Operation 673 A typical server in one-to-one style uses the following system call 674 sequence to prepare an SCTP endpoint for servicing requests: 676 1. socket() 678 2. bind() 680 3. listen() 682 4. accept() 684 The accept() call blocks until a new association is set up. It 685 returns with a new socket descriptor. The server then uses the new 686 socket descriptor to communicate with the client, using recv() and 687 send() calls to get requests and send back responses. 689 Then it calls 691 5. close() 693 to terminate the association. 695 A typical client uses the following system call sequence to setup an 696 association with a server to request services: 698 1. socket() 700 2. connect() 702 After returning from connect(), the client uses send() and recv() 703 calls to send out requests and receive responses from the server. 705 The client calls 707 3. close() 709 to terminate this association when done. 711 4.1.1 socket() - one-to-one style socket 713 Applications calls socket() to create a socket descriptor to 714 represent an SCTP endpoint. 716 The syntax is: 718 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 720 or, 722 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 724 Here, SOCK_STREAM indicates the creation of a one-to-one style 725 socket. 727 The first form creates an endpoint which can use only IPv4 addresses, 728 while the second form creates an endpoint which can use both IPv6 and 729 IPv4 addresses. 731 4.1.2 bind() - one-to-one style socket 733 Applications use bind() to pass an address to be associated with an 734 SCTP endpoint to the system. bind() allows only either a single 735 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 736 endpoint can be associated with multiple addresses. To do this, 737 sctp_bindx() is introduced in Section 8.1 to help applications do 738 the job of associating multiple addresses. 740 These addresses associated with a socket are the eligible transport 741 addresses for the endpoint to send and receive data. The endpoint 742 will also present these addresses to its peers during the association 743 initialization process, see RFC2960 [8]. 745 The syntax is: 747 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 749 sd: the socket descriptor returned by socket() call. 751 addr: the address structure (either struct sockaddr_in or struct 752 sockaddr_in6 defined in RFC2553 [7]). 754 addrlen: the size of the address structure. 756 If sd is an IPv4 socket, the address passed must be an IPv4 address. 757 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 758 either be an IPv4 or an IPv6 address. 760 Applications cannot call bind() multiple times to associate multiple 761 addresses to the endpoint. After the first call to bind(), all 762 subsequent calls will return an error. 764 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 765 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 766 operating system will associate the endpoint with an optimal address 767 set of the available interfaces. 769 If a bind() is not called prior to the connect() call, the system 770 picks an ephemeral port and will choose an address set equivalent to 771 binding with a wildcard address. One of those addresses will be the 772 primary address for the association. This automatically enables the 773 multi-homing capability of SCTP. 775 The completion of this bind() process does not ready the SCTP 776 endpoint to accept inbound SCTP association requests. Until a 777 listen() system call, described below, is performed on the socket, 778 the SCTP endpoint will promptly reject an inbound SCTP INIT request 779 with an SCTP ABORT. 781 4.1.3 listen() - one-to-one style socket 783 Applications use listen() to ready the SCTP endpoint for accepting 784 inbound associations. 786 The syntax is: 788 int listen(int sd, int backlog); 790 sd: the socket descriptor of the SCTP endpoint. 792 backlog: this specifies the max number of outstanding associations 793 allowed in the socket's accept queue. These are the associations 794 that have finished the four-way initiation handshake (see Section 795 5 of RFC2960 [8]) and are in the ESTABLISHED state. Note, a 796 backlog of '0' indicates that the caller no longer wishes to 797 receive new associations. 799 4.1.4 accept() - one-to-one style socket 801 Applications use accept() call to remove an established SCTP 802 association from the accept queue of the endpoint. A new socket 803 descriptor will be returned from accept() to represent the newly 804 formed association. 806 The syntax is: 808 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 810 new_sd: the socket descriptor for the newly formed association. 812 sd the listening socket descriptor. 814 addr on return, will contain the primary address of the peer 815 endpoint. 817 addrlen on return, will contain the size of addr. 819 4.1.5 connect() - one-to-one style socket 821 Applications use connect() to initiate an association to a peer. 823 The syntax is: 825 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 827 sd: the socket descriptor of the endpoint. 829 addr the peer's address. 831 addrlen the size of the address. 833 This operation corresponds to the ASSOCIATE primitive described in 834 section 10.1 of RFC2960 [8]. 836 By default, the new association created has only one outbound stream. 837 The SCTP_INITMSG option described in Section 7.1.3 should be used 838 before connecting to change the number of outbound streams. 840 If a bind() is not called prior to the connect() call, the system 841 picks an ephemeral port and will choose an address set equivalent to 842 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket 843 respectively. One of those addresses will be the primary address for 844 the association. This automatically enables the multi-homing 845 capability of SCTP. 847 Note that SCTP allows data exchange, similar to T/TCP RFC1644 [3], 848 during the association set up phase. If an application wants to do 849 this, it cannot use connect() call. Instead, it should use sendto() 850 or sendmsg() to initiate an association. If it uses sendto() and it 851 wants to change initialization behavior, it needs to use the 852 SCTP_INITMSG socket option before calling sendto(). Or it can use 853 SCTP_INIT type sendmsg() to initiate an association without doing the 854 setsockopt(). Note that some sockets implementations may not support 855 the sending of data to initiate an assocation with the one-to-one 856 style (implementations that do not support T/TCP normally have this 857 restriction). Implementations which allow sending of data to 858 initiate an association without calling connect() define the 859 preprocessor constant HAVE_SCTP_NOCONNECT to 1. 861 SCTP does not support half close semantics. This means that unlike 862 T/TCP, MSG_EOF should not be set in the flags parameter when calling 863 sendto() or sendmsg() when the call is used to initiate a connection. 864 MSG_EOF is not an acceptable flag with SCTP socket. 866 4.1.6 close() - one-to-one style socket 868 Applications use close() to gracefully close down an association. 870 The syntax is: 872 int close(int sd); 874 sd - the socket descriptor of the association to be closed. 876 After an application calls close() on a socket descriptor, no further 877 socket operations will succeed on that descriptor. 879 4.1.7 shutdown() - one-to-one style socket 881 SCTP differs from TCP in that it does not have half closed semantics. 882 Hence the shutdown() call for SCTP is an approximation of the TCP 883 shutdown() call, and solves some different problems. Full 884 TCP-compatibility is not provided, so developers porting TCP 885 applications to SCTP may need to recode sections that use shutdown(). 886 (Note that it is possible to achieve the same results as half close 887 in SCTP using SCTP streams.) 889 The syntax is: 891 int shutdown(int sd, int how); 893 sd - the socket descriptor of the association to be closed. 895 how - Specifies the type of shutdown. The values are 896 as follows: 898 SHUT_RD 899 Disables further receive operations. No SCTP 900 protocol action is taken. 902 SHUT_WR 903 Disables further send operations, and initiates 904 the SCTP shutdown sequence. 906 SHUT_RDWR 907 Disables further send and receive operations 908 and initiates the SCTP shutdown sequence. 910 The major difference between SCTP and TCP shutdown() is that SCTP 911 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 912 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 913 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close the 914 SCTP association while still leaving the socket descriptor open, so 915 that the caller can receive back any data SCTP was unable to deliver 916 (see Section 5.3.1.4 for more information). 918 To perform the ABORT operation described in RFC2960 [8] section 10.1, 919 an application can use the socket option SO_LINGER. It is described 920 in Section 7.1.4. 922 4.1.8 sendmsg() and recvmsg() - one-to-one style socket 924 With a one-to-one style socket, the application can also use 925 sendmsg() and recvmsg() to transmit data to and receive data from its 926 peer. The semantics is similar to those used in the one-to-many style 927 (section Section 3.1.3), with the following differences: 929 1) When sending, the msg_name field in the msghdr is not used to 930 specify the intended receiver, rather it is used to indicate a 931 preferred peer address if the sender wishes to discourage the stack 932 from sending the message to the primary address of the receiver. If 933 the transport address given is not part of the current association, 934 the data will not be sent and a SCTP_SEND_FAILED event will be 935 delivered to the application if send failure events are enabled. 937 2) An application must use close() to gracefully shutdown an 938 association, or use SO_LINGER option with close() to abort an 939 association. It must not use the MSG_ABORT or MSG_EOF flag in 940 sendmsg(). The system returns an error if an application tries to do 941 so. 943 4.1.9 getpeername() 945 Applications use getpeername() to retrieve the primary socket address 946 of the peer. This call is for TCP compatibility, and is not 947 multi-homed. It does not work with one-to-many style sockets. See 948 Section 8.3 for a multi-homed/one-to-many style version of the call. 950 The syntax is: 952 int getpeername(int sd, struct sockaddr *address, 953 socklen_t *len); 955 sd - the socket descriptor to be queried. 957 address - On return, the peer primary address is stored in 958 this buffer. If the socket is an IPv4 socket, the 959 address will be IPv4. If the socket is an IPv6 socket, 960 the address will be either an IPv6 or IPv4 961 address. 963 len - The caller should set the length of address here. 964 On return, this is set to the length of the returned 965 address. 967 If the actual length of the address is greater than the length of the 968 supplied sockaddr structure, the stored address will be truncated. 970 5. Data Structures 972 We discuss in this section important data structures which are 973 specific to SCTP and are used with sendmsg() and recvmsg() calls to 974 control SCTP endpoint operations and to access ancillary information 975 and notifications. 977 5.1 The msghdr and cmsghdr Structures 979 The msghdr structure used in the sendmsg() and recvmsg() calls, as 980 well as the ancillary data carried in the structure, is the key for 981 the application to set and get various control information from the 982 SCTP endpoint. 984 The msghdr and the related cmsghdr structures are defined and 985 discussed in details in RFC2292 [6]. Here we will cite their 986 definitions from RFC2292 [6]. 988 The msghdr structure: 990 struct msghdr { 991 void *msg_name; /* ptr to socket address structure */ 992 socklen_t msg_namelen; /* size of socket address structure */ 993 struct iovec *msg_iov; /* scatter/gather array */ 994 size_t msg_iovlen; /* # elements in msg_iov */ 995 void *msg_control; /* ancillary data */ 996 socklen_t msg_controllen; /* ancillary data buffer length */ 997 int msg_flags; /* flags on received message */ 998 }; 1000 The cmsghdr structure: 1002 struct cmsghdr { 1003 socklen_t cmsg_len; /* #bytes, including this header */ 1004 int cmsg_level; /* originating protocol */ 1005 int cmsg_type; /* protocol-specific type */ 1006 /* followed by unsigned char cmsg_data[]; */ 1007 }; 1009 In the msghdr structure, the usage of msg_name has been discussed in 1010 previous sections (see Section 3.1.3 and Section 4.1.8). 1012 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 1013 field) are treated as a single SCTP data chunk, rather than multiple 1014 chunks, for both sendmsg() and recvmsg(). 1016 The msg_flags are not used when sending a message with sendmsg(). 1018 If a notification has arrived, recvmsg() will return the notification 1019 with the MSG_NOTIFICATION flag set in msg_flags. If the 1020 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 1021 Section 5.3 for more information about notifications. 1023 If all portions of a data frame or notification have been read, 1024 recvmsg() will return with MSG_EOR set in msg_flags. 1026 5.2 SCTP msg_control Structures 1028 A key element of all SCTP-specific socket extensions is the use of 1029 ancillary data to specify and access SCTP-specific data via the 1030 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 1031 Fine-grained control over initialization and sending parameters are 1032 handled with ancillary data. 1034 Each ancillary data item is proceeded by a struct cmsghdr (see 1035 Section 5.1), which defines the function and purpose of the data 1036 contained in in the cmsg_data[] member. 1038 There are two kinds of ancillary data used by SCTP: initialization 1039 data, and, header information (SNDRCV). Initialization data 1040 (one-to-many style only) sets protocol parameters for new 1041 associations. Section 5.2.1 provides more details. Header information 1042 can set or report parameters on individual messages in a stream. See 1043 Section 5.2.2 for how to use SNDRCV ancillary data. 1045 By default on a one-to-one style socket, SCTP will pass no ancillary 1046 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1047 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1048 be enabled with socket options defined for SCTP; see Section 7.3. 1050 Note that all ancillary types are fixed length; see Section 5.4 for 1051 further discussion on this. These data structures use struct 1052 sockaddr_storage (defined in RFC2553 [7]) as a portable, fixed length 1053 address format. 1055 Other protocols may also provide ancillary data to the socket layer 1056 consumer. These ancillary data items from other protocols may 1057 intermingle with SCTP data. For example, the IPv6 socket API 1058 definitions (RFC2292 [6] and RFC2553 [7]) define a number of 1059 ancillary data items. If a socket API consumer enables delivery of 1060 both SCTP and IPv6 ancillary data, they both may appear in the same 1061 msg_control buffer in any order. An application may thus need to 1062 handle other types of ancillary data besides that passed by SCTP. 1064 The sockets application must provide a buffer large enough to 1065 accommodate all ancillary data provided via recvmsg(). If the buffer 1066 is not large enough, the ancillary data will be truncated and the 1067 msghdr's msg_flags will include MSG_CTRUNC. 1069 5.2.1 SCTP Initiation Structure (SCTP_INIT) 1071 This cmsghdr structure provides information for initializing new SCTP 1072 associations with sendmsg(). The SCTP_INITMSG socket option uses 1073 this same data structure. This structure is not used for recvmsg(). 1075 cmsg_level cmsg_type cmsg_data[] 1076 ------------ ------------ ---------------------- 1077 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1079 Here is the definition of the sctp_initmsg structure: 1081 struct sctp_initmsg { 1082 uint16_t sinit_num_ostreams; 1083 uint16_t sinit_max_instreams; 1084 uint16_t sinit_max_attempts; 1085 uint16_t sinit_max_init_timeo; 1086 }; 1088 sinit_num_ostreams: 16 bits (unsigned integer) 1090 This is an integer number representing the number of streams that the 1091 application wishes to be able to send to. This number is confirmed 1092 in the SCTP_COMM_UP notification and must be verified since it is a 1093 negotiated number with the remote endpoint. The default value of 0 1094 indicates to use the endpoint default value. 1096 sinit_max_instreams: 16 bits (unsigned integer) 1098 This value represents the maximum number of inbound streams the 1099 application is prepared to support. This value is bounded by the 1100 actual implementation. In other words the user MAY be able to 1101 support more streams than the Operating System. In such a case, the 1102 Operating System limit overrides the value requested by the user. The 1103 default value of 0 indicates to use the endpoint's default value. 1105 sinit_max_attempts: 16 bits (unsigned integer) 1107 This integer specifies how many attempts the SCTP endpoint should 1108 make at resending the INIT. This value overrides the system SCTP 1109 'Max.Init.Retransmits' value. The default value of 0 indicates to 1110 use the endpoint's default value. This is normally set to the 1111 system's default 'Max.Init.Retransmit' value. 1113 sinit_max_init_timeo: 16 bits (unsigned integer) 1114 This value represents the largest Time-Out or RTO value (in 1115 milliseconds) to use inattempting a INIT. Normally the 'RTO.Max' is 1116 used to limit the doubling of the RTO upon timeout. For the INIT 1117 message this value MAY override 'RTO.Max'. This value MUST NOT 1118 influence 'RTO.Max' during data transmission and is only used to 1119 bound the initial setup time. A default value of 0 indicates to use 1120 the endpoint's default value. This is normally set to the system's 1121 'RTO.Max' value (60 seconds). 1123 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 1125 This cmsghdr structure specifies SCTP options for sendmsg() and 1126 describes SCTP header information about a received message through 1127 recvmsg(). 1129 cmsg_level cmsg_type cmsg_data[] 1130 ------------ ------------ ---------------------- 1131 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1133 Here is the definition of sctp_sndrcvinfo: 1135 struct sctp_sndrcvinfo { 1136 uint16_t sinfo_stream; 1137 uint16_t sinfo_ssn; 1138 uint16_t sinfo_flags; 1139 uint32_t sinfo_ppid; 1140 uint32_t sinfo_context; 1141 uint32_t sinfo_timetolive; 1142 uint32_t sinfo_tsn; 1143 uint32_t sinfo_cumtsn; 1144 sctp_assoc_t sinfo_assoc_id; 1145 }; 1147 sinfo_stream: 16 bits (unsigned integer) 1149 For recvmsg() the SCTP stack places the message's stream number in 1150 this value. For sendmsg() this value holds the stream number that the 1151 application wishes to send this message to. If a sender specifies an 1152 invalid stream number an error indication is returned and the call 1153 fails. 1155 sinfo_ssn: 16 bits (unsigned integer) 1157 For recvmsg() this value contains the stream sequence number that the 1158 remote endpoint placed in the DATA chunk. For fragmented messages 1159 this is the same number for all deliveries of the message (if more 1160 than one recvmsg() is needed to read the message). The sendmsg() 1161 call will ignore this parameter. 1163 sinfo_ppid: 32 bits (unsigned integer) 1165 This value in sendmsg() is an opaque unsigned value that is passed to 1166 the remote end in each user message. In recvmsg() this value is the 1167 same information that was passed by the upper layer in the peer 1168 application. Please note that byte order issues are NOT accounted 1169 for and this information is passed opaquely by the SCTP stack from 1170 one end to the other. 1172 sinfo_context: 32 bits (unsigned integer) 1174 This value is an opaque 32 bit context datum that is used in the 1175 sendmsg() function. This value is passed back to the upper layer if 1176 a error occurs on the send of a message and is retrieved with each 1177 undelivered message (Note: if a endpoint has done multiple sends, all 1178 of which fail, multiple different sinfo_context values will be 1179 returned. One with each user data message). 1181 sinfo_flags: 16 bits (unsigned integer) 1183 This field may contain any of the following flags and is composed of 1184 a bitwise OR of these values. 1186 recvmsg() flags: 1188 MSG_UNORDERED - This flag is present when the message was sent 1189 non-ordered. 1191 sendmsg() flags: 1193 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1194 message. If this flag is clear the datagram is 1195 considered an ordered send. 1197 MSG_ADDR_OVER - This flag, in the one-to-many style, requests the SCTP 1198 stack to override the primary destination address 1199 with the address found with the sendto/sendmsg 1200 call. 1202 MSG_ABORT - Setting this flag causes the specified association 1203 to abort by sending an ABORT message to the peer 1204 (one-to-many style only). The ABORT chunk will contain an 1205 error cause 'User Initiated Abort' with cause code 12. 1206 The cause specific information of this error cause is 1207 provided in msg_iov. 1209 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1210 procedures on the specified association. Graceful 1211 shutdown assures that all data enqueued by both 1212 endpoints is successfully transmitted before closing 1213 the association (one-to-many style only). 1215 sinfo_timetolive: 32 bit (unsigned integer) 1217 For the sending side, this field contains the message time to live in 1218 milliseconds. The sending side will expire the message within the 1219 specified time period if the message as not been sent to the peer 1220 within this time period. This value will override any default value 1221 set using any socket option. Also note that the value of 0 is special 1222 in that it indicates no timeout should occur on this message. 1224 sinfo_tsn: 32 bit (unsigned integer) 1226 For the receiving side, this field holds a TSN that was assigned to 1227 one of the SCTP Data Chunks. 1229 sinfo_cumtsn: 32 bit (unsigned integer) 1231 This field will hold the current cumulative TSN as known by the 1232 underlying SCTP layer. Note this field is ignored when sending and 1233 only valid for a receive operation when sinfo_flags are set to 1234 MSG_UNORDERED. 1236 sinfo_assoc_id: sizeof (sctp_assoc_t) 1238 The association handle field, sinfo_assoc_id, holds the identifier 1239 for the association announced in the SCTP_COMM_UP notification. All 1240 notifications for a given association have the same identifier. 1241 Ignored for one-to-one style sockets. 1243 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1245 5.3 SCTP Events and Notifications 1247 An SCTP application may need to understand and process events and 1248 errors that happen on the SCTP stack. These events include network 1249 status changes, association startups, remote operational errors and 1250 undeliverable messages. All of these can be essential for the 1251 application. 1253 When an SCTP application layer does a recvmsg() the message read is 1254 normally a data message from a peer endpoint. If the application 1255 wishes to have the SCTP stack deliver notifications of non-data 1256 events, it sets the appropriate socket option for the notifications 1257 it wants. See Section 7.3 for these socket options. When a 1258 notification arrives, recvmsg() returns the notification in the 1259 application-supplied data buffer via msg_iov, and sets 1260 MSG_NOTIFICATION in msg_flags. 1262 This section details the notification structures. Every notification 1263 structure carries some common fields which provides general 1264 information. 1266 A recvmsg() call will return only one notification at a time. Just 1267 as when reading normal data, it may return part of a notification if 1268 the msg_iov buffer is not large enough. If a single read is not 1269 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1270 reading the notification before subsequent data can arrive. 1272 5.3.1 SCTP Notification Structure 1274 The notification structure is defined as the union of all 1275 notification types. 1277 union sctp_notification { 1278 struct { 1279 uint16_t sn_type; /* Notification type. */ 1280 uint16_t sn_flags; 1281 uint32_t sn_length; 1282 } sn_header; 1283 struct sctp_assoc_change sn_assoc_change; 1284 struct sctp_paddr_change sn_paddr_change; 1285 struct sctp_remote_error sn_remote_error; 1286 struct sctp_send_failed sn_send_failed; 1287 struct sctp_shutdown_event sn_shutdown_event; 1288 struct sctp_adaption_event sn_adaption_event; 1289 struct sctp_pdapi_event sn_pdapi_event; 1290 }; 1292 sn_type: 16 bits (unsigned integer) 1294 The following list describes the SCTP notification and event types 1295 for the field sn_type. 1297 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1298 been opened or closed. Refer to Section 5.3.1.1 for details. 1300 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1301 part of an existing association has experienced a change of state 1302 (e.g. a failure or return to service of the reachability of a 1303 endpoint via a specific transport address). Please see Section 1304 5.3.1.2 for data structure details. 1306 SCTP_REMOTE_ERROR: The attached error message is an Operational Error 1307 received from the remote peer. It includes the complete TLV sent 1308 by the remote endpoint. See Section 5.3.1.3 for the detailed 1309 format. 1311 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1312 remote endpoint. This structure includes the original 1313 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1314 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1316 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1317 should be sent on this socket. 1319 SCTP_ADAPTION_INDICATION: This notification holds the peers indicated 1320 adaption layer. Please see Section 5.3.1.6. 1322 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1323 receiver that the partial delivery has been aborted. This may 1324 indicate the association is about to be aborted. Please see 1325 Section 5.3.1.7 1327 All standard values for sn_type are greater than 2^15. Values from 1328 2^15 and down are reserved. 1330 sn_flags: 16 bits (unsigned integer) 1332 These are notification-specific flags. 1334 sn_length: 32 bits (unsigned integer) 1336 This is the length of the whole sctp_notification structure including 1337 the sn_type, sn_flags, and sn_length fields. 1339 5.3.1.1 SCTP_ASSOC_CHANGE 1341 Communication notifications inform the ULP that an SCTP association 1342 has either begun or ended. The identifier for a new association is 1343 provided by this notification. The notification information has the 1344 following format: 1346 struct sctp_assoc_change { 1347 uint16_t sac_type; 1348 uint16_t sac_flags; 1349 uint32_t sac_length; 1350 uint16_t sac_state; 1351 uint16_t sac_error; 1352 uint16_t sac_outbound_streams; 1353 uint16_t sac_inbound_streams; 1354 sctp_assoc_t sac_assoc_id; 1355 uint8_t sac_info[0]; 1356 }; 1358 sac_type: 1360 It should be SCTP_ASSOC_CHANGE. 1362 sac_flags: 16 bits (unsigned integer) 1364 Currently unused. 1366 sac_length: 32 bits (unsigned integer) 1368 This field is the total length of the notification data, including 1369 the notification header. 1371 sac_state: 16 bits (signed integer) 1373 This field holds one of a number of values that communicate the event 1374 that happened to the association. They include: 1376 Event Name Description 1377 ---------------- --------------- 1378 SCTP_COMM_UP A new association is now ready 1379 and data may be exchanged with this 1380 peer. 1382 SCTP_COMM_LOST The association has failed. The association 1383 is now in the closed state. If SEND FAILED 1384 notifications are turned on, a SCTP_COMM_LOST 1385 is followed by a series of SCTP_SEND_FAILED 1386 events, one for each outstanding message. 1388 SCTP_RESTART SCTP has detected that the peer has restarted. 1390 SCTP_SHUTDOWN_COMP The association has gracefully closed. 1392 SCTP_CANT_STR_ASSOC The association failed to setup. If non blocking 1393 mode is set and data was sent (in the udp mode), 1394 a SCTP_CANT_STR_ASSOC is followed by a series of 1395 SCTP_SEND_FAILED events, one for each outstanding 1396 message. 1398 sac_error: 16 bits (signed integer) 1400 If the state was reached due to a error condition (e.g. 1401 SCTP_COMM_LOST) any relevant error information is available in this 1402 field. This corresponds to the protocol error codes defined in 1403 RFC2960 [8]. 1405 sac_outbound_streams: 16 bits (unsigned integer) 1407 sac_inbound_streams: 16 bits (unsigned integer) 1409 The maximum number of streams allowed in each direction are available 1410 in sac_outbound_streams and sac_inbound streams. 1412 sac_assoc_id: sizeof (sctp_assoc_t) 1414 The association id field, holds the identifier for the association. 1415 All notifications for a given association have the same association 1416 identifier. For one-to-one style socket, this field is ignored. 1418 sac_info: variable 1419 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1420 for this association, sac_info[] contains the complete ABORT chunk as 1421 defined in the SCTP specification RFC2960 [8] section 3.3.7. 1423 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1425 When a destination address on a multi-homed peer encounters a change 1426 an interface details event is sent. The information has the 1427 following structure: 1429 struct sctp_paddr_change { 1430 uint16_t spc_type; 1431 uint16_t spc_flags; 1432 uint32_t spc_length; 1433 struct sockaddr_storage spc_aaddr; 1434 int spc_state; 1435 int spc_error; 1436 sctp_assoc_t spc_assoc_id; 1437 } 1439 spc_type: 1441 It should be SCTP_PEER_ADDR_CHANGE. 1443 spc_flags: 16 bits (unsigned integer) 1445 Currently unused. 1447 spc_length: 32 bits (unsigned integer) 1449 This field is the total length of the notification data, including 1450 the notification header. 1452 spc_aaddr: sizeof (struct sockaddr_storage) 1454 The affected address field, holds the remote peer's address that is 1455 encountering the change of state. 1457 spc_state: 32 bits (signed integer) 1459 This field holds one of a number of values that communicate the event 1460 that happened to the address. They include: 1462 Event Name Description 1463 ---------------- --------------- 1464 SCTP_ADDR_AVAILABLE This address is now reachable. 1466 SCTP_ADDR_UNREACHABLE The address specified can no 1467 longer be reached. Any data sent 1468 to this address is rerouted to an 1469 alternate until this address becomes 1470 reachable. 1472 SCTP_ADDR_REMOVED The address is no longer part of 1473 the association. 1475 SCTP_ADDR_ADDED The address is now part of the 1476 association. 1478 SCTP_ADDR_MADE_PRIM This address has now been made 1479 to be the primary destination address. 1481 spc_error: 32 bits (signed integer) 1483 If the state was reached due to any error condition (e.g. 1484 SCTP_ADDR_UNREACHABLE) any relevant error information is available in 1485 this field. 1487 spc_assoc_id: sizeof (sctp_assoc_t) 1489 The association id field, holds the identifier for the association. 1490 All notifications for a given association have the same association 1491 identifier. For one-to-one style socket, this field is ignored. 1493 5.3.1.3 SCTP_REMOTE_ERROR 1495 A remote peer may send an Operational Error message to its peer. This 1496 message indicates a variety of error conditions on an association. 1497 The entire ERROR chunk as it appears on the wire is included in a 1498 SCTP_REMOTE_ERROR event. Please refer to the SCTP specification 1499 RFC2960 [8] and any extensions for a list of possible error formats. 1500 SCTP error notifications have the format: 1502 struct sctp_remote_error { 1503 uint16_t sre_type; 1504 uint16_t sre_flags; 1505 uint32_t sre_length; 1506 uint16_t sre_error; 1507 sctp_assoc_t sre_assoc_id; 1508 uint8_t sre_data[0]; 1509 }; 1511 sre_type: 1513 It should be SCTP_REMOTE_ERROR. 1515 sre_flags: 16 bits (unsigned integer) 1517 Currently unused. 1519 sre_length: 32 bits (unsigned integer) 1521 This field is the total length of the notification data, including 1522 the notification header and the contents of sre_data. 1524 sre_error: 16 bits (unsigned integer) 1526 This value represents one of the Operational Error causes defined in 1527 the SCTP specification, in network byte order. 1529 sre_assoc_id: sizeof (sctp_assoc_t) 1531 The association id field, holds the identifier for the association. 1532 All notifications for a given association have the same association 1533 identifier. For one-to-one style socket, this field is ignored. 1535 sre_data: variable 1537 This contains the ERROR chunk as defined in the SCTP specification 1538 RFC2960 [8] section 3.3.10. 1540 5.3.1.4 SCTP_SEND_FAILED 1542 If SCTP cannot deliver a message it may return the message as a 1543 notification. 1545 struct sctp_send_failed { 1546 uint16_t ssf_type; 1547 uint16_t ssf_flags; 1548 uint32_t ssf_length; 1549 uint32_t ssf_error; 1550 struct sctp_sndrcvinfo ssf_info; 1551 sctp_assoc_t ssf_assoc_id; 1552 uint8_t ssf_data[0]; 1553 }; 1554 ssf_type: 1556 It should be SCTP_SEND_FAILED. 1558 The flag value will take one of the following values 1560 SCTP_DATA_UNSENT - Indicates that the data was never put on 1561 the wire. 1563 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1564 Note that this does not necessarily mean that the 1565 data was (or was not) successfully delivered. 1567 ssf_length: 32 bits (unsigned integer) 1569 This field is the total length of the notification data, including 1570 the notification header and the payload in ssf_data. 1572 ssf_error: 16 bits (unsigned integer) 1574 This value represents the reason why the send failed, and if set, 1575 will be a SCTP protocol error code as defined in RFC2960 [8] section 1576 3.3.10. 1578 ssf_info: sizeof (struct sctp_sndrcvinfo) 1580 The original send information associated with the undelivered 1581 message. 1583 ssf_assoc_id: sizeof (sctp_assoc_t) 1585 The association id field, sf_assoc_id, holds the identifier for the 1586 association. All notifications for a given association have the same 1587 association identifier. For one-to-one style socket, this field is 1588 ignored. 1590 ssf_data: variable length 1592 The undelivered message, exactly as delivered by the caller to the 1593 original send*() call. 1595 5.3.1.5 SCTP_SHUTDOWN_EVENT 1597 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1598 inform the application that it should cease sending data. 1600 struct sctp_shutdown_event { 1601 uint16_t sse_type; 1602 uint16_t sse_flags; 1603 uint32_t sse_length; 1604 sctp_assoc_t sse_assoc_id; 1605 }; 1607 sse_type 1609 It should be SCTP_SHUTDOWN_EVENT 1611 sse_flags: 16 bits (unsigned integer) 1613 Currently unused. 1615 sse_length: 32 bits (unsigned integer) 1617 This field is the total length of the notification data, including 1618 the notification header. It will generally be sizeof (struct 1619 sctp_shutdown_event). 1621 sse_flags: 16 bits (unsigned integer) 1623 Currently unused. 1625 sse_assoc_id: sizeof (sctp_assoc_t) 1627 The association id field, holds the identifier for the association. 1628 All notifications for a given association have the same association 1629 identifier. For one-to-one style socket, this field is ignored. 1631 5.3.1.6 SCTP_ADAPTION_INDICATION 1633 When a peer sends a Adaption Layer Indication parameter , SCTP 1634 delivers this notification to inform the application that of the 1635 peers requested adaption layer. 1637 struct sctp_adaption_event { 1638 uint16_t sai_type; 1639 uint16_t sai_flags; 1640 uint32_t sai_length; 1641 uint32_t sai_adaption_ind; 1642 sctp_assoc_t sai_assoc_id; 1643 }; 1645 sai_type 1647 It should be SCTP_ADAPTION_INDICATION 1648 sai_flags: 16 bits (unsigned integer) 1650 Currently unused. 1652 sai_length: 32 bits (unsigned integer) 1654 This field is the total length of the notification data, including 1655 the notification header. It will generally be sizeof (struct 1656 sctp_adaption_event). 1658 sai_adaption_ind: 32 bits (unsigned integer) 1660 This field holds the bit array sent by the peer in the adaption layer 1661 indication parameter. The bits are in network byte order. 1663 sai_assoc_id: sizeof (sctp_assoc_t) 1665 The association id field, holds the identifier for the association. 1666 All notifications for a given association have the same association 1667 identifier. For one-to-one style socket, this field is ignored. 1669 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT 1671 When a receiver is engaged in a partial delivery of a message this 1672 notification will be used to indicate various events. 1674 struct sctp_pdapi_event { 1675 uint16_t pdapi_type; 1676 uint16_t pdapi_flags; 1677 uint32_t pdapi_length; 1678 uint32_t pdapi_indication; 1679 sctp_assoc_t pdapi_assoc_id; 1680 }; 1682 pdapi_type 1684 It should be SCTP_PARTIAL_DELIVERY_EVENT 1686 pdapi_flags: 16 bits (unsigned integer) 1688 Currently unused. 1690 pdapi_length: 32 bits (unsigned integer) 1692 This field is the total length of the notification data, including 1693 the notification header. It will generally be sizeof (struct 1694 sctp_pdapi_event). 1696 pdapi_indication: 32 bits (unsigned integer) 1698 This field holds the indication being sent to the application 1699 possible values include: 1701 SCTP_PARTIAL_DELIVERY_ABORTED 1703 pdapi_assoc_id: sizeof (sctp_assoc_t) 1705 The association id field, holds the identifier for the association. 1706 All notifications for a given association have the same association 1707 identifier. For one-to-one style socket, this field is ignored. 1709 5.4 Ancillary Data Considerations and Semantics 1711 Programming with ancillary socket data contains some subtleties and 1712 pitfalls, which are discussed below. 1714 5.4.1 Multiple Items and Ordering 1716 Multiple ancillary data items may be included in any call to 1717 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1718 items, or both. 1720 The ordering of ancillary data items (either by SCTP or another 1721 protocol) is not significant and is implementation-dependent, so 1722 applications must not depend on any ordering. 1724 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1725 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1726 sendmsg() or recvmsg() call. 1728 5.4.2 Accessing and Manipulating Ancillary Data 1730 Applications can infer the presence of data or ancillary data by 1731 examining the msg_iovlen and msg_controllen msghdr members, 1732 respectively. 1734 Implementations may have different padding requirements for ancillary 1735 data, so portable applications should make use of the macros 1736 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1737 RFC2292 [6] and your SCTP implementation's documentation for more 1738 information. Following is an example, from RFC2292 [6], demonstrating 1739 the use of these macros to access ancillary data: 1741 struct msghdr msg; 1742 struct cmsghdr *cmsgptr; 1744 /* fill in msg */ 1746 /* call recvmsg() */ 1748 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1749 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1750 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1751 u_char *ptr; 1753 ptr = CMSG_DATA(cmsgptr); 1754 /* process data pointed to by ptr */ 1755 } 1756 } 1758 5.4.3 Control Message Buffer Sizing 1760 The information conveyed via SCTP_SNDRCV events will often be 1761 fundamental to the correct and sane operation of the sockets 1762 application. This is particularly true of the one-to-many semantics, 1763 but also of the one-ton-one semantics. For example, if an application 1764 needs to send and receive data on different SCTP streams, SCTP_SNDRCV 1765 events are indispensable. 1767 Given that some ancillary data is critical, and that multiple 1768 ancillary data items may appear in any order, applications should be 1769 carefully written to always provide a large enough buffer to contain 1770 all possible ancillary data that can be presented by recvmsg(). If 1771 the buffer is too small, and crucial data is truncated, it may pose a 1772 fatal error condition. 1774 Thus it is essential that applications be able to deterministically 1775 calculate the maximum required buffer size to pass to recvmsg(). One 1776 constraint imposed on this specification that makes this possible is 1777 that all ancillary data definitions are of a fixed length. One way to 1778 calculate the maximum required buffer size might be to take the sum 1779 the sizes of all enabled ancillary data item structures, as 1780 calculated by CMSG_SPACE. For example, if we enabled SCTP_SNDRCV_INFO 1781 and IPV6_RECVPKTINFO RFC2292 [6], we would calculate and allocate the 1782 buffer size as follows: 1784 size_t total; 1785 void *buf; 1787 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1788 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1790 buf = malloc(total); 1792 We could then use this buffer for msg_control on each call to 1793 recvmsg() and be assured that we would not lose any ancillary data to 1794 truncation. 1796 6. Common Operations for Both Styles 1798 6.1 send(), recv(), sendto(), recvfrom() 1800 Applications can use send() and sendto() to transmit data to the peer 1801 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1802 data from the peer. 1804 The syntax is: 1806 ssize_t send(int sd, const void *msg, size_t len, int flags); 1807 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1808 const struct sockaddr *to, socklen_t tolen); 1809 ssize_t recv(int sd, void *buf, size_t len, int flags); 1810 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1811 struct sockaddr *from, socklen_t *fromlen); 1813 sd - the socket descriptor of an SCTP endpoint. 1814 msg - the message to be sent. 1815 len - the size of the message or the size of buffer. 1816 to - one of the peer addresses of the association to be 1817 used to send the message. 1818 tolen - the size of the address. 1819 buf - the buffer to store a received message. 1820 from - the buffer to store the peer address used to send the 1821 received message. 1822 fromlen - the size of the from address 1823 flags - (described below). 1825 These calls give access to only basic SCTP protocol features. If 1826 either peer in the association uses multiple streams, or sends 1827 unordered data these calls will usually be inadequate, and may 1828 deliver the data in unpredictable ways. 1830 SCTP has the concept of multiple streams in one association. The 1831 above calls do not allow the caller to specify on which stream a 1832 message should be sent. The system uses stream 0 as the default 1833 stream for send() and sendto(). recv() and recvfrom() return data 1834 from any stream, but the caller can not distinguish the different 1835 streams. This may result in data seeming to arrive out of order. 1836 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1837 provide no indication. 1839 SCTP is message based. The msg buffer above in send() and sendto() 1840 is considered to be a single message. This means that if the caller 1841 wants to send a message which is composed by several buffers, the 1842 caller needs to combine them before calling send() or sendto(). 1843 Alternately, the caller can use sendmsg() to do that without 1844 combining them. recv() and recvfrom() cannot distinguish message 1845 boundaries. 1847 In receiving, if the buffer supplied is not large enough to hold a 1848 complete message, the receive call acts like a stream socket and 1849 returns as much data as will fit in the buffer. 1851 Note, the send() and recv() calls may not be used for a one-to-many 1852 style socket. 1854 Note, if an application calls a send function with no user data and 1855 no ancillary data the SCTP implementation should reject the request 1856 with an appropriate error message. An implementation is NOT allowed 1857 to send a Data chunk with no user data RFC2960 [8]. 1859 6.2 setsockopt(), getsockopt() 1861 Applications use setsockopt() and getsockopt() to set or retrieve 1862 socket options. Socket options are used to change the default 1863 behavior of sockets calls. They are described in Section 7 1865 The syntax is: 1867 ret = getsockopt(int sd, int level, int optname, void *optval, 1868 socklen_t *optlen); 1869 ret = setsockopt(int sd, int level, int optname, const void *optval, 1870 socklen_t optlen); 1872 sd - the socket descript. 1873 level - set to IPPROTO_SCTP for all SCTP options. 1874 optname - the option name. 1875 optval - the buffer to store the value of the option. 1876 optlen - the size of the buffer (or the length of the option 1877 returned). 1879 6.3 read() and write() 1881 Applications can use read() and write() to send and receive data to 1882 and from peer. They have the same semantics as send() and recv() 1883 except that the flags parameter cannot be used. 1885 Note, these calls, when used in the one-to-many style, may only be 1886 used with branched off socket descriptors (see Section 8.2). 1888 6.4 getsockname() 1890 Applications use getsockname() to retrieve the locally-bound socket 1891 address of the specified socket. This is especially useful if the 1892 caller let SCTP chose a local port. This call is for where the 1893 endpoint is not multi-homed. It does not work well with multi-homed 1894 sockets. See Section 8.5 for a multi-homed version of the call. 1896 The syntax is: 1898 int getsockname(int sd, struct sockaddr *address, 1899 socklen_t *len); 1901 sd - the socket descriptor to be queried. 1903 address - On return, one locally bound address (chosen by 1904 the SCTP stack) is stored in this buffer. If the 1905 socket is an IPv4 socket, the address will be IPv4. 1906 If the socket is an IPv6 socket, the address will 1907 be either an IPv6 or IPv4 address. 1909 len - The caller should set the length of address here. 1910 On return, this is set to the length of the returned 1911 address. 1913 If the actual length of the address is greater than the length of the 1914 supplied sockaddr structure, the stored address will be truncated. 1916 If the socket has not been bound to a local name, the value stored in 1917 the object pointed to by address is unspecified. 1919 7. Socket Options 1921 The following sub-section describes various SCTP level socket options 1922 that are common to both styles. SCTP associations can be 1923 multi-homed. Therefore, certain option parameters include a 1924 sockaddr_storage structure to select which peer address the option 1925 should be applied to. 1927 For the one-to-many style sockets, an sctp_assoc_t structure 1928 (association ID) is used to identify the the association instance 1929 that the operation affects. So it must be set when using this style. 1931 For the one-to-one style sockets and branched off one-to-many style 1932 sockets (see Section 8.2) this association ID parameter is ignored. 1934 Note that socket or IP level options are set or retrieved per socket. 1935 This means that for one-to-many style sockets, those options will be 1936 applied to all associations belonging to the socket. And for 1937 one-to-one style, those options will be applied to all peer addresses 1938 of the association controlled by the socket. Applications should be 1939 very careful in setting those options. 1941 For some IP stacks getsockopt() is read-only, so a new interface will 1942 be needed when information must be passed both in to and out of the 1943 SCTP stack. The syntax for scpt_opt_info() is, 1945 int sctp_opt_info(int sd, 1946 sctp_assoc_t id, 1947 int opt, 1948 void *arg, 1949 socklen_t *size); 1951 For one-to-many style sockets, id specifies the association to query. 1952 For one-to-one style sockets, id is ignored. 1954 opt specifies which SCTP socket option to get. It can any socket 1955 option currently supported that requests information (either read/ 1956 write options or read only) such as: 1958 SCTP_RTOINFO 1959 SCTP_ASSOCINFO 1960 SCTP_DEFAULT_SEND_PARAM 1961 SCTP_GET_PEER_ADDR_INFO 1962 SCTP_PRIMARY_ADDR 1963 SCTP_PEER_ADDR_PARAMS 1964 SCTP_STATUS 1966 arg is an option-specific structure buffer provided by the caller. 1968 See Section 8.5) subsections for more information on these options 1969 and option-specific structures. 1971 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1972 sets errno to the appropriate error code. 1974 All options that support specific settings on an association by 1975 filling in either an association id variable or a sockaddr_storage 1976 SHOULD also support setting of the same value for the entire endpoint 1977 (i.e. future associations). To accomplish this the following logic is 1978 used when setting one of these options: 1980 a) If an address is specified via a sockaddr_storage that is included 1981 in the structure the address is used to lookup the association and 1982 the settings are applied to the specific address (if appropriate) 1983 or to the entire association. 1985 b) If an association identification is filled in but not a 1986 sockaddr_storage (if present) the association is found using the 1987 association identification and the settings should be applied to 1988 the entire association (since a specific address is not 1989 specified). Note this also applies to options that hold an 1990 association identification in their structure but do not have a 1991 sockaddr_storage field. 1993 c) If neither the sockaddr_storage or association identification is 1994 set i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 1995 the association identification is 0, the settings are a default 1996 and to be applied to the endpoint (all future associations). 1998 7.1 Read / Write Options 2000 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 2002 The protocol parameters used to initialize and bound retransmission 2003 timeout (RTO) are tunable. See RFC2960 [8] for more information on 2004 how these parameters are used in RTO calculation. 2006 The following structure is used to access and modify these 2007 parameters: 2009 struct sctp_rtoinfo { 2010 sctp_assoc_t srto_assoc_id; 2011 uint32_t srto_initial; 2012 uint32_t srto_max; 2013 uint32_t srto_min; 2014 }; 2015 srto_initial - This contains the initial RTO value. 2016 srto_max and srto_min - These contain the maximum and minimum bounds 2017 for all RTOs. 2018 srto_assoc_id - (one-to-many style socket) This is filled in the application, 2019 and identifies the association for this query. If 2020 this parameter is '0' (on a one-to-many style socket), 2021 then the change effects the entire endpoint. 2023 All parameters are time values, in milliseconds. A value of 0, when 2024 modifying the parameters, indicates that the current value should not 2025 be changed. 2027 To access or modify these parameters, the application should call 2028 getsockopt or setsockopt() respectively with the option name 2029 SCTP_RTOINFO. 2031 7.1.2 Association Parameters (SCTP_ASSOCINFO) 2033 This option is used to both examine and set various association and 2034 endpoint parameters. 2036 See RFC2960 [8] for more information on how this parameter is used. 2037 The peer address parameter is ignored for one-to-one style socket. 2039 The following structure is used to access and modify this parameters: 2041 struct sctp_assocparams { 2042 sctp_assoc_t sasoc_assoc_id; 2043 uint16_t sasoc_asocmaxrxt; 2044 uint16_t sasoc_number_peer_destinations; 2045 uint32_t sasoc_peer_rwnd; 2046 uint32_t sasoc_local_rwnd; 2047 uint32_t sasoc_cookie_life; 2048 }; 2049 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2050 to make for the association. 2052 sasoc_number_peer_destinations - This is the number of destination 2053 addresses that the peer has. 2054 sasoc_peer_rwnd - This holds the current value of the peers 2055 rwnd (reported in the last SACK) minus any 2056 outstanding data (i.e. data inflight). 2057 sasoc_local_rwnd - This holds the last reported rwnd that was 2058 sent to the peer. 2059 sasoc_cookie_life - This is the associations cookie life value 2060 used when issuing cookies. 2061 sasoc_assoc_id - (one-to-many style socket) This is filled in the application, 2062 and identifies the association for this query. 2064 This information may be examined for either the endpoint or a 2065 specific association. To examine a endpoints default parameters the 2066 association id (sasoc_assoc_id) should must be set to the value '0'. 2067 The values of the sasoc_peer_rwnd is meaningless when examining 2068 endpoint information. 2070 All parameters are time values, in milliseconds. A value of 0, when 2071 modifying the parameters, indicates that the current value should not 2072 be changed. 2074 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2075 on either an endpoint or association basis. The rwnd and destination 2076 counts (sasoc_number_peer_destinations, 2077 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2078 placed in these is ignored. 2080 To access or modify these parameters, the application should call 2081 getsockopt or setsockopt() respectively with the option name 2082 SCTP_ASSOCINFO. 2084 The maximum number of retransmissions before an address is considered 2085 unreachable is also tunable, but is address-specific, so it is 2086 covered in a separate option. If an application attempts to set the 2087 value of the association maximum retransmission parameter to more 2088 than the sum of all maximum retransmission parameters, setsockopt() 2089 shall return an error. The reason for this, from RFC2960 [8] section 2090 8.2: 2092 Note: When configuring the SCTP endpoint, the user should avoid 2093 having the value of 'Association.Max.Retrans' larger than the 2094 summation of the 'Path.Max.Retrans' of all the destination addresses 2095 for the remote endpoint. Otherwise, all the destination addresses 2096 may become inactive while the endpoint still considers the peer 2097 endpoint reachable. 2099 7.1.3 Initialization Parameters (SCTP_INITMSG) 2101 Applications can specify protocol parameters for the default 2102 association initialization. The structure used to access and modify 2103 these parameters is defined in Section 5.2.1). The option name 2104 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2106 Setting initialization parameters is effective only on an unconnected 2107 socket (for one-to-many style sockets only future associations are 2108 effected by the change). With one-to-one style sockets, this option 2109 is inherited by sockets derived from a listener socket. 2111 7.1.4 SO_LINGER 2113 An application using the one-to-one style socket can use this option 2114 to perform the SCTP ABORT primitive. The linger option structure is: 2116 struct linger { 2117 int l_onoff; /* option on/off */ 2118 int l_linger; /* linger time */ 2119 }; 2121 To enable the option, set l_onoff to 1. If the l_linger value is set 2122 to 0, calling close() is the same as the ABORT primitive. If the 2123 value is set to a negative value, the setsockopt() call will return 2124 an error. If the value is set to a positive value linger_time, the 2125 close() can be blocked for at most linger_time ms. If the graceful 2126 shutdown phase does not finish during this period, close() will 2127 return but the graceful shutdown phase continues in the system. 2129 Note, this is a socket level option NOT an SCTP level option. So when 2130 setting SO_LINGER you must specify a level of SOL_SOCKET in the 2131 setsockopt() call. 2133 7.1.5 SCTP_NODELAY 2135 Turn on/off any Nagle-like algorithm. This means that packets are 2136 generally sent as soon as possible and no unnecessary delays are 2137 introduced, at the cost of more packets in the network. Expects an 2138 integer boolean flag. 2140 7.1.6 SO_RCVBUF 2142 Sets receive buffer size in octets. For SCTP one-to-one style 2143 sockets, this controls the receiver window size. For one-to-many 2144 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF 2145 (see Section 3.4). If the implementation defines HAVE_SCTP_MULTIBUF 2146 as 1, this controls the receiver window size for each association 2147 bound to the socket descriptor. If the implementation defines 2148 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive 2149 buffer for the whole socket. The call expects an integer. 2151 7.1.7 SO_SNDBUF 2153 Sets send buffer size. For SCTP one-to-one style sockets, this 2154 controls the amount of data SCTP may have waiting in internal buffers 2155 to be sent. This option therefore bounds the maximum size of data 2156 that can be sent in a single send call. For one-to-many style 2157 sockets, the effect is the same, except that it applies to one or all 2158 associations (see Section 3.4) bound to the socket descriptor 2159 used in the setsockopt() or getsockopt() call. The option applies to 2160 each association's window size separately. The call expects an 2161 integer. 2163 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 2165 This socket option is applicable to the one-to-many style socket 2166 only. When set it will cause associations that are idle for more than 2167 the specified number of seconds to automatically close. An 2168 association being idle is defined as an association that has NOT sent 2169 or received user data. The special value of '0' indicates that no 2170 automatic close of any associations should be performed, this is the 2171 default value. The option expects an integer defining the number of 2172 seconds of idle time before an association is closed. 2174 An application using this option should enable receiving the 2175 association change notification. This is the only mechanism an 2176 application is informed about the closing of an association. After 2177 an association is closed, the association ID assigned to it can be 2178 reused. An application should be aware of this to avoid the possible 2179 problem of sending data to an incorrect peer end point. 2181 7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2183 Requests that the peer mark the enclosed address as the association 2184 primary. The enclosed address must be one of the association's 2185 locally bound addresses. The following structure is used to make a 2186 set primary request: 2188 struct sctp_setpeerprim { 2189 sctp_assoc_t sspp_assoc_id; 2190 struct sockaddr_storage sspp_addr; 2191 }; 2193 sspp_addr The address to set as primary 2194 sspp_assoc_id (one-to-many style socket) This is filled in by the 2195 application, and identifies the association 2196 for this request. 2198 This functionality is optional. Implementations that do not support 2199 this functionality should return EOPNOTSUPP. 2201 7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) 2203 Requests that the local SCTP stack use the enclosed peer address as 2204 the association primary. The enclosed address must be one of the 2205 association peer's addresses. The following structure is used to make 2206 a set peer primary request: 2208 struct sctp_setprim { 2209 sctp_assoc_t ssp_assoc_id; 2210 struct sockaddr_storage ssp_addr; 2211 }; 2212 ssp_addr The address to set as primary 2213 ssp_assoc_id (one-to-many style socket) This is filled in by the 2214 application, and identifies the association 2215 for this request. 2217 7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) 2219 Requests that the local endpoint set the specified Adaption Layer 2220 Indication parameter for all future INIT and INIT-ACK exchanges. 2222 struct sctp_setadaption { 2223 uint32_t ssb_adaption_ind; 2224 }; 2226 ssb_adaption_ind The adaption layer indicator that will be included 2227 in any outgoing Adaption Layer Indication 2228 parameter. 2230 7.1.12 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2232 This option is a on/off flag and is passed an integer where a 2233 non-zero is on and a zero is off. If enabled no SCTP message 2234 fragmentation will be performed. Instead if a message being sent 2235 exceeds the current PMTU size, the message will NOT be sent and 2236 instead a error will be indicated to the user. 2238 7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2240 Applications can enable or disable heartbeats for any peer address of 2241 an association, modify an address's heartbeat interval, force a 2242 heartbeat to be sent immediately, and adjust the address's maximum 2243 number of retransmissions sent before an address is considered 2244 unreachable. The following structure is used to access and modify an 2245 address's parameters: 2247 struct sctp_paddrparams { 2248 sctp_assoc_t spp_assoc_id; 2249 struct sockaddr_storage spp_address; 2250 uint32_t spp_hbinterval; 2251 uint16_t spp_pathmaxrxt; 2252 }; 2254 spp_assoc_id - (one-to-many style socket) This is filled in the application, 2255 and identifies the association for this query. 2256 spp_address - This specifies which address is of interest. 2257 spp_hbinterval - This contains the value of the heartbeat interval, 2258 in milliseconds. A value of 0, when modifying the 2259 parameter, specifies that the heartbeat on this 2260 address should be disabled. A value of UINT32_MAX 2261 (4294967295), when modifying the parameter, 2262 specifies that a heartbeat should be sent 2263 immediately to the peer address, and the current 2264 interval should remain unchanged. 2265 spp_pathmaxrxt - This contains the maximum number of 2266 retransmissions before this address shall be 2267 considered unreachable. If a value of zero 2268 is present in this field then no changes are to 2269 be made to this parameter. 2271 To read or modify these parameters, the application should call 2272 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2274 7.1.14 Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 2276 Applications that wish to use the sendto() system call may wish to 2277 specify a default set of parameters that would normally be supplied 2278 through the inclusion of ancillary data. This socket option allows 2279 such an application to set the default sctp_sndrcvinfo structure. The 2280 application that wishes to use this socket option simply passes in to 2281 this call the sctp_sndrcvinfo structure defined in Section 5.2.2) The 2282 input parameters accepted by this call include sinfo_stream, 2283 sinfo_flags, sinfo_ppid, sinfo_context, sinfo_timetolive. The user 2284 must set the sinfo_assoc_id field to identify the association to 2285 affect if the caller is using the one-to-many style. 2287 7.1.15 Set notification and ancillary events (SCTP_EVENTS) 2289 This socket option is used to specify various notifications and 2290 ancillary data the user wishes to receive. Please see Section 7.3) 2291 for a full description of this option and its usage. 2293 7.1.16 Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2295 This socket option is a boolean flag which turns on or off mapped V4 2296 addresses. If this option is turned on and the socket is type 2297 PF_INET6, then IPv4 addresses will be mapped to V6 representation. If 2298 this option is turned off, then no mapping will be done of V4 2299 addresses and a user will receive both PF_INET6 and PF_INET type 2300 addresses on the socket. 2302 By default this option is turned on and expects an integer to be 2303 passed where non-zero turns on the option and zero turns off the 2304 option. 2306 7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) 2308 This socket option specifies the maximum size to put in any outgoing 2309 SCTP DATA chunk. If a message is larger than this size it will be 2310 fragmented by SCTP into the specified size. Note that the underlying 2311 SCTP implementation may fragment into smaller sized chunks when the 2312 PMTU of the underlying association is smaller than the value set by 2313 the user. The option expects an integer. 2315 The default value for this option is '0' which indicates the user is 2316 NOT limiting fragmentation and only the PMTU will effect SCTP's 2317 choice of DATA chunk size. 2319 7.2 Read-Only Options 2321 7.2.1 Association Status (SCTP_STATUS) 2323 Applications can retrieve current status information about an 2324 association, including association state, peer receiver window size, 2325 number of unacked data chunks, and number of data chunks pending 2326 receipt. This information is read-only. The following structure is 2327 used to access this information: 2329 struct sctp_status { 2330 sctp_assoc_t sstat_assoc_id; 2331 int32_t sstat_state; 2332 uint32_t sstat_rwnd; 2333 uint16_t sstat_unackdata; 2334 uint16_t sstat_penddata; 2335 uint16_t sstat_instrms; 2336 uint16_t sstat_outstrms; 2337 uint32_t sstat_fragmentation_point; 2338 struct sctp_paddrinfo sstat_primary; 2339 }; 2341 sstat_state - This contains the association's current state one 2342 of the following values: 2344 SCTP_CLOSED 2345 SCTP_BOUND 2346 SCTP_LISTEN 2347 SCTP_COOKIE_WAIT 2348 SCTP_COOKIE_ECHOED 2349 SCTP_ESTABLISHED 2350 SCTP_SHUTDOWN_PENDING 2351 SCTP_SHUTDOWN_SENT 2352 SCTP_SHUTDOWN_RECEIVED 2353 SCTP_SHUTDOWN_ACK_SENT 2355 sstat_rwnd - This contains the association peer's current 2356 receiver window size. 2357 sstat_unackdata - This is the number of unacked data chunks. 2358 sstat_penddata - This is the number of data chunks pending receipt. 2359 sstat_primary - This is information on the current primary peer 2360 address. 2361 sstat_assoc_id - (one-to-many style socket) This holds the an identifier for the 2362 association. All notifications for a given association 2363 have the same association identifier. 2365 sstat_instrms - The number of streams that the peer will 2366 be using inbound. 2368 sstat_outstrms - The number of streams that the endpoint is 2369 allowed to use outbound. 2371 sstat_fragmentation_point - The size at which SCTP fragmentation 2372 will occur. 2374 To access these status values, the application calls getsockopt() 2375 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2376 ignored for one-to-one style socket. 2378 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2380 Applications can retrieve information about a specific peer address 2381 of an association, including its reachability state, congestion 2382 window, and retransmission timer values. This information is 2383 read-only. The following structure is used to access this 2384 information: 2386 struct sctp_paddrinfo { 2387 sctp_assoc_t spinfo_assoc_id; 2388 struct sockaddr_storage spinfo_address; 2389 int32_t spinfo_state; 2390 uint32_t spinfo_cwnd; 2391 uint32_t spinfo_srtt; 2392 uint32_t spinfo_rto; 2393 uint32_t spinfo_mtu; 2394 }; 2396 spinfo_address - This is filled in the application, and contains 2397 the peer address of interest. 2399 On return from getsockopt(): 2401 spinfo_state - This contains the peer addresses's state (either 2402 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifer 2403 SCTP_UNCONFIRMED) 2405 spinfo_cwnd - This contains the peer addresses's current congestion 2406 window. 2407 spinfo_srtt - This contains the peer addresses's current smoothed 2408 round-trip time calculation in milliseconds. 2409 spinfo_rto - This contains the peer addresses's current 2410 retransmission timeout value in milliseconds. 2411 spinfo_mtu - The current P-MTU of this address. 2412 spinfo_assoc_id - (one-to-many style socket) This is filled in the application, 2413 and identifies the association for this query. 2415 To retrieve this information, use sctp_opt_info() with the 2416 SCTP_GET_PEER_ADDR_INFO options. 2418 7.3 Ancillary Data and Notification Interest Options 2420 Applications can receive per-message ancillary information and 2421 notifications of certain SCTP events with recvmsg(). 2423 The following optional information is available to the application: 2425 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 2426 stream number, TSN, SSN, etc. described in Section 5.2.2) 2428 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in Section 2429 5.3.1.1) 2431 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in Section 2432 5.3.1.2) 2434 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in Section 2435 5.3.1.4) 2437 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in Section 2438 5.3.1.3) 2440 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in Section 2441 5.3.1.5) 2443 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 2444 (described in Section 5.3.1.7) 2446 8. SCTP_ADAPTION_INDICATION (sctp_adaption_layer_event): (described 2447 in Section 5.3.1.6) 2449 To receive any ancillary data or notifications, first the application 2450 registers it's interest by calling the SCTP_EVENTS setsockopt() with 2451 the following structure. 2453 struct sctp_event_subscribe{ 2454 uint8_t sctp_data_io_event; 2455 uint8_t sctp_association_event; 2456 uint8_t sctp_address_event; 2457 uint8_t sctp_send_failure_event; 2458 uint8_t sctp_peer_error_event; 2459 uint8_t sctp_shutdown_event; 2460 uint8_t sctp_partial_delivery_event; 2461 uint8_t sctp_adaption_layer_event; 2462 }; 2464 sctp_data_io_event - Setting this flag to 1 will cause the reception 2465 of SCTP_SNDRCV information on a per message basis. The application 2466 will need to use the recvmsg() interface so that it can receive the 2467 event information contained in the msg_control field. Please see 2468 Section 5.2 for further details. Setting the flag to 0 will disable 2469 reception of the message control information. 2471 sctp_association_event - Setting this flag to 1 will enable the 2472 reception of association event notifications. Setting the flag to 0 2473 will disable association event notifications. For more information on 2474 event notifications please see Section 5.3. 2476 sctp_address_event - Setting this flag to 1 will enable the reception 2477 of address event notifications. Setting the flag to 0 will disable 2478 address event notifications. For more information on event 2479 notifications please see Section 5.3. 2481 sctp_send_failure_event - Setting this flag to 1 will enable the 2482 reception of send failure event notifications. Setting the flag to 0 2483 will disable send failure event notifications. For more information 2484 on event notifications please see Section 5.3. 2486 sctp_peer_error_event - Setting this flag to 1 will enable the 2487 reception of peer error event notifications. Setting the flag to 0 2488 will disable peer error event notifications. For more information on 2489 event notifications please see Section 5.3. 2491 sctp_shutdown_event - Setting this flag to 1 will enable the 2492 reception of shutdown event notifications. Setting the flag to 0 will 2493 disable shutdown event notifications. For more information on event 2494 notifications please see Section 5.3. 2496 sctp_partial_delivery_event - Setting this flag to 1 will enable the 2497 reception of partial delivery notifications. Setting the flag to 0 2498 will disable partial delivery event notifications. For more 2499 information on event notifications please see Section 5.3. 2501 sctp_adaption_layer_event - Setting this flag to 1 will enable the 2502 reception of adaption layer notifications. Setting the flag to 0 will 2503 disable adaption layer event notifications. For more information on 2504 event notifications please see Section 5.3. 2506 An example where an application would like to receive data io events 2507 and association events but no others would be as follows: 2509 { 2510 struct sctp_event_subscribe event; 2512 memset(&event,0,sizeof(event)); 2514 event.sctp_data_io_event = 1; 2515 event.sctp_association_event = 1; 2517 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2518 } 2520 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2521 receives ancillary data and notifications for ALL associations bound 2522 to the file descriptor. For one-to-one style SCTP sockets, the 2523 caller receives ancillary data and notifications for only the single 2524 association bound to the file descriptor. 2526 By default both the one-to-one style and one-to-many style socket has 2527 all options off. 2529 8. New Interfaces 2531 Depending on the system, the following interface can be implemented 2532 as a system call or library function. 2534 8.1 sctp_bindx() 2536 The syntax of sctp_bindx() is, 2538 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt, 2539 int flags); 2541 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 2542 If the sd is an IPv6 socket, the addresses passed can either be IPv4 2543 or IPv6 addresses. 2545 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2546 Section 3.1.2 for this usage. 2548 addrs is a pointer to an array of one or more socket addresses. Each 2549 address is contained in its appropriate structure. For an IPv6 2550 socket, an array of sockaddr_in6 would be returned. For a IPv4 2551 socket, an array of sockaddr_in would be returned. The caller 2552 specifies the number of addresses in the array with addrcnt. 2554 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2555 -1, and sets errno to the appropriate error code. 2557 For SCTP, the port given in each socket address must be the same, or 2558 sctp_bindx() will fail, setting errno to EINVAL. 2560 The flags parameter is formed from the bitwise OR of zero or more of 2561 the following currently defined flags: 2563 SCTP_BINDX_ADD_ADDR 2565 SCTP_BINDX_REM_ADDR 2567 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2568 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 2569 addresses from the association. The two flags are mutually exclusive; 2570 if both are given, sctp_bindx() will fail with EINVAL. A caller may 2571 not remove all addresses from an association; sctp_bindx() will 2572 reject such an attempt with EINVAL. 2574 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2575 additional addresses with an endpoint after calling bind(). Or use 2576 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2577 socket is associated with so that no new association accepted will be 2578 associated with those addresses. If the endpoint supports dynamic 2579 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 2580 endpoint to send the appropriate message to the peer to change the 2581 peers address lists. 2583 Adding and removing addresses from a connected association is 2584 optional functionality. Implementations that do not support this 2585 functionality should return EOPNOTSUPP. 2587 8.2 Branched-off Association 2589 After an association is established on a one-to-many style socket, 2590 the application may wish to branch off the association into a 2591 separate socket/file descriptor. 2593 This is particularly desirable when, for instance, the application 2594 wishes to have a number of sporadic message senders/receivers remain 2595 under the original one-to-many style socket but branch off those 2596 associations carrying high volume data traffic into their own 2597 separate socket descriptors. 2599 The application uses sctp_peeloff() call to branch off an association 2600 into a separate socket (Note the semantics are somewhat changed from 2601 the traditional one-to-one style accept() call). Note that the new 2602 socket is a one-to-one style socket. Thus it will be confined to 2603 operations allowed for a one-to-one style socket. 2605 The syntax is: 2607 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id); 2609 the new socket descriptor representing the branched-off 2610 association. 2612 the original one-to-many style socket descriptor returned from the 2613 socket() system call (see Section 3.1.1). 2615 the specified identifier of the association that is to be branched 2616 off to a separate file descriptor (Note, in a traditional 2617 one-to-one style accept() call, this would be an out parameter, 2618 but for the one-to-many style call, this is an in parameter). 2620 8.3 sctp_getpaddrs() 2622 sctp_getpaddrs() returns all peer addresses in an association. The 2623 syntax is, 2624 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2625 struct sockaddr **addrs); 2627 On return, addrs will point to an array dynamically allocated 2628 sockaddr structures of the appropriate type for the socket type. The 2629 caller should use sctp_freepaddrs() to free the memory. Note that the 2630 in/out parameter addrs must not be NULL. 2632 If sd is an IPv4 socket, the addresses returned will be all IPv4 2633 addresses. If sd is an IPv6 socket, the addresses returned can be a 2634 mix of IPv4 or IPv6 addresses. 2636 For one-to-many style sockets, id specifies the association to query. 2637 For one-to-one style sockets, id is ignored. 2639 On success, sctp_getpaddrs() returns the number of peer addresses in 2640 the association. If there is no association on this socket, 2641 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2642 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 2643 is undefined. 2645 8.4 sctp_freepaddrs() 2647 sctp_freepaddrs() frees all resources allocated by 2648 sctp_getpaddrs(). Its syntax is, 2650 void sctp_freepaddrs(struct sockaddr *addrs); 2652 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2654 8.5 sctp_getladdrs() 2656 sctp_getladdrs() returns all locally bound address(es) on a socket. 2657 The syntax is, 2659 int sctp_getladdrs(int sd, sctp_assoc_t id, 2660 struct sockaddr **ss); 2662 On return, addrs will point to a dynamically allocated array of 2663 sockaddr structures of the appropriate type for the socket type. The 2664 caller should use sctp_freeladdrs() to free the memory. Note that the 2665 in/out parameter addrs must not be NULL. 2667 If sd is an IPv4 socket, the addresses returned will be all IPv4 2668 addresses. If sd is an IPv6 socket, the addresses returned can be a 2669 mix of IPv4 or IPv6 addresses. 2671 For one-to-many style sockets, id specifies the association to query. 2672 For one-to-one style sockets, id is ignored. 2674 If the id field is set to the value '0' then the locally bound 2675 addresses are returned without regard to any particular association. 2677 On success, sctp_getladdrs() returns the number of local addresses 2678 bound to the socket. If the socket is unbound, sctp_getladdrs() 2679 returns 0, and the value of *addrs is undefined. If an error occurs, 2680 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2682 8.6 sctp_freeladdrs() 2684 sctp_freeladdrs() frees all resources allocated by 2685 sctp_getladdrs(). Its syntax is, 2687 void sctp_freeladdrs(struct sockaddr *addrs); 2689 addrs is the array of peer addresses returned by sctp_getladdrs(). 2691 8.7 sctp_sendmsg() 2693 An implementation may provide a library function (or possibly system 2694 call) to assist the user with the advanced features of SCTP. 2696 sctp_sendmsg(). Its syntax is, 2698 ssize_t sctp_sendmsg(int sd, 2699 const void *msg, 2700 size_t len, 2701 const struct sockaddr *to, 2702 socklen_t tolen, 2703 uint32_t ppid, 2704 uint32_t flags, 2705 uint16_t stream_no, 2706 uint32_t timetolive, 2707 uint32_t context) 2709 sd - is the socket descriptor 2710 msg - is the message to be sent. 2711 len - is the length of the message. 2712 to - is the destination address of the message. 2713 tolen - is the length of the destination address. 2714 ppid - is the same as sinfo_ppid (see section 5.2.2) 2715 flags - is the same as sinfo_flags (see section 5.2.2) 2716 stream_no - is the same as sinfo_stream (see section 5.2.2) 2717 timetolive - is the same as sinfo_timetolive (see section 5.2.2) 2718 context - is the same as sinfo_context (see section 5.2.2) 2720 8.8 sctp_recvmsg() 2722 An implementation may provide a library function (or possibly system 2723 call) to assist the user with the advanced features of SCTP. Note 2724 that in order for the sctp_sndrcvinfo structure to be filled in by 2725 sctp_recvmsg() the caller must enable the sctp_data_io_events with 2726 the SCTP_EVENTS option. 2728 sctp_recvmsg(). Its syntax is, 2730 ssize_t sctp_recvmsg(int sd, 2731 void *msg, 2732 size_t len, 2733 struct sockaddr *from, 2734 socklen_t *fromlen 2735 struct sctp_sndrcvinfo *sinfo 2736 int *msg_flags) 2738 sd - is the socket descriptor 2739 msg - is a message buffer to be filled. 2740 len - is the length of the message buffer. 2741 from - is a pointer to a address to be filled with 2742 the sender of this messages address. 2743 fromlen - is the from length. 2744 sinfo - A pointer to a sctp_sndrcvinfo structure 2745 to be filled upon receipt of the message. 2746 msg_flags - A pointer to a integer to be filled with 2747 any message flags (e.g. MSG_NOTIFICATION). 2749 8.9 sctp_connectx() 2751 An implementation may provide a library function (or possibly system 2752 call) to assist the user with associating to an endpoint that is 2753 multi-homed. Much like sctp_bindx() this call allows a caller to 2754 specify multiple addresses at which a peer can be reached. The way 2755 the SCTP stack uses the list of addresses to set up the association 2756 is implementation dependant. This function only specifies that the 2757 stack will try to make use of all the addresses in the list when 2758 needed. 2760 Note that the list of addresses passed in is only used for setting up 2761 the association. It does not necessarily equal the set of addresses 2762 the peer uses for the resulting association. If the caller wants to 2763 find out the set of peer addresses, it must use sctp_getpaddrs() to 2764 retrieve them after the association has been set up. 2766 sctp_connectx(). Its syntax is, 2768 int sctp_connectx(int sd, 2769 struct sockaddr *addrs, 2770 int addrcnt) 2772 sd - is the socket descriptor 2773 addrs - is an array of addresses. 2775 addrcnt - is the number of addresses in the array. 2777 8.10 sctp_send() 2779 An implementation may provide another alternative function or system 2780 call to assist an application with the sending of data without the 2781 use of the CMSG header structures. The function takes the following 2782 form: 2784 sctp_send(). Its syntax is, 2786 int sctp_send(int sd, 2787 const void *msg, 2788 size_t len, 2789 const struct sctp_sndrcvinfo *sinfo, 2790 int flags); 2792 sd - is the socket descriptor 2793 msg - The message to be sent 2794 len - The length of the message 2795 sinfo - A pointer to a sctp_sndrcvinfo struture used 2796 as described in 5.2.2 for a sendmsg call. 2797 flags - is used in the same format as the sendmsg call 2798 flags (e.g. MSG_DONTROUTE). 2800 This function call may also be used to terminate an association using 2801 an association identification by setting the sinfo.sinfo_flags to 2802 MSG_EOF and the sinfo.sinf_associd to the association that needs to 2803 be terminated. In such a case the len of the message would be zero. 2805 9. Preprocessor Constants 2807 For application portability it is desireable to define pre-processor 2808 constants for determination if sctp is present and supports various 2809 features. The following pre-processor constants should be defined in 2810 a include file, sctp.h. 2812 HAVE_SCTP - If this constant is defined to 1, then an implementation 2813 of SCTP is available. 2815 HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel 2816 SCTP implementation is available through the sockets interface. 2818 HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP 2819 implementation supports the partial reliablility extension to 2820 SCTP. 2822 HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP 2823 implementation supports the dynamic address extension to SCTP. 2825 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the 2826 SCTP implementation supports the ability to request setting of the 2827 remote primary address. 2829 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1, 2830 then the SCTP implementation supports the satellite network 2831 extension to SCTP. 2833 HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP 2834 implementation dedicates separate buffer space to each association 2835 on a one-to-many socket. If this constant is defined to 0, then 2836 the implementation provides a single block of shared buffer space 2837 for a one-to-many socket. 2839 HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the SCTP 2840 implementation supports initiating an association on a one-to-one 2841 style socket without the use of connect(), as outlined in Section 2842 4.1.5. 2844 10. Security Considerations 2846 Many TCP and UDP implementations reserve port numbers below 1024 for 2847 privileged users. If the target platform supports privileged users, 2848 the SCTP implementation SHOULD restrict the ability to call bind() or 2849 sctp_bindx() on these port numbers to privileged users. 2851 Similarly unpriviledged users should not be able to set protocol 2852 parameters which could result in the congestion control algorithm 2853 being more aggressive than permitted on the public Internet. These 2854 parameters are: 2856 struct sctp_rtoinfo 2858 If an unprivileged user inherits a one-to-many style socket with open 2859 associations on a privileged port, it MAY be permitted to accept new 2860 associations, but it SHOULD NOT be permitted to open new 2861 associations. This could be relevant for the r* family of protocols. 2863 11. Acknowledgments 2865 The authors wish to thank Kavitha Baratakke, Mike Bartlett, Jon 2866 Berger, Scott Kimble, Renee Revis, and many others on the TSVWG 2867 mailing list for contributing valuable comments. 2869 A special thanks to Phillip Conrad, for his suggested text, quick and 2870 constructive insights, and most of all his persistent fighting to 2871 keep the interface to SCTP usable for the application programmer. 2873 References 2875 [1] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2876 September 1981. 2878 [2] Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 2879 1980. 2881 [3] Braden, B., "T/TCP -- TCP Extensions for Transactions Functional 2882 Specification", RFC 1644, July 1994. 2884 [4] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 2885 9, RFC 2026, October 1996. 2887 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2888 Levels", BCP 14, RFC 2119, March 1997. 2890 [6] Stevens, W. and M. Thomas, "Advanced Sockets API for IPv6", RFC 2891 2292, February 1998. 2893 [7] Gilligan, R., Thomson, S., Bound, J. and W. Stevens, "Basic 2894 Socket Interface Extensions for IPv6", RFC 2553, March 1999. 2896 [8] Stewart, R., Xie, Q., Morneault, K., Sharp, C., Schwarzbauer, 2897 H., Taylor, T., Rytina, I., Kalla, M., Zhang, L. and V. Paxson, 2898 "Stream Control Transmission Protocol", RFC 2960, October 2000. 2900 Authors' Addresses 2902 Randall R. Stewart 2903 Cisco Systems, Inc. 2904 8725 West Higgins Road 2905 Suite 300 2906 Chicago, IL 60631 2907 USA 2909 Phone: 2910 EMail: rrs@cisco.com 2911 Qiaobing Xie 2912 Motorola, Inc. 2913 1501 W. Shure Drive, #2309 2914 Arlington Heights, IL 60004 2915 USA 2917 Phone: 2918 EMail: qxie1@email.mot.com 2920 La Monte H.P. Yarroll 2921 USACE ERDC-CERL. 2922 2902 Newmark Drive 2923 Champaign, IL 6182-1076 2924 USA 2926 Phone: 2927 EMail: piggy@acm.org 2929 Jonathan Wood 2930 DoCoMo USA Labs 2931 181 Metro Drive, Suite 300 2932 San Jose, CA 95110 2933 USA 2935 Phone: 2936 EMail: jonwood@speakeasy.net 2938 Kacheong Poon 2939 Sun Microsystems, Inc. 2940 4150 Network Circle 2941 Santa Clara, CA 95054 2942 USA 2944 Phone: 2945 EMail: kacheong.poon@sun.com 2947 Ken Fujita 2948 NEC USA, Inc. 2949 10080 Wolfe Road, Suite SW3-350 2950 Cupertino, CA 95014 2951 USA 2953 Phone: 2954 EMail: fken@ccrl.sj.nec.com 2955 Michael Tuexen 2956 Univ. of Applied Sciences Muenster 2957 Stegerwaldstr. 39 2958 48565 Steinfurt 2959 Germany 2961 EMail: tuexen@fh-muenster.de 2963 Appendix A. one-to-one style Code Example 2965 The following code is a simple implementation of an echo server over 2966 SCTP. The example shows how to use some features of one-to-one style 2967 IPv4 SCTP sockets, including: 2969 o Opening, binding, and listening for new associations on a socket; 2971 o Enabling ancillary data 2973 o Enabling notifications 2975 o Using ancillary data with sendmsg() and recvmsg() 2977 o Using MSG_EOR to determine if an entire message has been read 2979 o Handling notifications 2981 #include 2982 #include 2983 #include 2984 #include 2985 #include 2986 #include 2987 #include 2988 #include 2989 #include 2991 #define BUFLEN 100 2993 static void 2994 handle_event(void *buf) 2995 { 2996 struct sctp_assoc_change *sac; 2997 struct sctp_send_failed *ssf; 2998 struct sctp_paddr_change *spc; 2999 struct sctp_remote_error *sre; 3000 union sctp_notification *snp; 3001 char addrbuf[INET6_ADDRSTRLEN]; 3002 const char *ap; 3003 struct sockaddr_in *sin; 3004 struct sockaddr_in6 *sin6; 3006 snp = buf; 3008 switch (snp->sn_header.sn_type) { 3009 case SCTP_ASSOC_CHANGE: 3011 sac = &snp->sn_assoc_change; 3012 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 3013 "outstr=%hu\n", sac->sac_state, sac->sac_error, 3014 sac->sac_inbound_streams, sac->sac_outbound_streams); 3015 break; 3016 case SCTP_SEND_FAILED: 3017 ssf = &snp->sn_send_failed; 3018 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 3019 ssf->ssf_error); 3020 break; 3022 case SCTP_PEER_ADDR_CHANGE: 3023 spc = &snp->sn_paddr_change; 3024 if (spc->spc_aaddr.ss_family == AF_INET) { 3025 sin = (struct sockaddr_in *)&spc->spc_aaddr; 3026 ap = inet_ntop(AF_INET, &sin->sin_addr, 3027 addrbuf, INET6_ADDRSTRLEN); 3028 } else { 3029 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 3030 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 3031 addrbuf, INET6_ADDRSTRLEN); 3032 } 3033 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 3034 spc->spc_state, spc->spc_error); 3035 break; 3036 case SCTP_REMOTE_ERROR: 3037 sre = &snp->sn_remote_error; 3038 printf("^^^ remote_error: err=%hu len=%hu\n", 3039 ntohs(sre->sre_error), ntohs(sre->sre_length)); 3040 break; 3041 case SCTP_SHUTDOWN_EVENT: 3042 printf("^^^ shutdown event\n"); 3043 break; 3044 default: 3045 printf("unknown type: %hu\n", snp->sn_header.sn_type); 3046 break; 3047 } 3048 } 3050 static void * 3051 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 3052 ssize_t *nrp, size_t cmsglen) 3053 { 3054 ssize_t nr = 0, nnr = 0; 3055 struct iovec iov[1]; 3057 *nrp = 0; 3058 iov->iov_base = buf; 3059 iov->iov_len = *buflen; 3060 msg->msg_iov = iov; 3061 msg->msg_iovlen = 1; 3063 for (;;) { 3064 #ifndef MSG_XPG4_2 3065 #define MSG_XPG4_2 0 3066 #endif 3067 msg->msg_flags = MSG_XPG4_2; 3068 msg->msg_controllen = cmsglen; 3070 nnr = recvmsg(fd, msg, 0); 3071 if (nnr <= 0) { 3072 /* EOF or error */ 3073 *nrp = nr; 3074 return (NULL); 3075 } 3076 nr += nnr; 3078 if ((msg->msg_flags & MSG_EOR) != 0) { 3079 *nrp = nr; 3080 return (buf); 3081 } 3083 /* Realloc the buffer? */ 3084 if (*buflen == (size_t)nr) { 3085 buf = realloc(buf, *buflen * 2); 3086 if (buf == 0) { 3087 fprintf(stderr, "out of memory\n"); 3088 exit(1); 3089 } 3090 *buflen *= 2; 3091 } 3093 /* Set the next read offset */ 3094 iov->iov_base = (char *)buf + nr; 3095 iov->iov_len = *buflen - nr; 3097 } 3098 } 3100 static void 3101 echo(int fd, int socketModeone_to_many) 3102 { 3103 ssize_t nr; 3104 struct sctp_sndrcvinfo *sri; 3105 struct msghdr msg[1]; 3106 struct cmsghdr *cmsg; 3107 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3108 char *buf; 3109 size_t buflen; 3110 struct iovec iov[1]; 3111 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3113 /* Allocate the initial data buffer */ 3114 buflen = BUFLEN; 3115 if (!(buf = malloc(BUFLEN))) { 3116 fprintf(stderr, "out of memory\n"); 3117 exit(1); 3118 } 3120 /* Set up the msghdr structure for receiving */ 3121 memset(msg, 0, sizeof (*msg)); 3122 msg->msg_control = cbuf; 3123 msg->msg_controllen = cmsglen; 3124 msg->msg_flags = 0; 3125 cmsg = (struct cmsghdr *)cbuf; 3126 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3128 /* Wait for something to echo */ 3129 while (buf = mysctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 3131 /* Intercept notifications here */ 3132 if (msg->msg_flags & MSG_NOTIFICATION) { 3133 handle_event(buf); 3134 continue; 3135 } 3137 iov->iov_base = buf; 3138 iov->iov_len = nr; 3139 msg->msg_iov = iov; 3140 msg->msg_iovlen = 1; 3142 printf("got %u bytes on stream %hu:\n", nr, 3143 sri->sinfo_stream); 3144 write(0, buf, nr); 3146 /* Echo it back */ 3147 msg->msg_flags = MSG_XPG4_2; 3148 if (sendmsg(fd, msg, 0) < 0) { 3149 perror("sendmsg"); 3150 exit(1); 3151 } 3152 } 3153 if (nr < 0) { 3154 perror("recvmsg"); 3155 } 3156 if(socketModeone_to_many == 0) 3157 close(fd); 3158 } 3160 int main() 3161 { 3162 struct sctp_event_subscribe event; 3163 int lfd, cfd; 3164 int onoff = 1; 3165 struct sockaddr_in sin[1]; 3167 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3168 perror("socket"); 3169 exit(1); 3170 } 3172 sin->sin_family = AF_INET; 3173 sin->sin_port = htons(7); 3174 sin->sin_addr.s_addr = INADDR_ANY; 3175 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3176 perror("bind"); 3177 exit(1); 3178 } 3180 if (listen(lfd, 1) == -1) { 3181 perror("listen"); 3182 exit(1); 3183 } 3185 /* Wait for new associations */ 3186 for (;;) { 3187 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3188 perror("accept"); 3189 exit(1); 3190 } 3192 /* Enable all events */ 3193 event.sctp_data_io_event = 1; 3194 event.sctp_association_event = 1; 3195 event.sctp_address_event = 1; 3196 event.sctp_send_failure_event = 1; 3197 event.sctp_peer_error_event = 1; 3198 event.sctp_shutdown_event = 1; 3199 event.sctp_partial_delivery_event = 1; 3200 event.sctp_adaption_layer_event = 1; 3201 if (setsockopt(cfd, IPPROTO_SCTP, 3202 SCTP_EVENTS, &event, 3203 sizeof(event)) != 0) { 3204 perror("setevent failed"); 3205 exit(1); 3206 } 3207 /* Echo back any and all data */ 3208 echo(cfd,0); 3209 } 3210 } 3212 Appendix B. one-to-many style Code Example 3214 The following code is a simple implementation of an echo server over 3215 SCTP. The example shows how to use some features of one-to-many style 3216 IPv4 SCTP sockets, including: 3218 o Opening and binding of a socket; 3220 o Enabling ancillary data 3222 o Enabling notifications 3224 o Using ancillary data with sendmsg() and recvmsg() 3226 o Using MSG_EOR to determine if an entire message has been read 3228 o Handling notifications 3230 Note most functions defined in Appendix A are reused in this example. 3232 int main() 3233 { 3234 int fd; 3235 int idleTime = 2; 3236 struct sockaddr_in sin[1]; 3237 struct sctp_event_subscribe event; 3239 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3240 perror("socket"); 3241 exit(1); 3242 } 3244 sin->sin_family = AF_INET; 3245 sin->sin_port = htons(7); 3246 sin->sin_addr.s_addr = INADDR_ANY; 3247 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3248 perror("bind"); 3249 exit(1); 3250 } 3252 /* Enable all notifications and events */ 3253 event.sctp_data_io_event = 1; 3254 event.sctp_association_event = 1; 3255 event.sctp_address_event = 1; 3256 event.sctp_send_failure_event = 1; 3257 event.sctp_peer_error_event = 1; 3258 event.sctp_shutdown_event = 1; 3259 event.sctp_partial_delivery_event = 1; 3260 event.sctp_adaption_layer_event = 1; 3261 if (setsockopt(fd, IPPROTO_SCTP, 3262 SCTP_EVENTS, &event, 3263 sizeof(event)) != 0) { 3264 perror("setevent failed"); 3265 exit(1); 3266 } 3267 /* Set associations to auto-close in 2 seconds of 3268 * inactivity 3269 */ 3270 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3271 &idleTime, 4) < 0) { 3272 perror("setsockopt SCTP_AUTOCLOSE"); 3273 exit(1); 3274 } 3276 /* Allow new associations to be accepted */ 3277 if (listen(fd, 1) < 0) { 3278 perror("listen"); 3279 exit(1); 3280 } 3282 /* Wait for new associations */ 3283 while(1){ 3284 /* Echo back any and all data */ 3285 echo(fd,1); 3286 } 3287 } 3289 Intellectual Property Statement 3291 The IETF takes no position regarding the validity or scope of any 3292 intellectual property or other rights that might be claimed to 3293 pertain to the implementation or use of the technology described in 3294 this document or the extent to which any license under such rights 3295 might or might not be available; neither does it represent that it 3296 has made any effort to identify any such rights. Information on the 3297 IETF's procedures with respect to rights in standards-track and 3298 standards-related documentation can be found in BCP-11. Copies of 3299 claims of rights made available for publication and any assurances of 3300 licenses to be made available, or the result of an attempt made to 3301 obtain a general license or permission for the use of such 3302 proprietary rights by implementors or users of this specification can 3303 be obtained from the IETF Secretariat. 3305 The IETF invites any interested party to bring to its attention any 3306 copyrights, patents or patent applications, or other proprietary 3307 rights which may cover technology that may be required to practice 3308 this standard. Please address the information to the IETF Executive 3309 Director. 3311 Full Copyright Statement 3313 Copyright (C) The Internet Society (2004). All Rights Reserved. 3315 This document and translations of it may be copied and furnished to 3316 others, and derivative works that comment on or otherwise explain it 3317 or assist in its implementation may be prepared, copied, published 3318 and distributed, in whole or in part, without restriction of any 3319 kind, provided that the above copyright notice and this paragraph are 3320 included on all such copies and derivative works. However, this 3321 document itself may not be modified in any way, such as by removing 3322 the copyright notice or references to the Internet Society or other 3323 Internet organizations, except as needed for the purpose of 3324 developing Internet standards in which case the procedures for 3325 copyrights defined in the Internet Standards process must be 3326 followed, or as required to translate it into languages other than 3327 English. 3329 The limited permissions granted above are perpetual and will not be 3330 revoked by the Internet Society or its successors or assignees. 3332 This document and the information contained herein is provided on an 3333 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3334 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3335 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3336 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3337 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3339 Acknowledgment 3341 Funding for the RFC Editor function is currently provided by the 3342 Internet Society.