idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-07.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 858 has weird spacing: '...n. The value...' == Line 870 has weird spacing: '...er send and ...' == Line 1038 has weird spacing: '...g_level cms...' == Line 1092 has weird spacing: '...g_level cms...' == Line 1246 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 (August 22, 2003) is 7554 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 1515, but not defined == Unused Reference: '4' is defined on line 2805, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 2808, 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: February 20, 2004 Q. Xie 5 Motorola, Inc. 6 L. Yarroll 7 USACE ERDC-CERL. 8 J. Wood 9 DoCoMo USA Labs 10 K. Poon 11 Consultant 12 K. Fujita 13 NEC USA, Inc. 14 M. Tuexen 15 Univ. of Applied Sciences Muenster 16 August 22, 2003 18 Sockets API Extensions for Stream Control Transmission Protocol 19 (SCTP) 20 draft-ietf-tsvwg-sctpsocket-07.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 February 20, 2004. 44 Copyright Notice 46 Copyright (C) The Internet Society (2003). 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 . . . . . . . . . . . . 8 63 3.1.3 listen() - One-to-many style socket . . . . . . . . . . . 9 64 3.1.4 sendmsg() and recvmsg() - one-to-many style socket . . . . 10 65 3.1.5 close() - one-to-many style socket . . . . . . . . . . . . 11 66 3.1.6 connect() - one-to-many style socket . . . . . . . . . . . 12 67 3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 12 68 3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 69 3.4 Special considerations . . . . . . . . . . . . . . . . . . 14 70 4. one-to-one style Interface . . . . . . . . . . . . . . . . 16 71 4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 16 72 4.1.1 socket() - one-to-one style socket . . . . . . . . . . . . 17 73 4.1.2 bind() - one-to-one style socket . . . . . . . . . . . . . 17 74 4.1.3 listen() - one-to-one style socket . . . . . . . . . . . . 18 75 4.1.4 accept() - one-to-one style socket . . . . . . . . . . . . 19 76 4.1.5 connect() - one-to-one style socket . . . . . . . . . . . 19 77 4.1.6 close() - one-to-one style socket . . . . . . . . . . . . 20 78 4.1.7 shutdown() - one-to-one style socket . . . . . . . . . . . 20 79 4.1.8 sendmsg() and recvmsg() - one-to-one style socket . . . . 21 80 4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 22 81 5. Data Structures . . . . . . . . . . . . . . . . . . . . . 23 82 5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 23 83 5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 24 84 5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 25 85 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 26 86 5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 28 87 5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 29 88 5.4 Ancillary Data Considerations and Semantics . . . . . . . 38 89 5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 38 90 5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 39 91 5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 39 92 6. Common Operations for Both Styles . . . . . . . . . . . . 41 93 6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 41 94 6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 42 95 6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 42 96 6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 42 97 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 44 98 7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 45 99 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 45 100 7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 46 101 7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 47 102 7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 48 103 7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 48 104 7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 48 105 7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 48 106 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 49 107 7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 49 108 7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . . . 49 109 7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) . . . . 50 110 7.1.12 Enable/Disable message fragmentation 111 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 50 112 7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . . . 50 113 7.1.14 Set default send parameters (SCTP_DEFAULT_SEND_PARAM) . . 51 114 7.1.15 Set notification and ancillary events (SCTP_EVENTS) . . . 51 115 7.1.16 Set/clear IPv4 mapped addresses 116 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . . . 51 117 7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) . . . . . 52 118 7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 52 119 7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 52 120 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 53 121 7.3 Ancillary Data and Notification Interest Options . . . . . 54 122 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 57 123 8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 57 124 8.2 Branched-off Association . . . . . . . . . . . . . . . . . 58 125 8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 58 126 8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 59 127 8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 59 128 8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 60 129 8.7 sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 60 130 8.8 sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 61 131 8.9 sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 61 132 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . 63 133 10. Security Considerations . . . . . . . . . . . . . . . . . 64 134 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 65 135 References . . . . . . . . . . . . . . . . . . . . . . . . 66 136 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 66 137 A. one-to-one style Code Example . . . . . . . . . . . . . . 69 138 B. one-to-many style Code Example . . . . . . . . . . . . . . 75 139 Intellectual Property and Copyright Statements . . . . . . 77 141 1. Introduction 143 The sockets API has provided a standard mapping of the Internet 144 Protocol suite to many operating systems. Both TCP RFC793 [1] and UDP 145 RFC768 [2] have benefited from this standard representation and 146 access method across many diverse platforms. SCTP is a new protocol 147 that provides many of the characteristics of TCP but also 148 incorporates semantics more akin to UDP. This document defines a 149 method to map the existing sockets API for use with SCTP, providing 150 both a base for access to new features and compatibility so that most 151 existing TCP applications can be migrated to SCTP with few (if any) 152 changes. 154 There are three basic design objectives: 156 1) Maintain consistency with existing sockets APIs: 158 We define a sockets mapping for SCTP that is consistent with other 159 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 160 IPv6). 162 2) Support a one-to-many style interface 164 This set of semantics is similar to that defined for connection 165 less protocols, such as UDP. It is more efficient than a TCP-like 166 connection-oriented (the one-to-one style) interface in terms of 167 exploring the new features of SCTP. But the one-to-one style 168 interface can also make use of most new SCTP features. 170 Note that SCTP is connection-oriented in nature, and it does not 171 support broadcast or multicast communications, as UDP does. 173 3) Support a one-to-one style interface 175 This interface supports a similar semantics as sockets for 176 connection-oriented protocols, such as TCP. 178 The purpose of defining this interface is to allow existing 179 applications built on connection-oriented protocols be ported to 180 use SCTP with very little effort, and developers familiar with 181 those semantics can easily adapt to SCTP. 183 Extensions are added to this mapping to provide mechanisms to 184 exploit new features of SCTP. 186 Goals 2 and 3 are not compatible, so in this document we define two 187 modes of mapping, namely the one-to-many style mapping and the 188 one-to-one style mapping. These two modes share some common data 189 structures and operations, but will require the use of two different 190 application programming styles. 192 A mechanism is defined to extract a one-to-many style SCTP 193 association into a one-to-one style socket. 195 Some of the SCTP mechanisms cannot be adequately mapped to existing 196 socket interface. In some cases, it is more desirable to have new 197 interface instead of using existing socket calls. This document also 198 describes those new interface. 200 2. Conventions 202 2.1 Data Types 204 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 205 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 206 (e.g., uint16_t). We also assume the argument data types from 207 1003.1g when possible (e.g., the final argument to setsockopt() is a 208 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 209 size_t data type is used. 211 3. one-to-many style Interface 213 The one-to-many style interface has the following characteristics: 215 A) Outbound association setup is implicit. 217 B) Messages are delivered in complete messages (with one notable 218 exception). 220 C) There is a 1 to MANY relationship between socket and association. 222 3.1 Basic Operation 224 A typical server in this style uses the following socket calls in 225 sequence to prepare an endpoint for servicing requests: 227 1. socket() 229 2. bind() 231 3. listen() 233 4. recvmsg() 235 5. sendmsg() 237 6. close() 239 A typical client uses the following calls in sequence to setup an 240 association with a server to request services: 242 1. socket() 244 2. sendmsg() 246 3. recvmsg() 248 4. close() 250 In this style, by default, all the associations connected to the 251 endpoint are represented with a single socket. 253 If the server or client wishes to branch an existing association off 254 to a separate socket, it is required to call sctp_peeloff() and in 255 the parameter specifies the association identification. The 256 sctp_peeloff() call will return a new socket which can then be used 257 with recv() and send() functions for message passing. See Section 8.2 258 for more on branched-off associations. 260 Once an association is branched off to a separate socket, it becomes 261 completely separated from the original socket. All subsequent 262 control and data operations to that association must be done through 263 the new socket. For example, the close operation on the original 264 socket will not terminate any associations that have been branched 265 off to a different socket. 267 We will discuss the one-to-many style socket calls in more details in 268 the following subsections. 270 3.1.1 socket() - one-to-many style socket 272 Applications use socket() to create a socket descriptor to represent 273 an SCTP endpoint. 275 The syntax is, 277 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 279 or, 281 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 283 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style 284 socket. 286 The first form creates an endpoint which can use only IPv4 addresses, 287 while, the second form creates an endpoint which can use both IPv6 288 and IPv4 addresses. 290 3.1.2 bind() - one-to-many style socket 292 Applications use bind() to specify which local address the SCTP 293 endpoint should associate itself with. 295 An SCTP endpoint can be associated with multiple addresses. To do 296 this, sctp_bindx() is introduced in section Section 8.1 to help 297 applications do the job of associating multiple addresses. 299 These addresses associated with a socket are the eligible transport 300 addresses for the endpoint to send and receive data. The endpoint 301 will also present these addresses to its peers during the association 302 initialization process, see RFC2960 [8]. 304 After calling bind() or sctp_bindx(), if the endpoint wishes to 305 accept new associations on the socket, it must call listen() (see 306 section Section 3.1.3). 308 The syntax of bind() is, 310 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 312 sd: the socket descriptor returned by socket(). 314 addr: the address structure (struct sockaddr_in or struct 315 sockaddr_in6 RFC2553 [7]). 317 addrlen: the size of the address structure. 319 If sd is an IPv4 socket, the address passed must be an IPv4 address. 320 If the sd is an IPv6 socket, the address passed can either be an IPv4 321 or an IPv6 address. 323 Applications cannot call bind() multiple times to associate multiple 324 addresses to an endpoint. After the first call to bind(), all 325 subsequent calls will return an error. 327 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 328 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 329 operating system will associate the endpoint with an optimal address 330 set of the available interfaces. 332 If a bind() or sctp_bindx() is not called prior to a sendmsg() call 333 that initiates a new association, the system picks an ephemeral port 334 and will choose an address set equivalent to binding with a wildcard 335 address. One of those addresses will be the primary address for the 336 association. This automatically enables the multi-homing capability 337 of SCTP. 339 3.1.3 listen() - One-to-many style socket 341 By default, new associations are not accepted for one-to-many style 342 sockets. An application uses listen() to mark a socket as being able 343 to accept new associations. The syntax is, 345 int listen(int socket, int backlog); 346 socket - the socket descriptor of the endpoint. 347 backlog - if backlog is non-zero, enable listening else 348 disable listening. 350 Note that one-to-many style socket consumers do not need to call 351 accept to retrieve new associations. Calling accept() on a 352 one-to-many style socket should return EOPNOTSUPP. Rather, new 353 associations are accepted automatically, and notifications of the new 354 associations are delivered via recvmsg() with the SCTP_ASSOC_CHANGE 355 event (if these notifications are enabled). Clients will typically 356 not call listen(), so that they can be assured that the only 357 associations on the socket will be ones they actively initiated. 358 Server or peer-to-peer sockets, on the other hand, will always accept 359 new associations, so a well-written application using server 360 one-to-many style sockets must be prepared to handle new associations 361 from unwanted peers. 363 Also note that the SCTP_ASSOC_CHANGE event provides the association 364 ID for a new association, so if applications wish to use the 365 association ID as input to other socket calls, they should ensure 366 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 367 default). 369 3.1.4 sendmsg() and recvmsg() - one-to-many style socket 371 An application uses sendmsg() and recvmsg() call to transmit data to 372 and receive data from its peer. 374 ssize_t sendmsg(int socket, const struct msghdr *message, int flags); 376 ssize_t recvmsg(int socket, struct msghdr *message, int flags); 378 socket: the socket descriptor of the endpoint. 380 message: pointer to the msghdr structure which contains a single user 381 message and possibly some ancillary data. See Section 5 for 382 complete description of the data structures. 384 flags: No new flags are defined for SCTP at this level. See Section 5 385 for SCTP-specific flags used in the msghdr structure. 387 As we will see in Section 5, along with the user data, the ancillary 388 data field is used to carry the sctp_sndrcvinfo and/or the 389 sctp_initmsg structures to perform various SCTP functions including 390 specifying options for sending each user message. Those options, 391 depending on whether sending or receiving, include stream number, 392 stream sequence number, various flags, context and payload protocol 393 Id, etc. 395 When sending user data with sendmsg(), the msg_name field in msghdr 396 structure will be filled with one of the transport addresses of the 397 intended receiver. If there is no association existing between the 398 sender and the intended receiver, the sender's SCTP stack will set up 399 a new association and then send the user data (see Section 3.2 for 400 more on implicit association setup). 402 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 403 be delivered if that notification has been enabled, and no more data 404 can be sent to that association. Any attempt to send more data will 405 cause sendmsg() to return with an ESHUTDOWN error. Note that the 406 socket is still open for reading at this point so it is possible to 407 retrieve notifications. 409 When receiving a user message with recvmsg(), the msg_name field in 410 msghdr structure will be populated with the source transport address 411 of the user data. The caller of recvmsg() can use this address 412 information to determine to which association the received user 413 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 414 applications must use the peer transport address provided in the 415 msg_name field by recvmsg() to perform correlation to an association, 416 since they will not have the association ID. 418 If all data in a single message has been delivered, MSG_EOR will be 419 set in the msg_flags field of the msghdr structure (see section 420 Section 5.1). 422 If the application does not provide enough buffer space to completely 423 receive a data message, MSG_EOR will not be set in msg_flags. 424 Successive reads will consume more of the same message until the 425 entire message has been delivered, and MSG_EOR will be set. 427 If the SCTP stack is running low on buffers, it may partially deliver 428 a message. In this case, MSG_EOR will not be set, and more calls to 429 recvmsg() will be necessary to completely consume the message. Only 430 one message at a time can be partially delivered. 432 Note, if the socket is a branched-off socket that only represents one 433 association (see Section 3.1), the msg_name field can be used to 434 override the primary address when sending data. 436 3.1.5 close() - one-to-many style socket 438 Applications use close() to perform graceful shutdown (as described 439 in Section 10.1 of RFC2960 [8]) on ALL the associations currently 440 represented by a one-to-many style socket. 442 The syntax is: 444 ret = close(int sd); 446 sd - the socket descriptor of the associations to be closed. 448 To gracefully shutdown a specific association represented by the 449 one-to-many style socket, an application should use the sendmsg() 450 call, and including the MSG_EOF flag. A user may optionally terminate 451 an association non-gracefully by sending with the MSG_ABORT flag and 452 possibly passing a user specified abort code in the data field. Both 453 flags MSG_EOF and MSG_ABORT are passwd with ancillary data (see 454 Section 5.2.2) in the sendmsg call. 456 If sd in the close() call is a branched-off socket representing only 457 one association, the shutdown is performed on that association only. 459 3.1.6 connect() - one-to-many style socket 461 An application may use the connect() call in the one-to-many style to 462 initiate an association without sending data. 464 The syntax is: 466 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 468 sd: the socket descriptor to have a new association added to. 470 nam: the address structure (either struct sockaddr_in or struct 471 sockaddr_in6 defined in RFC2553 [7]). 473 len: the size of the address. 475 Multiple connect() calls can be made on the same socket to create 476 multiple associations. This is different from the semantics of 477 connect() on a UDP socket. 479 3.2 Implicit Association Setup 481 Once all bind() calls are complete on a one-to-many style socket, the 482 application can begin sending and receiving data using the sendmsg()/ 483 recvmsg() or sendto()/recvfrom() calls, without going through any 484 explicit association setup procedures (i.e., no connect() calls 485 required). 487 Whenever sendmsg() or sendto() is called and the SCTP stack at the 488 sender finds that there is no association existing between the sender 489 and the intended receiver (identified by the address passed either in 490 the msg_name field of msghdr structure in the sendmsg() call or the 491 dest_addr field in the sendto() call), the SCTP stack will 492 automatically setup an association to the intended receiver. 494 Upon the successful association setup a SCTP_COMM_UP notification 495 will be dispatched to the socket at both the sender and receiver 496 side. This notification can be read by the recvmsg() system call (see 497 Section 3.1.3). 499 Note, if the SCTP stack at the sender side supports bundling, the 500 first user message may be bundled with the COOKIE ECHO message 501 RFC2960 [8]. 503 When the SCTP stack sets up a new association implicitly, it first 504 consults the sctp_initmsg structure, which is passed along within the 505 ancillary data in the sendmsg() call (see Section 5.2.1 for details 506 of the data structures), for any special options to be used on the 507 new association. 509 If this information is not present in the sendmsg() call, or if the 510 implicit association setup is triggered by a sendto() call, the 511 default association initialization parameters will be used. These 512 default association parameters may be set with respective 513 setsockopt() calls or be left to the system defaults. 515 Implicit association setup cannot be initiated by send()/recv() 516 calls. 518 3.3 Non-blocking mode 520 Some SCTP users might want to avoid blocking when they call socket 521 interface function. 523 Whenever the user which want to avoid blocking must call select() 524 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and check 525 the socket status is writable or readable. If the socket status is 526 not writable sendmsg() and sendto() return EAGAIN and do not transmit 527 the message. Similarly, if the status is not readable, recvmsg() and 528 recvfrom() return EAGAIN. 530 Once all bind() calls are complete on a one-to-many style socket, the 531 application must set the non-blocking option by a fcntl() (such as 532 O_NONBLOCK). After which the sendmsg() function returns immediately, 533 and the success or failure of the data message (and possible 534 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 535 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 536 be sent (due to a CANT_START_ASSOC), the sender will also receive a 537 SCTP_SEND_FAILED event. Those event(s) can be received by the user 538 calling of recvmsg(). A server (having called listen()) is also 539 notified of an association up event by the reception of a 540 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 541 possibly the reception of the first data message. 543 In order to shutdown the association gracefully, the user must call 544 sendmsg() with no data and with the MSG_EOF flag set. The function 545 returns immediately, and completion of the graceful shutdown is 546 indicated by an SCTP_ASSOC_CHANGE notification of type 547 SHUTDOWN_COMPLETE (see Section 5.3.1.1). 549 3.4 Special considerations 551 The fact that a one-to-many style socket can provide access to many 552 SCTP associations through a single socket descriptor has important 553 implications for both application programmers and system programmers 554 implementing this API. A key issue is how buffer space inside the 555 sockets layer is managed. Because this implementation detail directly 556 affects how application programmers must write their code to ensure 557 correct operation and portability, this section provides some 558 guidance to both implementors and application programmers. 560 An important feature that SCTP shares with TCP is flow control: 561 specifically, a sender may not send data faster than the receiver can 562 consume it. 564 For TCP, flow control is typically provided for in the sockets API as 565 follows. If the reader stops reading, the sender queues messages in 566 the socket layer until it uses all of its socket buffer space 567 allocation creating a "stalled connection". Further attempts to 568 write to the socket will block or return the error EAGAIN (for a 569 non-blocking socket). At some point, either the connection is 570 closed, or the receiver begins to read again freeing space in the 571 output queue. 573 For one-to-one style SCTP sockets (this includes sockets descriptors 574 that were separated from a one-to-many style socket with 575 sctp_peeloff()) the behavior is identical. For one-to-many style 576 SCTP sockets, the fact that we have multiple associations on a single 577 socket makes the situation more complicated. If the implementation 578 uses a single buffer space allocation shared by all associations, a 579 single stalled association can prevent the further sending of data on 580 all associations active on a particular one-to-many style socket. 582 For a blocking socket, it should be clear that a single stalled 583 association can block the entire socket. For this reason, 584 application programmers may want to use non-blocking one-to-many 585 style sockets. The application should at least be able to send 586 messages to the non-stalled associations. 588 But a non-blocking socket is not sufficient if the API implementor 589 has chosen a single shared buffer allocation for the socket. A single 590 stalled association would eventually cause the shared allocation to 591 fill, and it would become impossible to send even to non-stalled 592 associations. 594 The API implementor can solve this problem by providing each 595 association with its own allocation of outbound buffer space. Each 596 association should conceptually have as much buffer space as it would 597 have if it had its own socket. As a bonus, this simplifies the 598 implementation of sctp_peeloff(). 600 To ensure that a given stalled association will not prevent other 601 non-stalled associations from being writable, application programmers 602 should either: 604 (a) demand that the underlying implementation dedicates independent 605 buffer space allotments to each association (as suggested above), 606 or 608 (b) verify that their application layer protocol does not permit 609 large amounts of unread data at the receiver (this is true of some 610 request-response protocols, for example), or 612 (c) use one-to-one style sockets for association which may 613 potentially stall (either from the beginning, or by using 614 sctp_peeloff before sending large amounts of data that may cause a 615 stalled condition). 617 An implemenation which dedicates independent buffer space for each 618 association should define HAVE_SCTP_MULTIBUF to 1. 620 4. one-to-one style Interface 622 The goal of this style is to follow as closely as possible the 623 current practice of using the sockets interface for a connection 624 oriented protocol, such as TCP. This style enables existing 625 applications using connection oriented protocols to be ported to SCTP 626 with very little effort. 628 Note that some new SCTP features and some new SCTP socket options can 629 only be utilized through the use of sendmsg() and recvmsg() calls, 630 see Section 4.1.8. Also note that some socket interfaces may not be 631 able to provide data on the third leg of the association set up with 632 this interface style. 634 4.1 Basic Operation 636 A typical server in one-to-one style uses the following system call 637 sequence to prepare an SCTP endpoint for servicing requests: 639 1. socket() 641 2. bind() 643 3. listen() 645 4. accept() 647 The accept() call blocks until a new association is set up. It 648 returns with a new socket descriptor. The server then uses the new 649 socket descriptor to communicate with the client, using recv() and 650 send() calls to get requests and send back responses. 652 Then it calls 654 5. close() 656 to terminate the association. 658 A typical client uses the following system call sequence to setup an 659 association with a server to request services: 661 1. socket() 663 2. connect() 665 After returning from connect(), the client uses send() and recv() 666 calls to send out requests and receive responses from the server. 668 The client calls 670 3. close() 672 to terminate this association when done. 674 4.1.1 socket() - one-to-one style socket 676 Applications calls socket() to create a socket descriptor to 677 represent an SCTP endpoint. 679 The syntax is: 681 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 683 or, 685 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 687 Here, SOCK_STREAM indicates the creation of a one-to-one style 688 socket. 690 The first form creates an endpoint which can use only IPv4 addresses, 691 while the second form creates an endpoint which can use both IPv6 and 692 IPv4 addresses. 694 4.1.2 bind() - one-to-one style socket 696 Applications use bind() to pass an address to be associated with an 697 SCTP endpoint to the system. bind() allows only either a single 698 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 699 endpoint can be associated with multiple addresses. To do this, 700 sctp_bindx() is introduced in Section 8.1 to help applications do 701 the job of associating multiple addresses. 703 These addresses associated with a socket are the eligible transport 704 addresses for the endpoint to send and receive data. The endpoint 705 will also present these addresses to its peers during the association 706 initialization process, see RFC2960 [8]. 708 The syntax is: 710 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 712 sd: the socket descriptor returned by socket() call. 714 addr: the address structure (either struct sockaddr_in or struct 715 sockaddr_in6 defined in RFC2553 [7]). 717 addrlen: the size of the address structure. 719 If sd is an IPv4 socket, the address passed must be an IPv4 address. 720 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 721 either be an IPv4 or an IPv6 address. 723 Applications cannot call bind() multiple times to associate multiple 724 addresses to the endpoint. After the first call to bind(), all 725 subsequent calls will return an error. 727 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 728 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 729 operating system will associate the endpoint with an optimal address 730 set of the available interfaces. 732 If a bind() or sctp_bindx() is not called prior to the connect() 733 call, the system picks an ephemeral port and will choose an address 734 set equivalent to binding with a wildcard address. One of those 735 addresses will be the primary address for the association. This 736 automatically enables the multi-homing capability of SCTP. 738 The completion of this bind() process does not ready the SCTP 739 endpoint to accept inbound SCTP association requests. Until a 740 listen() system call, described below, is performed on the socket, 741 the SCTP endpoint will promptly reject an inbound SCTP INIT request 742 with an SCTP ABORT. 744 4.1.3 listen() - one-to-one style socket 746 Applications use listen() to ready the SCTP endpoint for accepting 747 inbound associations. 749 The syntax is: 751 int listen(int sd, int backlog); 753 sd: the socket descriptor of the SCTP endpoint. 755 backlog: this specifies the max number of outstanding associations 756 allowed in the socket's accept queue. These are the associations 757 that have finished the four-way initiation handshake (see Section 758 5 of RFC2960 [8]) and are in the ESTABLISHED state. Note, a 759 backlog of '0' indicates that the caller no longer wishes to 760 receive new associations. 762 4.1.4 accept() - one-to-one style socket 764 Applications use accept() call to remove an established SCTP 765 association from the accept queue of the endpoint. A new socket 766 descriptor will be returned from accept() to represent the newly 767 formed association. 769 The syntax is: 771 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 773 new_sd: the socket descriptor for the newly formed association. 775 sd the listening socket descriptor. 777 addr on return, will contain the primary address of the peer 778 endpoint. 780 addrlen on return, will contain the size of addr. 782 4.1.5 connect() - one-to-one style socket 784 Applications use connect() to initiate an association to a peer. 786 The syntax is: 788 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 790 sd: the socket descriptor of the endpoint. 792 addr the peer's address. 794 addrlen the size of the address. 796 This operation corresponds to the ASSOCIATE primitive described in 797 section 10.1 of RFC2960 [8]. 799 By default, the new association created has only one outbound stream. 800 The SCTP_INITMSG option described in Section 7.1.3 should be used 801 before connecting to change the number of outbound streams. 803 If a bind() or sctp_bindx() is not called prior to the connect() 804 call, the system picks an ephemeral port and will choose an address 805 set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 806 and IPv6 socket respectively. One of those addresses will be the 807 primary address for the association. This automatically enables the 808 multi-homing capability of SCTP. 810 Note that SCTP allows data exchange, similar to T/TCP RFC1644 [3], 811 during the association set up phase. If an application wants to do 812 this, it cannot use connect() call. Instead, it should use sendto() 813 or sendmsg() to initiate an association. If it uses sendto() and it 814 wants to change initialization behavior, it needs to use the 815 SCTP_INITMSG socket option before calling sendto(). Or it can use 816 SCTP_INIT type sendmsg() to initiate an association without doing the 817 setsockopt(). Note that some sockets implementations may not support 818 the sending of data to initiate an assocation with the one-to-one 819 style (implementations that do not support T/TCP normally have this 820 restriction). Implementations which allow sending of data to 821 initiate an association without calling connect() define the 822 preprocessor constant HAVE_SCTP_NOCONNECT to 1. 824 SCTP does not support half close semantics. This means that unlike 825 T/TCP, MSG_EOF should not be set in the flags parameter when calling 826 sendto() or sendmsg() when the call is used to initiate a connection. 827 MSG_EOF is not an acceptable flag with SCTP socket. 829 4.1.6 close() - one-to-one style socket 831 Applications use close() to gracefully close down an association. 833 The syntax is: 835 int close(int sd); 837 sd - the socket descriptor of the association to be closed. 839 After an application calls close() on a socket descriptor, no further 840 socket operations will succeed on that descriptor. 842 4.1.7 shutdown() - one-to-one style socket 844 SCTP differs from TCP in that it does not have half closed semantics. 845 Hence the shutdown() call for SCTP is an approximation of the TCP 846 shutdown() call, and solves some different problems. Full 847 TCP-compatibility is not provided, so developers porting TCP 848 applications to SCTP may need to recode sections that use shutdown(). 849 (Note that it is possible to achieve the same results as half close 850 in SCTP using SCTP streams.) 852 The syntax is: 854 int shutdown(int socket, int how); 856 sd - the socket descriptor of the association to be closed. 858 how - Specifies the type of shutdown. The values are 859 as follows: 861 SHUT_RD 862 Disables further receive operations. No SCTP 863 protocol action is taken. 865 SHUT_WR 866 Disables further send operations, and initiates 867 the SCTP shutdown sequence. 869 SHUT_RDWR 870 Disables further send and receive operations 871 and initiates the SCTP shutdown sequence. 873 The major difference between SCTP and TCP shutdown() is that SCTP 874 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 875 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 876 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close the 877 SCTP association while still leaving the socket descriptor open, so 878 that the caller can receive back any data SCTP was unable to deliver 879 (see Section 5.3.1.4 for more information). 881 To perform the ABORT operation described in RFC2960 [8] section 10.1, 882 an application can use the socket option SO_LINGER. It is described 883 in Section 7.1.4. 885 4.1.8 sendmsg() and recvmsg() - one-to-one style socket 887 With a one-to-one style socket, the application can also use 888 sendmsg() and recvmsg() to transmit data to and receive data from its 889 peer. The semantics is similar to those used in the one-to-many style 890 (section Section 3.1.3), with the following differences: 892 1) When sending, the msg_name field in the msghdr is not used to 893 specify the intended receiver, rather it is used to indicate a 894 preferred peer address if the sender wishes to discourage the stack 895 from sending the message to the primary address of the receiver. If 896 the transport address given is not part of the current association, 897 the data will not be sent and a SCTP_SEND_FAILED event will be 898 delivered to the application if send failure events are enabled. 900 2) An application must use close() to gracefully shutdown an 901 association, or use SO_LINGER option with close() to abort an 902 association. It must not use the MSG_ABORT or MSG_EOF flag in 903 sendmsg(). The system returns an error if an application tries to do 904 so. 906 4.1.9 getpeername() 908 Applications use getpeername() to retrieve the primary socket address 909 of the peer. This call is for TCP compatibility, and is not 910 multi-homed. It does not work with one-to-many style sockets. See 911 Section 8.3 for a multi-homed/one-to-many style version of the call. 913 The syntax is: 915 int getpeername(int socket, struct sockaddr *address, 916 socklen_t *len); 918 sd - the socket descriptor to be queried. 920 address - On return, the peer primary address is stored in 921 this buffer. If the socket is an IPv4 socket, the 922 address will be IPv4. If the socket is an IPv6 socket, 923 the address will be either an IPv6 or IPv4 924 address. 926 len - The caller should set the length of address here. 927 On return, this is set to the length of the returned 928 address. 930 If the actual length of the address is greater than the length of the 931 supplied sockaddr structure, the stored address will be truncated. 933 5. Data Structures 935 We discuss in this section important data structures which are 936 specific to SCTP and are used with sendmsg() and recvmsg() calls to 937 control SCTP endpoint operations and to access ancillary information 938 and notifications. 940 5.1 The msghdr and cmsghdr Structures 942 The msghdr structure used in the sendmsg() and recvmsg() calls, as 943 well as the ancillary data carried in the structure, is the key for 944 the application to set and get various control information from the 945 SCTP endpoint. 947 The msghdr and the related cmsghdr structures are defined and 948 discussed in details in RFC2292 [6]. Here we will cite their 949 definitions from RFC2292 [6]. 951 The msghdr structure: 953 struct msghdr { 954 void *msg_name; /* ptr to socket address structure */ 955 socklen_t msg_namelen; /* size of socket address structure */ 956 struct iovec *msg_iov; /* scatter/gather array */ 957 size_t msg_iovlen; /* # elements in msg_iov */ 958 void *msg_control; /* ancillary data */ 959 socklen_t msg_controllen; /* ancillary data buffer length */ 960 int msg_flags; /* flags on received message */ 961 }; 963 The cmsghdr structure: 965 struct cmsghdr { 966 socklen_t cmsg_len; /* #bytes, including this header */ 967 int cmsg_level; /* originating protocol */ 968 int cmsg_type; /* protocol-specific type */ 969 /* followed by unsigned char cmsg_data[]; */ 970 }; 972 In the msghdr structure, the usage of msg_name has been discussed in 973 previous sections (see Section 3.1.3 and Section 4.1.8). 975 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 976 field) are treated as a single SCTP data chunk, rather than multiple 977 chunks, for both sendmsg() and recvmsg(). 979 The msg_flags are not used when sending a message with sendmsg(). 981 If a notification has arrived, recvmsg() will return the notification 982 with the MSG_NOTIFICATION flag set in msg_flags. If the 983 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 984 Section 5.3 for more information about notifications. 986 If all portions of a data frame or notification have been read, 987 recvmsg() will return with MSG_EOR set in msg_flags. 989 5.2 SCTP msg_control Structures 991 A key element of all SCTP-specific socket extensions is the use of 992 ancillary data to specify and access SCTP-specific data via the 993 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 994 Fine-grained control over initialization and sending parameters are 995 handled with ancillary data. 997 Each ancillary data item is proceeded by a struct cmsghdr (see 998 Section 5.1), which defines the function and purpose of the data 999 contained in in the cmsg_data[] member. 1001 There are two kinds of ancillary data used by SCTP: initialization 1002 data, and, header information (SNDRCV). Initialization data 1003 (one-to-many style only) sets protocol parameters for new 1004 associations. Section 5.2.1 provides more details. Header information 1005 can set or report parameters on individual messages in a stream. See 1006 Section 5.2.2 for how to use SNDRCV ancillary data. 1008 By default on a one-to-one style socket, SCTP will pass no ancillary 1009 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV 1010 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can 1011 be enabled with socket options defined for SCTP; see Section 7.3. 1013 Note that all ancillary types are fixed length; see Section 5.4 for 1014 further discussion on this. These data structures use struct 1015 sockaddr_storage (defined in RFC2553 [7]) as a portable, fixed length 1016 address format. 1018 Other protocols may also provide ancillary data to the socket layer 1019 consumer. These ancillary data items from other protocols may 1020 intermingle with SCTP data. For example, the IPv6 socket API 1021 definitions (RFC2292 [6] and RFC2553 [7]) define a number of 1022 ancillary data items. If a socket API consumer enables delivery of 1023 both SCTP and IPv6 ancillary data, they both may appear in the same 1024 msg_control buffer in any order. An application may thus need to 1025 handle other types of ancillary data besides that passed by SCTP. 1027 The sockets application must provide a buffer large enough to 1028 accommodate all ancillary data provided via recvmsg(). If the buffer 1029 is not large enough, the ancillary data will be truncated and the 1030 msghdr's msg_flags will include MSG_CTRUNC. 1032 5.2.1 SCTP Initiation Structure (SCTP_INIT) 1034 This cmsghdr structure provides information for initializing new SCTP 1035 associations with sendmsg(). The SCTP_INITMSG socket option uses 1036 this same data structure. This structure is not used for recvmsg(). 1038 cmsg_level cmsg_type cmsg_data[] 1039 ------------ ------------ ---------------------- 1040 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1042 Here is the definition of the sctp_initmsg structure: 1044 struct sctp_initmsg { 1045 uint16_t sinit_num_ostreams; 1046 uint16_t sinit_max_instreams; 1047 uint16_t sinit_max_attempts; 1048 uint16_t sinit_max_init_timeo; 1049 }; 1051 sinit_num_ostreams: 16 bits (unsigned integer) 1053 This is an integer number representing the number of streams that the 1054 application wishes to be able to send to. This number is confirmed 1055 in the SCTP_COMM_UP notification and must be verified since it is a 1056 negotiated number with the remote endpoint. The default value of 0 1057 indicates to use the endpoint default value. 1059 sinit_max_instreams: 16 bits (unsigned integer) 1061 This value represents the maximum number of inbound streams the 1062 application is prepared to support. This value is bounded by the 1063 actual implementation. In other words the user MAY be able to 1064 support more streams than the Operating System. In such a case, the 1065 Operating System limit overrides the value requested by the user. The 1066 default value of 0 indicates to use the endpoint's default value. 1068 sinit_max_attempts: 16 bits (unsigned integer) 1070 This integer specifies how many attempts the SCTP endpoint should 1071 make at resending the INIT. This value overrides the system SCTP 1072 'Max.Init.Retransmits' value. The default value of 0 indicates to 1073 use the endpoint's default value. This is normally set to the 1074 system's default 'Max.Init.Retransmit' value. 1076 sinit_max_init_timeo: 16 bits (unsigned integer) 1077 This value represents the largest Time-Out or RTO value (in 1078 milliseconds) to use inattempting a INIT. Normally the 'RTO.Max' is 1079 used to limit the doubling of the RTO upon timeout. For the INIT 1080 message this value MAY override 'RTO.Max'. This value MUST NOT 1081 influence 'RTO.Max' during data transmission and is only used to 1082 bound the initial setup time. A default value of 0 indicates to use 1083 the endpoint's default value. This is normally set to the system's 1084 'RTO.Max' value (60 seconds). 1086 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 1088 This cmsghdr structure specifies SCTP options for sendmsg() and 1089 describes SCTP header information about a received message through 1090 recvmsg(). 1092 cmsg_level cmsg_type cmsg_data[] 1093 ------------ ------------ ---------------------- 1094 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1096 Here is the definition of sctp_sndrcvinfo: 1098 struct sctp_sndrcvinfo { 1099 uint16_t sinfo_stream; 1100 uint16_t sinfo_ssn; 1101 uint16_t sinfo_flags; 1102 uint32_t sinfo_ppid; 1103 uint32_t sinfo_context; 1104 uint32_t sinfo_timetolive; 1105 uint32_t sinfo_tsn; 1106 uint32_t sinfo_cumtsn; 1107 sctp_assoc_t sinfo_assoc_id; 1108 }; 1110 sinfo_stream: 16 bits (unsigned integer) 1112 For recvmsg() the SCTP stack places the message's stream number in 1113 this value. For sendmsg() this value holds the stream number that the 1114 application wishes to send this message to. If a sender specifies an 1115 invalid stream number an error indication is returned and the call 1116 fails. 1118 sinfo_ssn: 16 bits (unsigned integer) 1120 For recvmsg() this value contains the stream sequence number that the 1121 remote endpoint placed in the DATA chunk. For fragmented messages 1122 this is the same number for all deliveries of the message (if more 1123 than one recvmsg() is needed to read the message). The sendmsg() 1124 call will ignore this parameter. 1126 sinfo_ppid: 32 bits (unsigned integer) 1128 This value in sendmsg() is an opaque unsigned value that is passed to 1129 the remote end in each user message. In recvmsg() this value is the 1130 same information that was passed by the upper layer in the peer 1131 application. Please note that byte order issues are NOT accounted 1132 for and this information is passed opaquely by the SCTP stack from 1133 one end to the other. 1135 sinfo_context: 32 bits (unsigned integer) 1137 This value is an opaque 32 bit context datum that is used in the 1138 sendmsg() function. This value is passed back to the upper layer if 1139 a error occurs on the send of a message and is retrieved with each 1140 undelivered message (Note: if a endpoint has done multiple sends, all 1141 of which fail, multiple different sinfo_context values will be 1142 returned. One with each user data message). 1144 sinfo_flags: 16 bits (unsigned integer) 1146 This field may contain any of the following flags and is composed of 1147 a bitwise OR of these values. 1149 recvmsg() flags: 1151 MSG_UNORDERED - This flag is present when the message was sent 1152 non-ordered. 1154 sendmsg() flags: 1156 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1157 message. If this flag is clear the datagram is 1158 considered an ordered send. 1160 MSG_ADDR_OVER - This flag, in the one-to-many style, requests the SCTP 1161 stack to override the primary destination address 1162 with the address found with the sendto/sendmsg 1163 call. 1165 MSG_ABORT - Setting this flag causes the specified association 1166 to abort by sending an ABORT message to the peer 1167 (one-to-many style only). The ABORT chunk will contain an 1168 error cause 'User Initiated Abort' with cause code 12. 1169 The cause specific information of this error cause is 1170 provided in msg_iov. 1172 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1173 procedures on the specified association. Graceful 1174 shutdown assures that all data enqueued by both 1175 endpoints is successfully transmitted before closing 1176 the association (one-to-many style only). 1178 sinfo_timetolive: 32 bit (unsigned integer) 1180 For the sending side, this field contains the message time to live in 1181 milliseconds. The sending side will expire the message within the 1182 specified time period if the message as not been sent to the peer 1183 within this time period. This value will override any default value 1184 set using any socket option. Also note that the value of 0 is special 1185 in that it indicates no timeout should occur on this message. 1187 sinfo_tsn: 32 bit (unsigned integer) 1189 For the receiving side, this field holds a TSN that was assigned to 1190 one of the SCTP Data Chunks. 1192 sinfo_cumtsn: 32 bit (unsigned integer) 1194 This field will hold the current cumulative TSN as known by the 1195 underlying SCTP layer. Note this field is ignored when sending and 1196 only valid for a receive operation when sinfo_flags are set to 1197 MSG_UNORDERED. 1199 sinfo_assoc_id: sizeof (sctp_assoc_t) 1201 The association handle field, sinfo_assoc_id, holds the identifier 1202 for the association announced in the SCTP_COMM_UP notification. All 1203 notifications for a given association have the same identifier. 1204 Ignored for one-to-one style sockets. 1206 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1208 5.3 SCTP Events and Notifications 1210 An SCTP application may need to understand and process events and 1211 errors that happen on the SCTP stack. These events include network 1212 status changes, association startups, remote operational errors and 1213 undeliverable messages. All of these can be essential for the 1214 application. 1216 When an SCTP application layer does a recvmsg() the message read is 1217 normally a data message from a peer endpoint. If the application 1218 wishes to have the SCTP stack deliver notifications of non-data 1219 events, it sets the appropriate socket option for the notifications 1220 it wants. See Section 7.3 for these socket options. When a 1221 notification arrives, recvmsg() returns the notification in the 1222 application-supplied data buffer via msg_iov, and sets 1223 MSG_NOTIFICATION in msg_flags. 1225 This section details the notification structures. Every notification 1226 structure carries some common fields which provides general 1227 information. 1229 A recvmsg() call will return only one notification at a time. Just 1230 as when reading normal data, it may return part of a notification if 1231 the msg_iov buffer is not large enough. If a single read is not 1232 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1233 reading the notification before subsequent data can arrive. 1235 5.3.1 SCTP Notification Structure 1237 The notification structure is defined as the union of all 1238 notification types. 1240 union sctp_notification { 1241 struct { 1242 uint16_t sn_type; /* Notification type. */ 1243 uint16_t sn_flags; 1244 uint32_t sn_length; 1245 } sn_header; 1246 struct sctp_assoc_change sn_assoc_change; 1247 struct sctp_paddr_change sn_paddr_change; 1248 struct sctp_remote_error sn_remote_error; 1249 struct sctp_send_failed sn_send_failed; 1250 struct sctp_shutdown_event sn_shutdown_event; 1251 struct sctp_adaption_event sn_adaption_event; 1252 struct sctp_pdapi_event sn_pdapi_event; 1253 }; 1255 sn_type: 16 bits (unsigned integer) 1257 The following list describes the SCTP notification and event types 1258 for the field sn_type. 1260 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1261 been opened or closed. Refer to Section 5.3.1.1 for details. 1263 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1264 part of an existing association has experienced a change of state 1265 (e.g. a failure or return to service of the reachability of a 1266 endpoint via a specific transport address). Please see Section 1267 5.3.1.2 for data structure details. 1269 SCTP_REMOTE_ERROR: The attached error message is an Operational Error 1270 received from the remote peer. It includes the complete TLV sent 1271 by the remote endpoint. See Section 5.3.1.3 for the detailed 1272 format. 1274 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1275 remote endpoint. This structure includes the original 1276 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1277 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1279 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1280 should be sent on this socket. 1282 SCTP_ADAPTION_INDICATION: This notification holds the peers indicated 1283 adaption layer. Please see Section 5.3.1.6. 1285 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1286 receiver that the partial delivery has been aborted. This may 1287 indicate the association is about to be aborted. Please see 1288 Section 5.3.1.7 1290 All standard values for sn_type are greater than 2^15. Values from 1291 2^15 and down are reserved. 1293 sn_flags: 16 bits (unsigned integer) 1295 These are notification-specific flags. 1297 sn_length: 32 bits (unsigned integer) 1299 This is the length of the whole sctp_notification structure including 1300 the sn_type, sn_flags, and sn_length fields. 1302 5.3.1.1 SCTP_ASSOC_CHANGE 1304 Communication notifications inform the ULP that an SCTP association 1305 has either begun or ended. The identifier for a new association is 1306 provided by this notification. The notification information has the 1307 following format: 1309 struct sctp_assoc_change { 1310 uint16_t sac_type; 1311 uint16_t sac_flags; 1312 uint32_t sac_length; 1313 uint16_t sac_state; 1314 uint16_t sac_error; 1315 uint16_t sac_outbound_streams; 1316 uint16_t sac_inbound_streams; 1317 sctp_assoc_t sac_assoc_id; 1318 uint8_t sac_info[0]; 1319 }; 1321 sac_type: 1323 It should be SCTP_ASSOC_CHANGE. 1325 sac_flags: 16 bits (unsigned integer) 1327 Currently unused. 1329 sac_length: 32 bits (unsigned integer) 1331 This field is the total length of the notification data, including 1332 the notification header. 1334 sac_state: 16 bits (signed integer) 1336 This field holds one of a number of values that communicate the event 1337 that happened to the association. They include: 1339 Event Name Description 1340 ---------------- --------------- 1341 SCTP_COMM_UP A new association is now ready 1342 and data may be exchanged with this 1343 peer. 1345 SCTP_COMM_LOST The association has failed. The association 1346 is now in the closed state. If SEND FAILED 1347 notifications are turned on, a SCTP_COMM_LOST 1348 is followed by a series of SCTP_SEND_FAILED 1349 events, one for each outstanding message. 1351 SCTP_RESTART SCTP has detected that the peer has restarted. 1353 SCTP_SHUTDOWN_COMP The association has gracefully closed. 1355 SCTP_CANT_STR_ASSOC The association failed to setup. If non blocking 1356 mode is set and data was sent (in the udp mode), 1357 a SCTP_CANT_STR_ASSOC is followed by a series of 1358 SCTP_SEND_FAILED events, one for each outstanding 1359 message. 1361 sac_error: 16 bits (signed integer) 1362 If the state was reached due to a error condition (e.g. 1363 SCTP_COMM_LOST) any relevant error information is available in this 1364 field. This corresponds to the protocol error codes defined in 1365 RFC2960 [8]. 1367 sac_outbound_streams: 16 bits (unsigned integer) 1369 sac_inbound_streams: 16 bits (unsigned integer) 1371 The maximum number of streams allowed in each direction are available 1372 in sac_outbound_streams and sac_inbound streams. 1374 sac_assoc_id: sizeof (sctp_assoc_t) 1376 The association id field, holds the identifier for the association. 1377 All notifications for a given association have the same association 1378 identifier. For one-to-one style socket, this field is ignored. 1380 sac_info: variable 1382 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1383 for this association, sac_info[] contains the complete ABORT chunk as 1384 defined in the SCTP specification RFC2960 [8] section 3.3.7. 1386 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1388 When a destination address on a multi-homed peer encounters a change 1389 an interface details event is sent. The information has the 1390 following structure: 1392 struct sctp_paddr_change { 1393 uint16_t spc_type; 1394 uint16_t spc_flags; 1395 uint32_t spc_length; 1396 struct sockaddr_storage spc_aaddr; 1397 int spc_state; 1398 int spc_error; 1399 sctp_assoc_t spc_assoc_id; 1400 } 1402 spc_type: 1404 It should be SCTP_PEER_ADDR_CHANGE. 1406 spc_flags: 16 bits (unsigned integer) 1408 Currently unused. 1410 spc_length: 32 bits (unsigned integer) 1412 This field is the total length of the notification data, including 1413 the notification header. 1415 spc_aaddr: sizeof (struct sockaddr_storage) 1417 The affected address field, holds the remote peer's address that is 1418 encountering the change of state. 1420 spc_state: 32 bits (signed integer) 1422 This field holds one of a number of values that communicate the event 1423 that happened to the address. They include: 1425 Event Name Description 1426 ---------------- --------------- 1427 SCTP_ADDR_AVAILABLE This address is now reachable. 1429 SCTP_ADDR_UNREACHABLE The address specified can no 1430 longer be reached. Any data sent 1431 to this address is rerouted to an 1432 alternate until this address becomes 1433 reachable. 1435 SCTP_ADDR_REMOVED The address is no longer part of 1436 the association. 1438 SCTP_ADDR_ADDED The address is now part of the 1439 association. 1441 SCTP_ADDR_MADE_PRIM This address has now been made 1442 to be the primary destination address. 1444 spc_error: 32 bits (signed integer) 1446 If the state was reached due to any error condition (e.g. 1447 SCTP_ADDR_UNREACHABLE) any relevant error information is available in 1448 this field. 1450 spc_assoc_id: sizeof (sctp_assoc_t) 1452 The association id field, holds the identifier for the association. 1453 All notifications for a given association have the same association 1454 identifier. For one-to-one style socket, this field is ignored. 1456 5.3.1.3 SCTP_REMOTE_ERROR 1458 A remote peer may send an Operational Error message to its peer. This 1459 message indicates a variety of error conditions on an association. 1460 The entire ERROR chunk as it appears on the wire is included in a 1461 SCTP_REMOTE_ERROR event. Please refer to the SCTP specification 1462 RFC2960 [8] and any extensions for a list of possible error formats. 1463 SCTP error notifications have the format: 1465 struct sctp_remote_error { 1466 uint16_t sre_type; 1467 uint16_t sre_flags; 1468 uint32_t sre_length; 1469 uint16_t sre_error; 1470 sctp_assoc_t sre_assoc_id; 1471 uint8_t sre_data[0]; 1472 }; 1474 sre_type: 1476 It should be SCTP_REMOTE_ERROR. 1478 sre_flags: 16 bits (unsigned integer) 1480 Currently unused. 1482 sre_length: 32 bits (unsigned integer) 1484 This field is the total length of the notification data, including 1485 the notification header and the contents of sre_data. 1487 sre_error: 16 bits (unsigned integer) 1489 This value represents one of the Operational Error causes defined in 1490 the SCTP specification, in network byte order. 1492 sre_assoc_id: sizeof (sctp_assoc_t) 1494 The association id field, holds the identifier for the association. 1495 All notifications for a given association have the same association 1496 identifier. For one-to-one style socket, this field is ignored. 1498 sre_data: variable 1500 This contains the ERROR chunk as defined in the SCTP specification 1501 RFC2960 [8] section 3.3.10. 1503 5.3.1.4 SCTP_SEND_FAILED 1505 If SCTP cannot deliver a message it may return the message as a 1506 notification. 1508 struct sctp_send_failed { 1509 uint16_t ssf_type; 1510 uint16_t ssf_flags; 1511 uint32_t ssf_length; 1512 uint32_t ssf_error; 1513 struct sctp_sndrcvinfo ssf_info; 1514 sctp_assoc_t ssf_assoc_id; 1515 uint8_t ssf_data[0]; 1516 }; 1518 ssf_type: 1520 It should be SCTP_SEND_FAILED. 1522 The flag value will take one of the following values 1524 SCTP_DATA_UNSENT - Indicates that the data was never put on 1525 the wire. 1527 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1528 Note that this does not necessarily mean that the 1529 data was (or was not) successfully delivered. 1531 ssf_length: 32 bits (unsigned integer) 1533 This field is the total length of the notification data, including 1534 the notification header and the payload in ssf_data. 1536 ssf_error: 16 bits (unsigned integer) 1538 This value represents the reason why the send failed, and if set, 1539 will be a SCTP protocol error code as defined in RFC2960 [8] section 1540 3.3.10. 1542 ssf_info: sizeof (struct sctp_sndrcvinfo) 1544 The original send information associated with the undelivered 1545 message. 1547 ssf_assoc_id: sizeof (sctp_assoc_t) 1549 The association id field, sf_assoc_id, holds the identifier for the 1550 association. All notifications for a given association have the same 1551 association identifier. For one-to-one style socket, this field is 1552 ignored. 1554 ssf_data: variable length 1556 The undelivered message, exactly as delivered by the caller to the 1557 original send*() call. 1559 5.3.1.5 SCTP_SHUTDOWN_EVENT 1561 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1562 inform the application that it should cease sending data. 1564 struct sctp_shutdown_event { 1565 uint16_t sse_type; 1566 uint16_t sse_flags; 1567 uint32_t sse_length; 1568 sctp_assoc_t sse_assoc_id; 1569 }; 1571 sse_type 1573 It should be SCTP_SHUTDOWN_EVENT 1575 sse_flags: 16 bits (unsigned integer) 1577 Currently unused. 1579 sse_length: 32 bits (unsigned integer) 1581 This field is the total length of the notification data, including 1582 the notification header. It will generally be sizeof (struct 1583 sctp_shutdown_event). 1585 sse_flags: 16 bits (unsigned integer) 1587 Currently unused. 1589 sse_assoc_id: sizeof (sctp_assoc_t) 1591 The association id field, holds the identifier for the association. 1592 All notifications for a given association have the same association 1593 identifier. For one-to-one style socket, this field is ignored. 1595 5.3.1.6 SCTP_ADAPTION_INDICATION 1597 When a peer sends a Adaption Layer Indication parameter , SCTP 1598 delivers this notification to inform the application that of the 1599 peers requested adaption layer. 1601 struct sctp_adaption_event { 1602 uint16_t sai_type; 1603 uint16_t sai_flags; 1604 uint32_t sai_length; 1605 uint32_t sai_adaption_ind; 1606 sctp_assoc_t sai_assoc_id; 1607 }; 1609 sai_type 1611 It should be SCTP_ADAPTION_INDICATION 1613 sai_flags: 16 bits (unsigned integer) 1615 Currently unused. 1617 sai_length: 32 bits (unsigned integer) 1619 This field is the total length of the notification data, including 1620 the notification header. It will generally be sizeof (struct 1621 sctp_adaption_event). 1623 sai_adaption_ind: 32 bits (unsigned integer) 1625 This field holds the bit array sent by the peer in the adaption layer 1626 indication parameter. The bits are in network byte order. 1628 sai_assoc_id: sizeof (sctp_assoc_t) 1630 The association id field, holds the identifier for the association. 1631 All notifications for a given association have the same association 1632 identifier. For one-to-one style socket, this field is ignored. 1634 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT 1636 When a receiver is engaged in a partial delivery of a message this 1637 notification will be used to indicate various events. 1639 struct sctp_pdapi_event { 1640 uint16_t pdapi_type; 1641 uint16_t pdapi_flags; 1642 uint32_t pdapi_length; 1643 uint32_t pdapi_indication; 1644 sctp_assoc_t pdapi_assoc_id; 1645 }; 1647 pdapi_type 1649 It should be SCTP_PARTIAL_DELIVERY_EVENT 1651 pdapi_flags: 16 bits (unsigned integer) 1653 Currently unused. 1655 pdapi_length: 32 bits (unsigned integer) 1657 This field is the total length of the notification data, including 1658 the notification header. It will generally be sizeof (struct 1659 sctp_pdapi_event). 1661 pdapi_indication: 32 bits (unsigned integer) 1663 This field holds the indication being sent to the application 1664 possible values include: 1666 SCTP_PARTIAL_DELIVERY_ABORTED 1668 pdapi_assoc_id: sizeof (sctp_assoc_t) 1670 The association id field, holds the identifier for the association. 1671 All notifications for a given association have the same association 1672 identifier. For one-to-one style socket, this field is ignored. 1674 5.4 Ancillary Data Considerations and Semantics 1676 Programming with ancillary socket data contains some subtleties and 1677 pitfalls, which are discussed below. 1679 5.4.1 Multiple Items and Ordering 1681 Multiple ancillary data items may be included in any call to 1682 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1683 items, or both. 1685 The ordering of ancillary data items (either by SCTP or another 1686 protocol) is not significant and is implementation-dependent, so 1687 applications must not depend on any ordering. 1689 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1690 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1691 sendmsg() or recvmsg() call. 1693 5.4.2 Accessing and Manipulating Ancillary Data 1695 Applications can infer the presence of data or ancillary data by 1696 examining the msg_iovlen and msg_controllen msghdr members, 1697 respectively. 1699 Implementations may have different padding requirements for ancillary 1700 data, so portable applications should make use of the macros 1701 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1702 RFC2292 [6] and your SCTP implementation's documentation for more 1703 information. Following is an example, from RFC2292 [6], demonstrating 1704 the use of these macros to access ancillary data: 1706 struct msghdr msg; 1707 struct cmsghdr *cmsgptr; 1709 /* fill in msg */ 1711 /* call recvmsg() */ 1713 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1714 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1715 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1716 u_char *ptr; 1718 ptr = CMSG_DATA(cmsgptr); 1719 /* process data pointed to by ptr */ 1720 } 1721 } 1723 5.4.3 Control Message Buffer Sizing 1725 The information conveyed via SCTP_SNDRCV events will often be 1726 fundamental to the correct and sane operation of the sockets 1727 application. This is particularly true of the one-to-many semantics, 1728 but also of the one-ton-one semantics. For example, if an application 1729 needs to send and receive data on different SCTP streams, SCTP_SNDRCV 1730 events are indispensable. 1732 Given that some ancillary data is critical, and that multiple 1733 ancillary data items may appear in any order, applications should be 1734 carefully written to always provide a large enough buffer to contain 1735 all possible ancillary data that can be presented by recvmsg(). If 1736 the buffer is too small, and crucial data is truncated, it may pose a 1737 fatal error condition. 1739 Thus it is essential that applications be able to deterministically 1740 calculate the maximum required buffer size to pass to recvmsg(). One 1741 constraint imposed on this specification that makes this possible is 1742 that all ancillary data definitions are of a fixed length. One way to 1743 calculate the maximum required buffer size might be to take the sum 1744 the sizes of all enabled ancillary data item structures, as 1745 calculated by CMSG_SPACE. For example, if we enabled SCTP_SNDRCV_INFO 1746 and IPV6_RECVPKTINFO RFC2292 [6], we would calculate and allocate the 1747 buffer size as follows: 1749 size_t total; 1750 void *buf; 1752 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1753 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1755 buf = malloc(total); 1757 We could then use this buffer for msg_control on each call to 1758 recvmsg() and be assured that we would not lose any ancillary data to 1759 truncation. 1761 6. Common Operations for Both Styles 1763 6.1 send(), recv(), sendto(), recvfrom() 1765 Applications can use send() and sendto() to transmit data to the peer 1766 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1767 data from the peer. 1769 The syntax is: 1771 ssize_t send(int sd, const void *msg, size_t len, int flags); 1772 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1773 const struct sockaddr *to, socklen_t tolen); 1774 ssize_t recv(int sd, void *buf, size_t len, int flags); 1775 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1776 struct sockaddr *from, socklen_t *fromlen); 1778 sd - the socket descriptor of an SCTP endpoint. 1779 msg - the message to be sent. 1780 len - the size of the message or the size of buffer. 1781 to - one of the peer addresses of the association to be 1782 used to send the message. 1783 tolen - the size of the address. 1784 buf - the buffer to store a received message. 1785 from - the buffer to store the peer address used to send the 1786 received message. 1787 fromlen - the size of the from address 1788 flags - (described below). 1790 These calls give access to only basic SCTP protocol features. If 1791 either peer in the association uses multiple streams, or sends 1792 unordered data these calls will usually be inadequate, and may 1793 deliver the data in unpredictable ways. 1795 SCTP has the concept of multiple streams in one association. The 1796 above calls do not allow the caller to specify on which stream a 1797 message should be sent. The system uses stream 0 as the default 1798 stream for send() and sendto(). recv() and recvfrom() return data 1799 from any stream, but the caller can not distinguish the different 1800 streams. This may result in data seeming to arrive out of order. 1801 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1802 provide no indication. 1804 SCTP is message based. The msg buffer above in send() and sendto() 1805 is considered to be a single message. This means that if the caller 1806 wants to send a message which is composed by several buffers, the 1807 caller needs to combine them before calling send() or sendto(). 1808 Alternately, the caller can use sendmsg() to do that without 1809 combining them. recv() and recvfrom() cannot distinguish message 1810 boundaries. 1812 In receiving, if the buffer supplied is not large enough to hold a 1813 complete message, the receive call acts like a stream socket and 1814 returns as much data as will fit in the buffer. 1816 Note, the send() and recv() calls may not be used for a one-to-many 1817 style socket. 1819 Note, if an application calls a send function with no user data and 1820 no ancillary data the SCTP implementation should reject the request 1821 with an appropriate error message. An implementation is NOT allowed 1822 to send a Data chunk with no user data RFC2960 [8]. 1824 6.2 setsockopt(), getsockopt() 1826 Applications use setsockopt() and getsockopt() to set or retrieve 1827 socket options. Socket options are used to change the default 1828 behavior of sockets calls. They are described in Section 7 1830 The syntax is: 1832 ret = getsockopt(int sd, int level, int optname, void *optval, 1833 socklen_t *optlen); 1834 ret = setsockopt(int sd, int level, int optname, const void *optval, 1835 socklen_t optlen); 1837 sd - the socket descript. 1838 level - set to IPPROTO_SCTP for all SCTP options. 1839 optname - the option name. 1840 optval - the buffer to store the value of the option. 1841 optlen - the size of the buffer (or the length of the option 1842 returned). 1844 6.3 read() and write() 1846 Applications can use read() and write() to send and receive data to 1847 and from peer. They have the same semantics as send() and recv() 1848 except that the flags parameter cannot be used. 1850 Note, these calls, when used in the one-to-many style, may only be 1851 used with branched off socket descriptors (see Section 8.2). 1853 6.4 getsockname() 1855 Applications use getsockname() to retrieve the locally-bound socket 1856 address of the specified socket. This is especially useful if the 1857 caller let SCTP chose a local port. This call is for where the 1858 endpoint is not multi-homed. It does not work well with multi-homed 1859 sockets. See Section 8.5 for a multi-homed version of the call. 1861 The syntax is: 1863 int getsockname(int socket, struct sockaddr *address, 1864 socklen_t *len); 1866 sd - the socket descriptor to be queried. 1868 address - On return, one locally bound address (chosen by 1869 the SCTP stack) is stored in this buffer. If the 1870 socket is an IPv4 socket, the address will be IPv4. 1871 If the socket is an IPv6 socket, the address will 1872 be either an IPv6 or IPv4 address. 1874 len - The caller should set the length of address here. 1875 On return, this is set to the length of the returned 1876 address. 1878 If the actual length of the address is greater than the length of the 1879 supplied sockaddr structure, the stored address will be truncated. 1881 If the socket has not been bound to a local name, the value stored in 1882 the object pointed to by address is unspecified. 1884 7. Socket Options 1886 The following sub-section describes various SCTP level socket options 1887 that are common to both styles. SCTP associations can be 1888 multi-homed. Therefore, certain option parameters include a 1889 sockaddr_storage structure to select which peer address the option 1890 should be applied to. 1892 For the one-to-many style sockets, an sctp_assoc_t structure 1893 (association ID) is used to identify the the association instance 1894 that the operation affects. So it must be set when using this style. 1896 For the one-to-one style sockets and branched off one-to-many style 1897 sockets (see Section 8.2) this association ID parameter is ignored. 1899 Note that socket or IP level options are set or retrieved per socket. 1900 This means that for one-to-many style sockets, those options will be 1901 applied to all associations belonging to the socket. And for 1902 one-to-one style, those options will be applied to all peer addresses 1903 of the association controlled by the socket. Applications should be 1904 very careful in setting those options. 1906 For some IP stacks getsockopt() is read-only, so a new interface will 1907 be needed when information must be passed both in to and out of the 1908 SCTP stack. The syntax for scpt_opt_info() is, 1910 int sctp_opt_info(int sd, 1911 sctp_assoc_t id, 1912 int opt, 1913 void *arg, 1914 socklen_t *size); 1916 For one-to-many style sockets, id specifies the association to query. 1917 For one-to-one style sockets, id is ignored. 1919 opt specifies which SCTP socket option to get. It can any socket 1920 option currently supported that requests information (either read/ 1921 write options or read only) such as: 1923 SCTP_RTOINFO 1924 SCTP_ASSOCINFO 1925 SCTP_DEFAULT_SEND_PARAM 1926 SCTP_GET_PEER_ADDR_INFO 1927 SCTP_PRIMARY_ADDR 1928 SCTP_PEER_ADDR_PARAMS 1929 SCTP_STATUS 1931 arg is an option-specific structure buffer provided by the caller. 1933 See Section 8.5) subsections for more information on these options 1934 and option-specific structures. 1936 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1937 sets errno to the appropriate error code. 1939 All options that support specific settings on an association by 1940 filling in either an association id variable or a sockaddr_storage 1941 SHOULD also support setting of the same value for the entire endpoint 1942 (i.e. future associations). To accomplish this the following logic is 1943 used when setting one of these options: 1945 a) If an address is specified via a sockaddr_storage that is included 1946 in the structure the address is used to lookup the association and 1947 the settings are applied to the specific address (if appropriate) 1948 or to the entire association. 1950 b) If an association identification is filled in but not a 1951 sockaddr_storage (if present) the association is found using the 1952 association identification and the settings should be applied to 1953 the entire association (since a specific address is not 1954 specified). Note this also applies to options that hold an 1955 association identification in their structure but do not have a 1956 sockaddr_storage field. 1958 c) If neither the sockaddr_storage or association identification is 1959 set i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and 1960 the association identification is 0, the settings are a default 1961 and to be applied to the endpoint (all future associations). 1963 7.1 Read / Write Options 1965 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1967 The protocol parameters used to initialize and bound retransmission 1968 timeout (RTO) are tunable. See RFC2960 [8] for more information on 1969 how these parameters are used in RTO calculation. 1971 The following structure is used to access and modify these 1972 parameters: 1974 struct sctp_rtoinfo { 1975 sctp_assoc_t srto_assoc_id; 1976 uint32_t srto_initial; 1977 uint32_t srto_max; 1978 uint32_t srto_min; 1979 }; 1980 srto_initial - This contains the initial RTO value. 1981 srto_max and srto_min - These contain the maximum and minimum bounds 1982 for all RTOs. 1983 srto_assoc_id - (one-to-many style socket) This is filled in the application, 1984 and identifies the association for this query. If 1985 this parameter is '0' (on a one-to-many style socket), 1986 then the change effects the entire endpoint. 1988 All parameters are time values, in milliseconds. A value of 0, when 1989 modifying the parameters, indicates that the current value should not 1990 be changed. 1992 To access or modify these parameters, the application should call 1993 getsockopt or setsockopt() respectively with the option name 1994 SCTP_RTOINFO. 1996 7.1.2 Association Parameters (SCTP_ASSOCINFO) 1998 This option is used to both examine and set various association and 1999 endpoint parameters. 2001 See RFC2960 [8] for more information on how this parameter is used. 2002 The peer address parameter is ignored for one-to-one style socket. 2004 The following structure is used to access and modify this parameters: 2006 struct sctp_assocparams { 2007 sctp_assoc_t sasoc_assoc_id; 2008 uint16_t sasoc_asocmaxrxt; 2009 uint16_t sasoc_number_peer_destinations; 2010 uint32_t sasoc_peer_rwnd; 2011 uint32_t sasoc_local_rwnd; 2012 uint32_t sasoc_cookie_life; 2013 }; 2014 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2015 to make for the association. 2017 sasoc_number_peer_destinations - This is the number of destination 2018 addresses that the peer has. 2019 sasoc_peer_rwnd - This holds the current value of the peers 2020 rwnd (reported in the last SACK) minus any 2021 outstanding data (i.e. data inflight). 2022 sasoc_local_rwnd - This holds the last reported rwnd that was 2023 sent to the peer. 2024 sasoc_cookie_life - This is the associations cookie life value 2025 used when issuing cookies. 2026 sasoc_assoc_id - (one-to-many style socket) This is filled in the application, 2027 and identifies the association for this query. 2029 This information may be examined for either the endpoint or a 2030 specific association. To examine a endpoints default parameters the 2031 association id (sasoc_assoc_id) should must be set to the value '0'. 2032 The values of the sasoc_peer_rwnd is meaningless when examining 2033 endpoint information. 2035 All parameters are time values, in milliseconds. A value of 0, when 2036 modifying the parameters, indicates that the current value should not 2037 be changed. 2039 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2040 on either an endpoint or association basis. The rwnd and destination 2041 counts (sasoc_number_peer_destinations, 2042 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2043 placed in these is ignored. 2045 To access or modify these parameters, the application should call 2046 getsockopt or setsockopt() respectively with the option name 2047 SCTP_ASSOCINFO. 2049 The maximum number of retransmissions before an address is considered 2050 unreachable is also tunable, but is address-specific, so it is 2051 covered in a separate option. If an application attempts to set the 2052 value of the association maximum retransmission parameter to more 2053 than the sum of all maximum retransmission parameters, setsockopt() 2054 shall return an error. The reason for this, from RFC2960 [8] section 2055 8.2: 2057 Note: When configuring the SCTP endpoint, the user should avoid 2058 having the value of 'Association.Max.Retrans' larger than the 2059 summation of the 'Path.Max.Retrans' of all the destination addresses 2060 for the remote endpoint. Otherwise, all the destination addresses 2061 may become inactive while the endpoint still considers the peer 2062 endpoint reachable. 2064 7.1.3 Initialization Parameters (SCTP_INITMSG) 2066 Applications can specify protocol parameters for the default 2067 association initialization. The structure used to access and modify 2068 these parameters is defined in Section 5.2.1). The option name 2069 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2071 Setting initialization parameters is effective only on an unconnected 2072 socket (for one-to-many style sockets only future associations are 2073 effected by the change). With one-to-one style sockets, this option 2074 is inherited by sockets derived from a listener socket. 2076 7.1.4 SO_LINGER 2078 An application using the one-to-one style socket can use this option 2079 to perform the SCTP ABORT primitive. The linger option structure is: 2081 struct linger { 2082 int l_onoff; /* option on/off */ 2083 int l_linger; /* linger time */ 2084 }; 2086 To enable the option, set l_onoff to 1. If the l_linger value is set 2087 to 0, calling close() is the same as the ABORT primitive. If the 2088 value is set to a negative value, the setsockopt() call will return 2089 an error. If the value is set to a positive value linger_time, the 2090 close() can be blocked for at most linger_time ms. If the graceful 2091 shutdown phase does not finish during this period, close() will 2092 return but the graceful shutdown phase continues in the system. 2094 Note, this is a socket level option NOT an SCTP level option. So when 2095 setting SO_LINGER you must specify a level of SOL_SOCKET in the 2096 setsockopt() call. 2098 7.1.5 SCTP_NODELAY 2100 Turn on/off any Nagle-like algorithm. This means that packets are 2101 generally sent as soon as possible and no unnecessary delays are 2102 introduced, at the cost of more packets in the network. Expects an 2103 integer boolean flag. 2105 7.1.6 SO_RCVBUF 2107 Sets receive buffer size in octets. For SCTP one-to-one style 2108 sockets, this controls the receiver window size. For one-to-many 2109 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF 2110 (see Section 3.4). If the implementation defines HAVE_SCTP_MULTIBUF 2111 as 1, this controls the receiver window size for each association 2112 bound to the socket descriptor. If the implementation defines 2113 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive 2114 buffer for the whole socket. The call expects an integer. 2116 7.1.7 SO_SNDBUF 2118 Sets send buffer size. For SCTP one-to-one style sockets, this 2119 controls the amount of data SCTP may have waiting in internal buffers 2120 to be sent. This option therefore bounds the maximum size of data 2121 that can be sent in a single send call. For one-to-many style 2122 sockets, the effect is the same, except that it applies to one or all 2123 associations (see Section 3.4) bound to the socket descriptor 2124 used in the setsockopt() or getsockopt() call. The option applies to 2125 each association's window size separately. The call expects an 2126 integer. 2128 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 2130 This socket option is applicable to the one-to-many style socket 2131 only. When set it will cause associations that are idle for more than 2132 the specified number of seconds to automatically close. An 2133 association being idle is defined an association that has NOT sent or 2134 received user data. The special value of '0' indicates that no 2135 automatic close of any associations should be performed. The option 2136 expects an integer defining the number of seconds of idle time before 2137 an association is closed. 2139 7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2141 Requests that the peer mark the enclosed address as the association 2142 primary. The enclosed address must be one of the association's 2143 locally bound addresses. The following structure is used to make a 2144 set primary request: 2146 struct sctp_setpeerprim { 2147 sctp_assoc_t sspp_assoc_id; 2148 struct sockaddr_storage sspp_addr; 2149 }; 2151 sspp_addr The address to set as primary 2152 sspp_assoc_id (one-to-many style socket) This is filled in by the 2153 application, and identifies the association 2154 for this request. 2156 This functionality is optional. Implementations that do not support 2157 this functionality should return EOPNOTSUPP. 2159 7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) 2161 Requests that the local SCTP stack use the enclosed peer address as 2162 the association primary. The enclosed address must be one of the 2163 association peer's addresses. The following structure is used to make 2164 a set peer primary request: 2166 struct sctp_setprim { 2167 sctp_assoc_t ssp_assoc_id; 2168 struct sockaddr_storage ssp_addr; 2169 }; 2170 ssp_addr The address to set as primary 2171 ssp_assoc_id (one-to-many style socket) This is filled in by the 2172 application, and identifies the association 2173 for this request. 2175 7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) 2177 Requests that the local endpoint set the specified Adaption Layer 2178 Indication parameter for all future INIT and INIT-ACK exchanges. 2180 struct sctp_setadaption { 2181 uint32_t ssb_adaption_ind; 2182 }; 2184 ssb_adaption_ind The adaption layer indicator that will be included 2185 in any outgoing Adaption Layer Indication 2186 parameter. 2188 7.1.12 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2190 This option is a on/off flag and is passed an integer where a 2191 non-zero is on and a zero is off. If enabled no SCTP message 2192 fragmentation will be performed. Instead if a message being sent 2193 exceeds the current PMTU size, the message will NOT be sent and 2194 instead a error will be indicated to the user. 2196 7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 2198 Applications can enable or disable heartbeats for any peer address of 2199 an association, modify an address's heartbeat interval, force a 2200 heartbeat to be sent immediately, and adjust the address's maximum 2201 number of retransmissions sent before an address is considered 2202 unreachable. The following structure is used to access and modify an 2203 address's parameters: 2205 struct sctp_paddrparams { 2206 sctp_assoc_t spp_assoc_id; 2207 struct sockaddr_storage spp_address; 2208 uint32_t spp_hbinterval; 2209 uint16_t spp_pathmaxrxt; 2210 }; 2212 spp_assoc_id - (one-to-many style socket) This is filled in the application, 2213 and identifies the association for this query. 2214 spp_address - This specifies which address is of interest. 2215 spp_hbinterval - This contains the value of the heartbeat interval, 2216 in milliseconds. A value of 0, when modifying the 2217 parameter, specifies that the heartbeat on this 2218 address should be disabled. A value of UINT32_MAX 2219 (4294967295), when modifying the parameter, 2220 specifies that a heartbeat should be sent 2221 immediately to the peer address, and the current 2222 interval should remain unchanged. 2223 spp_pathmaxrxt - This contains the maximum number of 2224 retransmissions before this address shall be 2225 considered unreachable. If a value of zero 2226 is present in this field then no changes are to 2227 be made to this parameter. 2229 To read or modify these parameters, the application should call 2230 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. 2232 7.1.14 Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 2234 Applications that wish to use the sendto() system call may wish to 2235 specify a default set of parameters that would normally be supplied 2236 through the inclusion of ancillary data. This socket option allows 2237 such an application to set the default sctp_sndrcvinfo structure. The 2238 application that wishes to use this socket option simply passes in to 2239 this call the sctp_sndrcvinfo structure defined in Section 5.2.2) The 2240 input parameters accepted by this call include sinfo_stream, 2241 sinfo_flags, sinfo_ppid, sinfo_context, sinfo_timetolive. The user 2242 must set the sinfo_assoc_id field to identify the association to 2243 affect if the caller is using the one-to-many style. 2245 7.1.15 Set notification and ancillary events (SCTP_EVENTS) 2247 This socket option is used to specify various notifications and 2248 ancillary data the user wishes to receive. Please see Section 7.3) 2249 for a full description of this option and its usage. 2251 7.1.16 Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2253 This socket option is a boolean flag which turns on or off mapped V4 2254 addresses. If this option is turned on and the socket is type 2255 PF_INET6, then IPv4 addresses will be mapped to V6 representation. If 2256 this option is turned off, then no mapping will be done of V4 2257 addresses and a user will receive both PF_INET6 and PF_INET type 2258 addresses on the socket. 2260 By default this option is turned on and expects an integer to be 2261 passed where non-zero turns on the option and zero turns off the 2262 option. 2264 7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) 2266 This socket option specifies the maximum size to put in any outgoing 2267 SCTP DATA chunk. If a message is larger than this size it will be 2268 fragmented by SCTP into the specified size. Note that the underlying 2269 SCTP implementation may fragment into smaller sized chunks when the 2270 PMTU of the underlying association is smaller than the value set by 2271 the user. The option expects an integer. 2273 The default value for this option is '0' which indicates the user is 2274 NOT limiting fragmentation and only the PMTU will effect SCTP's 2275 choice of DATA chunk size. 2277 7.2 Read-Only Options 2279 7.2.1 Association Status (SCTP_STATUS) 2281 Applications can retrieve current status information about an 2282 association, including association state, peer receiver window size, 2283 number of unacked data chunks, and number of data chunks pending 2284 receipt. This information is read-only. The following structure is 2285 used to access this information: 2287 struct sctp_status { 2288 sctp_assoc_t sstat_assoc_id; 2289 int32_t sstat_state; 2290 uint32_t sstat_rwnd; 2291 uint16_t sstat_unackdata; 2292 uint16_t sstat_penddata; 2293 uint16_t sstat_instrms; 2294 uint16_t sstat_outstrms; 2295 uint32_t sstat_fragmentation_point; 2296 struct sctp_paddrinfo sstat_primary; 2297 }; 2299 sstat_state - This contains the association's current state one 2300 of the following values: 2302 SCTP_CLOSED 2303 SCTP_BOUND 2304 SCTP_LISTEN 2305 SCTP_COOKIE_WAIT 2306 SCTP_COOKIE_ECHOED 2307 SCTP_ESTABLISHED 2308 SCTP_SHUTDOWN_PENDING 2309 SCTP_SHUTDOWN_SENT 2310 SCTP_SHUTDOWN_RECEIVED 2311 SCTP_SHUTDOWN_ACK_SENT 2313 sstat_rwnd - This contains the association peer's current 2314 receiver window size. 2315 sstat_unackdata - This is the number of unacked data chunks. 2316 sstat_penddata - This is the number of data chunks pending receipt. 2317 sstat_primary - This is information on the current primary peer 2318 address. 2319 sstat_assoc_id - (one-to-many style socket) This holds the an identifier for the 2320 association. All notifications for a given association 2321 have the same association identifier. 2323 sstat_instrms - The number of streams that the peer will 2324 be using inbound. 2326 sstat_outstrms - The number of streams that the endpoint is 2327 allowed to use outbound. 2329 sstat_fragmentation_point - The size at which SCTP fragmentation 2330 will occur. 2332 To access these status values, the application calls getsockopt() 2333 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2334 ignored for one-to-one style socket. 2336 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2338 Applications can retrieve information about a specific peer address 2339 of an association, including its reachability state, congestion 2340 window, and retransmission timer values. This information is 2341 read-only. The following structure is used to access this 2342 information: 2344 struct sctp_paddrinfo { 2345 sctp_assoc_t spinfo_assoc_id; 2346 struct sockaddr_storage spinfo_address; 2347 int32_t spinfo_state; 2348 uint32_t spinfo_cwnd; 2349 uint32_t spinfo_srtt; 2350 uint32_t spinfo_rto; 2351 uint32_t spinfo_mtu; 2352 }; 2354 spinfo_address - This is filled in the application, and contains 2355 the peer address of interest. 2357 On return from getsockopt(): 2359 spinfo_state - This contains the peer addresses's state (either 2360 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifer 2361 SCTP_UNCONFIRMED) 2363 spinfo_cwnd - This contains the peer addresses's current congestion 2364 window. 2365 spinfo_srtt - This contains the peer addresses's current smoothed 2366 round-trip time calculation in milliseconds. 2367 spinfo_rto - This contains the peer addresses's current 2368 retransmission timeout value in milliseconds. 2369 spinfo_mtu - The current P-MTU of this address. 2370 spinfo_assoc_id - (one-to-many style socket) This is filled in the application, 2371 and identifies the association for this query. 2373 To retrieve this information, use sctp_opt_info() with the 2374 SCTP_GET_PEER_ADDR_INFO options. 2376 7.3 Ancillary Data and Notification Interest Options 2378 Applications can receive per-message ancillary information and 2379 notifications of certain SCTP events with recvmsg(). 2381 The following optional information is available to the application: 2383 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 2384 stream number, TSN, SSN, etc. described in Section 5.2.2) 2386 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in Section 2387 5.3.1.1) 2389 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in Section 2390 5.3.1.2) 2392 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in Section 2393 5.3.1.4) 2395 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in Section 2396 5.3.1.3) 2398 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in Section 2399 5.3.1.5) 2401 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 2402 (described in Section 5.3.1.7) 2404 8. SCTP_ADAPTION_INDICATION (sctp_adaption_layer_event): (described 2405 in Section 5.3.1.6) 2407 To receive any ancillary data or notifications, first the application 2408 registers it's interest by calling the SCTP_EVENTS setsockopt() with 2409 the following structure. 2411 struct sctp_event_subscribe{ 2412 u_int8_t sctp_data_io_event; 2413 u_int8_t sctp_association_event; 2414 u_int8_t sctp_address_event; 2415 u_int8_t sctp_send_failure_event; 2416 u_int8_t sctp_peer_error_event; 2417 u_int8_t sctp_shutdown_event; 2418 u_int8_t sctp_partial_delivery_event; 2419 u_int8_t sctp_adaption_layer_event; 2420 }; 2422 sctp_data_io_event - Setting this flag to 1 will cause the reception 2423 of SCTP_SNDRCV information on a per message basis. The application 2424 will need to use the recvmsg() interface so that it can receive the 2425 event information contained in the msg_control field. Please see 2426 Section 5.2 for further details. Setting the flag to 0 will disable 2427 reception of the message control information. 2429 sctp_association_event - Setting this flag to 1 will enable the 2430 reception of association event notifications. Setting the flag to 0 2431 will disable association event notifications. For more information on 2432 event notifications please see Section 5.3. 2434 sctp_address_event - Setting this flag to 1 will enable the reception 2435 of address event notifications. Setting the flag to 0 will disable 2436 address event notifications. For more information on event 2437 notifications please see Section 5.3. 2439 sctp_send_failure_event - Setting this flag to 1 will enable the 2440 reception of send failure event notifications. Setting the flag to 0 2441 will disable send failure event notifications. For more information 2442 on event notifications please see Section 5.3. 2444 sctp_peer_error_event - Setting this flag to 1 will enable the 2445 reception of peer error event notifications. Setting the flag to 0 2446 will disable peer error event notifications. For more information on 2447 event notifications please see Section 5.3. 2449 sctp_shutdown_event - Setting this flag to 1 will enable the 2450 reception of shutdown event notifications. Setting the flag to 0 will 2451 disable shutdown event notifications. For more information on event 2452 notifications please see Section 5.3. 2454 sctp_partial_delivery_event - Setting this flag to 1 will enable the 2455 reception of partial delivery notifications. Setting the flag to 0 2456 will disable partial delivery event notifications. For more 2457 information on event notifications please see Section 5.3. 2459 sctp_adaption_layer_event - Setting this flag to 1 will enable the 2460 reception of adaption layer notifications. Setting the flag to 0 will 2461 disable adaption layer event notifications. For more information on 2462 event notifications please see Section 5.3. 2464 An example where an application would like to receive data io events 2465 and association events but no others would be as follows: 2467 { 2468 struct sctp_event_subscribe event; 2470 memset(&event,0,sizeof(event)); 2472 event.sctp_data_io_event = 1; 2473 event.sctp_association_event = 1; 2475 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENT, &event, sizeof(event)); 2476 } 2478 Note that for one-to-many style SCTP sockets, the caller of recvmsg() 2479 receives ancillary data and notifications for ALL associations bound 2480 to the file descriptor. For one-to-one style SCTP sockets, the 2481 caller receives ancillary data and notifications for only the single 2482 association bound to the file descriptor. 2484 By default both the one-to-one style and one-to-many style socket has 2485 all options off. 2487 8. New Interfaces 2489 Depending on the system, the following interface can be implemented 2490 as a system call or library function. 2492 8.1 sctp_bindx() 2494 The syntax of sctp_bindx() is, 2496 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt, 2497 int flags); 2499 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 2500 If the sd is an IPv6 socket, the addresses passed can either be IPv4 2501 or IPv6 addresses. 2503 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2504 Section 3.1.2 for this usage. 2506 addrs is a pointer to an array of one or more socket addresses. Each 2507 address is contained in its appropriate structure (i.e. struct 2508 sockaddr_in or struct sockaddr_in6) the family of the address type 2509 must be used to distengish the address length (note that this 2510 representation is termed a "packed array" of addresses). The caller 2511 specifies the number of addresses in the array with addrcnt. 2513 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2514 -1, and sets errno to the appropriate error code. 2516 For SCTP, the port given in each socket address must be the same, or 2517 sctp_bindx() will fail, setting errno to EINVAL. 2519 The flags parameter is formed from the bitwise OR of zero or more of 2520 the following currently defined flags: 2522 SCTP_BINDX_ADD_ADDR 2524 SCTP_BINDX_REM_ADDR 2526 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2527 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 2528 addresses from the association. The two flags are mutually exclusive; 2529 if both are given, sctp_bindx() will fail with EINVAL. A caller may 2530 not remove all addresses from an association; sctp_bindx() will 2531 reject such an attempt with EINVAL. 2533 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2534 additional addresses with an endpoint after calling bind(). Or use 2535 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2536 socket is associated with so that no new association accepted will be 2537 associated with those addresses. If the endpoint supports dynamic 2538 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 2539 endpoint to send the appropriate message to the peer to change the 2540 peers address lists. 2542 Adding and removing addresses from a connected association is 2543 optional functionality. Implementations that do not support this 2544 functionality should return EOPNOTSUPP. 2546 8.2 Branched-off Association 2548 After an association is established on a one-to-many style socket, 2549 the application may wish to branch off the association into a 2550 separate socket/file descriptor. 2552 This is particularly desirable when, for instance, the application 2553 wishes to have a number of sporadic message senders/receivers remain 2554 under the original one-to-many style socket but branch off those 2555 associations carrying high volume data traffic into their own 2556 separate socket descriptors. 2558 The application uses sctp_peeloff() call to branch off an association 2559 into a separate socket (Note the semantics are somewhat changed from 2560 the traditional one-to-one style accept() call). Note that the new 2561 socket is a one-to-one style socket. Thus it will be confined to 2562 operations allowed for a one-to-one style socket. 2564 The syntax is: 2566 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id); 2568 the new socket descriptor representing the branched-off 2569 association. 2571 the original one-to-many style socket descriptor returned from the 2572 socket() system call (see Section 3.1.1). 2574 the specified identifier of the association that is to be branched 2575 off to a separate file descriptor (Note, in a traditional 2576 one-to-one style accept() call, this would be an out parameter, 2577 but for the one-to-many style call, this is an in parameter). 2579 8.3 sctp_getpaddrs() 2581 sctp_getpaddrs() returns all peer addresses in an association. The 2582 syntax is, 2584 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2585 struct sockaddr **addrs); 2587 On return, addrs will point to a dynamically allocated packed array 2588 of sockaddr structures of the appropriate type for each address. The 2589 caller should use sctp_freepaddrs() to free the memory. Note that the 2590 in/out parameter addrs must not be NULL. 2592 If sd is an IPv4 socket, the addresses returned will be all IPv4 2593 addresses. If sd is an IPv6 socket, the addresses returned can be a 2594 mix of IPv4 or IPv6 addresses. 2596 For one-to-many style sockets, id specifies the association to query. 2597 For one-to-one style sockets, id is ignored. 2599 On success, sctp_getpaddrs() returns the number of peer addresses in 2600 the association. If there is no association on this socket, 2601 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2602 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 2603 is undefined. 2605 8.4 sctp_freepaddrs() 2607 sctp_freepaddrs() frees all resources allocated by 2608 sctp_getpaddrs(). Its syntax is, 2610 void sctp_freepaddrs(struct sockaddr *addrs); 2612 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2614 8.5 sctp_getladdrs() 2616 sctp_getladdrs() returns all locally bound address(es) on a socket. 2617 The syntax is, 2619 int sctp_getladdrs(int sock, sctp_assoc_t id, 2620 struct sockaddr **ss); 2622 On return, addrs will point to a dynamically allocated packed array 2623 of sockaddr structures of the appropriate type for each local 2624 address. The caller should use sctp_freeladdrs() to free the memory. 2625 Note that the in/out parameter addrs must not be NULL. 2627 If sd is an IPv4 socket, the addresses returned will be all IPv4 2628 addresses. If sd is an IPv6 socket, the addresses returned can be a 2629 mix of IPv4 or IPv6 addresses. 2631 For one-to-many style sockets, id specifies the association to query. 2632 For one-to-one style sockets, id is ignored. 2634 If the id field is set to the value '0' then the locally bound 2635 addresses are returned without regard to any particular association. 2637 On success, sctp_getladdrs() returns the number of local addresses 2638 bound to the socket. If the socket is unbound, sctp_getladdrs() 2639 returns 0, and the value of *addrs is undefined. If an error occurs, 2640 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2642 8.6 sctp_freeladdrs() 2644 sctp_freeladdrs() frees all resources allocated by 2645 sctp_getladdrs(). Its syntax is, 2647 void sctp_freeladdrs(struct sockaddr *addrs); 2649 addrs is the array of peer addresses returned by sctp_getladdrs(). 2651 8.7 sctp_sendmsg() 2653 An implementation may provide a library function (or possibly system 2654 call) to assist the user with the advanced features of SCTP. 2656 sctp_sendmsg(). Its syntax is, 2658 ssize_t sctp_sendmsg(int s, 2659 const void *msg, 2660 size_t len, 2661 struct sockaddr *to, 2662 socklen_t tolen, 2663 uint32_t ppid, 2664 uint32_t flags, 2665 uint16_t stream_no, 2666 uint32_t timetolive, 2667 uint32_t context) 2669 s - is the socket descriptor 2670 msg - is the message to be sent. 2671 len - is the length of the message. 2672 to - is the destination address of the message. 2674 tolen - is the length of the destination address. 2675 ppid - is the same as sinfo_ppid (see section 5.2.2) 2676 flags - is the same as sinfo_flags (see section 5.2.2) 2677 stream_no - is the same as sinfo_stream (see section 5.2.2) 2678 timetolive - is the same as sinfo_timetolive (see section 5.2.2) 2679 context - is the same as sinfo_context (see section 5.2.2) 2681 8.8 sctp_recvmsg() 2683 An implementation may provide a library function (or possibly system 2684 call) to assist the user with the advanced features of SCTP. Note 2685 that in order for the sctp_sndrcvinfo structure to be filled in by 2686 sctp_recvmsg() the caller must enable the sctp_data_io_events with 2687 the SCTP_EVENTS option. 2689 sctp_recvmsg(). Its syntax is, 2691 ssize_t sctp_recvmsg(int s, 2692 void *msg, 2693 size_t *len, 2694 struct sockaddr *from, 2695 socklen_t *fromlen 2696 struct sctp_sndrcvinfo *sinfo 2697 int *msg_flags) 2699 s - is the socket descriptor 2700 msg - is a message buffer to be filled. 2701 len - is the length of the message buffer. 2702 from - is a pointer to a address to be filled with 2703 the sender of this messages address. 2704 fromlen - is the from length. 2705 sinfo - A pointer to a sctp_sndrcvinfo structure 2706 to be filled upon receipt of the message. 2707 msg_flags - A pointer to a integer to be filled with 2708 any message flags (e.g. MSG_NOTIFICATION). 2710 8.9 sctp_connectx() 2712 An implementation may provide a library function (or possibly system 2713 call) to assist the user with associating to an endpoint that is 2714 multi-homed. Much like sctp_bindx() this call allows a caller to 2715 specify multiple addresses at which a peer can be reached. 2717 sctp_connectx(). Its syntax is, 2718 int sctp_connectx(int s, 2719 struct sockaddr *addrs, 2720 int addrcnt) 2722 s - is the socket descriptor 2723 addrs - is an array of addresses. 2724 addrcnt - is the number of addresses in the array. 2726 9. Preprocessor Constants 2728 For application portability it is desireable to define pre-processor 2729 constants for determination if sctp is present and supports various 2730 features. The following pre-processor constants should be defined in 2731 a include file, sctp.h. 2733 HAVE_SCTP - If this constant is defined to 1, then an implementation 2734 of SCTP is available. 2736 HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel 2737 SCTP implementation is available through the sockets interface. 2739 HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP 2740 implementation supports the partial reliablility extension to 2741 SCTP. 2743 HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP 2744 implementation supports the dynamic address extension to SCTP. 2746 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the 2747 SCTP implementation supports the ability to request setting of the 2748 remote primary address. 2750 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1, 2751 then the SCTP implementation supports the satellite network 2752 extension to SCTP. 2754 HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP 2755 implementation dedicates separate buffer space to each association 2756 on a one-to-many socket. If this constant is defined to 0, then 2757 the implementation provides a single block of shared buffer space 2758 for a one-to-many socket. 2760 HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the SCTP 2761 implementation supports initiating an association on a one-to-one 2762 style socket without the use of connect(), as outlined in Section 2763 4.1.5. 2765 10. Security Considerations 2767 Many TCP and UDP implementations reserve port numbers below 1024 for 2768 privileged users. If the target platform supports privileged users, 2769 the SCTP implementation SHOULD restrict the ability to call bind() or 2770 sctp_bindx() on these port numbers to privileged users. 2772 Similarly unpriviledged users should not be able to set protocol 2773 parameters which could result in the congestion control algorithm 2774 being more aggressive than permitted on the public Internet. These 2775 parameters are: 2777 struct sctp_rtoinfo 2779 If an unprivileged user inherits a one-to-many style socket with open 2780 associations on a privileged port, it MAY be permitted to accept new 2781 associations, but it SHOULD NOT be permitted to open new 2782 associations. This could be relevant for the r* family of protocols. 2784 11. Acknowledgments 2786 The authors wish to thank Kavitha Baratakke, Mike Bartlett, Jon 2787 Berger, Scott Kimble, Renee Revis, and many others on the TSVWG 2788 mailing list for contributing valuable comments. 2790 A special thanks to Phillip Conrad, for his suggested text, quick and 2791 constructive insights, and most of all his persistent fighting to 2792 keep the interface to SCTP usable for the application programmer. 2794 References 2796 [1] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2797 September 1981. 2799 [2] Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 2800 1980. 2802 [3] Braden, B., "T/TCP -- TCP Extensions for Transactions Functional 2803 Specification", RFC 1644, July 1994. 2805 [4] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 2806 9, RFC 2026, October 1996. 2808 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2809 Levels", BCP 14, RFC 2119, March 1997. 2811 [6] Stevens, W. and M. Thomas, "Advanced Sockets API for IPv6", RFC 2812 2292, February 1998. 2814 [7] Gilligan, R., Thomson, S., Bound, J. and W. Stevens, "Basic 2815 Socket Interface Extensions for IPv6", RFC 2553, March 1999. 2817 [8] Stewart, R., Xie, Q., Morneault, K., Sharp, C., Schwarzbauer, 2818 H., Taylor, T., Rytina, I., Kalla, M., Zhang, L. and V. Paxson, 2819 "Stream Control Transmission Protocol", RFC 2960, October 2000. 2821 Authors' Addresses 2823 Randall R. Stewart 2824 Cisco Systems, Inc. 2825 8725 West Higgins Road 2826 Suite 300 2827 Chicago, IL 60631 2828 USA 2830 Phone: 2831 EMail: rrs@cisco.com 2832 Qiaobing Xie 2833 Motorola, Inc. 2834 1501 W. Shure Drive, #2309 2835 Arlington Heights, IL 60004 2836 USA 2838 Phone: 2839 EMail: qxie1@email.mot.com 2841 La Monte H.P. Yarroll 2842 USACE ERDC-CERL. 2843 2902 Newmark Drive 2844 Champaign, IL 6182-1076 2845 USA 2847 Phone: 2848 EMail: piggy@acm.org 2850 Jonathan Wood 2851 DoCoMo USA Labs 2852 181 Metro Drive, Suite 300 2853 San Jose, CA 95110 2854 USA 2856 Phone: 2857 EMail: jonwood@speakeasy.net 2859 Kacheong Poon 2860 Consultant 2862 Milpitas, CA 2864 Phone: 2865 EMail: kcpoon@yahoo.com 2867 Ken Fujita 2868 NEC USA, Inc. 2869 10080 Wolfe Road, Suite SW3-350 2870 Cupertino, CA 95014 2871 USA 2873 Phone: 2874 EMail: fken@ccrl.sj.nec.com 2875 Michael Tuexen 2876 Univ. of Applied Sciences Muenster 2877 Stegerwaldstr. 39 2878 48565 Steinfurt 2879 Germany 2881 EMail: tuexen@fh-muenster.de 2883 Appendix A. one-to-one style Code Example 2885 The following code is a simple implementation of an echo server over 2886 SCTP. The example shows how to use some features of one-to-one style 2887 IPv4 SCTP sockets, including: 2889 o Opening, binding, and listening for new associations on a socket; 2891 o Enabling ancillary data 2893 o Enabling notifications 2895 o Using ancillary data with sendmsg() and recvmsg() 2897 o Using MSG_EOR to determine if an entire message has been read 2899 o Handling notifications 2901 #include 2902 #include 2903 #include 2904 #include 2905 #include 2906 #include 2907 #include 2908 #include 2909 #include 2911 #define BUFLEN 100 2913 static void 2914 handle_event(void *buf) 2915 { 2916 struct sctp_assoc_change *sac; 2917 struct sctp_send_failed *ssf; 2918 struct sctp_paddr_change *spc; 2919 struct sctp_remote_error *sre; 2920 union sctp_notification *snp; 2921 char addrbuf[INET6_ADDRSTRLEN]; 2922 const char *ap; 2923 struct sockaddr_in *sin; 2924 struct sockaddr_in6 *sin6; 2926 snp = buf; 2928 switch (snp->sn_header.sn_type) { 2929 case SCTP_ASSOC_CHANGE: 2931 sac = &snp->sn_assoc_change; 2932 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2933 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2934 sac->sac_inbound_streams, sac->sac_outbound_streams); 2935 break; 2936 case SCTP_SEND_FAILED: 2937 ssf = &snp->sn_send_failed; 2938 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2939 ssf->ssf_error); 2940 break; 2942 case SCTP_PEER_ADDR_CHANGE: 2943 spc = &snp->sn_paddr_change; 2944 if (spc->spc_aaddr.ss_family == AF_INET) { 2945 sin = (struct sockaddr_in *)&spc->spc_aaddr; 2946 ap = inet_ntop(AF_INET, &sin->sin_addr, 2947 addrbuf, INET6_ADDRSTRLEN); 2948 } else { 2949 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 2950 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 2951 addrbuf, INET6_ADDRSTRLEN); 2952 } 2953 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2954 spc->spc_state, spc->spc_error); 2955 break; 2956 case SCTP_REMOTE_ERROR: 2957 sre = &snp->sn_remote_error; 2958 printf("^^^ remote_error: err=%hu len=%hu\n", 2959 ntohs(sre->sre_error), ntohs(sre->sre_length)); 2960 break; 2961 case SCTP_SHUTDOWN_EVENT: 2962 printf("^^^ shutdown event\n"); 2963 break; 2964 default: 2965 printf("unknown type: %hu\n", snp->sn_header.sn_type); 2966 break; 2967 } 2968 } 2970 static void * 2971 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2972 ssize_t *nrp, size_t cmsglen) 2973 { 2974 ssize_t nr = 0, nnr = 0; 2975 struct iovec iov[1]; 2977 *nrp = 0; 2978 iov->iov_base = buf; 2979 iov->iov_len = *buflen; 2980 msg->msg_iov = iov; 2981 msg->msg_iovlen = 1; 2983 for (;;) { 2984 #ifndef MSG_XPG4_2 2985 #define MSG_XPG4_2 0 2986 #endif 2987 msg->msg_flags = MSG_XPG4_2; 2988 msg->msg_controllen = cmsglen; 2990 nnr = recvmsg(fd, msg, 0); 2991 if (nnr <= 0) { 2992 /* EOF or error */ 2993 *nrp = nr; 2994 return (NULL); 2995 } 2996 nr += nnr; 2998 if ((msg->msg_flags & MSG_EOR) != 0) { 2999 *nrp = nr; 3000 return (buf); 3001 } 3003 /* Realloc the buffer? */ 3004 if (*buflen == (size_t)nr) { 3005 buf = realloc(buf, *buflen * 2); 3006 if (buf == 0) { 3007 fprintf(stderr, "out of memory\n"); 3008 exit(1); 3009 } 3010 *buflen *= 2; 3011 } 3013 /* Set the next read offset */ 3014 iov->iov_base = (char *)buf + nr; 3015 iov->iov_len = *buflen - nr; 3017 } 3018 } 3020 static void 3021 echo(int fd, int socketModeone_to_many) 3022 { 3023 ssize_t nr; 3024 struct sctp_sndrcvinfo *sri; 3025 struct msghdr msg[1]; 3026 struct cmsghdr *cmsg; 3027 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 3028 char *buf; 3029 size_t buflen; 3030 struct iovec iov[1]; 3031 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 3033 /* Allocate the initial data buffer */ 3034 buflen = BUFLEN; 3035 if (!(buf = malloc(BUFLEN))) { 3036 fprintf(stderr, "out of memory\n"); 3037 exit(1); 3038 } 3040 /* Set up the msghdr structure for receiving */ 3041 memset(msg, 0, sizeof (*msg)); 3042 msg->msg_control = cbuf; 3043 msg->msg_controllen = cmsglen; 3044 msg->msg_flags = 0; 3045 cmsg = (struct cmsghdr *)cbuf; 3046 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 3048 /* Wait for something to echo */ 3049 while (buf = mysctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 3051 /* Intercept notifications here */ 3052 if (msg->msg_flags & MSG_NOTIFICATION) { 3053 handle_event(buf); 3054 continue; 3055 } 3057 iov->iov_base = buf; 3058 iov->iov_len = nr; 3059 msg->msg_iov = iov; 3060 msg->msg_iovlen = 1; 3062 printf("got %u bytes on stream %hu:\n", nr, 3063 sri->sinfo_stream); 3064 write(0, buf, nr); 3066 /* Echo it back */ 3067 msg->msg_flags = MSG_XPG4_2; 3068 if (sendmsg(fd, msg, 0) < 0) { 3069 perror("sendmsg"); 3070 exit(1); 3071 } 3072 } 3073 if (nr < 0) { 3074 perror("recvmsg"); 3075 } 3076 if(socketModeone_to_many == 0) 3077 close(fd); 3078 } 3080 int main() 3081 { 3082 struct sctp_event_subscribe event; 3083 int lfd, cfd; 3084 int onoff = 1; 3085 struct sockaddr_in sin[1]; 3087 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 3088 perror("socket"); 3089 exit(1); 3090 } 3092 sin->sin_family = AF_INET; 3093 sin->sin_port = htons(7); 3094 sin->sin_addr.s_addr = INADDR_ANY; 3095 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3096 perror("bind"); 3097 exit(1); 3098 } 3100 if (listen(lfd, 1) == -1) { 3101 perror("listen"); 3102 exit(1); 3103 } 3105 /* Wait for new associations */ 3106 for (;;) { 3107 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3108 perror("accept"); 3109 exit(1); 3110 } 3112 /* Enable all events */ 3113 event.sctp_data_io_event = 1; 3114 event.sctp_association_event = 1; 3115 event.sctp_address_event = 1; 3116 event.sctp_send_failure_event = 1; 3117 event.sctp_peer_error_event = 1; 3118 event.sctp_shutdown_event = 1; 3119 event.sctp_partial_delivery_event = 1; 3120 event.sctp_adaption_layer_event = 1; 3121 if (setsockopt(cfd, IPPROTO_SCTP, 3122 SCTP_EVENTS, &event, 3123 sizeof(event)) != 0) { 3124 perror("setevent failed"); 3125 exit(1); 3126 } 3127 /* Echo back any and all data */ 3128 echo(cfd,0); 3129 } 3130 } 3132 Appendix B. one-to-many style Code Example 3134 The following code is a simple implementation of an echo server over 3135 SCTP. The example shows how to use some features of one-to-many style 3136 IPv4 SCTP sockets, including: 3138 o Opening and binding of a socket; 3140 o Enabling ancillary data 3142 o Enabling notifications 3144 o Using ancillary data with sendmsg() and recvmsg() 3146 o Using MSG_EOR to determine if an entire message has been read 3148 o Handling notifications 3150 Note most functions defined in Appendix A are reused in this example. 3152 int main() 3153 { 3154 int fd; 3155 int idleTime = 2; 3156 struct sockaddr_in sin[1]; 3157 struct sctp_event_subscribe event; 3159 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3160 perror("socket"); 3161 exit(1); 3162 } 3164 sin->sin_family = AF_INET; 3165 sin->sin_port = htons(7); 3166 sin->sin_addr.s_addr = INADDR_ANY; 3167 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3168 perror("bind"); 3169 exit(1); 3170 } 3172 /* Enable all notifications and events */ 3173 event.sctp_data_io_event = 1; 3174 event.sctp_association_event = 1; 3175 event.sctp_address_event = 1; 3176 event.sctp_send_failure_event = 1; 3177 event.sctp_peer_error_event = 1; 3178 event.sctp_shutdown_event = 1; 3179 event.sctp_partial_delivery_event = 1; 3180 event.sctp_adaption_layer_event = 1; 3181 if (setsockopt(fd, IPPROTO_SCTP, 3182 SCTP_EVENTS, &event, 3183 sizeof(event)) != 0) { 3184 perror("setevent failed"); 3185 exit(1); 3186 } 3187 /* Set associations to auto-close in 2 seconds of 3188 * inactivity 3189 */ 3190 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3191 &idleTime, 4) < 0) { 3192 perror("setsockopt SCTP_AUTOCLOSE"); 3193 exit(1); 3194 } 3196 /* Allow new associations to be accepted */ 3197 if (listen(fd, 1) < 0) { 3198 perror("listen"); 3199 exit(1); 3200 } 3202 /* Wait for new associations */ 3203 while(1){ 3204 /* Echo back any and all data */ 3205 echo(fd,1); 3206 } 3207 } 3209 Intellectual Property Statement 3211 The IETF takes no position regarding the validity or scope of any 3212 intellectual property or other rights that might be claimed to 3213 pertain to the implementation or use of the technology described in 3214 this document or the extent to which any license under such rights 3215 might or might not be available; neither does it represent that it 3216 has made any effort to identify any such rights. Information on the 3217 IETF's procedures with respect to rights in standards-track and 3218 standards-related documentation can be found in BCP-11. Copies of 3219 claims of rights made available for publication and any assurances of 3220 licenses to be made available, or the result of an attempt made to 3221 obtain a general license or permission for the use of such 3222 proprietary rights by implementors or users of this specification can 3223 be obtained from the IETF Secretariat. 3225 The IETF invites any interested party to bring to its attention any 3226 copyrights, patents or patent applications, or other proprietary 3227 rights which may cover technology that may be required to practice 3228 this standard. Please address the information to the IETF Executive 3229 Director. 3231 Full Copyright Statement 3233 Copyright (C) The Internet Society (2003). All Rights Reserved. 3235 This document and translations of it may be copied and furnished to 3236 others, and derivative works that comment on or otherwise explain it 3237 or assist in its implementation may be prepared, copied, published 3238 and distributed, in whole or in part, without restriction of any 3239 kind, provided that the above copyright notice and this paragraph are 3240 included on all such copies and derivative works. However, this 3241 document itself may not be modified in any way, such as by removing 3242 the copyright notice or references to the Internet Society or other 3243 Internet organizations, except as needed for the purpose of 3244 developing Internet standards in which case the procedures for 3245 copyrights defined in the Internet Standards process must be 3246 followed, or as required to translate it into languages other than 3247 English. 3249 The limited permissions granted above are perpetual and will not be 3250 revoked by the Internet Society or its successors or assignees. 3252 This document and the information contained herein is provided on an 3253 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3254 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3255 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3256 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3257 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3259 Acknowledgement 3261 Funding for the RFC Editor function is currently provided by the 3262 Internet Society.