idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. == 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 32 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** There are 93 instances of lines with control characters in the document. ** The abstract seems to contain references ([SCTP]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 4 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 948: '...In other words the user MAY be able to...' RFC 2119 keyword, line 967: '... MAY override 'RTO.Max'. This valu...' RFC 2119 keyword, line 1109: '...e MSG_EOR clear. The user MUST finish...' RFC 2119 keyword, line 1863: '...sockaddr_storage SHOULD also support s...' RFC 2119 keyword, line 2547: '...P implementation SHOULD restrict the a...' (2 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 736 has weird spacing: '...n. The value...' == Line 748 has weird spacing: '...er send and ...' == Line 923 has weird spacing: '...g_level cms...' == Line 979 has weird spacing: '...g_level cms...' == Line 1597 has weird spacing: '... msghdr msg;...' == (4 more instances...) -- 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 (January 29, 2002) is 8095 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: 'RFC 2553' is mentioned on line 604, but not defined ** Obsolete undefined reference: RFC 2553 (Obsoleted by RFC 3493) -- Looks like a reference, but probably isn't: '0' on line 1401 == Missing Reference: 'RFC2960' is mentioned on line 1712, but not defined ** Obsolete undefined reference: RFC 2960 (Obsoleted by RFC 4960) -- Looks like a reference, but probably isn't: '1' on line 2898 == Unused Reference: 'STEVENS' is defined on line 2630, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 2292 (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2553 (Obsoleted by RFC 3493) ** Obsolete normative reference: RFC 2960 (ref. 'SCTP') (Obsoleted by RFC 4960) -- Duplicate reference: RFC2292, mentioned in 'STEVENS', was also mentioned in 'RFC2292'. ** Obsolete normative reference: RFC 2292 (ref. 'STEVENS') (Obsoleted by RFC 3542) Summary: 17 errors (**), 0 flaws (~~), 11 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group R. R. Stewart 2 INTERNET-DRAFT Cisco 3 Q. Xie 4 L Yarroll 5 Motorola 6 J. Wood 7 DoCoMo USA Labs 8 K. Poon 9 Sun Microsystems 10 K. Fujita 11 NEC 13 expires in six months January 29, 2002 15 Sockets API Extensions for SCTP 16 18 Status of This Memo 20 This document is an Internet-Draft and is in full conformance with 21 all provisions of Section 10 of [RFC2026]. Internet-Drafts are 22 working documents of the Internet Engineering Task Force (IETF), its 23 areas, and its working groups. Note that other groups may also 24 distribute working documents as Internet-Drafts. 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 Abstract 34 This document describes a mapping of the Stream Control Transmission 35 Protocol [SCTP] into a sockets API. The benefits of this mapping 36 include compatibility for TCP applications, access to new SCTP 37 features and a consolidated error and event notification scheme. 39 Table of Contents 41 1. Introduction............................................ 3 42 2. Conventions............................................. 4 43 2.1 Data Types............................................ 4 44 3. UDP-style Interface..................................... 4 45 3.1 Basic Operation....................................... 4 46 3.1.1 socket() - UDP Style Syntax...................... 5 47 3.1.2 bind() - UDP Style Syntax........................ 5 48 3.1.3 listen() - UDP Style Syntax...................... 6 49 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax....... 7 50 3.1.5 close() - UDP Style Syntax....................... 8 51 3.1.6 connect() - UDP Style Syntax..................... 8 52 3.2 Implicit Association Setup............................ 9 53 3.3 Non-blocking mode..................................... 9 54 4. TCP-style Interface.....................................10 55 4.1 Basic Operation.......................................10 56 4.1.1 socket() - TCP Style Syntax........................11 57 4.1.2 bind() - TCP Style Syntax..........................11 58 4.1.3 listen() - TCP Style Syntax........................12 59 4.1.4 accept() - TCP Style Syntax........................13 60 4.1.5 connect() - TCP Style Syntax.......................13 61 4.1.6 close() - TCP Style Syntax.........................14 62 4.1.7 shutdown() - TCP Style Syntax......................14 63 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax.........15 64 4.1.9 getpeername() .....................................15 65 5. Data Structures..........................................16 66 5.1 The msghdr and cmsghdr Structures......................16 67 5.2 SCTP msg_control Structures............................17 68 5.2.1 SCTP Initiation Structure (SCTP_INIT)...............17 69 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV).....19 70 5.3 SCTP Events and Notifications..........................21 71 5.3.1 SCTP Notification Structure.........................21 72 5.3.1.1 SCTP_ASSOC_CHANGE................................23 73 5.3.1.2 SCTP_PEER_ADDR_CHANGE............................24 74 5.3.1.3 SCTP_REMOTE_ERROR................................25 75 5.3.1.4 SCTP_SEND_FAILED.................................26 76 5.3.1.5 SCTP_SHUTDOWN_EVENT..............................27 77 5.3.1.6 SCTP_ADAPTION_INDICATION.........................28 78 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT......................29 79 5.4 Ancillary Data Considerations and Semantics...........30 80 5.4.1 Multiple Items and Ordering........................30 81 5.4.2 Accessing and Manipulating Ancillary Data..........30 82 5.4.3 Control Message Buffer Sizing......................30 83 6. Common Operations for Both Styles.......................31 84 6.1 send(), recv(), sendto(), recvfrom()..................31 85 6.2 setsockopt(), getsockopt()............................32 86 6.3 read() and write()....................................33 87 6.4 getsockname().........................................33 88 7. Socket Options..........................................33 89 7.1 Read / Write Options..................................36 90 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO)...36 91 7.1.2 Association Retransmission Parameter 92 (SCTP_ASSOCRTXINFO)................................36 93 7.1.3 Initialization Parameters (SCTP_INITMSG)...........37 94 7.1.4 SO_LINGER..........................................37 95 7.1.5 SO_NODELAY.........................................37 96 7.1.6 SO_RCVBUF..........................................37 97 7.1.7 SO_SNDBUF..........................................37 98 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE)...39 99 7.1.9 SCTP_SET_PRIMARY_ADDR..............................39 100 7.1.10 SCTP_SET_PEER_PRIMARY_ADDR........................39 101 7.1.11 Set Adaption Layer Bits...........................39 102 7.1.12 Set default message time outs 103 (SCTP_SET_STREAM_TIMEOUTS)........................40 104 7.1.13 Enable/Disable message fragmentation 105 (SCTP_DISABLE_FRAGMENTS)..........................40 106 7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS 107 /SCTP_GET_PEER_ADDR_PARAMS)....40 108 7.2 Read-Only Options.....................................41 109 7.2.1 Association Status (SCTP_STATUS)...................41 110 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO).42 112 7.3. Ancillary Data and Notification Interest Options.....43 113 8. New Interfaces..........................................45 114 8.1 sctp_bindx()..........................................45 115 8.2 Branched-off Association, sctp_peeloff()..............46 116 8.3 sctp_getpaddrs()......................................47 117 8.4 sctp_freepaddrs().....................................47 118 8.5 sctp_getladdrs()......................................47 119 8.6 sctp_freeladdrs().....................................48 120 9. Security Considerations.................................48 121 10. Acknowledgements......................................48 122 11. Authors' Addresses....................................48 123 12. References............................................49 124 Appendix A: TCP-style Code Example.........................50 125 Appendix B: UDP-style Code Example.........................54 127 1. Introduction 129 The sockets API has provided a standard mapping of the Internet 130 Protocol suite to many operating systems. Both TCP [RFC793] and UDP 131 [RFC768] have benefited from this standard representation and access 132 method across many diverse platforms. SCTP is a new protocol that 133 provides many of the characteristics of TCP but also incorporates 134 semantics more akin to UDP. This document defines a method to map 135 the existing sockets API for use with SCTP, providing both a base 136 for access to new features and compatibility so that most existing 137 TCP applications can be migrated to SCTP with few (if any) changes. 139 There are three basic design objectives: 141 1) Maintain consistency with existing sockets APIs: 143 We define a sockets mapping for SCTP that is consistent with other 144 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 145 IPv6). 147 2) Support a UDP-style interface 149 This set of semantics is similar to that defined for conntionless 150 protocols, such as UDP. It is more efficient than a TCP-like 151 connection-oriented interface in terms of exploring the new features 152 of SCTP. 154 Note that SCTP is connection-oriented in nature, and it does not 155 support broadcast or multicast communications, as UDP does. 157 3) Support a TCP-style interface 159 This interface supports the same basic semantics as sockets for 160 connection-oriented protocols, such as TCP. 162 The purpose of defining this interface is to allow existing 163 applications built on connnection-oriented protocols be ported to 164 use SCTP with very little effort, and developers familiar with those 165 semantics can easily adapt to SCTP. 167 Extensions will be added to this mapping to provide mechanisms to 168 exploit new features of SCTP. 170 Goals 2 and 3 are not compatible, so in this document we define two 171 modes of mapping, namely the UDP-style mapping and the TCP-style 172 mapping. These two modes share some common data structures and 173 operations, but will require the use of two different programming 174 models. 176 A mechanism is defined to convert a UDP-style SCTP socket into a 177 TCP-style socket. 179 Some of the SCTP mechanisms cannot be adequately mapped to existing 180 socket interface. In some cases, it is more desirable to have new 181 interface instead of using exisitng socket calls. This document 182 also describes those new interface. 184 2. Conventions 186 2.1 Data Types 188 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 189 1003.1g are used: uintN_t means an unsigned integer of exactly N 190 bits (e.g., uint16_t). We also assume the argument data types from 191 1003.1g when possible (e.g., the final argument to setsockopt() is a 192 size_t value). Whenever buffer sizes are specified, the POSIX 193 1003.1 size_t data type is used. 195 3. UDP-style Interface 197 The UDP-style interface has the following characteristics: 199 A) Outbound association setup is implicit. 201 B) Messages are delivered in complete messages (with one notable 202 exception). 204 3.1 Basic Operation 206 A typical server in this model uses the following socket calls in 207 sequence to prepare an endpoint for servicing requests: 209 1. socket() 210 2. bind() 211 3. listen() 212 4. recvmsg() 213 5. sendmsg() 214 6. close() 216 A typical client uses the following calls in sequence to setup an 217 association with a server to request services: 219 1. socket() 220 2. sendmsg() 221 3. recvmsg() 222 4. close() 224 In this model, by default, all the associations connected to the 225 endpoint are represented with a single socket. 227 If the server or client wishes to branch an existing association off 228 to a separate socket, it is required to call sctp_peeloff() and in 229 the parameter specifies one of the transport addresses of the 230 association. The sctp_peeloff() call will return a new socket which 231 can then be used with recv() and send() functions for message 232 passing. See Section 8.2 for more on branched-off associations. 234 Once an association is branched off to a separate socket, it becomes 235 completely separated from the original socket. All subsequent 236 control and data operations to that association must be done through 237 the new socket. For example, the close operation on the original 238 socket will not terminate any associations that have been branched 239 off to a different socket. 241 We will discuss the UDP-style socket calls in more details in the 242 following subsections. 244 3.1.1 socket() - UDP Style Syntax 246 Applications use socket() to create a socket descriptor to represent 247 an SCTP endpoint. 249 The syntax is, 251 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 253 or, 255 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 257 Here, SOCK_SEQPACKET indicates the creation of a UDP-style socket. 259 The first form creates an endpoint which can use only IPv4 260 addresses, while, the second form creates an endpoint which can use 261 both IPv6 and IPv4 mapped addresses. 263 3.1.2 bind() - UDP Style Syntax 265 Applications use bind() to specify which local address the SCTP 266 endpoint should associate itself with. 268 An SCTP endpoint can be associated with multiple addresses. To do 269 this, sctp_bindx() is introduced in section 8.1 to help applications 270 do the job of associating multiple addresses. 272 These addresses associated with a socket are the eligible transport 273 addresses for the endpoint to send and receive data. The endpoint 274 will also present these addresses to its peers during the 275 association initialization process, see [SCTP]. 277 After calling bind() or sctp_bindx(), if the endpoint wishes to 278 accept new associations on the socket, it must call listen() (see 279 section 3.1.3). 281 The syntax of bind() is, 283 ret = bind(int sd, struct sockaddr *addr, int addrlen); 285 sd - the socket descriptor returned by socket(). 286 addr - the address structure (struct sockaddr_in or struct 287 sockaddr_in6 [RFC 2553]), 288 addrlen - the size of the address structure. 290 If sd is an IPv4 socket, the address passed must be an IPv4 address. 291 If the sd is an IPv6 socket, the address passed can either be an 292 IPv4 or an IPv6 address. 294 Applications cannot call bind() multiple times to associate multiple 295 addresses to an endpoint. After the first call to bind(), all 296 subsequent calls will return an error. 298 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 299 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 300 operating system will associate the endpoint with an optimal address 301 set of the available interfaces. 303 If a bind() or sctp_bindx() is not called prior to a sendmsg() call 304 that initiates a new association, the system picks an ephemeral port 305 and will choose an address set equivalent to binding with a wildcard 306 address. One of those addresses will be the primary address for the 307 association. This automatically enables the multihoming capability 308 of SCTP. 310 3.1.3 listen() - UDP Style Syntax 312 By default, new associations are not accepted for UDP style sockets. 313 An application uses listen() to mark a socket as being able to 314 accept new associations. The syntax is, 316 int listen(int socket, int backlog); 318 socket - the socket descriptor of the endpoint. 319 backlog - ignored for UDP-style sockets. 321 Note that UDP-style socket consumers do not need to call accept to 322 retrieve new associations. Calling accept() on a UDP-style socket 323 should return EOPNOTSUPP. Rather, new associations are accepted 324 automatically, and notifications of the new associations are 325 delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if these 326 notifications are enabled). Clients will typically not call listen, 327 so that they can be assured that the only associations on the socket 328 will be ones they actively initiated. Server or peer-to-peer 329 sockets, on the other hand, will always accept new associations, so 330 a well-written application using server UDP-style sockets must be 331 prepared to handle new associations from unwanted peers. 333 Also note that the SCTP_ASSOC_CHANGE event provides the association 334 ID for a new association, so if applications wish to use the 335 association ID as input to other socket calls, they should ensure 336 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 337 default). 339 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax 341 An application uses sendmsg() and recvmsg() call to transmit data to 342 and receive data from its peer. 344 ssize_t sendmsg(int socket, const struct msghdr *message, 345 int flags); 347 ssize_t recvmsg(int socket, struct msghdr *message, 348 int flags); 350 socket - the socket descriptor of the endpoint. 351 message - pointer to the msghdr structure which contains a single 352 user message and possibly some ancillary data. 354 See Section 5 for complete description of the data 355 structures. 357 flags - No new flags are defined for SCTP at this level. See 358 Section 5 for SCTP-specific flags used in the msghdr 359 structure. 361 As we will see in Section 5, along with the user data, the ancillary 362 data field is used to carry the sctp_sndrcvinfo and/or the 363 sctp_initmsg structures to perform various SCTP functions including 364 specifying options for sending each user message. Those options, 365 depending on whether sending or receiving, include stream number, 366 stream sequence number, TOS, various flags, context and payload 367 protocol Id, etc. 369 When sending user data with sendmsg(), the msg_name field in msghdr 370 structure will be filled with one of the transport addresses of the 371 intended receiver. If there is no association existing between the 372 sender and the intended receiver, the sender's SCTP stack will set 373 up a new association and then send the user data (see Section 3.2 374 for more on implicit association setup). 376 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 377 be delivered if that notification has been enabled, and no more data 378 can be sent to that association. Any attempt to send more data will 379 cause sendmsg() to return with an ESHUTDOWN error. Note that the 380 socket is still open for reading at this point so it is possible to 381 retrieve notifications. 383 When receiving a user message with recvmsg(), the msg_name field in 384 msghdr structure will be populated with the source transport address 385 of the user data. The caller of recvmsg() can use this address 386 information to determine to which association the received user 387 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 388 applications must use the peer transport address provided in the 389 msg_name field by recvmsg() to perform correlation to an 390 association, since they will not have the association ID. 392 If all data in a single message has been delivered, MSG_EOR will be 393 set in the msg_flags field of the msghdr structure (see section 394 5.1). 396 If the application does not provide enough buffer space to 397 completely receive a data message, MSG_EOR will not be set in 398 msg_flags. Successive reads will consume more of the same message 399 until the entire message has been delivered, and MSG_EOR will be 400 set. 402 If the SCTP stack is running low on buffers, it may partially 403 deliver a message. In this case, MSG_EOR will not be set, and more 404 calls to recvmsg() will be necessary to completely consume the 405 message. Only one message at a time can be partially delivered. 407 Note, if the socket is a branched-off socket that only represents 408 one association (see Section 3.1), the msg_name field is not used 409 when sending data (i.e., ignored by the SCTP stack). 411 3.1.5 close() - UDP Style Syntax 413 Applications use close() to perform graceful shutdown (as described 414 in Section 10.1 of [SCTP]) on ALL the associations currently 415 represented by a UDP-style socket. 417 The syntax is 419 ret = close(int sd); 421 sd - the socket descriptor of the associations to be closed. 423 To gracefully shutdown a specific association represented by the 424 UDP-style socket, an application should use the sendmsg() call, 425 passing no user data, but including the MSG_EOF flag in the 426 ancillary data (see Section 5.2.2). 428 If sd in the close() call is a branched-off socket representing only 429 one association, the shutdown is performed on that association only. 431 3.1.6 connect() - UDP Style Syntax 433 An application may use the connect() call in the UDP model to 434 initiate an association without sending data. 436 The syntax is 438 ret = connect(int sd, const struct sockaddr *nam, int len); 440 sd - the socket descriptor to have a new association added 441 to. 443 nam - the address structure (either struct sockaddr_in or struct 444 sockaddr_in6 defined in [RFC 2553]). 446 len - the size of the address. 448 3.2 Implicit Association Setup 450 Once all bind() calls are complete on a UDP-style socket, the 451 application can begin sending and receiving data using the 452 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 453 through any explicit association setup procedures (i.e., no 454 connect() calls required). 456 Whenever sendmsg() or sendto() is called and the SCTP stack at the 457 sender finds that there is no association existing between the 458 sender and the intended receiver (identified by the address passed 459 either in the msg_name field of msghdr structure in the sendmsg() 460 call or the dest_addr field in the sendto() call), the SCTP stack 461 will automatically setup an association to the intended receiver. 463 Upon the successful association setup a COMMUNICATION_UP 464 notification will be dispatched to the socket at both the sender and 465 receiver side. This notification can be read by the recvmsg() system 466 call (see Section 3.1.3). 468 Note, if the SCTP stack at the sender side supports bundling, the 469 first user message may be bundled with the COOKIE ECHO message 470 [SCTP]. 472 When the SCTP stack sets up a new association implicitly, it first 473 consults the sctp_initmsg structure, which is passed along within 474 the ancillary data in the sendmsg() call (see Section 5.2.1 for 475 details of the data structures), for any special options to be used 476 on the new association. 478 If this information is not present in the sendmsg() call, or if the 479 implicit association setup is triggered by a sendto() call, the 480 default association initialization parameters will be used. These 481 default association parameters may be set with respective 482 setsockopt() calls or be left to the system defaults. 484 Implicit association setup cannot be initiated by send()/recv() 485 calls. 487 3.3 Non-blocking mode 488 Some SCTP users might want to avoid blocking when they call 489 socket interface function. 491 Whenever the user which want to avoid blocking must call select() 492 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and 493 check the socket status is writable or readable. If the socket 494 status isn't writeable or readable, the user should not call 495 sendmsg()/sendto() and recvmsg()/recvfrom(). 497 Once all bind() calls are complete on a UDP-style socket, the 498 application must set the non-blocking option by a fcntl() (such as 499 O_NONBLOCK). After which the sendmsg() function returns 500 immediately, and the success or failure of the data message (and 501 possible SCTP_INITMSG parameters) will be signalled by the 502 SCTP_ASSOC_CHANGE event with COMMUNICATION_UP or 503 CANT_START_ASSOC. If user data could not be sent (due to a 504 CANT_START_ASSOC), the sender will also receive a SCTP_SEND_FAILED 505 event. Those event(s) can be received by the user calling of 506 recvmsg(). A server (having called listen()) is also notified of an 507 association up event by the reception of a SCTP_ASSOC_CHANGE with 508 COMMUNICATION_UP via the calling of recvmsg() and possibly the 509 reception of the first data message. 511 In order to shutdown the association gracefully, the user must call 512 sendmsg() with no data and with the MSG_EOF flag set. The function 513 returns immediately, and completion of the graceful shutdown is 514 indicated by an SCTP_ASSOC_CHANGE notification of type 515 SHUTDOWN_COMPLETE (see section 5.3.1.1). 517 4. TCP-style Interface 519 The goal of this model is to follow as closely as possible the 520 current practice of using the sockets interface for a connection 521 oriented protocol, such as TCP. This model enables existing 522 applications using connection oriented protocols to be ported to 523 SCTP with very little effort. 525 Note that some new SCTP features and some new SCTP socket options 526 can only be utilized through the use of sendmsg() and recvmsg() 527 calls, see Section 4.1.8. 529 4.1 Basic Operation 531 A typical server in TCP-style model uses the following system call 532 sequence to prepare an SCTP endpoint for servicing requests: 534 1. socket() 535 2. bind() 536 3. listen() 537 4. accept() 539 The accept() call blocks until a new association is set up. It 540 returns with a new socket descriptor. The server then uses the new 541 socket descriptor to communicate with the client, using recv() and 542 send() calls to get requests and send back responses. 544 Then it calls 546 5. close() 548 to terminate the association. 550 A typical client uses the following system call sequence to setup an 551 association with a server to request services: 553 1. socket() 554 2. connect() 556 After returning from connect(), the client uses send() and recv() 557 calls to send out requests and receive responses from the server. 559 The client calls 561 3. close() 563 to terminate this association when done. 565 4.1.1 socket() - TCP Style Syntax 567 Applications calls socket() to create a socket descriptor to 568 represent an SCTP endpoint. 570 The syntax is: 572 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 574 or, 576 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 578 Here, SOCK_STREAM indicates the creation of a TCP-style socket. 580 The first form creates an endpoint which can use only IPv4 581 addresses, while the second form creates an endpoint which can use 582 both IPv6 and mapped IPv4 addresses. 584 4.1.2 bind() - TCP Style Syntax 586 Applications use bind() to pass an address to be associated with an 587 SCTP endpoint to the system. bind() allows only either a single 588 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 589 endpoint can be associated with multiple addresses. To do this, 590 sctp_bindx() is introduced in section 8.1 to help applications do 591 the job of associating multiple addresses. 593 These addresses associated with a socket are the eligible transport 594 addresses for the endpoint to send and receive data. The endpoint 595 will also present these addresses to its peers during the 596 association initialization process, see [SCTP]. 598 The syntax is: 600 int bind(int sd, struct sockaddr *addr, int addrlen); 602 sd - the socket descriptor returned by socket() call. 603 addr - the address structure (either struct sockaddr_in or struct 604 sockaddr_in6 defined in [RFC 2553]). 605 addrlen - the size of the address structure. 607 If sd is an IPv4 socket, the address passed must be an IPv4 address. 608 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 609 either be an IPv4 or an IPv6 address. 611 Applications cannot call bind() multiple times to associate multiple 612 addresses to the endpoint. After the first call to bind(), all 613 subsequent calls will return an error. 615 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 616 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 617 operating system will associate the endpoint with an optimal address 618 set of the available interfaces. 620 If a bind() or sctp_bindx() is not called prior to the connect() 621 call, the system picks an ephemeral port and will choose an address 622 set equivalant to binding with a wildcard address. One of those 623 addresses will be the primary address for the association. This 624 automatically enables the multihoming capability of SCTP. 626 The completion of this bind() process does not ready the SCTP 627 endpoint to accept inbound SCTP association requests. Until a 628 listen() system call, described below, is performed on the socket, 629 the SCTP endpoint will promptly reject an inbound SCTP INIT request 630 with an SCTP ABORT. 632 4.1.3 listen() - TCP Style Syntax 634 Applications use listen() to ready the SCTP endpoint for accepting 635 inbound associations. 637 The syntax is: 639 int listen(int sd, int backlog); 641 sd - the socket descriptor of the SCTP endpoint. 642 backlog - this specifies the max number of outstanding associations 643 allowed in the socket's accept queue. These are the 644 associations that have finished the four-way initiation 645 handshake (see Section 5 of [SCTP]) and are in the 646 ESTABLISHED state. Note, a backlog of '0' indicates 647 that the caller no longer wishes to receive new 648 associations. 650 4.1.4 accept() - TCP Style Syntax 652 Applications use accept() call to remove an established SCTP 653 association from the accept queue of the endpoint. A new socket 654 descriptor will be returned from accept() to represent the newly 655 formed association. 657 The syntax is: 659 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 661 new_sd - the socket descriptor for the newly formed association. 662 sd - the listening socket descriptor. 663 addr - on return, will contain the primary address of the peer 664 endpoint. 665 addrlen - on return, will contain the size of addr. 667 4.1.5 connect() - TCP Style Syntax 669 Applications use connect() to initiate an association to a peer. 671 The syntax is 673 int connect(int sd, const struct sockaddr *addr, int addrlen); 675 sd - the socket descriptor of the endpoint. 676 addr - the peer's address. 677 addrlen - the size of the address. 679 This operation corresponds to the ASSOCIATE primitive described in 680 section 10.1 of [SCTP]. 682 By default, the new association created has only one outbound 683 stream. The SCTP_INITMSG option described in Section 7.1.3 should be 684 used before connecting to change the number of outbound streams. 686 If a bind() or sctp_bindx() is not called prior to the connect() 687 call, the system picks an ephemeral port and will choose an address 688 set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 689 and IPv6 socket respectively. One of those addresses will be the 690 primary address for the association. This automatically enables the 691 multihoming capability of SCTP. 693 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 694 during the association set up phase. If an application wants to do 695 this, it cannot use connect() call. Instead, it should use sendto() 696 or sendmsg() to initiate an association. If it uses sendto() and it 697 wants to change initialization behavior, it needs to use the 698 SCTP_INITMSG socket option before calling sendto(). Or it can use 699 SCTP_INIT type sendmsg() to initiate an association without doing 700 the setsockopt(). 702 SCTP does not support half close semantics. This means that unlike 703 T/TCP, MSG_EOF should not be set in the flags parameter when calling 704 sendto() or sendmsg() when the call is used to initiate a 705 connection. MSG_EOF is not an acceptable flag with SCTP socket. 707 4.1.6 close() - TCP Style Syntax 709 Applications use close() to gracefully close down an association. 711 The syntax is: 713 int close(int sd); 715 sd - the socket descriptor of the association to be closed. 717 After an application calls close() on a socket descriptor, no 718 further socket operations will suceed on that descriptor. 720 4.1.7 shutdown() - TCP Style Syntax 722 SCTP differs from TCP in that it does not have half closed 723 semantics. Hence the shutdown() call for SCTP is an approximation 724 of the TCP shutdown() call, and solves some different problems. 725 Full TCP-compatibility is not provided, so developers porting TCP 726 applications to SCTP may need to recode sections that use 727 shutdown(). (Note that it is possible to achieve the same results 728 as half close in SCTP using SCTP streams.) 730 The syntax is: 732 int shutdown(int socket, int how); 734 sd - the socket descriptor of the association to be closed. 736 how - Specifies the type of shutdown. The values are 737 as follows: 739 SHUT_RD 740 Disables further receive operations. No SCTP 741 protocol action is taken. 743 SHUT_WR 744 Disables further send operations, and initiates 745 the SCTP shutdown sequence. 747 SHUT_RDWR 748 Disables further send and receive operations 749 and initiates the SCTP shutdown sequence. 751 The major difference between SCTP and TCP shutdown() is that SCTP 752 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 753 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 754 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 755 the SCTP association while still leaving the socket descriptor open, 756 so that the caller can receive back any data SCTP was unable to 757 deliver (see section 5.3.1.4 for more information). 759 To perform the ABORT operation described in [SCTP] section 10.1, an 760 application can use the socket option SO_LINGER. It is described in 761 section 7.1.4. 763 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax 765 With a TCP-style socket, the application can also use sendmsg() and 766 recvmsg() to transmit data to and receive data from its peer. The 767 semantics is similar to those used in the UDP-style model (section 768 3.1.3), with the following differences: 770 1) When sending, the msg_name field in the msghdr is not used to 771 specify the intended receiver, rather it is used to indicate a 772 different peer address if the sender does not want to send the 773 message over the primary address of the receiver. If the transport 774 address given is not part of the current association, the data will 775 not be sent and a SCTP_SEND_FAILED event will be delivered to the 776 application if send failure events are enabled. 778 When receiving, if a message is not received from the primary 779 address, the SCTP stack will fill in the msg_name field on return so 780 that the application can retrieve the source address information of 781 the received message. 783 2) An application must use close() to gracefully shutdown an 784 association, or use SO_LINGER option with close() to abort an 785 association. It must not use the MSG_ABORT or MSG_EOF flag in 786 sendmsg(). The system returns an error if an application tries to 787 do so. 789 4.1.9 getpeername() 791 Applications use getpeername() to retrieve the primary socket 792 address of the peer. This call is for TCP compatibility, and is not 793 multihomed.It does not work with UDP-style sockets. See section 8.3 794 for a multihomed/UDP-sockets version of the call. 796 The syntax is: 798 int getpeername(int socket, struct sockaddr *address, 799 socklen_t *len); 801 sd - the socket descriptor to be queried. 803 address - On return, the peer primary address is stored in 804 this buffer. If the socket is an IPv4 socket, the 805 address will be IPv4. If the socket is an IPv6 socket, 806 the address will be either an IPv6 or mapped IPv4 807 address. 809 len - The caller should set the length of address here. 810 On return, this is set to the length of the returned 811 address. 813 If the actual length of the address is greater than the length of 814 the supplied sockaddr structure, the stored address will be 815 truncated. 817 5. Data Structures 819 We discuss in this section important data structures which are 820 specific to SCTP and are used with sendmsg() and recvmsg() calls to 821 control SCTP endpoint operations and to access ancillary 822 information and notifications. 824 5.1 The msghdr and cmsghdr Structures 826 The msghdr structure used in the sendmsg() and recvmsg() calls, as 827 well as the ancillary data carried in the structure, is the key for 828 the application to set and get various control information from the 829 SCTP endpoint. 831 The msghdr and the related cmsghdr structures are defined and 832 discussed in details in [RFC2292]. Here we will cite their 833 definitions from [RFC2292]. 835 The msghdr structure: 837 struct msghdr { 838 void *msg_name; /* ptr to socket address structure */ 839 socklen_t msg_namelen; /* size of socket address structure */ 840 struct iovec *msg_iov; /* scatter/gather array */ 841 size_t msg_iovlen; /* # elements in msg_iov */ 842 void *msg_control; /* ancillary data */ 843 socklen_t msg_controllen; /* ancillary data buffer length */ 844 int msg_flags; /* flags on received message */ 845 }; 847 The cmsghdr structure: 849 struct cmsghdr { 850 socklen_t cmsg_len; /* #bytes, including this header */ 851 int cmsg_level; /* originating protocol */ 852 int cmsg_type; /* protocol-specific type */ 853 /* followed by unsigned char cmsg_data[]; */ 854 }; 856 In the msghdr structure, the usage of msg_name has been discussed in 857 previous sections (see Sections 3.1.3 and 4.1.8). 859 The scatter/gather buffers, or I/O vectors (pointed to by the 860 msg_iov field) are treated as a single SCTP data chunk, rather than 861 multiple chunks, for both sendmsg() and recvmsg(). 863 The msg_flags are not used when sending a message with sendmsg(). 865 If a notification has arrived, recvmsg() will return the 866 notification with the MSG_NOTIFICATION flag set in msg_flags. If the 867 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 868 section 5.3 for more information about notifications. 870 If all portions of a data frame or notification have been read, 871 recvmsg() will return with MSG_EOR set in msg_flags. 873 5.2 SCTP msg_control Structures 875 A key element of all SCTP-specific socket extensions is the use of 876 ancillary data to specify and access SCTP-specific data via the 877 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 878 Fine-grained control over initialization and sending parameters are 879 handled with ancillary data. 881 Each ancillary data item is preceeded by a struct cmsghdr (see 882 Section 5.1), which defines the function and purpose of the data 883 contained in in the cmsg_data[] member. 885 There are two kinds of ancillary data used by SCTP: initialization 886 data, and, header information (SNDRCV). Initialization data 887 (UDP-style only) sets protocol parameters for new associations. 888 Section 5.2.1 provides more details. Header information can set or 889 report parameters on individual messages in a stream. See section 890 5.2.2 for how to use SNDRCV ancillary data. 892 By default on a TCP-style socket, SCTP will pass no ancillary data; 893 on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and 894 SCTP_ASSOC_CHANGE information. Specific ancillary data items can be 895 enabled with socket options defined for SCTP; see section 7.3. 897 Note that all ancillary types are fixed length; see section 5.4 for 898 further discussion on this. These data structures use struct 899 sockaddr_storage (defined in [RFC2553]) as a portable, fixed length 900 address format. 902 Other protocols may also provide ancillary data to the socket layer 903 consumer. These ancillary data items from other protocols may 904 intermingle with SCTP data. For example, the IPv6 socket API 905 definitions ([RFC2292] and [RFC2553]) define a number of ancillary 906 data items. If a socket API consumer enables delivery of both SCTP 907 and IPv6 ancillary data, they both may appear in the same 908 msg_control buffer in any order. An application may thus need to 909 handle other types of ancillary data besides that passed by SCTP. 911 The sockets application must provide a buffer large enough to 912 accomodate all ancillary data provided via recvmsg(). If the buffer 913 is not large enough, the ancillary data will be truncated and the 914 msghdr's msg_flags will include MSG_CTRUNC. 916 5.2.1 SCTP Initiation Structure (SCTP_INIT) 918 This cmsghdr structure provides information for initializing new 919 SCTP associations with sendmsg(). The SCTP_INITMSG socket option 920 uses this same data structure. This structure is not used for 921 recvmsg(). 923 cmsg_level cmsg_type cmsg_data[] 924 ------------ ------------ ---------------------- 925 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 927 Here is the definition of the sctp_initmsg structure: 929 struct sctp_initmsg { 930 uint16_t sinit_num_ostreams; 931 uint16_t sinit_max_instreams; 932 uint16_t sinit_max_attempts; 933 uint16_t sinit_max_init_timeo; 934 }; 936 sinit_num_ostreams: 16 bits (unsigned integer) 938 This is an integer number representing the number of streams that 939 the application wishes to be able to send to. This number is 940 confirmed in the COMMUNICATION_UP notification and must be verified 941 since it is a negotiated number with the remote endpoint. The 942 default value of 0 indicates to use the endpoint default value. 944 sinit_max_instreams: 16 bits (unsigned integer) 946 This value represents the maximum number of inbound streams the 947 application is prepared to support. This value is bounded by the 948 actual implementation. In other words the user MAY be able to 949 support more streams than the Operating System. In such a case, the 950 Operating System limit overrides the value requested by the 951 user. The default value of 0 indicates to use the endpoint's default 952 value. 954 sinit_max_attempts: 16 bits (unsigned integer) 956 This integer specifies how many attempts the SCTP endpoint should 957 make at resending the INIT. This value overrides the system SCTP 958 'Max.Init.Retransmits' value. The default value of 0 indicates to 959 use the endpoint's default value. This is normally set to the 960 system's default 'Max.Init.Retransmit' value. 962 sinit_max_init_timeo: 16 bits (unsigned integer) 964 This value represents the largest Time-Out or RTO value to use in 965 attempting a INIT. Normally the 'RTO.Max' is used to limit the 966 doubling of the RTO upon timeout. For the INIT message this value 967 MAY override 'RTO.Max'. This value MUST NOT influence 'RTO.Max' 968 during data transmission and is only used to bound the initial setup 969 time. A default value of 0 indicates to use the endpoint's default 970 value. This is normally set to the system's 'RTO.Max' value (60 971 seconds). 973 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 975 This cmsghdr structure specifies SCTP options for sendmsg() and 976 describes SCTP header information about a received message through 977 recvmsg(). 979 cmsg_level cmsg_type cmsg_data[] 980 ------------ ------------ ---------------------- 981 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 983 Here is the defintion of sctp_sndrcvinfo: 985 struct sctp_sndrcvinfo { 986 uint16_t sinfo_stream; 987 uint16_t sinfo_ssn; 988 uint16_t sinfo_flags; 989 uint32_t sinfo_ppid; 990 uint32_t sinfo_context; 991 uint32_t sinfo_timetolive; 992 uint32_t sinfo_tsn; 993 sctp_assoc_t sinfo_assoc_id; 994 }; 996 sinfo_stream: 16 bits (unsigned integer) 998 For recvmsg() the SCTP stack places the message's stream number in 999 this value. For sendmsg() this value holds the stream number that 1000 the application wishes to send this message to. If a sender 1001 specifies an invalid stream number an error indication is returned 1002 and the call fails. 1004 sinfo_ssn: 16 bits (unsigned integer) 1006 For recvmsg() this value contains the stream sequence number that 1007 the remote endpoint placed in the DATA chunk. For fragmented 1008 messages this is the same number for all deliveries of the message 1009 (if more than one recvmsg() is needed to read the message). The 1010 sendmsg() call will ignore this parameter. 1012 sinfo_ppid: 32 bits (unsigned integer) 1014 This value in sendmsg() is an opaque unsigned value that is passed 1015 to the remote end in each user message. In recvmsg() this value is 1016 the same information that was passed by the upper layer in the peer 1017 application. Please note that byte order issues are NOT accounted 1018 for and this information is passed opaquely by the SCTP stack from 1019 one end to the other. 1021 sinfo_context: 32 bits (unsigned integer) 1023 This value is an opaque 32 bit context datum that is used in the 1024 sendmsg() function. This value is passed back to the upper layer if 1025 a error occurs on the send of a message and is retrieved with each 1026 undelivered message (Note: if a endpoint has done multple sends, all 1027 of which fail, multiple different sinfo_context values will be 1028 returned. One with each user data message). 1030 sinfo_flags: 16 bits (unsigned integer) 1032 This field may contain any of the following flags and is composed of 1033 a bitwise OR of these values. 1035 recvmsg() flags: 1037 MSG_UNORDERED - This flag is present when the message was sent 1038 non-ordered. 1040 sendmsg() flags: 1042 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1043 message. If this flag is clear the datagram is 1044 considered an ordered send. 1046 MSG_ADDR_OVER - This flag, in the UDP model, requests the SCTP 1047 stack to override the primary destination address 1048 with the address found with the sendto/sendmsg 1049 call. 1051 MSG_ABORT - Setting this flag causes the specified association 1052 to abort by sending an ABORT message to the peer 1053 (UDP-style only). 1055 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1056 procedures on the specified association. Graceful 1057 shutdown assures that all data enqueued by both 1058 endpoints is successfully transmitted before closing 1059 the association (UDP-style only). 1061 sinfo_timetolive: 32 bit (unsigned integer) 1063 For the sending side, this field contains the message time 1064 to live in milliseconds. The sending side wil expire the 1065 message within the specified time period if the message as 1066 not been sent to the peer within this time period. 1068 sinfo_tsn: 32 bit (unsigned integer) 1070 For the receiving side, this field holds a TSN that was 1071 assigned to one of the SCTP Data Chunks. 1073 sinfo_assoc_id: sizeof (sctp_assoc_t) 1075 The association handle field, sinfo_assoc_id, holds the identifier 1076 for the association announced in the COMMUNICATION_UP notification. 1077 All notifications for a given association have the same identifier. 1078 Ignored for TCP-style sockets. 1080 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1082 5.3 SCTP Events and Notifications 1084 An SCTP application may need to understand and process events and 1085 errors that happen on the SCTP stack. These events include network 1086 status changes, association startups, remote operational errors and 1087 undeliverable messages. All of these can be essential for the 1088 application. 1090 When an SCTP application layer does a recvmsg() the message read is 1091 normally a data message from a peer endpoint. If the application 1092 wishes to have the SCTP stack deliver notifications of non-data 1093 events, it sets the appropriate socket option for the notifications 1094 it wants. See section 7.3 for these socket options. When a 1095 notification arrives, recvmsg() returns the notification in the 1096 application-supplied data buffer via msg_iov, and sets 1097 MSG_NOTIFICATION in msg_flags. 1099 Multiple notifications may be returned to a single recvmsg() 1100 call. 1102 This section details the notification structures. Every 1103 notification structure carries some common fields which provides 1104 general information. 1106 A recvmsg() call will return only one notification at a time. Just 1107 as when reading normal data, it may return part of a notification if 1108 the msg_iov buffer is not large enough. If a single read is not 1109 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1110 reading the notification before subsequent data can arrive. 1112 5.3.1 SCTP Notification Structure 1114 The notification structure is defined as the union of all 1115 notification types. 1117 union sctp_notification { 1118 struct { 1119 uint16_t sn_type; /* Notification type. */ 1120 uint16_t sn_flags; 1121 uint32_t sn_length; 1122 } h; 1123 struct sctp_assoc_change sn_assoc_change; 1124 struct sctp_paddr_change sn_padr_change; 1125 struct sctp_remote_error sn_remote_error; 1126 struct sctp_send_failed sn_send_failed; 1127 struct sctp_shutdown_event sn_shutdown_event; 1128 struct sctp_adaption_event sn_adaption_event; 1129 struct sctp_rcv_pdapi_event sn_rcv_pdapi_event; 1130 }; 1132 sn_type: 16 bits (unsigned integer) 1133 The following table describes the SCTP notification and event types 1134 for the field sn_type. 1136 sn_type Description 1137 --------- --------------------------- 1139 SCTP_ASSOC_CHANGE This tag indicates that an 1140 association has either been 1141 opened or closed. Refer to 1142 5.3.1.1 for details. 1144 SCTP_PEER_ADDR_CHANGE This tag indicates that an 1145 address that is part of an existing 1146 association has experienced a 1147 change of state (e.g. a failure 1148 or return to service of the 1149 reachability of a endpoint 1150 via a specific transport 1151 address). Please see 5.3.1.2 1152 for data structure details. 1154 SCTP_REMOTE_ERROR The attached error message 1155 is an Operational Error received from 1156 the remote peer. It includes the complete 1157 TLV sent by the remote endpoint. 1158 See section 5.3.1.3 for the detailed format. 1160 SCTP_SEND_FAILED The attached datagram 1161 could not be sent to the remote endpoint. 1162 This structure includes the 1163 original SCTP_SNDRCVINFO 1164 that was used in sending this 1165 message i.e. this structure 1166 uses the sctp_sndrecvinfo per 1167 section 5.3.1.4. 1169 SCTP_SHUTDOWN_EVENT The peer has sent a SHUTDOWN. No further 1170 data should be sent on this socket. 1172 SCTP_ADAPTION_INDICATION This notification holds the 1173 peers indicated adaption layer. 1174 Please see 5.3.1.6. 1176 SCTP_PARTIAL_DELIVERY_EVENT This notitifcation is used to 1177 tell a receiver that the partial 1178 delivery has been aborted. This 1179 may indicate the association is 1180 about to be aborted. Please see 1181 5.3.1.7. 1183 All standard values for sn_type flags are greater than 2^15. 1184 Values from 2^15 and down are reserved. 1186 sn_flags: 16 bits (unsigned integer) 1188 These are notification-specific flags. 1190 sn_length: 32 bits (unsigned integer) 1192 This is the length of the whole sctp_notification structure 1193 including the sn_type, sn_flags, and sn_length fields. 1195 5.3.1.1 SCTP_ASSOC_CHANGE 1197 Communication notifications inform the ULP that an SCTP association 1198 has either begun or ended. The identifier for a new association is 1199 provided by this notificaion. The notification information has the 1200 following format: 1202 struct sctp_assoc_change { 1203 uint16_t sac_type; 1204 uint16_t sac_flags; 1205 uint32_t sac_length; 1206 uint16_t sac_state; 1207 uint16_t sac_error; 1208 uint16_t sac_outbound_streams; 1209 uint16_t sac_inbound_streams; 1210 sctp_assoc_t sac_assoc_id; 1211 }; 1213 sac_type: 1215 It should be SCTP_ASSOC_CHANGE. 1217 sac_flags: 16 bits (unsigned integer) 1219 Currently unused. 1221 sac_length: 32 bits (unsigned integer) 1223 This field is the total length of the notification data, including 1224 the notification header. 1226 sac_state: 32 bits (signed integer) 1228 This field holds one of a number of values that communicate the 1229 event that happened to the association. They include: 1231 Event Name Description 1232 ---------------- --------------- 1233 COMMUNICATION_UP A new association is now ready 1234 and data may be exchanged with this 1235 peer. 1237 COMMUNICATION_LOST The association has failed. The association 1238 is now in the closed state. If SEND FAILED 1240 notifications are turned on, a COMMUNICATION_LOST 1241 is followed by a series of SCTP_SEND_FAILED 1242 events, one for each outstanding message. 1244 RESTART SCTP has detected that the peer has restarted. 1246 SHUTDOWN_COMPLETE The association has gracefully closed. 1248 CANT_START_ASSOC The association failed to setup. If non blocking 1249 mode is set and data was sent (in the udp mode), 1250 a CANT_START_ASSOC is followed by a series of 1251 SCTP_SEND_FAILED events, one for each outstanding 1252 message. 1254 sac_error: 32 bits (signed integer) 1256 If the state was reached due to a error condition (e.g. 1257 COMMUNICATION_LOST) any relevant error information is available in 1258 this field. This corresponds to the protocol error codes defined in 1259 [SCTP]. 1261 sac_outbound_streams: 16 bits (unsigned integer) 1262 sac_inbound_streams: 16 bits (unsigned integer) 1264 The maximum number of streams allowed in each direction are 1265 available in sac_outbound_streams and sac_inbound streams. 1267 sac_assoc_id: sizeof (sctp_assoc_t) 1269 The association id field, holds the identifier for the association. 1270 All notifications for a given association have the same association 1271 identifier. For TCP style socket, this field is ignored. 1273 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1275 When a destination address on a multi-homed peer encounters a change 1276 an interface details event is sent. The information has the 1277 following structure: 1279 struct sctp_paddr_change { 1280 uint16_t spc_type; 1281 uint16_t spc_flags; 1282 uint32_t spc_length; 1283 struct sockaddr_storage spc_aaddr; 1284 int spc_state; 1285 int spc_error; 1286 sctp_assoc_t spc_assoc_id; 1287 } 1289 spc_type: 1291 It should be SCTP_PEER_ADDR_CHANGE. 1293 spc_flags: 16 bits (unsigned integer) 1294 Currently unused. 1296 spc_length: 32 bits (unsigned integer) 1298 This field is the total length of the notification data, including 1299 the notification header. 1301 spc_aaddr: sizeof (struct sockaddr_storage) 1303 The affected address field, holds the remote peer's address that is 1304 encountering the change of state. 1306 spc_state: 32 bits (signed integer) 1308 This field holds one of a number of values that communicate the 1309 event that happened to the address. They include: 1311 Event Name Description 1312 ---------------- --------------- 1313 ADDRESS_AVAILABLE This address is now reachable. 1315 ADDRESS_UNREACHABLE The address specified can no 1316 longer be reached. Any data sent 1317 to this address is rerouted to an 1318 alternate until this address becomes 1319 reachable. 1321 ADDRESS_REMOVED The address is no longer part of 1322 the association. 1324 ADDRESS_ADDED The address is now part of the 1325 association. 1327 ADDRESS_MADE_PRIM This address has now been made 1328 to be the primary destination address. 1330 spc_error: 32 bits (signed integer) 1332 If the state was reached due to any error condition (e.g. 1333 ADDRESS_UNREACHABLE) any relevant error information is available in 1334 this field. 1336 spc_assoc_id: sizeof (sctp_assoc_t) 1338 The association id field, holds the identifier for the association. 1339 All notifications for a given association have the same association 1340 identifier. For TCP style socket, this field is ignored. 1342 5.3.1.3 SCTP_REMOTE_ERROR 1344 A remote peer may send an Operational Error message to its peer. 1345 This message indicates a variety of error conditions on an 1346 association. The entire error TLV as it appears on the wire is 1347 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1348 specification [SCTP] and any extensions for a list of possible 1349 error formats. SCTP error TLVs have the format: 1351 struct sctp_remote_error { 1352 uint16_t sre_type; 1353 uint16_t sre_flags; 1354 uint32_t sre_length; 1355 uint16_t sre_error; 1356 sctp_assoc_t sre_assoc_id; 1357 uint8_t sre_data[0]; 1358 }; 1360 sre_type: 1362 It should be SCTP_REMOTE_ERROR. 1364 sre_flags: 16 bits (unsigned integer) 1366 Currently unused. 1368 sre_length: 32 bits (unsigned integer) 1370 This field is the total length of the notification data, including 1371 the notification header and the contents of sre_data. 1373 sre_error: 16 bits (unsigned integer) 1375 This value represents one of the Operational Error causes defined in 1376 the SCTP specification, in network byte order. 1378 sre_assoc_id: sizeof (sctp_assoc_t) 1380 The association id field, holds the identifier for the association. 1381 All notifications for a given association have the same association 1382 identifier. For TCP style socket, this field is ignored. 1384 sre_data: variable 1386 This contains the payload of the operational error as defined in the 1387 SCTP specification [SCTP] section 3.3.10. 1389 5.3.1.4 SCTP_SEND_FAILED 1391 If SCTP cannot deliver a message it may return the message as a 1392 notification. 1394 struct sctp_send_failed { 1395 uint16_t ssf_type; 1396 uint16_t ssf_flags; 1397 uint32_t ssf_length; 1398 uint32_t ssf_error; 1399 struct sctp_sndrcvinfo ssf_info; 1400 sctp_assoc_t ssf_assoc_id; 1401 uint8_t ssf_data[0]; 1402 }; 1404 ssf_type: 1406 It should be SCTP_SEND_FAILED. 1408 ssf_flags: 16 bits (unsigned integer) 1410 The flag value will take one of the following values 1412 SCTP_DATA_UNSENT - Indicates that the data was never put on 1413 the wire. 1415 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1416 Note that this does not necessarily mean that the 1417 data was (or was not) successfully delivered. 1419 ssf_length: 32 bits (unsigned integer) 1421 This field is the total length of the notification data, including 1422 the notification header and the payload in ssf_data. 1424 ssf_error: 16 bits (unsigned integer) 1426 This value represents the reason why the send failed, and if set, 1427 will be a SCTP protocol error code as defined in [SCTP] section 1428 3.3.10. 1430 ssf_info: sizeof (struct sctp_sndrcvinfo) 1432 The original send information associated with the undelivered 1433 message. 1435 ssf_assoc_id: sizeof (sctp_assoc_t) 1437 The association id field, sf_assoc_id, holds the identifier for the 1438 association. All notifications for a given association have the 1439 same association identifier. For TCP style socket, this field is 1440 ignored. 1442 ssf_data: variable length 1444 The undelivered message, exactly as delivered by the caller to the 1445 original send*() call. 1447 5.3.1.5 SCTP_SHUTDOWN_EVENT 1449 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1450 inform the application that it should cease sending data. 1452 struct sctp_shutdown_event { 1453 uint16_t sse_type; 1455 uint16_t sse_flags; 1456 uint32_t sse_length; 1457 sctp_assoc_t sse_assoc_id; 1458 }; 1460 sse_type 1462 It should be SCTP_SHUTDOWN_EVENT 1464 sse_flags: 16 bits (unsigned integer) 1466 Currently unused. 1468 sse_length: 32 bits (unsigned integer) 1470 This field is the total length of the notification data, including 1471 the notification header. It will generally be 1472 sizeof (struct sctp_shutdown_event). 1474 sse_flags: 16 bits (unsigned integer) 1476 Currently unused. 1478 sse_assoc_id: sizeof (sctp_assoc_t) 1480 The association id field, holds the identifier for the association. 1481 All notifications for a given association have the same association 1482 identifier. For TCP style socket, this field is ignored. 1484 5.3.1.6 SCTP_ADAPTION_INDICATION 1486 When a peer sends a Adaption Layer Indication parameter , SCTP 1487 delivers this notification to inform the application 1488 that of the peers requested adaption layer. 1490 struct sctp_adaption_event { 1491 uint16_t sai_type; 1492 uint16_t sai_flags; 1493 uint32_t sai_length; 1494 uint32_t sai_adaptation_bits; 1495 sctp_assoc_t sse_assoc_id; 1496 }; 1498 sai_type 1500 It should be SCTP_ADAPTION_INDICATION 1502 sai_flags: 16 bits (unsigned integer) 1504 Currently unused. 1506 sai_length: 32 bits (unsigned integer) 1507 This field is the total length of the notification data, including 1508 the notification header. It will generally be 1509 sizeof (struct sctp_adaption_event). 1511 sai_adaption_bits: 32 bits (unsigned integer) 1513 This field holds the bit array sent by the peer in the 1514 adaption layer indication parameter. The bits are in 1515 network byte order. 1517 sai_assoc_id: sizeof (sctp_assoc_t) 1519 The association id field, holds the identifier for the association. 1520 All notifications for a given association have the same association 1521 identifier. For TCP style socket, this field is ignored. 1523 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT 1525 When a reciever is engaged in a partial delivery of a 1526 message this notification will be used to inidicate 1527 various events. 1529 struct sctp_rcv_pdapi_event { 1530 uint16_t pdapi_type; 1531 uint16_t pdapi_flags; 1532 uint32_t pdapi_length; 1533 uint32_t pdapi_indication; 1534 sctp_assoc_t pdapi_assoc_id; 1535 }; 1537 pdapi_type 1539 It should be SCTP_ADAPTION_INDICATION 1541 pdapi_flags: 16 bits (unsigned integer) 1543 Currently unused. 1545 pdapi_length: 32 bits (unsigned integer) 1547 This field is the total length of the notification data, including 1548 the notification header. It will generally be 1549 sizeof (struct sctp_rcv_pdapi_event). 1551 pdapi_indication: 32 bits (unsigned integer) 1553 This field holds the indication being sent to the 1554 application possible values include: 1556 SCTP_PARTIAL_DELIVERY_ABORTED 1558 pdapi_assoc_id: sizeof (sctp_assoc_t) 1560 The association id field, holds the identifier for the association. 1562 All notifications for a given association have the same association 1563 identifier. For TCP style socket, this field is ignored. 1565 5.4 Ancillary Data Considerations and Semantics 1567 Programming with ancillary socket data contains some subtleties and 1568 pitfalls, which are discussed below. 1570 5.4.1 Multiple Items and Ordering 1572 Multiple ancillary data items may be included in any call to 1573 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1574 items, or both. 1576 The ordering of ancillary data items (either by SCTP or another 1577 protocol) is not significant and is implementation-dependant, so 1578 applications must not depend on any ordering. 1580 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1581 msg_iov member. There can be only a single SCTP_SNDRCV info for 1582 each sendmsg() or recvmsg() call. 1584 5.4.2 Accessing and Manipulating Ancillary Data 1586 Applications can infer the presence of data or ancillary data by 1587 examining the msg_iovlen and msg_controllen msghdr members, 1588 respectively. 1590 Implementations may have different padding requirements for 1591 ancillary data, so portable applications should make use of the 1592 macros CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and 1593 CMSG_LEN. See [RFC2292] and your SCTP implementation's documentation 1594 for more information. Following is an example, from [RFC2292], 1595 demonstrating the use of these macros to access ancillary data: 1597 struct msghdr msg; 1598 struct cmsghdr *cmsgptr; 1600 /* fill in msg */ 1602 /* call recvmsg() */ 1604 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1605 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1606 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1607 u_char *ptr; 1609 ptr = CMSG_DATA(cmsgptr); 1610 /* process data pointed to by ptr */ 1611 } 1612 } 1614 5.4.3 Control Message Buffer Sizing 1615 The information conveyed via SCTP_SNDRCV events will often be 1616 fundamental to the correct and sane operation of the sockets 1617 application. This is particularly true of the UDP semantics, but 1618 also of the TCP semantics. For example, if an application needs to 1619 send and receive data on different SCTP streams, SCTP_SNDRCV events 1620 are indispensable. 1622 Given that some ancillary data is critical, and that multiple 1623 ancillary data items may appear in any order, applications should be 1624 carefully written to always provide a large enough buffer to contain 1625 all possible ancillary data that can be presented by recvmsg(). If 1626 the buffer is too small, and crucial data is truncated, it may pose 1627 a fatal error condition. 1629 Thus it is essential that applications be able to deterministically 1630 calculate the maximum required buffer size to pass to recvmsg(). One 1631 constraint imposed on this specification that makes this possible is 1632 that all ancillary data definitions are of a fixed length. One way 1633 to calculate the maximum required buffer size might be to take the 1634 sum the sizes of all enabled ancillary data item structures, as 1635 calculated by CMSG_SPACE. For example, if we enabled 1636 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC2292], we would calculate 1637 and allocate the buffer size as follows: 1639 size_t total; 1640 void *buf; 1642 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1643 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1645 buf = malloc(total); 1647 We could then use this buffer for msg_control on each call to 1648 recvmsg() and be assured that we would not lose any ancillary data 1649 to truncation. 1651 6. Common Operations for Both Styles 1653 6.1 send(), recv(), sendto(), recvfrom() 1655 Applications can use send() and sendto() to transmit data to the 1656 peer of an SCTP endpoint. recv() and recvfrom() can be used to 1657 receive data from the peer. 1659 The syntax is: 1661 ssize_t send(int sd, connst void *msg, size_t len, int flags); 1662 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1663 const struct sockaddr *to, int tolen); 1664 ssize_t recv(int sd, void *buf, size_t len, int flags); 1665 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1666 struct sockaddr *from, int *fromlen); 1668 sd - the socket descriptor of an SCTP endpoint. 1669 msg - the message to be sent. 1670 len - the size of the message or the size of buffer. 1671 to - one of the peer addresses of the association to be 1672 used to send the message. 1673 tolen - the size of the address. 1674 buf - the buffer to store a received message. 1675 from - the buffer to store the peer address used to send the 1676 received message. 1677 fromlen - the size of the from address 1678 flags - (described below). 1680 These calls give access to only basic SCTP protocol features. If 1681 either peer in the association uses multiple streams, or sends 1682 unordered data these calls will usually be inadequate, and may 1683 deliver the data in unpredictable ways. 1685 SCTP has the concept of multiple streams in one association. The 1686 above calls do not allow the caller to specify on which stream a 1687 message should be sent. The system uses stream 0 as the default 1688 stream for send() and sendto(). recv() and recvfrom() return data 1689 from any stream, but the caller can not distinguish the different 1690 streams. This may result in data seeming to arrive out of 1691 order. Similarly, if a data chunk is sent unordered, recv() and 1692 recvfrom() provide no indication. 1694 SCTP is message based. The msg buffer above in send() and sendto() 1695 is considered to be a single message. This means that if the caller 1696 wants to send a message which is composed by several buffers, the 1697 caller needs to combine them before calling send() or sendto(). 1698 Alternately, the caller can use sendmsg() to do that without 1699 combining them. recv() and recvfrom() cannot distinguish message 1700 boundaries. 1702 In receiving, if the buffer supplied is not large enough to hold a 1703 complete message, the receive call acts like a stream socket and 1704 returns as much data as will fit in the buffer. 1706 Note, the send and recv calls, when used in the UDP-style model, may 1707 only be used with branched off socket descriptors (see Section 8.2). 1709 Note, if an application calls a send function with no user data 1710 and no ancillary data the SCTP implementation should reject the 1711 request with an appropriate error message. An implementation is 1712 NOT allowed to send a Data chunk with no user data [RFC2960]. 1714 6.2 setsockopt(), getsockopt() 1716 Applications use setsockopt() and getsockopt() to set or retrieve 1717 socket options. Socket options are used to change the default 1718 behavior of sockets calls. They are described in Section 7. 1720 The syntax is: 1722 ret = getsockopt(int sd, int level, int optname, void *optval, 1723 size_t *optlen); 1724 ret = setsockopt(int sd, int level, int optname, const void *optval, 1725 size_t optlen); 1727 sd - the socket descript. 1728 level - set to IPPROTO_SCTP for all SCTP options. 1729 optname - the option name. 1730 optval - the buffer to store the value of the option. 1731 optlen - the size of the buffer (or the length of the option 1732 returned). 1734 6.3 read() and write() 1736 Applications can use read() and write() to send and receive data to 1737 and from peer. They have the same semantics as send() and recv() 1738 except that the flags parameter cannot be used. 1740 Note, these calls, when used in the UDP-style model, may only be 1741 used with branched off socket descriptors (see Section 8.2). 1743 6.4 getsockname() 1745 Applications use getsockname() to retrieve the locally-bound socket 1746 address of the specified socket. This is especially useful if the 1747 caller let SCTP chose a local port. This call is for where the 1748 endpoint is not multihomed. It does not work well with multi-homed 1749 sockets. See section 8.5 for a multihomed version of the call. 1751 The syntax is: 1753 int getsockname(int socket, struct sockaddr *address, 1754 socklen_t *len); 1756 sd - the socket descriptor to be queried. 1758 address - On return, one locally bound address (chosen by 1759 the SCTP stack) is stored in this buffer. If the 1760 socket is an IPv4 socket, the address will be IPv4. 1761 If the socket is an IPv6 socket, the address will 1762 be either an IPv6 or mapped IPv4 address. 1764 len - The caller should set the length of address here. 1765 On return, this is set to the length of the returned 1766 address. 1768 If the actual length of the address is greater than the length of 1769 the supplied sockaddr structure, the stored address will be 1770 truncated. 1772 If the socket has not been bound to a local name, the value stored 1773 in the object pointed to by address is unspecified. 1775 7. Socket Options 1776 The following sub-section describes various SCTP level socket 1777 options that are common to both models. SCTP associations can be 1778 multihomed. Therefore, certain option parameters include a 1779 sockaddr_storage structure to select which peer address the option 1780 should be applied to. 1782 For the UDP-style sockets, an sctp_assoc_t structure (association 1783 ID) is used to identify the the association instance that the 1784 operation affects. So it must be set when using this model. 1786 For the TCP-style sockets and branched off UDP-style sockets (see 1787 section 8.2) this association ID parameter is ignored. In the cases 1788 noted below where the parameter is ignored, an application can pass 1789 to the system a corresponding option structure similar to those 1790 described below but without the association ID parameter, which 1791 should be the last field of the option structure. This can make the 1792 option setting/getting operation more efficient. If an application 1793 does this, it should also specify an appropriate optlen value 1794 (i.e. sizeof (option parameter) - sizeof (struct sctp_assoc_t)). 1796 Note that socket or IP level options is set or retrieved per socket. 1797 This means that for UDP-style sockets, those options will be applied 1798 to all associations belonging to the socket. And for TCP-style 1799 model, those options will be applied to all peer addresses of the 1800 association controlled by the socket. Applications should be very 1801 careful in setting those options. 1803 sctp_opt_info() 1805 For some implementations getsockopt() is read-only, so a new 1806 interface will be needed when information must be passed both in 1807 to and out of the SCTP stack. The syntax for scpt_opt_info() is, 1809 int sctp_opt_info(int sd, 1810 sctp_assoc_t id, 1811 int opt, 1812 void *arg, 1813 size_t *size); 1815 For UDP-style sockets, id specifies the association to query. For 1816 TCP-style sockets, id is ignored. 1818 opt specifies which SCTP socket option to get. It can 1819 any socket option currently supported that requests information 1820 (either read/write options or read only) such as: 1822 SCTP_RTOINFO 1823 SCTP_ASSOCINFO 1824 SCTP_SET_PRIMARY_ADDR 1825 SCTP_SET_PEER_PRIMARY_ADDR 1826 SCTP_SET_STREAM_TIMEOUTS 1827 SCTP_SET_PEER_ADDR_PARAMS 1828 SCTP_GET_PEER_ADDR_PARAMS 1829 SCTP_STATUS 1830 SCTP_GET_PEER_ADDR_INFO 1832 arg is an option-specific structure buffer provided by the caller. 1833 See 8.5 subsections for more information on these options and 1834 option-specific structures. 1836 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1837 sets errno to the appropriate error code. 1839 For those implementations that DO support a read/write 1840 getsocketopt interface a simple macro wrapper can be 1841 created to support the sctp_opt_info() interface such as: 1843 #define sctp_opt_info(fd,asoc,opt,arg,sz) \ 1844 do { \ 1845 if((opt == SCTP_RTOINFO) || \ 1846 (opt == SCTP_ASSOCINFO) || \ 1847 (opt == SCTP_SET_PRIMARY_ADDR) || \ 1848 (opt == SCTP_SET_PEER_PRIMARY_ADDR) || \ 1849 (opt == SCTP_SET_STREAM_TIMEOUTS) || \ 1850 (opt == SCTP_SET_PEER_ADDR_PARAMS) || \ 1851 (opt == SCTP_GET_PEER_ADDR_PARAMS) || \ 1852 (opt == SCTP_STATUS) || \ 1853 (opt == SCTP_GET_PEER_ADDR_INFO)){ \ 1854 *(sctp_assoc_t *)arg = asoc; \ 1855 return(getsockopt(fd,IPPROTO_SCTP,opt,arg,sz)); \ 1856 }else{ \ 1857 return(ENOTSUP); \ 1858 } \ 1859 }while(0); 1861 All options that support specific settings on an association 1862 by filling in either an association id variable or a 1863 sockaddr_storage SHOULD also support setting of the same 1864 value for the entire endpoint (i.e. future associations). 1865 To accomplish this the following logic is used when 1866 setting one of these options: 1868 a) If an address is specified via a sockaddr_storage that 1869 is included in the structure the address is used to 1870 lookup the association and the settings are applied to 1871 the specific address (if appropriate) or to the entire 1872 association. 1874 b) If an association identification is filled in but not a 1875 sockaddr_storage (if present) the association is found 1876 using the association identification and the settings 1877 should be applied to the entire association (since a specific 1878 address is specified). Note this also applies to options that 1879 hold an association identification in their structure but do not 1880 have a sockaddr_storage field. 1882 c) If neither the sockaddr_storage or association identification is set 1883 i.e. the sockadd_storage is set to all 0's (INADDR_ANY) and the 1884 association identification is 0, the settings are a default and 1885 to be applied to the endpoint (all future associations). 1887 7.1 Read / Write Options 1889 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1891 The protocol parameters used to initialize and bound retransmission 1892 timeout (RTO) are tunable. See [SCTP] for more information on how 1893 these parameters are used in RTO calculation. The peer address 1894 parameter is ignored for TCP style socket. 1896 The following structure is used to access and modify these 1897 parameters: 1899 struct sctp_rtoinfo { 1900 sctp_assoc_t srto_assoc_id; 1901 uint32_t srto_initial; 1902 uint32_t srto_max; 1903 uint32_t srto_min; 1904 }; 1906 srto_initial - This contains the initial RTO value. 1907 srto_max and srto_min - These contain the maximum and minumum bounds 1908 for all RTOs. 1909 srto_assoc_id - (UDP style socket) This is filled in the application, 1910 and identifies the association for this query. If 1911 this parameter is missing (on a UDP style socket), 1912 then the change effects the entire endpoint. 1914 All parameters are time values, in milliseconds. A value of 0, when 1915 modifying the parameters, indicates that the current value should 1916 not be changed. 1918 To access or modify these parameters, the application should call 1919 getsockopt or setsockopt() respectively with the option name 1920 SCTP_RTOINFO. 1922 7.1.2 Association Parameters (SCTP_ASSOCINFO) 1924 This option is used to both examine and set various association 1925 and endpoint parameters. 1927 See [SCTP] for more information on how this parameter is used. The 1928 peer address parameter is ignored for TCP style socket. 1930 The following structure is used to access and modify this 1931 parameters: 1933 struct sctp_assocparams { 1934 sctp_assoc_t sasoc_assoc_id; 1935 uint16_t sasoc_asocmaxrxt; 1936 uint16_t sasoc_number_peer_destinations; 1937 uint32_t sasoc_peer_rwnd; 1938 uint32_t sasoc_local_rwnd; 1939 uint32_t sasoc_cookie_life; 1940 }; 1942 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 1943 to make for the association. 1945 sasoc_number_peer_destinations - This is the number of destination 1946 address that the peer considers 1947 valid. 1948 sasoc_peer_rwnd - This holds the current value of the peers 1949 rwnd (reported in the last SACK) minus any 1950 outstanding data (i.e. data inflight). 1951 sasoc_local_rwnd - This holds the last reported rwnd that was 1952 sent to the peer. 1953 sasoc_cookie_life - This is the associations cookie life value 1954 used when issueing cookies. 1956 sasoc_assoc_id - (UDP style socket) This is filled in the application, 1957 and identifies the association for this query. 1959 This information may be examined for either the 1960 endpoint or a specific association. To examine a endpoints 1961 default parameters the association id (sasoc_assoc_id) should 1962 must be set to the value '0'. The values of the sasoc_peer_rwnd 1963 is meaningless when examining endpoint information. 1965 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may 1966 be set on either an endpoint or association basis. The 1967 rwnd and destination counts (sasoc_number_peer_destinations, 1968 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any 1969 value placed in these is ignored. 1971 To access or modify these parameters, the application should call 1972 getsockopt or setsockopt() respectively with the option name 1973 SCTP_ASSOCRTXINFO. 1975 The maximum number of retransmissions before an address is 1976 considered unreachable is also tunable, but is address-specific, so 1977 it is covered in a seperate option. If an application attempts to 1978 set the value of the association maximum retransmission parameter to 1979 more than the sum of all maximum retransmission parameters, 1980 setsockopt() shall return an error. The reason for this, from 1981 [SCTP] section 8.2: 1983 Note: When configuring the SCTP endpoint, the user should avoid 1984 having the value of 'Association.Max.Retrans' larger than the 1985 summation of the 'Path.Max.Retrans' of all the destination addresses 1986 for the remote endpoint. Otherwise, all the destination addresses 1987 may become inactive while the endpoint still considers the peer 1988 endpoint reachable. 1990 7.1.3 Initialization Parameters (SCTP_INITMSG) 1992 Applications can specify protocol parameters for the default 1993 association intialization. The structure used to access and modify 1994 these parameters is defined in section 5.2.1. The option name 1995 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 1997 Setting initialization parameters is effective only on an 1998 unconnected socket (for UDP-style sockets only future associations 1999 are effected by the change). With TCP-style sockets, this option is 2000 inherited by sockets derived from a listener socket. 2002 7.1.4 SO_LINGER 2004 An application using the TCP-style socket can use this option to 2005 perform the SCTP ABORT primitive. The linger option structure is: 2007 struct linger { 2008 int l_onoff; /* option on/off */ 2009 int l_linger; /* linger time */ 2010 }; 2012 To enable the option, set l_onoff to 1. If the l_linger value is 2013 set to 0, calling close() is the same as the ABORT primitive. If 2014 the value is set to a negative value, the setsockopt() call will 2015 return an error. If the value is set to a positive value 2016 linger_time, the close() can be blocked for at most linger_time ms. 2017 If the graceful shutdown phase does not finish during this period, 2018 close() will return but the graceful shutdown phase continues in the 2019 system. 2021 7.1.5 SCTP_NODELAY 2023 Turn off any Nagle-like algorithm. This means that packets are 2024 generally sent as soon as possible and no unnecessary delays are 2025 introduced, at the cost of more packets in the network. Expects an 2026 integer boolean flag. 2028 7.1.6 SO_RCVBUF 2030 Sets receive buffer size. For SCTP TCP-style sockets, this controls 2031 the receiver window size. For UDP-style sockets, this controls the 2032 receiver window size for all associations bound to the socket 2033 descriptor used in the setsockopt() or getsockopt() call. The option 2034 applies to each association's window size seperately. Expects an 2035 integer. 2037 7.1.7 SO_SNDBUF 2039 Sets send buffer size. For SCTP TCP-style sockets, this controls the 2040 amount of data SCTP may have waiting in internal buffers to be 2041 sent. This option therefore bounds the maximum size of data that can 2042 be sent in a single send call. For UDP-style sockets, the effect is 2043 the same, except that it applies to all associations bound to the 2044 socket descriptor used in the setsockopt() or getsockopt() call. The 2045 option applies to each association's window size seperately. Expects 2046 an integer. 2048 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 2050 This socket option is applicable to the UDP-style socket only. When 2051 set it will cause associations that are idle for more than the 2052 specified number of seconds to automatically close. An association 2053 being idle is defined an association that has NOT sent or received 2054 user data. The special value of '0' indicates that no automatic 2055 close of any associations should be performed. The option expects 2056 an integer defining the number of seconds of idle time before 2057 an association is closed. 2059 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) 2061 Requests that the peer mark the enclosed address as the association 2062 primary. The enclosed address must be one of the association's 2063 locally bound addresses. The following structure is used to make a 2064 set primary request: 2066 struct sctp_setprim { 2067 sctp_assoc_t ssp_assoc_id; 2068 struct sockaddr_storage ssp_addr; 2069 }; 2071 ssp_addr The address to set as primary 2072 ssp_assoc_id (UDP style socket) This is filled in by the 2073 application, and identifies the association 2074 for this request. 2076 This functionality is optional. Implementations that do not support 2077 this functionality should return EOPNOTSUPP. 2079 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2081 Requests that the local SCTP stack use the enclosed peer address as 2082 the association primary. The enclosed address must be one of the 2083 association peer's addresses. The following structure is used to 2084 make a set peer primary request: 2086 struct sctp_setpeerprim { 2087 sctp_assoc_t sspp_assoc_id; 2088 struct sockaddr_storage sspp_addr; 2089 }; 2091 sspp_addr The address to set as primary 2092 sspp_assoc_id (UDP style socket) This is filled in by the 2093 application, and identifies the association 2094 for this request. 2096 7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER) 2097 Requests that the local endpoint set the specified Adaption Layer 2098 Indication parameter for all future 2099 INIT and INIT-ACK exchanges. 2101 struct sctp_setadaption { 2102 u_int32_t ssb_adaption_ind; 2103 } 2105 ssb_adaption_ind The adaption layer indicator that will be included 2106 in any outgoing Adaption Layer Indication 2107 parameter. 2109 7.1.12 Set default message time outs (SCTP_SET_STREAM_TIMEOUTS) 2111 This option requests that the requested stream apply a 2112 default time-out for messages in queue. 2114 struct sctp_setstrm_timeout { 2115 sctp_assoc_t ssto_assoc_id; 2116 u_int32_t ssto_timeout; 2117 u_int16_t ssto_streamid_start; 2118 u_int16_t ssto_streamid_end; 2119 }; 2121 ssto_assoc_id (UDP style socket) This is filled in by the 2122 application, and identifies the association 2123 for this request. 2124 ssto_timeout The maximum time in milliseconds that messages 2125 should be held inqueue before failure. 2126 ssto_streamid_start The beginning stream identifer to apply this 2127 default against. 2128 ssto_streamid_end The ending stream identifer to apply this 2129 default against. 2131 Note that a timeout value of 0 indicates that no inqueue timeout 2132 should be applied against the stream. 2134 7.1.13 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2136 This option is a on/off flag. If enabled no SCTP message 2137 fragmentation will be performed. Instead if a message 2138 being sent exceeds the current PMTU size, the message will 2139 NOT be sent and instead a error will be indicated to the user. 2141 7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS/ 2142 SCTP_GET_PEER_ADDR_PARAMS) 2144 Applications can enable or disable heartbeats for any peer address 2145 of an association, modify an address's heartbeat interval, force a 2146 heartbeat to be sent immediately, and adjust the address's maximum 2147 number of retransmissions sent before an address is considered 2148 unreachable. The following structure is used to access and modify an 2149 address's parameters: 2151 struct sctp_paddrparams { 2152 sctp_assoc_t spp_assoc_id; 2153 struct sockaddr_storage spp_address; 2154 uint32_t spp_hbinterval; 2155 uint16_t spp_pathmaxrxt; 2156 }; 2158 spp_assoc_id - (UDP style socket) This is filled in the application, 2159 and identifies the association for this query. 2160 spp_address - This specifies which address is of interest. 2161 spp_hbinterval - This contains the value of the heartbeat interval, 2162 in milliseconds. A value of 0, when modifying the 2163 parameter, specifies that the heartbeat on this 2164 address should be disabled. A value of UINT32_MAX 2165 (4294967295), when modifying the parameter, 2166 specifies that a heartbeat should be sent 2167 immediately to the peer address, and the current 2168 interval should remain unchanged. 2169 spp_pathmaxrxt - This contains the maximum number of 2170 retransmissions before this address shall be 2171 considered unreachable. 2173 To modify these parameters, the application should call 2174 sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. To get 2175 these parameters, the application should use 2176 SCTP_GET_PEER_ADDR_PARAMS. 2178 7.2 Read-Only Options 2180 7.2.1 Association Status (SCTP_STATUS) 2182 Applications can retrieve current status information about an 2183 association, including association state, peer receiver window size, 2184 number of unacked data chunks, and number of data chunks pending 2185 receipt. This information is read-only. The following structure is 2186 used to access this information: 2188 struct sctp_status { 2189 sctp_assoc_t sstat_assoc_id; 2190 int32_t sstat_state; 2191 uint32_t sstat_rwnd; 2192 uint16_t sstat_unackdata; 2193 uint16_t sstat_penddata; 2194 uint16_t sstat_instrms; 2195 uint16_t sstat_outstrms; 2196 uint32_t sstat_fragmentation_point; 2197 struct sctp_paddrinfo sstat_primary; 2198 }; 2200 sstat_state - This contains the association's current state one 2201 of the following values: 2203 SCTP_CLOSED 2204 SCTP_BOUND 2205 SCTP_LISTEN 2206 SCTP_COOKIE_WAIT 2207 SCTP_COOKIE_ECHOED 2208 SCTP_ESTABLISHED 2209 SCTP_SHUTDOWN_PENDING 2210 SCTP_SHUTDOWN_SENT 2211 SCTP_SHUTDOWN_RECEIVED 2212 SCTP_SHUTDOWN_ACK_SENT 2214 sstat_rwnd - This contains the association peer's current 2215 receiver window size. 2216 sstat_unackdata - This is the number of unacked data chunks. 2217 sstat_penddata - This is the number of data chunks pending receipt. 2218 sstat_primary - This is information on the current primary peer 2219 address. 2220 sstat_assoc_id - (UDP style socket) This holds the an identifier for the 2221 association. All notifications for a given association 2222 have the same association identifier. 2224 sstat_instrms - The number of streams that the peer will 2225 be using inbound. 2227 sstat_outstrms - The number of streams that the endpoint is 2228 allowed to use outbound. 2230 sstat_fragmentation_point - The size at which SCTP fragmentation 2231 will occur. 2233 To access these status values, the application calls getsockopt() 2234 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2235 ignored for TCP style socket. 2237 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2239 Applications can retrieve information about a specific peer address 2240 of an association, including its reachability state, congestion 2241 window, and retransmission timer values. This information is 2242 read-only. The following structure is used to access this 2243 information: 2245 struct sctp_paddrinfo { 2246 sctp_assoc_t spinfo_assoc_id; 2247 struct sockaddr_storage spinfo_address; 2248 int32_t spinfo_state; 2249 uint32_t spinfo_cwnd; 2250 uint32_t spinfo_srtt; 2251 uint32_t spinfo_rto; 2252 uint32_t spinfo_mtu; 2253 }; 2255 spinfo_address - This is filled in the application, and contains 2256 the peer address of interest. 2258 On return from getsockopt(): 2260 spinfo_state - This contains the peer addresses's state (either 2261 SCTP_ACTIVE or SCTP_INACTIVE). 2262 spinfo_cwnd - This contains the peer addresses's current congestion 2263 window. 2264 spinfo_srtt - This contains the peer addresses's current smoothed 2265 round-trip time calculation in milliseconds. 2266 spinfo_rto - This contains the peer addresses's current 2267 retransmission timeout value in milliseconds. 2268 spinfo_mtu - The current P-MTU of this address. 2269 spinfo_assoc_id - (UDP style socket) This is filled in the application, 2270 and identifies the association for this query. 2272 To retrieve this information, use sctp_opt_info() with the 2273 SCTP_GET_PEER_ADDR_INFO options. 2275 7.3. Ancillary Data and Notification Interest Options 2277 Applications can receive per-message ancillary information and 2278 notifications of certain SCTP events with recvmsg(). 2280 The following optional information is available to the application: 2282 1. SCTP_SNDRCV: Per-message information (i.e. stream number, 2283 TSN, SSN, etc. described in section 5.2.2) 2284 2. SCTP_ASSOC_CHANGE: (described in section 5.3.1.1) 2285 3. SCTP_PEER_ADDR_CHANGE: (described in section 5.3.1.2) 2286 4. SCTP_REMOTE_ERROR: (described in section 5.3.1.3) 2287 5. SCTP_SEND_FAILED: (described in section 5.3.1.4) 2288 6. SCTP_SHUTDOWN_EVENT: (described in section 5.3.1.5) 2289 7. SCTP_ADAPTION_INDICATION: (described in section 5.3.1.6) 2290 8. SCTP_PARTIAL_DELIVERY_EVENT: (described in section 5.3.1.7) 2292 To receive any ancillary data or notifications, first the 2293 application registers it's interest by calling the SCTP_SET_EVENTS 2294 setsockopt() with the following structure. 2296 struct sctp_event_subscribe{ 2297 u_int8_t sctp_data_io_event; 2298 u_int8_t sctp_association_event; 2299 u_int8_t sctp_address_event; 2300 u_int8_t sctp_send_failure_event; 2301 u_int8_t sctp_peer_error_event; 2302 u_int8_t sctp_shutdown_event; 2303 u_int8_t sctp_partial_delivery_event; 2304 u_int8_t sctp_adaption_layer_event; 2305 }; 2307 sctp_data_io_event - Setting this flag to 1 will cause the 2308 reception of SCTP_SNDRCV information on a per message basis. 2309 The application will need to use the recvmsg() interface so 2310 that it can receive the event information contained in the 2311 msg_control field. Please see section 5.2 for further details. 2312 Setting the flag to 0 will disable reception of the message 2313 control information. 2315 sctp_association_event - Setting this flag to 1 will enable 2316 the reception of association event notifications. Setting 2317 the flag to 0 will disable association event notifications. 2318 For more information on event notifications please see section 2319 5.3. 2321 sctp_address_event - Setting this flag to 1 will enable 2322 the reception of address event notifications. Setting 2323 the flag to 0 will disable address event notifications. 2324 For more information on event notifications please see section 2325 5.3. 2327 sctp_send_failure_event - Setting this flag to 1 will enable 2328 the reception of send failure event notifications. Setting 2329 the flag to 0 will disable send failure event notifications. 2330 For more information on event notifications please see section 2331 5.3. 2333 sctp_peer_error_event - Setting this flag to 1 will enable 2334 the reception of peer error event notifications. Setting 2335 the flag to 0 will disable peer error event notifications. 2336 For more information on event notifications please see section 2337 5.3. 2339 sctp_shutdown_event - Setting this flag to 1 will enable 2340 the reception of shutdown event notifications. Setting 2341 the flag to 0 will disable shutdown event notifications. 2342 For more information on event notifications please see section 2343 5.3. 2345 sctp_partial_delivery_event - Setting this flag to 1 will enable 2346 the reception of partial delivery notifications. Setting 2347 the flag to 0 will disable partial delivery event notifications. 2348 For more information on event notifications please see section 2349 5.3. 2351 sctp_adaption_layer_event - Setting this flag to 1 will enable 2352 the reception of adaption layer notifications. Setting 2353 the flag to 0 will disable adaption layer event notifications. 2354 For more information on event notifications please see section 2355 5.3. 2357 An example where an application would like to recieve data 2358 io events and association events but no others would be 2359 as follows: 2361 { 2362 struct sctp_event_subscribe event; 2364 memset(&event,0,sizeof(event)); 2366 event.sctp_data_io_event = 1; 2367 event.sctp_association_event = 1; 2369 setsockopt(fd, IPPROTO_SCTP, SCTP_SET_EVENT, &event, sizeof(event)); 2370 } 2372 Note that for UDP-style SCTP sockets, the caller of recvmsg() 2373 receives ancillary data and notifications for ALL associations bound 2374 to the file descriptor. For TCP-style SCTP sockets, the caller 2375 receives ancillary data and notifications for only the single 2376 association bound to the file descriptor. 2378 By default a TCP-style socket has all options off. 2380 By default a UDP-style socket has sctp_data_io_event and 2381 sctp_association_event on and all other options off. 2383 8. New Interfaces 2385 Depending on the system, the following interface can be implemented 2386 as a system call or library funtion. 2388 8.1 sctp_bindx() 2390 The syntax of sctp_bindx() is, 2392 int sctp_bindx(int sd, struct sockaddr_storage *addrs, int addrcnt, 2393 int flags); 2395 If sd is an IPv4 socket, the addresses passed must be IPv4 2396 addresses. If the sd is an IPv6 socket, the addresses passed can 2397 either be IPv4 or IPv6 addresses. 2399 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2400 section 3.1.2 for this usage. 2402 addrs is a pointer to an array of one or more socket addresses. 2403 Each address is contained in a struct sockaddr_storage, so each 2404 address is a fixed length. The caller specifies the number of 2405 addresses in the array with addrcnt. 2407 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2408 -1, and sets errno to the appropriate error code. 2410 For SCTP, the port given in each socket address must be the same, or 2411 sctp_bindx() will fail, setting errno to EINVAL. 2413 The flags parameter is formed from the bitwise OR of zero or more of 2414 the following currently defined flags: 2416 SCTP_BINDX_ADD_ADDR 2417 SCTP_BINDX_REM_ADDR 2419 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2420 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the 2421 given addresses from the association. The two flags are mutually 2422 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 2423 caller may not remove all addresses from an association; 2424 sctp_bindx() will reject such an attempt with EINVAL. 2426 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2427 additional addresses with an endpoint after calling bind(). Or use 2428 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2429 socket is associated with so that no new association accepted will 2430 be associated with those addresses. If the endpoint supports dynamic 2431 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause 2432 a endpoint to send the appropriate message to the peer to 2433 change the peers address lists. 2435 Adding and removing addresses from a connected association is 2436 optional functionality. Implementations that do not support this 2437 functionality should return EOPNOTSUPP. 2439 8.2 Branched-off Association 2441 After an association is established on a UDP-style socket, the 2442 application may wish to branch off the association into a separate 2443 socket/file descriptor. 2445 This is particularly desirable when, for instance, the application 2446 wishes to have a number of sporadic message senders/receivers remain 2447 under the original UDP-style socket but branch off those 2448 associations carrying high volume data traffic into their own 2449 separate socket descriptors. 2451 The application uses sctp_peeloff() call to branch off an 2452 association into a separate socket (Note the semantics are somewhat 2453 changed from the traditional TCP-style accept() call). 2455 The syntax is: 2457 new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id) 2459 new_sd - the new socket descriptor representing the branched-off 2460 association. 2462 sd - the original UDP-style socket descriptor returned from the 2463 socket() system call (see Section 3.1.1). 2465 assoc_id - the specified identifier of the association that is to be 2466 branched off to a separate file descriptor (Note, in a 2467 traditional TCP-style accept() call, this would be an out 2468 parameter, but for the UDP-style call, this is an in 2469 parameter). 2471 8.3 sctp_getpaddrs() 2473 sctp_getpaddrs() returns all peer addresses in an association. The 2474 syntax is, 2476 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2477 struct sockaddr_storage **addrs); 2479 On return, addrs will point to a dynamically allocated array of 2480 struct sockaddr_storages, one for each peer address. The caller 2481 should use sctp_freepaddrs() to free the memory. addrs must not be 2482 NULL. 2484 If sd is an IPv4 socket, the addresses returned will be all IPv4 2485 addresses. If sd is an IPv6 socket, the addresses returned can be a 2486 mix of IPv4 or IPv6 addresses. 2488 For UDP-style sockets, id specifies the association to query. For 2489 TCP-style sockets, id is ignored. 2491 On success, sctp_getpaddrs() returns the number of peer addresses in 2492 the association. If there is no association on this socket, 2493 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2494 an error occurs, sctp_getpaddrs() returns -1, and the value of 2495 *addrs is undefined. 2497 8.4 sctp_freepaddrs() 2499 sctp_freepaddrs() frees all resources allocated by 2500 sctp_getpaddrs(). Its syntax is, 2502 void sctp_freepaddrs(struct sockaddr_storage *addrs); 2504 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2506 8.5 sctp_getladdrs() 2508 sctp_getladdrs() returns all locally bound address on a socket. The 2509 syntax is, 2511 int sctp_getladdrs(int sock, sctp_assoc_t id, 2512 struct sockaddr_storage **ss); 2514 On return, addrs will point to a dynamically allocated array of 2515 struct sockaddr_storages, one for each local address. The caller 2516 should use sctp_freeladdrs() to free the memory. addrs must not be 2517 NULL. 2519 If sd is an IPv4 socket, the addresses returned will be all IPv4 2520 addresses. If sd is an IPv6 socket, the addresses returned can be a 2521 mix of IPv4 or IPv6 addresses. 2523 For UDP-style sockets, id specifies the association to query. For 2524 TCP-style sockets, id is ignored. 2526 If the id field is set to the value '0' then the locally bound 2527 addresses are returned without regard to any particular association. 2529 On success, sctp_getladdrs() returns the number of local addresses 2530 bound to the socket. If the socket is unbound, sctp_getladdrs() 2531 returns 0, and the value of *addrs is undefined. If an error occurs, 2532 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2534 8.6 sctp_freeladdrs() 2536 sctp_freeladdrs() frees all resources allocated by 2537 sctp_getladdrs(). Its syntax is, 2539 void sctp_freeladdrs(struct sockaddr_storage *addrs); 2541 addrs is the array of peer addresses returned by sctp_getladdrs(). 2543 9. Security Considerations 2545 Many TCP and UDP implementations reserve port numbers below 1024 for 2546 privileged users. If the target platform supports privileged users, 2547 the SCTP implementation SHOULD restrict the ability to call bind() 2548 or sctp_bindx() on these port numbers to privileged users. 2550 Similarly unprivelged users should not be able to set protocol 2551 parameters which could result in the congestion control algorithm 2552 being more agressive than permitted on the public Internet. These 2553 paramaters are: 2555 struct sctp_rtoinfo 2557 If an unprivileged user inherits a UDP-style socket with open 2558 associations on a privileged port, it MAY be permitted to accept new 2559 associations, but it SHOULD NOT be permitted to open new 2560 associations. This could be relevant for the r* family of 2561 protocols. 2563 10. Acknowledgements 2565 The authors wish to thank Kavitha Baratakke, Mike Bartlett, 2566 Jon Berger, Scott Kimble, Renee Revis, and many others on 2567 the TSVWG mailing list for contributing valuable comments. 2569 11. Authors' Addresses 2571 Randall R. Stewart Tel: +1-815-477-2127 2572 Cisco Systems, Inc. EMail: rrs@cisco.com 2573 Crystal Lake, IL 60012 2574 USA 2576 Qiaobing Xie Tel: +1-847-632-3028 2577 Motorola, Inc. EMail: qxie1@email.mot.com 2578 1501 W. Shure Drive, Room 2309 2579 Arlington Heights, IL 60004 2580 USA 2582 La Monte H.P. Yarroll NIC Handle: LY 2583 Motorola, Inc. EMail: piggy@acm.org 2584 1501 W. Shure Drive, IL27-2315 2585 Arlington Heights, IL 60004 2586 USA 2588 Jonathan Wood 2589 DoCoMo USA Labs Email: jonwood@speakeasy.net 2590 181 Metro Drive, Suite 300 2591 San Jose, CA 95110 2592 USA 2594 Kacheong Poon 2595 Sun Microsystems, Inc. Email: kacheong.poon@sun.com 2596 901 San Antonio Road 2597 Palo Alto, CA 94303 2598 USA 2600 Ken Fujita Tel: +81-471-82-1131 2601 NEC Corporation Email: fken@cd.jp.nec.com 2602 1131, Hinode, Abiko 2603 Chiba, 270-1198 2604 Japan 2606 12. References 2608 [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2609 September 1981. 2611 [RFC768] Postel, J. (ed.), "User Datagram Protocol", STD 6, RFC 768, 2612 August 1980. 2614 [RFC1644] Braden, R., "T/TCP -- TCP Extensions for Transactions 2615 Functional Specification," RFC 1644, July 1994. 2617 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", 2618 RFC 2026, October 1996. 2620 [RFC2292] W.R. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 2621 RFC 2292, February 1998. 2623 [RFC2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens. "Basic Socket 2624 Interface Extensions for IPv6," RFC 2553, March 1999. 2626 [SCTP] R.R. Stewart, Q. Xie, K. Morneault, C. Sharp, H.J. Schwarzbauer, 2627 T. Taylor, I. Rytina, M. Kalla, L. Zhang, and, V. Paxson, 2628 "Stream Control Transmission Protocol," RFC2960, October 2000. 2630 [STEVENS] W.R. Stevens, M. Thomas, E. Nordmark, "Advanced Sockets API for 2631 IPv6," , November 2001 2632 (Work in progress) 2634 Appendix A: TCP-style Code Example 2636 The following code is a simple implementation of an echo server over 2637 SCTP. The example shows how to use some features of TCP-style IPv4 2638 SCTP sockets, including: 2640 o Opening, binding, and listening for new associations on a socket; 2641 o Enabling ancillary data 2642 o Enabling notifications 2643 o Using ancillary data with sendmsg() and recvmsg() 2644 o Using MSG_EOR to determine if an entire message has been read 2645 o Handling notifications 2647 static void 2648 handle_event(void *buf) 2649 { 2650 struct sctp_assoc_change *sac; 2651 struct sctp_send_failed *ssf; 2652 struct sctp_paddr_change *spc; 2653 struct sctp_remote_error *sre; 2654 union sctp_notification *snp; 2655 char addrbuf[INET6_ADDRSTRLEN]; 2656 const char *ap; 2657 struct sockaddr_in *sin; 2658 struct sockaddr_in6 *sin6; 2660 snp = buf; 2662 switch (snp->sn_type) { 2663 case SCTP_ASSOC_CHANGE: 2664 sac = &snp->sn_assoc_change; 2665 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2666 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2667 sac->sac_inbound_streams, sac->sac_outbound_streams); 2668 break; 2669 case SCTP_SEND_FAILED: 2670 ssf = &snp->sn_send_failed; 2671 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2672 ssf->ssf_error); 2673 break; 2674 case SCTP_PEER_ADDR_CHANGE: 2675 spc = &snp->sn_intf_change; 2676 if (spc->spc_addr.ss_family == AF_INET) { 2677 sin = (struct sockaddr_in *)&spc->spc_addr; 2678 ap = inet_ntop(AF_INET, &sin->sin_addr, addrbuf, 2679 INET6_ADDRSTRLEN); 2680 } else { 2681 sin6 = (struct sockaddr_in6 *)&spc->spc_addr; 2682 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, addrbuf, 2683 INET6_ADDRSTRLEN); 2684 } 2685 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2686 spc->spc_state, spc->spc_error); 2687 break; 2688 case SCTP_REMOTE_ERROR: 2689 sre = &snp->sn_remote_error; 2690 printf("^^^ remote_error: err=%hu len=%hu\n", 2691 ntohs(sre->sre_error), ntohs(sre->sre_len)); 2692 break; 2693 case SCTP_SHUTDOWN_EVENT: 2694 printf("^^^ shutdown event\n"); 2695 break; 2696 default: 2697 printf("unknown type: %hu\n", snp->sn_type); 2698 break; 2699 } 2700 } 2702 static void * 2703 sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2704 ssize_t *nrp, size_t cmsglen) 2705 { 2706 ssize_t nr = 0; 2707 struct iovec iov[1]; 2709 *nrp = 0; 2710 iov->iov_base = buf; 2711 msg->msg_iov = iov; 2712 msg->msg_iovlen = 1; 2714 for (;;) { 2715 msg->msg_flags = MSG_XPG4_2; 2716 msg->msg_iov->iov_len = *buflen; 2717 msg->msg_controllen = cmsglen; 2719 nr += recvmsg(fd, msg, 0); 2720 if (nr <= 0) { 2721 /* EOF or error */ 2722 *nrp = nr; 2723 return (NULL); 2724 } 2726 if ((msg->msg_flags & MSG_EOR) != 0) { 2727 *nrp = nr; 2728 return (buf); 2729 } 2731 /* Realloc the buffer? */ 2732 if (*buflen == nr) { 2733 buf = realloc(buf, *buflen * 2); 2734 if (buf == 0) { 2735 fprintf(stderr, "out of memory\n"); 2736 exit(1); 2737 } 2738 *buflen *= 2; 2739 } 2741 /* Set the next read offset */ 2742 iov->iov_base = (char *)buf + nr; 2743 iov->iov_len = *buflen - nr; 2745 } 2746 } 2748 static void 2749 echo(int fd, int socketModeUDP) 2750 { 2751 ssize_t nr; 2752 struct sctp_sndrcvinfo *sri; 2753 struct msghdr msg[1]; 2754 struct cmsghdr *cmsg; 2755 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 2756 char *buf; 2757 size_t buflen; 2758 struct iovec iov[1]; 2759 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 2761 /* Allocate the initial data buffer */ 2762 buflen = BUFLEN; 2763 if (!(buf = malloc(BUFLEN))) { 2764 fprintf(stderr, "out of memory\n"); 2765 exit(1); 2766 } 2768 /* Set up the msghdr structure for receiving */ 2769 memset(msg, 0, sizeof (*msg)); 2770 msg->msg_control = cbuf; 2771 msg->msg_controllen = cmsglen; 2772 msg->msg_flags = 0; 2773 cmsg = (struct cmsghdr *)cbuf; 2774 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 2776 /* Wait for something to echo */ 2777 while (buf = sctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 2779 /* Intercept notifications here */ 2780 if (msg->msg_flags & MSG_NOTIFICATION) { 2781 handle_event(buf); 2782 continue; 2783 } 2785 iov->iov_base = buf; 2786 iov->iov_len = nr; 2787 msg->msg_iov = iov; 2788 msg->msg_iovlen = 1; 2789 printf("got %u bytes on stream %hu:\n", nr, 2790 sri->sinfo_stream); 2791 write(0, buf, nr); 2793 /* Echo it back */ 2794 msg->msg_flags = MSG_XPG4_2; 2795 if (sendmsg(fd, msg, 0) < 0) { 2796 perror("sendmsg"); 2797 exit(1); 2798 } 2799 } 2801 if (nr < 0) { 2802 perror("recvmsg"); 2803 } 2804 if(socketModeUDP == 0) 2805 close(fd); 2806 } 2808 main() 2809 { 2810 int lfd, cfd; 2811 int onoff = 1; 2812 struct sockaddr_in sin[1]; 2814 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 2815 perror("socket"); 2816 exit(1); 2817 } 2819 sin->sin_family = AF_INET; 2820 sin->sin_port = htons(7); 2821 sin->sin_addr.s_addr = INADDR_ANY; 2822 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2823 perror("bind"); 2824 exit(1); 2825 } 2827 if (listen(lfd, 1) == -1) { 2828 perror("listen"); 2829 exit(1); 2830 } 2832 /* Wait for new associations */ 2833 for (;;) { 2834 if ((cfd = accept(lfd, NULL, 0)) == -1) { 2835 perror("accept"); 2836 exit(1); 2837 } 2839 /* Enable ancillary data */ 2840 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2841 &onoff, 4) < 0) { 2842 perror("setsockopt RECVDATAIOEVNT"); 2843 exit(1); 2844 } 2845 /* Enable notifications */ 2846 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, 2847 &onoff, 4) < 0) { 2848 perror("setsockopt SCTP_RECVASSOCEVNT"); 2849 exit(1); 2850 } 2851 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2852 &onoff, 4) < 0) { 2853 perror("setsockopt SCTP_RECVASSOCEVNT"); 2854 exit(1); 2855 } 2856 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2857 &onoff, 4) < 0) { 2858 perror("setsockopt SCTP_RECVPADDREVNT"); 2859 exit(1); 2860 } 2861 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2862 &onoff, 4) < 0) { 2863 perror("setsockopt SCTP_RECVPEERERR"); 2864 exit(1); 2865 } 2866 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2867 &onoff, 4) < 0) { 2868 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2869 exit(1); 2870 } 2872 /* Echo back any and all data */ 2873 echo(cfd,0); 2874 } 2875 } 2877 Appendix B: UDP-style Code Example 2879 The following code is a simple implementation of an echo server over 2880 SCTP. The example shows how to use some features of UDP-style IPv4 2881 SCTP sockets, including: 2883 o Opening and binding of a socket; 2884 o Enabling ancillary data 2885 o Enabling notifications 2886 o Using ancillary data with sendmsg() and recvmsg() 2887 o Using MSG_EOR to determine if an entire message has been read 2888 o Handling notifications 2890 Note most functions defined in Appendix A are reused in 2891 this example. 2893 main() 2894 { 2895 int fd; 2896 int onoff = 1; 2897 int idleTime = 2; 2898 struct sockaddr_in sin[1]; 2900 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 2901 perror("socket"); 2902 exit(1); 2903 } 2905 sin->sin_family = AF_INET; 2906 sin->sin_port = htons(7); 2907 sin->sin_addr.s_addr = INADDR_ANY; 2908 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2909 perror("bind"); 2910 exit(1); 2911 } 2913 /* Enable notifications */ 2915 /* SCTP_RECVASSOCEVNT and SCTP_RECVDATAIOEVNT are on by default */ 2917 /* if a send fails we want to know it */ 2918 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2919 &onoff, 4) < 0) { 2920 perror("setsockopt SCTP_RECVASSOCEVNT"); 2921 exit(1); 2922 } 2923 /* if a network address change or event transpires 2924 * we wish to know it 2925 */ 2926 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2927 &onoff, 4) < 0) { 2928 perror("setsockopt SCTP_RECVPADDREVNT"); 2929 exit(1); 2930 } 2931 /* We would like all error TLV's from the peer */ 2932 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2933 &onoff, 4) < 0) { 2934 perror("setsockopt SCTP_RECVPEERERR"); 2935 exit(1); 2936 } 2937 /* And of course we would like to know about shutdown's */ 2938 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2939 &onoff, 4) < 0) { 2940 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2941 exit(1); 2942 } 2943 /* Set associations to auto-close in 2 seconds of 2944 * inactivity 2945 */ 2946 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 2947 &idleTime, 4) < 0) { 2948 perror("setsockopt SCTP_AUTOCLOSE"); 2949 exit(1); 2950 } 2952 /* Allow new associations to be accepted */ 2953 if (listen(fd, 0) < 0) { 2954 perror("listen"); 2955 exit(1); 2956 } 2958 /* Wait for new associations */ 2959 while(1){ 2960 /* Echo back any and all data */ 2961 echo(fd,1); 2962 } 2963 }