idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-05.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 34 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** There are 43 instances of lines with control characters in the document. ** 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 834 has weird spacing: '...n. The value...' == Line 846 has weird spacing: '...er send and ...' == Line 1019 has weird spacing: '...g_level cms...' == Line 1073 has weird spacing: '...g_level cms...' == Line 1685 has weird spacing: '... msghdr msg;...' == (4 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 (October 2, 2002) is 7870 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 1496, but not defined == Unused Reference: '4' is defined on line 2673, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 2676, 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: 11 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: April 2, 2003 Q. Xie 5 L. Yarroll 6 Motorola, Inc. 7 J. Wood 8 DoCoMo USA Labs 9 K. Poon 10 Sun Microsystems, Inc. 11 K. Fujita 12 NEC USA, Inc. 13 M. Tuexen 14 Siemens AG 15 October 2, 2002 17 Sockets API Extensions for Stream Control Transmission Protocol 18 (SCTP) 19 draft-ietf-tsvwg-sctpsocket-05.txt 21 Status of this Memo 23 This document is an Internet-Draft and is in full conformance with 24 all provisions of Section 10 of RFC2026. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as Internet- 29 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 April 2, 2003. 44 Copyright Notice 46 Copyright (C) The Internet Society (2002). 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 . . . . . . . . . . . . . . . . . . . . . . . 5 57 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 7 58 2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 7 59 3. UDP-style Interface . . . . . . . . . . . . . . . . . . . 8 60 3.1 3.1 Basic Operation . . . . . . . . . . . . . . . . . . . 8 61 3.1.1 socket() - UDP Style Syntax . . . . . . . . . . . . . . . 9 62 3.1.2 bind() - UDP Style Syntax . . . . . . . . . . . . . . . . 9 63 3.1.3 listen() - UDP Style Syntax . . . . . . . . . . . . . . . 10 64 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax . . . . . . . . 11 65 3.1.5 close() - UDP Style Syntax . . . . . . . . . . . . . . . . 12 66 3.1.6 connect() - UDP Style Syntax . . . . . . . . . . . . . . . 13 67 3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 13 68 3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14 69 3.4 Special considerations . . . . . . . . . . . . . . . . . . 14 70 4. TCP-style Interface . . . . . . . . . . . . . . . . . . . 17 71 4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 17 72 4.1.1 socket() - TCP Style Syntax . . . . . . . . . . . . . . . 18 73 4.1.2 bind() - TCP Style Syntax . . . . . . . . . . . . . . . . 18 74 4.1.3 listen() - TCP Style Syntax . . . . . . . . . . . . . . . 19 75 4.1.4 accept() - TCP Style Syntax . . . . . . . . . . . . . . . 19 76 4.1.5 connect() - TCP Style Syntax . . . . . . . . . . . . . . . 20 77 4.1.6 close() - TCP Style Syntax . . . . . . . . . . . . . . . . 21 78 4.1.7 shutdown() - TCP Style Syntax . . . . . . . . . . . . . . 21 79 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax . . . . . . . . 22 80 4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 23 81 5. Data Structures . . . . . . . . . . . . . . . . . . . . . 24 82 5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 24 83 5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 25 84 5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 26 85 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 27 86 5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 30 87 5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 30 88 5.3.1.1 SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . . . 32 89 5.3.1.2 SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . . . 34 90 5.3.1.3 SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . . . 35 91 5.3.1.4 SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . . . 36 92 5.3.1.5 SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . . . 38 93 5.3.1.6 SCTP_ADAPTION_INDICATION . . . . . . . . . . . . . . . . . 38 94 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . . . 39 95 5.4 Ancillary Data Considerations and Semantics . . . . . . . 40 96 5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 40 97 5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 40 98 5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 41 99 6. Common Operations for Both Styles . . . . . . . . . . . . 43 100 6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 43 101 6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 44 102 6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 44 103 6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 44 104 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 46 105 7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 48 106 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 48 107 7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 49 108 7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 50 109 7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 50 110 7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 51 111 7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 51 112 7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 51 113 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 51 114 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) . . . . . . . 51 115 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 52 116 7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER) . . 52 117 7.1.12 Set default message time outs (SCTP_SET_STREAM_TIMEOUTS) . 52 118 7.1.13 Enable/Disable message fragmentation 119 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 53 120 7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) . . . 53 121 7.1.15 Set default send parameters (SET_DEFAULT_SEND_PARAM) . . . 54 122 7.1.16 Set notification and ancillary events (SCTP_SET_EVENTS) . 54 123 7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 54 124 7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 55 125 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 56 126 7.3 Ancillary Data and Notification Interest Options . . . . . 57 127 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 60 128 8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 60 129 8.2 Branched-off Association . . . . . . . . . . . . . . . . . 61 130 8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 61 131 8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 62 132 8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 62 133 8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 63 134 9. Security Considerations . . . . . . . . . . . . . . . . . 64 135 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 65 136 References . . . . . . . . . . . . . . . . . . . . . . . . 66 137 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 66 138 A. TCP-style Code Example . . . . . . . . . . . . . . . . . . 69 139 B. UDP-style Code Example . . . . . . . . . . . . . . . . . . 75 140 Full Copyright Statement . . . . . . . . . . . . . . . . . 77 142 1. Introduction 144 The sockets API has provided a standard mapping of the Internet 145 Protocol suite to many operating systems. Both TCP RFC793 [1] and 146 UDP RFC768 [2] have benefited from this standard representation and 147 access method across many diverse platforms. SCTP is a new protocol 148 that provides many of the characteristics of TCP but also 149 incorporates semantics more akin to UDP. This document defines a 150 method to map the existing sockets API for use with SCTP, providing 151 both a base for access to new features and compatibility so that most 152 existing TCP applications can be migrated to SCTP with few (if any) 153 changes. 155 There are three basic design objectives: 157 1) Maintain consistency with existing sockets APIs: 159 We define a sockets mapping for SCTP that is consistent with other 160 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 161 IPv6). 163 2) Support a UDP-style interface 165 This set of semantics is similar to that defined for connection 166 less protocols, such as UDP. It is more efficient than a TCP-like 167 connection-oriented interface in terms of exploring the new 168 features of SCTP. 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 TCP-style interface 175 This interface supports the same basic 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 will be 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 UDP-style mapping and the TCP-style 188 mapping. These two modes share some common data structures and 189 operations, but will require the use of two different application 190 programming models. 192 A mechanism is defined to convert a UDP-style SCTP association into a 193 TCP-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. UDP-style Interface 213 The UDP-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 3.1 Basic Operation 224 A typical server in this model 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 model, 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 one of the transport addresses of the 256 association. The sctp_peeloff() call will return a new socket which 257 can then be used with recv() and send() functions for message 258 passing. See Section Section 8.2 for more on branched-off 259 associations. 261 Once an association is branched off to a separate socket, it becomes 262 completely separated from the original socket. All subsequent 263 control and data operations to that association must be done through 264 the new socket. For example, the close operation on the original 265 socket will not terminate any associations that have been branched 266 off to a different socket. 268 We will discuss the UDP-style socket calls in more details in the 269 following subsections. 271 3.1.1 socket() - UDP Style Syntax 273 Applications use socket() to create a socket descriptor to represent 274 an SCTP endpoint. 276 The syntax is, 278 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 280 or, 282 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 284 Here, SOCK_SEQPACKET indicates the creation of a UDP-style 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() - UDP Style Syntax 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() - UDP Style Syntax 341 By default, new associations are not accepted for UDP style sockets. 342 An application uses listen() to mark a socket as being able to accept 343 new associations. The syntax is, 345 int listen(int socket, int backlog); 346 socket - the socket descriptor of the endpoint. 347 backlog - ignored for UDP-style sockets. 349 Note that UDP-style socket consumers do not need to call accept to 350 retrieve new associations. Calling accept() on a UDP-style socket 351 should return EOPNOTSUPP. Rather, new associations are accepted 352 automatically, and notifications of the new associations are 353 delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if these 354 notifications are enabled). Clients will typically not call listen, 355 so that they can be assured that the only associations on the socket 356 will be ones they actively initiated. Server or peer-to-peer 357 sockets, on the other hand, will always accept new associations, so a 358 well-written application using server UDP-style sockets must be 359 prepared to handle new associations from unwanted peers. 361 Also note that the SCTP_ASSOC_CHANGE event provides the association 362 ID for a new association, so if applications wish to use the 363 association ID as input to other socket calls, they should ensure 364 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 365 default). 367 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax 369 An application uses sendmsg() and recvmsg() call to transmit data to 370 and receive data from its peer. 372 ssize_t sendmsg(int socket, const struct msghdr *message, int flags); 374 ssize_t recvmsg(int socket, struct msghdr *message, int flags); 376 socket: the socket descriptor of the endpoint. 378 message: pointer to the msghdr structure which contains a single user 379 message and possibly some ancillary data. See Section 5 for 380 complete description of the data structures. 382 flags: No new flags are defined for SCTP at this level. See Section 383 5 for SCTP-specific flags used in the msghdr structure. 385 As we will see in Section 5, along with the user data, the ancillary 386 data field is used to carry the sctp_sndrcvinfo and/or the 387 sctp_initmsg structures to perform various SCTP functions including 388 specifying options for sending each user message. Those options, 389 depending on whether sending or receiving, include stream number, 390 stream sequence number, various flags, context and payload protocol 391 Id, etc. 393 When sending user data with sendmsg(), the msg_name field in msghdr 394 structure will be filled with one of the transport addresses of the 395 intended receiver. If there is no association existing between the 396 sender and the intended receiver, the sender's SCTP stack will set up 397 a new association and then send the user data (see Section 3.2 for 398 more on implicit association setup). 400 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 401 be delivered if that notification has been enabled, and no more data 402 can be sent to that association. Any attempt to send more data will 403 cause sendmsg() to return with an ESHUTDOWN error. Note that the 404 socket is still open for reading at this point so it is possible to 405 retrieve notifications. 407 When receiving a user message with recvmsg(), the msg_name field in 408 msghdr structure will be populated with the source transport address 409 of the user data. The caller of recvmsg() can use this address 410 information to determine to which association the received user 411 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 412 applications must use the peer transport address provided in the 413 msg_name field by recvmsg() to perform correlation to an association, 414 since they will not have the association ID. 416 If all data in a single message has been delivered, MSG_EOR will be 417 set in the msg_flags field of the msghdr structure (see section 418 Section 5.1). 420 If the application does not provide enough buffer space to completely 421 receive a data message, MSG_EOR will not be set in msg_flags. 422 Successive reads will consume more of the same message until the 423 entire message has been delivered, and MSG_EOR will be set. 425 If the SCTP stack is running low on buffers, it may partially deliver 426 a message. In this case, MSG_EOR will not be set, and more calls to 427 recvmsg() will be necessary to completely consume the message. Only 428 one message at a time can be partially delivered. 430 Note, if the socket is a branched-off socket that only represents one 431 association (see Section 3.1), the msg_name field is not used when 432 sending data (i.e., ignored by the SCTP stack). 434 3.1.5 close() - UDP Style Syntax 436 Applications use close() to perform graceful shutdown (as described 437 in Section 10.1 of RFC2960 [8]) on ALL the associations currently 438 represented by a UDP-style socket. 440 The syntax is: 442 ret = close(int sd); 444 sd - the socket descriptor of the associations to be closed. 446 To gracefully shutdown a specific association represented by the UDP- 447 style socket, an application should use the sendmsg() call, passing 448 no user data, but including the MSG_EOF flag in the ancillary data 449 (see Section 5.2.2). 451 If sd in the close() call is a branched-off socket representing only 452 one association, the shutdown is performed on that association only. 454 3.1.6 connect() - UDP Style Syntax 456 An application may use the connect() call in the UDP model to 457 initiate an association without sending data. 459 The syntax is: 461 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 463 sd: the socket descriptor to have a new association added to. 465 nam: the address structure (either struct sockaddr_in or struct 466 sockaddr_in6 defined in RFC2553 [7]). 468 len: the size of the address. 470 3.2 Implicit Association Setup 472 Once all bind() calls are complete on a UDP-style socket, the 473 application can begin sending and receiving data using the sendmsg()/ 474 recvmsg() or sendto()/recvfrom() calls, without going through any 475 explicit association setup procedures (i.e., no connect() calls 476 required). 478 Whenever sendmsg() or sendto() is called and the SCTP stack at the 479 sender finds that there is no association existing between the sender 480 and the intended receiver (identified by the address passed either in 481 the msg_name field of msghdr structure in the sendmsg() call or the 482 dest_addr field in the sendto() call), the SCTP stack will 483 automatically setup an association to the intended receiver. 485 Upon the successful association setup a SCTP_COMM_UP notification 486 will be dispatched to the socket at both the sender and receiver 487 side. This notification can be read by the recvmsg() system call 488 (see Section 3.1.3). 490 Note, if the SCTP stack at the sender side supports bundling, the 491 first user message may be bundled with the COOKIE ECHO message 492 RFC2960 [8]. 494 When the SCTP stack sets up a new association implicitly, it first 495 consults the sctp_initmsg structure, which is passed along within the 496 ancillary data in the sendmsg() call (see Section 5.2.1 for details 497 of the data structures), for any special options to be used on the 498 new association. 500 If this information is not present in the sendmsg() call, or if the 501 implicit association setup is triggered by a sendto() call, the 502 default association initialization parameters will be used. These 503 default association parameters may be set with respective 504 setsockopt() calls or be left to the system defaults. 506 Implicit association setup cannot be initiated by send()/recv() 507 calls. 509 3.3 Non-blocking mode 511 Some SCTP users might want to avoid blocking when they call socket 512 interface function. 514 Whenever the user which want to avoid blocking must call select() 515 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and check 516 the socket status is writable or readable. If the socket status 517 isn't writeable or readable, the user should not call sendmsg()/ 518 sendto() and recvmsg()/recvfrom(). 520 Once all bind() calls are complete on a UDP-style socket, the 521 application must set the non-blocking option by a fcntl() (such as 522 O_NONBLOCK). After which the sendmsg() function returns immediately, 523 and the success or failure of the data message (and possible 524 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 525 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 526 be sent (due to a CANT_START_ASSOC), the sender will also receive a 527 SCTP_SEND_FAILED event. Those event(s) can be received by the user 528 calling of recvmsg(). A server (having called listen()) is also 529 notified of an association up event by the reception of a 530 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 531 possibly the reception of the first data message. 533 In order to shutdown the association gracefully, the user must call 534 sendmsg() with no data and with the MSG_EOF flag set. The function 535 returns immediately, and completion of the graceful shutdown is 536 indicated by an SCTP_ASSOC_CHANGE notification of type 537 SHUTDOWN_COMPLETE (see Section 5.3.1.1). 539 3.4 Special considerations 541 The fact that a UDP-style socket can provide access to many SCTP 542 associations through a single socket descriptor has important 543 implications for both application programmers and system programmers 544 implementing this API. A key issue is how buffer space inside the 545 sockets layer is managed. Because this implementation detail 546 directly affects how application programmers must write their code to 547 ensure correct operation and portability, this section provides some 548 guidance to both implementors and application programmers. 550 An important feature that SCTP shares with TCP is flow control: 551 specifically, a sender may not send data faster than the receiver can 552 consume it. 554 For TCP, flow control is typically provided for in the sockets API as 555 follows. If the reader stops reading, the sender queues messages in 556 the socket layer until it uses all of its socket buffer space 557 allocation creating a "stalled connection". Further attempts to 558 write to the socket will block or return the error EAGAIN (for a non- 559 blocking socket). At some point, either the connection is closed, or 560 the receiver begins to read again freeing space in the output queue. 562 For TCP-style SCTP sockets (this includes sockets descriptors that 563 were separated from a UDP style socket with sctp_peeloff()) the 564 behavior is identical. For UDP-style SCTP sockets, the fact that we 565 have multiple associations on a single socket makes the situation 566 more complicated. If the implementation uses a single buffer space 567 allocation shared by all associations, a single stalled association 568 can prevent the further sending of data on all associations active on 569 a particular UDP-style socket. 571 For a blocking socket, it should be clear that a single stalled 572 association can block the entire socket. For this reason, 573 application programmers may want to use non-blocking UDP-style 574 sockets. The application should at least be able to send messages to 575 the non-stalled associations. 577 But a non-blocking socket is not sufficient if the API implementor 578 has chosen a single shared buffer allocation for the socket. A 579 single stalled association would eventually cause the shared 580 allocation to fill, and it would become impossible to send even to 581 non-stalled associations. 583 The API implementor can solve this problem by providing each 584 association with its own allocation of outbound buffer space. Each 585 association should conceptually have as much buffer space as it would 586 have if it had its own socket. As a bonus, this simplifies the 587 implementation of sctp_peeloff(). 589 To ensure that a given stalled association will not prevent other 590 non-stalled associations from being writable, application programmers 591 should either: 593 (a) demand that the underlying implementation dedicates independent 594 buffer space allotments to each association (as suggested above), 595 or 597 (b) verify that their application layer protocol does not permit 598 large amounts of unread data at the receiver (this is true of some 599 request-response protocols, for example), or 601 (c) use TCP-style sockets for association which may potentially stall 602 (either from the beginning, or by using sctp_peeloff before 603 sending large amounts of data that may cause a stalled condition). 605 4. TCP-style Interface 607 The goal of this model is to follow as closely as possible the 608 current practice of using the sockets interface for a connection 609 oriented protocol, such as TCP. This model enables existing 610 applications using connection oriented protocols to be ported to SCTP 611 with very little effort. 613 Note that some new SCTP features and some new SCTP socket options can 614 only be utilized through the use of sendmsg() and recvmsg() calls, 615 see Section 4.1.8. 617 4.1 Basic Operation 619 A typical server in TCP-style model uses the following system call 620 sequence to prepare an SCTP endpoint for servicing requests: 622 1. socket() 624 2. bind() 626 3. listen() 628 4. accept() 630 The accept() call blocks until a new association is set up. It 631 returns with a new socket descriptor. The server then uses the new 632 socket descriptor to communicate with the client, using recv() and 633 send() calls to get requests and send back responses. 635 Then it calls 637 5. close() 639 to terminate the association. 641 A typical client uses the following system call sequence to setup an 642 association with a server to request services: 644 1. socket() 646 2. connect() 648 After returning from connect(), the client uses send() and recv() 649 calls to send out requests and receive responses from the server. 651 The client calls 652 3. close() 654 to terminate this association when done. 656 4.1.1 socket() - TCP Style Syntax 658 Applications calls socket() to create a socket descriptor to 659 represent an SCTP endpoint. 661 The syntax is: 663 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 665 or, 667 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 669 Here, SOCK_STREAM indicates the creation of a TCP-style socket. 671 The first form creates an endpoint which can use only IPv4 addresses, 672 while the second form creates an endpoint which can use both IPv6 and 673 IPv4 addresses. 675 4.1.2 bind() - TCP Style Syntax 677 Applications use bind() to pass an address to be associated with an 678 SCTP endpoint to the system. bind() allows only either a single 679 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 680 endpoint can be associated with multiple addresses. To do this, 681 sctp_bindx() is introduced in Section 8.1 to help applications do 682 the job of associating multiple addresses. 684 These addresses associated with a socket are the eligible transport 685 addresses for the endpoint to send and receive data. The endpoint 686 will also present these addresses to its peers during the association 687 initialization process, see RFC2960 [8]. 689 The syntax is: 691 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 693 sd: the socket descriptor returned by socket() call. 695 addr: the address structure (either struct sockaddr_in or struct 696 sockaddr_in6 defined in RFC2553 [7]). 698 addrlen: the size of the address structure. 700 If sd is an IPv4 socket, the address passed must be an IPv4 address. 701 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 702 either be an IPv4 or an IPv6 address. 704 Applications cannot call bind() multiple times to associate multiple 705 addresses to the endpoint. After the first call to bind(), all 706 subsequent calls will return an error. 708 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 709 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 710 operating system will associate the endpoint with an optimal address 711 set of the available interfaces. 713 If a bind() or sctp_bindx() is not called prior to the connect() 714 call, the system picks an ephemeral port and will choose an address 715 set equivalent to binding with a wildcard address. One of those 716 addresses will be the primary address for the association. This 717 automatically enables the multi-homing capability of SCTP. 719 The completion of this bind() process does not ready the SCTP 720 endpoint to accept inbound SCTP association requests. Until a 721 listen() system call, described below, is performed on the socket, 722 the SCTP endpoint will promptly reject an inbound SCTP INIT request 723 with an SCTP ABORT. 725 4.1.3 listen() - TCP Style Syntax 727 Applications use listen() to ready the SCTP endpoint for accepting 728 inbound associations. 730 The syntax is: 732 int listen(int sd, int backlog); 734 sd: the socket descriptor of the SCTP endpoint. 736 backlog: this specifies the max number of outstanding associations 737 allowed in the socket's accept queue. These are the associations 738 that have finished the four-way initiation handshake (see Section 739 5 of RFC2960 [8]) and are in the ESTABLISHED state. Note, a 740 backlog of '0' indicates that the caller no longer wishes to 741 receive new associations. 743 4.1.4 accept() - TCP Style Syntax 745 Applications use accept() call to remove an established SCTP 746 association from the accept queue of the endpoint. A new socket 747 descriptor will be returned from accept() to represent the newly 748 formed association. 750 The syntax is: 752 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 754 new_sd: the socket descriptor for the newly formed association. 756 sd the listening socket descriptor. 758 addr on return, will contain the primary address of the peer 759 endpoint. 761 addrlen on return, will contain the size of addr. 763 4.1.5 connect() - TCP Style Syntax 765 Applications use connect() to initiate an association to a peer. 767 The syntax is: 769 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 771 sd: the socket descriptor of the endpoint. 773 addr the peer's address. 775 addrlen the size of the address. 777 This operation corresponds to the ASSOCIATE primitive described in 778 section 10.1 of RFC2960 [8]. 780 By default, the new association created has only one outbound stream. 781 The SCTP_INITMSG option described in Section 7.1.3 should be used 782 before connecting to change the number of outbound streams. 784 If a bind() or sctp_bindx() is not called prior to the connect() 785 call, the system picks an ephemeral port and will choose an address 786 set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 787 and IPv6 socket respectively. One of those addresses will be the 788 primary address for the association. This automatically enables the 789 multi-homing capability of SCTP. 791 Note that SCTP allows data exchange, similar to T/TCP RFC1644 [3], 792 during the association set up phase. If an application wants to do 793 this, it cannot use connect() call. Instead, it should use sendto() 794 or sendmsg() to initiate an association. If it uses sendto() and it 795 wants to change initialization behavior, it needs to use the 796 SCTP_INITMSG socket option before calling sendto(). Or it can use 797 SCTP_INIT type sendmsg() to initiate an association without doing the 798 setsockopt(). 800 SCTP does not support half close semantics. This means that unlike 801 T/TCP, MSG_EOF should not be set in the flags parameter when calling 802 sendto() or sendmsg() when the call is used to initiate a connection. 803 MSG_EOF is not an acceptable flag with SCTP socket. 805 4.1.6 close() - TCP Style Syntax 807 Applications use close() to gracefully close down an association. 809 The syntax is: 811 int close(int sd); 813 sd - the socket descriptor of the association to be closed. 815 After an application calls close() on a socket descriptor, no further 816 socket operations will succeed on that descriptor. 818 4.1.7 shutdown() - TCP Style Syntax 820 SCTP differs from TCP in that it does not have half closed semantics. 821 Hence the shutdown() call for SCTP is an approximation of the TCP 822 shutdown() call, and solves some different problems. Full TCP- 823 compatibility is not provided, so developers porting TCP applications 824 to SCTP may need to recode sections that use shutdown(). (Note that 825 it is possible to achieve the same results as half close in SCTP 826 using SCTP streams.) 828 The syntax is: 830 int shutdown(int socket, int how); 832 sd - the socket descriptor of the association to be closed. 834 how - Specifies the type of shutdown. The values are 835 as follows: 837 SHUT_RD 838 Disables further receive operations. No SCTP 839 protocol action is taken. 841 SHUT_WR 842 Disables further send operations, and initiates 843 the SCTP shutdown sequence. 845 SHUT_RDWR 846 Disables further send and receive operations 847 and initiates the SCTP shutdown sequence. 849 The major difference between SCTP and TCP shutdown() is that SCTP 850 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 851 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 852 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 853 the SCTP association while still leaving the socket descriptor open, 854 so that the caller can receive back any data SCTP was unable to 855 deliver (see Section 5.3.1.4 for more information). 857 To perform the ABORT operation described in RFC2960 [8] section 10.1, 858 an application can use the socket option SO_LINGER. It is described 859 in Section 7.1.4. 861 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax 863 With a TCP-style socket, the application can also use sendmsg() and 864 recvmsg() to transmit data to and receive data from its peer. The 865 semantics is similar to those used in the UDP-style model (section 866 Section 3.1.3), with the following differences: 868 1) When sending, the msg_name field in the msghdr is not used to 869 specify the intended receiver, rather it is used to indicate a 870 different peer address if the sender does not want to send the 871 message over the primary address of the receiver. If the transport 872 address given is not part of the current association, the data will 873 not be sent and a SCTP_SEND_FAILED event will be delivered to the 874 application if send failure events are enabled. 876 When receiving, if a message is not received from the primary 877 address, the SCTP stack will fill in the msg_name field on return so 878 that the application can retrieve the source address information of 879 the received message. 881 2) An application must use close() to gracefully shutdown an 882 association, or use SO_LINGER option with close() to abort an 883 association. It must not use the MSG_ABORT or MSG_EOF flag in 884 sendmsg(). The system returns an error if an application tries to do 885 so. 887 4.1.9 getpeername() 889 Applications use getpeername() to retrieve the primary socket address 890 of the peer. This call is for TCP compatibility, and is not multi- 891 homed. It does not work with UDP-style sockets. See Section 8.3 for 892 a multi-homed/UDP-sockets version of the call. 894 The syntax is: 896 int getpeername(int socket, struct sockaddr *address, 897 socklen_t *len); 899 sd - the socket descriptor to be queried. 901 address - On return, the peer primary address is stored in 902 this buffer. If the socket is an IPv4 socket, the 903 address will be IPv4. If the socket is an IPv6 socket, 904 the address will be either an IPv6 or IPv4 905 address. 907 len - The caller should set the length of address here. 908 On return, this is set to the length of the returned 909 address. 911 If the actual length of the address is greater than the length of the 912 supplied sockaddr structure, the stored address will be truncated. 914 5. Data Structures 916 We discuss in this section important data structures which are 917 specific to SCTP and are used with sendmsg() and recvmsg() calls to 918 control SCTP endpoint operations and to access ancillary information 919 and notifications. 921 5.1 The msghdr and cmsghdr Structures 923 The msghdr structure used in the sendmsg() and recvmsg() calls, as 924 well as the ancillary data carried in the structure, is the key for 925 the application to set and get various control information from the 926 SCTP endpoint. 928 The msghdr and the related cmsghdr structures are defined and 929 discussed in details in RFC2292 [6]. Here we will cite their 930 definitions from RFC2292 [6]. 932 The msghdr structure: 934 struct msghdr { 935 void *msg_name; /* ptr to socket address structure */ 936 socklen_t msg_namelen; /* size of socket address structure */ 937 struct iovec *msg_iov; /* scatter/gather array */ 938 size_t msg_iovlen; /* # elements in msg_iov */ 939 void *msg_control; /* ancillary data */ 940 socklen_t msg_controllen; /* ancillary data buffer length */ 941 int msg_flags; /* flags on received message */ 942 }; 944 The cmsghdr structure: 946 struct cmsghdr { 947 socklen_t cmsg_len; /* #bytes, including this header */ 948 int cmsg_level; /* originating protocol */ 949 int cmsg_type; /* protocol-specific type */ 950 /* followed by unsigned char cmsg_data[]; */ 951 }; 953 In the msghdr structure, the usage of msg_name has been discussed in 954 previous sections (see Section 3.1.3 and Section 4.1.8). 956 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 957 field) are treated as a single SCTP data chunk, rather than multiple 958 chunks, for both sendmsg() and recvmsg(). 960 The msg_flags are not used when sending a message with sendmsg(). 962 If a notification has arrived, recvmsg() will return the notification 963 with the MSG_NOTIFICATION flag set in msg_flags. If the 964 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 965 Section 5.3 for more information about notifications. 967 If all portions of a data frame or notification have been read, 968 recvmsg() will return with MSG_EOR set in msg_flags. 970 5.2 SCTP msg_control Structures 972 A key element of all SCTP-specific socket extensions is the use of 973 ancillary data to specify and access SCTP-specific data via the 974 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 975 Fine-grained control over initialization and sending parameters are 976 handled with ancillary data. 978 Each ancillary data item is proceeded by a struct cmsghdr (see 979 Section 5.1), which defines the function and purpose of the data 980 contained in in the cmsg_data[] member. 982 There are two kinds of ancillary data used by SCTP: initialization 983 data, and, header information (SNDRCV). Initialization data (UDP- 984 style only) sets protocol parameters for new associations. Section 985 5.2.1 provides more details. Header information can set or report 986 parameters on individual messages in a stream. See Section 5.2.2 for 987 how to use SNDRCV ancillary data. 989 By default on a TCP-style socket, SCTP will pass no ancillary data; 990 on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and 991 SCTP_ASSOC_CHANGE information. Specific ancillary data items can be 992 enabled with socket options defined for SCTP; see Section 7.3. 994 Note that all ancillary types are fixed length; see Section 5.4 for 995 further discussion on this. These data structures use struct 996 sockaddr_storage (defined in RFC2553 [7]) as a portable, fixed length 997 address format. 999 Other protocols may also provide ancillary data to the socket layer 1000 consumer. These ancillary data items from other protocols may 1001 intermingle with SCTP data. For example, the IPv6 socket API 1002 definitions (RFC2292 [6] and RFC2553 [7]) define a number of 1003 ancillary data items. If a socket API consumer enables delivery of 1004 both SCTP and IPv6 ancillary data, they both may appear in the same 1005 msg_control buffer in any order. An application may thus need to 1006 handle other types of ancillary data besides that passed by SCTP. 1008 The sockets application must provide a buffer large enough to 1009 accommodate all ancillary data provided via recvmsg(). If the buffer 1010 is not large enough, the ancillary data will be truncated and the 1011 msghdr's msg_flags will include MSG_CTRUNC. 1013 5.2.1 SCTP Initiation Structure (SCTP_INIT) 1015 This cmsghdr structure provides information for initializing new SCTP 1016 associations with sendmsg(). The SCTP_INITMSG socket option uses 1017 this same data structure. This structure is not used for recvmsg(). 1019 cmsg_level cmsg_type cmsg_data[] 1020 ------------ ------------ ---------------------- 1021 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1023 Here is the definition of the sctp_initmsg structure: 1025 struct sctp_initmsg { 1026 uint16_t sinit_num_ostreams; 1027 uint16_t sinit_max_instreams; 1028 uint16_t sinit_max_attempts; 1029 uint16_t sinit_max_init_timeo; 1030 }; 1032 sinit_num_ostreams: 16 bits (unsigned integer) 1034 This is an integer number representing the number of streams that the 1035 application wishes to be able to send to. This number is confirmed 1036 in the SCTP_COMM_UP notification and must be verified since it is a 1037 negotiated number with the remote endpoint. The default value of 0 1038 indicates to use the endpoint default value. 1040 sinit_max_instreams: 16 bits (unsigned integer) 1042 This value represents the maximum number of inbound streams the 1043 application is prepared to support. This value is bounded by the 1044 actual implementation. In other words the user MAY be able to 1045 support more streams than the Operating System. In such a case, the 1046 Operating System limit overrides the value requested by the user. 1047 The default value of 0 indicates to use the endpoint's default value. 1049 sinit_max_attempts: 16 bits (unsigned integer) 1051 This integer specifies how many attempts the SCTP endpoint should 1052 make at resending the INIT. This value overrides the system SCTP 1053 'Max.Init.Retransmits' value. The default value of 0 indicates to 1054 use the endpoint's default value. This is normally set to the 1055 system's default 'Max.Init.Retransmit' value. 1057 sinit_max_init_timeo: 16 bits (unsigned integer) 1058 This value represents the largest Time-Out or RTO value to use in 1059 attempting a INIT. Normally the 'RTO.Max' is used to limit the 1060 doubling of the RTO upon timeout. For the INIT message this value 1061 MAY override 'RTO.Max'. This value MUST NOT influence 'RTO.Max' 1062 during data transmission and is only used to bound the initial setup 1063 time. A default value of 0 indicates to use the endpoint's default 1064 value. This is normally set to the system's 'RTO.Max' value (60 1065 seconds). 1067 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 1069 This cmsghdr structure specifies SCTP options for sendmsg() and 1070 describes SCTP header information about a received message through 1071 recvmsg(). 1073 cmsg_level cmsg_type cmsg_data[] 1074 ------------ ------------ ---------------------- 1075 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1077 Here is the definition of sctp_sndrcvinfo: 1079 struct sctp_sndrcvinfo { 1080 uint16_t sinfo_stream; 1081 uint16_t sinfo_ssn; 1082 uint16_t sinfo_flags; 1083 uint32_t sinfo_ppid; 1084 uint32_t sinfo_context; 1085 uint32_t sinfo_timetolive; 1086 uint32_t sinfo_tsn; 1087 uint32_t sinfo_cumtsn; 1088 sctp_assoc_t sinfo_assoc_id; 1089 }; 1091 sinfo_stream: 16 bits (unsigned integer) 1093 For recvmsg() the SCTP stack places the message's stream number in 1094 this value. For sendmsg() this value holds the stream number that 1095 the application wishes to send this message to. If a sender 1096 specifies an invalid stream number an error indication is returned 1097 and the call fails. 1099 sinfo_ssn: 16 bits (unsigned integer) 1101 For recvmsg() this value contains the stream sequence number that the 1102 remote endpoint placed in the DATA chunk. For fragmented messages 1103 this is the same number for all deliveries of the message (if more 1104 than one recvmsg() is needed to read the message). The sendmsg() 1105 call will ignore this parameter. 1107 sinfo_ppid: 32 bits (unsigned integer) 1109 This value in sendmsg() is an opaque unsigned value that is passed to 1110 the remote end in each user message. In recvmsg() this value is the 1111 same information that was passed by the upper layer in the peer 1112 application. Please note that byte order issues are NOT accounted 1113 for and this information is passed opaquely by the SCTP stack from 1114 one end to the other. 1116 sinfo_context: 32 bits (unsigned integer) 1118 This value is an opaque 32 bit context datum that is used in the 1119 sendmsg() function. This value is passed back to the upper layer if 1120 a error occurs on the send of a message and is retrieved with each 1121 undelivered message (Note: if a endpoint has done multiple sends, all 1122 of which fail, multiple different sinfo_context values will be 1123 returned. One with each user data message). 1125 sinfo_flags: 16 bits (unsigned integer) 1127 This field may contain any of the following flags and is composed of 1128 a bitwise OR of these values. 1130 recvmsg() flags: 1132 MSG_UNORDERED - This flag is present when the message was sent 1133 non-ordered. 1135 sendmsg() flags: 1137 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1138 message. If this flag is clear the datagram is 1139 considered an ordered send. 1141 MSG_ADDR_OVER - This flag, in the UDP model, requests the SCTP 1142 stack to override the primary destination address 1143 with the address found with the sendto/sendmsg 1144 call. 1146 MSG_ABORT - Setting this flag causes the specified association 1147 to abort by sending an ABORT message to the peer 1148 (UDP-style only). The ABORT chunk will contain an 1149 error cause 'User Initiated Abort' with cause code 12. 1150 The cause specific information of this error cause is 1151 provided in msg_iov. 1153 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1154 procedures on the specified association. Graceful 1155 shutdown assures that all data enqueued by both 1156 endpoints is successfully transmitted before closing 1157 the association (UDP-style only). 1159 sinfo_timetolive: 32 bit (unsigned integer) 1161 For the sending side, this field contains the message time to live in 1162 milliseconds. The sending side will expire the message within the 1163 specified time period if the message as not been sent to the peer 1164 within this time period. This value will override any default value 1165 set using any socket option. Also note that the value of 0 is 1166 special in that it indicates no timeout should occur on this message. 1168 sinfo_tsn: 32 bit (unsigned integer) 1170 For the receiving side, this field holds a TSN that was assigned to 1171 one of the SCTP Data Chunks. 1173 sinfo_cumtsn: 32 bit (unsigned integer) 1175 This field will hold the current cumulative TSN as known by the 1176 underlying SCTP layer. Note this field is ignored when sending and 1177 only valid for a receive operation when sinfo_flags are set to 1178 MSG_UNORDERED. 1180 sinfo_assoc_id: sizeof (sctp_assoc_t) 1182 The association handle field, sinfo_assoc_id, holds the identifier 1183 for the association announced in the SCTP_COMM_UP notification. All 1184 notifications for a given association have the same identifier. 1185 Ignored for TCP-style sockets. 1187 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1189 5.3 SCTP Events and Notifications 1191 An SCTP application may need to understand and process events and 1192 errors that happen on the SCTP stack. These events include network 1193 status changes, association startups, remote operational errors and 1194 undeliverable messages. All of these can be essential for the 1195 application. 1197 When an SCTP application layer does a recvmsg() the message read is 1198 normally a data message from a peer endpoint. If the application 1199 wishes to have the SCTP stack deliver notifications of non-data 1200 events, it sets the appropriate socket option for the notifications 1201 it wants. See Section 7.3 for these socket options. When a 1202 notification arrives, recvmsg() returns the notification in the 1203 application-supplied data buffer via msg_iov, and sets 1204 MSG_NOTIFICATION in msg_flags. 1206 This section details the notification structures. Every notification 1207 structure carries some common fields which provides general 1208 information. 1210 A recvmsg() call will return only one notification at a time. Just 1211 as when reading normal data, it may return part of a notification if 1212 the msg_iov buffer is not large enough. If a single read is not 1213 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1214 reading the notification before subsequent data can arrive. 1216 5.3.1 SCTP Notification Structure 1218 The notification structure is defined as the union of all 1219 notification types. 1221 union sctp_notification { 1222 struct { 1223 uint16_t sn_type; /* Notification type. */ 1224 uint16_t sn_flags; 1225 uint32_t sn_length; 1226 } h; 1227 struct sctp_assoc_change sn_assoc_change; 1228 struct sctp_paddr_change sn_padr_change; 1229 struct sctp_remote_error sn_remote_error; 1230 struct sctp_send_failed sn_send_failed; 1231 struct sctp_shutdown_event sn_shutdown_event; 1232 struct sctp_adaption_event sn_adaption_event; 1233 struct sctp_rcv_pdapi_event sn_rcv_pdapi_event; 1234 }; 1236 sn_type: 16 bits (unsigned integer) 1238 The following list describes the SCTP notification and event types 1239 for the field sn_type. 1241 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1242 been opened or closed. Refer to Section 5.3.1.1 for details. 1244 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1245 part of an existing association has experienced a change of state 1246 (e.g. a failure or return to service of the reachability of a 1247 endpoint via a specific transport address). Please see Section 1248 5.3.1.2 for data structure details. 1250 SCTP_REMOTE_ERROR: The attached error message is an Operational Error 1251 received from the remote peer. It includes the complete TLV sent 1252 by the remote endpoint. See Section 5.3.1.3 for the detailed 1253 format. 1255 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1256 remote endpoint. This structure includes the original 1257 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1258 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1260 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1261 should be sent on this socket. 1263 SCTP_ADAPTION_INDICATION: This notification holds the peers indicated 1264 adaption layer. Please see Section 5.3.1.6. 1266 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1267 receiver that the partial delivery has been aborted. This may 1268 indicate the association is about to be aborted. Please see 1269 Section 5.3.1.7 1271 All standard values for sn_type flags are greater than 2^15. Values 1272 from 2^15 and down are reserved. 1274 sn_flags: 16 bits (unsigned integer) 1276 These are notification-specific flags. 1278 sn_length: 32 bits (unsigned integer) 1280 This is the length of the whole sctp_notification structure including 1281 the sn_type, sn_flags, and sn_length fields. 1283 5.3.1.1 SCTP_ASSOC_CHANGE 1285 Communication notifications inform the ULP that an SCTP association 1286 has either begun or ended. The identifier for a new association is 1287 provided by this notification. The notification information has the 1288 following format: 1290 struct sctp_assoc_change { 1291 uint16_t sac_type; 1292 uint16_t sac_flags; 1293 uint32_t sac_length; 1294 uint16_t sac_state; 1295 uint16_t sac_error; 1296 uint16_t sac_outbound_streams; 1297 uint16_t sac_inbound_streams; 1298 sctp_assoc_t sac_assoc_id; 1299 uint8_t sac_info[0]; 1300 }; 1302 sac_type: 1304 It should be SCTP_ASSOC_CHANGE. 1306 sac_flags: 16 bits (unsigned integer) 1308 Currently unused. 1310 sac_length: 32 bits (unsigned integer) 1312 This field is the total length of the notification data, including 1313 the notification header. 1315 sac_state: 16 bits (signed integer) 1316 This field holds one of a number of values that communicate the event 1317 that happened to the association. They include: 1319 Event Name Description 1320 ---------------- --------------- 1321 SCTP_COMM_UP A new association is now ready 1322 and data may be exchanged with this 1323 peer. 1325 SCTP_COMM_LOST The association has failed. The association 1326 is now in the closed state. If SEND FAILED 1327 notifications are turned on, a SCTP_COMM_LOST 1328 is followed by a series of SCTP_SEND_FAILED 1329 events, one for each outstanding message. 1331 SCTP_RESTART SCTP has detected that the peer has restarted. 1333 SCTP_SHUTDOWN_COMP The association has gracefully closed. 1335 SCTP_CANT_STR_ASSOC The association failed to setup. If non blocking 1336 mode is set and data was sent (in the udp mode), 1337 a SCTP_CANT_STR_ASSOC is followed by a series of 1338 SCTP_SEND_FAILED events, one for each outstanding 1339 message. 1341 sac_error: 16 bits (signed integer) 1343 If the state was reached due to a error condition (e.g. 1344 SCTP_COMM_LOST) any relevant error information is available in this 1345 field. This corresponds to the protocol error codes defined in 1346 RFC2960 [8]. 1348 sac_outbound_streams: 16 bits (unsigned integer) 1350 sac_inbound_streams: 16 bits (unsigned integer) 1352 The maximum number of streams allowed in each direction are available 1353 in sac_outbound_streams and sac_inbound streams. 1355 sac_assoc_id: sizeof (sctp_assoc_t) 1357 The association id field, holds the identifier for the association. 1358 All notifications for a given association have the same association 1359 identifier. For TCP style socket, this field is ignored. 1361 sac_data: variable 1363 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1364 for this association, sac_data[] contains the complete ABORT chunk as 1365 defined in the SCTP specification RFC2960 [8] section 3.3.7. 1367 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1369 When a destination address on a multi-homed peer encounters a change 1370 an interface details event is sent. The information has the 1371 following structure: 1373 struct sctp_paddr_change { 1374 uint16_t spc_type; 1375 uint16_t spc_flags; 1376 uint32_t spc_length; 1377 struct sockaddr_storage spc_aaddr; 1378 int spc_state; 1379 int spc_error; 1380 sctp_assoc_t spc_assoc_id; 1381 } 1383 spc_type: 1385 It should be SCTP_PEER_ADDR_CHANGE. 1387 spc_flags: 16 bits (unsigned integer) 1389 Currently unused. 1391 spc_length: 32 bits (unsigned integer) 1393 This field is the total length of the notification data, including 1394 the notification header. 1396 spc_aaddr: sizeof (struct sockaddr_storage) 1398 The affected address field, holds the remote peer's address that is 1399 encountering the change of state. 1401 spc_state: 32 bits (signed integer) 1403 This field holds one of a number of values that communicate the event 1404 that happened to the address. They include: 1406 Event Name Description 1407 ---------------- --------------- 1408 SCTP_ADDR_AVAILABLE This address is now reachable. 1410 SCTP_ADDR_UNREACHABL The address specified can no 1411 longer be reached. Any data sent 1412 to this address is rerouted to an 1413 alternate until this address becomes 1414 reachable. 1416 SCTP_ADDR_REMOVED The address is no longer part of 1417 the association. 1419 SCTP_ADDR_ADDED The address is now part of the 1420 association. 1422 SCTP_ADDR_MADE_PRIM This address has now been made 1423 to be the primary destination address. 1425 spc_error: 32 bits (signed integer) 1427 If the state was reached due to any error condition (e.g. 1428 SCTP_ADDR_UNREACHABL) any relevant error information is available in 1429 this field. 1431 spc_assoc_id: sizeof (sctp_assoc_t) 1433 The association id field, holds the identifier for the association. 1434 All notifications for a given association have the same association 1435 identifier. For TCP style socket, this field is ignored. 1437 5.3.1.3 SCTP_REMOTE_ERROR 1439 A remote peer may send an Operational Error message to its peer. 1440 This message indicates a variety of error conditions on an 1441 association. The entire ERROR chunk as it appears on the wire is 1442 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1443 specification RFC2960 [8] and any extensions for a list of possible 1444 error formats. SCTP error notifications have the format: 1446 struct sctp_remote_error { 1447 uint16_t sre_type; 1448 uint16_t sre_flags; 1449 uint32_t sre_length; 1450 uint16_t sre_error; 1451 sctp_assoc_t sre_assoc_id; 1452 uint8_t sre_data[0]; 1453 }; 1455 sre_type: 1457 It should be SCTP_REMOTE_ERROR. 1459 sre_flags: 16 bits (unsigned integer) 1461 Currently unused. 1463 sre_length: 32 bits (unsigned integer) 1465 This field is the total length of the notification data, including 1466 the notification header and the contents of sre_data. 1468 sre_error: 16 bits (unsigned integer) 1470 This value represents one of the Operational Error causes defined in 1471 the SCTP specification, in network byte order. 1473 sre_assoc_id: sizeof (sctp_assoc_t) 1475 The association id field, holds the identifier for the association. 1476 All notifications for a given association have the same association 1477 identifier. For TCP style socket, this field is ignored. 1479 sre_data: variable 1481 This contains the ERROR chunk as defined in the SCTP specification 1482 RFC2960 [8] section 3.3.10. 1484 5.3.1.4 SCTP_SEND_FAILED 1486 If SCTP cannot deliver a message it may return the message as a 1487 notification. 1489 struct sctp_send_failed { 1490 uint16_t ssf_type; 1491 uint16_t ssf_flags; 1492 uint32_t ssf_length; 1493 uint32_t ssf_error; 1494 struct sctp_sndrcvinfo ssf_info; 1495 sctp_assoc_t ssf_assoc_id; 1496 uint8_t ssf_data[0]; 1497 }; 1499 ssf_type: 1501 It should be SCTP_SEND_FAILED. 1503 The flag value will take one of the following values 1505 SCTP_DATA_UNSENT - Indicates that the data was never put on 1506 the wire. 1508 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1509 Note that this does not necessarily mean that the 1510 data was (or was not) successfully delivered. 1512 ssf_length: 32 bits (unsigned integer) 1514 This field is the total length of the notification data, including 1515 the notification header and the payload in ssf_data. 1517 ssf_error: 16 bits (unsigned integer) 1519 This value represents the reason why the send failed, and if set, 1520 will be a SCTP protocol error code as defined in RFC2960 [8] section 1521 3.3.10. 1523 ssf_info: sizeof (struct sctp_sndrcvinfo) 1525 The original send information associated with the undelivered 1526 message. 1528 ssf_assoc_id: sizeof (sctp_assoc_t) 1530 The association id field, sf_assoc_id, holds the identifier for the 1531 association. All notifications for a given association have the same 1532 association identifier. For TCP style socket, this field is ignored. 1534 ssf_data: variable length 1536 The undelivered message, exactly as delivered by the caller to the 1537 original send*() call. 1539 5.3.1.5 SCTP_SHUTDOWN_EVENT 1541 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1542 inform the application that it should cease sending data. 1544 struct sctp_shutdown_event { 1545 uint16_t sse_type; 1546 uint16_t sse_flags; 1547 uint32_t sse_length; 1548 sctp_assoc_t sse_assoc_id; 1549 }; 1551 sse_type 1553 It should be SCTP_SHUTDOWN_EVENT 1555 sse_flags: 16 bits (unsigned integer) 1557 Currently unused. 1559 sse_length: 32 bits (unsigned integer) 1561 This field is the total length of the notification data, including 1562 the notification header. It will generally be sizeof (struct 1563 sctp_shutdown_event). 1565 sse_flags: 16 bits (unsigned integer) 1567 Currently unused. 1569 sse_assoc_id: sizeof (sctp_assoc_t) 1571 The association id field, holds the identifier for the association. 1572 All notifications for a given association have the same association 1573 identifier. For TCP style socket, this field is ignored. 1575 5.3.1.6 SCTP_ADAPTION_INDICATION 1577 When a peer sends a Adaption Layer Indication parameter , SCTP 1578 delivers this notification to inform the application that of the 1579 peers requested adaption layer. 1581 struct sctp_adaption_event { 1582 uint16_t sai_type; 1583 uint16_t sai_flags; 1584 uint32_t sai_length; 1585 uint32_t sai_adaptation_bits; 1586 sctp_assoc_t sai_assoc_id; 1587 }; 1589 sai_type 1591 It should be SCTP_ADAPTION_INDICATION 1593 sai_flags: 16 bits (unsigned integer) 1595 Currently unused. 1597 sai_length: 32 bits (unsigned integer) 1599 This field is the total length of the notification data, including 1600 the notification header. It will generally be sizeof (struct 1601 sctp_adaption_event). 1603 sai_adaption_bits: 32 bits (unsigned integer) 1605 This field holds the bit array sent by the peer in the adaption layer 1606 indication parameter. The bits are in network byte order. 1608 sai_assoc_id: sizeof (sctp_assoc_t) 1610 The association id field, holds the identifier for the association. 1611 All notifications for a given association have the same association 1612 identifier. For TCP style socket, this field is ignored. 1614 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT 1616 When a receiver is engaged in a partial delivery of a message this 1617 notification will be used to indicate various events. 1619 struct sctp_rcv_pdapi_event { 1620 uint16_t pdapi_type; 1621 uint16_t pdapi_flags; 1622 uint32_t pdapi_length; 1623 uint32_t pdapi_indication; 1624 sctp_assoc_t pdapi_assoc_id; 1625 }; 1627 pdapi_type 1628 It should be SCTP_PARTIAL_DELIVERY_EVENT 1630 pdapi_flags: 16 bits (unsigned integer) 1632 Currently unused. 1634 pdapi_length: 32 bits (unsigned integer) 1636 This field is the total length of the notification data, including 1637 the notification header. It will generally be sizeof (struct 1638 sctp_rcv_pdapi_event). 1640 pdapi_indication: 32 bits (unsigned integer) 1642 This field holds the indication being sent to the application 1643 possible values include: 1645 SCTP_PARTIAL_DELIVERY_ABORTED 1647 pdapi_assoc_id: sizeof (sctp_assoc_t) 1649 The association id field, holds the identifier for the association. 1650 All notifications for a given association have the same association 1651 identifier. For TCP style socket, this field is ignored. 1653 5.4 Ancillary Data Considerations and Semantics 1655 Programming with ancillary socket data contains some subtleties and 1656 pitfalls, which are discussed below. 1658 5.4.1 Multiple Items and Ordering 1660 Multiple ancillary data items may be included in any call to 1661 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1662 items, or both. 1664 The ordering of ancillary data items (either by SCTP or another 1665 protocol) is not significant and is implementation-dependent, so 1666 applications must not depend on any ordering. 1668 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1669 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1670 sendmsg() or recvmsg() call. 1672 5.4.2 Accessing and Manipulating Ancillary Data 1674 Applications can infer the presence of data or ancillary data by 1675 examining the msg_iovlen and msg_controllen msghdr members, 1676 respectively. 1678 Implementations may have different padding requirements for ancillary 1679 data, so portable applications should make use of the macros 1680 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1681 RFC2292 [6] and your SCTP implementation's documentation for more 1682 information. Following is an example, from RFC2292 [6], 1683 demonstrating the use of these macros to access ancillary data: 1685 struct msghdr msg; 1686 struct cmsghdr *cmsgptr; 1688 /* fill in msg */ 1690 /* call recvmsg() */ 1692 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1693 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1694 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1695 u_char *ptr; 1697 ptr = CMSG_DATA(cmsgptr); 1698 /* process data pointed to by ptr */ 1699 } 1700 } 1702 5.4.3 Control Message Buffer Sizing 1704 The information conveyed via SCTP_SNDRCV events will often be 1705 fundamental to the correct and sane operation of the sockets 1706 application. This is particularly true of the UDP semantics, but 1707 also of the TCP semantics. For example, if an application needs to 1708 send and receive data on different SCTP streams, SCTP_SNDRCV events 1709 are indispensable. 1711 Given that some ancillary data is critical, and that multiple 1712 ancillary data items may appear in any order, applications should be 1713 carefully written to always provide a large enough buffer to contain 1714 all possible ancillary data that can be presented by recvmsg(). If 1715 the buffer is too small, and crucial data is truncated, it may pose a 1716 fatal error condition. 1718 Thus it is essential that applications be able to deterministically 1719 calculate the maximum required buffer size to pass to recvmsg(). One 1720 constraint imposed on this specification that makes this possible is 1721 that all ancillary data definitions are of a fixed length. One way 1722 to calculate the maximum required buffer size might be to take the 1723 sum the sizes of all enabled ancillary data item structures, as 1724 calculated by CMSG_SPACE. For example, if we enabled 1725 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [6], we would calculate 1726 and allocate the buffer size as follows: 1728 size_t total; 1729 void *buf; 1731 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1732 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1734 buf = malloc(total); 1736 We could then use this buffer for msg_control on each call to 1737 recvmsg() and be assured that we would not lose any ancillary data to 1738 truncation. 1740 6. Common Operations for Both Styles 1742 6.1 send(), recv(), sendto(), recvfrom() 1744 Applications can use send() and sendto() to transmit data to the peer 1745 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1746 data from the peer. 1748 The syntax is: 1750 ssize_t send(int sd, connst void *msg, size_t len, int flags); 1751 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1752 const struct sockaddr *to, int tolen); 1753 ssize_t recv(int sd, void *buf, size_t len, int flags); 1754 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1755 struct sockaddr *from, int *fromlen); 1757 sd - the socket descriptor of an SCTP endpoint. 1758 msg - the message to be sent. 1759 len - the size of the message or the size of buffer. 1760 to - one of the peer addresses of the association to be 1761 used to send the message. 1762 tolen - the size of the address. 1763 buf - the buffer to store a received message. 1764 from - the buffer to store the peer address used to send the 1765 received message. 1766 fromlen - the size of the from address 1767 flags - (described below). 1769 These calls give access to only basic SCTP protocol features. If 1770 either peer in the association uses multiple streams, or sends 1771 unordered data these calls will usually be inadequate, and may 1772 deliver the data in unpredictable ways. 1774 SCTP has the concept of multiple streams in one association. The 1775 above calls do not allow the caller to specify on which stream a 1776 message should be sent. The system uses stream 0 as the default 1777 stream for send() and sendto(). recv() and recvfrom() return data 1778 from any stream, but the caller can not distinguish the different 1779 streams. This may result in data seeming to arrive out of order. 1780 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1781 provide no indication. 1783 SCTP is message based. The msg buffer above in send() and sendto() 1784 is considered to be a single message. This means that if the caller 1785 wants to send a message which is composed by several buffers, the 1786 caller needs to combine them before calling send() or sendto(). 1787 Alternately, the caller can use sendmsg() to do that without 1788 combining them. recv() and recvfrom() cannot distinguish message 1789 boundaries. 1791 In receiving, if the buffer supplied is not large enough to hold a 1792 complete message, the receive call acts like a stream socket and 1793 returns as much data as will fit in the buffer. 1795 Note, the send and recv calls, when used in the UDP-style model, may 1796 only be used with branched off socket descriptors (see Section 8.2). 1798 Note, if an application calls a send function with no user data and 1799 no ancillary data the SCTP implementation should reject the request 1800 with an appropriate error message. An implementation is NOT allowed 1801 to send a Data chunk with no user data RFC2960 [8]. 1803 6.2 setsockopt(), getsockopt() 1805 Applications use setsockopt() and getsockopt() to set or retrieve 1806 socket options. Socket options are used to change the default 1807 behavior of sockets calls. They are described in Section 7 1809 The syntax is: 1811 ret = getsockopt(int sd, int level, int optname, void *optval, 1812 size_t *optlen); 1813 ret = setsockopt(int sd, int level, int optname, const void *optval, 1814 size_t optlen); 1816 sd - the socket descript. 1817 level - set to IPPROTO_SCTP for all SCTP options. 1818 optname - the option name. 1819 optval - the buffer to store the value of the option. 1820 optlen - the size of the buffer (or the length of the option 1821 returned). 1823 6.3 read() and write() 1825 Applications can use read() and write() to send and receive data to 1826 and from peer. They have the same semantics as send() and recv() 1827 except that the flags parameter cannot be used. 1829 Note, these calls, when used in the UDP-style model, may only be used 1830 with branched off socket descriptors (see Section 8.2). 1832 6.4 getsockname() 1834 Applications use getsockname() to retrieve the locally-bound socket 1835 address of the specified socket. This is especially useful if the 1836 caller let SCTP chose a local port. This call is for where the 1837 endpoint is not multi-homed. It does not work well with multi-homed 1838 sockets. See Section 8.5 for a multi-homed version of the call. 1840 The syntax is: 1842 int getsockname(int socket, struct sockaddr *address, 1843 socklen_t *len); 1845 sd - the socket descriptor to be queried. 1847 address - On return, one locally bound address (chosen by 1848 the SCTP stack) is stored in this buffer. If the 1849 socket is an IPv4 socket, the address will be IPv4. 1850 If the socket is an IPv6 socket, the address will 1851 be either an IPv6 or IPv4 address. 1853 len - The caller should set the length of address here. 1854 On return, this is set to the length of the returned 1855 address. 1857 If the actual length of the address is greater than the length of the 1858 supplied sockaddr structure, the stored address will be truncated. 1860 If the socket has not been bound to a local name, the value stored in 1861 the object pointed to by address is unspecified. 1863 7. Socket Options 1865 The following sub-section describes various SCTP level socket options 1866 that are common to both models. SCTP associations can be multi- 1867 homed. Therefore, certain option parameters include a 1868 sockaddr_storage structure to select which peer address the option 1869 should be applied to. 1871 For the UDP-style sockets, an sctp_assoc_t structure (association ID) 1872 is used to identify the the association instance that the operation 1873 affects. So it must be set when using this model. 1875 For the TCP-style sockets and branched off UDP-style sockets (see 1876 Section 8.2) this association ID parameter is ignored. In the cases 1877 noted below where the parameter is ignored, an application can pass 1878 to the system a corresponding option structure similar to those 1879 described below but without the association ID parameter, which 1880 should be the last field of the option structure. This can make the 1881 option setting/getting operation more efficient. If an application 1882 does this, it should also specify an appropriate optlen value (i.e. 1883 sizeof (option parameter) - sizeof (struct sctp_assoc_t)). 1885 Note that socket or IP level options is set or retrieved per socket. 1886 This means that for UDP-style sockets, those options will be applied 1887 to all associations belonging to the socket. And for TCP-style 1888 model, those options will be applied to all peer addresses of the 1889 association controlled by the socket. Applications should be very 1890 careful in setting those options. 1892 sctp_opt_info() 1894 For some implementations getsockopt() is read-only, so a new 1895 interface will be needed when information must be passed both in to 1896 and out of the SCTP stack. The syntax for scpt_opt_info() is, 1898 int sctp_opt_info(int sd, 1899 sctp_assoc_t id, 1900 int opt, 1901 void *arg, 1902 size_t *size); 1904 For UDP-style sockets, id specifies the association to query. For 1905 TCP-style sockets, id is ignored. 1907 opt specifies which SCTP socket option to get. It can any socket 1908 option currently supported that requests information (either read/ 1909 write options or read only) such as: 1911 SCTP_RTOINFO 1912 SCTP_ASSOCINFO 1913 SCTP_SET_PRIMARY_ADDR 1914 SCTP_SET_PEER_PRIMARY_ADDR 1915 SCTP_SET_STREAM_TIMEOUTS 1916 SCTP_SET_PEER_ADDR_PARAMS 1917 SCTP_STATUS 1918 SCTP_GET_PEER_ADDR_INFO 1920 arg is an option-specific structure buffer provided by the caller. 1921 See Section 8.5) subsections for more information on these options 1922 and option-specific structures. 1924 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1925 sets errno to the appropriate error code. 1927 For those implementations that DO support a read/write getsocketopt 1928 interface a simple macro wrapper can be created to support the 1929 sctp_opt_info() interface such as: 1931 #define sctp_opt_info(fd,asoc,opt,arg,sz) \ 1932 do { \ 1933 if((opt == SCTP_RTOINFO) || \ 1934 (opt == SCTP_ASSOCINFO) || \ 1935 (opt == SCTP_SET_PRIMARY_ADDR) || \ 1936 (opt == SCTP_SET_PEER_PRIMARY_ADDR) || \ 1937 (opt == SCTP_SET_STREAM_TIMEOUTS) || \ 1938 (opt == SCTP_SET_PEER_ADDR_PARAMS) || \ 1939 (opt == SCTP_STATUS) || \ 1940 (opt == SCTP_GET_PEER_ADDR_INFO)){ \ 1941 *(sctp_assoc_t *)arg = asoc; \ 1942 return(getsockopt(fd,IPPROTO_SCTP,opt,arg,sz)); \ 1943 }else{ \ 1944 return(ENOTSUP); \ 1945 } \ 1946 }while(0); 1948 All options that support specific settings on an association by 1949 filling in either an association id variable or a sockaddr_storage 1950 SHOULD also support setting of the same value for the entire endpoint 1951 (i.e. future associations). To accomplish this the following logic 1952 is used when setting one of these options: 1954 a) If an address is specified via a sockaddr_storage that is included 1955 in the structure the address is used to lookup the association and 1956 the settings are applied to the specific address (if appropriate) 1957 or to the entire association. 1959 b) If an association identification is filled in but not a 1960 sockaddr_storage (if present) the association is found using the 1961 association identification and the settings should be applied to 1962 the entire association (since a specific address is specified). 1963 Note this also applies to options that hold an association 1964 identification in their structure but do not have a 1965 sockaddr_storage field. 1967 c) If neither the sockaddr_storage or association identification is 1968 set i.e. the sockadd_storage is set to all 0's (INADDR_ANY) and 1969 the association identification is 0, the settings are a default 1970 and to be applied to the endpoint (all future associations). 1972 7.1 Read / Write Options 1974 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1976 The protocol parameters used to initialize and bound retransmission 1977 timeout (RTO) are tunable. See RFC2960 [8] for more information on 1978 how these parameters are used in RTO calculation. The peer address 1979 parameter is ignored for TCP style socket. 1981 The following structure is used to access and modify these 1982 parameters: 1984 struct sctp_rtoinfo { 1985 sctp_assoc_t srto_assoc_id; 1986 uint32_t srto_initial; 1987 uint32_t srto_max; 1988 uint32_t srto_min; 1989 }; 1990 srto_initial - This contains the initial RTO value. 1991 srto_max and srto_min - These contain the maximum and minimum bounds 1992 for all RTOs. 1993 srto_assoc_id - (UDP style socket) This is filled in the application, 1994 and identifies the association for this query. If 1995 this parameter is missing (on a UDP style socket), 1996 then the change effects the entire endpoint. 1998 All parameters are time values, in milliseconds. A value of 0, when 1999 modifying the parameters, indicates that the current value should not 2000 be changed. 2002 To access or modify these parameters, the application should call 2003 getsockopt or setsockopt() respectively with the option name 2004 SCTP_RTOINFO. 2006 7.1.2 Association Parameters (SCTP_ASSOCINFO) 2008 This option is used to both examine and set various association and 2009 endpoint parameters. 2011 See RFC2960 [8] for more information on how this parameter is used. 2012 The peer address parameter is ignored for TCP style socket. 2014 The following structure is used to access and modify this parameters: 2016 struct sctp_assocparams { 2017 sctp_assoc_t sasoc_assoc_id; 2018 uint16_t sasoc_asocmaxrxt; 2019 uint16_t sasoc_number_peer_destinations; 2020 uint32_t sasoc_peer_rwnd; 2021 uint32_t sasoc_local_rwnd; 2022 uint32_t sasoc_cookie_life; 2023 }; 2024 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 2025 to make for the association. 2027 sasoc_number_peer_destinations - This is the number of destination 2028 address that the peer considers 2029 valid. 2030 sasoc_peer_rwnd - This holds the current value of the peers 2031 rwnd (reported in the last SACK) minus any 2032 outstanding data (i.e. data inflight). 2033 sasoc_local_rwnd - This holds the last reported rwnd that was 2034 sent to the peer. 2035 sasoc_cookie_life - This is the associations cookie life value 2036 used when issuing cookies. 2037 sasoc_assoc_id - (UDP style socket) This is filled in the application, 2038 and identifies the association for this query. 2040 This information may be examined for either the endpoint or a 2041 specific association. To examine a endpoints default parameters the 2042 association id (sasoc_assoc_id) should must be set to the value '0'. 2043 The values of the sasoc_peer_rwnd is meaningless when examining 2044 endpoint information. 2046 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2047 on either an endpoint or association basis. The rwnd and destination 2048 counts (sasoc_number_peer_destinations, 2049 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2050 placed in these is ignored. 2052 To access or modify these parameters, the application should call 2053 getsockopt or setsockopt() respectively with the option name 2054 SCTP_ASSOCRTXINFO. 2056 The maximum number of retransmissions before an address is considered 2057 unreachable is also tunable, but is address-specific, so it is 2058 covered in a separate option. If an application attempts to set the 2059 value of the association maximum retransmission parameter to more 2060 than the sum of all maximum retransmission parameters, setsockopt() 2061 shall return an error. The reason for this, from RFC2960 [8] section 2062 8.2: 2064 Note: When configuring the SCTP endpoint, the user should avoid 2065 having the value of 'Association.Max.Retrans' larger than the 2066 summation of the 'Path.Max.Retrans' of all the destination addresses 2067 for the remote endpoint. Otherwise, all the destination addresses 2068 may become inactive while the endpoint still considers the peer 2069 endpoint reachable. 2071 7.1.3 Initialization Parameters (SCTP_INITMSG) 2073 Applications can specify protocol parameters for the default 2074 association initialization. The structure used to access and modify 2075 these parameters is defined in Section 5.2.1). The option name 2076 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2078 Setting initialization parameters is effective only on an unconnected 2079 socket (for UDP-style sockets only future associations are effected 2080 by the change). With TCP-style sockets, this option is inherited by 2081 sockets derived from a listener socket. 2083 7.1.4 SO_LINGER 2085 An application using the TCP-style socket can use this option to 2086 perform the SCTP ABORT primitive. The linger option structure is: 2088 struct linger { 2089 int l_onoff; /* option on/off */ 2090 int l_linger; /* linger time */ 2091 }; 2093 To enable the option, set l_onoff to 1. If the l_linger value is set 2094 to 0, calling close() is the same as the ABORT primitive. If the 2095 value is set to a negative value, the setsockopt() call will return 2096 an error. If the value is set to a positive value linger_time, the 2097 close() can be blocked for at most linger_time ms. If the graceful 2098 shutdown phase does not finish during this period, close() will 2099 return but the graceful shutdown phase continues in the system. 2101 7.1.5 SCTP_NODELAY 2103 Turn on/off any Nagle-like algorithm. This means that packets are 2104 generally sent as soon as possible and no unnecessary delays are 2105 introduced, at the cost of more packets in the network. Expects an 2106 integer boolean flag. 2108 7.1.6 SO_RCVBUF 2110 Sets receive buffer size. For SCTP TCP-style sockets, this controls 2111 the receiver window size. For UDP-style sockets, this controls the 2112 receiver window size for all associations bound to the socket 2113 descriptor used in the setsockopt() or getsockopt() call. The option 2114 applies to each association's window size separately. Expects an 2115 integer. 2117 7.1.7 SO_SNDBUF 2119 Sets send buffer size. For SCTP TCP-style sockets, this controls the 2120 amount of data SCTP may have waiting in internal buffers to be sent. 2121 This option therefore bounds the maximum size of data that can be 2122 sent in a single send call. For UDP-style sockets, the effect is the 2123 same, except that it applies to all associations bound to the socket 2124 descriptor used in the setsockopt() or getsockopt() call. The option 2125 applies to each association's window size separately. Expects an 2126 integer. 2128 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 2130 This socket option is applicable to the UDP-style socket only. When 2131 set it will cause associations that are idle for more than the 2132 specified number of seconds to automatically close. An association 2133 being idle is defined an association that has NOT sent or received 2134 user data. The special value of '0' indicates that no automatic 2135 close of any associations should be performed. The option expects an 2136 integer defining the number of seconds of idle time before an 2137 association is closed. 2139 7.1.9 Set Primary Address (SCTP_SET_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_setprim { 2147 sctp_assoc_t ssp_assoc_id; 2148 struct sockaddr_storage ssp_addr; 2149 }; 2150 ssp_addr The address to set as primary 2151 ssp_assoc_id (UDP style socket) This is filled in by the 2152 application, and identifies the association 2153 for this request. 2155 This functionality is optional. Implementations that do not support 2156 this functionality should return EOPNOTSUPP. 2158 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2160 Requests that the local SCTP stack use the enclosed peer address as 2161 the association primary. The enclosed address must be one of the 2162 association peer's addresses. The following structure is used to 2163 make a set peer primary request: 2165 struct sctp_setpeerprim { 2166 sctp_assoc_t sspp_assoc_id; 2167 struct sockaddr_storage sspp_addr; 2168 }; 2170 sspp_addr The address to set as primary 2171 sspp_assoc_id (UDP 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_SET_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 u_int32_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 Set default message time outs (SCTP_SET_STREAM_TIMEOUTS) 2190 This option requests that the requested stream apply a default time- 2191 out for messages in queue. The default value is used when the 2192 application does not specify a timeout in the sendrcvinfo structure 2193 (sinfo_timetolive element see Section 5.2.2). 2195 struct sctp_setstrm_timeout { 2196 sctp_assoc_t ssto_assoc_id; 2197 u_int32_t ssto_timeout; 2198 u_int16_t ssto_streamid_start; 2199 u_int16_t ssto_streamid_end; 2200 }; 2202 ssto_assoc_id (UDP style socket) This is filled in by the 2203 application, and identifies the association 2204 for this request. 2205 ssto_timeout The maximum time in milliseconds that messages 2206 should be held inqueue before failure. 2207 ssto_streamid_start The beginning stream identifier to apply this 2208 default against. 2209 ssto_streamid_end The ending stream identifier to apply this 2210 default against. 2212 Note that a timeout value of 0 indicates that no inqueue timeout 2213 should be applied against the stream. 2215 7.1.13 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2217 This option is a on/off flag. If enabled no SCTP message 2218 fragmentation will be performed. Instead if a message being sent 2219 exceeds the current PMTU size, the message will NOT be sent and 2220 instead a error will be indicated to the user. 2222 7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) 2224 Applications can enable or disable heartbeats for any peer address of 2225 an association, modify an address's heartbeat interval, force a 2226 heartbeat to be sent immediately, and adjust the address's maximum 2227 number of retransmissions sent before an address is considered 2228 unreachable. The following structure is used to access and modify an 2229 address's parameters: 2231 struct sctp_paddrparams { 2232 sctp_assoc_t spp_assoc_id; 2233 struct sockaddr_storage spp_address; 2234 uint32_t spp_hbinterval; 2235 uint16_t spp_pathmaxrxt; 2236 }; 2238 spp_assoc_id - (UDP style socket) This is filled in the application, 2239 and identifies the association for this query. 2240 spp_address - This specifies which address is of interest. 2241 spp_hbinterval - This contains the value of the heartbeat interval, 2242 in milliseconds. A value of 0, when modifying the 2243 parameter, specifies that the heartbeat on this 2244 address should be disabled. A value of UINT32_MAX 2245 (4294967295), when modifying the parameter, 2246 specifies that a heartbeat should be sent 2247 immediately to the peer address, and the current 2248 interval should remain unchanged. 2249 spp_pathmaxrxt - This contains the maximum number of 2250 retransmissions before this address shall be 2251 considered unreachable. 2253 To read or modify these parameters, the application should call 2254 sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. 2256 7.1.15 Set default send parameters (SET_DEFAULT_SEND_PARAM) 2258 Applications that wish to use the sendto() system call may wish to 2259 specify a default set of parameters that would normally be supplied 2260 through the inclusion of ancillary data. This socket option allows 2261 such an application to set the default sctp_sndrcvinfo structure. 2262 The application that wishes to use this socket option simply passes 2263 in to this call the sctp_sndrcvinfo structure defined in Section 2264 5.2.2) The input parameters accepted by this call include 2265 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, 2266 sinfo_timetolive. The user must provide the sinfo_assoc_id field in 2267 to this call if the caller is using the UDP model. 2269 7.1.16 Set notification and ancillary events (SCTP_SET_EVENTS) 2271 This socket option is used to specify various notifications and 2272 ancillary data the user wishes to receive. Please see Section 7.3) 2273 for a full description of this option and its usage. 2275 7.2 Read-Only Options 2276 7.2.1 Association Status (SCTP_STATUS) 2278 Applications can retrieve current status information about an 2279 association, including association state, peer receiver window size, 2280 number of unacked data chunks, and number of data chunks pending 2281 receipt. This information is read-only. The following structure is 2282 used to access this information: 2284 struct sctp_status { 2285 sctp_assoc_t sstat_assoc_id; 2286 int32_t sstat_state; 2287 uint32_t sstat_rwnd; 2288 uint16_t sstat_unackdata; 2289 uint16_t sstat_penddata; 2290 uint16_t sstat_instrms; 2291 uint16_t sstat_outstrms; 2292 uint32_t sstat_fragmentation_point; 2293 struct sctp_paddrinfo sstat_primary; 2294 }; 2296 sstat_state - This contains the association's current state one 2297 of the following values: 2299 SCTP_CLOSED 2300 SCTP_BOUND 2301 SCTP_LISTEN 2302 SCTP_COOKIE_WAIT 2303 SCTP_COOKIE_ECHOED 2304 SCTP_ESTABLISHED 2305 SCTP_SHUTDOWN_PENDING 2306 SCTP_SHUTDOWN_SENT 2307 SCTP_SHUTDOWN_RECEIVED 2308 SCTP_SHUTDOWN_ACK_SENT 2310 sstat_rwnd - This contains the association peer's current 2311 receiver window size. 2312 sstat_unackdata - This is the number of unacked data chunks. 2313 sstat_penddata - This is the number of data chunks pending receipt. 2314 sstat_primary - This is information on the current primary peer 2315 address. 2316 sstat_assoc_id - (UDP style socket) This holds the an identifier for the 2317 association. All notifications for a given association 2318 have the same association identifier. 2320 sstat_instrms - The number of streams that the peer will 2321 be using inbound. 2323 sstat_outstrms - The number of streams that the endpoint is 2324 allowed to use outbound. 2326 sstat_fragmentation_point - The size at which SCTP fragmentation 2327 will occur. 2329 To access these status values, the application calls getsockopt() 2330 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2331 ignored for TCP style socket. 2333 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2335 Applications can retrieve information about a specific peer address 2336 of an association, including its reachability state, congestion 2337 window, and retransmission timer values. This information is read- 2338 only. The following structure is used to access this information: 2340 struct sctp_paddrinfo { 2341 sctp_assoc_t spinfo_assoc_id; 2342 struct sockaddr_storage spinfo_address; 2343 int32_t spinfo_state; 2344 uint32_t spinfo_cwnd; 2345 uint32_t spinfo_srtt; 2346 uint32_t spinfo_rto; 2347 uint32_t spinfo_mtu; 2348 }; 2350 spinfo_address - This is filled in the application, and contains 2351 the peer address of interest. 2353 On return from getsockopt(): 2355 spinfo_state - This contains the peer addresses's state (either 2356 SCTP_ACTIVE or SCTP_INACTIVE). 2357 spinfo_cwnd - This contains the peer addresses's current congestion 2358 window. 2359 spinfo_srtt - This contains the peer addresses's current smoothed 2360 round-trip time calculation in milliseconds. 2361 spinfo_rto - This contains the peer addresses's current 2362 retransmission timeout value in milliseconds. 2363 spinfo_mtu - The current P-MTU of this address. 2364 spinfo_assoc_id - (UDP style socket) This is filled in the application, 2365 and identifies the association for this query. 2367 To retrieve this information, use sctp_opt_info() with the 2368 SCTP_GET_PEER_ADDR_INFO options. 2370 7.3 Ancillary Data and Notification Interest Options 2372 Applications can receive per-message ancillary information and 2373 notifications of certain SCTP events with recvmsg(). 2375 The following optional information is available to the application: 2377 1. SCTP_SNDRCV: Per-message information (i.e. stream number, TSN, 2378 SSN, etc. described in Section 5.2.2) 2380 2. SCTP_ASSOC_CHANGE: (described in Section 5.3.1.1) 2382 3. SCTP_PEER_ADDR_CHANGE: (described in Section 5.3.1.2) 2384 4. SCTP_REMOTE_ERROR: (described in Section 5.3.1.3) 2386 5. SCTP_SEND_FAILED: (described in Section 5.3.1.4) 2388 6. SCTP_SHUTDOWN_EVENT: (described in Section 5.3.1.5) 2390 7. SCTP_ADAPTION_INDICATION: (described in Section 5.3.1.6) 2392 8. SCTP_PARTIAL_DELIVERY_EVENT: (described in Section 5.3.1.7) 2394 To receive any ancillary data or notifications, first the application 2395 registers it's interest by calling the SCTP_SET_EVENTS setsockopt() 2396 with the following structure. 2398 struct sctp_event_subscribe{ 2399 u_int8_t sctp_data_io_event; 2400 u_int8_t sctp_association_event; 2401 u_int8_t sctp_address_event; 2402 u_int8_t sctp_send_failure_event; 2403 u_int8_t sctp_peer_error_event; 2404 u_int8_t sctp_shutdown_event; 2405 u_int8_t sctp_partial_delivery_event; 2406 u_int8_t sctp_adaption_layer_event; 2407 }; 2409 sctp_data_io_event - Setting this flag to 1 will cause the reception 2410 of SCTP_SNDRCV information on a per message basis. The application 2411 will need to use the recvmsg() interface so that it can receive the 2412 event information contained in the msg_control field. Please see 2413 Section 5.2 for further details. Setting the flag to 0 will disable 2414 reception of the message control information. 2416 sctp_association_event - Setting this flag to 1 will enable the 2417 reception of association event notifications. Setting the flag to 0 2418 will disable association event notifications. For more information 2419 on event notifications please see Section 5.3. 2421 sctp_address_event - Setting this flag to 1 will enable the reception 2422 of address event notifications. Setting the flag to 0 will disable 2423 address event notifications. For more information on event 2424 notifications please see Section 5.3. 2426 sctp_send_failure_event - Setting this flag to 1 will enable the 2427 reception of send failure event notifications. Setting the flag to 0 2428 will disable send failure event notifications. For more information 2429 on event notifications please see Section 5.3. 2431 sctp_peer_error_event - Setting this flag to 1 will enable the 2432 reception of peer error event notifications. Setting the flag to 0 2433 will disable peer error event notifications. For more information on 2434 event notifications please see Section 5.3. 2436 sctp_shutdown_event - Setting this flag to 1 will enable the 2437 reception of shutdown event notifications. Setting the flag to 0 2438 will disable shutdown event notifications. For more information on 2439 event notifications please see Section 5.3. 2441 sctp_partial_delivery_event - Setting this flag to 1 will enable the 2442 reception of partial delivery notifications. Setting the flag to 0 2443 will disable partial delivery event notifications. For more 2444 information on event notifications please see Section 5.3. 2446 sctp_adaption_layer_event - Setting this flag to 1 will enable the 2447 reception of adaption layer notifications. Setting the flag to 0 2448 will disable adaption layer event notifications. For more 2449 information on event notifications please see Section 5.3. 2451 An example where an application would like to receive data io events 2452 and association events but no others would be as follows: 2454 { 2455 struct sctp_event_subscribe event; 2457 memset(&event,0,sizeof(event)); 2459 event.sctp_data_io_event = 1; 2460 event.sctp_association_event = 1; 2462 setsockopt(fd, IPPROTO_SCTP, SCTP_SET_EVENT, &event, sizeof(event)); 2463 } 2465 Note that for UDP-style SCTP sockets, the caller of recvmsg() 2466 receives ancillary data and notifications for ALL associations bound 2467 to the file descriptor. For TCP-style SCTP sockets, the caller 2468 receives ancillary data and notifications for only the single 2469 association bound to the file descriptor. 2471 By default a UDP-style socket has sctp_data_io_event and 2472 sctp_association_event on and all other options off. 2474 8. New Interfaces 2476 Depending on the system, the following interface can be implemented 2477 as a system call or library function. 2479 8.1 sctp_bindx() 2481 The syntax of sctp_bindx() is, 2483 int sctp_bindx(int sd, struct sockaddr_storage *addrs, int addrcnt, 2484 int flags); 2486 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 2487 If the sd is an IPv6 socket, the addresses passed can either be IPv4 2488 or IPv6 addresses. 2490 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2491 Section 3.1.2 for this usage. 2493 addrs is a pointer to an array of one or more socket addresses. Each 2494 address is contained in a struct sockaddr_storage, so each address is 2495 a fixed length. The caller specifies the number of addresses in the 2496 array with addrcnt. 2498 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2499 -1, and sets errno to the appropriate error code. 2501 For SCTP, the port given in each socket address must be the same, or 2502 sctp_bindx() will fail, setting errno to EINVAL. 2504 The flags parameter is formed from the bitwise OR of zero or more of 2505 the following currently defined flags: 2507 SCTP_BINDX_ADD_ADDR 2509 SCTP_BINDX_REM_ADDR 2511 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2512 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 2513 addresses from the association. The two flags are mutually 2514 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 2515 caller may not remove all addresses from an association; sctp_bindx() 2516 will reject such an attempt with EINVAL. 2518 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2519 additional addresses with an endpoint after calling bind(). Or use 2520 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2521 socket is associated with so that no new association accepted will be 2522 associated with those addresses. If the endpoint supports dynamic 2523 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 2524 endpoint to send the appropriate message to the peer to change the 2525 peers address lists. 2527 Adding and removing addresses from a connected association is 2528 optional functionality. Implementations that do not support this 2529 functionality should return EOPNOTSUPP. 2531 8.2 Branched-off Association 2533 After an association is established on a UDP-style socket, the 2534 application may wish to branch off the association into a separate 2535 socket/file descriptor. 2537 This is particularly desirable when, for instance, the application 2538 wishes to have a number of sporadic message senders/receivers remain 2539 under the original UDP-style socket but branch off those associations 2540 carrying high volume data traffic into their own separate socket 2541 descriptors. 2543 The application uses sctp_peeloff() call to branch off an association 2544 into a separate socket (Note the semantics are somewhat changed from 2545 the traditional TCP-style accept() call). 2547 The syntax is: 2549 new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id); 2551 the new socket descriptor representing the branched-off 2552 association. 2554 the original UDP-style socket descriptor returned from the 2555 socket() system call (see Section 3.1.1). 2557 the specified identifier of the association that is to be branched 2558 off to a separate file descriptor (Note, in a traditional TCP- 2559 style accept() call, this would be an out parameter, but for the 2560 UDP-style call, this is an in parameter). 2562 8.3 sctp_getpaddrs() 2564 sctp_getpaddrs() returns all peer addresses in an association. The 2565 syntax is, 2566 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2567 struct sockaddr_storage **addrs); 2569 On return, addrs will point to a dynamically allocated array of 2570 struct sockaddr_storages, one for each peer address. The caller 2571 should use sctp_freepaddrs() to free the memory. addrs must not be 2572 NULL. 2574 If sd is an IPv4 socket, the addresses returned will be all IPv4 2575 addresses. If sd is an IPv6 socket, the addresses returned can be a 2576 mix of IPv4 or IPv6 addresses. 2578 For UDP-style sockets, id specifies the association to query. For 2579 TCP-style sockets, id is ignored. 2581 On success, sctp_getpaddrs() returns the number of peer addresses in 2582 the association. If there is no association on this socket, 2583 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2584 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 2585 is undefined. 2587 8.4 sctp_freepaddrs() 2589 sctp_freepaddrs() frees all resources allocated by 2590 sctp_getpaddrs(). Its syntax is, 2592 void sctp_freepaddrs(struct sockaddr_storage *addrs); 2594 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2596 8.5 sctp_getladdrs() 2598 sctp_getladdrs() returns all locally bound address on a socket. The 2599 syntax is, 2601 int sctp_getladdrs(int sock, sctp_assoc_t id, 2602 struct sockaddr_storage **ss); 2604 On return, addrs will point to a dynamically allocated array of 2605 struct sockaddr_storages, one for each local address. The caller 2606 should use sctp_freeladdrs() to free the memory. addrs must not be 2607 NULL. 2609 If sd is an IPv4 socket, the addresses returned will be all IPv4 2610 addresses. If sd is an IPv6 socket, the addresses returned can be a 2611 mix of IPv4 or IPv6 addresses. 2613 For UDP-style sockets, id specifies the association to query. For 2614 TCP-style sockets, id is ignored. 2616 If the id field is set to the value '0' then the locally bound 2617 addresses are returned without regard to any particular association. 2619 On success, sctp_getladdrs() returns the number of local addresses 2620 bound to the socket. If the socket is unbound, sctp_getladdrs() 2621 returns 0, and the value of *addrs is undefined. If an error occurs, 2622 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2624 8.6 sctp_freeladdrs() 2626 sctp_freeladdrs() frees all resources allocated by 2627 sctp_getladdrs(). Its syntax is, 2629 void sctp_freeladdrs(struct sockaddr_storage *addrs); 2631 addrs is the array of peer addresses returned by sctp_getladdrs(). 2633 9. Security Considerations 2635 Many TCP and UDP implementations reserve port numbers below 1024 for 2636 privileged users. If the target platform supports privileged users, 2637 the SCTP implementation SHOULD restrict the ability to call bind() or 2638 sctp_bindx() on these port numbers to privileged users. 2640 Similarly unprevledged users should not be able to set protocol 2641 parameters which could result in the congestion control algorithm 2642 being more aggressive than permitted on the public Internet. These 2643 parameters are: 2645 struct sctp_rtoinfo 2647 If an unprivileged user inherits a UDP-style socket with open 2648 associations on a privileged port, it MAY be permitted to accept new 2649 associations, but it SHOULD NOT be permitted to open new 2650 associations. This could be relevant for the r* family of protocols. 2652 10. Acknowledgments 2654 The authors wish to thank Kavitha Baratakke, Mike Bartlett, Jon 2655 Berger, Scott Kimble, Renee Revis, and many others on the TSVWG 2656 mailing list for contributing valuable comments. 2658 A special thanks to Phillip Conrad, for his suggested text, quick and 2659 constructive insights, and most of all his persistent fighting to 2660 keep the interface to SCTP usable for the application programmer. 2662 References 2664 [1] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2665 September 1981. 2667 [2] Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 2668 1980. 2670 [3] Braden, B., "T/TCP -- TCP Extensions for Transactions Functional 2671 Specification", RFC 1644, July 1994. 2673 [4] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 2674 9, RFC 2026, October 1996. 2676 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2677 Levels", BCP 14, RFC 2119, March 1997. 2679 [6] Stevens, W. and M. Thomas, "Advanced Sockets API for IPv6", RFC 2680 2292, February 1998. 2682 [7] Gilligan, R., Thomson, S., Bound, J. and W. Stevens, "Basic 2683 Socket Interface Extensions for IPv6", RFC 2553, March 1999. 2685 [8] Stewart, R., Xie, Q., Morneault, K., Sharp, C., Schwarzbauer, 2686 H., Taylor, T., Rytina, I., Kalla, M., Zhang, L. and V. Paxson, 2687 "Stream Control Transmission Protocol", RFC 2960, October 2000. 2689 Authors' Addresses 2691 Randall R. Stewart 2692 Cisco Systems, Inc. 2693 8725 West Higgins Road 2694 Suite 300 2695 Chicago, IL 60631 2696 USA 2698 Phone: 2699 EMail: rrs@cisco.com 2700 Qiaobing Xie 2701 Motorola, Inc. 2702 1501 W. Shure Drive, #2309 2703 Arlington Heights, IL 60004 2704 USA 2706 Phone: 2707 EMail: qxie1@email.mot.com 2709 La Monte H.P. Yarroll 2710 Motorola, Inc. 2711 1501 W. Shure Drive, IL-2315 2712 Arlington Heights, IL 60004 2713 USA 2715 Phone: 2716 EMail: piggy@acm.org 2718 Jonathan Wood 2719 DoCoMo USA Labs 2720 181 Metro Drive, Suite 300 2721 San Jose, CA 95110 2722 USA 2724 Phone: 2725 EMail: jonwood@speakeasy.net 2727 Kacheong Poon 2728 Sun Microsystems, Inc. 2729 901 San Antonio Road 2730 Palo Alto, CA 94303 2731 USA 2733 Phone: 2734 EMail: kcpoon@yahoo.com 2736 Ken Fujita 2737 NEC USA, Inc. 2738 10080 Wolfe Road, Suite SW3-350 2739 Cupertino, CA 95014 2740 USA 2742 Phone: 2743 EMail: fken@ccrl.sj.nec.com 2744 Michael Tuexen 2745 Siemens AG 2746 ICN WN CC SE 7 2747 D-81359 Munich 2748 Germany 2750 Phone: 2751 EMail: Michael.Tuexen@siemens.com 2753 Appendix A. TCP-style Code Example 2755 The following code is a simple implementation of an echo server over 2756 SCTP. The example shows how to use some features of TCP-style IPv4 2757 SCTP sockets, including: 2759 o Opening, binding, and listening for new associations on a socket; 2761 o Enabling ancillary data 2763 o Enabling notifications 2765 o Using ancillary data with sendmsg() and recvmsg() 2767 o Using MSG_EOR to determine if an entire message has been read 2769 o Handling notifications 2771 #include 2772 #include 2773 #include 2774 #include 2775 #include 2776 #include 2777 #include 2778 #include 2779 #include 2781 #define BUFLEN 100 2783 static void 2784 handle_event(void *buf) 2785 { 2786 struct sctp_assoc_change *sac; 2787 struct sctp_send_failed *ssf; 2788 struct sctp_paddr_change *spc; 2789 struct sctp_remote_error *sre; 2790 union sctp_notification *snp; 2791 char addrbuf[INET6_ADDRSTRLEN]; 2792 const char *ap; 2793 struct sockaddr_in *sin; 2794 struct sockaddr_in6 *sin6; 2796 snp = buf; 2798 switch (snp->sn_type) { 2799 case SCTP_ASSOC_CHANGE: 2801 sac = &snp->sn_assoc_change; 2802 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2803 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2804 sac->sac_inbound_streams, sac->sac_outbound_streams); 2805 break; 2806 case SCTP_SEND_FAILED: 2807 ssf = &snp->sn_send_failed; 2808 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2809 ssf->ssf_error); 2810 break; 2812 case SCTP_PEER_ADDR_CHANGE: 2813 spc = &snp->sn_paddr_change; /* mt changed */ 2814 if (spc->spc_aaddr.ss_family == AF_INET) { 2815 sin = (struct sockaddr_in *)&spc->spc_aaddr; 2816 ap = inet_ntop(AF_INET, &sin->sin_addr, 2817 addrbuf, INET6_ADDRSTRLEN); 2818 } else { 2819 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 2820 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 2821 addrbuf, INET6_ADDRSTRLEN); 2822 } 2823 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2824 spc->spc_state, spc->spc_error); 2825 break; 2826 case SCTP_REMOTE_ERROR: 2827 sre = &snp->sn_remote_error; 2828 printf("^^^ remote_error: err=%hu len=%hu\n", 2829 ntohs(sre->sre_error), ntohs(sre->sre_len)); 2830 break; 2831 case SCTP_SHUTDOWN_EVENT: 2832 printf("^^^ shutdown event\n"); 2833 break; 2834 default: 2835 printf("unknown type: %hu\n", snp->sn_type); 2836 break; 2837 } 2838 } 2840 static void * 2841 sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2842 ssize_t *nrp, size_t cmsglen) 2843 { 2844 ssize_t nr = 0; 2845 struct iovec iov[1]; 2847 *nrp = 0; 2848 iov->iov_base = buf; 2849 msg->msg_iov = iov; 2850 msg->msg_iovlen = 1; 2852 for (;;) { 2853 #ifndef MSG_XPG4_2 2854 #define MSG_XPG4_2 0 2855 #endif 2856 msg->msg_flags = MSG_XPG4_2; 2857 msg->msg_iov->iov_len = *buflen; 2858 msg->msg_controllen = cmsglen; 2860 nr += recvmsg(fd, msg, 0); 2861 if (nr <= 0) { 2862 /* EOF or error */ 2863 *nrp = nr; 2864 return (NULL); 2865 } 2867 if ((msg->msg_flags & MSG_EOR) != 0) { 2868 *nrp = nr; 2869 return (buf); 2870 } 2872 /* Realloc the buffer? */ 2873 if (*buflen == nr) { 2874 buf = realloc(buf, *buflen * 2); 2875 if (buf == 0) { 2876 fprintf(stderr, "out of memory\n"); 2877 exit(1); 2878 } 2879 *buflen *= 2; 2880 } 2882 /* Set the next read offset */ 2883 iov->iov_base = (char *)buf + nr; 2884 iov->iov_len = *buflen - nr; 2886 } 2887 } 2889 static void 2890 echo(int fd, int socketModeUDP) 2891 { 2892 ssize_t nr; 2893 struct sctp_sndrcvinfo *sri; 2894 struct msghdr msg[1]; 2895 struct cmsghdr *cmsg; 2896 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 2897 char *buf; 2898 size_t buflen; 2899 struct iovec iov[1]; 2900 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 2902 /* Allocate the initial data buffer */ 2903 buflen = BUFLEN; 2904 if (!(buf = malloc(BUFLEN))) { 2905 fprintf(stderr, "out of memory\n"); 2906 exit(1); 2907 } 2909 /* Set up the msghdr structure for receiving */ 2910 memset(msg, 0, sizeof (*msg)); 2911 msg->msg_control = cbuf; 2912 msg->msg_controllen = cmsglen; 2913 msg->msg_flags = 0; 2914 cmsg = (struct cmsghdr *)cbuf; 2915 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 2917 /* Wait for something to echo */ 2918 while (buf = sctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 2920 /* Intercept notifications here */ 2921 if (msg->msg_flags & MSG_NOTIFICATION) { 2922 handle_event(buf); 2923 continue; 2924 } 2926 iov->iov_base = buf; 2927 iov->iov_len = nr; 2928 msg->msg_iov = iov; 2929 msg->msg_iovlen = 1; 2931 printf("got %u bytes on stream %hu:\n", nr, 2932 sri->sinfo_stream); 2933 write(0, buf, nr); 2935 /* Echo it back */ 2936 msg->msg_flags = MSG_XPG4_2; 2937 if (sendmsg(fd, msg, 0) < 0) { 2938 perror("sendmsg"); 2939 exit(1); 2940 } 2941 } 2943 if (nr < 0) { 2944 perror("recvmsg"); 2946 } 2947 if(socketModeUDP == 0) 2948 close(fd); 2949 } 2951 int main() 2952 { 2953 int lfd, cfd; 2954 int onoff = 1; 2955 struct sockaddr_in sin[1]; 2957 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 2958 perror("socket"); 2959 exit(1); 2960 } 2962 sin->sin_family = AF_INET; 2963 sin->sin_port = htons(7); 2964 sin->sin_addr.s_addr = INADDR_ANY; 2965 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2966 perror("bind"); 2967 exit(1); 2968 } 2970 if (listen(lfd, 1) == -1) { 2971 perror("listen"); 2972 exit(1); 2973 } 2975 /* Wait for new associations */ 2976 for (;;) { 2977 struct sctp_event_subscribe event; 2978 if ((cfd = accept(lfd, NULL, 0)) == -1) { 2979 perror("accept"); 2980 exit(1); 2981 } 2983 /* Enable all events */ 2984 event.sctp_data_io_event = 1; 2985 event.sctp_association_event = 1; 2986 event.sctp_address_event = 1; 2987 event.sctp_send_failure_event = 1; 2988 event.sctp_peer_error_event = 1; 2989 event.sctp_shutdown_event = 1; 2990 event.sctp_partial_delivery_event = 1; 2991 event.sctp_adaption_layer_event = 1; 2992 if (setsockopt(r->fd, IPPROTO_SCTP, 2993 SCTP_SET_EVENTS, &event, 2994 sizeof(event)) != 0) { 2995 perror("setevent failed"); 2996 exit(1); 2997 } 2998 /* Echo back any and all data */ 2999 echo(cfd,0); 3000 } 3001 } 3003 Appendix B. UDP-style Code Example 3005 The following code is a simple implementation of an echo server over 3006 SCTP. The example shows how to use some features of UDP-style IPv4 3007 SCTP sockets, including: 3009 o Opening and binding of a socket; 3011 o Enabling ancillary data 3013 o Enabling notifications 3015 o Using ancillary data with sendmsg() and recvmsg() 3017 o Using MSG_EOR to determine if an entire message has been read 3019 o Handling notifications 3021 Note most functions defined in Appendix A are reused in this example. 3023 int main() 3024 { 3025 int fd; 3026 int onoff = 1; 3027 int idleTime = 2; 3028 struct sockaddr_in sin[1]; 3030 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3031 perror("socket"); 3032 exit(1); 3033 } 3035 sin->sin_family = AF_INET; 3036 sin->sin_port = htons(7); 3037 sin->sin_addr.s_addr = INADDR_ANY; 3038 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3039 perror("bind"); 3040 exit(1); 3041 } 3043 /* Enable all notifications and events */ 3044 event.sctp_data_io_event = 1; 3045 event.sctp_association_event = 1; 3046 event.sctp_address_event = 1; 3047 event.sctp_send_failure_event = 1; 3048 event.sctp_peer_error_event = 1; 3049 event.sctp_shutdown_event = 1; 3050 event.sctp_partial_delivery_event = 1; 3051 event.sctp_adaption_layer_event = 1; 3052 if (setsockopt(r->fd, IPPROTO_SCTP, 3053 SCTP_SET_EVENTS, &event, 3054 sizeof(event)) != 0) { 3055 perror("setevent failed"); 3056 exit(1); 3057 } 3058 /* Set associations to auto-close in 2 seconds of 3059 * inactivity 3060 */ 3061 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3062 &idleTime, 4) < 0) { 3063 perror("setsockopt SCTP_AUTOCLOSE"); 3064 exit(1); 3065 } 3067 /* Allow new associations to be accepted */ 3068 if (listen(fd, 0) < 0) { 3069 perror("listen"); 3070 exit(1); 3071 } 3073 /* Wait for new associations */ 3074 while(1){ 3075 /* Echo back any and all data */ 3076 echo(fd,1); 3077 } 3078 } 3080 Full Copyright Statement 3082 Copyright (C) The Internet Society (2002). All Rights Reserved. 3084 This document and translations of it may be copied and furnished to 3085 others, and derivative works that comment on or otherwise explain it 3086 or assist in its implementation may be prepared, copied, published 3087 and distributed, in whole or in part, without restriction of any 3088 kind, provided that the above copyright notice and this paragraph are 3089 included on all such copies and derivative works. However, this 3090 document itself may not be modified in any way, such as by removing 3091 the copyright notice or references to the Internet Society or other 3092 Internet organizations, except as needed for the purpose of 3093 developing Internet standards in which case the procedures for 3094 copyrights defined in the Internet Standards process must be 3095 followed, or as required to translate it into languages other than 3096 English. 3098 The limited permissions granted above are perpetual and will not be 3099 revoked by the Internet Society or its successors or assigns. 3101 This document and the information contained herein is provided on an 3102 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3103 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3104 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3105 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3106 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3108 Acknowledgement 3110 Funding for the RFC Editor function is currently provided by the 3111 Internet Society.