idnits 2.17.1 draft-ietf-tsvwg-sctpsocket-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 35 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** There are 50 instances of lines with control characters in the document. ** The abstract seems to contain references ([8]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 832 has weird spacing: '...n. The value...' == Line 844 has weird spacing: '...er send and ...' == Line 1012 has weird spacing: '...g_level cms...' == Line 1066 has weird spacing: '...g_level cms...' == Line 1678 has weird spacing: '... msghdr msg;...' == (4 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 26, 2003) is 7728 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '0' is mentioned on line 1489, but not defined == Unused Reference: '4' is defined on line 2694, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 2697, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (ref. '1') (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1644 (ref. '3') (Obsoleted by RFC 6247) ** Obsolete normative reference: RFC 2292 (ref. '6') (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2553 (ref. '7') (Obsoleted by RFC 3493) ** Obsolete normative reference: RFC 2960 (ref. '8') (Obsoleted by RFC 4960) Summary: 11 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Stewart 3 Internet-Draft Cisco Systems, Inc. 4 Expires: August 27, 2003 Q. Xie 5 L. Yarroll 6 Motorola, Inc. 7 J. Wood 8 DoCoMo USA Labs 9 K. Poon 10 Consultant 11 K. Fujita 12 NEC USA, Inc. 13 M. Tuexen 14 February 26, 2003 16 Sockets API Extensions for Stream Control Transmission Protocol 17 (SCTP) 18 draft-ietf-tsvwg-sctpsocket-06.txt 20 Status of this Memo 22 This document is an Internet-Draft and is in full conformance with 23 all provisions of Section 10 of RFC2026. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as 28 Internet-Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at http:// 36 www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on August 27, 2003. 43 Copyright Notice 45 Copyright (C) The Internet Society (2003). All Rights Reserved. 47 Abstract 49 This document describes a mapping of the Stream Control Transmission 50 Protocol SCTP RFC2960 [8] into a sockets API. The benefits of this 51 mapping include compatibility for TCP applications, access to new 52 SCTP features and a consolidated error and event notification scheme. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6 58 2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3. UDP-style Interface . . . . . . . . . . . . . . . . . . . 7 60 3.1 3.1 Basic Operation . . . . . . . . . . . . . . . . . . . 7 61 3.1.1 socket() - UDP Style Syntax . . . . . . . . . . . . . . . 8 62 3.1.2 bind() - UDP Style Syntax . . . . . . . . . . . . . . . . 8 63 3.1.3 listen() - UDP Style Syntax . . . . . . . . . . . . . . . 9 64 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax . . . . . . . . 10 65 3.1.5 close() - UDP Style Syntax . . . . . . . . . . . . . . . . 11 66 3.1.6 connect() - UDP Style Syntax . . . . . . . . . . . . . . . 12 67 3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 12 68 3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 69 3.4 Special considerations . . . . . . . . . . . . . . . . . . 13 70 4. TCP-style Interface . . . . . . . . . . . . . . . . . . . 16 71 4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 16 72 4.1.1 socket() - TCP Style Syntax . . . . . . . . . . . . . . . 17 73 4.1.2 bind() - TCP Style Syntax . . . . . . . . . . . . . . . . 17 74 4.1.3 listen() - TCP Style Syntax . . . . . . . . . . . . . . . 18 75 4.1.4 accept() - TCP Style Syntax . . . . . . . . . . . . . . . 19 76 4.1.5 connect() - TCP Style Syntax . . . . . . . . . . . . . . . 19 77 4.1.6 close() - TCP Style Syntax . . . . . . . . . . . . . . . . 20 78 4.1.7 shutdown() - TCP Style Syntax . . . . . . . . . . . . . . 20 79 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax . . . . . . . . 21 80 4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 22 81 5. Data Structures . . . . . . . . . . . . . . . . . . . . . 23 82 5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 23 83 5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 24 84 5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 25 85 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 26 86 5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 29 87 5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 29 88 5.4 Ancillary Data Considerations and Semantics . . . . . . . 39 89 5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 39 90 5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 39 91 5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 40 92 6. Common Operations for Both Styles . . . . . . . . . . . . 42 93 6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 42 94 6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 43 95 6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 43 96 6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 43 97 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 45 98 7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 46 99 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 46 100 7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 47 101 7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 49 102 7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 49 103 7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 49 104 7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 50 105 7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 50 106 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 50 107 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) . . . . . . . 50 108 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 51 109 7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER) . . 51 110 7.1.12 Enable/Disable message fragmentation 111 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 51 112 7.1.13 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) . . . 51 113 7.1.14 Set default send parameters (SET_DEFAULT_SEND_PARAM) . . . 52 114 7.1.15 Set notification and ancillary events (SCTP_SET_EVENTS) . 52 115 7.1.16 Set/clear IPv4 mapped addresses 116 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . . . 53 117 7.1.17 Set the maximum fragrmentation size (SCTP_MAXSEG) . . . . 53 118 7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 53 119 7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 53 120 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 54 121 7.3 Ancillary Data and Notification Interest Options . . . . . 55 122 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 58 123 8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 58 124 8.2 Branched-off Association . . . . . . . . . . . . . . . . . 59 125 8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 59 126 8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 60 127 8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 60 128 8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 61 129 8.7 sctp_sndmsg() . . . . . . . . . . . . . . . . . . . . . . 61 130 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . 62 131 10. Security Considerations . . . . . . . . . . . . . . . . . 63 132 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 64 133 References . . . . . . . . . . . . . . . . . . . . . . . . 65 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 65 135 A. TCP-style Code Example . . . . . . . . . . . . . . . . . . 68 136 B. UDP-style Code Example . . . . . . . . . . . . . . . . . . 74 137 Intellectual Property and Copyright Statements . . . . . . 76 139 1. Introduction 141 The sockets API has provided a standard mapping of the Internet 142 Protocol suite to many operating systems. Both TCP RFC793 [1] and 143 UDP RFC768 [2] have benefited from this standard representation and 144 access method across many diverse platforms. SCTP is a new protocol 145 that provides many of the characteristics of TCP but also 146 incorporates semantics more akin to UDP. This document defines a 147 method to map the existing sockets API for use with SCTP, providing 148 both a base for access to new features and compatibility so that most 149 existing TCP applications can be migrated to SCTP with few (if any) 150 changes. 152 There are three basic design objectives: 154 1) Maintain consistency with existing sockets APIs: 156 We define a sockets mapping for SCTP that is consistent with other 157 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and 158 IPv6). 160 2) Support a UDP-style interface 162 This set of semantics is similar to that defined for connection 163 less protocols, such as UDP. It is more efficient than a TCP-like 164 connection-oriented interface in terms of exploring the new 165 features of SCTP. 167 Note that SCTP is connection-oriented in nature, and it does not 168 support broadcast or multicast communications, as UDP does. 170 3) Support a TCP-style interface 172 This interface supports the same basic semantics as sockets for 173 connection-oriented protocols, such as TCP. 175 The purpose of defining this interface is to allow existing 176 applications built on connection-oriented protocols be ported to 177 use SCTP with very little effort, and developers familiar with 178 those semantics can easily adapt to SCTP. 180 Extensions will be added to this mapping to provide mechanisms to 181 exploit new features of SCTP. 183 Goals 2 and 3 are not compatible, so in this document we define two 184 modes of mapping, namely the UDP-style mapping and the TCP-style 185 mapping. These two modes share some common data structures and 186 operations, but will require the use of two different application 187 programming models. 189 A mechanism is defined to convert a UDP-style SCTP association into a 190 TCP-style socket. 192 Some of the SCTP mechanisms cannot be adequately mapped to existing 193 socket interface. In some cases, it is more desirable to have new 194 interface instead of using existing socket calls. This document also 195 describes those new interface. 197 2. Conventions 199 2.1 Data Types 201 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX 202 1003.1g are used: uintN_t means an unsigned integer of exactly N bits 203 (e.g., uint16_t). We also assume the argument data types from 204 1003.1g when possible (e.g., the final argument to setsockopt() is a 205 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 206 size_t data type is used. 208 3. UDP-style Interface 210 The UDP-style interface has the following characteristics: 212 A) Outbound association setup is implicit. 214 B) Messages are delivered in complete messages (with one notable 215 exception). 217 C) There is a 1 to MANY relationship between socket and association. 219 3.1 3.1 Basic Operation 221 A typical server in this model uses the following socket calls in 222 sequence to prepare an endpoint for servicing requests: 224 1. socket() 226 2. bind() 228 3. listen() 230 4. recvmsg() 232 5. sendmsg() 234 6. close() 236 A typical client uses the following calls in sequence to setup an 237 association with a server to request services: 239 1. socket() 241 2. sendmsg() 243 3. recvmsg() 245 4. close() 247 In this model, by default, all the associations connected to the 248 endpoint are represented with a single socket. 250 If the server or client wishes to branch an existing association off 251 to a separate socket, it is required to call sctp_peeloff() and in 252 the parameter specifies one of the transport addresses of the 253 association. The sctp_peeloff() call will return a new socket which 254 can then be used with recv() and send() functions for message 255 passing. See Section Section 8.2 for more on branched-off 256 associations. 258 Once an association is branched off to a separate socket, it becomes 259 completely separated from the original socket. All subsequent 260 control and data operations to that association must be done through 261 the new socket. For example, the close operation on the original 262 socket will not terminate any associations that have been branched 263 off to a different socket. 265 We will discuss the UDP-style socket calls in more details in the 266 following subsections. 268 3.1.1 socket() - UDP Style Syntax 270 Applications use socket() to create a socket descriptor to represent 271 an SCTP endpoint. 273 The syntax is, 275 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP); 277 or, 279 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP); 281 Here, SOCK_SEQPACKET indicates the creation of a UDP-style socket. 283 The first form creates an endpoint which can use only IPv4 addresses, 284 while, the second form creates an endpoint which can use both IPv6 285 and IPv4 addresses. 287 3.1.2 bind() - UDP Style Syntax 289 Applications use bind() to specify which local address the SCTP 290 endpoint should associate itself with. 292 An SCTP endpoint can be associated with multiple addresses. To do 293 this, sctp_bindx() is introduced in section Section 8.1 to help 294 applications do the job of associating multiple addresses. 296 These addresses associated with a socket are the eligible transport 297 addresses for the endpoint to send and receive data. The endpoint 298 will also present these addresses to its peers during the association 299 initialization process, see RFC2960 [8]. 301 After calling bind() or sctp_bindx(), if the endpoint wishes to 302 accept new associations on the socket, it must call listen() (see 303 section Section 3.1.3). 305 The syntax of bind() is, 307 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); 309 sd: the socket descriptor returned by socket(). 311 addr: the address structure (struct sockaddr_in or struct 312 sockaddr_in6 RFC2553 [7]). 314 addrlen: the size of the address structure. 316 If sd is an IPv4 socket, the address passed must be an IPv4 address. 317 If the sd is an IPv6 socket, the address passed can either be an IPv4 318 or an IPv6 address. 320 Applications cannot call bind() multiple times to associate multiple 321 addresses to an endpoint. After the first call to bind(), all 322 subsequent calls will return an error. 324 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 325 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 326 operating system will associate the endpoint with an optimal address 327 set of the available interfaces. 329 If a bind() or sctp_bindx() is not called prior to a sendmsg() call 330 that initiates a new association, the system picks an ephemeral port 331 and will choose an address set equivalent to binding with a wildcard 332 address. One of those addresses will be the primary address for the 333 association. This automatically enables the multi-homing capability 334 of SCTP. 336 3.1.3 listen() - UDP Style Syntax 338 By default, new associations are not accepted for UDP style sockets. 339 An application uses listen() to mark a socket as being able to accept 340 new associations. The syntax is, 342 int listen(int socket, int backlog); 343 socket - the socket descriptor of the endpoint. 344 backlog - ignored for UDP-style sockets. 346 Note that UDP-style socket consumers do not need to call accept to 347 retrieve new associations. Calling accept() on a UDP-style socket 348 should return EOPNOTSUPP. Rather, new associations are accepted 349 automatically, and notifications of the new associations are 350 delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if these 351 notifications are enabled). Clients will typically not call listen, 352 so that they can be assured that the only associations on the socket 353 will be ones they actively initiated. Server or peer-to-peer 354 sockets, on the other hand, will always accept new associations, so a 355 well-written application using server UDP-style sockets must be 356 prepared to handle new associations from unwanted peers. 358 Also note that the SCTP_ASSOC_CHANGE event provides the association 359 ID for a new association, so if applications wish to use the 360 association ID as input to other socket calls, they should ensure 361 that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by 362 default). 364 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax 366 An application uses sendmsg() and recvmsg() call to transmit data to 367 and receive data from its peer. 369 ssize_t sendmsg(int socket, const struct msghdr *message, int flags); 371 ssize_t recvmsg(int socket, struct msghdr *message, int flags); 373 socket: the socket descriptor of the endpoint. 375 message: pointer to the msghdr structure which contains a single user 376 message and possibly some ancillary data. See Section 5 for 377 complete description of the data structures. 379 flags: No new flags are defined for SCTP at this level. See Section 380 5 for SCTP-specific flags used in the msghdr structure. 382 As we will see in Section 5, along with the user data, the ancillary 383 data field is used to carry the sctp_sndrcvinfo and/or the 384 sctp_initmsg structures to perform various SCTP functions including 385 specifying options for sending each user message. Those options, 386 depending on whether sending or receiving, include stream number, 387 stream sequence number, various flags, context and payload protocol 388 Id, etc. 390 When sending user data with sendmsg(), the msg_name field in msghdr 391 structure will be filled with one of the transport addresses of the 392 intended receiver. If there is no association existing between the 393 sender and the intended receiver, the sender's SCTP stack will set up 394 a new association and then send the user data (see Section 3.2 for 395 more on implicit association setup). 397 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will 398 be delivered if that notification has been enabled, and no more data 399 can be sent to that association. Any attempt to send more data will 400 cause sendmsg() to return with an ESHUTDOWN error. Note that the 401 socket is still open for reading at this point so it is possible to 402 retrieve notifications. 404 When receiving a user message with recvmsg(), the msg_name field in 405 msghdr structure will be populated with the source transport address 406 of the user data. The caller of recvmsg() can use this address 407 information to determine to which association the received user 408 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled, 409 applications must use the peer transport address provided in the 410 msg_name field by recvmsg() to perform correlation to an association, 411 since they will not have the association ID. 413 If all data in a single message has been delivered, MSG_EOR will be 414 set in the msg_flags field of the msghdr structure (see section 415 Section 5.1). 417 If the application does not provide enough buffer space to completely 418 receive a data message, MSG_EOR will not be set in msg_flags. 419 Successive reads will consume more of the same message until the 420 entire message has been delivered, and MSG_EOR will be set. 422 If the SCTP stack is running low on buffers, it may partially deliver 423 a message. In this case, MSG_EOR will not be set, and more calls to 424 recvmsg() will be necessary to completely consume the message. Only 425 one message at a time can be partially delivered. 427 Note, if the socket is a branched-off socket that only represents one 428 association (see Section 3.1), the msg_name field is not used when 429 sending data (i.e., ignored by the SCTP stack). 431 3.1.5 close() - UDP Style Syntax 433 Applications use close() to perform graceful shutdown (as described 434 in Section 10.1 of RFC2960 [8]) on ALL the associations currently 435 represented by a UDP-style socket. 437 The syntax is: 439 ret = close(int sd); 441 sd - the socket descriptor of the associations to be closed. 443 To gracefully shutdown a specific association represented by the 444 UDP-style socket, an application should use the sendmsg() call, 445 possibly passing a user specified abort code in the data field, and 446 including the MSG_EOF flag in the ancillary data (see Section 5.2.2). 448 If sd in the close() call is a branched-off socket representing only 449 one association, the shutdown is performed on that association only. 451 3.1.6 connect() - UDP Style Syntax 453 An application may use the connect() call in the UDP model to 454 initiate an association without sending data. 456 The syntax is: 458 ret = connect(int sd, const struct sockaddr *nam, socklen_t len); 460 sd: the socket descriptor to have a new association added to. 462 nam: the address structure (either struct sockaddr_in or struct 463 sockaddr_in6 defined in RFC2553 [7]). 465 len: the size of the address. 467 3.2 Implicit Association Setup 469 Once all bind() calls are complete on a UDP-style socket, the 470 application can begin sending and receiving data using the sendmsg()/ 471 recvmsg() or sendto()/recvfrom() calls, without going through any 472 explicit association setup procedures (i.e., no connect() calls 473 required). 475 Whenever sendmsg() or sendto() is called and the SCTP stack at the 476 sender finds that there is no association existing between the sender 477 and the intended receiver (identified by the address passed either in 478 the msg_name field of msghdr structure in the sendmsg() call or the 479 dest_addr field in the sendto() call), the SCTP stack will 480 automatically setup an association to the intended receiver. 482 Upon the successful association setup a SCTP_COMM_UP notification 483 will be dispatched to the socket at both the sender and receiver 484 side. This notification can be read by the recvmsg() system call 485 (see Section 3.1.3). 487 Note, if the SCTP stack at the sender side supports bundling, the 488 first user message may be bundled with the COOKIE ECHO message 489 RFC2960 [8]. 491 When the SCTP stack sets up a new association implicitly, it first 492 consults the sctp_initmsg structure, which is passed along within the 493 ancillary data in the sendmsg() call (see Section 5.2.1 for details 494 of the data structures), for any special options to be used on the 495 new association. 497 If this information is not present in the sendmsg() call, or if the 498 implicit association setup is triggered by a sendto() call, the 499 default association initialization parameters will be used. These 500 default association parameters may be set with respective 501 setsockopt() calls or be left to the system defaults. 503 Implicit association setup cannot be initiated by send()/recv() 504 calls. 506 3.3 Non-blocking mode 508 Some SCTP users might want to avoid blocking when they call socket 509 interface function. 511 Whenever the user which want to avoid blocking must call select() 512 before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and check 513 the socket status is writable or readable. If the socket status 514 isn't writeable or readable, the user should not call sendmsg()/ 515 sendto() and recvmsg()/recvfrom(). 517 Once all bind() calls are complete on a UDP-style socket, the 518 application must set the non-blocking option by a fcntl() (such as 519 O_NONBLOCK). After which the sendmsg() function returns immediately, 520 and the success or failure of the data message (and possible 521 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE 522 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not 523 be sent (due to a CANT_START_ASSOC), the sender will also receive a 524 SCTP_SEND_FAILED event. Those event(s) can be received by the user 525 calling of recvmsg(). A server (having called listen()) is also 526 notified of an association up event by the reception of a 527 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and 528 possibly the reception of the first data message. 530 In order to shutdown the association gracefully, the user must call 531 sendmsg() with no data and with the MSG_EOF flag set. The function 532 returns immediately, and completion of the graceful shutdown is 533 indicated by an SCTP_ASSOC_CHANGE notification of type 534 SHUTDOWN_COMPLETE (see Section 5.3.1.1). 536 3.4 Special considerations 538 The fact that a UDP-style socket can provide access to many SCTP 539 associations through a single socket descriptor has important 540 implications for both application programmers and system programmers 541 implementing this API. A key issue is how buffer space inside the 542 sockets layer is managed. Because this implementation detail 543 directly affects how application programmers must write their code to 544 ensure correct operation and portability, this section provides some 545 guidance to both implementors and application programmers. 547 An important feature that SCTP shares with TCP is flow control: 548 specifically, a sender may not send data faster than the receiver can 549 consume it. 551 For TCP, flow control is typically provided for in the sockets API as 552 follows. If the reader stops reading, the sender queues messages in 553 the socket layer until it uses all of its socket buffer space 554 allocation creating a "stalled connection". Further attempts to 555 write to the socket will block or return the error EAGAIN (for a 556 non-blocking socket). At some point, either the connection is 557 closed, or the receiver begins to read again freeing space in the 558 output queue. 560 For TCP-style SCTP sockets (this includes sockets descriptors that 561 were separated from a UDP style socket with sctp_peeloff()) the 562 behavior is identical. For UDP-style SCTP sockets, the fact that we 563 have multiple associations on a single socket makes the situation 564 more complicated. If the implementation uses a single buffer space 565 allocation shared by all associations, a single stalled association 566 can prevent the further sending of data on all associations active on 567 a particular UDP-style socket. 569 For a blocking socket, it should be clear that a single stalled 570 association can block the entire socket. For this reason, 571 application programmers may want to use non-blocking UDP-style 572 sockets. The application should at least be able to send messages to 573 the non-stalled associations. 575 But a non-blocking socket is not sufficient if the API implementor 576 has chosen a single shared buffer allocation for the socket. A 577 single stalled association would eventually cause the shared 578 allocation to fill, and it would become impossible to send even to 579 non-stalled associations. 581 The API implementor can solve this problem by providing each 582 association with its own allocation of outbound buffer space. Each 583 association should conceptually have as much buffer space as it would 584 have if it had its own socket. As a bonus, this simplifies the 585 implementation of sctp_peeloff(). 587 To ensure that a given stalled association will not prevent other 588 non-stalled associations from being writable, application programmers 589 should either: 591 (a) demand that the underlying implementation dedicates independent 592 buffer space allotments to each association (as suggested above), 593 or 595 (b) verify that their application layer protocol does not permit 596 large amounts of unread data at the receiver (this is true of some 597 request-response protocols, for example), or 599 (c) use TCP-style sockets for association which may potentially stall 600 (either from the beginning, or by using sctp_peeloff before 601 sending large amounts of data that may cause a stalled condition). 603 4. TCP-style Interface 605 The goal of this model is to follow as closely as possible the 606 current practice of using the sockets interface for a connection 607 oriented protocol, such as TCP. This model enables existing 608 applications using connection oriented protocols to be ported to SCTP 609 with very little effort. 611 Note that some new SCTP features and some new SCTP socket options can 612 only be utilized through the use of sendmsg() and recvmsg() calls, 613 see Section 4.1.8. 615 4.1 Basic Operation 617 A typical server in TCP-style model uses the following system call 618 sequence to prepare an SCTP endpoint for servicing requests: 620 1. socket() 622 2. bind() 624 3. listen() 626 4. accept() 628 The accept() call blocks until a new association is set up. It 629 returns with a new socket descriptor. The server then uses the new 630 socket descriptor to communicate with the client, using recv() and 631 send() calls to get requests and send back responses. 633 Then it calls 635 5. close() 637 to terminate the association. 639 A typical client uses the following system call sequence to setup an 640 association with a server to request services: 642 1. socket() 644 2. connect() 646 After returning from connect(), the client uses send() and recv() 647 calls to send out requests and receive responses from the server. 649 The client calls 650 3. close() 652 to terminate this association when done. 654 4.1.1 socket() - TCP Style Syntax 656 Applications calls socket() to create a socket descriptor to 657 represent an SCTP endpoint. 659 The syntax is: 661 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP); 663 or, 665 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP); 667 Here, SOCK_STREAM indicates the creation of a TCP-style socket. 669 The first form creates an endpoint which can use only IPv4 addresses, 670 while the second form creates an endpoint which can use both IPv6 and 671 IPv4 addresses. 673 4.1.2 bind() - TCP Style Syntax 675 Applications use bind() to pass an address to be associated with an 676 SCTP endpoint to the system. bind() allows only either a single 677 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP 678 endpoint can be associated with multiple addresses. To do this, 679 sctp_bindx() is introduced in Section 8.1 to help applications do 680 the job of associating multiple addresses. 682 These addresses associated with a socket are the eligible transport 683 addresses for the endpoint to send and receive data. The endpoint 684 will also present these addresses to its peers during the association 685 initialization process, see RFC2960 [8]. 687 The syntax is: 689 int bind(int sd, struct sockaddr *addr, socklen_t addrlen); 691 sd: the socket descriptor returned by socket() call. 693 addr: the address structure (either struct sockaddr_in or struct 694 sockaddr_in6 defined in RFC2553 [7]). 696 addrlen: the size of the address structure. 698 If sd is an IPv4 socket, the address passed must be an IPv4 address. 699 Otherwise, i.e., the sd is an IPv6 socket, the address passed can 700 either be an IPv4 or an IPv6 address. 702 Applications cannot call bind() multiple times to associate multiple 703 addresses to the endpoint. After the first call to bind(), all 704 subsequent calls will return an error. 706 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, 707 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the 708 operating system will associate the endpoint with an optimal address 709 set of the available interfaces. 711 If a bind() or sctp_bindx() is not called prior to the connect() 712 call, the system picks an ephemeral port and will choose an address 713 set equivalent to binding with a wildcard address. One of those 714 addresses will be the primary address for the association. This 715 automatically enables the multi-homing capability of SCTP. 717 The completion of this bind() process does not ready the SCTP 718 endpoint to accept inbound SCTP association requests. Until a 719 listen() system call, described below, is performed on the socket, 720 the SCTP endpoint will promptly reject an inbound SCTP INIT request 721 with an SCTP ABORT. 723 4.1.3 listen() - TCP Style Syntax 725 Applications use listen() to ready the SCTP endpoint for accepting 726 inbound associations. 728 The syntax is: 730 int listen(int sd, int backlog); 732 sd: the socket descriptor of the SCTP endpoint. 734 backlog: this specifies the max number of outstanding associations 735 allowed in the socket's accept queue. These are the associations 736 that have finished the four-way initiation handshake (see Section 737 5 of RFC2960 [8]) and are in the ESTABLISHED state. Note, a 738 backlog of '0' indicates that the caller no longer wishes to 739 receive new associations. 741 4.1.4 accept() - TCP Style Syntax 743 Applications use accept() call to remove an established SCTP 744 association from the accept queue of the endpoint. A new socket 745 descriptor will be returned from accept() to represent the newly 746 formed association. 748 The syntax is: 750 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen); 752 new_sd: the socket descriptor for the newly formed association. 754 sd the listening socket descriptor. 756 addr on return, will contain the primary address of the peer 757 endpoint. 759 addrlen on return, will contain the size of addr. 761 4.1.5 connect() - TCP Style Syntax 763 Applications use connect() to initiate an association to a peer. 765 The syntax is: 767 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); 769 sd: the socket descriptor of the endpoint. 771 addr the peer's address. 773 addrlen the size of the address. 775 This operation corresponds to the ASSOCIATE primitive described in 776 section 10.1 of RFC2960 [8]. 778 By default, the new association created has only one outbound stream. 779 The SCTP_INITMSG option described in Section 7.1.3 should be used 780 before connecting to change the number of outbound streams. 782 If a bind() or sctp_bindx() is not called prior to the connect() 783 call, the system picks an ephemeral port and will choose an address 784 set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 785 and IPv6 socket respectively. One of those addresses will be the 786 primary address for the association. This automatically enables the 787 multi-homing capability of SCTP. 789 Note that SCTP allows data exchange, similar to T/TCP RFC1644 [3], 790 during the association set up phase. If an application wants to do 791 this, it cannot use connect() call. Instead, it should use sendto() 792 or sendmsg() to initiate an association. If it uses sendto() and it 793 wants to change initialization behavior, it needs to use the 794 SCTP_INITMSG socket option before calling sendto(). Or it can use 795 SCTP_INIT type sendmsg() to initiate an association without doing the 796 setsockopt(). 798 SCTP does not support half close semantics. This means that unlike 799 T/TCP, MSG_EOF should not be set in the flags parameter when calling 800 sendto() or sendmsg() when the call is used to initiate a connection. 801 MSG_EOF is not an acceptable flag with SCTP socket. 803 4.1.6 close() - TCP Style Syntax 805 Applications use close() to gracefully close down an association. 807 The syntax is: 809 int close(int sd); 811 sd - the socket descriptor of the association to be closed. 813 After an application calls close() on a socket descriptor, no further 814 socket operations will succeed on that descriptor. 816 4.1.7 shutdown() - TCP Style Syntax 818 SCTP differs from TCP in that it does not have half closed semantics. 819 Hence the shutdown() call for SCTP is an approximation of the TCP 820 shutdown() call, and solves some different problems. Full 821 TCP-compatibility is not provided, so developers porting TCP 822 applications to SCTP may need to recode sections that use shutdown(). 823 (Note that it is possible to achieve the same results as half close 824 in SCTP using SCTP streams.) 826 The syntax is: 828 int shutdown(int socket, int how); 830 sd - the socket descriptor of the association to be closed. 832 how - Specifies the type of shutdown. The values are 833 as follows: 835 SHUT_RD 836 Disables further receive operations. No SCTP 837 protocol action is taken. 839 SHUT_WR 840 Disables further send operations, and initiates 841 the SCTP shutdown sequence. 843 SHUT_RDWR 844 Disables further send and receive operations 845 and initiates the SCTP shutdown sequence. 847 The major difference between SCTP and TCP shutdown() is that SCTP 848 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP 849 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves 850 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close 851 the SCTP association while still leaving the socket descriptor open, 852 so that the caller can receive back any data SCTP was unable to 853 deliver (see Section 5.3.1.4 for more information). 855 To perform the ABORT operation described in RFC2960 [8] section 10.1, 856 an application can use the socket option SO_LINGER. It is described 857 in Section 7.1.4. 859 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax 861 With a TCP-style socket, the application can also use sendmsg() and 862 recvmsg() to transmit data to and receive data from its peer. The 863 semantics is similar to those used in the UDP-style model (section 864 Section 3.1.3), with the following differences: 866 1) When sending, the msg_name field in the msghdr is not used to 867 specify the intended receiver, rather it is used to indicate a 868 different peer address if the sender does not want to send the 869 message over the primary address of the receiver. If the transport 870 address given is not part of the current association, the data will 871 not be sent and a SCTP_SEND_FAILED event will be delivered to the 872 application if send failure events are enabled. 874 2) An application must use close() to gracefully shutdown an 875 association, or use SO_LINGER option with close() to abort an 876 association. It must not use the MSG_ABORT or MSG_EOF flag in 877 sendmsg(). The system returns an error if an application tries to do 878 so. 880 4.1.9 getpeername() 882 Applications use getpeername() to retrieve the primary socket address 883 of the peer. This call is for TCP compatibility, and is not 884 multi-homed. It does not work with UDP-style sockets. See Section 885 8.3 for a multi-homed/UDP-sockets version of the call. 887 The syntax is: 889 int getpeername(int socket, struct sockaddr *address, 890 socklen_t *len); 892 sd - the socket descriptor to be queried. 894 address - On return, the peer primary address is stored in 895 this buffer. If the socket is an IPv4 socket, the 896 address will be IPv4. If the socket is an IPv6 socket, 897 the address will be either an IPv6 or IPv4 898 address. 900 len - The caller should set the length of address here. 901 On return, this is set to the length of the returned 902 address. 904 If the actual length of the address is greater than the length of the 905 supplied sockaddr structure, the stored address will be truncated. 907 5. Data Structures 909 We discuss in this section important data structures which are 910 specific to SCTP and are used with sendmsg() and recvmsg() calls to 911 control SCTP endpoint operations and to access ancillary information 912 and notifications. 914 5.1 The msghdr and cmsghdr Structures 916 The msghdr structure used in the sendmsg() and recvmsg() calls, as 917 well as the ancillary data carried in the structure, is the key for 918 the application to set and get various control information from the 919 SCTP endpoint. 921 The msghdr and the related cmsghdr structures are defined and 922 discussed in details in RFC2292 [6]. Here we will cite their 923 definitions from RFC2292 [6]. 925 The msghdr structure: 927 struct msghdr { 928 void *msg_name; /* ptr to socket address structure */ 929 socklen_t msg_namelen; /* size of socket address structure */ 930 struct iovec *msg_iov; /* scatter/gather array */ 931 size_t msg_iovlen; /* # elements in msg_iov */ 932 void *msg_control; /* ancillary data */ 933 socklen_t msg_controllen; /* ancillary data buffer length */ 934 int msg_flags; /* flags on received message */ 935 }; 937 The cmsghdr structure: 939 struct cmsghdr { 940 socklen_t cmsg_len; /* #bytes, including this header */ 941 int cmsg_level; /* originating protocol */ 942 int cmsg_type; /* protocol-specific type */ 943 /* followed by unsigned char cmsg_data[]; */ 944 }; 946 In the msghdr structure, the usage of msg_name has been discussed in 947 previous sections (see Section 3.1.3 and Section 4.1.8). 949 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov 950 field) are treated as a single SCTP data chunk, rather than multiple 951 chunks, for both sendmsg() and recvmsg(). 953 The msg_flags are not used when sending a message with sendmsg(). 955 If a notification has arrived, recvmsg() will return the notification 956 with the MSG_NOTIFICATION flag set in msg_flags. If the 957 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See 958 Section 5.3 for more information about notifications. 960 If all portions of a data frame or notification have been read, 961 recvmsg() will return with MSG_EOR set in msg_flags. 963 5.2 SCTP msg_control Structures 965 A key element of all SCTP-specific socket extensions is the use of 966 ancillary data to specify and access SCTP-specific data via the 967 struct msghdr's msg_control member used in sendmsg() and recvmsg(). 968 Fine-grained control over initialization and sending parameters are 969 handled with ancillary data. 971 Each ancillary data item is proceeded by a struct cmsghdr (see 972 Section 5.1), which defines the function and purpose of the data 973 contained in in the cmsg_data[] member. 975 There are two kinds of ancillary data used by SCTP: initialization 976 data, and, header information (SNDRCV). Initialization data 977 (UDP-style only) sets protocol parameters for new associations. 978 Section 5.2.1 provides more details. Header information can set or 979 report parameters on individual messages in a stream. See Section 980 5.2.2 for how to use SNDRCV ancillary data. 982 By default on a TCP-style socket, SCTP will pass no ancillary data; 983 on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and 984 SCTP_ASSOC_CHANGE information. Specific ancillary data items can be 985 enabled with socket options defined for SCTP; see Section 7.3. 987 Note that all ancillary types are fixed length; see Section 5.4 for 988 further discussion on this. These data structures use struct 989 sockaddr_storage (defined in RFC2553 [7]) as a portable, fixed length 990 address format. 992 Other protocols may also provide ancillary data to the socket layer 993 consumer. These ancillary data items from other protocols may 994 intermingle with SCTP data. For example, the IPv6 socket API 995 definitions (RFC2292 [6] and RFC2553 [7]) define a number of 996 ancillary data items. If a socket API consumer enables delivery of 997 both SCTP and IPv6 ancillary data, they both may appear in the same 998 msg_control buffer in any order. An application may thus need to 999 handle other types of ancillary data besides that passed by SCTP. 1001 The sockets application must provide a buffer large enough to 1002 accommodate all ancillary data provided via recvmsg(). If the buffer 1003 is not large enough, the ancillary data will be truncated and the 1004 msghdr's msg_flags will include MSG_CTRUNC. 1006 5.2.1 SCTP Initiation Structure (SCTP_INIT) 1008 This cmsghdr structure provides information for initializing new SCTP 1009 associations with sendmsg(). The SCTP_INITMSG socket option uses 1010 this same data structure. This structure is not used for recvmsg(). 1012 cmsg_level cmsg_type cmsg_data[] 1013 ------------ ------------ ---------------------- 1014 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg 1016 Here is the definition of the sctp_initmsg structure: 1018 struct sctp_initmsg { 1019 uint16_t sinit_num_ostreams; 1020 uint16_t sinit_max_instreams; 1021 uint16_t sinit_max_attempts; 1022 uint16_t sinit_max_init_timeo; 1023 }; 1025 sinit_num_ostreams: 16 bits (unsigned integer) 1027 This is an integer number representing the number of streams that the 1028 application wishes to be able to send to. This number is confirmed 1029 in the SCTP_COMM_UP notification and must be verified since it is a 1030 negotiated number with the remote endpoint. The default value of 0 1031 indicates to use the endpoint default value. 1033 sinit_max_instreams: 16 bits (unsigned integer) 1035 This value represents the maximum number of inbound streams the 1036 application is prepared to support. This value is bounded by the 1037 actual implementation. In other words the user MAY be able to 1038 support more streams than the Operating System. In such a case, the 1039 Operating System limit overrides the value requested by the user. 1040 The default value of 0 indicates to use the endpoint's default value. 1042 sinit_max_attempts: 16 bits (unsigned integer) 1044 This integer specifies how many attempts the SCTP endpoint should 1045 make at resending the INIT. This value overrides the system SCTP 1046 'Max.Init.Retransmits' value. The default value of 0 indicates to 1047 use the endpoint's default value. This is normally set to the 1048 system's default 'Max.Init.Retransmit' value. 1050 sinit_max_init_timeo: 16 bits (unsigned integer) 1051 This value represents the largest Time-Out or RTO value (in 1052 milliseconds) to use inattempting a INIT. Normally the 'RTO.Max' is 1053 used to limit the doubling of the RTO upon timeout. For the INIT 1054 message this value MAY override 'RTO.Max'. This value MUST NOT 1055 influence 'RTO.Max' during data transmission and is only used to 1056 bound the initial setup time. A default value of 0 indicates to use 1057 the endpoint's default value. This is normally set to the system's 1058 'RTO.Max' value (60 seconds). 1060 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 1062 This cmsghdr structure specifies SCTP options for sendmsg() and 1063 describes SCTP header information about a received message through 1064 recvmsg(). 1066 cmsg_level cmsg_type cmsg_data[] 1067 ------------ ------------ ---------------------- 1068 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo 1070 Here is the definition of sctp_sndrcvinfo: 1072 struct sctp_sndrcvinfo { 1073 uint16_t sinfo_stream; 1074 uint16_t sinfo_ssn; 1075 uint16_t sinfo_flags; 1076 uint32_t sinfo_ppid; 1077 uint32_t sinfo_context; 1078 uint32_t sinfo_timetolive; 1079 uint32_t sinfo_tsn; 1080 uint32_t sinfo_cumtsn; 1081 sctp_assoc_t sinfo_assoc_id; 1082 }; 1084 sinfo_stream: 16 bits (unsigned integer) 1086 For recvmsg() the SCTP stack places the message's stream number in 1087 this value. For sendmsg() this value holds the stream number that 1088 the application wishes to send this message to. If a sender 1089 specifies an invalid stream number an error indication is returned 1090 and the call fails. 1092 sinfo_ssn: 16 bits (unsigned integer) 1094 For recvmsg() this value contains the stream sequence number that the 1095 remote endpoint placed in the DATA chunk. For fragmented messages 1096 this is the same number for all deliveries of the message (if more 1097 than one recvmsg() is needed to read the message). The sendmsg() 1098 call will ignore this parameter. 1100 sinfo_ppid: 32 bits (unsigned integer) 1102 This value in sendmsg() is an opaque unsigned value that is passed to 1103 the remote end in each user message. In recvmsg() this value is the 1104 same information that was passed by the upper layer in the peer 1105 application. Please note that byte order issues are NOT accounted 1106 for and this information is passed opaquely by the SCTP stack from 1107 one end to the other. 1109 sinfo_context: 32 bits (unsigned integer) 1111 This value is an opaque 32 bit context datum that is used in the 1112 sendmsg() function. This value is passed back to the upper layer if 1113 a error occurs on the send of a message and is retrieved with each 1114 undelivered message (Note: if a endpoint has done multiple sends, all 1115 of which fail, multiple different sinfo_context values will be 1116 returned. One with each user data message). 1118 sinfo_flags: 16 bits (unsigned integer) 1120 This field may contain any of the following flags and is composed of 1121 a bitwise OR of these values. 1123 recvmsg() flags: 1125 MSG_UNORDERED - This flag is present when the message was sent 1126 non-ordered. 1128 sendmsg() flags: 1130 MSG_UNORDERED - This flag requests the un-ordered delivery of the 1131 message. If this flag is clear the datagram is 1132 considered an ordered send. 1134 MSG_ADDR_OVER - This flag, in the UDP model, requests the SCTP 1135 stack to override the primary destination address 1136 with the address found with the sendto/sendmsg 1137 call. 1139 MSG_ABORT - Setting this flag causes the specified association 1140 to abort by sending an ABORT message to the peer 1141 (UDP-style only). The ABORT chunk will contain an 1142 error cause 'User Initiated Abort' with cause code 12. 1143 The cause specific information of this error cause is 1144 provided in msg_iov. 1146 MSG_EOF - Setting this flag invokes the SCTP graceful shutdown 1147 procedures on the specified association. Graceful 1148 shutdown assures that all data enqueued by both 1149 endpoints is successfully transmitted before closing 1150 the association (UDP-style only). 1152 sinfo_timetolive: 32 bit (unsigned integer) 1154 For the sending side, this field contains the message time to live in 1155 milliseconds. The sending side will expire the message within the 1156 specified time period if the message as not been sent to the peer 1157 within this time period. This value will override any default value 1158 set using any socket option. Also note that the value of 0 is 1159 special in that it indicates no timeout should occur on this message. 1161 sinfo_tsn: 32 bit (unsigned integer) 1163 For the receiving side, this field holds a TSN that was assigned to 1164 one of the SCTP Data Chunks. 1166 sinfo_cumtsn: 32 bit (unsigned integer) 1168 This field will hold the current cumulative TSN as known by the 1169 underlying SCTP layer. Note this field is ignored when sending and 1170 only valid for a receive operation when sinfo_flags are set to 1171 MSG_UNORDERED. 1173 sinfo_assoc_id: sizeof (sctp_assoc_t) 1175 The association handle field, sinfo_assoc_id, holds the identifier 1176 for the association announced in the SCTP_COMM_UP notification. All 1177 notifications for a given association have the same identifier. 1178 Ignored for TCP-style sockets. 1180 A sctp_sndrcvinfo item always corresponds to the data in msg_iov. 1182 5.3 SCTP Events and Notifications 1184 An SCTP application may need to understand and process events and 1185 errors that happen on the SCTP stack. These events include network 1186 status changes, association startups, remote operational errors and 1187 undeliverable messages. All of these can be essential for the 1188 application. 1190 When an SCTP application layer does a recvmsg() the message read is 1191 normally a data message from a peer endpoint. If the application 1192 wishes to have the SCTP stack deliver notifications of non-data 1193 events, it sets the appropriate socket option for the notifications 1194 it wants. See Section 7.3 for these socket options. When a 1195 notification arrives, recvmsg() returns the notification in the 1196 application-supplied data buffer via msg_iov, and sets 1197 MSG_NOTIFICATION in msg_flags. 1199 This section details the notification structures. Every notification 1200 structure carries some common fields which provides general 1201 information. 1203 A recvmsg() call will return only one notification at a time. Just 1204 as when reading normal data, it may return part of a notification if 1205 the msg_iov buffer is not large enough. If a single read is not 1206 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish 1207 reading the notification before subsequent data can arrive. 1209 5.3.1 SCTP Notification Structure 1211 The notification structure is defined as the union of all 1212 notification types. 1214 union sctp_notification { 1215 struct { 1216 uint16_t sn_type; /* Notification type. */ 1217 uint16_t sn_flags; 1218 uint32_t sn_length; 1219 } sn_header; 1220 struct sctp_assoc_change sn_assoc_change; 1221 struct sctp_paddr_change sn_padr_change; 1222 struct sctp_remote_error sn_remote_error; 1223 struct sctp_send_failed sn_send_failed; 1224 struct sctp_shutdown_event sn_shutdown_event; 1225 struct sctp_adaption_event sn_adaption_event; 1226 struct sctp_rcv_pdapi_event sn_rcv_pdapi_event; 1227 }; 1229 sn_type: 16 bits (unsigned integer) 1231 The following list describes the SCTP notification and event types 1232 for the field sn_type. 1234 SCTP_ASSOC_CHANGE: This tag indicates that an association has either 1235 been opened or closed. Refer to Section 5.3.1.1 for details. 1237 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is 1238 part of an existing association has experienced a change of state 1239 (e.g. a failure or return to service of the reachability of a 1240 endpoint via a specific transport address). Please see Section 1241 5.3.1.2 for data structure details. 1243 SCTP_REMOTE_ERROR: The attached error message is an Operational Error 1244 received from the remote peer. It includes the complete TLV sent 1245 by the remote endpoint. See Section 5.3.1.3 for the detailed 1246 format. 1248 SCTP_SEND_FAILED: The attached datagram could not be sent to the 1249 remote endpoint. This structure includes the original 1250 SCTP_SNDRCVINFO that was used in sending this message i.e. this 1251 structure uses the sctp_sndrecvinfo per Section 5.3.1.4. 1253 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data 1254 should be sent on this socket. 1256 SCTP_ADAPTION_INDICATION: This notification holds the peers indicated 1257 adaption layer. Please see Section 5.3.1.6. 1259 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a 1260 receiver that the partial delivery has been aborted. This may 1261 indicate the association is about to be aborted. Please see 1262 Section 5.3.1.7 1264 All standard values for sn_type flags are greater than 2^15. Values 1265 from 2^15 and down are reserved. 1267 sn_flags: 16 bits (unsigned integer) 1269 These are notification-specific flags. 1271 sn_length: 32 bits (unsigned integer) 1273 This is the length of the whole sctp_notification structure including 1274 the sn_type, sn_flags, and sn_length fields. 1276 5.3.1.1 SCTP_ASSOC_CHANGE 1278 Communication notifications inform the ULP that an SCTP association 1279 has either begun or ended. The identifier for a new association is 1280 provided by this notification. The notification information has the 1281 following format: 1283 struct sctp_assoc_change { 1284 uint16_t sac_type; 1285 uint16_t sac_flags; 1286 uint32_t sac_length; 1287 uint16_t sac_state; 1288 uint16_t sac_error; 1289 uint16_t sac_outbound_streams; 1290 uint16_t sac_inbound_streams; 1291 sctp_assoc_t sac_assoc_id; 1292 uint8_t sac_info[0]; 1293 }; 1295 sac_type: 1297 It should be SCTP_ASSOC_CHANGE. 1299 sac_flags: 16 bits (unsigned integer) 1301 Currently unused. 1303 sac_length: 32 bits (unsigned integer) 1305 This field is the total length of the notification data, including 1306 the notification header. 1308 sac_state: 16 bits (signed integer) 1310 This field holds one of a number of values that communicate the event 1311 that happened to the association. They include: 1313 Event Name Description 1314 ---------------- --------------- 1315 SCTP_COMM_UP A new association is now ready 1316 and data may be exchanged with this 1317 peer. 1319 SCTP_COMM_LOST The association has failed. The association 1320 is now in the closed state. If SEND FAILED 1321 notifications are turned on, a SCTP_COMM_LOST 1322 is followed by a series of SCTP_SEND_FAILED 1323 events, one for each outstanding message. 1325 SCTP_RESTART SCTP has detected that the peer has restarted. 1327 SCTP_SHUTDOWN_COMP The association has gracefully closed. 1329 SCTP_CANT_STR_ASSOC The association failed to setup. If non blocking 1330 mode is set and data was sent (in the udp mode), 1331 a SCTP_CANT_STR_ASSOC is followed by a series of 1332 SCTP_SEND_FAILED events, one for each outstanding 1333 message. 1335 sac_error: 16 bits (signed integer) 1337 If the state was reached due to a error condition (e.g. 1338 SCTP_COMM_LOST) any relevant error information is available in this 1339 field. This corresponds to the protocol error codes defined in 1340 RFC2960 [8]. 1342 sac_outbound_streams: 16 bits (unsigned integer) 1344 sac_inbound_streams: 16 bits (unsigned integer) 1346 The maximum number of streams allowed in each direction are available 1347 in sac_outbound_streams and sac_inbound streams. 1349 sac_assoc_id: sizeof (sctp_assoc_t) 1351 The association id field, holds the identifier for the association. 1352 All notifications for a given association have the same association 1353 identifier. For TCP style socket, this field is ignored. 1355 sac_data: variable 1356 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received 1357 for this association, sac_data[] contains the complete ABORT chunk as 1358 defined in the SCTP specification RFC2960 [8] section 3.3.7. 1360 5.3.1.2 SCTP_PEER_ADDR_CHANGE 1362 When a destination address on a multi-homed peer encounters a change 1363 an interface details event is sent. The information has the 1364 following structure: 1366 struct sctp_paddr_change { 1367 uint16_t spc_type; 1368 uint16_t spc_flags; 1369 uint32_t spc_length; 1370 struct sockaddr_storage spc_aaddr; 1371 int spc_state; 1372 int spc_error; 1373 sctp_assoc_t spc_assoc_id; 1374 } 1376 spc_type: 1378 It should be SCTP_PEER_ADDR_CHANGE. 1380 spc_flags: 16 bits (unsigned integer) 1382 Currently unused. 1384 spc_length: 32 bits (unsigned integer) 1386 This field is the total length of the notification data, including 1387 the notification header. 1389 spc_aaddr: sizeof (struct sockaddr_storage) 1391 The affected address field, holds the remote peer's address that is 1392 encountering the change of state. 1394 spc_state: 32 bits (signed integer) 1396 This field holds one of a number of values that communicate the event 1397 that happened to the address. They include: 1399 Event Name Description 1400 ---------------- --------------- 1401 SCTP_ADDR_AVAILABLE This address is now reachable. 1403 SCTP_ADDR_UNREACHABL The address specified can no 1404 longer be reached. Any data sent 1405 to this address is rerouted to an 1406 alternate until this address becomes 1407 reachable. 1409 SCTP_ADDR_REMOVED The address is no longer part of 1410 the association. 1412 SCTP_ADDR_ADDED The address is now part of the 1413 association. 1415 SCTP_ADDR_MADE_PRIM This address has now been made 1416 to be the primary destination address. 1418 spc_error: 32 bits (signed integer) 1420 If the state was reached due to any error condition (e.g. 1421 SCTP_ADDR_UNREACHABL) any relevant error information is available in 1422 this field. 1424 spc_assoc_id: sizeof (sctp_assoc_t) 1426 The association id field, holds the identifier for the association. 1427 All notifications for a given association have the same association 1428 identifier. For TCP style socket, this field is ignored. 1430 5.3.1.3 SCTP_REMOTE_ERROR 1432 A remote peer may send an Operational Error message to its peer. 1433 This message indicates a variety of error conditions on an 1434 association. The entire ERROR chunk as it appears on the wire is 1435 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP 1436 specification RFC2960 [8] and any extensions for a list of possible 1437 error formats. SCTP error notifications have the format: 1439 struct sctp_remote_error { 1440 uint16_t sre_type; 1441 uint16_t sre_flags; 1442 uint32_t sre_length; 1443 uint16_t sre_error; 1444 sctp_assoc_t sre_assoc_id; 1445 uint8_t sre_data[0]; 1446 }; 1448 sre_type: 1450 It should be SCTP_REMOTE_ERROR. 1452 sre_flags: 16 bits (unsigned integer) 1454 Currently unused. 1456 sre_length: 32 bits (unsigned integer) 1458 This field is the total length of the notification data, including 1459 the notification header and the contents of sre_data. 1461 sre_error: 16 bits (unsigned integer) 1463 This value represents one of the Operational Error causes defined in 1464 the SCTP specification, in network byte order. 1466 sre_assoc_id: sizeof (sctp_assoc_t) 1468 The association id field, holds the identifier for the association. 1469 All notifications for a given association have the same association 1470 identifier. For TCP style socket, this field is ignored. 1472 sre_data: variable 1474 This contains the ERROR chunk as defined in the SCTP specification 1475 RFC2960 [8] section 3.3.10. 1477 5.3.1.4 SCTP_SEND_FAILED 1479 If SCTP cannot deliver a message it may return the message as a 1480 notification. 1482 struct sctp_send_failed { 1483 uint16_t ssf_type; 1484 uint16_t ssf_flags; 1485 uint32_t ssf_length; 1486 uint32_t ssf_error; 1487 struct sctp_sndrcvinfo ssf_info; 1488 sctp_assoc_t ssf_assoc_id; 1489 uint8_t ssf_data[0]; 1490 }; 1492 ssf_type: 1494 It should be SCTP_SEND_FAILED. 1496 The flag value will take one of the following values 1498 SCTP_DATA_UNSENT - Indicates that the data was never put on 1499 the wire. 1501 SCTP_DATA_SENT - Indicates that the data was put on the wire. 1502 Note that this does not necessarily mean that the 1503 data was (or was not) successfully delivered. 1505 ssf_length: 32 bits (unsigned integer) 1507 This field is the total length of the notification data, including 1508 the notification header and the payload in ssf_data. 1510 ssf_error: 16 bits (unsigned integer) 1512 This value represents the reason why the send failed, and if set, 1513 will be a SCTP protocol error code as defined in RFC2960 [8] section 1514 3.3.10. 1516 ssf_info: sizeof (struct sctp_sndrcvinfo) 1518 The original send information associated with the undelivered 1519 message. 1521 ssf_assoc_id: sizeof (sctp_assoc_t) 1523 The association id field, sf_assoc_id, holds the identifier for the 1524 association. All notifications for a given association have the same 1525 association identifier. For TCP style socket, this field is ignored. 1527 ssf_data: variable length 1529 The undelivered message, exactly as delivered by the caller to the 1530 original send*() call. 1532 5.3.1.5 SCTP_SHUTDOWN_EVENT 1534 When a peer sends a SHUTDOWN, SCTP delivers this notification to 1535 inform the application that it should cease sending data. 1537 struct sctp_shutdown_event { 1538 uint16_t sse_type; 1539 uint16_t sse_flags; 1540 uint32_t sse_length; 1541 sctp_assoc_t sse_assoc_id; 1542 }; 1544 sse_type 1546 It should be SCTP_SHUTDOWN_EVENT 1548 sse_flags: 16 bits (unsigned integer) 1550 Currently unused. 1552 sse_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 sizeof (struct 1556 sctp_shutdown_event). 1558 sse_flags: 16 bits (unsigned integer) 1560 Currently unused. 1562 sse_assoc_id: sizeof (sctp_assoc_t) 1564 The association id field, holds the identifier for the association. 1565 All notifications for a given association have the same association 1566 identifier. For TCP style socket, this field is ignored. 1568 5.3.1.6 SCTP_ADAPTION_INDICATION 1570 When a peer sends a Adaption Layer Indication parameter , SCTP 1571 delivers this notification to inform the application that of the 1572 peers requested adaption layer. 1574 struct sctp_adaption_event { 1575 uint16_t sai_type; 1576 uint16_t sai_flags; 1577 uint32_t sai_length; 1578 uint32_t sai_adaptation_bits; 1579 sctp_assoc_t sai_assoc_id; 1580 }; 1582 sai_type 1584 It should be SCTP_ADAPTION_INDICATION 1586 sai_flags: 16 bits (unsigned integer) 1588 Currently unused. 1590 sai_length: 32 bits (unsigned integer) 1592 This field is the total length of the notification data, including 1593 the notification header. It will generally be sizeof (struct 1594 sctp_adaption_event). 1596 sai_adaption_bits: 32 bits (unsigned integer) 1598 This field holds the bit array sent by the peer in the adaption layer 1599 indication parameter. The bits are in network byte order. 1601 sai_assoc_id: sizeof (sctp_assoc_t) 1603 The association id field, holds the identifier for the association. 1604 All notifications for a given association have the same association 1605 identifier. For TCP style socket, this field is ignored. 1607 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT 1609 When a receiver is engaged in a partial delivery of a message this 1610 notification will be used to indicate various events. 1612 struct sctp_rcv_pdapi_event { 1613 uint16_t pdapi_type; 1614 uint16_t pdapi_flags; 1615 uint32_t pdapi_length; 1616 uint32_t pdapi_indication; 1617 sctp_assoc_t pdapi_assoc_id; 1618 }; 1620 pdapi_type 1621 It should be SCTP_PARTIAL_DELIVERY_EVENT 1623 pdapi_flags: 16 bits (unsigned integer) 1625 Currently unused. 1627 pdapi_length: 32 bits (unsigned integer) 1629 This field is the total length of the notification data, including 1630 the notification header. It will generally be sizeof (struct 1631 sctp_rcv_pdapi_event). 1633 pdapi_indication: 32 bits (unsigned integer) 1635 This field holds the indication being sent to the application 1636 possible values include: 1638 SCTP_PARTIAL_DELIVERY_ABORTED 1640 pdapi_assoc_id: sizeof (sctp_assoc_t) 1642 The association id field, holds the identifier for the association. 1643 All notifications for a given association have the same association 1644 identifier. For TCP style socket, this field is ignored. 1646 5.4 Ancillary Data Considerations and Semantics 1648 Programming with ancillary socket data contains some subtleties and 1649 pitfalls, which are discussed below. 1651 5.4.1 Multiple Items and Ordering 1653 Multiple ancillary data items may be included in any call to 1654 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP 1655 items, or both. 1657 The ordering of ancillary data items (either by SCTP or another 1658 protocol) is not significant and is implementation-dependent, so 1659 applications must not depend on any ordering. 1661 SCTP_SNDRCV items must always correspond to the data in the msghdr's 1662 msg_iov member. There can be only a single SCTP_SNDRCV info for each 1663 sendmsg() or recvmsg() call. 1665 5.4.2 Accessing and Manipulating Ancillary Data 1667 Applications can infer the presence of data or ancillary data by 1668 examining the msg_iovlen and msg_controllen msghdr members, 1669 respectively. 1671 Implementations may have different padding requirements for ancillary 1672 data, so portable applications should make use of the macros 1673 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See 1674 RFC2292 [6] and your SCTP implementation's documentation for more 1675 information. Following is an example, from RFC2292 [6], 1676 demonstrating the use of these macros to access ancillary data: 1678 struct msghdr msg; 1679 struct cmsghdr *cmsgptr; 1681 /* fill in msg */ 1683 /* call recvmsg() */ 1685 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1686 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1687 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 1688 u_char *ptr; 1690 ptr = CMSG_DATA(cmsgptr); 1691 /* process data pointed to by ptr */ 1692 } 1693 } 1695 5.4.3 Control Message Buffer Sizing 1697 The information conveyed via SCTP_SNDRCV events will often be 1698 fundamental to the correct and sane operation of the sockets 1699 application. This is particularly true of the UDP semantics, but 1700 also of the TCP semantics. For example, if an application needs to 1701 send and receive data on different SCTP streams, SCTP_SNDRCV events 1702 are indispensable. 1704 Given that some ancillary data is critical, and that multiple 1705 ancillary data items may appear in any order, applications should be 1706 carefully written to always provide a large enough buffer to contain 1707 all possible ancillary data that can be presented by recvmsg(). If 1708 the buffer is too small, and crucial data is truncated, it may pose a 1709 fatal error condition. 1711 Thus it is essential that applications be able to deterministically 1712 calculate the maximum required buffer size to pass to recvmsg(). One 1713 constraint imposed on this specification that makes this possible is 1714 that all ancillary data definitions are of a fixed length. One way 1715 to calculate the maximum required buffer size might be to take the 1716 sum the sizes of all enabled ancillary data item structures, as 1717 calculated by CMSG_SPACE. For example, if we enabled 1718 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [6], we would calculate 1719 and allocate the buffer size as follows: 1721 size_t total; 1722 void *buf; 1724 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + 1725 CMSG_SPACE(sizeof (struct in6_pktinfo)); 1727 buf = malloc(total); 1729 We could then use this buffer for msg_control on each call to 1730 recvmsg() and be assured that we would not lose any ancillary data to 1731 truncation. 1733 6. Common Operations for Both Styles 1735 6.1 send(), recv(), sendto(), recvfrom() 1737 Applications can use send() and sendto() to transmit data to the peer 1738 of an SCTP endpoint. recv() and recvfrom() can be used to receive 1739 data from the peer. 1741 The syntax is: 1743 ssize_t send(int sd, connst void *msg, size_t len, int flags); 1744 ssize_t sendto(int sd, const void *msg, size_t len, int flags, 1745 const struct sockaddr *to, int tolen); 1746 ssize_t recv(int sd, void *buf, size_t len, int flags); 1747 ssize_t recvfrom(int sd, void *buf, size_t len, int flags, 1748 struct sockaddr *from, int *fromlen); 1750 sd - the socket descriptor of an SCTP endpoint. 1751 msg - the message to be sent. 1752 len - the size of the message or the size of buffer. 1753 to - one of the peer addresses of the association to be 1754 used to send the message. 1755 tolen - the size of the address. 1756 buf - the buffer to store a received message. 1757 from - the buffer to store the peer address used to send the 1758 received message. 1759 fromlen - the size of the from address 1760 flags - (described below). 1762 These calls give access to only basic SCTP protocol features. If 1763 either peer in the association uses multiple streams, or sends 1764 unordered data these calls will usually be inadequate, and may 1765 deliver the data in unpredictable ways. 1767 SCTP has the concept of multiple streams in one association. The 1768 above calls do not allow the caller to specify on which stream a 1769 message should be sent. The system uses stream 0 as the default 1770 stream for send() and sendto(). recv() and recvfrom() return data 1771 from any stream, but the caller can not distinguish the different 1772 streams. This may result in data seeming to arrive out of order. 1773 Similarly, if a data chunk is sent unordered, recv() and recvfrom() 1774 provide no indication. 1776 SCTP is message based. The msg buffer above in send() and sendto() 1777 is considered to be a single message. This means that if the caller 1778 wants to send a message which is composed by several buffers, the 1779 caller needs to combine them before calling send() or sendto(). 1780 Alternately, the caller can use sendmsg() to do that without 1781 combining them. recv() and recvfrom() cannot distinguish message 1782 boundaries. 1784 In receiving, if the buffer supplied is not large enough to hold a 1785 complete message, the receive call acts like a stream socket and 1786 returns as much data as will fit in the buffer. 1788 Note, the send and recv calls, when used in the UDP-style model, may 1789 only be used with branched off socket descriptors (see Section 8.2). 1791 Note, if an application calls a send function with no user data and 1792 no ancillary data the SCTP implementation should reject the request 1793 with an appropriate error message. An implementation is NOT allowed 1794 to send a Data chunk with no user data RFC2960 [8]. 1796 6.2 setsockopt(), getsockopt() 1798 Applications use setsockopt() and getsockopt() to set or retrieve 1799 socket options. Socket options are used to change the default 1800 behavior of sockets calls. They are described in Section 7 1802 The syntax is: 1804 ret = getsockopt(int sd, int level, int optname, void *optval, 1805 size_t *optlen); 1806 ret = setsockopt(int sd, int level, int optname, const void *optval, 1807 size_t optlen); 1809 sd - the socket descript. 1810 level - set to IPPROTO_SCTP for all SCTP options. 1811 optname - the option name. 1812 optval - the buffer to store the value of the option. 1813 optlen - the size of the buffer (or the length of the option 1814 returned). 1816 6.3 read() and write() 1818 Applications can use read() and write() to send and receive data to 1819 and from peer. They have the same semantics as send() and recv() 1820 except that the flags parameter cannot be used. 1822 Note, these calls, when used in the UDP-style model, may only be used 1823 with branched off socket descriptors (see Section 8.2). 1825 6.4 getsockname() 1827 Applications use getsockname() to retrieve the locally-bound socket 1828 address of the specified socket. This is especially useful if the 1829 caller let SCTP chose a local port. This call is for where the 1830 endpoint is not multi-homed. It does not work well with multi-homed 1831 sockets. See Section 8.5 for a multi-homed version of the call. 1833 The syntax is: 1835 int getsockname(int socket, struct sockaddr *address, 1836 socklen_t *len); 1838 sd - the socket descriptor to be queried. 1840 address - On return, one locally bound address (chosen by 1841 the SCTP stack) is stored in this buffer. If the 1842 socket is an IPv4 socket, the address will be IPv4. 1843 If the socket is an IPv6 socket, the address will 1844 be either an IPv6 or IPv4 address. 1846 len - The caller should set the length of address here. 1847 On return, this is set to the length of the returned 1848 address. 1850 If the actual length of the address is greater than the length of the 1851 supplied sockaddr structure, the stored address will be truncated. 1853 If the socket has not been bound to a local name, the value stored in 1854 the object pointed to by address is unspecified. 1856 7. Socket Options 1858 The following sub-section describes various SCTP level socket options 1859 that are common to both models. SCTP associations can be 1860 multi-homed. Therefore, certain option parameters include a 1861 sockaddr_storage structure to select which peer address the option 1862 should be applied to. 1864 For the UDP-style sockets, an sctp_assoc_t structure (association ID) 1865 is used to identify the the association instance that the operation 1866 affects. So it must be set when using this model. 1868 For the TCP-style sockets and branched off UDP-style sockets (see 1869 Section 8.2) this association ID parameter is ignored. In the cases 1870 noted below where the parameter is ignored, an application can pass 1871 to the system a corresponding option structure similar to those 1872 described below but without the association ID parameter, which 1873 should be the last field of the option structure. This can make the 1874 option setting/getting operation more efficient. If an application 1875 does this, it should also specify an appropriate optlen value (i.e. 1876 sizeof (option parameter) - sizeof (struct sctp_assoc_t)). 1878 Note that socket or IP level options is set or retrieved per socket. 1879 This means that for UDP-style sockets, those options will be applied 1880 to all associations belonging to the socket. And for TCP-style 1881 model, those options will be applied to all peer addresses of the 1882 association controlled by the socket. Applications should be very 1883 careful in setting those options. 1885 sctp_opt_info() 1887 For some implementations getsockopt() is read-only, so a new 1888 interface will be needed when information must be passed both in to 1889 and out of the SCTP stack. The syntax for scpt_opt_info() is, 1891 int sctp_opt_info(int sd, 1892 sctp_assoc_t id, 1893 int opt, 1894 void *arg, 1895 size_t *size); 1897 For UDP-style sockets, id specifies the association to query. For 1898 TCP-style sockets, id is ignored. 1900 opt specifies which SCTP socket option to get. It can any socket 1901 option currently supported that requests information (either read/ 1902 write options or read only) such as: 1904 SCTP_RTOINFO 1905 SCTP_ASSOCINFO 1906 SCTP_SET_PRIMARY_ADDR 1907 SCTP_SET_PEER_PRIMARY_ADDR 1908 SCTP_SET_PEER_ADDR_PARAMS 1909 SCTP_STATUS 1910 SCTP_GET_PEER_ADDR_INFO 1912 arg is an option-specific structure buffer provided by the caller. 1913 See Section 8.5) subsections for more information on these options 1914 and option-specific structures. 1916 sctp_opt_info() returns 0 on success, or on failure returns -1 and 1917 sets errno to the appropriate error code. 1919 All options that support specific settings on an association by 1920 filling in either an association id variable or a sockaddr_storage 1921 SHOULD also support setting of the same value for the entire endpoint 1922 (i.e. future associations). To accomplish this the following logic 1923 is used when setting one of these options: 1925 a) If an address is specified via a sockaddr_storage that is included 1926 in the structure the address is used to lookup the association and 1927 the settings are applied to the specific address (if appropriate) 1928 or to the entire association. 1930 b) If an association identification is filled in but not a 1931 sockaddr_storage (if present) the association is found using the 1932 association identification and the settings should be applied to 1933 the entire association (since a specific address is specified). 1934 Note this also applies to options that hold an association 1935 identification in their structure but do not have a 1936 sockaddr_storage field. 1938 c) If neither the sockaddr_storage or association identification is 1939 set i.e. the sockadd_storage is set to all 0's (INADDR_ANY) and 1940 the association identification is 0, the settings are a default 1941 and to be applied to the endpoint (all future associations). 1943 7.1 Read / Write Options 1945 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 1947 The protocol parameters used to initialize and bound retransmission 1948 timeout (RTO) are tunable. See RFC2960 [8] for more information on 1949 how these parameters are used in RTO calculation. The peer address 1950 parameter is ignored for TCP style socket. 1952 The following structure is used to access and modify these 1953 parameters: 1955 struct sctp_rtoinfo { 1956 sctp_assoc_t srto_assoc_id; 1957 uint32_t srto_initial; 1958 uint32_t srto_max; 1959 uint32_t srto_min; 1960 }; 1961 srto_initial - This contains the initial RTO value. 1962 srto_max and srto_min - These contain the maximum and minimum bounds 1963 for all RTOs. 1964 srto_assoc_id - (UDP style socket) This is filled in the application, 1965 and identifies the association for this query. If 1966 this parameter is missing (on a UDP style socket), 1967 then the change effects the entire endpoint. 1969 All parameters are time values, in milliseconds. A value of 0, when 1970 modifying the parameters, indicates that the current value should not 1971 be changed. 1973 To access or modify these parameters, the application should call 1974 getsockopt or setsockopt() respectively with the option name 1975 SCTP_RTOINFO. 1977 7.1.2 Association Parameters (SCTP_ASSOCINFO) 1979 This option is used to both examine and set various association and 1980 endpoint parameters. 1982 See RFC2960 [8] for more information on how this parameter is used. 1983 The peer address parameter is ignored for TCP style socket. 1985 The following structure is used to access and modify this parameters: 1987 struct sctp_assocparams { 1988 sctp_assoc_t sasoc_assoc_id; 1989 uint16_t sasoc_asocmaxrxt; 1990 uint16_t sasoc_number_peer_destinations; 1991 uint32_t sasoc_peer_rwnd; 1992 uint32_t sasoc_local_rwnd; 1993 uint32_t sasoc_cookie_life; 1994 }; 1995 sasoc_asocmaxrxt - This contains the maximum retransmission attempts 1996 to make for the association. 1998 sasoc_number_peer_destinations - This is the number of destination 1999 address that the peer considers 2000 valid. 2001 sasoc_peer_rwnd - This holds the current value of the peers 2002 rwnd (reported in the last SACK) minus any 2003 outstanding data (i.e. data inflight). 2004 sasoc_local_rwnd - This holds the last reported rwnd that was 2005 sent to the peer. 2006 sasoc_cookie_life - This is the associations cookie life value 2007 used when issuing cookies. 2008 sasoc_assoc_id - (UDP style socket) This is filled in the application, 2009 and identifies the association for this query. 2011 This information may be examined for either the endpoint or a 2012 specific association. To examine a endpoints default parameters the 2013 association id (sasoc_assoc_id) should must be set to the value '0'. 2014 The values of the sasoc_peer_rwnd is meaningless when examining 2015 endpoint information. 2017 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set 2018 on either an endpoint or association basis. The rwnd and destination 2019 counts (sasoc_number_peer_destinations, 2020 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value 2021 placed in these is ignored. 2023 To access or modify these parameters, the application should call 2024 getsockopt or setsockopt() respectively with the option name 2025 SCTP_ASSOCINFO. 2027 The maximum number of retransmissions before an address is considered 2028 unreachable is also tunable, but is address-specific, so it is 2029 covered in a separate option. If an application attempts to set the 2030 value of the association maximum retransmission parameter to more 2031 than the sum of all maximum retransmission parameters, setsockopt() 2032 shall return an error. The reason for this, from RFC2960 [8] section 2033 8.2: 2035 Note: When configuring the SCTP endpoint, the user should avoid 2036 having the value of 'Association.Max.Retrans' larger than the 2037 summation of the 'Path.Max.Retrans' of all the destination addresses 2038 for the remote endpoint. Otherwise, all the destination addresses 2039 may become inactive while the endpoint still considers the peer 2040 endpoint reachable. 2042 7.1.3 Initialization Parameters (SCTP_INITMSG) 2044 Applications can specify protocol parameters for the default 2045 association initialization. The structure used to access and modify 2046 these parameters is defined in Section 5.2.1). The option name 2047 argument to setsockopt() and getsockopt() is SCTP_INITMSG. 2049 Setting initialization parameters is effective only on an unconnected 2050 socket (for UDP-style sockets only future associations are effected 2051 by the change). With TCP-style sockets, this option is inherited by 2052 sockets derived from a listener socket. 2054 7.1.4 SO_LINGER 2056 An application using the TCP-style socket can use this option to 2057 perform the SCTP ABORT primitive. The linger option structure is: 2059 struct linger { 2060 int l_onoff; /* option on/off */ 2061 int l_linger; /* linger time */ 2062 }; 2064 To enable the option, set l_onoff to 1. If the l_linger value is set 2065 to 0, calling close() is the same as the ABORT primitive. If the 2066 value is set to a negative value, the setsockopt() call will return 2067 an error. If the value is set to a positive value linger_time, the 2068 close() can be blocked for at most linger_time ms. If the graceful 2069 shutdown phase does not finish during this period, close() will 2070 return but the graceful shutdown phase continues in the system. 2072 Note, this is a socket level option NOT an SCTP level option. So 2073 when setting SO_LINGER you must specify a level of SOL_SOCKET in the 2074 setsockopt() call. 2076 7.1.5 SCTP_NODELAY 2078 Turn on/off any Nagle-like algorithm. This means that packets are 2079 generally sent as soon as possible and no unnecessary delays are 2080 introduced, at the cost of more packets in the network. Expects an 2081 integer boolean flag. 2083 7.1.6 SO_RCVBUF 2085 Sets receive buffer size. For SCTP TCP-style sockets, this controls 2086 the receiver window size. For UDP-style sockets, this controls the 2087 receiver window size for all associations bound to the socket 2088 descriptor used in the setsockopt() or getsockopt() call. The option 2089 applies to each association's window size separately. Expects an 2090 integer. 2092 7.1.7 SO_SNDBUF 2094 Sets send buffer size. For SCTP TCP-style sockets, this controls the 2095 amount of data SCTP may have waiting in internal buffers to be sent. 2096 This option therefore bounds the maximum size of data that can be 2097 sent in a single send call. For UDP-style sockets, the effect is the 2098 same, except that it applies to all associations bound to the socket 2099 descriptor used in the setsockopt() or getsockopt() call. The option 2100 applies to each association's window size separately. Expects an 2101 integer. 2103 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 2105 This socket option is applicable to the UDP-style socket only. When 2106 set it will cause associations that are idle for more than the 2107 specified number of seconds to automatically close. An association 2108 being idle is defined an association that has NOT sent or received 2109 user data. The special value of '0' indicates that no automatic 2110 close of any associations should be performed. The option expects an 2111 integer defining the number of seconds of idle time before an 2112 association is closed. 2114 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) 2116 Requests that the peer mark the enclosed address as the association 2117 primary. The enclosed address must be one of the association's 2118 locally bound addresses. The following structure is used to make a 2119 set primary request: 2121 struct sctp_setprim { 2122 sctp_assoc_t ssp_assoc_id; 2123 struct sockaddr_storage ssp_addr; 2124 }; 2125 ssp_addr The address to set as primary 2126 ssp_assoc_id (UDP style socket) This is filled in by the 2127 application, and identifies the association 2128 for this request. 2130 This functionality is optional. Implementations that do not support 2131 this functionality should return EOPNOTSUPP. 2133 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 2135 Requests that the local SCTP stack use the enclosed peer address as 2136 the association primary. The enclosed address must be one of the 2137 association peer's addresses. The following structure is used to 2138 make a set peer primary request: 2140 struct sctp_setpeerprim { 2141 sctp_assoc_t sspp_assoc_id; 2142 struct sockaddr_storage sspp_addr; 2143 }; 2145 sspp_addr The address to set as primary 2146 sspp_assoc_id (UDP style socket) This is filled in by the 2147 application, and identifies the association 2148 for this request. 2150 7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER) 2152 Requests that the local endpoint set the specified Adaption Layer 2153 Indication parameter for all future INIT and INIT-ACK exchanges. 2155 struct sctp_setadaption { 2156 u_int32_t ssb_adaption_ind; 2157 }; 2159 ssb_adaption_ind The adaption layer indicator that will be included 2160 in any outgoing Adaption Layer Indication 2161 parameter. 2163 7.1.12 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS) 2165 This option is a on/off flag. If enabled no SCTP message 2166 fragmentation will be performed. Instead if a message being sent 2167 exceeds the current PMTU size, the message will NOT be sent and 2168 instead a error will be indicated to the user. 2170 7.1.13 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) 2172 Applications can enable or disable heartbeats for any peer address of 2173 an association, modify an address's heartbeat interval, force a 2174 heartbeat to be sent immediately, and adjust the address's maximum 2175 number of retransmissions sent before an address is considered 2176 unreachable. The following structure is used to access and modify an 2177 address's parameters: 2179 struct sctp_paddrparams { 2180 sctp_assoc_t spp_assoc_id; 2181 struct sockaddr_storage spp_address; 2182 uint32_t spp_hbinterval; 2183 uint16_t spp_pathmaxrxt; 2184 }; 2186 spp_assoc_id - (UDP style socket) This is filled in the application, 2187 and identifies the association for this query. 2188 spp_address - This specifies which address is of interest. 2189 spp_hbinterval - This contains the value of the heartbeat interval, 2190 in milliseconds. A value of 0, when modifying the 2191 parameter, specifies that the heartbeat on this 2192 address should be disabled. A value of UINT32_MAX 2193 (4294967295), when modifying the parameter, 2194 specifies that a heartbeat should be sent 2195 immediately to the peer address, and the current 2196 interval should remain unchanged. 2197 spp_pathmaxrxt - This contains the maximum number of 2198 retransmissions before this address shall be 2199 considered unreachable. 2201 To read or modify these parameters, the application should call 2202 sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. 2204 7.1.14 Set default send parameters (SET_DEFAULT_SEND_PARAM) 2206 Applications that wish to use the sendto() system call may wish to 2207 specify a default set of parameters that would normally be supplied 2208 through the inclusion of ancillary data. This socket option allows 2209 such an application to set the default sctp_sndrcvinfo structure. 2210 The application that wishes to use this socket option simply passes 2211 in to this call the sctp_sndrcvinfo structure defined in Section 2212 5.2.2) The input parameters accepted by this call include 2213 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, 2214 sinfo_timetolive. The user must provide the sinfo_assoc_id field in 2215 to this call if the caller is using the UDP model. 2217 7.1.15 Set notification and ancillary events (SCTP_SET_EVENTS) 2219 This socket option is used to specify various notifications and 2220 ancillary data the user wishes to receive. Please see Section 7.3) 2221 for a full description of this option and its usage. 2223 7.1.16 Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 2225 This socket option is a boolean flag which turns on or off mapped V4 2226 addresses. If this option is turned on and the socket is type 2227 PF_INET6, then IPv4 addresses will be mapped to V6 representation. 2228 If this option is turned off, then no mapping will be done of V4 2229 addresses and a user will receive both PF_INET6 and PF_INET type 2230 addresses on the socket. 2232 By default this option is turned on. 2234 7.1.17 Set the maximum fragrmentation size (SCTP_MAXSEG) 2236 This socket option specifies the maximum size to put in any outgoing 2237 SCTP chunk. If a message is larger than this size it will be 2238 fragmented by SCTP into the specified size. Note that the underlying 2239 SCTP implementation may fragment into smaller sized chunks when the 2240 PMTU of the underlying association is smaller than the value set by 2241 the user. 2243 7.2 Read-Only Options 2245 7.2.1 Association Status (SCTP_STATUS) 2247 Applications can retrieve current status information about an 2248 association, including association state, peer receiver window size, 2249 number of unacked data chunks, and number of data chunks pending 2250 receipt. This information is read-only. The following structure is 2251 used to access this information: 2253 struct sctp_status { 2254 sctp_assoc_t sstat_assoc_id; 2255 int32_t sstat_state; 2256 uint32_t sstat_rwnd; 2257 uint16_t sstat_unackdata; 2258 uint16_t sstat_penddata; 2259 uint16_t sstat_instrms; 2260 uint16_t sstat_outstrms; 2261 uint32_t sstat_fragmentation_point; 2262 struct sctp_paddrinfo sstat_primary; 2263 }; 2265 sstat_state - This contains the association's current state one 2266 of the following values: 2268 SCTP_CLOSED 2269 SCTP_BOUND 2270 SCTP_LISTEN 2271 SCTP_COOKIE_WAIT 2272 SCTP_COOKIE_ECHOED 2273 SCTP_ESTABLISHED 2274 SCTP_SHUTDOWN_PENDING 2275 SCTP_SHUTDOWN_SENT 2276 SCTP_SHUTDOWN_RECEIVED 2277 SCTP_SHUTDOWN_ACK_SENT 2279 sstat_rwnd - This contains the association peer's current 2280 receiver window size. 2281 sstat_unackdata - This is the number of unacked data chunks. 2282 sstat_penddata - This is the number of data chunks pending receipt. 2283 sstat_primary - This is information on the current primary peer 2284 address. 2285 sstat_assoc_id - (UDP style socket) This holds the an identifier for the 2286 association. All notifications for a given association 2287 have the same association identifier. 2289 sstat_instrms - The number of streams that the peer will 2290 be using inbound. 2292 sstat_outstrms - The number of streams that the endpoint is 2293 allowed to use outbound. 2295 sstat_fragmentation_point - The size at which SCTP fragmentation 2296 will occur. 2298 To access these status values, the application calls getsockopt() 2299 with the option name SCTP_STATUS. The sstat_assoc_id parameter is 2300 ignored for TCP style socket. 2302 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) 2304 Applications can retrieve information about a specific peer address 2305 of an association, including its reachability state, congestion 2306 window, and retransmission timer values. This information is 2307 read-only. The following structure is used to access this 2308 information: 2310 struct sctp_paddrinfo { 2311 sctp_assoc_t spinfo_assoc_id; 2312 struct sockaddr_storage spinfo_address; 2313 int32_t spinfo_state; 2314 uint32_t spinfo_cwnd; 2315 uint32_t spinfo_srtt; 2316 uint32_t spinfo_rto; 2317 uint32_t spinfo_mtu; 2318 }; 2320 spinfo_address - This is filled in the application, and contains 2321 the peer address of interest. 2323 On return from getsockopt(): 2325 spinfo_state - This contains the peer addresses's state (either 2326 SCTP_ACTIVE or SCTP_INACTIVE). 2327 spinfo_cwnd - This contains the peer addresses's current congestion 2328 window. 2329 spinfo_srtt - This contains the peer addresses's current smoothed 2330 round-trip time calculation in milliseconds. 2331 spinfo_rto - This contains the peer addresses's current 2332 retransmission timeout value in milliseconds. 2333 spinfo_mtu - The current P-MTU of this address. 2334 spinfo_assoc_id - (UDP style socket) This is filled in the application, 2335 and identifies the association for this query. 2337 To retrieve this information, use sctp_opt_info() with the 2338 SCTP_GET_PEER_ADDR_INFO options. 2340 7.3 Ancillary Data and Notification Interest Options 2342 Applications can receive per-message ancillary information and 2343 notifications of certain SCTP events with recvmsg(). 2345 The following optional information is available to the application: 2347 1. SCTP_SNDRCV: Per-message information (i.e. stream number, TSN, 2348 SSN, etc. described in Section 5.2.2) 2350 2. SCTP_ASSOC_CHANGE: (described in Section 5.3.1.1) 2352 3. SCTP_PEER_ADDR_CHANGE: (described in Section 5.3.1.2) 2354 4. SCTP_REMOTE_ERROR: (described in Section 5.3.1.3) 2356 5. SCTP_SEND_FAILED: (described in Section 5.3.1.4) 2357 6. SCTP_SHUTDOWN_EVENT: (described in Section 5.3.1.5) 2359 7. SCTP_ADAPTION_INDICATION: (described in Section 5.3.1.6) 2361 8. SCTP_PARTIAL_DELIVERY_EVENT: (described in Section 5.3.1.7) 2363 To receive any ancillary data or notifications, first the application 2364 registers it's interest by calling the SCTP_SET_EVENTS setsockopt() 2365 with the following structure. 2367 struct sctp_event_subscribe{ 2368 u_int8_t sctp_data_io_event; 2369 u_int8_t sctp_association_event; 2370 u_int8_t sctp_address_event; 2371 u_int8_t sctp_send_failure_event; 2372 u_int8_t sctp_peer_error_event; 2373 u_int8_t sctp_shutdown_event; 2374 u_int8_t sctp_partial_delivery_event; 2375 u_int8_t sctp_adaption_layer_event; 2376 }; 2378 sctp_data_io_event - Setting this flag to 1 will cause the reception 2379 of SCTP_SNDRCV information on a per message basis. The application 2380 will need to use the recvmsg() interface so that it can receive the 2381 event information contained in the msg_control field. Please see 2382 Section 5.2 for further details. Setting the flag to 0 will disable 2383 reception of the message control information. 2385 sctp_association_event - Setting this flag to 1 will enable the 2386 reception of association event notifications. Setting the flag to 0 2387 will disable association event notifications. For more information 2388 on event notifications please see Section 5.3. 2390 sctp_address_event - Setting this flag to 1 will enable the reception 2391 of address event notifications. Setting the flag to 0 will disable 2392 address event notifications. For more information on event 2393 notifications please see Section 5.3. 2395 sctp_send_failure_event - Setting this flag to 1 will enable the 2396 reception of send failure event notifications. Setting the flag to 0 2397 will disable send failure event notifications. For more information 2398 on event notifications please see Section 5.3. 2400 sctp_peer_error_event - Setting this flag to 1 will enable the 2401 reception of peer error event notifications. Setting the flag to 0 2402 will disable peer error event notifications. For more information on 2403 event notifications please see Section 5.3. 2405 sctp_shutdown_event - Setting this flag to 1 will enable the 2406 reception of shutdown event notifications. Setting the flag to 0 2407 will disable shutdown event notifications. For more information on 2408 event notifications please see Section 5.3. 2410 sctp_partial_delivery_event - Setting this flag to 1 will enable the 2411 reception of partial delivery notifications. Setting the flag to 0 2412 will disable partial delivery event notifications. For more 2413 information on event notifications please see Section 5.3. 2415 sctp_adaption_layer_event - Setting this flag to 1 will enable the 2416 reception of adaption layer notifications. Setting the flag to 0 2417 will disable adaption layer event notifications. For more 2418 information on event notifications please see Section 5.3. 2420 An example where an application would like to receive data io events 2421 and association events but no others would be as follows: 2423 { 2424 struct sctp_event_subscribe event; 2426 memset(&event,0,sizeof(event)); 2428 event.sctp_data_io_event = 1; 2429 event.sctp_association_event = 1; 2431 setsockopt(fd, IPPROTO_SCTP, SCTP_SET_EVENT, &event, sizeof(event)); 2432 } 2434 Note that for UDP-style SCTP sockets, the caller of recvmsg() 2435 receives ancillary data and notifications for ALL associations bound 2436 to the file descriptor. For TCP-style SCTP sockets, the caller 2437 receives ancillary data and notifications for only the single 2438 association bound to the file descriptor. 2440 By default a UDP-style socket has sctp_data_io_event and 2441 sctp_association_event on and all other options off. 2443 8. New Interfaces 2445 Depending on the system, the following interface can be implemented 2446 as a system call or library function. 2448 8.1 sctp_bindx() 2450 The syntax of sctp_bindx() is, 2452 int sctp_bindx(int sd, struct sockaddr_storage *addrs, int addrcnt, 2453 int flags); 2455 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. 2456 If the sd is an IPv6 socket, the addresses passed can either be IPv4 2457 or IPv6 addresses. 2459 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see 2460 Section 3.1.2 for this usage. 2462 addrs is a pointer to an array of one or more socket addresses. Each 2463 address is contained in a struct sockaddr_storage, so each address is 2464 a fixed length. The caller specifies the number of addresses in the 2465 array with addrcnt. 2467 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns 2468 -1, and sets errno to the appropriate error code. 2470 For SCTP, the port given in each socket address must be the same, or 2471 sctp_bindx() will fail, setting errno to EINVAL. 2473 The flags parameter is formed from the bitwise OR of zero or more of 2474 the following currently defined flags: 2476 SCTP_BINDX_ADD_ADDR 2478 SCTP_BINDX_REM_ADDR 2480 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the 2481 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given 2482 addresses from the association. The two flags are mutually 2483 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A 2484 caller may not remove all addresses from an association; sctp_bindx() 2485 will reject such an attempt with EINVAL. 2487 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate 2488 additional addresses with an endpoint after calling bind(). Or use 2489 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening 2490 socket is associated with so that no new association accepted will be 2491 associated with those addresses. If the endpoint supports dynamic 2492 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a 2493 endpoint to send the appropriate message to the peer to change the 2494 peers address lists. 2496 Adding and removing addresses from a connected association is 2497 optional functionality. Implementations that do not support this 2498 functionality should return EOPNOTSUPP. 2500 8.2 Branched-off Association 2502 After an association is established on a UDP-style socket, the 2503 application may wish to branch off the association into a separate 2504 socket/file descriptor. 2506 This is particularly desirable when, for instance, the application 2507 wishes to have a number of sporadic message senders/receivers remain 2508 under the original UDP-style socket but branch off those associations 2509 carrying high volume data traffic into their own separate socket 2510 descriptors. 2512 The application uses sctp_peeloff() call to branch off an association 2513 into a separate socket (Note the semantics are somewhat changed from 2514 the traditional TCP-style accept() call). 2516 The syntax is: 2518 new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id); 2520 the new socket descriptor representing the branched-off 2521 association. 2523 the original UDP-style socket descriptor returned from the 2524 socket() system call (see Section 3.1.1). 2526 the specified identifier of the association that is to be branched 2527 off to a separate file descriptor (Note, in a traditional 2528 TCP-style accept() call, this would be an out parameter, but for 2529 the UDP-style call, this is an in parameter). 2531 8.3 sctp_getpaddrs() 2533 sctp_getpaddrs() returns all peer addresses in an association. The 2534 syntax is, 2536 int sctp_getpaddrs(int sd, sctp_assoc_t id, 2537 struct sockaddr_storage **addrs); 2539 On return, addrs will point to a dynamically allocated array of 2540 struct sockaddr_storages, one for each peer address. The caller 2541 should use sctp_freepaddrs() 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 On success, sctp_getpaddrs() returns the number of peer addresses in 2552 the association. If there is no association on this socket, 2553 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If 2554 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs 2555 is undefined. 2557 8.4 sctp_freepaddrs() 2559 sctp_freepaddrs() frees all resources allocated by 2560 sctp_getpaddrs(). Its syntax is, 2562 void sctp_freepaddrs(struct sockaddr_storage *addrs); 2564 addrs is the array of peer addresses returned by sctp_getpaddrs(). 2566 8.5 sctp_getladdrs() 2568 sctp_getladdrs() returns all locally bound address on a socket. The 2569 syntax is, 2571 int sctp_getladdrs(int sock, sctp_assoc_t id, 2572 struct sockaddr_storage **ss); 2574 On return, addrs will point to a dynamically allocated array of 2575 struct sockaddr_storages, one for each local address. The caller 2576 should use sctp_freeladdrs() to free the memory. addrs must not be 2577 NULL. 2579 If sd is an IPv4 socket, the addresses returned will be all IPv4 2580 addresses. If sd is an IPv6 socket, the addresses returned can be a 2581 mix of IPv4 or IPv6 addresses. 2583 For UDP-style sockets, id specifies the association to query. For 2584 TCP-style sockets, id is ignored. 2586 If the id field is set to the value '0' then the locally bound 2587 addresses are returned without regard to any particular association. 2589 On success, sctp_getladdrs() returns the number of local addresses 2590 bound to the socket. If the socket is unbound, sctp_getladdrs() 2591 returns 0, and the value of *addrs is undefined. If an error occurs, 2592 sctp_getladdrs() returns -1, and the value of *addrs is undefined. 2594 8.6 sctp_freeladdrs() 2596 sctp_freeladdrs() frees all resources allocated by 2597 sctp_getladdrs(). Its syntax is, 2599 void sctp_freeladdrs(struct sockaddr_storage *addrs); 2601 addrs is the array of peer addresses returned by sctp_getladdrs(). 2603 8.7 sctp_sndmsg() 2605 An implementation may provide a library function (or possibly system 2606 call) to assist the user with the advanced features of SCTP. 2608 sctp_sendmsg(). Its syntax is, 2610 void sctp_sendmsg(int s, const void *msg, size_t len, 2611 uint32_t ppid, 2612 uint32_t flags, 2613 uint16_t stream_no, 2614 uint32_t timetolive, 2615 uint32_t context) 2617 s - is the socket descriptor 2618 msg - is the message to be sent. 2619 len - is the length of the message. 2620 ppid - is the same as sinfo_ppid (see section 5.2.2) 2621 flags - is the same as sinfo_flags (see section 5.2.2) 2622 stream_no - is the same as sinfo_stream (see section 5.2.2) 2623 timetolive - is the same as sinfo_timetolive (see section 5.2.2) 2624 context - is the same as sinfo_context (see section 5.2.2) 2626 9. Preprocessor Constants 2628 For application portability it is desireable to define pre-processor 2629 constants for determination if sctp is present and supports various 2630 features. The following pre-processor constants should be defined in 2631 a include file, sctp.h. 2633 HAVE_SCTP - If this constant is defined to 1, then an implementation 2634 of SCTP is available. 2636 HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel 2637 SCTP implementation is available through the sockets interface. 2639 HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP 2640 implementation supports the partial reliablility extension to 2641 SCTP. 2643 HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP 2644 implementation supports the dynamic address extension to SCTP. 2646 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the 2647 SCTP implementation supports the ability to request setting of the 2648 remote primary address. 2650 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1, 2651 then the SCTP implementation supports the satellite network 2652 extension to SCTP. 2654 10. Security Considerations 2656 Many TCP and UDP implementations reserve port numbers below 1024 for 2657 privileged users. If the target platform supports privileged users, 2658 the SCTP implementation SHOULD restrict the ability to call bind() or 2659 sctp_bindx() on these port numbers to privileged users. 2661 Similarly unprevledged users should not be able to set protocol 2662 parameters which could result in the congestion control algorithm 2663 being more aggressive than permitted on the public Internet. These 2664 parameters are: 2666 struct sctp_rtoinfo 2668 If an unprivileged user inherits a UDP-style socket with open 2669 associations on a privileged port, it MAY be permitted to accept new 2670 associations, but it SHOULD NOT be permitted to open new 2671 associations. This could be relevant for the r* family of protocols. 2673 11. Acknowledgments 2675 The authors wish to thank Kavitha Baratakke, Mike Bartlett, Jon 2676 Berger, Scott Kimble, Renee Revis, and many others on the TSVWG 2677 mailing list for contributing valuable comments. 2679 A special thanks to Phillip Conrad, for his suggested text, quick and 2680 constructive insights, and most of all his persistent fighting to 2681 keep the interface to SCTP usable for the application programmer. 2683 References 2685 [1] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, 2686 September 1981. 2688 [2] Postel, J., "User Datagram Protocol", STD 6, RFC 768, August 2689 1980. 2691 [3] Braden, B., "T/TCP -- TCP Extensions for Transactions Functional 2692 Specification", RFC 1644, July 1994. 2694 [4] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 2695 9, RFC 2026, October 1996. 2697 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2698 Levels", BCP 14, RFC 2119, March 1997. 2700 [6] Stevens, W. and M. Thomas, "Advanced Sockets API for IPv6", RFC 2701 2292, February 1998. 2703 [7] Gilligan, R., Thomson, S., Bound, J. and W. Stevens, "Basic 2704 Socket Interface Extensions for IPv6", RFC 2553, March 1999. 2706 [8] Stewart, R., Xie, Q., Morneault, K., Sharp, C., Schwarzbauer, 2707 H., Taylor, T., Rytina, I., Kalla, M., Zhang, L. and V. Paxson, 2708 "Stream Control Transmission Protocol", RFC 2960, October 2000. 2710 Authors' Addresses 2712 Randall R. Stewart 2713 Cisco Systems, Inc. 2714 8725 West Higgins Road 2715 Suite 300 2716 Chicago, IL 60631 2717 USA 2719 Phone: 2720 EMail: rrs@cisco.com 2722 Qiaobing Xie 2723 Motorola, Inc. 2724 1501 W. Shure Drive, #2309 2725 Arlington Heights, IL 60004 2726 USA 2728 Phone: 2730 EMail: qxie1@email.mot.com 2732 La Monte H.P. Yarroll 2733 Motorola, Inc. 2734 1501 W. Shure Drive, IL-2315 2735 Arlington Heights, IL 60004 2736 USA 2738 Phone: 2739 EMail: piggy@acm.org 2741 Jonathan Wood 2742 DoCoMo USA Labs 2743 181 Metro Drive, Suite 300 2744 San Jose, CA 95110 2745 USA 2747 Phone: 2748 EMail: jonwood@speakeasy.net 2750 Kacheong Poon 2751 Consultant 2753 Milpitas, CA 2755 Phone: 2756 EMail: kcpoon@yahoo.com 2758 Ken Fujita 2759 NEC USA, Inc. 2760 10080 Wolfe Road, Suite SW3-350 2761 Cupertino, CA 95014 2762 USA 2764 Phone: 2765 EMail: fken@ccrl.sj.nec.com 2767 Michael Tuexen 2769 Germany 2771 Phone: 2773 EMail: tuexen@fh-muenster.de 2775 Appendix A. TCP-style Code Example 2777 The following code is a simple implementation of an echo server over 2778 SCTP. The example shows how to use some features of TCP-style IPv4 2779 SCTP sockets, including: 2781 o Opening, binding, and listening for new associations on a socket; 2783 o Enabling ancillary data 2785 o Enabling notifications 2787 o Using ancillary data with sendmsg() and recvmsg() 2789 o Using MSG_EOR to determine if an entire message has been read 2791 o Handling notifications 2793 #include 2794 #include 2795 #include 2796 #include 2797 #include 2798 #include 2799 #include 2800 #include 2801 #include 2803 #define BUFLEN 100 2805 static void 2806 handle_event(void *buf) 2807 { 2808 struct sctp_assoc_change *sac; 2809 struct sctp_send_failed *ssf; 2810 struct sctp_paddr_change *spc; 2811 struct sctp_remote_error *sre; 2812 union sctp_notification *snp; 2813 char addrbuf[INET6_ADDRSTRLEN]; 2814 const char *ap; 2815 struct sockaddr_in *sin; 2816 struct sockaddr_in6 *sin6; 2818 snp = buf; 2820 switch (snp->sn_header.sn_type) { 2821 case SCTP_ASSOC_CHANGE: 2823 sac = &snp->sn_assoc_change; 2824 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " 2825 "outstr=%hu\n", sac->sac_state, sac->sac_error, 2826 sac->sac_inbound_streams, sac->sac_outbound_streams); 2827 break; 2828 case SCTP_SEND_FAILED: 2829 ssf = &snp->sn_send_failed; 2830 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, 2831 ssf->ssf_error); 2832 break; 2834 case SCTP_PEER_ADDR_CHANGE: 2835 spc = &snp->sn_paddr_change; /* mt changed */ 2836 if (spc->spc_aaddr.ss_family == AF_INET) { 2837 sin = (struct sockaddr_in *)&spc->spc_aaddr; 2838 ap = inet_ntop(AF_INET, &sin->sin_addr, 2839 addrbuf, INET6_ADDRSTRLEN); 2840 } else { 2841 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr; 2842 ap = inet_ntop(AF_INET6, &sin6->sin6_addr, 2843 addrbuf, INET6_ADDRSTRLEN); 2844 } 2845 printf("^^^ intf_change: %s state=%d, error=%d\n", ap, 2846 spc->spc_state, spc->spc_error); 2847 break; 2848 case SCTP_REMOTE_ERROR: 2849 sre = &snp->sn_remote_error; 2850 printf("^^^ remote_error: err=%hu len=%hu\n", 2851 ntohs(sre->sre_error), ntohs(sre->sre_len)); 2852 break; 2853 case SCTP_SHUTDOWN_EVENT: 2854 printf("^^^ shutdown event\n"); 2855 break; 2856 default: 2857 printf("unknown type: %hu\n", snp->sn_header.sn_type); 2858 break; 2859 } 2860 } 2862 static void * 2863 sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, 2864 ssize_t *nrp, size_t cmsglen) 2865 { 2866 ssize_t nr = 0, nnr = 0; 2867 struct iovec iov[1]; 2869 *nrp = 0; 2870 iov->iov_base = buf; 2872 iov->iov_len = *buflen; 2873 msg->msg_iov = iov; 2874 msg->msg_iovlen = 1; 2876 for (;;) { 2877 #ifndef MSG_XPG4_2 2878 #define MSG_XPG4_2 0 2879 #endif 2880 msg->msg_flags = MSG_XPG4_2; 2881 msg->msg_controllen = cmsglen; 2883 nnr = recvmsg(fd, msg, 0); 2884 if (nnr <= 0) { 2885 /* EOF or error */ 2886 *nrp = nr; 2887 return (NULL); 2888 } 2889 nr += nnr; 2891 if ((msg->msg_flags & MSG_EOR) != 0) { 2892 *nrp = nr; 2893 return (buf); 2894 } 2896 /* Realloc the buffer? */ 2897 if (*buflen == nr) { 2898 buf = realloc(buf, *buflen * 2); 2899 if (buf == 0) { 2900 fprintf(stderr, "out of memory\n"); 2901 exit(1); 2902 } 2903 *buflen *= 2; 2904 } 2906 /* Set the next read offset */ 2907 iov->iov_base = (char *)buf + nr; 2908 iov->iov_len = *buflen - nr; 2910 } 2911 } 2913 static void 2914 echo(int fd, int socketModeUDP) 2915 { 2916 ssize_t nr; 2917 struct sctp_sndrcvinfo *sri; 2918 struct msghdr msg[1]; 2919 struct cmsghdr *cmsg; 2920 char cbuf[sizeof (*cmsg) + sizeof (*sri)]; 2921 char *buf; 2922 size_t buflen; 2923 struct iovec iov[1]; 2924 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri); 2926 /* Allocate the initial data buffer */ 2927 buflen = BUFLEN; 2928 if (!(buf = malloc(BUFLEN))) { 2929 fprintf(stderr, "out of memory\n"); 2930 exit(1); 2931 } 2933 /* Set up the msghdr structure for receiving */ 2934 memset(msg, 0, sizeof (*msg)); 2935 msg->msg_control = cbuf; 2936 msg->msg_controllen = cmsglen; 2937 msg->msg_flags = 0; 2938 cmsg = (struct cmsghdr *)cbuf; 2939 sri = (struct sctp_sndrcvinfo *)(cmsg + 1); 2941 /* Wait for something to echo */ 2942 while (buf = sctp_recvmsg(fd, msg, buf, &buflen, &nr, cmsglen)) { 2944 /* Intercept notifications here */ 2945 if (msg->msg_flags & MSG_NOTIFICATION) { 2946 handle_event(buf); 2947 continue; 2948 } 2950 iov->iov_base = buf; 2951 iov->iov_len = nr; 2952 msg->msg_iov = iov; 2953 msg->msg_iovlen = 1; 2955 printf("got %u bytes on stream %hu:\n", nr, 2956 sri->sinfo_stream); 2957 write(0, buf, nr); 2959 /* Echo it back */ 2960 msg->msg_flags = MSG_XPG4_2; 2961 if (sendmsg(fd, msg, 0) < 0) { 2962 perror("sendmsg"); 2963 exit(1); 2964 } 2965 } 2966 if (nr < 0) { 2967 perror("recvmsg"); 2968 } 2969 if(socketModeUDP == 0) 2970 close(fd); 2971 } 2973 int main() 2974 { 2975 int lfd, cfd; 2976 int onoff = 1; 2977 struct sockaddr_in sin[1]; 2979 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) { 2980 perror("socket"); 2981 exit(1); 2982 } 2984 sin->sin_family = AF_INET; 2985 sin->sin_port = htons(7); 2986 sin->sin_addr.s_addr = INADDR_ANY; 2987 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 2988 perror("bind"); 2989 exit(1); 2990 } 2992 if (listen(lfd, 1) == -1) { 2993 perror("listen"); 2994 exit(1); 2995 } 2997 /* Wait for new associations */ 2998 for (;;) { 2999 struct sctp_event_subscribe event; 3000 if ((cfd = accept(lfd, NULL, 0)) == -1) { 3001 perror("accept"); 3002 exit(1); 3003 } 3005 /* Enable all events */ 3006 event.sctp_data_io_event = 1; 3007 event.sctp_association_event = 1; 3008 event.sctp_address_event = 1; 3009 event.sctp_send_failure_event = 1; 3010 event.sctp_peer_error_event = 1; 3011 event.sctp_shutdown_event = 1; 3012 event.sctp_partial_delivery_event = 1; 3013 event.sctp_adaption_layer_event = 1; 3014 if (setsockopt(cfd, IPPROTO_SCTP, 3015 SCTP_SET_EVENTS, &event, 3016 sizeof(event)) != 0) { 3017 perror("setevent failed"); 3018 exit(1); 3019 } 3020 /* Echo back any and all data */ 3021 echo(cfd,0); 3022 } 3023 } 3025 Appendix B. UDP-style Code Example 3027 The following code is a simple implementation of an echo server over 3028 SCTP. The example shows how to use some features of UDP-style IPv4 3029 SCTP sockets, including: 3031 o Opening and binding of a socket; 3033 o Enabling ancillary data 3035 o Enabling notifications 3037 o Using ancillary data with sendmsg() and recvmsg() 3039 o Using MSG_EOR to determine if an entire message has been read 3041 o Handling notifications 3043 Note most functions defined in Appendix A are reused in this example. 3045 int main() 3046 { 3047 int fd; 3048 int onoff = 1; 3049 int idleTime = 2; 3050 struct sockaddr_in sin[1]; 3051 struct sctp_event_subscribe event; 3053 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { 3054 perror("socket"); 3055 exit(1); 3056 } 3058 sin->sin_family = AF_INET; 3059 sin->sin_port = htons(7); 3060 sin->sin_addr.s_addr = INADDR_ANY; 3061 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { 3062 perror("bind"); 3063 exit(1); 3064 } 3066 /* Enable all notifications and events */ 3067 event.sctp_data_io_event = 1; 3068 event.sctp_association_event = 1; 3069 event.sctp_address_event = 1; 3070 event.sctp_send_failure_event = 1; 3071 event.sctp_peer_error_event = 1; 3072 event.sctp_shutdown_event = 1; 3073 event.sctp_partial_delivery_event = 1; 3074 event.sctp_adaption_layer_event = 1; 3075 if (setsockopt(fd, IPPROTO_SCTP, 3076 SCTP_SET_EVENTS, &event, 3077 sizeof(event)) != 0) { 3078 perror("setevent failed"); 3079 exit(1); 3080 } 3081 /* Set associations to auto-close in 2 seconds of 3082 * inactivity 3083 */ 3084 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, 3085 &idleTime, 4) < 0) { 3086 perror("setsockopt SCTP_AUTOCLOSE"); 3087 exit(1); 3088 } 3090 /* Allow new associations to be accepted */ 3091 if (listen(fd, 0) < 0) { 3092 perror("listen"); 3093 exit(1); 3094 } 3096 /* Wait for new associations */ 3097 while(1){ 3098 /* Echo back any and all data */ 3099 echo(fd,1); 3100 } 3101 } 3103 Intellectual Property Statement 3105 The IETF takes no position regarding the validity or scope of any 3106 intellectual property or other rights that might be claimed to 3107 pertain to the implementation or use of the technology described in 3108 this document or the extent to which any license under such rights 3109 might or might not be available; neither does it represent that it 3110 has made any effort to identify any such rights. Information on the 3111 IETF's procedures with respect to rights in standards-track and 3112 standards-related documentation can be found in BCP-11. Copies of 3113 claims of rights made available for publication and any assurances of 3114 licenses to be made available, or the result of an attempt made to 3115 obtain a general license or permission for the use of such 3116 proprietary rights by implementors or users of this specification can 3117 be obtained from the IETF Secretariat. 3119 The IETF invites any interested party to bring to its attention any 3120 copyrights, patents or patent applications, or other proprietary 3121 rights which may cover technology that may be required to practice 3122 this standard. Please address the information to the IETF Executive 3123 Director. 3125 Full Copyright Statement 3127 Copyright (C) The Internet Society (2003). All Rights Reserved. 3129 This document and translations of it may be copied and furnished to 3130 others, and derivative works that comment on or otherwise explain it 3131 or assist in its implementation may be prepared, copied, published 3132 and distributed, in whole or in part, without restriction of any 3133 kind, provided that the above copyright notice and this paragraph are 3134 included on all such copies and derivative works. However, this 3135 document itself may not be modified in any way, such as by removing 3136 the copyright notice or references to the Internet Society or other 3137 Internet organizations, except as needed for the purpose of 3138 developing Internet standards in which case the procedures for 3139 copyrights defined in the Internet Standards process must be 3140 followed, or as required to translate it into languages other than 3141 English. 3143 The limited permissions granted above are perpetual and will not be 3144 revoked by the Internet Society or its successors or assignees. 3146 This document and the information contained herein is provided on an 3147 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3148 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3149 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3150 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3151 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3153 Acknowledgement 3155 Funding for the RFC Editor function is currently provided by the 3156 Internet Society.