idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-04.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-04-26) 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 == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 2) being 60 lines 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 33 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 950: '...In other words the user MAY be able to...' RFC 2119 keyword, line 969: '... MAY override 'RTO.Max'. This valu...' RFC 2119 keyword, line 1115: '...e MSG_EOR clear. The user MUST finish...' RFC 2119 keyword, line 1869: '...sockaddr_storage SHOULD also support s...' RFC 2119 keyword, line 2572: '...P implementation SHOULD restrict the a...' (2 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 738 has weird spacing: '...n. The value...' == Line 750 has weird spacing: '...er send and ...' == Line 925 has weird spacing: '...g_level cms...' == Line 981 has weird spacing: '...g_level cms...' == Line 1602 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 (May 12, 2002) is 8020 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 606, but not defined ** Obsolete undefined reference: RFC 2553 (Obsoleted by RFC 3493) -- Looks like a reference, but probably isn't: '0' on line 1409 == Missing Reference: 'RFC2960' is mentioned on line 1719, but not defined ** Obsolete undefined reference: RFC 2960 (Obsoleted by RFC 4960) -- Looks like a reference, but probably isn't: '1' on line 2921 == Unused Reference: 'STEVENS' is defined on line 2652, 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 (~~), 12 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 May 12, 2002 15 Sockets API Extensions for Stream Control Transmission Protocol 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......................31 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..........................................34 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)...........38 94 7.1.4 SO_LINGER..........................................38 95 7.1.5 SO_NODELAY.........................................38 96 7.1.6 SO_RCVBUF..........................................38 97 7.1.7 SO_SNDBUF..........................................38 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...........................40 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 107 (SCTP_SET_PEER_ADDR_PARAMS).......................40 108 7.1.15 Set default send parameters.......................41 109 7.1.16 Set notification and ancillary events 110 (SCTP_SET_EVENTS).................................41 111 7.2 Read-Only Options.....................................41 112 7.2.1 Association Status (SCTP_STATUS)...................42 113 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO).43 114 7.3. Ancillary Data and Notification Interest Options.....43 115 8. New Interfaces..........................................45 116 8.1 sctp_bindx()..........................................45 117 8.2 Branched-off Association, sctp_peeloff()..............46 118 8.3 sctp_getpaddrs()......................................47 119 8.4 sctp_freepaddrs().....................................47 120 8.5 sctp_getladdrs()......................................48 121 8.6 sctp_freeladdrs().....................................48 122 9. Security Considerations.................................48 123 10. Acknowledgments.......................................49 124 11. Authors' Addresses....................................49 125 12. References............................................49 126 Appendix A: TCP-style Code Example.........................50 127 Appendix B: UDP-style Code Example.........................55 129 1. Introduction 131 The sockets API has provided a standard mapping of the Internet 132 Protocol suite to many operating systems. Both TCP [RFC793] and UDP 133 [RFC768] have benefited from this standard representation and access 134 method across many diverse platforms. SCTP is a new protocol that 135 provides many of the characteristics of TCP but also incorporates 136 semantics more akin to UDP. This document defines a method to map 137 the existing sockets API for use with SCTP, providing both a base 138 for access to new features and compatibility so that most existing 139 TCP applications can be migrated to SCTP with few (if any) changes. 141 There are three basic design objectives: 143 1) Maintain consistency with existing sockets APIs: 145 We define a sockets mapping for SCTP that is consistent with other 146 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 147 IPv6). 149 2) Support a UDP-style interface 151 This set of semantics is similar to that defined for connection less 152 protocols, such as UDP. It is more efficient than a TCP-like 153 connection-oriented interface in terms of exploring the new features 154 of SCTP. 156 Note that SCTP is connection-oriented in nature, and it does not 157 support broadcast or multicast communications, as UDP does. 159 3) Support a TCP-style interface 161 This interface supports the same basic semantics as sockets for 162 connection-oriented protocols, such as TCP. 164 The purpose of defining this interface is to allow existing 165 applications built on connection-oriented protocols be ported to 166 use SCTP with very little effort, and developers familiar with those 167 semantics can easily adapt to SCTP. 169 Extensions will be added to this mapping to provide mechanisms to 170 exploit new features of SCTP. 172 Goals 2 and 3 are not compatible, so in this document we define two 173 modes of mapping, namely the UDP-style mapping and the TCP-style 174 mapping. These two modes share some common data structures and 175 operations, but will require the use of two different programming 176 models. 178 A mechanism is defined to convert a UDP-style SCTP socket into a 179 TCP-style socket. 181 Some of the SCTP mechanisms cannot be adequately mapped to existing 182 socket interface. In some cases, it is more desirable to have new 183 interface instead of using existing socket calls. This document 184 also describes those new interface. 186 2. Conventions 188 2.1 Data Types 190 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 191 1003.1g are used: uintN_t means an unsigned integer of exactly N 192 bits (e.g., uint16_t). We also assume the argument data types from 193 1003.1g when possible (e.g., the final argument to setsockopt() is a 194 size_t value). Whenever buffer sizes are specified, the POSIX 195 1003.1 size_t data type is used. 197 3. UDP-style Interface 199 The UDP-style interface has the following characteristics: 201 A) Outbound association setup is implicit. 203 B) Messages are delivered in complete messages (with one notable 204 exception). 206 3.1 Basic Operation 208 A typical server in this model uses the following socket calls in 209 sequence to prepare an endpoint for servicing requests: 211 1. socket() 212 2. bind() 213 3. listen() 214 4. recvmsg() 215 5. sendmsg() 216 6. close() 218 A typical client uses the following calls in sequence to setup an 219 association with a server to request services: 221 1. socket() 222 2. sendmsg() 223 3. recvmsg() 224 4. close() 226 In this model, by default, all the associations connected to the 227 endpoint are represented with a single socket. 229 If the server or client wishes to branch an existing association off 230 to a separate socket, it is required to call sctp_peeloff() and in 231 the parameter specifies one of the transport addresses of the 232 association. The sctp_peeloff() call will return a new socket which 233 can then be used with recv() and send() functions for message 234 passing. See Section 8.2 for more on branched-off associations. 236 Once an association is branched off to a separate socket, it becomes 237 completely separated from the original socket. All subsequent 238 control and data operations to that association must be done through 239 the new socket. For example, the close operation on the original 240 socket will not terminate any associations that have been branched 241 off to a different socket. 243 We will discuss the UDP-style socket calls in more details in the 244 following subsections. 246 3.1.1 socket() - UDP Style Syntax 248 Applications use socket() to create a socket descriptor to represent 249 an SCTP endpoint. 251 The syntax is, 253 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 255 or, 257 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 259 Here, SOCK_SEQPACKET indicates the creation of a UDP-style socket. 261 The first form creates an endpoint which can use only IPv4 262 addresses, while, the second form creates an endpoint which can use 263 both IPv6 and IPv4 mapped addresses. 265 3.1.2 bind() - UDP Style Syntax 267 Applications use bind() to specify which local address the SCTP 268 endpoint should associate itself with. 270 An SCTP endpoint can be associated with multiple addresses. To do 271 this, sctp_bindx() is introduced in section 8.1 to help applications 272 do the job of associating multiple addresses. 274 These addresses associated with a socket are the eligible transport 275 addresses for the endpoint to send and receive data. The endpoint 276 will also present these addresses to its peers during the 277 association initialization process, see [SCTP]. 279 After calling bind() or sctp_bindx(), if the endpoint wishes to 280 accept new associations on the socket, it must call listen() (see 281 section 3.1.3). 283 The syntax of bind() is, 285 ret = bind(int sd, struct sockaddr *addr, int addrlen); 287 sd - the socket descriptor returned by socket(). 288 addr - the address structure (struct sockaddr_in or struct 289 sockaddr_in6 [RFC 2553]), 290 addrlen - the size of the address structure. 292 If sd is an IPv4 socket, the address passed must be an IPv4 address. 293 If the sd is an IPv6 socket, the address passed can either be an 294 IPv4 or an IPv6 address. 296 Applications cannot call bind() multiple times to associate multiple 297 addresses to an endpoint. After the first call to bind(), all 298 subsequent calls will return an error. 300 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 301 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 302 operating system will associate the endpoint with an optimal address 303 set of the available interfaces. 305 If a bind() or sctp_bindx() is not called prior to a sendmsg() call 306 that initiates a new association, the system picks an ephemeral port 307 and will choose an address set equivalent to binding with a wildcard 308 address. One of those addresses will be the primary address for the 309 association. This automatically enables the multi-homing capability 310 of SCTP. 312 3.1.3 listen() - UDP Style Syntax 314 By default, new associations are not accepted for UDP style sockets. 315 An application uses listen() to mark a socket as being able to 316 accept new associations. The syntax is, 318 int listen(int socket, int backlog); 320 socket - the socket descriptor of the endpoint. 321 backlog - ignored for UDP-style sockets. 323 Note that UDP-style socket consumers do not need to call accept to 324 retrieve new associations. Calling accept() on a UDP-style socket 325 should return EOPNOTSUPP. Rather, new associations are accepted 326 automatically, and notifications of the new associations are 327 delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if these 328 notifications are enabled). Clients will typically not call listen, 329 so that they can be assured that the only associations on the socket 330 will be ones they actively initiated. Server or peer-to-peer 331 sockets, on the other hand, will always accept new associations, so 332 a well-written application using server UDP-style sockets must be 333 prepared to handle new associations from unwanted peers. 335 Also note that the SCTP_ASSOC_CHANGE event provides the association 336 ID for a new association, so if applications wish to use the 337 association ID as input to other socket calls, they should ensure 338 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 339 default). 341 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax 343 An application uses sendmsg() and recvmsg() call to transmit data to 344 and receive data from its peer. 346 ssize_t sendmsg(int socket, const struct msghdr *message, 347 int flags); 349 ssize_t recvmsg(int socket, struct msghdr *message, 350 int flags); 352 socket - the socket descriptor of the endpoint. 353 message - pointer to the msghdr structure which contains a single 354 user message and possibly some ancillary data. 356 See Section 5 for complete description of the data 357 structures. 359 flags - No new flags are defined for SCTP at this level. See 360 Section 5 for SCTP-specific flags used in the msghdr 361 structure. 363 As we will see in Section 5, along with the user data, the ancillary 364 data field is used to carry the sctp_sndrcvinfo and/or the 365 sctp_initmsg structures to perform various SCTP functions including 366 specifying options for sending each user message. Those options, 367 depending on whether sending or receiving, include stream number, 368 stream sequence number, TOS, various flags, context and payload 369 protocol Id, etc. 371 When sending user data with sendmsg(), the msg_name field in msghdr 372 structure will be filled with one of the transport addresses of the 373 intended receiver. If there is no association existing between the 374 sender and the intended receiver, the sender's SCTP stack will set 375 up a new association and then send the user data (see Section 3.2 376 for more on implicit association setup). 378 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 379 be delivered if that notification has been enabled, and no more data 380 can be sent to that association. Any attempt to send more data will 381 cause sendmsg() to return with an ESHUTDOWN error. Note that the 382 socket is still open for reading at this point so it is possible to 383 retrieve notifications. 385 When receiving a user message with recvmsg(), the msg_name field in 386 msghdr structure will be populated with the source transport address 387 of the user data. The caller of recvmsg() can use this address 388 information to determine to which association the received user 389 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 390 applications must use the peer transport address provided in the 391 msg_name field by recvmsg() to perform correlation to an 392 association, since they will not have the association ID. 394 If all data in a single message has been delivered, MSG_EOR will be 395 set in the msg_flags field of the msghdr structure (see section 396 5.1). 398 If the application does not provide enough buffer space to 399 completely receive a data message, MSG_EOR will not be set in 400 msg_flags. Successive reads will consume more of the same message 401 until the entire message has been delivered, and MSG_EOR will be 402 set. 404 If the SCTP stack is running low on buffers, it may partially 405 deliver a message. In this case, MSG_EOR will not be set, and more 406 calls to recvmsg() will be necessary to completely consume the 407 message. Only one message at a time can be partially delivered. 409 Note, if the socket is a branched-off socket that only represents 410 one association (see Section 3.1), the msg_name field is not used 411 when sending data (i.e., ignored by the SCTP stack). 413 3.1.5 close() - UDP Style Syntax 415 Applications use close() to perform graceful shutdown (as described 416 in Section 10.1 of [SCTP]) on ALL the associations currently 417 represented by a UDP-style socket. 419 The syntax is 421 ret = close(int sd); 423 sd - the socket descriptor of the associations to be closed. 425 To gracefully shutdown a specific association represented by the 426 UDP-style socket, an application should use the sendmsg() call, 427 passing no user data, but including the MSG_EOF flag in the 428 ancillary data (see Section 5.2.2). 430 If sd in the close() call is a branched-off socket representing only 431 one association, the shutdown is performed on that association only. 433 3.1.6 connect() - UDP Style Syntax 435 An application may use the connect() call in the UDP model to 436 initiate an association without sending data. 438 The syntax is 440 ret = connect(int sd, const struct sockaddr *nam, int len); 442 sd - the socket descriptor to have a new association added 443 to. 445 nam - the address structure (either struct sockaddr_in or struct 446 sockaddr_in6 defined in [RFC 2553]). 448 len - the size of the address. 450 3.2 Implicit Association Setup 452 Once all bind() calls are complete on a UDP-style socket, the 453 application can begin sending and receiving data using the 454 sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going 455 through any explicit association setup procedures (i.e., no 456 connect() calls required). 458 Whenever sendmsg() or sendto() is called and the SCTP stack at the 459 sender finds that there is no association existing between the 460 sender and the intended receiver (identified by the address passed 461 either in the msg_name field of msghdr structure in the sendmsg() 462 call or the dest_addr field in the sendto() call), the SCTP stack 463 will automatically setup an association to the intended receiver. 465 Upon the successful association setup a SCTP_COMM_UP 466 notification will be dispatched to the socket at both the sender and 467 receiver side. This notification can be read by the recvmsg() system 468 call (see Section 3.1.3). 470 Note, if the SCTP stack at the sender side supports bundling, the 471 first user message may be bundled with the COOKIE ECHO message 472 [SCTP]. 474 When the SCTP stack sets up a new association implicitly, it first 475 consults the sctp_initmsg structure, which is passed along within 476 the ancillary data in the sendmsg() call (see Section 5.2.1 for 477 details of the data structures), for any special options to be used 478 on the new association. 480 If this information is not present in the sendmsg() call, or if the 481 implicit association setup is triggered by a sendto() call, the 482 default association initialization parameters will be used. These 483 default association parameters may be set with respective 484 setsockopt() calls or be left to the system defaults. 486 Implicit association setup cannot be initiated by send()/recv() 487 calls. 489 3.3 Non-blocking mode 490 Some SCTP users might want to avoid blocking when they call 491 socket interface function. 493 Whenever the user which want to avoid blocking must call select() 494 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and 495 check the socket status is writable or readable. If the socket 496 status isn't writeable or readable, the user should not call 497 sendmsg()/sendto() and recvmsg()/recvfrom(). 499 Once all bind() calls are complete on a UDP-style socket, the 500 application must set the non-blocking option by a fcntl() (such as 501 O_NONBLOCK). After which the sendmsg() function returns 502 immediately, and the success or failure of the data message (and 503 possible SCTP_INITMSG parameters) will be signaled by the 504 SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or 505 CANT_START_ASSOC. If user data could not be sent (due to a 506 CANT_START_ASSOC), the sender will also receive a SCTP_SEND_FAILED 507 event. Those event(s) can be received by the user calling of 508 recvmsg(). A server (having called listen()) is also notified of an 509 association up event by the reception of a SCTP_ASSOC_CHANGE with 510 SCTP_COMM_UP via the calling of recvmsg() and possibly the 511 reception of the first data message. 513 In order to shutdown the association gracefully, the user must call 514 sendmsg() with no data and with the MSG_EOF flag set. The function 515 returns immediately, and completion of the graceful shutdown is 516 indicated by an SCTP_ASSOC_CHANGE notification of type 517 SHUTDOWN_COMPLETE (see section 5.3.1.1). 519 4. TCP-style Interface 521 The goal of this model is to follow as closely as possible the 522 current practice of using the sockets interface for a connection 523 oriented protocol, such as TCP. This model enables existing 524 applications using connection oriented protocols to be ported to 525 SCTP with very little effort. 527 Note that some new SCTP features and some new SCTP socket options 528 can only be utilized through the use of sendmsg() and recvmsg() 529 calls, see Section 4.1.8. 531 4.1 Basic Operation 533 A typical server in TCP-style model uses the following system call 534 sequence to prepare an SCTP endpoint for servicing requests: 536 1. socket() 537 2. bind() 538 3. listen() 539 4. accept() 541 The accept() call blocks until a new association is set up. It 542 returns with a new socket descriptor. The server then uses the new 543 socket descriptor to communicate with the client, using recv() and 544 send() calls to get requests and send back responses. 546 Then it calls 548 5. close() 550 to terminate the association. 552 A typical client uses the following system call sequence to setup an 553 association with a server to request services: 555 1. socket() 556 2. connect() 558 After returning from connect(), the client uses send() and recv() 559 calls to send out requests and receive responses from the server. 561 The client calls 563 3. close() 565 to terminate this association when done. 567 4.1.1 socket() - TCP Style Syntax 569 Applications calls socket() to create a socket descriptor to 570 represent an SCTP endpoint. 572 The syntax is: 574 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 576 or, 578 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 580 Here, SOCK_STREAM indicates the creation of a TCP-style socket. 582 The first form creates an endpoint which can use only IPv4 583 addresses, while the second form creates an endpoint which can use 584 both IPv6 and mapped IPv4 addresses. 586 4.1.2 bind() - TCP Style Syntax 588 Applications use bind() to pass an address to be associated with an 589 SCTP endpoint to the system. bind() allows only either a single 590 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 591 endpoint can be associated with multiple addresses. To do this, 592 sctp_bindx() is introduced in section 8.1 to help applications do 593 the job of associating multiple addresses. 595 These addresses associated with a socket are the eligible transport 596 addresses for the endpoint to send and receive data. The endpoint 597 will also present these addresses to its peers during the 598 association initialization process, see [SCTP]. 600 The syntax is: 602 int bind(int sd, struct sockaddr *addr, int addrlen); 604 sd - the socket descriptor returned by socket() call. 605 addr - the address structure (either struct sockaddr_in or struct 606 sockaddr_in6 defined in [RFC 2553]). 607 addrlen - the size of the address structure. 609 If sd is an IPv4 socket, the address passed must be an IPv4 address. 610 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 611 either be an IPv4 or an IPv6 address. 613 Applications cannot call bind() multiple times to associate multiple 614 addresses to the endpoint. After the first call to bind(), all 615 subsequent calls will return an error. 617 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 618 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 619 operating system will associate the endpoint with an optimal address 620 set of the available interfaces. 622 If a bind() or sctp_bindx() is not called prior to the connect() 623 call, the system picks an ephemeral port and will choose an address 624 set equivalent to binding with a wildcard address. One of those 625 addresses will be the primary address for the association. This 626 automatically enables the multi-homing capability of SCTP. 628 The completion of this bind() process does not ready the SCTP 629 endpoint to accept inbound SCTP association requests. Until a 630 listen() system call, described below, is performed on the socket, 631 the SCTP endpoint will promptly reject an inbound SCTP INIT request 632 with an SCTP ABORT. 634 4.1.3 listen() - TCP Style Syntax 636 Applications use listen() to ready the SCTP endpoint for accepting 637 inbound associations. 639 The syntax is: 641 int listen(int sd, int backlog); 643 sd - the socket descriptor of the SCTP endpoint. 644 backlog - this specifies the max number of outstanding associations 645 allowed in the socket's accept queue. These are the 646 associations that have finished the four-way initiation 647 handshake (see Section 5 of [SCTP]) and are in the 648 ESTABLISHED state. Note, a backlog of '0' indicates 649 that the caller no longer wishes to receive new 650 associations. 652 4.1.4 accept() - TCP Style Syntax 654 Applications use accept() call to remove an established SCTP 655 association from the accept queue of the endpoint. A new socket 656 descriptor will be returned from accept() to represent the newly 657 formed association. 659 The syntax is: 661 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 663 new_sd - the socket descriptor for the newly formed association. 664 sd - the listening socket descriptor. 665 addr - on return, will contain the primary address of the peer 666 endpoint. 667 addrlen - on return, will contain the size of addr. 669 4.1.5 connect() - TCP Style Syntax 671 Applications use connect() to initiate an association to a peer. 673 The syntax is 675 int connect(int sd, const struct sockaddr *addr, int addrlen); 677 sd - the socket descriptor of the endpoint. 678 addr - the peer's address. 679 addrlen - the size of the address. 681 This operation corresponds to the ASSOCIATE primitive described in 682 section 10.1 of [SCTP]. 684 By default, the new association created has only one outbound 685 stream. The SCTP_INITMSG option described in Section 7.1.3 should be 686 used before connecting to change the number of outbound streams. 688 If a bind() or sctp_bindx() is not called prior to the connect() 689 call, the system picks an ephemeral port and will choose an address 690 set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 691 and IPv6 socket respectively. One of those addresses will be the 692 primary address for the association. This automatically enables the 693 multi-homing capability of SCTP. 695 Note that SCTP allows data exchange, similar to T/TCP [RFC1644], 696 during the association set up phase. If an application wants to do 697 this, it cannot use connect() call. Instead, it should use sendto() 698 or sendmsg() to initiate an association. If it uses sendto() and it 699 wants to change initialization behavior, it needs to use the 700 SCTP_INITMSG socket option before calling sendto(). Or it can use 701 SCTP_INIT type sendmsg() to initiate an association without doing 702 the setsockopt(). 704 SCTP does not support half close semantics. This means that unlike 705 T/TCP, MSG_EOF should not be set in the flags parameter when calling 706 sendto() or sendmsg() when the call is used to initiate a 707 connection. MSG_EOF is not an acceptable flag with SCTP socket. 709 4.1.6 close() - TCP Style Syntax 711 Applications use close() to gracefully close down an association. 713 The syntax is: 715 int close(int sd); 717 sd - the socket descriptor of the association to be closed. 719 After an application calls close() on a socket descriptor, no 720 further socket operations will succeed on that descriptor. 722 4.1.7 shutdown() - TCP Style Syntax 724 SCTP differs from TCP in that it does not have half closed 725 semantics. Hence the shutdown() call for SCTP is an approximation 726 of the TCP shutdown() call, and solves some different problems. 727 Full TCP-compatibility is not provided, so developers porting TCP 728 applications to SCTP may need to recode sections that use 729 shutdown(). (Note that it is possible to achieve the same results 730 as half close in SCTP using SCTP streams.) 732 The syntax is: 734 int shutdown(int socket, int how); 736 sd - the socket descriptor of the association to be closed. 738 how - Specifies the type of shutdown. The values are 739 as follows: 741 SHUT_RD 742 Disables further receive operations. No SCTP 743 protocol action is taken. 745 SHUT_WR 746 Disables further send operations, and initiates 747 the SCTP shutdown sequence. 749 SHUT_RDWR 750 Disables further send and receive operations 751 and initiates the SCTP shutdown sequence. 753 The major difference between SCTP and TCP shutdown() is that SCTP 754 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 755 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 756 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 757 the SCTP association while still leaving the socket descriptor open, 758 so that the caller can receive back any data SCTP was unable to 759 deliver (see section 5.3.1.4 for more information). 761 To perform the ABORT operation described in [SCTP] section 10.1, an 762 application can use the socket option SO_LINGER. It is described in 763 section 7.1.4. 765 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax 767 With a TCP-style socket, the application can also use sendmsg() and 768 recvmsg() to transmit data to and receive data from its peer. The 769 semantics is similar to those used in the UDP-style model (section 770 3.1.3), with the following differences: 772 1) When sending, the msg_name field in the msghdr is not used to 773 specify the intended receiver, rather it is used to indicate a 774 different peer address if the sender does not want to send the 775 message over the primary address of the receiver. If the transport 776 address given is not part of the current association, the data will 777 not be sent and a SCTP_SEND_FAILED event will be delivered to the 778 application if send failure events are enabled. 780 When receiving, if a message is not received from the primary 781 address, the SCTP stack will fill in the msg_name field on return so 782 that the application can retrieve the source address information of 783 the received message. 785 2) An application must use close() to gracefully shutdown an 786 association, or use SO_LINGER option with close() to abort an 787 association. It must not use the MSG_ABORT or MSG_EOF flag in 788 sendmsg(). The system returns an error if an application tries to 789 do so. 791 4.1.9 getpeername() 793 Applications use getpeername() to retrieve the primary socket 794 address of the peer. This call is for TCP compatibility, and is not 795 multi-homed.It does not work with UDP-style sockets. See section 8.3 796 for a multi-homed/UDP-sockets version of the call. 798 The syntax is: 800 int getpeername(int socket, struct sockaddr *address, 801 socklen_t *len); 803 sd - the socket descriptor to be queried. 805 address - On return, the peer primary address is stored in 806 this buffer. If the socket is an IPv4 socket, the 807 address will be IPv4. If the socket is an IPv6 socket, 808 the address will be either an IPv6 or mapped IPv4 809 address. 811 len - The caller should set the length of address here. 813 On return, this is set to the length of the returned 814 address. 816 If the actual length of the address is greater than the length of 817 the supplied sockaddr structure, the stored address will be 818 truncated. 820 5. Data Structures 822 We discuss in this section important data structures which are 823 specific to SCTP and are used with sendmsg() and recvmsg() calls to 824 control SCTP endpoint operations and to access ancillary 825 information and notifications. 827 5.1 The msghdr and cmsghdr Structures 829 The msghdr structure used in the sendmsg() and recvmsg() calls, as 830 well as the ancillary data carried in the structure, is the key for 831 the application to set and get various control information from the 832 SCTP endpoint. 834 The msghdr and the related cmsghdr structures are defined and 835 discussed in details in [RFC2292]. Here we will cite their 836 definitions from [RFC2292]. 838 The msghdr structure: 840 struct msghdr { 841 void *msg_name; /* ptr to socket address structure */ 842 socklen_t msg_namelen; /* size of socket address structure */ 843 struct iovec *msg_iov; /* scatter/gather array */ 844 size_t msg_iovlen; /* # elements in msg_iov */ 845 void *msg_control; /* ancillary data */ 846 socklen_t msg_controllen; /* ancillary data buffer length */ 847 int msg_flags; /* flags on received message */ 848 }; 850 The cmsghdr structure: 852 struct cmsghdr { 853 socklen_t cmsg_len; /* #bytes, including this header */ 854 int cmsg_level; /* originating protocol */ 855 int cmsg_type; /* protocol-specific type */ 856 /* followed by unsigned char cmsg_data[]; */ 857 }; 859 In the msghdr structure, the usage of msg_name has been discussed in 860 previous sections (see Sections 3.1.3 and 4.1.8). 862 The scatter/gather buffers, or I/O vectors (pointed to by the 863 msg_iov field) are treated as a single SCTP data chunk, rather than 864 multiple chunks, for both sendmsg() and recvmsg(). 866 The msg_flags are not used when sending a message with sendmsg(). 868 If a notification has arrived, recvmsg() will return the 869 notification with the MSG_NOTIFICATION flag set in msg_flags. If the 870 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 871 section 5.3 for more information about notifications. 873 If all portions of a data frame or notification have been read, 874 recvmsg() will return with MSG_EOR set in msg_flags. 876 5.2 SCTP msg_control Structures 878 A key element of all SCTP-specific socket extensions is the use of 879 ancillary data to specify and access SCTP-specific data via the 880 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 881 Fine-grained control over initialization and sending parameters are 882 handled with ancillary data. 884 Each ancillary data item is proceeded by a struct cmsghdr (see 885 Section 5.1), which defines the function and purpose of the data 886 contained in in the cmsg_data[] member. 888 There are two kinds of ancillary data used by SCTP: initialization 889 data, and, header information (SNDRCV). Initialization data 890 (UDP-style only) sets protocol parameters for new associations. 891 Section 5.2.1 provides more details. Header information can set or 892 report parameters on individual messages in a stream. See section 893 5.2.2 for how to use SNDRCV ancillary data. 895 By default on a TCP-style socket, SCTP will pass no ancillary data; 896 on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and 897 SCTP_ASSOC_CHANGE information. Specific ancillary data items can be 898 enabled with socket options defined for SCTP; see section 7.3. 900 Note that all ancillary types are fixed length; see section 5.4 for 901 further discussion on this. These data structures use struct 902 sockaddr_storage (defined in [RFC2553]) as a portable, fixed length 903 address format. 905 Other protocols may also provide ancillary data to the socket layer 906 consumer. These ancillary data items from other protocols may 907 intermingle with SCTP data. For example, the IPv6 socket API 908 definitions ([RFC2292] and [RFC2553]) define a number of ancillary 909 data items. If a socket API consumer enables delivery of both SCTP 910 and IPv6 ancillary data, they both may appear in the same 911 msg_control buffer in any order. An application may thus need to 912 handle other types of ancillary data besides that passed by SCTP. 914 The sockets application must provide a buffer large enough to 915 accommodate all ancillary data provided via recvmsg(). If the buffer 916 is not large enough, the ancillary data will be truncated and the 917 msghdr's msg_flags will include MSG_CTRUNC. 919 5.2.1 SCTP Initiation Structure (SCTP_INIT) 920 This cmsghdr structure provides information for initializing new 921 SCTP associations with sendmsg(). The SCTP_INITMSG socket option 922 uses this same data structure. This structure is not used for 923 recvmsg(). 925 cmsg_level cmsg_type cmsg_data[] 926 ------------ ------------ ---------------------- 927 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 929 Here is the definition of the sctp_initmsg structure: 931 struct sctp_initmsg { 932 uint16_t sinit_num_ostreams; 933 uint16_t sinit_max_instreams; 934 uint16_t sinit_max_attempts; 935 uint16_t sinit_max_init_timeo; 936 }; 938 sinit_num_ostreams: 16 bits (unsigned integer) 940 This is an integer number representing the number of streams that 941 the application wishes to be able to send to. This number is 942 confirmed in the SCTP_COMM_UP notification and must be verified 943 since it is a negotiated number with the remote endpoint. The 944 default value of 0 indicates to use the endpoint default value. 946 sinit_max_instreams: 16 bits (unsigned integer) 948 This value represents the maximum number of inbound streams the 949 application is prepared to support. This value is bounded by the 950 actual implementation. In other words the user MAY be able to 951 support more streams than the Operating System. In such a case, the 952 Operating System limit overrides the value requested by the 953 user. The default value of 0 indicates to use the endpoint's default 954 value. 956 sinit_max_attempts: 16 bits (unsigned integer) 958 This integer specifies how many attempts the SCTP endpoint should 959 make at resending the INIT. This value overrides the system SCTP 960 'Max.Init.Retransmits' value. The default value of 0 indicates to 961 use the endpoint's default value. This is normally set to the 962 system's default 'Max.Init.Retransmit' value. 964 sinit_max_init_timeo: 16 bits (unsigned integer) 966 This value represents the largest Time-Out or RTO value to use in 967 attempting a INIT. Normally the 'RTO.Max' is used to limit the 968 doubling of the RTO upon timeout. For the INIT message this value 969 MAY override 'RTO.Max'. This value MUST NOT influence 'RTO.Max' 970 during data transmission and is only used to bound the initial setup 971 time. A default value of 0 indicates to use the endpoint's default 972 value. This is normally set to the system's 'RTO.Max' value (60 973 seconds). 975 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 977 This cmsghdr structure specifies SCTP options for sendmsg() and 978 describes SCTP header information about a received message through 979 recvmsg(). 981 cmsg_level cmsg_type cmsg_data[] 982 ------------ ------------ ---------------------- 983 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 985 Here is the definition of sctp_sndrcvinfo: 987 struct sctp_sndrcvinfo { 988 uint16_t sinfo_stream; 989 uint16_t sinfo_ssn; 990 uint16_t sinfo_flags; 991 uint32_t sinfo_ppid; 992 uint32_t sinfo_context; 993 uint32_t sinfo_timetolive; 994 uint32_t sinfo_tsn; 995 sctp_assoc_t sinfo_assoc_id; 996 }; 998 sinfo_stream: 16 bits (unsigned integer) 1000 For recvmsg() the SCTP stack places the message's stream number in 1001 this value. For sendmsg() this value holds the stream number that 1002 the application wishes to send this message to. If a sender 1003 specifies an invalid stream number an error indication is returned 1004 and the call fails. 1006 sinfo_ssn: 16 bits (unsigned integer) 1008 For recvmsg() this value contains the stream sequence number that 1009 the remote endpoint placed in the DATA chunk. For fragmented 1010 messages this is the same number for all deliveries of the message 1011 (if more than one recvmsg() is needed to read the message). The 1012 sendmsg() call will ignore this parameter. 1014 sinfo_ppid: 32 bits (unsigned integer) 1016 This value in sendmsg() is an opaque unsigned value that is passed 1017 to the remote end in each user message. In recvmsg() this value is 1018 the same information that was passed by the upper layer in the peer 1019 application. Please note that byte order issues are NOT accounted 1020 for and this information is passed opaquely by the SCTP stack from 1021 one end to the other. 1023 sinfo_context: 32 bits (unsigned integer) 1025 This value is an opaque 32 bit context datum that is used in the 1026 sendmsg() function. This value is passed back to the upper layer if 1027 a error occurs on the send of a message and is retrieved with each 1028 undelivered message (Note: if a endpoint has done multiple sends, all 1029 of which fail, multiple different sinfo_context values will be 1030 returned. One with each user data message). 1032 sinfo_flags: 16 bits (unsigned integer) 1034 This field may contain any of the following flags and is composed of 1035 a bitwise OR of these values. 1037 recvmsg() flags: 1039 MSG_UNORDERED - This flag is present when the message was sent 1040 non-ordered. 1042 sendmsg() flags: 1044 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1045 message. If this flag is clear the datagram is 1046 considered an ordered send. 1048 MSG_ADDR_OVER - This flag, in the UDP model, requests the SCTP 1049 stack to override the primary destination address 1050 with the address found with the sendto/sendmsg 1051 call. 1053 MSG_ABORT - Setting this flag causes the specified association 1054 to abort by sending an ABORT message to the peer 1055 (UDP-style only). 1057 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1058 procedures on the specified association. Graceful 1059 shutdown assures that all data enqueued by both 1060 endpoints is successfully transmitted before closing 1061 the association (UDP-style only). 1063 sinfo_timetolive: 32 bit (unsigned integer) 1065 For the sending side, this field contains the message time 1066 to live in milliseconds. The sending side will expire the 1067 message within the specified time period if the message as 1068 not been sent to the peer within this time period. This value 1069 will override any default value set using any socket option. 1070 Also note that the value of 0 is special in that it indicates 1071 no timeout should occur on this message. 1073 sinfo_tsn: 32 bit (unsigned integer) 1075 For the receiving side, this field holds a TSN that was 1076 assigned to one of the SCTP Data Chunks. 1078 sinfo_assoc_id: sizeof (sctp_assoc_t) 1080 The association handle field, sinfo_assoc_id, holds the identifier 1081 for the association announced in the SCTP_COMM_UP notification. 1083 All notifications for a given association have the same identifier. 1084 Ignored for TCP-style sockets. 1086 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1088 5.3 SCTP Events and Notifications 1090 An SCTP application may need to understand and process events and 1091 errors that happen on the SCTP stack. These events include network 1092 status changes, association startups, remote operational errors and 1093 undeliverable messages. All of these can be essential for the 1094 application. 1096 When an SCTP application layer does a recvmsg() the message read is 1097 normally a data message from a peer endpoint. If the application 1098 wishes to have the SCTP stack deliver notifications of non-data 1099 events, it sets the appropriate socket option for the notifications 1100 it wants. See section 7.3 for these socket options. When a 1101 notification arrives, recvmsg() returns the notification in the 1102 application-supplied data buffer via msg_iov, and sets 1103 MSG_NOTIFICATION in msg_flags. 1105 Multiple notifications may be returned to a single recvmsg() 1106 call. 1108 This section details the notification structures. Every 1109 notification structure carries some common fields which provides 1110 general information. 1112 A recvmsg() call will return only one notification at a time. Just 1113 as when reading normal data, it may return part of a notification if 1114 the msg_iov buffer is not large enough. If a single read is not 1115 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1116 reading the notification before subsequent data can arrive. 1118 5.3.1 SCTP Notification Structure 1120 The notification structure is defined as the union of all 1121 notification types. 1123 union sctp_notification { 1124 struct { 1125 uint16_t sn_type; /* Notification type. */ 1126 uint16_t sn_flags; 1127 uint32_t sn_length; 1128 } h; 1129 struct sctp_assoc_change sn_assoc_change; 1130 struct sctp_paddr_change sn_padr_change; 1131 struct sctp_remote_error sn_remote_error; 1132 struct sctp_send_failed sn_send_failed; 1133 struct sctp_shutdown_event sn_shutdown_event; 1134 struct sctp_adaption_event sn_adaption_event; 1135 struct sctp_rcv_pdapi_event sn_rcv_pdapi_event; 1136 }; 1138 sn_type: 16 bits (unsigned integer) 1140 The following table describes the SCTP notification and event types 1141 for the field sn_type. 1143 sn_type Description 1144 --------- --------------------------- 1146 SCTP_ASSOC_CHANGE This tag indicates that an 1147 association has either been 1148 opened or closed. Refer to 1149 5.3.1.1 for details. 1151 SCTP_PEER_ADDR_CHANGE This tag indicates that an 1152 address that is part of an existing 1153 association has experienced a 1154 change of state (e.g. a failure 1155 or return to service of the 1156 reachability of a endpoint 1157 via a specific transport 1158 address). Please see 5.3.1.2 1159 for data structure details. 1161 SCTP_REMOTE_ERROR The attached error message 1162 is an Operational Error received from 1163 the remote peer. It includes the complete 1164 TLV sent by the remote endpoint. 1165 See section 5.3.1.3 for the detailed format. 1167 SCTP_SEND_FAILED The attached datagram 1168 could not be sent to the remote endpoint. 1169 This structure includes the 1170 original SCTP_SNDRCVINFO 1171 that was used in sending this 1172 message i.e. this structure 1173 uses the sctp_sndrecvinfo per 1174 section 5.3.1.4. 1176 SCTP_SHUTDOWN_EVENT The peer has sent a SHUTDOWN. No further 1177 data should be sent on this socket. 1179 SCTP_ADAPTION_INDICATION This notification holds the 1180 peers indicated adaption layer. 1181 Please see 5.3.1.6. 1183 SCTP_PARTIAL_DELIVERY_EVENT This notification is used to 1184 tell a receiver that the partial 1185 delivery has been aborted. This 1186 may indicate the association is 1187 about to be aborted. Please see 1188 5.3.1.7. 1190 All standard values for sn_type flags are greater than 2^15. 1191 Values from 2^15 and down are reserved. 1193 sn_flags: 16 bits (unsigned integer) 1195 These are notification-specific flags. 1197 sn_length: 32 bits (unsigned integer) 1199 This is the length of the whole sctp_notification structure 1200 including the sn_type, sn_flags, and sn_length fields. 1202 5.3.1.1 SCTP_ASSOC_CHANGE 1204 Communication notifications inform the ULP that an SCTP association 1205 has either begun or ended. The identifier for a new association is 1206 provided by this notification. The notification information has the 1207 following format: 1209 struct sctp_assoc_change { 1210 uint16_t sac_type; 1211 uint16_t sac_flags; 1212 uint32_t sac_length; 1213 uint16_t sac_state; 1214 uint16_t sac_error; 1215 uint16_t sac_outbound_streams; 1216 uint16_t sac_inbound_streams; 1217 sctp_assoc_t sac_assoc_id; 1218 }; 1220 sac_type: 1222 It should be SCTP_ASSOC_CHANGE. 1224 sac_flags: 16 bits (unsigned integer) 1226 Currently unused. 1228 sac_length: 32 bits (unsigned integer) 1230 This field is the total length of the notification data, including 1231 the notification header. 1233 sac_state: 16 bits (signed integer) 1235 This field holds one of a number of values that communicate the 1236 event that happened to the association. They include: 1238 Event Name Description 1239 ---------------- --------------- 1240 SCTP_COMM_UP A new association is now ready 1241 and data may be exchanged with this 1243 peer. 1245 SCTP_COMM_LOST The association has failed. The association 1246 is now in the closed state. If SEND FAILED 1247 notifications are turned on, a SCTP_COMM_LOST 1248 is followed by a series of SCTP_SEND_FAILED 1249 events, one for each outstanding message. 1251 SCTP_RESTART SCTP has detected that the peer has restarted. 1253 SCTP_SHUTDOWN_COMP The association has gracefully closed. 1255 SCTP_CANT_STR_ASSOC The association failed to setup. If non blocking 1256 mode is set and data was sent (in the udp mode), 1257 a SCTP_CANT_STR_ASSOC is followed by a series of 1258 SCTP_SEND_FAILED events, one for each outstanding 1259 message. 1261 sac_error: 16 bits (signed integer) 1263 If the state was reached due to a error condition (e.g. 1264 SCTP_COMM_LOST) any relevant error information is available in 1265 this field. This corresponds to the protocol error codes defined in 1266 [SCTP]. 1268 sac_outbound_streams: 16 bits (unsigned integer) 1269 sac_inbound_streams: 16 bits (unsigned integer) 1271 The maximum number of streams allowed in each direction are 1272 available in sac_outbound_streams and sac_inbound streams. 1274 sac_assoc_id: sizeof (sctp_assoc_t) 1276 The association id field, holds the identifier for the association. 1277 All notifications for a given association have the same association 1278 identifier. For TCP style socket, this field is ignored. 1280 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1282 When a destination address on a multi-homed peer encounters a change 1283 an interface details event is sent. The information has the 1284 following structure: 1286 struct sctp_paddr_change { 1287 uint16_t spc_type; 1288 uint16_t spc_flags; 1289 uint32_t spc_length; 1290 struct sockaddr_storage spc_aaddr; 1291 int spc_state; 1292 int spc_error; 1293 sctp_assoc_t spc_assoc_id; 1294 } 1296 spc_type: 1298 It should be SCTP_PEER_ADDR_CHANGE. 1300 spc_flags: 16 bits (unsigned integer) 1302 Currently unused. 1304 spc_length: 32 bits (unsigned integer) 1306 This field is the total length of the notification data, including 1307 the notification header. 1309 spc_aaddr: sizeof (struct sockaddr_storage) 1311 The affected address field, holds the remote peer's address that is 1312 encountering the change of state. 1314 spc_state: 32 bits (signed integer) 1316 This field holds one of a number of values that communicate the 1317 event that happened to the address. They include: 1319 Event Name Description 1320 ---------------- --------------- 1321 SCTP_ADDR_AVAILABLE This address is now reachable. 1323 SCTP_ADDR_UNREACHABL The address specified can no 1324 longer be reached. Any data sent 1325 to this address is rerouted to an 1326 alternate until this address becomes 1327 reachable. 1329 SCTP_ADDR_REMOVED The address is no longer part of 1330 the association. 1332 SCTP_ADDR_ADDED The address is now part of the 1333 association. 1335 SCTP_ADDR_MADE_PRIM This address has now been made 1336 to be the primary destination address. 1338 spc_error: 32 bits (signed integer) 1340 If the state was reached due to any error condition (e.g. 1341 SCTP_ADDR_UNREACHABL) any relevant error information is available in 1342 this field. 1344 spc_assoc_id: sizeof (sctp_assoc_t) 1346 The association id field, holds the identifier for the association. 1347 All notifications for a given association have the same association 1348 identifier. For TCP style socket, this field is ignored. 1350 5.3.1.3 SCTP_REMOTE_ERROR 1351 A remote peer may send an Operational Error message to its peer. 1352 This message indicates a variety of error conditions on an 1353 association. The entire error TLV as it appears on the wire is 1354 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1355 specification [SCTP] and any extensions for a list of possible 1356 error formats. SCTP error TLVs have the format: 1358 struct sctp_remote_error { 1359 uint16_t sre_type; 1360 uint16_t sre_flags; 1361 uint32_t sre_length; 1362 uint16_t sre_error; 1363 sctp_assoc_t sre_assoc_id; 1364 uint8_t sre_data[0]; 1365 }; 1367 sre_type: 1369 It should be SCTP_REMOTE_ERROR. 1371 sre_flags: 16 bits (unsigned integer) 1373 Currently unused. 1375 sre_length: 32 bits (unsigned integer) 1377 This field is the total length of the notification data, including 1378 the notification header and the contents of sre_data. 1380 sre_error: 16 bits (unsigned integer) 1382 This value represents one of the Operational Error causes defined in 1383 the SCTP specification, in network byte order. 1385 sre_assoc_id: sizeof (sctp_assoc_t) 1387 The association id field, holds the identifier for the association. 1388 All notifications for a given association have the same association 1389 identifier. For TCP style socket, this field is ignored. 1391 sre_data: variable 1393 This contains the payload of the operational error as defined in the 1394 SCTP specification [SCTP] section 3.3.10. 1396 5.3.1.4 SCTP_SEND_FAILED 1398 If SCTP cannot deliver a message it may return the message as a 1399 notification. 1401 struct sctp_send_failed { 1402 uint16_t ssf_type; 1403 uint16_t ssf_flags; 1405 uint32_t ssf_length; 1406 uint32_t ssf_error; 1407 struct sctp_sndrcvinfo ssf_info; 1408 sctp_assoc_t ssf_assoc_id; 1409 uint8_t ssf_data[0]; 1410 }; 1412 ssf_type: 1414 It should be SCTP_SEND_FAILED. 1416 ssf_flags: 16 bits (unsigned integer) 1418 The flag value will take one of the following values 1420 SCTP_DATA_UNSENT - Indicates that the data was never put on 1421 the wire. 1423 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1424 Note that this does not necessarily mean that the 1425 data was (or was not) successfully delivered. 1427 ssf_length: 32 bits (unsigned integer) 1429 This field is the total length of the notification data, including 1430 the notification header and the payload in ssf_data. 1432 ssf_error: 16 bits (unsigned integer) 1434 This value represents the reason why the send failed, and if set, 1435 will be a SCTP protocol error code as defined in [SCTP] section 1436 3.3.10. 1438 ssf_info: sizeof (struct sctp_sndrcvinfo) 1440 The original send information associated with the undelivered 1441 message. 1443 ssf_assoc_id: sizeof (sctp_assoc_t) 1445 The association id field, sf_assoc_id, holds the identifier for the 1446 association. All notifications for a given association have the 1447 same association identifier. For TCP style socket, this field is 1448 ignored. 1450 ssf_data: variable length 1452 The undelivered message, exactly as delivered by the caller to the 1453 original send*() call. 1455 5.3.1.5 SCTP_SHUTDOWN_EVENT 1457 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1458 inform the application that it should cease sending data. 1460 struct sctp_shutdown_event { 1461 uint16_t sse_type; 1462 uint16_t sse_flags; 1463 uint32_t sse_length; 1464 sctp_assoc_t sse_assoc_id; 1465 }; 1467 sse_type 1469 It should be SCTP_SHUTDOWN_EVENT 1471 sse_flags: 16 bits (unsigned integer) 1473 Currently unused. 1475 sse_length: 32 bits (unsigned integer) 1477 This field is the total length of the notification data, including 1478 the notification header. It will generally be 1479 sizeof (struct sctp_shutdown_event). 1481 sse_flags: 16 bits (unsigned integer) 1483 Currently unused. 1485 sse_assoc_id: sizeof (sctp_assoc_t) 1487 The association id field, holds the identifier for the association. 1488 All notifications for a given association have the same association 1489 identifier. For TCP style socket, this field is ignored. 1491 5.3.1.6 SCTP_ADAPTION_INDICATION 1493 When a peer sends a Adaption Layer Indication parameter , SCTP 1494 delivers this notification to inform the application 1495 that of the peers requested adaption layer. 1497 struct sctp_adaption_event { 1498 uint16_t sai_type; 1499 uint16_t sai_flags; 1500 uint32_t sai_length; 1501 uint32_t sai_adaptation_bits; 1502 sctp_assoc_t sse_assoc_id; 1503 }; 1505 sai_type 1507 It should be SCTP_ADAPTION_INDICATION 1509 sai_flags: 16 bits (unsigned integer) 1510 Currently unused. 1512 sai_length: 32 bits (unsigned integer) 1514 This field is the total length of the notification data, including 1515 the notification header. It will generally be 1516 sizeof (struct sctp_adaption_event). 1518 sai_adaption_bits: 32 bits (unsigned integer) 1520 This field holds the bit array sent by the peer in the 1521 adaption layer indication parameter. The bits are in 1522 network byte order. 1524 sai_assoc_id: sizeof (sctp_assoc_t) 1526 The association id field, holds the identifier for the association. 1527 All notifications for a given association have the same association 1528 identifier. For TCP style socket, this field is ignored. 1530 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT 1532 When a receiver is engaged in a partial delivery of a 1533 message this notification will be used to indicate 1534 various events. 1536 struct sctp_rcv_pdapi_event { 1537 uint16_t pdapi_type; 1538 uint16_t pdapi_flags; 1539 uint32_t pdapi_length; 1540 uint32_t pdapi_indication; 1541 sctp_assoc_t pdapi_assoc_id; 1542 }; 1544 pdapi_type 1546 It should be SCTP_ADAPTION_INDICATION 1548 pdapi_flags: 16 bits (unsigned integer) 1550 Currently unused. 1552 pdapi_length: 32 bits (unsigned integer) 1554 This field is the total length of the notification data, including 1555 the notification header. It will generally be 1556 sizeof (struct sctp_rcv_pdapi_event). 1558 pdapi_indication: 32 bits (unsigned integer) 1560 This field holds the indication being sent to the 1561 application possible values include: 1563 SCTP_PARTIAL_DELIVERY_ABORTED 1564 pdapi_assoc_id: sizeof (sctp_assoc_t) 1566 The association id field, holds the identifier for the association. 1567 All notifications for a given association have the same association 1568 identifier. For TCP style socket, this field is ignored. 1570 5.4 Ancillary Data Considerations and Semantics 1572 Programming with ancillary socket data contains some subtleties and 1573 pitfalls, which are discussed below. 1575 5.4.1 Multiple Items and Ordering 1577 Multiple ancillary data items may be included in any call to 1578 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1579 items, or both. 1581 The ordering of ancillary data items (either by SCTP or another 1582 protocol) is not significant and is implementation-dependent, so 1583 applications must not depend on any ordering. 1585 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1586 msg_iov member. There can be only a single SCTP_SNDRCV info for 1587 each sendmsg() or recvmsg() call. 1589 5.4.2 Accessing and Manipulating Ancillary Data 1591 Applications can infer the presence of data or ancillary data by 1592 examining the msg_iovlen and msg_controllen msghdr members, 1593 respectively. 1595 Implementations may have different padding requirements for 1596 ancillary data, so portable applications should make use of the 1597 macros CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and 1598 CMSG_LEN. See [RFC2292] and your SCTP implementation's documentation 1599 for more information. Following is an example, from [RFC2292], 1600 demonstrating the use of these macros to access ancillary data: 1602 struct msghdr msg; 1603 struct cmsghdr *cmsgptr; 1605 /* fill in msg */ 1607 /* call recvmsg() */ 1609 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1610 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1611 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1612 u_char *ptr; 1614 ptr = CMSG_DATA(cmsgptr); 1615 /* process data pointed to by ptr */ 1617 } 1618 } 1620 5.4.3 Control Message Buffer Sizing 1622 The information conveyed via SCTP_SNDRCV events will often be 1623 fundamental to the correct and sane operation of the sockets 1624 application. This is particularly true of the UDP semantics, but 1625 also of the TCP semantics. For example, if an application needs to 1626 send and receive data on different SCTP streams, SCTP_SNDRCV events 1627 are indispensable. 1629 Given that some ancillary data is critical, and that multiple 1630 ancillary data items may appear in any order, applications should be 1631 carefully written to always provide a large enough buffer to contain 1632 all possible ancillary data that can be presented by recvmsg(). If 1633 the buffer is too small, and crucial data is truncated, it may pose 1634 a fatal error condition. 1636 Thus it is essential that applications be able to deterministically 1637 calculate the maximum required buffer size to pass to recvmsg(). One 1638 constraint imposed on this specification that makes this possible is 1639 that all ancillary data definitions are of a fixed length. One way 1640 to calculate the maximum required buffer size might be to take the 1641 sum the sizes of all enabled ancillary data item structures, as 1642 calculated by CMSG_SPACE. For example, if we enabled 1643 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC2292], we would calculate 1644 and allocate the buffer size as follows: 1646 size_t total; 1647 void *buf; 1649 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1650 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1652 buf = malloc(total); 1654 We could then use this buffer for msg_control on each call to 1655 recvmsg() and be assured that we would not lose any ancillary data 1656 to truncation. 1658 6. Common Operations for Both Styles 1660 6.1 send(), recv(), sendto(), recvfrom() 1662 Applications can use send() and sendto() to transmit data to the 1663 peer of an SCTP endpoint. recv() and recvfrom() can be used to 1664 receive data from the peer. 1666 The syntax is: 1668 ssize_t send(int sd, connst void *msg, size_t len, int flags); 1669 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1670 const struct sockaddr *to, int tolen); 1671 ssize_t recv(int sd, void *buf, size_t len, int flags); 1672 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1673 struct sockaddr *from, int *fromlen); 1675 sd - the socket descriptor of an SCTP endpoint. 1676 msg - the message to be sent. 1677 len - the size of the message or the size of buffer. 1678 to - one of the peer addresses of the association to be 1679 used to send the message. 1680 tolen - the size of the address. 1681 buf - the buffer to store a received message. 1682 from - the buffer to store the peer address used to send the 1683 received message. 1684 fromlen - the size of the from address 1685 flags - (described below). 1687 These calls give access to only basic SCTP protocol features. If 1688 either peer in the association uses multiple streams, or sends 1689 unordered data these calls will usually be inadequate, and may 1690 deliver the data in unpredictable ways. 1692 SCTP has the concept of multiple streams in one association. The 1693 above calls do not allow the caller to specify on which stream a 1694 message should be sent. The system uses stream 0 as the default 1695 stream for send() and sendto(). recv() and recvfrom() return data 1696 from any stream, but the caller can not distinguish the different 1697 streams. This may result in data seeming to arrive out of 1698 order. Similarly, if a data chunk is sent unordered, recv() and 1699 recvfrom() provide no indication. 1701 SCTP is message based. The msg buffer above in send() and sendto() 1702 is considered to be a single message. This means that if the caller 1703 wants to send a message which is composed by several buffers, the 1704 caller needs to combine them before calling send() or sendto(). 1705 Alternately, the caller can use sendmsg() to do that without 1706 combining them. recv() and recvfrom() cannot distinguish message 1707 boundaries. 1709 In receiving, if the buffer supplied is not large enough to hold a 1710 complete message, the receive call acts like a stream socket and 1711 returns as much data as will fit in the buffer. 1713 Note, the send and recv calls, when used in the UDP-style model, may 1714 only be used with branched off socket descriptors (see Section 8.2). 1716 Note, if an application calls a send function with no user data 1717 and no ancillary data the SCTP implementation should reject the 1718 request with an appropriate error message. An implementation is 1719 NOT allowed to send a Data chunk with no user data [RFC2960]. 1721 6.2 setsockopt(), getsockopt() 1723 Applications use setsockopt() and getsockopt() to set or retrieve 1724 socket options. Socket options are used to change the default 1725 behavior of sockets calls. They are described in Section 7. 1727 The syntax is: 1729 ret = getsockopt(int sd, int level, int optname, void *optval, 1730 size_t *optlen); 1731 ret = setsockopt(int sd, int level, int optname, const void *optval, 1732 size_t optlen); 1734 sd - the socket descript. 1735 level - set to IPPROTO_SCTP for all SCTP options. 1736 optname - the option name. 1737 optval - the buffer to store the value of the option. 1738 optlen - the size of the buffer (or the length of the option 1739 returned). 1741 6.3 read() and write() 1743 Applications can use read() and write() to send and receive data to 1744 and from peer. They have the same semantics as send() and recv() 1745 except that the flags parameter cannot be used. 1747 Note, these calls, when used in the UDP-style model, may only be 1748 used with branched off socket descriptors (see Section 8.2). 1750 6.4 getsockname() 1752 Applications use getsockname() to retrieve the locally-bound socket 1753 address of the specified socket. This is especially useful if the 1754 caller let SCTP chose a local port. This call is for where the 1755 endpoint is not multi-homed. It does not work well with multi-homed 1756 sockets. See section 8.5 for a multi-homed version of the call. 1758 The syntax is: 1760 int getsockname(int socket, struct sockaddr *address, 1761 socklen_t *len); 1763 sd - the socket descriptor to be queried. 1765 address - On return, one locally bound address (chosen by 1766 the SCTP stack) is stored in this buffer. If the 1767 socket is an IPv4 socket, the address will be IPv4. 1768 If the socket is an IPv6 socket, the address will 1769 be either an IPv6 or mapped IPv4 address. 1771 len - The caller should set the length of address here. 1772 On return, this is set to the length of the returned 1773 address. 1775 If the actual length of the address is greater than the length of 1776 the supplied sockaddr structure, the stored address will be 1777 truncated. 1779 If the socket has not been bound to a local name, the value stored 1780 in the object pointed to by address is unspecified. 1782 7. Socket Options 1784 The following sub-section describes various SCTP level socket 1785 options that are common to both models. SCTP associations can be 1786 multi-homed. Therefore, certain option parameters include a 1787 sockaddr_storage structure to select which peer address the option 1788 should be applied to. 1790 For the UDP-style sockets, an sctp_assoc_t structure (association 1791 ID) is used to identify the the association instance that the 1792 operation affects. So it must be set when using this model. 1794 For the TCP-style sockets and branched off UDP-style sockets (see 1795 section 8.2) this association ID parameter is ignored. In the cases 1796 noted below where the parameter is ignored, an application can pass 1797 to the system a corresponding option structure similar to those 1798 described below but without the association ID parameter, which 1799 should be the last field of the option structure. This can make the 1800 option setting/getting operation more efficient. If an application 1801 does this, it should also specify an appropriate optlen value 1802 (i.e. sizeof (option parameter) - sizeof (struct sctp_assoc_t)). 1804 Note that socket or IP level options is set or retrieved per socket. 1805 This means that for UDP-style sockets, those options will be applied 1806 to all associations belonging to the socket. And for TCP-style 1807 model, those options will be applied to all peer addresses of the 1808 association controlled by the socket. Applications should be very 1809 careful in setting those options. 1811 sctp_opt_info() 1813 For some implementations getsockopt() is read-only, so a new 1814 interface will be needed when information must be passed both in 1815 to and out of the SCTP stack. The syntax for scpt_opt_info() is, 1817 int sctp_opt_info(int sd, 1818 sctp_assoc_t id, 1819 int opt, 1820 void *arg, 1821 size_t *size); 1823 For UDP-style sockets, id specifies the association to query. For 1824 TCP-style sockets, id is ignored. 1826 opt specifies which SCTP socket option to get. It can 1827 any socket option currently supported that requests information 1828 (either read/write options or read only) such as: 1830 SCTP_RTOINFO 1831 SCTP_ASSOCINFO 1832 SCTP_SET_PRIMARY_ADDR 1833 SCTP_SET_PEER_PRIMARY_ADDR 1834 SCTP_SET_STREAM_TIMEOUTS 1835 SCTP_SET_PEER_ADDR_PARAMS 1836 SCTP_STATUS 1837 SCTP_GET_PEER_ADDR_INFO 1839 arg is an option-specific structure buffer provided by the caller. 1840 See 8.5 subsections for more information on these options and 1841 option-specific structures. 1843 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1844 sets errno to the appropriate error code. 1846 For those implementations that DO support a read/write 1847 getsocketopt interface a simple macro wrapper can be 1848 created to support the sctp_opt_info() interface such as: 1850 #define sctp_opt_info(fd,asoc,opt,arg,sz) \ 1851 do { \ 1852 if((opt == SCTP_RTOINFO) || \ 1853 (opt == SCTP_ASSOCINFO) || \ 1854 (opt == SCTP_SET_PRIMARY_ADDR) || \ 1855 (opt == SCTP_SET_PEER_PRIMARY_ADDR) || \ 1856 (opt == SCTP_SET_STREAM_TIMEOUTS) || \ 1857 (opt == SCTP_SET_PEER_ADDR_PARAMS) || \ 1858 (opt == SCTP_STATUS) || \ 1859 (opt == SCTP_GET_PEER_ADDR_INFO)){ \ 1860 *(sctp_assoc_t *)arg = asoc; \ 1861 return(getsockopt(fd,IPPROTO_SCTP,opt,arg,sz)); \ 1862 }else{ \ 1863 return(ENOTSUP); \ 1864 } \ 1865 }while(0); 1867 All options that support specific settings on an association 1868 by filling in either an association id variable or a 1869 sockaddr_storage SHOULD also support setting of the same 1870 value for the entire endpoint (i.e. future associations). 1871 To accomplish this the following logic is used when 1872 setting one of these options: 1874 a) If an address is specified via a sockaddr_storage that 1875 is included in the structure the address is used to 1876 lookup the association and the settings are applied to 1877 the specific address (if appropriate) or to the entire 1878 association. 1880 b) If an association identification is filled in but not a 1881 sockaddr_storage (if present) the association is found 1882 using the association identification and the settings 1883 should be applied to the entire association (since a specific 1884 address is specified). Note this also applies to options that 1885 hold an association identification in their structure but do not 1886 have a sockaddr_storage field. 1888 c) If neither the sockaddr_storage or association identification is set 1889 i.e. the sockadd_storage is set to all 0's (INADDR_ANY) and the 1890 association identification is 0, the settings are a default and 1891 to be applied to the endpoint (all future associations). 1893 7.1 Read / Write Options 1895 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1897 The protocol parameters used to initialize and bound retransmission 1898 timeout (RTO) are tunable. See [SCTP] for more information on how 1899 these parameters are used in RTO calculation. The peer address 1900 parameter is ignored for TCP style socket. 1902 The following structure is used to access and modify these 1903 parameters: 1905 struct sctp_rtoinfo { 1906 sctp_assoc_t srto_assoc_id; 1907 uint32_t srto_initial; 1908 uint32_t srto_max; 1909 uint32_t srto_min; 1910 }; 1912 srto_initial - This contains the initial RTO value. 1913 srto_max and srto_min - These contain the maximum and minimum bounds 1914 for all RTOs. 1915 srto_assoc_id - (UDP style socket) This is filled in the application, 1916 and identifies the association for this query. If 1917 this parameter is missing (on a UDP style socket), 1918 then the change effects the entire endpoint. 1920 All parameters are time values, in milliseconds. A value of 0, when 1921 modifying the parameters, indicates that the current value should 1922 not be changed. 1924 To access or modify these parameters, the application should call 1925 getsockopt or setsockopt() respectively with the option name 1926 SCTP_RTOINFO. 1928 7.1.2 Association Parameters (SCTP_ASSOCINFO) 1930 This option is used to both examine and set various association 1931 and endpoint parameters. 1933 See [SCTP] for more information on how this parameter is used. The 1934 peer address parameter is ignored for TCP style socket. 1936 The following structure is used to access and modify this 1937 parameters: 1939 struct sctp_assocparams { 1940 sctp_assoc_t sasoc_assoc_id; 1941 uint16_t sasoc_asocmaxrxt; 1942 uint16_t sasoc_number_peer_destinations; 1943 uint32_t sasoc_peer_rwnd; 1944 uint32_t sasoc_local_rwnd; 1945 uint32_t sasoc_cookie_life; 1946 }; 1948 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 1949 to make for the association. 1951 sasoc_number_peer_destinations - This is the number of destination 1952 address that the peer considers 1953 valid. 1954 sasoc_peer_rwnd - This holds the current value of the peers 1955 rwnd (reported in the last SACK) minus any 1956 outstanding data (i.e. data inflight). 1957 sasoc_local_rwnd - This holds the last reported rwnd that was 1958 sent to the peer. 1959 sasoc_cookie_life - This is the associations cookie life value 1960 used when issuing cookies. 1962 sasoc_assoc_id - (UDP style socket) This is filled in the application, 1963 and identifies the association for this query. 1965 This information may be examined for either the 1966 endpoint or a specific association. To examine a endpoints 1967 default parameters the association id (sasoc_assoc_id) should 1968 must be set to the value '0'. The values of the sasoc_peer_rwnd 1969 is meaningless when examining endpoint information. 1971 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may 1972 be set on either an endpoint or association basis. The 1973 rwnd and destination counts (sasoc_number_peer_destinations, 1974 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any 1975 value placed in these is ignored. 1977 To access or modify these parameters, the application should call 1978 getsockopt or setsockopt() respectively with the option name 1979 SCTP_ASSOCRTXINFO. 1981 The maximum number of retransmissions before an address is 1982 considered unreachable is also tunable, but is address-specific, so 1983 it is covered in a separate option. If an application attempts to 1984 set the value of the association maximum retransmission parameter to 1985 more than the sum of all maximum retransmission parameters, 1986 setsockopt() shall return an error. The reason for this, from 1987 [SCTP] section 8.2: 1989 Note: When configuring the SCTP endpoint, the user should avoid 1990 having the value of 'Association.Max.Retrans' larger than the 1991 summation of the 'Path.Max.Retrans' of all the destination addresses 1992 for the remote endpoint. Otherwise, all the destination addresses 1993 may become inactive while the endpoint still considers the peer 1994 endpoint reachable. 1996 7.1.3 Initialization Parameters (SCTP_INITMSG) 1998 Applications can specify protocol parameters for the default 1999 association initialization. The structure used to access and modify 2000 these parameters is defined in section 5.2.1. The option name 2001 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2003 Setting initialization parameters is effective only on an 2004 unconnected socket (for UDP-style sockets only future associations 2005 are effected by the change). With TCP-style sockets, this option is 2006 inherited by sockets derived from a listener socket. 2008 7.1.4 SO_LINGER 2010 An application using the TCP-style socket can use this option to 2011 perform the SCTP ABORT primitive. The linger option structure is: 2013 struct linger { 2014 int l_onoff; /* option on/off */ 2015 int l_linger; /* linger time */ 2016 }; 2018 To enable the option, set l_onoff to 1. If the l_linger value is 2019 set to 0, calling close() is the same as the ABORT primitive. If 2020 the value is set to a negative value, the setsockopt() call will 2021 return an error. If the value is set to a positive value 2022 linger_time, the close() can be blocked for at most linger_time ms. 2023 If the graceful shutdown phase does not finish during this period, 2024 close() will return but the graceful shutdown phase continues in the 2025 system. 2027 7.1.5 SCTP_NODELAY 2029 Turn off any Nagle-like algorithm. This means that packets are 2030 generally sent as soon as possible and no unnecessary delays are 2031 introduced, at the cost of more packets in the network. Expects an 2032 integer boolean flag. 2034 7.1.6 SO_RCVBUF 2036 Sets receive buffer size. For SCTP TCP-style sockets, this controls 2037 the receiver window size. For UDP-style sockets, this controls the 2038 receiver window size for all associations bound to the socket 2039 descriptor used in the setsockopt() or getsockopt() call. The option 2040 applies to each association's window size separately. Expects an 2041 integer. 2043 7.1.7 SO_SNDBUF 2045 Sets send buffer size. For SCTP TCP-style sockets, this controls the 2046 amount of data SCTP may have waiting in internal buffers to be 2047 sent. This option therefore bounds the maximum size of data that can 2048 be sent in a single send call. For UDP-style sockets, the effect is 2049 the same, except that it applies to all associations bound to the 2050 socket descriptor used in the setsockopt() or getsockopt() call. The 2051 option applies to each association's window size separately. Expects 2052 an integer. 2054 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 2056 This socket option is applicable to the UDP-style socket only. When 2057 set it will cause associations that are idle for more than the 2058 specified number of seconds to automatically close. An association 2059 being idle is defined an association that has NOT sent or received 2060 user data. The special value of '0' indicates that no automatic 2061 close of any associations should be performed. The option expects 2062 an integer defining the number of seconds of idle time before 2063 an association is closed. 2065 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) 2067 Requests that the peer mark the enclosed address as the association 2068 primary. The enclosed address must be one of the association's 2069 locally bound addresses. The following structure is used to make a 2070 set primary request: 2072 struct sctp_setprim { 2073 sctp_assoc_t ssp_assoc_id; 2074 struct sockaddr_storage ssp_addr; 2075 }; 2077 ssp_addr The address to set as primary 2078 ssp_assoc_id (UDP style socket) This is filled in by the 2079 application, and identifies the association 2080 for this request. 2082 This functionality is optional. Implementations that do not support 2083 this functionality should return EOPNOTSUPP. 2085 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2087 Requests that the local SCTP stack use the enclosed peer address as 2088 the association primary. The enclosed address must be one of the 2089 association peer's addresses. The following structure is used to 2090 make a set peer primary request: 2092 struct sctp_setpeerprim { 2093 sctp_assoc_t sspp_assoc_id; 2094 struct sockaddr_storage sspp_addr; 2095 }; 2097 sspp_addr The address to set as primary 2098 sspp_assoc_id (UDP style socket) This is filled in by the 2099 application, and identifies the association 2100 for this request. 2102 7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER) 2104 Requests that the local endpoint set the specified Adaption Layer 2105 Indication parameter for all future 2106 INIT and INIT-ACK exchanges. 2108 struct sctp_setadaption { 2109 u_int32_t ssb_adaption_ind; 2110 }; 2112 ssb_adaption_ind The adaption layer indicator that will be included 2113 in any outgoing Adaption Layer Indication 2114 parameter. 2116 7.1.12 Set default message time outs (SCTP_SET_STREAM_TIMEOUTS) 2118 This option requests that the requested stream apply a 2119 default time-out for messages in queue. The default value 2120 is used when the application does not specify a timeout 2121 in the sendrcvinfo structure (sinfo_timetolive element 2122 see section 5.2.2). 2124 struct sctp_setstrm_timeout { 2125 sctp_assoc_t ssto_assoc_id; 2126 u_int32_t ssto_timeout; 2127 u_int16_t ssto_streamid_start; 2128 u_int16_t ssto_streamid_end; 2129 }; 2131 ssto_assoc_id (UDP style socket) This is filled in by the 2132 application, and identifies the association 2133 for this request. 2134 ssto_timeout The maximum time in milliseconds that messages 2135 should be held inqueue before failure. 2136 ssto_streamid_start The beginning stream identifier to apply this 2137 default against. 2138 ssto_streamid_end The ending stream identifier to apply this 2139 default against. 2141 Note that a timeout value of 0 indicates that no inqueue timeout 2142 should be applied against the stream. 2144 7.1.13 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2146 This option is a on/off flag. If enabled no SCTP message 2147 fragmentation will be performed. Instead if a message 2148 being sent exceeds the current PMTU size, the message will 2149 NOT be sent and instead a error will be indicated to the user. 2151 7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) 2153 Applications can enable or disable heartbeats for any peer address 2154 of an association, modify an address's heartbeat interval, force a 2155 heartbeat to be sent immediately, and adjust the address's maximum 2156 number of retransmissions sent before an address is considered 2157 unreachable. The following structure is used to access and modify an 2158 address's parameters: 2160 struct sctp_paddrparams { 2161 sctp_assoc_t spp_assoc_id; 2162 struct sockaddr_storage spp_address; 2163 uint32_t spp_hbinterval; 2164 uint16_t spp_pathmaxrxt; 2165 }; 2167 spp_assoc_id - (UDP style socket) This is filled in the application, 2168 and identifies the association for this query. 2169 spp_address - This specifies which address is of interest. 2170 spp_hbinterval - This contains the value of the heartbeat interval, 2171 in milliseconds. A value of 0, when modifying the 2172 parameter, specifies that the heartbeat on this 2173 address should be disabled. A value of UINT32_MAX 2174 (4294967295), when modifying the parameter, 2175 specifies that a heartbeat should be sent 2176 immediately to the peer address, and the current 2177 interval should remain unchanged. 2178 spp_pathmaxrxt - This contains the maximum number of 2179 retransmissions before this address shall be 2180 considered unreachable. 2182 To read or modify these parameters, the application should call 2183 sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. 2185 7.1.15 Set default send parameters (SET_DEFAULT_SEND_PARAM) 2187 Applications that wish to use the sendto() system call may wish 2188 to specify a default set of parameters that would normally be 2189 supplied through the inclusion of ancillary data. This socket 2190 option allows such an application to set the default 2191 sctp_sndrcvinfo structure. The application that wishes 2192 to use this socket option simply passes in to this 2193 call the sctp_sndrcvinfo structure defined in section 5.2.2 2194 The input parameters accepted by this call include 2195 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, 2196 sinfo_timetolive. The user must provide the sinfo_assoc_id 2197 field in to this call if the caller is using the UDP model. 2199 7.1.16 Set notification and ancillary events (SCTP_SET_EVENTS) 2201 This socket option is used to specify various notifications 2202 and ancillary data the user wishes to receive. Please see 2203 section 7.3 for a full description of this option and its 2204 usage. 2206 7.2 Read-Only Options 2207 7.2.1 Association Status (SCTP_STATUS) 2209 Applications can retrieve current status information about an 2210 association, including association state, peer receiver window size, 2211 number of unacked data chunks, and number of data chunks pending 2212 receipt. This information is read-only. The following structure is 2213 used to access this information: 2215 struct sctp_status { 2216 sctp_assoc_t sstat_assoc_id; 2217 int32_t sstat_state; 2218 uint32_t sstat_rwnd; 2219 uint16_t sstat_unackdata; 2220 uint16_t sstat_penddata; 2221 uint16_t sstat_instrms; 2222 uint16_t sstat_outstrms; 2223 uint32_t sstat_fragmentation_point; 2224 struct sctp_paddrinfo sstat_primary; 2225 }; 2227 sstat_state - This contains the association's current state one 2228 of the following values: 2230 SCTP_CLOSED 2231 SCTP_BOUND 2232 SCTP_LISTEN 2233 SCTP_COOKIE_WAIT 2234 SCTP_COOKIE_ECHOED 2235 SCTP_ESTABLISHED 2236 SCTP_SHUTDOWN_PENDING 2237 SCTP_SHUTDOWN_SENT 2238 SCTP_SHUTDOWN_RECEIVED 2239 SCTP_SHUTDOWN_ACK_SENT 2241 sstat_rwnd - This contains the association peer's current 2242 receiver window size. 2243 sstat_unackdata - This is the number of unacked data chunks. 2244 sstat_penddata - This is the number of data chunks pending receipt. 2245 sstat_primary - This is information on the current primary peer 2246 address. 2247 sstat_assoc_id - (UDP style socket) This holds the an identifier for the 2248 association. All notifications for a given association 2249 have the same association identifier. 2251 sstat_instrms - The number of streams that the peer will 2252 be using inbound. 2254 sstat_outstrms - The number of streams that the endpoint is 2255 allowed to use outbound. 2257 sstat_fragmentation_point - The size at which SCTP fragmentation 2258 will occur. 2260 To access these status values, the application calls getsockopt() 2261 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2262 ignored for TCP style socket. 2264 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2266 Applications can retrieve information about a specific peer address 2267 of an association, including its reachability state, congestion 2268 window, and retransmission timer values. This information is 2269 read-only. The following structure is used to access this 2270 information: 2272 struct sctp_paddrinfo { 2273 sctp_assoc_t spinfo_assoc_id; 2274 struct sockaddr_storage spinfo_address; 2275 int32_t spinfo_state; 2276 uint32_t spinfo_cwnd; 2277 uint32_t spinfo_srtt; 2278 uint32_t spinfo_rto; 2279 uint32_t spinfo_mtu; 2280 }; 2282 spinfo_address - This is filled in the application, and contains 2283 the peer address of interest. 2285 On return from getsockopt(): 2287 spinfo_state - This contains the peer addresses's state (either 2288 SCTP_ACTIVE or SCTP_INACTIVE). 2289 spinfo_cwnd - This contains the peer addresses's current congestion 2290 window. 2291 spinfo_srtt - This contains the peer addresses's current smoothed 2292 round-trip time calculation in milliseconds. 2293 spinfo_rto - This contains the peer addresses's current 2294 retransmission timeout value in milliseconds. 2295 spinfo_mtu - The current P-MTU of this address. 2296 spinfo_assoc_id - (UDP style socket) This is filled in the application, 2297 and identifies the association for this query. 2299 To retrieve this information, use sctp_opt_info() with the 2300 SCTP_GET_PEER_ADDR_INFO options. 2302 7.3. Ancillary Data and Notification Interest Options 2304 Applications can receive per-message ancillary information and 2305 notifications of certain SCTP events with recvmsg(). 2307 The following optional information is available to the application: 2309 1. SCTP_SNDRCV: Per-message information (i.e. stream number, 2310 TSN, SSN, etc. described in section 5.2.2) 2311 2. SCTP_ASSOC_CHANGE: (described in section 5.3.1.1) 2312 3. SCTP_PEER_ADDR_CHANGE: (described in section 5.3.1.2) 2313 4. SCTP_REMOTE_ERROR: (described in section 5.3.1.3) 2314 5. SCTP_SEND_FAILED: (described in section 5.3.1.4) 2315 6. SCTP_SHUTDOWN_EVENT: (described in section 5.3.1.5) 2316 7. SCTP_ADAPTION_INDICATION: (described in section 5.3.1.6) 2317 8. SCTP_PARTIAL_DELIVERY_EVENT: (described in section 5.3.1.7) 2319 To receive any ancillary data or notifications, first the 2320 application registers it's interest by calling the SCTP_SET_EVENTS 2321 setsockopt() with the following structure. 2323 struct sctp_event_subscribe{ 2324 u_int8_t sctp_data_io_event; 2325 u_int8_t sctp_association_event; 2326 u_int8_t sctp_address_event; 2327 u_int8_t sctp_send_failure_event; 2328 u_int8_t sctp_peer_error_event; 2329 u_int8_t sctp_shutdown_event; 2330 u_int8_t sctp_partial_delivery_event; 2331 u_int8_t sctp_adaption_layer_event; 2332 }; 2334 sctp_data_io_event - Setting this flag to 1 will cause the 2335 reception of SCTP_SNDRCV information on a per message basis. 2336 The application will need to use the recvmsg() interface so 2337 that it can receive the event information contained in the 2338 msg_control field. Please see section 5.2 for further details. 2339 Setting the flag to 0 will disable reception of the message 2340 control information. 2342 sctp_association_event - Setting this flag to 1 will enable 2343 the reception of association event notifications. Setting 2344 the flag to 0 will disable association event notifications. 2345 For more information on event notifications please see section 2346 5.3. 2348 sctp_address_event - Setting this flag to 1 will enable 2349 the reception of address event notifications. Setting 2350 the flag to 0 will disable address event notifications. 2351 For more information on event notifications please see section 2352 5.3. 2354 sctp_send_failure_event - Setting this flag to 1 will enable 2355 the reception of send failure event notifications. Setting 2356 the flag to 0 will disable send failure event notifications. 2357 For more information on event notifications please see section 2358 5.3. 2360 sctp_peer_error_event - Setting this flag to 1 will enable 2361 the reception of peer error event notifications. Setting 2362 the flag to 0 will disable peer error event notifications. 2363 For more information on event notifications please see section 2364 5.3. 2366 sctp_shutdown_event - Setting this flag to 1 will enable 2367 the reception of shutdown event notifications. Setting 2368 the flag to 0 will disable shutdown event notifications. 2369 For more information on event notifications please see section 2370 5.3. 2372 sctp_partial_delivery_event - Setting this flag to 1 will enable 2373 the reception of partial delivery notifications. Setting 2374 the flag to 0 will disable partial delivery event notifications. 2375 For more information on event notifications please see section 2376 5.3. 2378 sctp_adaption_layer_event - Setting this flag to 1 will enable 2379 the reception of adaption layer notifications. Setting 2380 the flag to 0 will disable adaption layer event notifications. 2381 For more information on event notifications please see section 2382 5.3. 2384 An example where an application would like to receive data 2385 io events and association events but no others would be 2386 as follows: 2388 { 2389 struct sctp_event_subscribe event; 2391 memset(&event,0,sizeof(event)); 2393 event.sctp_data_io_event = 1; 2394 event.sctp_association_event = 1; 2396 setsockopt(fd, IPPROTO_SCTP, SCTP_SET_EVENT, &event, sizeof(event)); 2397 } 2399 Note that for UDP-style SCTP sockets, the caller of recvmsg() 2400 receives ancillary data and notifications for ALL associations bound 2401 to the file descriptor. For TCP-style SCTP sockets, the caller 2402 receives ancillary data and notifications for only the single 2403 association bound to the file descriptor. 2405 By default a TCP-style socket has all options off. 2407 By default a UDP-style socket has sctp_data_io_event and 2408 sctp_association_event on and all other options off. 2410 8. New Interfaces 2412 Depending on the system, the following interface can be implemented 2413 as a system call or library function. 2415 8.1 sctp_bindx() 2417 The syntax of sctp_bindx() is, 2418 int sctp_bindx(int sd, struct sockaddr_storage *addrs, int addrcnt, 2419 int flags); 2421 If sd is an IPv4 socket, the addresses passed must be IPv4 2422 addresses. If the sd is an IPv6 socket, the addresses passed can 2423 either be IPv4 or IPv6 addresses. 2425 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2426 section 3.1.2 for this usage. 2428 addrs is a pointer to an array of one or more socket addresses. 2429 Each address is contained in a struct sockaddr_storage, so each 2430 address is a fixed length. The caller specifies the number of 2431 addresses in the array with addrcnt. 2433 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2434 -1, and sets errno to the appropriate error code. 2436 For SCTP, the port given in each socket address must be the same, or 2437 sctp_bindx() will fail, setting errno to EINVAL. 2439 The flags parameter is formed from the bitwise OR of zero or more of 2440 the following currently defined flags: 2442 SCTP_BINDX_ADD_ADDR 2443 SCTP_BINDX_REM_ADDR 2445 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2446 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the 2447 given addresses from the association. The two flags are mutually 2448 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 2449 caller may not remove all addresses from an association; 2450 sctp_bindx() will reject such an attempt with EINVAL. 2452 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2453 additional addresses with an endpoint after calling bind(). Or use 2454 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2455 socket is associated with so that no new association accepted will 2456 be associated with those addresses. If the endpoint supports dynamic 2457 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause 2458 a endpoint to send the appropriate message to the peer to 2459 change the peers address lists. 2461 Adding and removing addresses from a connected association is 2462 optional functionality. Implementations that do not support this 2463 functionality should return EOPNOTSUPP. 2465 8.2 Branched-off Association 2467 After an association is established on a UDP-style socket, the 2468 application may wish to branch off the association into a separate 2469 socket/file descriptor. 2471 This is particularly desirable when, for instance, the application 2472 wishes to have a number of sporadic message senders/receivers remain 2473 under the original UDP-style socket but branch off those 2474 associations carrying high volume data traffic into their own 2475 separate socket descriptors. 2477 The application uses sctp_peeloff() call to branch off an 2478 association into a separate socket (Note the semantics are somewhat 2479 changed from the traditional TCP-style accept() call). 2481 The syntax is: 2483 new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id) 2485 new_sd - the new socket descriptor representing the branched-off 2486 association. 2488 sd - the original UDP-style socket descriptor returned from the 2489 socket() system call (see Section 3.1.1). 2491 assoc_id - the specified identifier of the association that is to be 2492 branched off to a separate file descriptor (Note, in a 2493 traditional TCP-style accept() call, this would be an out 2494 parameter, but for the UDP-style call, this is an in 2495 parameter). 2497 8.3 sctp_getpaddrs() 2499 sctp_getpaddrs() returns all peer addresses in an association. The 2500 syntax is, 2502 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2503 struct sockaddr_storage **addrs); 2505 On return, addrs will point to a dynamically allocated array of 2506 struct sockaddr_storages, one for each peer address. The caller 2507 should use sctp_freepaddrs() to free the memory. addrs must not be 2508 NULL. 2510 If sd is an IPv4 socket, the addresses returned will be all IPv4 2511 addresses. If sd is an IPv6 socket, the addresses returned can be a 2512 mix of IPv4 or IPv6 addresses. 2514 For UDP-style sockets, id specifies the association to query. For 2515 TCP-style sockets, id is ignored. 2517 On success, sctp_getpaddrs() returns the number of peer addresses in 2518 the association. If there is no association on this socket, 2519 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2520 an error occurs, sctp_getpaddrs() returns -1, and the value of 2521 *addrs is undefined. 2523 8.4 sctp_freepaddrs() 2524 sctp_freepaddrs() frees all resources allocated by 2525 sctp_getpaddrs(). Its syntax is, 2527 void sctp_freepaddrs(struct sockaddr_storage *addrs); 2529 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2531 8.5 sctp_getladdrs() 2533 sctp_getladdrs() returns all locally bound address on a socket. The 2534 syntax is, 2536 int sctp_getladdrs(int sock, sctp_assoc_t id, 2537 struct sockaddr_storage **ss); 2539 On return, addrs will point to a dynamically allocated array of 2540 struct sockaddr_storages, one for each local address. The caller 2541 should use sctp_freeladdrs() to free the memory. addrs must not be 2542 NULL. 2544 If sd is an IPv4 socket, the addresses returned will be all IPv4 2545 addresses. If sd is an IPv6 socket, the addresses returned can be a 2546 mix of IPv4 or IPv6 addresses. 2548 For UDP-style sockets, id specifies the association to query. For 2549 TCP-style sockets, id is ignored. 2551 If the id field is set to the value '0' then the locally bound 2552 addresses are returned without regard to any particular association. 2554 On success, sctp_getladdrs() returns the number of local addresses 2555 bound to the socket. If the socket is unbound, sctp_getladdrs() 2556 returns 0, and the value of *addrs is undefined. If an error occurs, 2557 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2559 8.6 sctp_freeladdrs() 2561 sctp_freeladdrs() frees all resources allocated by 2562 sctp_getladdrs(). Its syntax is, 2564 void sctp_freeladdrs(struct sockaddr_storage *addrs); 2566 addrs is the array of peer addresses returned by sctp_getladdrs(). 2568 9. Security Considerations 2570 Many TCP and UDP implementations reserve port numbers below 1024 for 2571 privileged users. If the target platform supports privileged users, 2572 the SCTP implementation SHOULD restrict the ability to call bind() 2573 or sctp_bindx() on these port numbers to privileged users. 2575 Similarly unprevledged users should not be able to set protocol 2576 parameters which could result in the congestion control algorithm 2577 being more aggressive than permitted on the public Internet. These 2578 parameters are: 2580 struct sctp_rtoinfo 2582 If an unprivileged user inherits a UDP-style socket with open 2583 associations on a privileged port, it MAY be permitted to accept new 2584 associations, but it SHOULD NOT be permitted to open new 2585 associations. This could be relevant for the r* family of 2586 protocols. 2588 10. Acknowledgments 2590 The authors wish to thank Kavitha Baratakke, Mike Bartlett, 2591 Jon Berger, Scott Kimble, Renee Revis, and many others on 2592 the TSVWG mailing list for contributing valuable comments. 2594 11. Authors' Addresses 2596 Randall R. Stewart Tel: +1-815-477-2127 2597 Cisco Systems, Inc. EMail: rrs@cisco.com 2598 Crystal Lake, IL 60012 2599 USA 2601 Qiaobing Xie Tel: +1-847-632-3028 2602 Motorola, Inc. EMail: qxie1@email.mot.com 2603 1501 W. Shure Drive, Room 2309 2604 Arlington Heights, IL 60004 2605 USA 2607 La Monte H.P. Yarroll NIC Handle: LY 2608 Motorola, Inc. EMail: piggy@acm.org 2609 1501 W. Shure Drive, IL27-2315 2610 Arlington Heights, IL 60004 2611 USA 2613 Jonathan Wood 2614 DoCoMo USA Labs Email: jonwood@speakeasy.net 2615 181 Metro Drive, Suite 300 2616 San Jose, CA 95110 2617 USA 2619 Kacheong Poon 2620 Sun Microsystems, Inc. Email: kacheong.poon@sun.com 2621 901 San Antonio Road 2622 Palo Alto, CA 94303 2623 USA 2625 Ken Fujita Tel: +1-408-863-6045 2626 NEC Corporation Email: fken@cd.jp.nec.com 2627 Cupertino, CA 2629 12. References 2630 [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2631 September 1981. 2633 [RFC768] Postel, J. (ed.), "User Datagram Protocol", STD 6, RFC 768, 2634 August 1980. 2636 [RFC1644] Braden, R., "T/TCP -- TCP Extensions for Transactions 2637 Functional Specification," RFC 1644, July 1994. 2639 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", 2640 RFC 2026, October 1996. 2642 [RFC2292] W.R. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 2643 RFC 2292, February 1998. 2645 [RFC2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens. "Basic Socket 2646 Interface Extensions for IPv6," RFC 2553, March 1999. 2648 [SCTP] R.R. Stewart, Q. Xie, K. Morneault, C. Sharp, H.J. Schwarzbauer, 2649 T. Taylor, I. Rytina, M. Kalla, L. Zhang, and, V. Paxson, 2650 "Stream Control Transmission Protocol," RFC2960, October 2000. 2652 [STEVENS] W.R. Stevens, M. Thomas, E. Nordmark, "Advanced Sockets API for 2653 IPv6," , November 2001 2654 (Work in progress) 2656 Appendix A: TCP-style Code Example 2658 The following code is a simple implementation of an echo server over 2659 SCTP. The example shows how to use some features of TCP-style IPv4 2660 SCTP sockets, including: 2662 o Opening, binding, and listening for new associations on a socket; 2663 o Enabling ancillary data 2664 o Enabling notifications 2665 o Using ancillary data with sendmsg() and recvmsg() 2666 o Using MSG_EOR to determine if an entire message has been read 2667 o Handling notifications 2669 static void 2670 handle_event(void *buf) 2671 { 2672 struct sctp_assoc_change *sac; 2673 struct sctp_send_failed *ssf; 2674 struct sctp_paddr_change *spc; 2675 struct sctp_remote_error *sre; 2676 union sctp_notification *snp; 2677 char addrbuf[INET6_ADDRSTRLEN]; 2678 const char *ap; 2679 struct sockaddr_in *sin; 2680 struct sockaddr_in6 *sin6; 2681 snp = buf; 2683 switch (snp->sn_type) { 2684 case SCTP_ASSOC_CHANGE: 2685 sac = &snp->sn_assoc_change; 2686 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2687 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2688 sac->sac_inbound_streams, sac->sac_outbound_streams); 2689 break; 2690 case SCTP_SEND_FAILED: 2691 ssf = &snp->sn_send_failed; 2692 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2693 ssf->ssf_error); 2694 break; 2696 case SCTP_PEER_ADDR_CHANGE: 2697 spc = &snp->sn_paddr_change; /* mt changed */ 2698 if (spc->spc_aaddr.ss_family == AF_INET) { 2699 sin = (struct sockaddr_in *)&spc->spc_aaddr; 2700 ap = inet_ntop(AF_INET, &sin->sin_addr, 2701 addrbuf, INET6_ADDRSTRLEN); 2702 } else { 2703 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 2704 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 2705 addrbuf, INET6_ADDRSTRLEN); 2706 } 2707 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2708 spc->spc_state, spc->spc_error); 2709 break; 2710 case SCTP_REMOTE_ERROR: 2711 sre = &snp->sn_remote_error; 2712 printf("^^^ remote_error: err=%hu len=%hu\n", 2713 ntohs(sre->sre_error), ntohs(sre->sre_len)); 2714 break; 2715 case SCTP_SHUTDOWN_EVENT: 2716 printf("^^^ shutdown event\n"); 2717 break; 2718 default: 2719 printf("unknown type: %hu\n", snp->sn_type); 2720 break; 2721 } 2722 } 2724 static void * 2725 sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2726 ssize_t *nrp, size_t cmsglen) 2727 { 2728 ssize_t nr = 0; 2729 struct iovec iov[1]; 2731 *nrp = 0; 2732 iov->iov_base = buf; 2733 msg->msg_iov = iov; 2734 msg->msg_iovlen = 1; 2736 for (;;) { 2737 msg->msg_flags = MSG_XPG4_2; 2738 msg->msg_iov->iov_len = *buflen; 2739 msg->msg_controllen = cmsglen; 2741 nr += recvmsg(fd, msg, 0); 2742 if (nr <= 0) { 2743 /* EOF or error */ 2744 *nrp = nr; 2745 return (NULL); 2746 } 2748 if ((msg->msg_flags & MSG_EOR) != 0) { 2749 *nrp = nr; 2750 return (buf); 2751 } 2753 /* Realloc the buffer? */ 2754 if (*buflen == nr) { 2755 buf = realloc(buf, *buflen * 2); 2756 if (buf == 0) { 2757 fprintf(stderr, "out of memory\n"); 2758 exit(1); 2759 } 2760 *buflen *= 2; 2761 } 2763 /* Set the next read offset */ 2764 iov->iov_base = (char *)buf + nr; 2765 iov->iov_len = *buflen - nr; 2767 } 2768 } 2770 static void 2771 echo(int fd, int socketModeUDP) 2772 { 2773 ssize_t nr; 2774 struct sctp_sndrcvinfo *sri; 2775 struct msghdr msg[1]; 2776 struct cmsghdr *cmsg; 2777 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 2778 char *buf; 2779 size_t buflen; 2780 struct iovec iov[1]; 2781 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 2783 /* Allocate the initial data buffer */ 2784 buflen = BUFLEN; 2785 if (!(buf = malloc(BUFLEN))) { 2786 fprintf(stderr, "out of memory\n"); 2787 exit(1); 2789 } 2791 /* Set up the msghdr structure for receiving */ 2792 memset(msg, 0, sizeof (*msg)); 2793 msg->msg_control = cbuf; 2794 msg->msg_controllen = cmsglen; 2795 msg->msg_flags = 0; 2796 cmsg = (struct cmsghdr *)cbuf; 2797 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 2799 /* Wait for something to echo */ 2800 while (buf = sctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 2802 /* Intercept notifications here */ 2803 if (msg->msg_flags & MSG_NOTIFICATION) { 2804 handle_event(buf); 2805 continue; 2806 } 2808 iov->iov_base = buf; 2809 iov->iov_len = nr; 2810 msg->msg_iov = iov; 2811 msg->msg_iovlen = 1; 2813 printf("got %u bytes on stream %hu:\n", nr, 2814 sri->sinfo_stream); 2815 write(0, buf, nr); 2817 /* Echo it back */ 2818 msg->msg_flags = MSG_XPG4_2; 2819 if (sendmsg(fd, msg, 0) < 0) { 2820 perror("sendmsg"); 2821 exit(1); 2822 } 2823 } 2825 if (nr < 0) { 2826 perror("recvmsg"); 2827 } 2828 if(socketModeUDP == 0) 2829 close(fd); 2830 } 2832 int main() 2833 { 2834 int lfd, cfd; 2835 int onoff = 1; 2836 struct sockaddr_in sin[1]; 2838 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 2839 perror("socket"); 2840 exit(1); 2841 } 2842 sin->sin_family = AF_INET; 2843 sin->sin_port = htons(7); 2844 sin->sin_addr.s_addr = INADDR_ANY; 2845 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2846 perror("bind"); 2847 exit(1); 2848 } 2850 if (listen(lfd, 1) == -1) { 2851 perror("listen"); 2852 exit(1); 2853 } 2855 /* Wait for new associations */ 2856 for (;;) { 2857 if ((cfd = accept(lfd, NULL, 0)) == -1) { 2858 perror("accept"); 2859 exit(1); 2860 } 2862 /* Enable ancillary data */ 2863 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, 2864 &onoff, 4) < 0) { 2865 perror("setsockopt RECVDATAIOEVNT"); 2866 exit(1); 2867 } 2868 /* Enable notifications */ 2869 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, 2870 &onoff, 4) < 0) { 2871 perror("setsockopt SCTP_RECVASSOCEVNT"); 2872 exit(1); 2873 } 2874 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2875 &onoff, 4) < 0) { 2876 perror("setsockopt SCTP_RECVASSOCEVNT"); 2877 exit(1); 2878 } 2879 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2880 &onoff, 4) < 0) { 2881 perror("setsockopt SCTP_RECVPADDREVNT"); 2882 exit(1); 2883 } 2884 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2885 &onoff, 4) < 0) { 2886 perror("setsockopt SCTP_RECVPEERERR"); 2887 exit(1); 2888 } 2889 if (setsockopt(cfd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2890 &onoff, 4) < 0) { 2891 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2892 exit(1); 2893 } 2895 /* Echo back any and all data */ 2896 echo(cfd,0); 2897 } 2898 } 2900 Appendix B: UDP-style Code Example 2902 The following code is a simple implementation of an echo server over 2903 SCTP. The example shows how to use some features of UDP-style IPv4 2904 SCTP sockets, including: 2906 o Opening and binding of a socket; 2907 o Enabling ancillary data 2908 o Enabling notifications 2909 o Using ancillary data with sendmsg() and recvmsg() 2910 o Using MSG_EOR to determine if an entire message has been read 2911 o Handling notifications 2913 Note most functions defined in Appendix A are reused in 2914 this example. 2916 int main() 2917 { 2918 int fd; 2919 int onoff = 1; 2920 int idleTime = 2; 2921 struct sockaddr_in sin[1]; 2923 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 2924 perror("socket"); 2925 exit(1); 2926 } 2928 sin->sin_family = AF_INET; 2929 sin->sin_port = htons(7); 2930 sin->sin_addr.s_addr = INADDR_ANY; 2931 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2932 perror("bind"); 2933 exit(1); 2934 } 2936 /* Enable notifications */ 2938 /* SCTP_RECVASSOCEVNT and SCTP_RECVDATAIOEVNT are on by default */ 2940 /* if a send fails we want to know it */ 2941 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, 2942 &onoff, 4) < 0) { 2943 perror("setsockopt SCTP_RECVASSOCEVNT"); 2944 exit(1); 2945 } 2946 /* if a network address change or event transpires 2947 * we wish to know it 2948 */ 2949 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, 2950 &onoff, 4) < 0) { 2951 perror("setsockopt SCTP_RECVPADDREVNT"); 2952 exit(1); 2953 } 2954 /* We would like all error TLV's from the peer */ 2955 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, 2956 &onoff, 4) < 0) { 2957 perror("setsockopt SCTP_RECVPEERERR"); 2958 exit(1); 2959 } 2960 /* And of course we would like to know about shutdown's */ 2961 if (setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, 2962 &onoff, 4) < 0) { 2963 perror("setsockopt SCTP_RECVSHUTDOWNEVNT"); 2964 exit(1); 2965 } 2966 /* Set associations to auto-close in 2 seconds of 2967 * inactivity 2968 */ 2969 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 2970 &idleTime, 4) < 0) { 2971 perror("setsockopt SCTP_AUTOCLOSE"); 2972 exit(1); 2973 } 2975 /* Allow new associations to be accepted */ 2976 if (listen(fd, 0) < 0) { 2977 perror("listen"); 2978 exit(1); 2979 } 2981 /* Wait for new associations */ 2982 while(1){ 2983 /* Echo back any and all data */ 2984 echo(fd,1); 2985 } 2986 }