4 Network Working Group R. Stewart
5 Internet-Draft Cisco Systems, Inc.
6 Expires: June 14, 2007 Q. Xie
11 Sun Microsystems, Inc.
13 Univ. of Applied Sciences Muenster
17 Sockets API Extensions for Stream Control Transmission Protocol (SCTP)
18 draft-ietf-tsvwg-sctpsocket-14.txt
22 By submitting this Internet-Draft, each author represents that any
23 applicable patent or other IPR claims of which he or she is aware
24 have been or will be disclosed, and any of which he or she becomes
25 aware will be disclosed, in accordance with Section 6 of BCP 79.
27 Internet-Drafts are working documents of the Internet Engineering
28 Task Force (IETF), its areas, and its working groups. Note that
29 other groups may also distribute working documents as Internet-
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as "work in progress."
37 The list of current Internet-Drafts can be accessed at
38 http://www.ietf.org/ietf/1id-abstracts.txt.
40 The list of Internet-Draft Shadow Directories can be accessed at
41 http://www.ietf.org/shadow.html.
43 This Internet-Draft will expire on June 14, 2007.
47 Copyright (C) The IETF Trust (2006).
51 This document describes a mapping of the Stream Control Transmission
55 Stewart, et al. Expires June 14, 2007 [Page 1]
57 Internet-Draft SCTP sockets API December 2006
60 Protocol SCTP into a sockets API. The benefits of this mapping
61 include compatibility for TCP applications, access to new SCTP
62 features and a consolidated error and event notification scheme.
67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
68 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6
69 2.1. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6
70 3. one-to-many style Interface . . . . . . . . . . . . . . . . . 6
71 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6
72 3.1.1. socket() - one-to-many style socket . . . . . . . . . 7
73 3.1.2. bind() - one-to-many style socket . . . . . . . . . . 8
74 3.1.3. listen() - One-to-many style socket . . . . . . . . . 9
75 3.1.4. sendmsg() and recvmsg() - one-to-many style socket . . 9
76 3.1.5. close() - one-to-many style socket . . . . . . . . . . 11
77 3.1.6. connect() - one-to-many style socket . . . . . . . . . 11
78 3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12
79 3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13
80 3.4. Special considerations . . . . . . . . . . . . . . . . . . 13
81 4. one-to-one style Interface . . . . . . . . . . . . . . . . . . 15
82 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 15
83 4.1.1. socket() - one-to-one style socket . . . . . . . . . . 16
84 4.1.2. bind() - one-to-one style socket . . . . . . . . . . . 16
85 4.1.3. listen() - one-to-one style socket . . . . . . . . . . 17
86 4.1.4. accept() - one-to-one style socket . . . . . . . . . . 18
87 4.1.5. connect() - one-to-one style socket . . . . . . . . . 18
88 4.1.6. close() - one-to-one style socket . . . . . . . . . . 19
89 4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 19
90 4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20
91 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 20
92 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21
93 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21
94 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22
95 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23
96 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 24
97 5.2.3. Extended SCTP Header Information Structure
98 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 27
99 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 31
100 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 31
101 5.4. Ancillary Data Considerations and Semantics . . . . . . . 42
102 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 42
103 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 42
104 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 43
105 6. Common Operations for Both Styles . . . . . . . . . . . . . . 44
106 6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 44
107 6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 45
111 Stewart, et al. Expires June 14, 2007 [Page 2]
113 Internet-Draft SCTP sockets API December 2006
116 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 46
117 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 46
118 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 47
119 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 48
120 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 48
121 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 49
122 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 51
123 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 51
124 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 51
125 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 51
126 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 52
127 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 52
128 7.1.9. Set Peer Primary Address
129 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 52
130 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 53
131 7.1.11. Set Adaptation Layer Indicator
132 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 53
133 7.1.12. Enable/Disable message fragmentation
134 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 53
135 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 54
136 7.1.14. Set default send parameters
137 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 56
138 7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 57
139 7.1.16. Set/clear IPv4 mapped addresses
140 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 57
141 7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG) . . . 57
142 7.1.18. Add a chunk that must be authenticated
143 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 57
144 7.1.19. Get or set the list of supported HMAC Identifiers
145 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 58
146 7.1.20. Set a shared key (SCTP_AUTH_KEY) . . . . . . . . . . . 58
147 7.1.21. Get or set the active shared key
148 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 59
149 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) . . . . . . 59
150 7.1.23. Get or set delayed ack timer
151 (SCTP_DELAYED_ACK_TIME) . . . . . . . . . . . . . . . 60
152 7.1.24. Get or set fragmented interleave
153 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 60
154 7.1.25. Set or Get the sctp partial delivery point
155 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 61
156 7.1.26. Set or Get the use of extended receive info
157 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 61
158 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) . . 61
159 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) . . . . 61
160 7.1.29. Set or Get the default context (SCTP_CONTEXT) . . . . 62
161 7.1.30. Enable or disable explicit EOR marking
162 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 62
163 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 62
167 Stewart, et al. Expires June 14, 2007 [Page 3]
169 Internet-Draft SCTP sockets API December 2006
172 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 62
173 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 64
174 7.2.3. Get the list of chunks the peer requires to be
175 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 65
176 7.2.4. Get the list of chunks the local endpoint requires
177 to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 65
178 7.2.5. Get the list of current associations
179 (SCTP_GET_ASOC_ID_LIST) . . . . . . . . . . . . . . . 65
180 7.3. Ancillary Data and Notification Interest Options . . . . . 66
181 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 68
182 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 69
183 8.2. Branched-off Association . . . . . . . . . . . . . . . . . 70
184 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 70
185 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 71
186 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 71
187 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 72
188 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 72
189 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 73
190 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 73
191 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 74
192 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 75
193 8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 76
194 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . . 76
195 10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 77
196 11. Security Considerations . . . . . . . . . . . . . . . . . . . 77
197 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 77
198 13. Normative references . . . . . . . . . . . . . . . . . . . . . 78
199 Appendix A. one-to-one style Code Example . . . . . . . . . . . . 78
200 Appendix B. one-to-many style Code Example . . . . . . . . . . . 84
201 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 85
202 Intellectual Property and Copyright Statements . . . . . . . . . . 87
223 Stewart, et al. Expires June 14, 2007 [Page 4]
225 Internet-Draft SCTP sockets API December 2006
230 The sockets API has provided a standard mapping of the Internet
231 Protocol suite to many operating systems. Both TCP RFC793 [RFC0793]
232 and UDP RFC768 [RFC0768] have benefited from this standard
233 representation and access method across many diverse platforms. SCTP
234 is a new protocol that provides many of the characteristics of TCP
235 but also incorporates semantics more akin to UDP. This document
236 defines a method to map the existing sockets API for use with SCTP,
237 providing both a base for access to new features and compatibility so
238 that most existing TCP applications can be migrated to SCTP with few
241 There are three basic design objectives:
243 1) Maintain consistency with existing sockets APIs:
244 We define a sockets mapping for SCTP that is consistent with other
245 sockets API protocol mappings (for instance, UDP, TCP, IPv4, and
247 2) Support a one-to-many style interface
248 This set of semantics is similar to that defined for connection-
249 less protocols, such as UDP. A one-to-many style SCTP socket
250 should be able to control multiple SCTP associations. This is
251 similar to an UDP socket, which can communicate with many peer end
252 points. Each of these associations is assigned an association ID
253 so that an applications can use the ID to differentiate them.
254 Note that SCTP is connection-oriented in nature, and it does not
255 support broadcast or multicast communications, as UDP does.
256 3) Support a one-to-one style interface
257 This interface supports a similar semantics as sockets for
258 connection-oriented protocols, such as TCP. A one-to-one style
259 SCTP socket should only control one SCTP association.
260 One purpose of defining this interface is to allow existing
261 applications built on other connection-oriented protocols be
262 ported to use SCTP with very little effort. And developers
263 familiar with those semantics can easily adapt to SCTP. Another
264 purpose is to make sure that existing mechanisms in most OSes to
265 deal with socket, such as select(), should continue to work with
266 this style of socket.
267 Extensions are added to this mapping to provide mechanisms to
268 exploit new features of SCTP.
270 Goals 2 and 3 are not compatible, so in this document we define two
271 modes of mapping, namely the one-to-many style mapping and the one-
272 to-one style mapping. These two modes share some common data
273 structures and operations, but will require the use of two different
274 application programming styles. Note that all new SCTP features can
275 be used with both styles of socket. The decision on which one to use
279 Stewart, et al. Expires June 14, 2007 [Page 5]
281 Internet-Draft SCTP sockets API December 2006
284 depends mainly on the nature of applications.
286 A mechanism is defined to extract a one-to-many style SCTP
287 association into a one-to-one style socket.
289 Some of the SCTP mechanisms cannot be adequately mapped to existing
290 socket interface. In some cases, it is more desirable to have new
291 interface instead of using existing socket calls. Section 8 of this
292 document describes those new interface.
299 Whenever possible, data types from Draft 6.6 (March 1997) of POSIX
300 1003.1g are used: uintN_t means an unsigned integer of exactly N bits
301 (e.g., uint16_t). We also assume the argument data types from
302 1003.1g when possible (e.g., the final argument to setsockopt() is a
303 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1
304 size_t data type is used.
307 3. one-to-many style Interface
309 The one-to-many style interface has the following characteristics:
311 A) Outbound association setup is implicit.
313 B) Messages are delivered in complete messages (with one notable
316 C) There is a 1 to MANY relationship between socket and association.
320 A typical server in this style uses the following socket calls in
321 sequence to prepare an endpoint for servicing requests:
330 A typical client uses the following calls in sequence to setup an
331 association with a server to request services:
335 Stewart, et al. Expires June 14, 2007 [Page 6]
337 Internet-Draft SCTP sockets API December 2006
345 In this style, by default, all the associations connected to the
346 endpoint are represented with a single socket. Each associations is
347 assigned an association ID (type is sctp_assoc_t) so that an
348 application can use it to differentiate between them. In some
349 implementations, the peer endpoints addresses can also be used for
350 this purpose. But this is not required for performance reasons. If
351 an implementation does not support using addresses to differentiate
352 between different associations, the sendto() call can only be used to
353 setup an association implicitly. It cannot be used to send data to
354 an established association as the association ID cannot be specified.
356 Once as association ID is assigned to an SCTP association, that ID
357 will not be reused until the application explicitly terminates the
358 association. The resources belonged to that association will not be
359 freed until that happens. This is similar to the close() operation
360 on a normal socket. The only exception is when the SCTP_AUTOCLOSE
361 option (section 7.1.8) is set. In this case, after the association
362 is terminated gracefully automatically, the association ID assigned
363 to it can be reused. All applications using this option should be
364 aware of this to avoid the possible problem of sending data to an
365 incorrect peer end point.
367 If the server or client wishes to branch an existing association off
368 to a separate socket, it is required to call sctp_peeloff() and in
369 the parameter specifies the association identification. The
370 sctp_peeloff() call will return a new socket which can then be used
371 with recv() and send() functions for message passing. See
372 Section 8.2 for more on branched-off associations.
374 Once an association is branched off to a separate socket, it becomes
375 completely separated from the original socket. All subsequent
376 control and data operations to that association must be done through
377 the new socket. For example, the close operation on the original
378 socket will not terminate any associations that have been branched
379 off to a different socket.
381 We will discuss the one-to-many style socket calls in more details in
382 the following subsections.
384 3.1.1. socket() - one-to-many style socket
386 Applications use socket() to create a socket descriptor to represent
391 Stewart, et al. Expires June 14, 2007 [Page 7]
393 Internet-Draft SCTP sockets API December 2006
398 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
402 sd = socket(PF_INET6, SOCK_SEQPACKET, IPPROTO_SCTP);
404 Here, SOCK_SEQPACKET indicates the creation of a one-to-many style
407 The first form creates an endpoint which can use only IPv4 addresses,
408 while, the second form creates an endpoint which can use both IPv6
411 3.1.2. bind() - one-to-many style socket
413 Applications use bind() to specify which local address the SCTP
414 endpoint should associate itself with.
416 An SCTP endpoint can be associated with multiple addresses. To do
417 this, sctp_bindx() is introduced in section Section 8.1 to help
418 applications do the job of associating multiple addresses.
420 These addresses associated with a socket are the eligible transport
421 addresses for the endpoint to send and receive data. The endpoint
422 will also present these addresses to its peers during the association
423 initialization process, see RFC2960 [RFC2960].
425 After calling bind(), if the endpoint wishes to accept new
426 associations on the socket, it must call listen() (see section
429 The syntax of bind() is,
431 ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen);
433 sd - the socket descriptor returned by socket().
434 addr - the address structure (struct sockaddr_in or struct
435 sockaddr_in6 RFC2553 [RFC2553]).
436 addrlen - the size of the address structure.
438 If sd is an IPv4 socket, the address passed must be an IPv4 address.
439 If the sd is an IPv6 socket, the address passed can either be an IPv4
442 Applications cannot call bind() multiple times to associate multiple
443 addresses to an endpoint. After the first call to bind(), all
447 Stewart, et al. Expires June 14, 2007 [Page 8]
449 Internet-Draft SCTP sockets API December 2006
452 subsequent calls will return an error.
454 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address,
455 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the
456 operating system will associate the endpoint with an optimal address
457 set of the available interfaces.
459 If a bind() is not called prior to a sendmsg() call that initiates a
460 new association, the system picks an ephemeral port and will choose
461 an address set equivalent to binding with a wildcard address. One of
462 those addresses will be the primary address for the association.
463 This automatically enables the multi-homing capability of SCTP.
465 3.1.3. listen() - One-to-many style socket
467 By default, new associations are not accepted for one-to-many style
468 sockets. An application uses listen() to mark a socket as being able
469 to accept new associations. The syntax is,
472 int listen(int sd, int backlog);
475 sd - the socket descriptor of the endpoint.
476 backlog - if backlog is non-zero, enable listening else disable
479 Note that one-to-many style socket consumers do not need to call
480 accept to retrieve new associations. Calling accept() on a one-to-
481 many style socket should return EOPNOTSUPP. Rather, new associations
482 are accepted automatically, and notifications of the new associations
483 are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if
484 these notifications are enabled). Clients will typically not call
485 listen(), so that they can be assured that the only associations on
486 the socket will be ones they actively initiated. Server or peer-to-
487 peer sockets, on the other hand, will always accept new associations,
488 so a well-written application using server one-to-many style sockets
489 must be prepared to handle new associations from unwanted peers.
491 Also note that the SCTP_ASSOC_CHANGE event provides the association
492 ID for a new association, so if applications wish to use the
493 association ID as input to other socket calls, they should ensure
494 that the SCTP_ASSOC_CHANGE event is enabled.
496 3.1.4. sendmsg() and recvmsg() - one-to-many style socket
498 An application uses sendmsg() and recvmsg() call to transmit data to
499 and receive data from its peer.
503 Stewart, et al. Expires June 14, 2007 [Page 9]
505 Internet-Draft SCTP sockets API December 2006
508 ssize_t sendmsg(int sd, const struct msghdr *message, int flags);
510 ssize_t recvmsg(int sd, struct msghdr *message, int flags);
512 sd - the socket descriptor of the endpoint.
513 message: pointer to the msghdr structure which contains a single
514 user message and possibly some ancillary data. See Section 5 for
515 complete description of the data structures.
516 flags - No new flags are defined for SCTP at this level. See
517 Section 5 for SCTP-specific flags used in the msghdr structure.
519 As we will see in Section 5, along with the user data, the ancillary
520 data field is used to carry the sctp_sndrcvinfo and/or the
521 sctp_initmsg structures to perform various SCTP functions including
522 specifying options for sending each user message. Those options,
523 depending on whether sending or receiving, include stream number,
524 stream sequence number, various flags, context and payload protocol
527 When sending user data with sendmsg(), the msg_name field in msghdr
528 structure will be filled with one of the transport addresses of the
529 intended receiver. If there is no association existing between the
530 sender and the intended receiver, the sender's SCTP stack will set up
531 a new association and then send the user data (see Section 3.2 for
532 more on implicit association setup).
534 If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will
535 be delivered if that notification has been enabled, and no more data
536 can be sent to that association. Any attempt to send more data will
537 cause sendmsg() to return with an ESHUTDOWN error. Note that the
538 socket is still open for reading at this point so it is possible to
539 retrieve notifications.
541 When receiving a user message with recvmsg(), the msg_name field in
542 msghdr structure will be populated with the source transport address
543 of the user data. The caller of recvmsg() can use this address
544 information to determine to which association the received user
545 message belongs. Note that if SCTP_ASSOC_CHANGE events are disabled,
546 applications must use the peer transport address provided in the
547 msg_name field by recvmsg() to perform correlation to an association,
548 since they will not have the association ID.
550 If all data in a single message has been delivered, MSG_EOR will be
551 set in the msg_flags field of the msghdr structure (see section
554 If the application does not provide enough buffer space to completely
555 receive a data message, MSG_EOR will not be set in msg_flags.
559 Stewart, et al. Expires June 14, 2007 [Page 10]
561 Internet-Draft SCTP sockets API December 2006
564 Successive reads will consume more of the same message until the
565 entire message has been delivered, and MSG_EOR will be set.
567 If the SCTP stack is running low on buffers, it may partially deliver
568 a message. In this case, MSG_EOR will not be set, and more calls to
569 recvmsg() will be necessary to completely consume the message. Only
570 one message at a time per stream can be partially delivered.
572 Note, if the socket is a branched-off socket that only represents one
573 association (see Section 3.1), the msg_name field can be used to
574 override the primary address when sending data.
576 3.1.5. close() - one-to-many style socket
578 Applications use close() to perform graceful shutdown (as described
579 in Section 10.1 of RFC2960 [RFC2960]) on ALL the associations
580 currently represented by a one-to-many style socket.
588 sd - the socket descriptor of the associations to be closed.
590 To gracefully shutdown a specific association represented by the one-
591 to-many style socket, an application should use the sendmsg() call,
592 and including the SCTP_EOF flag. A user may optionally terminate an
593 association non-gracefully by sending with the SCTP_ABORT flag and
594 possibly passing a user specified abort code in the data field. Both
595 flags SCTP_EOF and SCTP_ABORT are passed with ancillary data (see
596 Section 5.2.2) in the sendmsg call.
598 If sd in the close() call is a branched-off socket representing only
599 one association, the shutdown is performed on that association only.
601 3.1.6. connect() - one-to-many style socket
603 An application may use the connect() call in the one-to-many style to
604 initiate an association without sending data.
608 ret = connect(int sd, const struct sockaddr *nam, socklen_t len);
615 Stewart, et al. Expires June 14, 2007 [Page 11]
617 Internet-Draft SCTP sockets API December 2006
620 sd - the socket descriptor to have a new association added to.
621 nam - the address structure (either struct sockaddr_in or struct
622 sockaddr_in6 defined in RFC2553 [RFC2553]).
623 len - the size of the address.
624 Multiple connect() calls can be made on the same socket to create
625 multiple associations. This is different from the semantics of
626 connect() on a UDP socket.
628 3.2. Implicit Association Setup
630 Once the bind() call is complete on a one-to-many style socket, the
631 application can begin sending and receiving data using the sendmsg()/
632 recvmsg() or sendto()/recvfrom() calls, without going through any
633 explicit association setup procedures (i.e., no connect() calls
636 Whenever sendmsg() or sendto() is called and the SCTP stack at the
637 sender finds that there is no association existing between the sender
638 and the intended receiver (identified by the address passed either in
639 the msg_name field of msghdr structure in the sendmsg() call or the
640 dest_addr field in the sendto() call), the SCTP stack will
641 automatically setup an association to the intended receiver.
643 Upon the successful association setup a SCTP_COMM_UP notification
644 will be dispatched to the socket at both the sender and receiver
645 side. This notification can be read by the recvmsg() system call
648 Note, if the SCTP stack at the sender side supports bundling, the
649 first user message may be bundled with the COOKIE ECHO message
652 When the SCTP stack sets up a new association implicitly, it first
653 consults the sctp_initmsg structure, which is passed along within the
654 ancillary data in the sendmsg() call (see Section 5.2.1 for details
655 of the data structures), for any special options to be used on the
658 If this information is not present in the sendmsg() call, or if the
659 implicit association setup is triggered by a sendto() call, the
660 default association initialization parameters will be used. These
661 default association parameters may be set with respective
662 setsockopt() calls or be left to the system defaults.
664 Implicit association setup cannot be initiated by send()/recv()
671 Stewart, et al. Expires June 14, 2007 [Page 12]
673 Internet-Draft SCTP sockets API December 2006
676 3.3. Non-blocking mode
678 Some SCTP users might want to avoid blocking when they call socket
681 Once all bind() calls are complete on a one-to-many style socket, the
682 application must set the non-blocking option by a fcntl() (such as
683 O_NONBLOCK). After which the sendmsg() function returns immediately,
684 and the success or failure of the data message (and possible
685 SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE
686 event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not
687 be sent (due to a CANT_START_ASSOC), the sender will also receive a
688 SCTP_SEND_FAILED event. Those event(s) can be received by the user
689 calling of recvmsg(). A server (having called listen()) is also
690 notified of an association up event by the reception of a
691 SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and
692 possibly the reception of the first data message.
694 In order to shutdown the association gracefully, the user must call
695 sendmsg() with no data and with the SCTP_EOF flag set. The function
696 returns immediately, and completion of the graceful shutdown is
697 indicated by an SCTP_ASSOC_CHANGE notification of type
698 SHUTDOWN_COMPLETE (see Section 5.3.1.1). Note that this can also be
699 done using the sctp_send() call described in Section 8.10.
701 An application is recommended to use caution when using select() (or
702 poll()) for writing on a one-to-many style socket. The reason being
703 that interpretation of select on write is implementation specific.
704 Generally a positive return on a select on write would only indicate
705 that one of the associations represented by the one-to-many socket is
706 writable. An application that writes after the select return may
707 still block since the association that was writeable is not the
708 destination association of the write call. Likewise select (or
709 poll()) for reading from a one-to-many socket will only return an
710 indication that one of the associations represented by the socket has
713 An application that wishes to know that a particular association is
714 ready for reading or writing should either use the one-to-one style
715 or use the sctp_peeloff() (see Section 8.2) function to separate the
716 association of interest from the one-to-many socket.
718 3.4. Special considerations
720 The fact that a one-to-many style socket can provide access to many
721 SCTP associations through a single socket descriptor has important
722 implications for both application programmers and system programmers
723 implementing this API. A key issue is how buffer space inside the
727 Stewart, et al. Expires June 14, 2007 [Page 13]
729 Internet-Draft SCTP sockets API December 2006
732 sockets layer is managed. Because this implementation detail
733 directly affects how application programmers must write their code to
734 ensure correct operation and portability, this section provides some
735 guidance to both implementors and application programmers.
737 An important feature that SCTP shares with TCP is flow control:
738 specifically, a sender may not send data faster than the receiver can
741 For TCP, flow control is typically provided for in the sockets API as
742 follows. If the reader stops reading, the sender queues messages in
743 the socket layer until it uses all of its socket buffer space
744 allocation creating a "stalled connection". Further attempts to
745 write to the socket will block or return the error EAGAIN or
746 EWOULDBLOCK for a non-blocking socket. At some point, either the
747 connection is closed, or the receiver begins to read again freeing
748 space in the output queue.
750 For one-to-one style SCTP sockets (this includes sockets descriptors
751 that were separated from a one-to-many style socket with
752 sctp_peeloff()) the behavior is identical. For one-to-many style
753 SCTP sockets, the fact that we have multiple associations on a single
754 socket makes the situation more complicated. If the implementation
755 uses a single buffer space allocation shared by all associations, a
756 single stalled association can prevent the further sending of data on
757 all associations active on a particular one-to-many style socket.
759 For a blocking socket, it should be clear that a single stalled
760 association can block the entire socket. For this reason,
761 application programmers may want to use non-blocking one-to-many
762 style sockets. The application should at least be able to send
763 messages to the non-stalled associations.
765 But a non-blocking socket is not sufficient if the API implementor
766 has chosen a single shared buffer allocation for the socket. A
767 single stalled association would eventually cause the shared
768 allocation to fill, and it would become impossible to send even to
769 non-stalled associations.
771 The API implementor can solve this problem by providing each
772 association with its own allocation of outbound buffer space. Each
773 association should conceptually have as much buffer space as it would
774 have if it had its own socket. As a bonus, this simplifies the
775 implementation of sctp_peeloff().
777 To ensure that a given stalled association will not prevent other
778 non-stalled associations from being writable, application programmers
783 Stewart, et al. Expires June 14, 2007 [Page 14]
785 Internet-Draft SCTP sockets API December 2006
788 (a) demand that the underlying implementation dedicates independent
789 buffer space allotments to each association (as suggested above),
791 (b) verify that their application layer protocol does not permit
792 large amounts of unread data at the receiver (this is true of some
793 request-response protocols, for example), or
794 (c) use one-to-one style sockets for association which may
795 potentially stall (either from the beginning, or by using
796 sctp_peeloff before sending large amounts of data that may cause a
798 An implementation which dedicates independent buffer space for
799 each association should define HAVE_SCTP_MULTIBUF to 1.
802 4. one-to-one style Interface
804 The goal of this style is to follow as closely as possible the
805 current practice of using the sockets interface for a connection
806 oriented protocol, such as TCP. This style enables existing
807 applications using connection oriented protocols to be ported to SCTP
808 with very little effort.
810 Note that some new SCTP features and some new SCTP socket options can
811 only be utilized through the use of sendmsg() and recvmsg() calls,
812 see Section 4.1.8. Also note that some socket interfaces may not be
813 able to provide data on the third leg of the association set up with
814 this interface style.
818 A typical server in one-to-one style uses the following system call
819 sequence to prepare an SCTP endpoint for servicing requests:
829 The accept() call blocks until a new association is set up. It
830 returns with a new socket descriptor. The server then uses the new
831 socket descriptor to communicate with the client, using recv() and
832 send() calls to get requests and send back responses.
839 Stewart, et al. Expires June 14, 2007 [Page 15]
841 Internet-Draft SCTP sockets API December 2006
846 to terminate the association.
848 A typical client uses the following system call sequence to setup an
849 association with a server to request services:
855 After returning from connect(), the client uses send() and recv()
856 calls to send out requests and receive responses from the server.
862 to terminate this association when done.
864 4.1.1. socket() - one-to-one style socket
866 Applications calls socket() to create a socket descriptor to
867 represent an SCTP endpoint.
871 int socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
875 int socket(PF_INET6, SOCK_STREAM, IPPROTO_SCTP);
877 Here, SOCK_STREAM indicates the creation of a one-to-one style
880 The first form creates an endpoint which can use only IPv4 addresses,
881 while the second form creates an endpoint which can use both IPv6 and
884 4.1.2. bind() - one-to-one style socket
886 Applications use bind() to pass an address to be associated with an
887 SCTP endpoint to the system. bind() allows only either a single
888 address or a IPv4 or IPv6 wildcard address to be bound. An SCTP
889 endpoint can be associated with multiple addresses. To do this,
890 sctp_bindx() is introduced in Section 8.1 to help applications do the
891 job of associating multiple addresses.
895 Stewart, et al. Expires June 14, 2007 [Page 16]
897 Internet-Draft SCTP sockets API December 2006
900 These addresses associated with a socket are the eligible transport
901 addresses for the endpoint to send and receive data. The endpoint
902 will also present these addresses to its peers during the association
903 initialization process, see RFC2960 [RFC2960].
907 int bind(int sd, struct sockaddr *addr, socklen_t addrlen);
909 sd: the socket descriptor returned by socket() call.
910 addr: the address structure (either struct sockaddr_in or struct
911 sockaddr_in6 defined in RFC2553 [RFC2553]).
912 addrlen: the size of the address structure.
914 If sd is an IPv4 socket, the address passed must be an IPv4 address.
915 Otherwise, i.e., the sd is an IPv6 socket, the address passed can
916 either be an IPv4 or an IPv6 address.
918 Applications cannot call bind() multiple times to associate multiple
919 addresses to the endpoint. After the first call to bind(), all
920 subsequent calls will return an error.
922 If addr is specified as a wildcard (INADDR_ANY for an IPv4 address,
923 or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the
924 operating system will associate the endpoint with an optimal address
925 set of the available interfaces.
927 If a bind() is not called prior to the connect() call, the system
928 picks an ephemeral port and will choose an address set equivalent to
929 binding with a wildcard address. One of those addresses will be the
930 primary address for the association. This automatically enables the
931 multi-homing capability of SCTP.
933 The completion of this bind() process does not ready the SCTP
934 endpoint to accept inbound SCTP association requests. Until a
935 listen() system call, described below, is performed on the socket,
936 the SCTP endpoint will promptly reject an inbound SCTP INIT request
939 4.1.3. listen() - one-to-one style socket
941 Applications use listen() to ready the SCTP endpoint for accepting
942 inbound associations.
946 int listen(int sd, int backlog);
951 Stewart, et al. Expires June 14, 2007 [Page 17]
953 Internet-Draft SCTP sockets API December 2006
956 sd: the socket descriptor of the SCTP endpoint.
957 backlog: this specifies the max number of outstanding associations
958 allowed in the socket's accept queue. These are the associations
959 that have finished the four-way initiation handshake (see Section
960 5 of RFC2960 [RFC2960]) and are in the ESTABLISHED state. Note, a
961 backlog of '0' indicates that the caller no longer wishes to
962 receive new associations.
964 4.1.4. accept() - one-to-one style socket
966 Applications use accept() call to remove an established SCTP
967 association from the accept queue of the endpoint. A new socket
968 descriptor will be returned from accept() to represent the newly
973 new_sd = accept(int sd, struct sockaddr *addr, socklen_t *addrlen);
975 new_sd - the socket descriptor for the newly formed association.
976 sd - the listening socket descriptor.
977 addr - on return, will contain the primary address of the peer
979 addrlen - on return, will contain the size of addr.
981 4.1.5. connect() - one-to-one style socket
983 Applications use connect() to initiate an association to a peer.
987 int connect(int sd, const struct sockaddr *addr, socklen_t addrlen);
989 sd - the socket descriptor of the endpoint.
990 addr - the peer's address.
991 addrlen - the size of the address.
993 This operation corresponds to the ASSOCIATE primitive described in
994 section 10.1 of RFC2960 [RFC2960].
996 By default, the new association created has only one outbound stream.
997 The SCTP_INITMSG option described in Section 7.1.3 should be used
998 before connecting to change the number of outbound streams.
1000 If a bind() is not called prior to the connect() call, the system
1001 picks an ephemeral port and will choose an address set equivalent to
1002 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket
1003 respectively. One of those addresses will be the primary address for
1007 Stewart, et al. Expires June 14, 2007 [Page 18]
1009 Internet-Draft SCTP sockets API December 2006
1012 the association. This automatically enables the multi-homing
1015 Note that SCTP allows data exchange, similar to T/TCP RFC1644
1016 [RFC1644], during the association set up phase. If an application
1017 wants to do this, it cannot use connect() call. Instead, it should
1018 use sendto() or sendmsg() to initiate an association. If it uses
1019 sendto() and it wants to change initialization behavior, it needs to
1020 use the SCTP_INITMSG socket option before calling sendto(). Or it
1021 can use SCTP_INIT type sendmsg() to initiate an association without
1022 doing the setsockopt(). Note that some sockets implementations may
1023 not support the sending of data to initiate an association with the
1024 one-to-one style (implementations that do not support T/TCP normally
1025 have this restriction). Implementations which allow sending of data
1026 to initiate an association without calling connect() define the
1027 preprocessor constant HAVE_SCTP_NOCONNECT to 1.
1029 SCTP does not support half close semantics. This means that unlike
1030 T/TCP, MSG_EOF should not be set in the flags parameter when calling
1031 sendto() or sendmsg() when the call is used to initiate a connection.
1032 MSG_EOF is not an acceptable flag with SCTP socket.
1034 4.1.6. close() - one-to-one style socket
1036 Applications use close() to gracefully close down an association.
1042 sd - the socket descriptor of the association to be closed.
1044 After an application calls close() on a socket descriptor, no further
1045 socket operations will succeed on that descriptor.
1047 4.1.7. shutdown() - one-to-one style socket
1049 SCTP differs from TCP in that it does not have half closed semantics.
1050 Hence the shutdown() call for SCTP is an approximation of the TCP
1051 shutdown() call, and solves some different problems. Full TCP-
1052 compatibility is not provided, so developers porting TCP applications
1053 to SCTP may need to recode sections that use shutdown(). (Note that
1054 it is possible to achieve the same results as half close in SCTP
1055 using SCTP streams.)
1059 int shutdown(int sd, int how);
1063 Stewart, et al. Expires June 14, 2007 [Page 19]
1065 Internet-Draft SCTP sockets API December 2006
1068 sd - the socket descriptor of the association to be closed.
1069 how - Specifies the type of shutdown. The values are as follows:
1070 SHUT_RD - Disables further receive operations. No SCTP protocol
1072 SHUT_WR - Disables further send operations, and initiates the
1073 SCTP shutdown sequence.
1074 SHUT_RDWR - Disables further send and receive operations and
1075 initiates the SCTP shutdown sequence.
1077 The major difference between SCTP and TCP shutdown() is that SCTP
1078 SHUT_WR initiates immediate and full protocol shutdown, whereas TCP
1079 SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves
1080 the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close
1081 the SCTP association while still leaving the socket descriptor open,
1082 so that the caller can receive back any data SCTP was unable to
1083 deliver (see Section 5.3.1.4 for more information).
1085 To perform the ABORT operation described in RFC2960 [RFC2960] section
1086 10.1, an application can use the socket option SO_LINGER. It is
1087 described in Section 7.1.4.
1089 4.1.8. sendmsg() and recvmsg() - one-to-one style socket
1091 With a one-to-one style socket, the application can also use
1092 sendmsg() and recvmsg() to transmit data to and receive data from its
1093 peer. The semantics is similar to those used in the one-to-many
1094 style (section Section 3.1.3), with the following differences:
1096 1) When sending, the msg_name field in the msghdr is not used to
1097 specify the intended receiver, rather it is used to indicate a
1098 preferred peer address if the sender wishes to discourage the stack
1099 from sending the message to the primary address of the receiver. If
1100 the transport address given is not part of the current association,
1101 the data will not be sent and a SCTP_SEND_FAILED event will be
1102 delivered to the application if send failure events are enabled.
1104 4.1.9. getpeername()
1106 Applications use getpeername() to retrieve the primary socket address
1107 of the peer. This call is for TCP compatibility, and is not multi-
1108 homed. It does not work with one-to-many style sockets. See
1109 Section 8.3 for a multi-homed/one-to-many style version of the call.
1113 int getpeername(int sd, struct sockaddr *address,
1119 Stewart, et al. Expires June 14, 2007 [Page 20]
1121 Internet-Draft SCTP sockets API December 2006
1124 sd - the socket descriptor to be queried.
1125 address - On return, the peer primary address is stored in this
1126 buffer. If the socket is an IPv4 socket, the address will be
1127 IPv4. If the socket is an IPv6 socket, the address will be either
1128 an IPv6 or IPv4 address.
1129 len - The caller should set the length of address here. On return,
1130 this is set to the length of the returned address.
1132 If the actual length of the address is greater than the length of the
1133 supplied sockaddr structure, the stored address will be truncated.
1138 We discuss in this section important data structures which are
1139 specific to SCTP and are used with sendmsg() and recvmsg() calls to
1140 control SCTP endpoint operations and to access ancillary information
1143 5.1. The msghdr and cmsghdr Structures
1145 The msghdr structure used in the sendmsg() and recvmsg() calls, as
1146 well as the ancillary data carried in the structure, is the key for
1147 the application to set and get various control information from the
1150 The msghdr and the related cmsghdr structures are defined and
1151 discussed in details in RFC2292 [RFC2292]. Here we will cite their
1152 definitions from RFC2292 [RFC2292].
1154 The msghdr structure:
1157 void *msg_name; /* ptr to socket address structure */
1158 socklen_t msg_namelen; /* size of socket address structure */
1159 struct iovec *msg_iov; /* scatter/gather array */
1160 size_t msg_iovlen; /* # elements in msg_iov */
1161 void *msg_control; /* ancillary data */
1162 socklen_t msg_controllen; /* ancillary data buffer length */
1163 int msg_flags; /* flags on received message */
1166 The cmsghdr structure:
1175 Stewart, et al. Expires June 14, 2007 [Page 21]
1177 Internet-Draft SCTP sockets API December 2006
1181 socklen_t cmsg_len; /* #bytes, including this header */
1182 int cmsg_level; /* originating protocol */
1183 int cmsg_type; /* protocol-specific type */
1184 /* followed by unsigned char cmsg_data[]; */
1187 In the msghdr structure, the usage of msg_name has been discussed in
1188 previous sections (see Section 3.1.3 and Section 4.1.8).
1190 The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov
1191 field) are treated as a single SCTP data chunk, rather than multiple
1192 chunks, for both sendmsg() and recvmsg().
1194 The msg_flags are not used when sending a message with sendmsg().
1196 If a notification has arrived, recvmsg() will return the notification
1197 with the MSG_NOTIFICATION flag set in msg_flags. If the
1198 MSG_NOTIFICATION flag is not set, recvmsg() will return data. See
1199 Section 5.3 for more information about notifications.
1201 If all portions of a data frame or notification have been read,
1202 recvmsg() will return with MSG_EOR set in msg_flags.
1204 5.2. SCTP msg_control Structures
1206 A key element of all SCTP-specific socket extensions is the use of
1207 ancillary data to specify and access SCTP-specific data via the
1208 struct msghdr's msg_control member used in sendmsg() and recvmsg().
1209 Fine-grained control over initialization and sending parameters are
1210 handled with ancillary data.
1212 Each ancillary data item is proceeded by a struct cmsghdr (see
1213 Section 5.1), which defines the function and purpose of the data
1214 contained in in the cmsg_data[] member.
1216 There are two kinds of ancillary data used by SCTP: initialization
1217 data, and, header information (SNDRCV). Initialization data (one-to-
1218 many style only) sets protocol parameters for new associations.
1219 Section 5.2.1 provides more details. Header information can set or
1220 report parameters on individual messages in a stream. See
1221 Section 5.2.2 for how to use SNDRCV ancillary data.
1223 By default on a one-to-one style socket, SCTP will pass no ancillary
1224 data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV
1225 and SCTP_ASSOC_CHANGE information. Specific ancillary data items can
1226 be enabled with socket options defined for SCTP; see Section 7.3.
1231 Stewart, et al. Expires June 14, 2007 [Page 22]
1233 Internet-Draft SCTP sockets API December 2006
1236 Note that all ancillary types are fixed length; see Section 5.4 for
1237 further discussion on this. These data structures use struct
1238 sockaddr_storage (defined in RFC2553 [RFC2553]) as a portable, fixed
1239 length address format.
1241 Other protocols may also provide ancillary data to the socket layer
1242 consumer. These ancillary data items from other protocols may
1243 intermingle with SCTP data. For example, the IPv6 socket API
1244 definitions (RFC2292 [RFC2292] and RFC2553 [RFC2553]) define a number
1245 of ancillary data items. If a socket API consumer enables delivery
1246 of both SCTP and IPv6 ancillary data, they both may appear in the
1247 same msg_control buffer in any order. An application may thus need
1248 to handle other types of ancillary data besides that passed by SCTP.
1250 The sockets application must provide a buffer large enough to
1251 accommodate all ancillary data provided via recvmsg(). If the buffer
1252 is not large enough, the ancillary data will be truncated and the
1253 msghdr's msg_flags will include MSG_CTRUNC.
1255 5.2.1. SCTP Initiation Structure (SCTP_INIT)
1257 This cmsghdr structure provides information for initializing new SCTP
1258 associations with sendmsg(). The SCTP_INITMSG socket option uses
1259 this same data structure. This structure is not used for recvmsg().
1261 cmsg_level cmsg_type cmsg_data[]
1262 ------------ ------------ ----------------------
1263 IPPROTO_SCTP SCTP_INIT struct sctp_initmsg
1265 Here is the definition of the sctp_initmsg structure:
1267 struct sctp_initmsg {
1268 uint16_t sinit_num_ostreams;
1269 uint16_t sinit_max_instreams;
1270 uint16_t sinit_max_attempts;
1271 uint16_t sinit_max_init_timeo;
1274 sinit_num_ostreams: 16 bits (unsigned integer)
1276 This is an integer number representing the number of streams that the
1277 application wishes to be able to send to. This number is confirmed
1278 in the SCTP_COMM_UP notification and must be verified since it is a
1279 negotiated number with the remote endpoint. The default value of 0
1280 indicates to use the endpoint default value.
1282 sinit_max_instreams: 16 bits (unsigned integer)
1287 Stewart, et al. Expires June 14, 2007 [Page 23]
1289 Internet-Draft SCTP sockets API December 2006
1292 This value represents the maximum number of inbound streams the
1293 application is prepared to support. This value is bounded by the
1294 actual implementation. In other words the user MAY be able to
1295 support more streams than the Operating System. In such a case, the
1296 Operating System limit overrides the value requested by the user.
1297 The default value of 0 indicates to use the endpoints default value.
1299 sinit_max_attempts: 16 bits (unsigned integer)
1301 This integer specifies how many attempts the SCTP endpoint should
1302 make at resending the INIT. This value overrides the system SCTP
1303 'Max.Init.Retransmits' value. The default value of 0 indicates to
1304 use the endpoints default value. This is normally set to the
1305 system's default 'Max.Init.Retransmit' value.
1307 sinit_max_init_timeo: 16 bits (unsigned integer)
1309 This value represents the largest Time-Out or RTO value (in
1310 milliseconds) to use in attempting an INIT. Normally the 'RTO.Max'
1311 is used to limit the doubling of the RTO upon timeout. For the INIT
1312 message this value MAY override 'RTO.Max'. This value MUST NOT
1313 influence 'RTO.Max' during data transmission and is only used to
1314 bound the initial setup time. A default value of 0 indicates to use
1315 the endpoints default value. This is normally set to the system's
1316 'RTO.Max' value (60 seconds).
1318 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV)
1320 This cmsghdr structure specifies SCTP options for sendmsg() and
1321 describes SCTP header information about a received message through
1324 cmsg_level cmsg_type cmsg_data[]
1325 ------------ ------------ ----------------------
1326 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo
1328 Here is the definition of sctp_sndrcvinfo:
1330 struct sctp_sndrcvinfo {
1331 uint16_t sinfo_stream;
1333 uint16_t sinfo_flags;
1334 uint32_t sinfo_ppid;
1335 uint32_t sinfo_context;
1336 uint32_t sinfo_timetolive;
1338 uint32_t sinfo_cumtsn;
1339 sctp_assoc_t sinfo_assoc_id;
1343 Stewart, et al. Expires June 14, 2007 [Page 24]
1345 Internet-Draft SCTP sockets API December 2006
1351 sinfo_stream: 16 bits (unsigned integer)
1353 For recvmsg() the SCTP stack places the message's stream number in
1354 this value. For sendmsg() this value holds the stream number that
1355 the application wishes to send this message to. If a sender
1356 specifies an invalid stream number an error indication is returned
1359 sinfo_ssn: 16 bits (unsigned integer)
1361 For recvmsg() this value contains the stream sequence number that the
1362 remote endpoint placed in the DATA chunk. For fragmented messages
1363 this is the same number for all deliveries of the message (if more
1364 than one recvmsg() is needed to read the message). The sendmsg()
1365 call will ignore this parameter.
1367 sinfo_ppid: 32 bits (unsigned integer)
1369 This value in sendmsg() is an unsigned integer that is passed to the
1370 remote end in each user message. In recvmsg() this value is the same
1371 information that was passed by the upper layer in the peer
1372 application. Please note that the SCTP stack performs no byte order
1373 modification of this field. For example, if the DATA chunk has to
1374 contain a given value in network byte order, the SCTP user has to
1375 perform the htonl() computation.
1377 sinfo_context: 32 bits (unsigned integer)
1379 This value is an opaque 32 bit context datum that is used in the
1380 sendmsg() function. This value is passed back to the upper layer if
1381 a error occurs on the send of a message and is retrieved with each
1382 undelivered message (Note: if a endpoint has done multiple sends, all
1383 of which fail, multiple different sinfo_context values will be
1384 returned. One with each user data message).
1386 sinfo_flags: 16 bits (unsigned integer)
1388 This field may contain any of the following flags and is composed of
1389 a bitwise OR of these values.
1399 Stewart, et al. Expires June 14, 2007 [Page 25]
1401 Internet-Draft SCTP sockets API December 2006
1404 SCTP_UNORDERED - This flag is present when the message was sent non-
1409 SCTP_UNORDERED - This flag requests the un-ordered delivery of the
1410 message. If this flag is clear the datagram is considered an
1413 SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the
1414 SCTP stack to override the primary destination address with the
1415 address found with the sendto/sendmsg call.
1417 SCTP_ABORT - Setting this flag causes the specified association to
1418 abort by sending an ABORT message to the peer (one-to-many style
1419 only). The ABORT chunk will contain an error cause 'User
1420 Initiated Abort' with cause code 12. The cause specific
1421 information of this error cause is provided in msg_iov.
1423 SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown
1424 procedures on the specified association. Graceful shutdown
1425 assures that all data enqueued by both endpoints is successfully
1426 transmitted before closing the association (one-to-many style
1429 SCTP_SENDALL - This flag, if set, will cause a one-to-many model
1430 socket to send the message to all associations that are currently
1431 established on this socket. For the one-to-one socket, this flag
1435 sinfo_timetolive: 32 bit (unsigned integer)
1437 For the sending side, this field contains the message time to live in
1438 milliseconds. The sending side will expire the message within the
1439 specified time period if the message as not been sent to the peer
1440 within this time period. This value will override any default value
1441 set using any socket option. Also note that the value of 0 is
1442 special in that it indicates no timeout should occur on this message.
1444 sinfo_tsn: 32 bit (unsigned integer)
1446 For the receiving side, this field holds a TSN that was assigned to
1447 one of the SCTP Data Chunks.
1449 sinfo_cumtsn: 32 bit (unsigned integer)
1451 This field will hold the current cumulative TSN as known by the
1455 Stewart, et al. Expires June 14, 2007 [Page 26]
1457 Internet-Draft SCTP sockets API December 2006
1460 underlying SCTP layer. Note this field is ignored when sending and
1461 only valid for a receive operation when sinfo_flags are set to
1464 sinfo_assoc_id: sizeof (sctp_assoc_t)
1466 The association handle field, sinfo_assoc_id, holds the identifier
1467 for the association announced in the SCTP_COMM_UP notification. All
1468 notifications for a given association have the same identifier.
1469 Ignored for one-to-one style sockets.
1471 A sctp_sndrcvinfo item always corresponds to the data in msg_iov.
1473 5.2.3. Extended SCTP Header Information Structure (SCTP_EXTRCV)
1475 This cmsghdr structure specifies SCTP options for SCTP header
1476 information about a received message via recvmsg(). Note that this
1477 structure is an extended version of SCTP_SNDRCV and will only be
1478 received if the user has set the socket option SCTP_USE_EXT_RCVINFO
1479 to true in addition to any event subscription needed to receive
1482 cmsg_level cmsg_type cmsg_data[]
1483 ------------ ------------ ----------------------
1484 IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo
1486 Here is the definition of sctp_sndrcvinfo:
1488 struct sctp_extrcvinfo {
1489 uint16_t sinfo_stream;
1491 uint16_t sinfo_flags;
1492 uint32_t sinfo_ppid;
1493 uint32_t sinfo_context;
1494 uint32_t sinfo_timetolive;
1496 uint32_t sinfo_cumtsn;
1497 sctp_assoc_t sinfo_assoc_id;
1498 uint16_t next_flags;
1499 uint16_t next_stream;
1500 uint32_t next_asocid;
1501 uint32_t next_length;
1506 sinfo_stream: 16 bits (unsigned integer)
1511 Stewart, et al. Expires June 14, 2007 [Page 27]
1513 Internet-Draft SCTP sockets API December 2006
1516 For recvmsg() the SCTP stack places the message's stream number in
1517 this value. For sendmsg() this value holds the stream number that
1518 the application wishes to send this message to. If a sender
1519 specifies an invalid stream number an error indication is returned
1522 sinfo_ssn: 16 bits (unsigned integer)
1524 For recvmsg() this value contains the stream sequence number that the
1525 remote endpoint placed in the DATA chunk. For fragmented messages
1526 this is the same number for all deliveries of the message (if more
1527 than one recvmsg() is needed to read the message). The sendmsg()
1528 call will ignore this parameter.
1530 sinfo_ppid: 32 bits (unsigned integer)
1532 This value in sendmsg() is an unsigned integer that is passed to the
1533 remote end in each user message. In recvmsg() this value is the same
1534 information that was passed by the upper layer in the peer
1535 application. Please note that the SCTP stack performs no byte order
1536 modification of this field. For example, if the DATA chunk has to
1537 contain a given value in network byte order, the SCTP user has to
1538 perform the htonl() computation.
1540 sinfo_context: 32 bits (unsigned integer)
1542 This value is an opaque 32 bit context datum that is used in the
1543 sendmsg() function. This value is passed back to the upper layer if
1544 a error occurs on the send of a message and is retrieved with each
1545 undelivered message (Note: if a endpoint has done multiple sends, all
1546 of which fail, multiple different sinfo_context values will be
1547 returned. One with each user data message).
1549 sinfo_flags: 16 bits (unsigned integer)
1551 This field may contain any of the following flags and is composed of
1552 a bitwise OR of these values.
1555 SCTP_UNORDERED - This flag is present when the message was sent non-
1559 SCTP_UNORDERED - This flag requests the un-ordered delivery of the
1560 message. If this flag is clear the datagram is considered an
1567 Stewart, et al. Expires June 14, 2007 [Page 28]
1569 Internet-Draft SCTP sockets API December 2006
1572 SCTP_ADDR_OVER - This flag, in the one-to-many style, requests the
1573 SCTP stack to override the primary destination address with the
1574 address found with the sendto/sendmsg call.
1576 SCTP_ABORT - Setting this flag causes the specified association to
1577 abort by sending an ABORT message to the peer (one-to-many style
1578 only). The ABORT chunk will contain an error cause 'User
1579 Initiated Abort' with cause code 12. The cause specific
1580 information of this error cause is provided in msg_iov.
1582 SCTP_EOF - Setting this flag invokes the SCTP graceful shutdown
1583 procedures on the specified association. Graceful shutdown
1584 assures that all data enqueued by both endpoints is successfully
1585 transmitted before closing the association (one-to-many style
1588 SCTP_SENDALL - This flag, if set, will cause a one-to-many model
1589 socket to send the message to all associations that are currently
1590 established on this socket. For the one-to-one socket, this flag
1592 SCTP_EOR - This flag, if set, will indicate that this send
1593 terminates the record.
1595 sinfo_timetolive: 32 bit (unsigned integer)
1597 For the sending side, this field contains the message time to live in
1598 milliseconds. The sending side will expire the message within the
1599 specified time period if the message as not been sent to the peer
1600 within this time period. This value will override any default value
1601 set using any socket option. Also note that the value of 0 is
1602 special in that it indicates no timeout should occur on this message.
1604 sinfo_tsn: 32 bit (unsigned integer)
1606 For the receiving side, this field holds a TSN that was assigned to
1607 one of the SCTP Data Chunks.
1609 sinfo_cumtsn: 32 bit (unsigned integer)
1611 This field will hold the current cumulative TSN as known by the
1612 underlying SCTP layer. Note this field is ignored when sending and
1613 only valid for a receive operation when sinfo_flags are set to
1616 sinfo_assoc_id: sizeof (sctp_assoc_t)
1618 The association handle field, sinfo_assoc_id, holds the identifier
1619 for the association announced in the SCTP_COMM_UP notification. All
1623 Stewart, et al. Expires June 14, 2007 [Page 29]
1625 Internet-Draft SCTP sockets API December 2006
1628 notifications for a given association have the same identifier.
1629 Ignored for one-to-one style sockets.
1631 A sctp_sndrcvinfo item always corresponds to the data in msg_iov.
1633 next_flags: 16 bit (unsigned integer)
1635 This bitmask will hold one or more of the following values:
1636 SCTP_NEXT_MSG_AVAIL - This bit, when set to 1, indicates that next
1637 message information is available i.e.: next_stream, next_asocid,
1638 next_length and next_ppid fields all have valid values. If this
1639 bit is set to 0, then these fields are not valid and should be
1642 SCTP_NEXT_MSG_ISCOMPLETE - This bit, when set, indicates that the
1643 next message is completely in the receive buffer. The next_length
1644 field thus contains the entire message size. If this flag is set
1645 to 0, then the next_length field only contains part of the message
1646 size since the message is still being received (it is being
1647 partially delivered).
1649 SCTP_NEXT_MSG_IS_UNORDERED - This bit, when set, indicates that the
1650 next message to be received was sent by the peer as unordered. If
1651 this bit is not set (i.e the bit is 0) the next message to be read
1652 is an ordered message in the stream specified.
1654 next_stream: 16 bit (unsigned integer)
1656 This value, when valid (see next_flags), contains the next stream
1657 number that will be received on a subsequent call to one of the
1658 receive message functions.
1660 next_asocid: 32 bit (unsigned integer)
1662 This value, when valid (see next_flags), contains the next
1663 association identification that will be received on a subsequent call
1664 to one of the receive message functions.
1666 next_length: 32 bit (unsigned integer)
1668 This value, when valid (see next_flags), contains the length of the
1669 next message that will be received on a subsequent call to one of the
1670 receive message functions. Note that this length may be a partial
1671 length depending on the settings of next_flags.
1673 next_ppid: 32 bit (unsigned integer)
1675 This value, when valid (see next_flags), contains the ppid of the
1679 Stewart, et al. Expires June 14, 2007 [Page 30]
1681 Internet-Draft SCTP sockets API December 2006
1684 next message that will be received on a subsequent call to one of the
1685 receive message functions.
1687 5.3. SCTP Events and Notifications
1689 An SCTP application may need to understand and process events and
1690 errors that happen on the SCTP stack. These events include network
1691 status changes, association startups, remote operational errors and
1692 undeliverable messages. All of these can be essential for the
1695 When an SCTP application layer does a recvmsg() the message read is
1696 normally a data message from a peer endpoint. If the application
1697 wishes to have the SCTP stack deliver notifications of non-data
1698 events, it sets the appropriate socket option for the notifications
1699 it wants. See Section 7.3 for these socket options. When a
1700 notification arrives, recvmsg() returns the notification in the
1701 application-supplied data buffer via msg_iov, and sets
1702 MSG_NOTIFICATION in msg_flags.
1704 This section details the notification structures. Every notification
1705 structure carries some common fields which provides general
1708 A recvmsg() call will return only one notification at a time. Just
1709 as when reading normal data, it may return part of a notification if
1710 the msg_iov buffer is not large enough. If a single read is not
1711 sufficient, msg_flags will have MSG_EOR clear. The user MUST finish
1712 reading the notification before subsequent data can arrive.
1714 5.3.1. SCTP Notification Structure
1716 The notification structure is defined as the union of all
1735 Stewart, et al. Expires June 14, 2007 [Page 31]
1737 Internet-Draft SCTP sockets API December 2006
1740 union sctp_notification {
1742 uint16_t sn_type; /* Notification type. */
1746 struct sctp_assoc_change sn_assoc_change;
1747 struct sctp_paddr_change sn_paddr_change;
1748 struct sctp_remote_error sn_remote_error;
1749 struct sctp_send_failed sn_send_failed;
1750 struct sctp_shutdown_event sn_shutdown_event;
1751 struct sctp_adaptation_event sn_adaptation_event;
1752 struct sctp_pdapi_event sn_pdapi_event;
1753 struct sctp_authkey_event sn_auth_event;
1757 sn_type: 16 bits (unsigned integer)
1759 The following list describes the SCTP notification and event types
1760 for the field sn_type.
1762 SCTP_ASSOC_CHANGE: This tag indicates that an association has either
1763 been opened or closed. Refer to Section 5.3.1.1 for details.
1764 SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is
1765 part of an existing association has experienced a change of state
1766 (e.g. a failure or return to service of the reachability of a
1767 endpoint via a specific transport address). Please see
1768 Section 5.3.1.2 for data structure details.
1769 SCTP_REMOTE_ERROR: The attached error message is an Operational
1770 Error received from the remote peer. It includes the complete TLV
1771 sent by the remote endpoint. See Section 5.3.1.3 for the detailed
1773 SCTP_SEND_FAILED: The attached datagram could not be sent to the
1774 remote endpoint. This structure includes the original
1775 SCTP_SNDRCVINFO that was used in sending this message i.e. this
1776 structure uses the sctp_sndrecvinfo per Section 5.3.1.4.
1777 SCTP_SHUTDOWN_EVENT: The peer has sent a SHUTDOWN. No further data
1778 should be sent on this socket.
1779 SCTP_ADAPTATION_INDICATION: This notification holds the peers
1780 indicated adaptation layer. Please see Section 5.3.1.6.
1781 SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a
1782 receiver that the partial delivery has been aborted. This may
1783 indicate the association is about to be aborted. Please see
1791 Stewart, et al. Expires June 14, 2007 [Page 32]
1793 Internet-Draft SCTP sockets API December 2006
1796 SCTP_AUTHENTICATION_EVENT: This notification is used to tell a
1797 receiver that either an error occurred on authentication, or a new
1798 key was made active. Section 5.3.1.8
1800 All standard values for sn_type are greater than 2^15. Values from
1801 2^15 and down are reserved.
1803 sn_flags: 16 bits (unsigned integer)
1805 These are notification-specific flags.
1807 sn_length: 32 bits (unsigned integer)
1809 This is the length of the whole sctp_notification structure including
1810 the sn_type, sn_flags, and sn_length fields.
1812 5.3.1.1. SCTP_ASSOC_CHANGE
1814 Communication notifications inform the ULP that an SCTP association
1815 has either begun or ended. The identifier for a new association is
1816 provided by this notification. The notification information has the
1819 struct sctp_assoc_change {
1822 uint32_t sac_length;
1825 uint16_t sac_outbound_streams;
1826 uint16_t sac_inbound_streams;
1827 sctp_assoc_t sac_assoc_id;
1828 uint8_t sac_info[0];
1833 It should be SCTP_ASSOC_CHANGE.
1835 sac_flags: 16 bits (unsigned integer)
1839 sac_length: 32 bits (unsigned integer)
1841 This field is the total length of the notification data, including
1842 the notification header.
1847 Stewart, et al. Expires June 14, 2007 [Page 33]
1849 Internet-Draft SCTP sockets API December 2006
1852 sac_state: 16 bits (signed integer)
1854 This field holds one of a number of values that communicate the event
1855 that happened to the association. They include:
1857 Event Name Description
1859 ---------------- ---------------
1861 SCTP_COMM_UP - A new association is now ready and data may be
1862 exchanged with this peer.
1863 SCTP_COMM_LOST - The association has failed. The association is now
1864 in the closed state. If SEND FAILED notifications are turned on,
1865 a SCTP_COMM_LOST is followed by a series of SCTP_SEND_FAILED
1866 events, one for each outstanding message.
1867 SCTP_RESTART - SCTP has detected that the peer has restarted.
1868 SCTP_SHUTDOWN_COMP - The association has gracefully closed.
1869 SCTP_CANT_STR_ASSOC - The association failed to setup. If non
1870 blocking mode is set and data was sent (in the udp mode), a
1871 SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED
1872 events, one for each outstanding message.
1874 sac_error: 16 bits (signed integer)
1876 If the state was reached due to a error condition (e.g.
1877 SCTP_COMM_LOST) any relevant error information is available in this
1878 field. This corresponds to the protocol error codes defined in
1881 sac_outbound_streams: 16 bits (unsigned integer)
1883 sac_inbound_streams: 16 bits (unsigned integer)
1885 The maximum number of streams allowed in each direction are available
1886 in sac_outbound_streams and sac_inbound streams.
1888 sac_assoc_id: sizeof (sctp_assoc_t)
1890 The association id field, holds the identifier for the association.
1891 All notifications for a given association have the same association
1892 identifier. For one-to-one style socket, this field is ignored.
1896 If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received
1897 for this association, sac_info[] contains the complete ABORT chunk as
1898 defined in the SCTP specification RFC2960 [RFC2960] section 3.3.7.
1903 Stewart, et al. Expires June 14, 2007 [Page 34]
1905 Internet-Draft SCTP sockets API December 2006
1908 5.3.1.2. SCTP_PEER_ADDR_CHANGE
1910 When a destination address on a multi-homed peer encounters a change
1911 an interface details event is sent. The information has the
1912 following structure:
1915 struct sctp_paddr_change {
1918 uint32_t spc_length;
1919 struct sockaddr_storage spc_aaddr;
1922 sctp_assoc_t spc_assoc_id;
1927 It should be SCTP_PEER_ADDR_CHANGE.
1929 spc_flags: 16 bits (unsigned integer)
1933 spc_length: 32 bits (unsigned integer)
1935 This field is the total length of the notification data, including
1936 the notification header.
1938 spc_aaddr: sizeof (struct sockaddr_storage)
1940 The affected address field, holds the remote peer's address that is
1941 encountering the change of state.
1943 spc_state: 32 bits (signed integer)
1945 This field holds one of a number of values that communicate the event
1946 that happened to the address. They include:
1948 Event Name Description
1950 ---------------- ---------------
1959 Stewart, et al. Expires June 14, 2007 [Page 35]
1961 Internet-Draft SCTP sockets API December 2006
1964 SCTP_ADDR_AVAILABLE - This address is now reachable.
1965 SCTP_ADDR_UNREACHABLE - The address specified can no longer be
1966 reached. Any data sent to this address is rerouted to an
1967 alternate until this address becomes reachable.
1968 SCTP_ADDR_REMOVED - The address is no longer part of the
1970 SCTP_ADDR_ADDED - The address is now part of the association.
1971 SCTP_ADDR_MADE_PRIM - This address has now been made to be the
1972 primary destination address.
1973 SCTP_ADDR_CONFIRMED - This address has now been confirmed as a valid
1976 spc_error: 32 bits (signed integer)
1978 If the state was reached due to any error condition (e.g.
1979 SCTP_ADDR_UNREACHABLE) any relevant error information is available in
1982 spc_assoc_id: sizeof (sctp_assoc_t)
1984 The association id field, holds the identifier for the association.
1985 All notifications for a given association have the same association
1986 identifier. For one-to-one style socket, this field is ignored.
1988 5.3.1.3. SCTP_REMOTE_ERROR
1990 A remote peer may send an Operational Error message to its peer.
1991 This message indicates a variety of error conditions on an
1992 association. The entire ERROR chunk as it appears on the wire is
1993 included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP
1994 specification RFC2960 [RFC2960] and any extensions for a list of
1995 possible error formats. SCTP error notifications have the format:
1998 struct sctp_remote_error {
2001 uint32_t sre_length;
2003 sctp_assoc_t sre_assoc_id;
2004 uint8_t sre_data[0];
2010 It should be SCTP_REMOTE_ERROR.
2015 Stewart, et al. Expires June 14, 2007 [Page 36]
2017 Internet-Draft SCTP sockets API December 2006
2020 sre_flags: 16 bits (unsigned integer)
2024 sre_length: 32 bits (unsigned integer)
2026 This field is the total length of the notification data, including
2027 the notification header and the contents of sre_data.
2029 sre_error: 16 bits (unsigned integer)
2031 This value represents one of the Operational Error causes defined in
2032 the SCTP specification, in network byte order.
2034 sre_assoc_id: sizeof (sctp_assoc_t)
2036 The association id field, holds the identifier for the association.
2037 All notifications for a given association have the same association
2038 identifier. For one-to-one style socket, this field is ignored.
2042 This contains the ERROR chunk as defined in the SCTP specification
2043 RFC2960 [RFC2960] section 3.3.10.
2045 5.3.1.4. SCTP_SEND_FAILED
2047 If SCTP cannot deliver a message it may return the message as a
2051 struct sctp_send_failed {
2054 uint32_t ssf_length;
2056 struct sctp_sndrcvinfo ssf_info;
2057 sctp_assoc_t ssf_assoc_id;
2058 uint8_t ssf_data[0];
2064 It should be SCTP_SEND_FAILED.
2066 ssf_flags: 16 bits (unsigned integer)
2071 Stewart, et al. Expires June 14, 2007 [Page 37]
2073 Internet-Draft SCTP sockets API December 2006
2076 The flag value will take one of the following values:
2078 SCTP_DATA_UNSENT - Indicates that the data was never put on the
2080 SCTP_DATA_SENT - Indicates that the data was put on the wire. Note
2081 that this does not necessarily mean that the data was (or was not)
2082 successfully delivered.
2084 ssf_length: 32 bits (unsigned integer)
2086 This field is the total length of the notification data, including
2087 the notification header and the payload in ssf_data.
2089 ssf_error: 16 bits (unsigned integer)
2091 This value represents the reason why the send failed, and if set,
2092 will be a SCTP protocol error code as defined in RFC2960 [RFC2960]
2095 ssf_info: sizeof (struct sctp_sndrcvinfo)
2097 The original send information associated with the undelivered
2100 ssf_assoc_id: sizeof (sctp_assoc_t)
2102 The association id field, sf_assoc_id, holds the identifier for the
2103 association. All notifications for a given association have the same
2104 association identifier. For one-to-one style socket, this field is
2107 ssf_data: variable length
2109 The undelivered message, exactly as delivered by the caller to the
2110 original send*() call.
2112 5.3.1.5. SCTP_SHUTDOWN_EVENT
2114 When a peer sends a SHUTDOWN, SCTP delivers this notification to
2115 inform the application that it should cease sending data.
2117 struct sctp_shutdown_event {
2120 uint32_t sse_length;
2121 sctp_assoc_t sse_assoc_id;
2127 Stewart, et al. Expires June 14, 2007 [Page 38]
2129 Internet-Draft SCTP sockets API December 2006
2134 It should be SCTP_SHUTDOWN_EVENT
2136 sse_flags: 16 bits (unsigned integer)
2140 sse_length: 32 bits (unsigned integer)
2142 This field is the total length of the notification data, including
2143 the notification header. It will generally be sizeof (struct
2144 sctp_shutdown_event).
2146 sse_flags: 16 bits (unsigned integer)
2150 sse_assoc_id: sizeof (sctp_assoc_t)
2152 The association id field, holds the identifier for the association.
2153 All notifications for a given association have the same association
2154 identifier. For one-to-one style socket, this field is ignored.
2156 5.3.1.6. SCTP_ADAPTATION_INDICATION
2158 When a peer sends a Adaptation Layer Indication parameter , SCTP
2159 delivers this notification to inform the application that of the
2160 peers requested adaptation layer.
2162 struct sctp_adaptation_event {
2165 uint32_t sai_length;
2166 uint32_t sai_adaptation_ind;
2167 sctp_assoc_t sai_assoc_id;
2172 It should be SCTP_ADAPTATION_INDICATION
2174 sai_flags: 16 bits (unsigned integer)
2178 sai_length: 32 bits (unsigned integer)
2183 Stewart, et al. Expires June 14, 2007 [Page 39]
2185 Internet-Draft SCTP sockets API December 2006
2188 This field is the total length of the notification data, including
2189 the notification header. It will generally be sizeof (struct
2190 sctp_adaptation_event).
2192 sai_adaptation_ind: 32 bits (unsigned integer)
2194 This field holds the bit array sent by the peer in the adaptation
2195 layer indication parameter. The bits are in network byte order.
2197 sai_assoc_id: sizeof (sctp_assoc_t)
2199 The association id field, holds the identifier for the association.
2200 All notifications for a given association have the same association
2201 identifier. For one-to-one style socket, this field is ignored.
2203 5.3.1.7. SCTP_PARTIAL_DELIVERY_EVENT
2205 When a receiver is engaged in a partial delivery of a message this
2206 notification will be used to indicate various events.
2208 struct sctp_pdapi_event {
2209 uint16_t pdapi_type;
2210 uint16_t pdapi_flags;
2211 uint32_t pdapi_length;
2212 uint32_t pdapi_indication;
2213 sctp_assoc_t pdapi_assoc_id;
2218 It should be SCTP_PARTIAL_DELIVERY_EVENT
2220 pdapi_flags: 16 bits (unsigned integer)
2224 pdapi_length: 32 bits (unsigned integer)
2226 This field is the total length of the notification data, including
2227 the notification header. It will generally be sizeof (struct
2230 pdapi_indication: 32 bits (unsigned integer)
2232 This field holds the indication being sent to the application
2233 possible values include:
2235 SCTP_PARTIAL_DELIVERY_ABORTED
2239 Stewart, et al. Expires June 14, 2007 [Page 40]
2241 Internet-Draft SCTP sockets API December 2006
2244 pdapi_assoc_id: sizeof (sctp_assoc_t)
2246 The association id field, holds the identifier for the association.
2247 All notifications for a given association have the same association
2248 identifier. For one-to-one style socket, this field is ignored.
2250 5.3.1.8. SCTP_AUTHENTICATION_EVENT
2252 When a receiver is using authentication this message will provide
2253 notifications regarding new keys being made active as well as errors.
2255 struct sctp_authkey_event {
2257 uint16_t auth_flags;
2258 uint32_t auth_length;
2259 uint16_t auth_keynumber;
2260 uint16_t auth_altkeynumber;
2261 uint32_t auth_indication;
2262 sctp_assoc_t auth_assoc_id;
2267 It should be SCTP_AUTHENTICATION_EVENT
2269 auth_flags: 16 bits (unsigned integer)
2273 auth_length: 32 bits (unsigned integer)
2275 This field is the total length of the notification data, including
2276 the notification header. It will generally be sizeof (struct
2277 sctp_authkey_event).
2279 auth_keynumber: 32 bits (unsigned integer)
2281 This field holds the keynumber set by the user for the effected key.
2282 If more than one key is involved, this will contain one of the keys
2283 involved in the notification.
2285 auth_altkeynumber: 32 bits (unsigned integer)
2287 This field holds an alternate keynumber which is used by some
2290 auth_indication: 32 bits (unsigned integer)
2295 Stewart, et al. Expires June 14, 2007 [Page 41]
2297 Internet-Draft SCTP sockets API December 2006
2300 This field hold the error or indication being reported. The
2301 following values are currently defined:
2302 SCTP_AUTH_NEWKEY - this report indicates that a new key has been
2303 made active (used for the first time by the peer) and is now the
2304 active key. The auth_keynumber field holds the user specified key
2307 auth_assoc_id: sizeof (sctp_assoc_t)
2309 The association id field, holds the identifier for the association.
2310 All notifications for a given association have the same association
2313 5.4. Ancillary Data Considerations and Semantics
2315 Programming with ancillary socket data contains some subtleties and
2316 pitfalls, which are discussed below.
2318 5.4.1. Multiple Items and Ordering
2320 Multiple ancillary data items may be included in any call to
2321 sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP
2324 The ordering of ancillary data items (either by SCTP or another
2325 protocol) is not significant and is implementation-dependent, so
2326 applications must not depend on any ordering.
2328 SCTP_SNDRCV items must always correspond to the data in the msghdr's
2329 msg_iov member. There can be only a single SCTP_SNDRCV info for each
2330 sendmsg() or recvmsg() call.
2332 5.4.2. Accessing and Manipulating Ancillary Data
2334 Applications can infer the presence of data or ancillary data by
2335 examining the msg_iovlen and msg_controllen msghdr members,
2338 Implementations may have different padding requirements for ancillary
2339 data, so portable applications should make use of the macros
2340 CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See
2341 RFC2292 [RFC2292] and your SCTP implementation's documentation for
2342 more information. Following is an example, from RFC2292 [RFC2292],
2343 demonstrating the use of these macros to access ancillary data:
2351 Stewart, et al. Expires June 14, 2007 [Page 42]
2353 Internet-Draft SCTP sockets API December 2006
2357 struct cmsghdr *cmsgptr;
2361 /* call recvmsg() */
2363 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL;
2364 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) {
2365 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) {
2368 ptr = CMSG_DATA(cmsgptr);
2369 /* process data pointed to by ptr */
2373 5.4.3. Control Message Buffer Sizing
2375 The information conveyed via SCTP_SNDRCV events will often be
2376 fundamental to the correct and sane operation of the sockets
2377 application. This is particularly true of the one-to-many semantics,
2378 but also of the one-ton-one semantics. For example, if an
2379 application needs to send and receive data on different SCTP streams,
2380 SCTP_SNDRCV events are indispensable.
2382 Given that some ancillary data is critical, and that multiple
2383 ancillary data items may appear in any order, applications should be
2384 carefully written to always provide a large enough buffer to contain
2385 all possible ancillary data that can be presented by recvmsg(). If
2386 the buffer is too small, and crucial data is truncated, it may pose a
2387 fatal error condition.
2389 Thus it is essential that applications be able to deterministically
2390 calculate the maximum required buffer size to pass to recvmsg(). One
2391 constraint imposed on this specification that makes this possible is
2392 that all ancillary data definitions are of a fixed length. One way
2393 to calculate the maximum required buffer size might be to take the
2394 sum the sizes of all enabled ancillary data item structures, as
2395 calculated by CMSG_SPACE. For example, if we enabled
2396 SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [RFC2292], we would
2397 calculate and allocate the buffer size as follows:
2407 Stewart, et al. Expires June 14, 2007 [Page 43]
2409 Internet-Draft SCTP sockets API December 2006
2415 total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) +
2416 CMSG_SPACE(sizeof (struct in6_pktinfo));
2418 buf = malloc(total);
2420 We could then use this buffer for msg_control on each call to
2421 recvmsg() and be assured that we would not lose any ancillary data to
2425 6. Common Operations for Both Styles
2427 6.1. send(), recv(), sendto(), recvfrom()
2429 Applications can use send() and sendto() to transmit data to the peer
2430 of an SCTP endpoint. recv() and recvfrom() can be used to receive
2435 ssize_t send(int sd, const void *msg, size_t len, int flags);
2436 ssize_t sendto(int sd, const void *msg, size_t len, int flags,
2437 const struct sockaddr *to, socklen_t tolen);
2438 ssize_t recv(int sd, void *buf, size_t len, int flags);
2439 ssize_t recvfrom(int sd, void *buf, size_t len, int flags,
2440 struct sockaddr *from, socklen_t *fromlen);
2442 sd - the socket descriptor of an SCTP endpoint.
2443 msg - the message to be sent.
2444 len - the size of the message or the size of buffer.
2445 to - one of the peer addresses of the association to be used to send
2447 tolen - the size of the address.
2448 buf - the buffer to store a received message.
2449 from - the buffer to store the peer address used to send the
2451 fromlen - the size of the from address
2452 flags - (described below).
2454 These calls give access to only basic SCTP protocol features. If
2455 either peer in the association uses multiple streams, or sends
2456 unordered data these calls will usually be inadequate, and may
2457 deliver the data in unpredictable ways.
2459 SCTP has the concept of multiple streams in one association. The
2463 Stewart, et al. Expires June 14, 2007 [Page 44]
2465 Internet-Draft SCTP sockets API December 2006
2468 above calls do not allow the caller to specify on which stream a
2469 message should be sent. The system uses stream 0 as the default
2470 stream for send() and sendto(). recv() and recvfrom() return data
2471 from any stream, but the caller can not distinguish the different
2472 streams. This may result in data seeming to arrive out of order.
2473 Similarly, if a data chunk is sent unordered, recv() and recvfrom()
2474 provide no indication.
2476 SCTP is message based. The msg buffer above in send() and sendto()
2477 is considered to be a single message. This means that if the caller
2478 wants to send a message which is composed by several buffers, the
2479 caller needs to combine them before calling send() or sendto().
2480 Alternately, the caller can use sendmsg() to do that without
2481 combining them. recv() and recvfrom() cannot distinguish message
2484 In receiving, if the buffer supplied is not large enough to hold a
2485 complete message, the receive call acts like a stream socket and
2486 returns as much data as will fit in the buffer.
2488 Note, the send() and recv() calls may not be used for a one-to-many
2491 Note, if an application calls a send function with no user data and
2492 no ancillary data the SCTP implementation should reject the request
2493 with an appropriate error message. An implementation is NOT allowed
2494 to send a Data chunk with no user data RFC2960 [RFC2960].
2496 6.2. setsockopt(), getsockopt()
2498 Applications use setsockopt() and getsockopt() to set or retrieve
2499 socket options. Socket options are used to change the default
2500 behavior of sockets calls. They are described in Section 7
2504 ret = getsockopt(int sd, int level, int optname, void *optval,
2506 ret = setsockopt(int sd, int level, int optname, const void *optval,
2510 sd - the socket descriptor.
2511 level - set to IPPROTO_SCTP for all SCTP options.
2519 Stewart, et al. Expires June 14, 2007 [Page 45]
2521 Internet-Draft SCTP sockets API December 2006
2524 optname - the option name.
2525 optval - the buffer to store the value of the option.
2526 optlen - the size of the buffer (or the length of the option
2529 All socket options set on a 1-to-1 listening sockets also apply all
2530 accepted sockets. All socket options set on a 1-to-many socket using
2531 the assoc_id 0 applies for all future assocs on the socket.
2533 6.3. read() and write()
2535 Applications can use read() and write() to send and receive data to
2536 and from peer. They have the same semantics as send() and recv()
2537 except that the flags parameter cannot be used.
2539 Note, these calls, when used in the one-to-many style, may only be
2540 used with branched off socket descriptors (see Section 8.2).
2544 Applications use getsockname() to retrieve the locally-bound socket
2545 address of the specified socket. This is especially useful if the
2546 caller let SCTP chose a local port. This call is for where the
2547 endpoint is not multi-homed. It does not work well with multi-homed
2548 sockets. See Section 8.5 for a multi-homed version of the call.
2552 int getsockname(int sd, struct sockaddr *address,
2555 sd - the socket descriptor to be queried.
2556 address - On return, one locally bound address (chosen by the SCTP
2557 stack) is stored in this buffer. If the socket is an IPv4 socket,
2558 the address will be IPv4. If the socket is an IPv6 socket, the
2559 address will be either an IPv6 or IPv4 address.
2560 len - The caller should set the length of address here. On return,
2561 this is set to the length of the returned address.
2563 If the actual length of the address is greater than the length of the
2564 supplied sockaddr structure, the stored address will be truncated.
2566 If the socket has not been bound to a local name, the value stored in
2567 the object pointed to by address is unspecified.
2575 Stewart, et al. Expires June 14, 2007 [Page 46]
2577 Internet-Draft SCTP sockets API December 2006
2582 The following sub-section describes various SCTP level socket options
2583 that are common to both styles. SCTP associations can be multi-
2584 homed. Therefore, certain option parameters include a
2585 sockaddr_storage structure to select which peer address the option
2586 should be applied to.
2588 For the one-to-many style sockets, an sctp_assoc_t structure
2589 (association ID) is used to identify the the association instance
2590 that the operation affects. So it must be set when using this style.
2592 For the one-to-one style sockets and branched off one-to-many style
2593 sockets (see Section 8.2) this association ID parameter is ignored.
2595 Note that socket or IP level options are set or retrieved per socket.
2596 This means that for one-to-many style sockets, those options will be
2597 applied to all associations belonging to the socket. And for one-to-
2598 one style, those options will be applied to all peer addresses of the
2599 association controlled by the socket. Applications should be very
2600 careful in setting those options.
2602 For some IP stacks getsockopt() is read-only; so a new interface will
2603 be needed when information must be passed both in to and out of the
2604 SCTP stack. The syntax for sctp_opt_info() is,
2606 int sctp_opt_info(int sd,
2612 The sctp_opt_info() call is a replacement for getsockopt() only and
2613 will not set any options associated with the specified socket. A
2614 setsockopt() must be used to set any writeable option.
2616 For one-to-many style sockets, id specifies the association to query.
2617 For one-to-one style sockets, id is ignored.
2619 opt specifies which SCTP socket option to get. It can get any socket
2620 option currently supported that requests information (either read/
2621 write options or read only) such as:
2631 Stewart, et al. Expires June 14, 2007 [Page 47]
2633 Internet-Draft SCTP sockets API December 2006
2636 SCTP_DEFAULT_SEND_PARAM
2637 SCTP_GET_PEER_ADDR_INFO
2639 SCTP_PEER_ADDR_PARAMS
2641 SCTP_AUTH_ACTIVE_KEY
2642 SCTP_PEER_AUTH_CHUNKS
2643 SCTP_LOCAL_AUTH_CHUNKS
2645 arg is an option-specific structure buffer provided by the caller.
2646 See Section 8.5) subsections for more information on these options
2647 and option-specific structures.
2649 sctp_opt_info() returns 0 on success, or on failure returns -1 and
2650 sets errno to the appropriate error code.
2652 All options that support specific settings on an association by
2653 filling in either an association id variable or a sockaddr_storage
2654 SHOULD also support setting of the same value for the entire endpoint
2655 (i.e. future associations). To accomplish this the following logic
2656 is used when setting one of these options:
2658 a) If an address is specified via a sockaddr_storage that is included
2659 in the structure, the address is used to lookup the association
2660 and the settings are applied to the specific address (if
2661 appropriate) or to the entire association.
2662 b) If an association identification is filled in but not a
2663 sockaddr_storage (if present), the association is found using the
2664 association identification and the settings should be applied to
2665 the entire association (since a specific address is not
2666 specified). Note this also applies to options that hold an
2667 association identification in their structure but do not have a
2668 sockaddr_storage field.
2669 c) If neither the sockaddr_storage or association identification is
2670 set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and
2671 the association identification is 0, the settings are a default
2672 and to be applied to the endpoint (all future associations).
2674 7.1. Read / Write Options
2676 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO)
2678 The protocol parameters used to initialize and bound retransmission
2679 timeout (RTO) are tunable. See RFC2960 [RFC2960] for more
2680 information on how these parameters are used in RTO calculation.
2682 The following structure is used to access and modify these
2687 Stewart, et al. Expires June 14, 2007 [Page 48]
2689 Internet-Draft SCTP sockets API December 2006
2692 struct sctp_rtoinfo {
2693 sctp_assoc_t srto_assoc_id;
2694 uint32_t srto_initial;
2699 srto_initial - This contains the initial RTO value.
2700 srto_max and srto_min - These contain the maximum and minimum bounds
2702 srto_assoc_id - (one-to-many style socket) This is filled in the
2703 application, and identifies the association for this query. If
2704 this parameter is '0' (on a one-to-many style socket), then the
2705 change effects the entire endpoint.
2707 All parameters are time values, in milliseconds. A value of 0, when
2708 modifying the parameters, indicates that the current value should not
2711 To access or modify these parameters, the application should call
2712 getsockopt or setsockopt() respectively with the option name
2715 7.1.2. Association Parameters (SCTP_ASSOCINFO)
2717 This option is used to both examine and set various association and
2718 endpoint parameters.
2720 See RFC2960 [RFC2960] for more information on how this parameter is
2721 used. The peer address parameter is ignored for one-to-one style
2724 The following structure is used to access and modify this parameters:
2726 struct sctp_assocparams {
2727 sctp_assoc_t sasoc_assoc_id;
2728 uint16_t sasoc_asocmaxrxt;
2729 uint16_t sasoc_number_peer_destinations;
2730 uint32_t sasoc_peer_rwnd;
2731 uint32_t sasoc_local_rwnd;
2732 uint32_t sasoc_cookie_life;
2735 sasoc_asocmaxrxt - This contains the maximum retransmission attempts
2736 to make for the association.
2743 Stewart, et al. Expires June 14, 2007 [Page 49]
2745 Internet-Draft SCTP sockets API December 2006
2748 sasoc_number_peer_destinations - This is the number of destination
2749 addresses that the peer has.
2750 sasoc_peer_rwnd - This holds the current value of the peers rwnd
2751 (reported in the last SACK) minus any outstanding data (i.e. data
2753 sasoc_local_rwnd - This holds the last reported rwnd that was sent
2755 sasoc_cookie_life - This is the associations cookie life value used
2756 when issuing cookies.
2757 sasoc_assoc_id - This is filled in the application, and identifies
2758 the association for this query.
2760 This information may be examined for either the endpoint or a
2761 specific association. To examine a endpoints default parameters the
2762 association id (sasoc_assoc_id) should must be set to the value '0'.
2763 The values of the sasoc_peer_rwnd is meaningless when examining
2764 endpoint information.
2766 All parameters are time values, in milliseconds. A value of 0, when
2767 modifying the parameters, indicates that the current value should not
2770 The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set
2771 on either an endpoint or association basis. The rwnd and destination
2772 counts (sasoc_number_peer_destinations,
2773 sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value
2774 placed in these is ignored.
2776 To access or modify these parameters, the application should call
2777 getsockopt or setsockopt() respectively with the option name
2780 The maximum number of retransmissions before an address is considered
2781 unreachable is also tunable, but is address-specific, so it is
2782 covered in a separate option. If an application attempts to set the
2783 value of the association maximum retransmission parameter to more
2784 than the sum of all maximum retransmission parameters, setsockopt()
2785 shall return an error. The reason for this, from RFC2960 [RFC2960]
2788 Note: When configuring the SCTP endpoint, the user should avoid
2789 having the value of 'Association.Max.Retrans' larger than the
2790 summation of the 'Path.Max.Retrans' of all the destination addresses
2791 for the remote endpoint. Otherwise, all the destination addresses
2792 may become inactive while the endpoint still considers the peer
2799 Stewart, et al. Expires June 14, 2007 [Page 50]
2801 Internet-Draft SCTP sockets API December 2006
2804 7.1.3. Initialization Parameters (SCTP_INITMSG)
2806 Applications can specify protocol parameters for the default
2807 association initialization. The structure used to access and modify
2808 these parameters is defined in Section 5.2.1). The option name
2809 argument to setsockopt() and getsockopt() is SCTP_INITMSG.
2811 Setting initialization parameters is effective only on an unconnected
2812 socket (for one-to-many style sockets only future associations are
2813 effected by the change). With one-to-one style sockets, this option
2814 is inherited by sockets derived from a listener socket.
2818 An application using the one-to-one style socket can use this option
2819 to perform the SCTP ABORT primitive. The linger option structure is:
2822 int l_onoff; /* option on/off */
2823 int l_linger; /* linger time */
2826 To enable the option, set l_onoff to 1. If the l_linger value is set
2827 to 0, calling close() is the same as the ABORT primitive. If the
2828 value is set to a negative value, the setsockopt() call will return
2829 an error. If the value is set to a positive value linger_time, the
2830 close() can be blocked for at most linger_time ms. If the graceful
2831 shutdown phase does not finish during this period, close() will
2832 return but the graceful shutdown phase continues in the system.
2834 Note, this is a socket level option NOT an SCTP level option. So
2835 when setting SO_LINGER you must specify a level of SOL_SOCKET in the
2840 Turn on/off any Nagle-like algorithm. This means that packets are
2841 generally sent as soon as possible and no unnecessary delays are
2842 introduced, at the cost of more packets in the network. Expects an
2843 integer boolean flag.
2847 Sets receive buffer size in octets. For SCTP one-to-one style
2848 sockets, this controls the receiver window size. For one-to-many
2849 style sockets the meaning depends on the constant HAVE_SCTP_MULTIBUF
2850 (see Section 3.4). If the implementation defines HAVE_SCTP_MULTIBUF
2851 as 1, this controls the receiver window size for each association
2855 Stewart, et al. Expires June 14, 2007 [Page 51]
2857 Internet-Draft SCTP sockets API December 2006
2860 bound to the socket descriptor. If the implementation defines
2861 HAVE_SCTP_MULTIBUF as 0, this controls the size of the single receive
2862 buffer for the whole socket. The call expects an integer.
2866 Sets send buffer size. For SCTP one-to-one style sockets, this
2867 controls the amount of data SCTP may have waiting in internal buffers
2868 to be sent. This option therefore bounds the maximum size of data
2869 that can be sent in a single send call. For one-to-many style
2870 sockets, the effect is the same, except that it applies to one or all
2871 associations (see Section 3.4) bound to the socket descriptor used in
2872 the setsockopt() or getsockopt() call. The option applies to each
2873 association's window size separately. The call expects an integer.
2875 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE)
2877 This socket option is applicable to the one-to-many style socket
2878 only. When set it will cause associations that are idle for more
2879 than the specified number of seconds to automatically close using the
2880 graceful shutdown procedure. An association being idle is defined as
2881 an association that has NOT sent or received user data. The special
2882 value of '0' indicates that no automatic close of any associations
2883 should be performed, this is the default value. The option expects
2884 an integer defining the number of seconds of idle time before an
2885 association is closed.
2887 An application using this option should enable receiving the
2888 association change notification. This is the only mechanism an
2889 application is informed about the closing of an association. After
2890 an association is closed, the association ID assigned to it can be
2891 reused. An application should be aware of this to avoid the possible
2892 problem of sending data to an incorrect peer end point.
2894 7.1.9. Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR)
2896 Requests that the peer mark the enclosed address as the association
2897 primary. The enclosed address must be one of the association's
2898 locally bound addresses. The following structure is used to make a
2899 set primary request:
2901 struct sctp_setpeerprim {
2902 sctp_assoc_t sspp_assoc_id;
2903 struct sockaddr_storage sspp_addr;
2911 Stewart, et al. Expires June 14, 2007 [Page 52]
2913 Internet-Draft SCTP sockets API December 2006
2916 sspp_addr - The address to set as primary
2917 sspp_assoc_id - This is filled in by the application, and identifies
2918 the association for this request.
2920 This functionality is optional. Implementations that do not support
2921 this functionality should return EOPNOTSUPP.
2923 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR)
2925 Requests that the local SCTP stack use the enclosed peer address as
2926 the association primary. The enclosed address must be one of the
2927 association peer's addresses. The following structure is used to
2928 make a set peer primary request:
2930 struct sctp_setprim {
2931 sctp_assoc_t ssp_assoc_id;
2932 struct sockaddr_storage ssp_addr;
2935 ssp_addr - The address to set as primary
2936 ssp_assoc_id - This is filled in by the application, and identifies
2937 the association for this request.
2939 7.1.11. Set Adaptation Layer Indicator (SCTP_ADAPTATION_LAYER)
2941 Requests that the local endpoint set the specified Adaptation Layer
2942 Indication parameter for all future INIT and INIT-ACK exchanges.
2945 struct sctp_setadaptation {
2946 uint32_t ssb_adaptation_ind;
2950 ssb_adaptation_ind - The adaptation layer indicator that will be
2951 included in any outgoing Adaptation Layer Indication parameter.
2953 7.1.12. Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS)
2955 This option is a on/off flag and is passed an integer where a non-
2956 zero is on and a zero is off. If enabled no SCTP message
2957 fragmentation will be performed. Instead if a message being sent
2958 exceeds the current PMTU size, the message will NOT be sent and
2959 instead a error will be indicated to the user.
2967 Stewart, et al. Expires June 14, 2007 [Page 53]
2969 Internet-Draft SCTP sockets API December 2006
2972 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS)
2974 Applications can enable or disable heartbeats for any peer address of
2975 an association, modify an address's heartbeat interval, force a
2976 heartbeat to be sent immediately, and adjust the address's maximum
2977 number of retransmissions sent before an address is considered
2978 unreachable. The following structure is used to access and modify an
2979 address's parameters:
2981 struct sctp_paddrparams {
2982 sctp_assoc_t spp_assoc_id;
2983 struct sockaddr_storage spp_address;
2984 uint32_t spp_hbinterval;
2985 uint16_t spp_pathmaxrxt;
2986 uint32_t spp_pathmtu;
2987 uint32_t spp_sackdelay;
2989 uint32_t spp_ipv6_flowlabel;
2990 uint8_t spp_ipv4_tos;
2993 spp_assoc_id - (one-to-many style socket) This is filled in the
2994 application, and identifies the association for this query.
2995 spp_address - This specifies which address is of interest.
2996 spp_hbinterval - This contains the value of the heartbeat interval,
2997 in milliseconds. Note that unless the spp_flag is set to
2998 SPP_HB_ENABLE the value of this field is ignored. Note also that
2999 a value of zero indicates the current setting should be left
3000 unchanged. To set an actual value of zero the use of the flag
3001 SPP_HB_TIME_IS_ZERO should be used.
3002 spp_pathmaxrxt - This contains the maximum number of retransmissions
3003 before this address shall be considered unreachable. Note that
3004 unless the spp_flag is set to SPP_PMTUD_ENABLE the value of this
3005 field is ignored. Note also that a value of zero indicates the
3006 current setting should be left unchanged.
3007 spp_pathmtu - When Path MTU discovery is disabled the value
3008 specified here will be the "fixed" path mtu (i.e. the value of the
3009 spp_flags field must include the flag SPP_PMTUD_DISABLE for this
3010 field to have any effect). Note that if the spp_address field is
3011 empty then all associations on this address will have this fixed
3012 path mtu set upon them. If an address is specified, then only
3013 that address will be effected.
3014 spp_sackdelay - When delayed sack is enabled, this value specifies
3015 the number of milliseconds that sacks will be delayed for. This
3016 value will apply to all addresses of an association if the
3017 spp_address field is empty. Note that unless the spp_flag is set
3018 to SPP_SACKDELAY_ENABLE the value of this field is ignored. Note
3019 also that a value of zero indicates the current setting should be
3023 Stewart, et al. Expires June 14, 2007 [Page 54]
3025 Internet-Draft SCTP sockets API December 2006
3029 spp_ipv6_flowlabel- This field is used in conjunction with the
3030 SPP_IPV4_FLOWLABEL flag.
3031 spp_ipv4_tos- This field is used in conjunction with the
3033 spp_flags- These flags are used to control various features on an
3034 association. The flag field is a bit mask which may contain zero
3035 or more of the following options:
3036 SPP_HB_ENABLE - Enable heartbeats on the specified address. Note
3037 that if the address field is empty all addresses for the
3038 association have heartbeats enabled upon them.
3039 SPP_HB_DISABLE - Disable heartbeats on the specified address.
3040 Note that if the address field is empty all addresses for the
3041 association will have their heartbeats disabled. Note also
3042 that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually exclusive,
3043 only one of these two should be specified. Enabling both
3044 fields will have undetermined results.
3045 SPP_HB_DEMAND - Request a user initiated heartbeat to be made
3047 SPP_HB_TIME_IS_ZERO - Specify's that the time for heartbeat delay
3048 is to be set to the value of 0 milliseconds.
3049 SPP_PMTUD_ENABLE - This field will enable PMTU discovery upon the
3050 specified address. Note that if the address field is empty
3051 then all addresses on the association are effected.
3052 SPP_PMTUD_DISABLE - This field will disable PMTU discovery upon
3053 the specified address. Note that if the address field is empty
3054 then all addresses on the association are effected. Not also
3055 that SPP_PMTUD_ENABLE and SPP_PMTUD_DISABLE are mutually
3056 exclusive. Enabling both will have undetermined results.
3057 SPP_SACKDELAY_ENABLE - Setting this flag turns on delayed sack.
3058 The time specified in spp_sackdelay is used to specify the sack
3059 delay for this address. Note that if spp_address is empty then
3060 all addresses will enable delayed sack and take on the sack
3061 delay value specified in spp_sackdelay.
3062 SPP_SACKDELAY_DISABLE - Setting this flag turns off delayed sack.
3063 If the spp_address field is blank then delayed sack is disabled
3064 for the entire association. Note also that this field is
3065 mutually exclusive to SPP_SACKDELAY_ENABLE, setting both will
3066 have undefined results.
3067 SPP_IPV6_FLOWLABEL - Setting this flag enables setting of the
3068 IPV6 flowlabel value associated with either the association or
3069 the specific address. If the address field is filled in, then
3070 the specific destination address has this value set upon it.
3071 If the association is specified, but not the address, then the
3072 flowlabel value is set for any future destination addresses
3073 that may be added. The value is obtained in the
3074 spp_ipv6_flowlabel field.
3079 Stewart, et al. Expires June 14, 2007 [Page 55]
3081 Internet-Draft SCTP sockets API December 2006
3084 Upon retrieval, this flag will be set to indicate that the
3085 spp_ipv6_flowlabel field has a valid value returned. If a
3086 specific destination addresses is set (in the spp_address
3087 field) when called then the value returned is that of the
3088 address. If just an association is specified (and no address)
3089 then the association default flowlabel is returned. If neither
3090 an association nor an destination is specified, then the
3091 sockets default flowlabel is returned. For non IPv6 sockets,
3092 then this flag will be left cleared.
3093 SPP_IPV4_TOS - Setting this flag enables setting of the IPV4 tos
3094 value associated with either the association or specific
3095 address. If the address field is filled in, then the specific
3096 destination address has this value set upon it. If the
3097 association is specified, but not the address, then the tos
3098 value is set for any future destination addresses that may be
3099 added. The value is obtained in the spp_ipv4_tos field.
3101 Upon retrieval, this flag will be set to indicate that the
3102 spp_ipv4_tos field has a valid value returned. If a specific
3103 destination addresses is set when called (in the spp_address
3104 field) then that specific destination addresses tos value is
3105 returned. If just an association is specified then the
3106 association default tos is returned. If neither an association
3107 nor an destination is specified, then the sockets default tos
3108 is returned. For non IPv4 sockets, then this flag will be left
3111 To read or modify these parameters, the application should call
3112 sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option.
3114 7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM)
3116 Applications that wish to use the sendto() system call may wish to
3117 specify a default set of parameters that would normally be supplied
3118 through the inclusion of ancillary data. This socket option allows
3119 such an application to set the default sctp_sndrcvinfo structure.
3120 The application that wishes to use this socket option simply passes
3121 in to this call the sctp_sndrcvinfo structure defined in
3122 Section 5.2.2) The input parameters accepted by this call include
3123 sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context,
3124 sinfo_timetolive. The sinfo_assoc_id field specifies the default
3125 association used for send operations on one-to-many style sockets.
3126 It is ignored on the one-to-one style. Note that setting the
3127 sinfo_assoc_id field to zero indicates that the users wishes to set
3128 the endpoint default send parameters for all future associations.
3135 Stewart, et al. Expires June 14, 2007 [Page 56]
3137 Internet-Draft SCTP sockets API December 2006
3140 7.1.15. Set notification and ancillary events (SCTP_EVENTS)
3142 This socket option is used to specify various notifications and
3143 ancillary data the user wishes to receive. Please see Section 7.3)
3144 for a full description of this option and its usage.
3146 7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR)
3148 This socket option is a boolean flag which turns on or off mapped V4
3149 addresses. If this option is turned on and the socket is type
3150 PF_INET6, then IPv4 addresses will be mapped to V6 representation.
3151 If this option is turned off, then no mapping will be done of V4
3152 addresses and a user will receive both PF_INET6 and PF_INET type
3153 addresses on the socket.
3155 By default this option is turned on and expects an integer to be
3156 passed where non-zero turns on the option and zero turns off the
3159 7.1.17. Set the maximum fragmentation size (SCTP_MAXSEG)
3161 This socket option specifies the maximum size to put in any outgoing
3162 SCTP DATA chunk. If a message is larger than this size it will be
3163 fragmented by SCTP into the specified size. Note that the underlying
3164 SCTP implementation may fragment into smaller sized chunks when the
3165 PMTU of the underlying association is smaller than the value set by
3166 the user. The option expects an integer.
3168 The default value for this option is '0' which indicates the user is
3169 NOT limiting fragmentation and only the PMTU will effect SCTP's
3170 choice of DATA chunk size.
3172 7.1.18. Add a chunk that must be authenticated (SCTP_AUTH_CHUNK)
3174 This option adds a chunk type that the user is requesting to be
3175 received only in an authenticated way. Changes to the list of chunks
3176 will only effect future associations on the socket.
3178 struct sctp_authchunk {
3179 uint8_t sauth_chunk;
3182 sauth_chunks - This parameter contains a chunk type
3183 that the user is requesting to be authenticated.
3186 The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH
3187 chunks MUST not be used. If they are used an error MUST be returned.
3191 Stewart, et al. Expires June 14, 2007 [Page 57]
3193 Internet-Draft SCTP sockets API December 2006
3196 The usage of this option enables SCTP-AUTH in cases where it is not
3197 required by other means (for example the use of ADD-IP).
3199 7.1.19. Get or set the list of supported HMAC Identifiers
3202 This option gets or sets the list of HMAC algorithms that the local
3203 endpoint requires the peer to use.
3206 struct sctp_hmacalgo {
3207 uint16_t shmac_idents[];
3211 shmac_idents - This parameter contains an array of HMAC Identifiers
3212 that the local endpoint is requesting the peer to use, in priority
3215 7.1.20. Set a shared key (SCTP_AUTH_KEY)
3217 This option will set a shared secret key which is used to build an
3218 association shared key.
3220 struct sctp_authkey {
3221 sctp_assoc_t sca_assoc_id;
3222 uint16_t sca_keynumber;
3227 sca_assoc_id - This parameter, if non-zero, indicates what
3228 association that the shared key is being set upon. Note that if
3229 this element contains zero, then the shared key is set upon the
3230 endpoint and all future associations will use this key (if not
3231 changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one
3232 sockets, this parameter is ignored. Note, however, that this
3233 option will set a key on the association if the socket is
3234 connected, otherwise this will set a key on the endpoint.
3235 sca_keynumber - this parameter is the shared key identifier by which
3236 the application will refer to this key. If a key of the specified
3237 index already exists, then this new key will replace the old
3238 existing key. Note that shared key identifier '0' defaults to a
3247 Stewart, et al. Expires June 14, 2007 [Page 58]
3249 Internet-Draft SCTP sockets API December 2006
3252 sca_key - This parameter contains an array of bytes that is to be
3253 used by the endpoint (or association) as the shared secret key.
3254 Note, if the length of this field is zero, a null key is set.
3256 7.1.21. Get or set the active shared key (SCTP_AUTH_ACTIVE_KEY)
3258 This option will get or set the active shared key to be used to build
3259 the association shared key.
3262 struct sctp_authkeyid {
3263 sctp_assoc_t scact_assoc_id;
3264 uint16_t scact_keynumber;
3268 scact_assoc_id - This parameter, if non-zero, indicates what
3269 association that the shared key identifier is being set active
3270 upon. Note that if this element contains zero, then the
3271 activation applies to the endpoint and all future associations
3272 will use the specified shared key identifier. For one-to-one
3273 sockets, this parameter is ignored. Note, however, that this
3274 option will set the active key on the association if the socket is
3275 connected, otherwise this will set the default active key for the
3277 scact_keynumber - this parameter is the shared key identifier which
3278 the application is requesting to become the active shared key to
3279 be used for sending authenticated chunks. The key identifier MUST
3280 correspond to an existing shared key. Note that shared key
3281 identifier '0' defaults to a null key.
3283 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY)
3285 This option will delete a shared secret key from use.
3288 struct sctp_authkeyid {
3289 sctp_assoc_t scact_assoc_id;
3290 uint16_t scact_keynumber;
3294 scact_assoc_id - This parameter, if non-zero, indicates what
3295 association that the shared key identifier is being deleted from.
3296 Note that if this element contains zero, then the shared key is
3297 deleted from the endpoint and all associations will no longer use
3298 the specified shared key identifier (unless otherwise set on the
3299 association using SCTP_AUTH_KEY). For one-to-one sockets, this
3303 Stewart, et al. Expires June 14, 2007 [Page 59]
3305 Internet-Draft SCTP sockets API December 2006
3308 parameter is ignored. Note, however, that this option will delete
3309 the key from the association if the socket is connected, otherwise
3310 this will delete the key from the endpoint.
3311 scact_keynumber - this parameter is the shared key identifier which
3312 the application is requesting to be deleted. The key identifier
3313 MUST correspond to an existing shared key and MUST NOT be the
3314 current active key. Note if this parameter is zero, use of the
3315 null key identifier '0' is disabled on the endpoint and/or
3318 7.1.23. Get or set delayed ack timer (SCTP_DELAYED_ACK_TIME)
3320 This options will get or set the delayed ack timer. The time is set
3321 in milliseconds. If the assoc_id is 0, then this sets or gets the
3322 endpoints default delayed ack timer value. If the assoc_id field is
3323 non-zero, then the set or get effects the specified association.
3326 struct sctp_assoc_value {
3327 sctp_assoc_t assoc_id;
3328 uint32_t assoc_value;
3332 assoc_id - This parameter, indicates which association the user is
3333 performing an action upon. Note that if this field's value is
3334 zero then the endpoints default value is changed (effecting future
3336 assoc_value - This parameter contains the number of milliseconds
3337 that the user is requesting the delayed ACK timer be set to. Note
3338 that this value is defined in the standard to be between 200 and
3341 7.1.24. Get or set fragmented interleave (SCTP_FRAGMENT_INTERLEAVE)
3343 This options will at a minimum specify if the implementation is doing
3344 fragmented interleave. Fragmented interleave, for a one to many
3345 socket, is when subsequent calls to receive a message may return
3346 parts of messages from different associations. Some implementations
3347 may allow you to turn this value on or off. If so, when turned off,
3348 no fragment interleave will occur (which will cause a head of line
3349 blocking amongst multiple associations sharing the same one to many
3350 socket). When this option is turned on, then each receive call may
3351 come from a different association (thus the user must receive data
3352 with the extended calls (e.g. sctp_recvmsg) to keep track of which
3353 association each receive belongs to.
3355 This option takes a boolean value. A non-zero value indicates that
3359 Stewart, et al. Expires June 14, 2007 [Page 60]
3361 Internet-Draft SCTP sockets API December 2006
3364 fragmented interleave is on. A value of zero indicates that
3365 fragmented interleave is off.
3367 Note that it is important that an implementation that allows this
3368 option to be turned on, have it off by default. Otherwise an unaware
3369 application using the one to many model may become confused and act
3372 7.1.25. Set or Get the sctp partial delivery point
3373 (SCTP_PARTIAL_DELIVERY_POINT)
3375 This option will set or get the SCTP partial delivery point. This
3376 point is the size of a message where the partial delivery API will be
3377 invoked to help free up rwnd space for the peer. Setting this to a
3378 lower value will cause partial delivery's to happen more often. The
3379 calls argument is an integer that sets or gets the partial delivery
3382 7.1.26. Set or Get the use of extended receive info
3383 (SCTP_USE_EXT_RCVINFO)
3385 This option will enable or disable the use of the extended version of
3386 the sctp_sndrcvinfo structure. If this option is disabled, then the
3387 normal sctp_sndrcvinfo structure is returned in all receive message
3388 calls. If this option is enabled then the sctp_extrcvinfo structure
3389 is returned in all receive message calls.
3391 Note that the sctp_extrcvinfo structure is never used in any send
3394 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF)
3396 This option will enable or disable the use of the automatic
3397 generation of ASCONF chunks to add and delete addresses to an
3398 existing association. Note that this option has two caveats namely:
3399 a) it only effects sockets that are bound to all addresses on the
3400 machine, and b) the system administrator may have an overriding
3401 control that turns the asconf feature off no matter what setting the
3402 socket option may have.
3404 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST)
3406 This option will allow a user to change the maximum burst of packets
3407 that can be emitted by this association. Note that the default value
3408 is 4, and some implementations may restrict this setting so that it
3409 can only be lowered.
3415 Stewart, et al. Expires June 14, 2007 [Page 61]
3417 Internet-Draft SCTP sockets API December 2006
3420 7.1.29. Set or Get the default context (SCTP_CONTEXT)
3422 The context field in the sctp_sndrcvinfo structure is normally only
3423 used when a failed message is retrieved holding the value that was
3424 sent down on the actual send call. This option allows the setting of
3425 a default context on an association basis that will be received on
3426 reading messages from the peer. This is especially helpful in the
3427 one-2-many model for an application to keep some reference to an
3428 internal state machine that is processing messages on the
3429 association. Note that the setting of this value only effects
3430 received messages from the peer and does not effect the value that is
3431 saved with outbound messages.
3433 To set or get this option the user fills in the following structure:
3436 struct sctp_assoc_value {
3437 sctp_assoc_t assoc_id;
3438 uint32_t assoc_value;
3442 assoc_id - This parameter, indicates which association the user is
3443 performing an action upon. Note that if this field's value is
3444 zero then the endpoints default value is changed (effecting future
3446 assoc_value - This parameter contains the context.
3448 7.1.30. Enable or disable explicit EOR marking (SCTP_EXPLICIT_EOR)
3450 This boolean flag is used to enable or disable explict end of record
3451 (EOR) marking. When this option is enabled, a user may make multiple
3452 send system calls to send a record and must indicate that they are
3453 finished sending a particular record by including on the send the
3454 SCTP_EOR flag. If this boolean flag is disabled then each individual
3455 send system call is considered to have a SCTP_EOR indicator set on it
3456 implicitly without the user having to explicitly add this flag.
3458 7.2. Read-Only Options
3460 7.2.1. Association Status (SCTP_STATUS)
3462 Applications can retrieve current status information about an
3463 association, including association state, peer receiver window size,
3464 number of unacked data chunks, and number of data chunks pending
3465 receipt. This information is read-only. The following structure is
3466 used to access this information:
3471 Stewart, et al. Expires June 14, 2007 [Page 62]
3473 Internet-Draft SCTP sockets API December 2006
3476 struct sctp_status {
3477 sctp_assoc_t sstat_assoc_id;
3478 int32_t sstat_state;
3479 uint32_t sstat_rwnd;
3480 uint16_t sstat_unackdata;
3481 uint16_t sstat_penddata;
3482 uint16_t sstat_instrms;
3483 uint16_t sstat_outstrms;
3484 uint32_t sstat_fragmentation_point;
3485 struct sctp_paddrinfo sstat_primary;
3489 sstat_state - This contains the association's current state one of
3490 the following values:
3497 SCTP_SHUTDOWN_PENDING
3499 SCTP_SHUTDOWN_RECEIVED
3500 SCTP_SHUTDOWN_ACK_SENT
3501 sstat_rwnd - This contains the association peer's current receiver
3503 sstat_unackdata - This is the number of unacked data chunks.
3504 sstat_penddata - This is the number of data chunks pending receipt.
3505 sstat_primary - This is information on the current primary peer
3507 sstat_assoc_id - (one-to-many style socket) This holds the an
3508 identifier for the association. All notifications for a given
3509 association have the same association identifier.
3510 sstat_instrms - The number of streams that the peer will be using
3512 sstat_outstrms - The number of streams that the endpoint is allowed
3514 sstat_fragmentation_point - The size at which SCTP fragmentation
3517 To access these status values, the application calls getsockopt()
3518 with the option name SCTP_STATUS. The sstat_assoc_id parameter is
3519 ignored for one-to-one style socket.
3527 Stewart, et al. Expires June 14, 2007 [Page 63]
3529 Internet-Draft SCTP sockets API December 2006
3532 7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO)
3534 Applications can retrieve information about a specific peer address
3535 of an association, including its reachability state, congestion
3536 window, and retransmission timer values. This information is read-
3537 only. The following structure is used to access this information:
3540 struct sctp_paddrinfo {
3541 sctp_assoc_t spinfo_assoc_id;
3542 struct sockaddr_storage spinfo_address;
3543 int32_t spinfo_state;
3544 uint32_t spinfo_cwnd;
3545 uint32_t spinfo_srtt;
3546 uint32_t spinfo_rto;
3547 uint32_t spinfo_mtu;
3551 spinfo_address - This is filled in the application, and contains the
3552 peer address of interest.
3554 On return from getsockopt():
3556 spinfo_state - This contains the peer addresses's state (either
3557 SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier
3559 spinfo_cwnd - This contains the peer addresses's current congestion
3561 spinfo_srtt - This contains the peer addresses's current smoothed
3562 round-trip time calculation in milliseconds.
3563 spinfo_rto - This contains the peer addresses's current
3564 retransmission timeout value in milliseconds.
3565 spinfo_mtu - The current P-MTU of this address.
3566 spinfo_assoc_id - This is field may be filled in by the application,
3567 if so, this field will have priority in looking up the association
3568 over the address specified in spinfo_address. Note that if the
3569 address does not belong to the association specified then this
3570 call will fail. If the application does NOT fill in the
3571 spinfo_assoc_id, then the address will be used to lookup the
3572 association and on return this field will have the valid
3573 association id. In other words, this call can be used to
3574 translate a address into an association id.
3576 To retrieve this information, use sctp_opt_info() with the
3577 SCTP_GET_PEER_ADDR_INFO options.
3583 Stewart, et al. Expires June 14, 2007 [Page 64]
3585 Internet-Draft SCTP sockets API December 2006
3588 7.2.3. Get the list of chunks the peer requires to be authenticated
3589 (SCTP_PEER_AUTH_CHUNKS)
3591 This option gets a list of chunks for a specified association that
3592 the peer requires to be received authenticated only.
3595 struct sctp_authchunks {
3596 sctp_assoc_t gauth_assoc_id;
3597 uint8_t gauth_chunks[];
3601 gauth_assoc_id - This parameter, indicates which association the
3602 user is requesting the list of peer authenticated chunks. For
3603 one-to-one sockets, this parameter is ignored.
3604 gauth_chunks - This parameter contains an array of chunks that the
3605 peer is requesting to be authenticated.
3607 7.2.4. Get the list of chunks the local endpoint requires to be
3608 authenticated (SCTP_LOCAL_AUTH_CHUNKS)
3610 This option gets a list of chunks for a specified association that
3611 the local endpoint requires to be received authenticated only.
3614 struct sctp_authchunks {
3615 sctp_assoc_t gauth_assoc_id;
3616 uint8_t gauth_chunks[];
3620 gauth_assoc_id - This parameter, indicates which association the
3621 user is requesting the list of local authenticated chunks. For
3622 one-to-one sockets, this parameter is ignored.
3623 gauth_chunks - This parameter contains an array of chunks that the
3624 local endpoint is requesting to be authenticated.
3626 7.2.5. Get the list of current associations (SCTP_GET_ASOC_ID_LIST)
3628 This option gets a list of current associations that are associated
3632 struct sctp_assoc_ids {
3633 uint16_t asls_assoc_start; /* array of index's start at 0 */
3634 uint8_t asls_numb_present;
3635 uint8_t asls_more_to_get;
3639 Stewart, et al. Expires June 14, 2007 [Page 65]
3641 Internet-Draft SCTP sockets API December 2006
3644 sctp_assoc_t asls_assoc_id[MAX_ASOC_IDS_RET];
3648 asls_assoc_start - This parameter gives an initial starting place to
3649 begin collecting association information. Normally a user sets
3650 this initially to 0. Subsequent calls that need to get more
3651 association identifications (in cases where the socket has more
3652 than MAX_ASOC_IDS_RET established i.e asls_more_to_get returns set
3653 to false) are made by incrementing the asls_assoc_start by the
3654 number of previous association id's seen. This cycle is repeated
3655 until the asls_more_to_get field becomes true, indicating that all
3656 association id's have been retrieved.
3657 asls_numb_present - This field holds the total number of
3658 associations that have been copied into the asls_assoc_id array.
3659 This value will NOT be larger than MAX_ASOC_IDS_RET.
3660 asls_more_to_get - This field holds a boolean flag indicating to the
3661 caller if more association id's are available then asked for.
3662 Subsequent calls to this option will be needed to gather these
3664 asls_assoc_id - an array of association id's that are currently
3665 active under this socket.
3666 MAX_ASOC_IDS_RET This value is a constant defined to limit the
3667 number of association identifications returned with each call.
3668 This value can be no larger than 255..
3670 7.3. Ancillary Data and Notification Interest Options
3672 Applications can receive per-message ancillary information and
3673 notifications of certain SCTP events with recvmsg().
3675 The following optional information is available to the application:
3677 1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e.
3678 stream number, TSN, SSN, etc. described in Section 5.2.2)
3679 2. SCTP_ASSOC_CHANGE (sctp_association_event): (described in
3681 3. SCTP_PEER_ADDR_CHANGE (sctp_address_event): (described in
3683 4. SCTP_SEND_FAILED (sctp_send_failure_event): (described in
3685 5. SCTP_REMOTE_ERROR (sctp_peer_error_event): (described in
3687 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in
3689 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event):
3690 (described in Section 5.3.1.7)
3695 Stewart, et al. Expires June 14, 2007 [Page 66]
3697 Internet-Draft SCTP sockets API December 2006
3700 8. SCTP_ADAPTATION_INDICATION (sctp_adaptation_layer_event):
3701 (described in Section 5.3.1.6)
3702 9. SCTP_AUTHENTICATION_INDICATION (sctp_authentication_event):
3703 (described in Section 5.3.1.8)
3705 To receive any ancillary data or notifications, first the application
3706 registers it's interest by calling the SCTP_EVENTS setsockopt() with
3707 the following structure.
3709 struct sctp_event_subscribe{
3710 uint8_t sctp_data_io_event;
3711 uint8_t sctp_association_event;
3712 uint8_t sctp_address_event;
3713 uint8_t sctp_send_failure_event;
3714 uint8_t sctp_peer_error_event;
3715 uint8_t sctp_shutdown_event;
3716 uint8_t sctp_partial_delivery_event;
3717 uint8_t sctp_adaptation_layer_event;
3718 uint8_t sctp_authentication_event;
3721 sctp_data_io_event - Setting this flag to 1 will cause the reception
3722 of SCTP_SNDRCV information on a per message basis. The application
3723 will need to use the recvmsg() interface so that it can receive the
3724 event information contained in the msg_control field. Please see
3725 Section 5.2 for further details. Setting the flag to 0 will disable
3726 reception of the message control information.
3728 sctp_association_event - Setting this flag to 1 will enable the
3729 reception of association event notifications. Setting the flag to 0
3730 will disable association event notifications. For more information
3731 on event notifications please see Section 5.3.
3733 sctp_address_event - Setting this flag to 1 will enable the reception
3734 of address event notifications. Setting the flag to 0 will disable
3735 address event notifications. For more information on event
3736 notifications please see Section 5.3.
3738 sctp_send_failure_event - Setting this flag to 1 will enable the
3739 reception of send failure event notifications. Setting the flag to 0
3740 will disable send failure event notifications. For more information
3741 on event notifications please see Section 5.3.
3743 sctp_peer_error_event - Setting this flag to 1 will enable the
3744 reception of peer error event notifications. Setting the flag to 0
3745 will disable peer error event notifications. For more information on
3746 event notifications please see Section 5.3.
3751 Stewart, et al. Expires June 14, 2007 [Page 67]
3753 Internet-Draft SCTP sockets API December 2006
3756 sctp_shutdown_event - Setting this flag to 1 will enable the
3757 reception of shutdown event notifications. Setting the flag to 0
3758 will disable shutdown event notifications. For more information on
3759 event notifications please see Section 5.3.
3761 sctp_partial_delivery_event - Setting this flag to 1 will enable the
3762 reception of partial delivery notifications. Setting the flag to 0
3763 will disable partial delivery event notifications. For more
3764 information on event notifications please see Section 5.3.
3766 sctp_adaptation_layer_event - Setting this flag to 1 will enable the
3767 reception of adaptation layer notifications. Setting the flag to 0
3768 will disable adaptation layer event notifications. For more
3769 information on event notifications please see Section 5.3.
3771 sctp_authentication_event - Setting this flag to 1 will enable the
3772 reception of authentication layer notifications. Setting the flag to
3773 0 will disable authentication layer event notifications. For More
3774 information please see Section 5.3.
3776 An example where an application would like to receive data io events
3777 and association events but no others would be as follows:
3780 struct sctp_event_subscribe event;
3782 memset(&event,0,sizeof(event));
3784 event.sctp_data_io_event = 1;
3785 event.sctp_association_event = 1;
3787 setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &event, sizeof(event));
3790 Note that for one-to-many style SCTP sockets, the caller of recvmsg()
3791 receives ancillary data and notifications for ALL associations bound
3792 to the file descriptor. For one-to-one style SCTP sockets, the
3793 caller receives ancillary data and notifications for only the single
3794 association bound to the file descriptor.
3796 By default both the one-to-one style and one-to-many style socket has
3802 Depending on the system, the following interface can be implemented
3803 as a system call or library function.
3807 Stewart, et al. Expires June 14, 2007 [Page 68]
3809 Internet-Draft SCTP sockets API December 2006
3814 The syntax of sctp_bindx() is,
3816 int sctp_bindx(int sd, struct sockaddr *addrs, int addrcnt,
3819 If sd is an IPv4 socket, the addresses passed must be IPv4 addresses.
3820 If the sd is an IPv6 socket, the addresses passed can either be IPv4
3823 A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see
3824 Section 3.1.2 for this usage.
3826 addrs is a pointer to an array of one or more socket addresses. Each
3827 address is contained in its appropriate structure. For an IPv6
3828 socket, an array of sockaddr_in6 would be returned. For a IPv4
3829 socket, an array of sockaddr_in would be returned. The caller
3830 specifies the number of addresses in the array with addrcnt. Note
3831 that the wildcard addresses cannot be used with this function, doing
3832 so will result in an error.
3834 On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns
3835 -1, and sets errno to the appropriate error code.
3837 For SCTP, the port given in each socket address must be the same, or
3838 sctp_bindx() will fail, setting errno to EINVAL.
3840 The flags parameter is formed from the bitwise OR of zero or more of
3841 the following currently defined flags:
3847 SCTP_BINDX_ADD_ADDR directs SCTP to add the given addresses to the
3848 association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given
3849 addresses from the association. The two flags are mutually
3850 exclusive; if both are given, sctp_bindx() will fail with EINVAL. A
3851 caller may not remove all addresses from an association; sctp_bindx()
3852 will reject such an attempt with EINVAL.
3854 An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate
3855 additional addresses with an endpoint after calling bind(). Or use
3856 sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening
3857 socket is associated with so that no new association accepted will be
3858 associated with those addresses. If the endpoint supports dynamic
3859 address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a
3863 Stewart, et al. Expires June 14, 2007 [Page 69]
3865 Internet-Draft SCTP sockets API December 2006
3868 endpoint to send the appropriate message to the peer to change the
3869 peers address lists.
3871 Adding and removing addresses from a connected association is
3872 optional functionality. Implementations that do not support this
3873 functionality should return EOPNOTSUPP.
3875 8.2. Branched-off Association
3877 After an association is established on a one-to-many style socket,
3878 the application may wish to branch off the association into a
3879 separate socket/file descriptor.
3881 This is particularly desirable when, for instance, the application
3882 wishes to have a number of sporadic message senders/receivers remain
3883 under the original one-to-many style socket but branch off those
3884 associations carrying high volume data traffic into their own
3885 separate socket descriptors.
3887 The application uses sctp_peeloff() call to branch off an association
3888 into a separate socket (Note the semantics are somewhat changed from
3889 the traditional one-to-one style accept() call). Note that the new
3890 socket is a one-to-one style socket. Thus it will be confined to
3891 operations allowed for a one-to-one style socket.
3895 new_sd = sctp_peeloff(int sd, sctp_assoc_t assoc_id);
3897 new_sd: the new socket descriptor representing the branched-off
3899 sd: the original one-to-many style socket descriptor returned from
3900 the socket() system call (see Section 3.1.1).
3901 assoc_id: the specified identifier of the association that is to be
3902 branched off to a separate file descriptor (Note, in a traditional
3903 one-to-one style accept() call, this would be an out parameter,
3904 but for the one-to-many style call, this is an in parameter).
3906 8.3. sctp_getpaddrs()
3908 sctp_getpaddrs() returns all peer addresses in an association. The
3911 int sctp_getpaddrs(int sd, sctp_assoc_t id,
3912 struct sockaddr **addrs);
3915 On return, addrs will point to an array dynamically allocated
3919 Stewart, et al. Expires June 14, 2007 [Page 70]
3921 Internet-Draft SCTP sockets API December 2006
3924 sockaddr structures of the appropriate type for the socket type. The
3925 caller should use sctp_freepaddrs() to free the memory. Note that
3926 the in/out parameter addrs must not be NULL.
3928 If sd is an IPv4 socket, the addresses returned will be all IPv4
3929 addresses. If sd is an IPv6 socket, the addresses returned can be a
3930 mix of IPv4 or IPv6 addresses.
3932 For one-to-many style sockets, id specifies the association to query.
3933 For one-to-one style sockets, id is ignored.
3935 On success, sctp_getpaddrs() returns the number of peer addresses in
3936 the association. If there is no association on this socket,
3937 sctp_getpaddrs() returns 0, and the value of *addrs is undefined. If
3938 an error occurs, sctp_getpaddrs() returns -1, and the value of *addrs
3941 8.4. sctp_freepaddrs()
3945 sctp_freepaddrs() frees all resources allocated by
3946 sctp_getpaddrs(). Its syntax is,
3948 void sctp_freepaddrs(struct sockaddr *addrs);
3949 addrs is the array of peer addresses returned by sctp_getpaddrs().
3952 8.5. sctp_getladdrs()
3954 sctp_getladdrs() returns all locally bound address(es) on a socket.
3957 int sctp_getladdrs(int sd, sctp_assoc_t id,
3958 struct sockaddr **ss);
3961 On return, addrs will point to a dynamically allocated array of
3962 sockaddr structures of the appropriate type for the socket type. The
3963 caller should use sctp_freeladdrs() to free the memory. Note that
3964 the in/out parameter addrs must not be NULL.
3966 If sd is an IPv4 socket, the addresses returned will be all IPv4
3967 addresses. If sd is an IPv6 socket, the addresses returned can be a
3968 mix of IPv4 or IPv6 addresses.
3970 For one-to-many style sockets, id specifies the association to query.
3971 For one-to-one style sockets, id is ignored.
3975 Stewart, et al. Expires June 14, 2007 [Page 71]
3977 Internet-Draft SCTP sockets API December 2006
3980 If the id field is set to the value '0' then the locally bound
3981 addresses are returned without regard to any particular association.
3983 On success, sctp_getladdrs() returns the number of local addresses
3984 bound to the socket. If the socket is unbound, sctp_getladdrs()
3985 returns 0, and the value of *addrs is undefined. If an error occurs,
3986 sctp_getladdrs() returns -1, and the value of *addrs is undefined.
3988 8.6. sctp_freeladdrs()
3990 sctp_freeladdrs() frees all resources allocated by
3991 sctp_getladdrs(). Its syntax is,
3993 void sctp_freeladdrs(struct sockaddr *addrs);
3995 addrs is the array of peer addresses returned by sctp_getladdrs().
3999 An implementation may provide a library function (or possibly system
4000 call) to assist the user with the advanced features of SCTP.
4003 sctp_sendmsg(). Its syntax is,
4005 ssize_t sctp_sendmsg(int sd,
4008 const struct sockaddr *to,
4013 uint32_t timetolive,
4017 sd - is the socket descriptor
4018 msg - is the message to be sent.
4019 len - is the length of the message.
4020 to - is the destination address of the message.
4021 tolen - is the length of the destination address.
4022 ppid - is the same as sinfo_ppid (see section 5.2.2)
4023 flags - is the same as sinfo_flags (see section 5.2.2)
4031 Stewart, et al. Expires June 14, 2007 [Page 72]
4033 Internet-Draft SCTP sockets API December 2006
4036 stream_no - is the same as sinfo_stream (see section 5.2.2)
4037 timetolive - is the same as sinfo_timetolive (see section 5.2.2)
4038 context - is the same as sinfo_context (see section 5.2.2)
4039 The call returns the number of characters sent, or -1 if an error
4040 occurred. The variable errno is then set appropriately.
4044 An implementation may provide a library function (or possibly system
4045 call) to assist the user with the advanced features of SCTP. Note
4046 that in order for the sctp_sndrcvinfo structure to be filled in by
4047 sctp_recvmsg() the caller must enable the sctp_data_io_events with
4048 the SCTP_EVENTS option. Note that the setting of the
4049 SCTP_USE_EXT_RCVINFO will effect this function as well, causing the
4050 sctp_sndrcvinfo information to be extended.
4053 sctp_recvmsg(). Its syntax is,
4055 ssize_t sctp_recvmsg(int sd,
4058 struct sockaddr *from,
4060 struct sctp_sndrcvinfo *sinfo
4064 sd - is the socket descriptor
4065 msg - is a message buffer to be filled.
4066 len - is the length of the message buffer.
4067 from - is a pointer to a address to be filled with the sender of
4068 this messages address.
4069 fromlen - is the from length.
4070 sinfo - A pointer to a sctp_sndrcvinfo structure to be filled upon
4071 receipt of the message.
4072 msg_flags - A pointer to a integer to be filled with any message
4073 flags (e.g. MSG_NOTIFICATION).
4074 The call returns the number of bytes received, or -1 if an error
4075 occurred. The variable errno is then set appropriately.
4077 8.9. sctp_connectx()
4079 An implementation may provide a library function (or possibly system
4080 call) to assist the user with associating to an endpoint that is
4081 multi-homed. Much like sctp_bindx() this call allows a caller to
4082 specify multiple addresses at which a peer can be reached. The way
4083 the SCTP stack uses the list of addresses to set up the association
4087 Stewart, et al. Expires June 14, 2007 [Page 73]
4089 Internet-Draft SCTP sockets API December 2006
4092 is implementation dependent. This function only specifies that the
4093 stack will try to make use of all the addresses in the list when
4096 Note that the list of addresses passed in is only used for setting up
4097 the association. It does not necessarily equal the set of addresses
4098 the peer uses for the resulting association. If the caller wants to
4099 find out the set of peer addresses, it must use sctp_getpaddrs() to
4100 retrieve them after the association has been set up.
4102 sctp_connectx(). Its syntax is,
4105 int sctp_connectx(int sd,
4106 struct sockaddr *addrs,
4111 sd - is the socket descriptor
4112 addrs - is an array of addresses.
4113 addrcnt - is the number of addresses in the array.
4114 id - is an output parameter that if passed in as a non-NULL will
4115 return the association identification for the newly created
4116 association (if successful).
4118 The call returns 0 on success or -1 if an error occured. The
4119 variable errno is then set appropriately.
4123 An implementation may provide another alternative function or system
4124 call to assist an application with the sending of data without the
4125 use of the CMSG header structures. The function takes the following
4128 sctp_send(). Its syntax is,
4130 int sctp_send(int sd,
4133 const struct sctp_sndrcvinfo *sinfo,
4143 Stewart, et al. Expires June 14, 2007 [Page 74]
4145 Internet-Draft SCTP sockets API December 2006
4148 sd - is the socket descriptor
4149 msg - The message to be sent
4150 len - The length of the message
4151 sinfo - A pointer to a sctp_sndrcvinfo structure used as described
4152 in 5.2.2 for a sendmsg call.
4153 flags - is used in the same format as the sendmsg call flags (e.g.
4156 This function call may also be used to terminate an association using
4157 an association identification by setting the sinfo.sinfo_flags to
4158 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs
4159 to be terminated. In such a case the len of the message would be
4162 The call returns the number of characters sent, or -1 if an error
4163 occurred. The variable errno is then set appropriately.
4167 An implementation may provide another alternative function or system
4168 call to assist an application with the sending of data without the
4169 use of the CMSG header structures that also gives a list of
4170 addresses. The list of addresses is provided for implicit
4171 association setup. In such a case the list of addresses serves the
4172 same purpose as the addresses given in sctp_connectx (see
4176 sctp_sendx(). Its syntax is,
4178 int sctp_sendx(int sd,
4181 struct sockaddr *addrs,
4183 struct sctp_sndrcvinfo *sinfo,
4186 sd - is the socket descriptor
4187 msg - The message to be sent
4188 len - The length of the message
4189 addrs - is an array of addresses.
4190 addrcnt - is the number of addresses in the array.
4191 sinfo - A pointer to a sctp_sndrcvinfo structure used as described
4192 in 5.2.2 for a sendmsg call.
4199 Stewart, et al. Expires June 14, 2007 [Page 75]
4201 Internet-Draft SCTP sockets API December 2006
4204 flags - is used in the same format as the sendmsg call flags (e.g.
4207 Note that on return from this call the sinfo structure will have
4208 changed in that the sinfo_assoc_id will be filled in with the new
4211 This function call may also be used to terminate an association using
4212 an association identification by setting the sinfo.sinfo_flags to
4213 SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs
4214 to be terminated. In such a case the len of the message would be
4217 The call returns the number of characters sent, or -1 if an error
4218 occurred. The variable errno is then set appropriately.
4220 8.12. sctp_getaddrlen
4222 For application binary portability it is sometimes desirable to know
4223 what the kernel thinks is the length of a socket address family.
4224 This function, when called with a valid family type will return the
4225 length that the operating system uses in the specified family's
4226 socket address structure.
4229 int sctp_getaddrlen(sa_family_t family);
4232 9. Preprocessor Constants
4234 For application portability it is desirable to define pre-processor
4235 constants for determination if sctp is present and supports various
4236 features. The following pre-processor constants should be defined in
4237 a include file, sctp.h.
4239 HAVE_SCTP - If this constant is defined to 1, then an implementation
4240 of SCTP is available.
4241 HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel
4242 SCTP implementation is available through the sockets interface.
4243 HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP
4244 implementation supports the partial reliability extension to SCTP.
4245 HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP
4246 implementation supports the dynamic address extension to SCTP.
4247 HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then
4248 the SCTP implementation supports the ability to request setting of
4249 the remote primary address.
4255 Stewart, et al. Expires June 14, 2007 [Page 76]
4257 Internet-Draft SCTP sockets API December 2006
4260 HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1,
4261 then the SCTP implementation supports the satellite network
4263 HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP
4264 implementation dedicates separate buffer space to each association
4265 on a one-to-many socket. If this constant is defined to 0, then
4266 the implementation provides a single block of shared buffer space
4267 for a one-to-many socket.
4268 HAVE_SCTP_NOCONNECT - If this constant is defined to 1, then the
4269 SCTP implementation supports initiating an association on a one-
4270 to-one style socket without the use of connect(), as outlined in
4272 HAVE_SCTP_EXT_RCVINFO - If this constant is defined to 1, then the
4273 SCTP implementation supports the use of the extended style
4274 sndrecinfo structure, sctp_extrcvinfo.
4277 10. IANA considerations
4279 This document contains no IANA considerations.
4282 11. Security Considerations
4284 Many TCP and UDP implementations reserve port numbers below 1024 for
4285 privileged users. If the target platform supports privileged users,
4286 the SCTP implementation SHOULD restrict the ability to call bind() or
4287 sctp_bindx() on these port numbers to privileged users.
4289 Similarly unprivileged users should not be able to set protocol
4290 parameters which could result in the congestion control algorithm
4291 being more aggressive than permitted on the public Internet. These
4296 If an unprivileged user inherits a one-to-many style socket with open
4297 associations on a privileged port, it MAY be permitted to accept new
4298 associations, but it SHOULD NOT be permitted to open new
4299 associations. This could be relevant for the r* family of protocols.
4304 Special acknowledgment is given to Ken Fujita and Jonathan Woods who
4305 helped extensively in the early formation of this document.
4307 The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon
4311 Stewart, et al. Expires June 14, 2007 [Page 77]
4313 Internet-Draft SCTP sockets API December 2006
4316 Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, and
4317 many others on the TSVWG mailing list for contributing valuable
4320 A special thanks to Phillip Conrad, for his suggested text, quick and
4321 constructive insights, and most of all his persistent fighting to
4322 keep the interface to SCTP usable for the application programmer.
4325 13. Normative references
4327 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
4328 RFC 793, September 1981.
4330 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
4333 [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions
4334 Functional Specification", RFC 1644, July 1994.
4336 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
4337 3", BCP 9, RFC 2026, October 1996.
4339 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
4340 Requirement Levels", BCP 14, RFC 2119, March 1997.
4342 [RFC2292] Stevens, W. and M. Thomas, "Advanced Sockets API for
4343 IPv6", RFC 2292, February 1998.
4345 [RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens,
4346 "Basic Socket Interface Extensions for IPv6", RFC 2553,
4349 [RFC2960] Stewart, R., Xie, Q., Morneault, K., Sharp, C.,
4350 Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M.,
4351 Zhang, L., and V. Paxson, "Stream Control Transmission
4352 Protocol", RFC 2960, October 2000.
4355 Appendix A. one-to-one style Code Example
4357 The following code is a simple implementation of an echo server over
4358 SCTP. The example shows how to use some features of one-to-one style
4359 IPv4 SCTP sockets, including:
4367 Stewart, et al. Expires June 14, 2007 [Page 78]
4369 Internet-Draft SCTP sockets API December 2006
4372 o Opening, binding, and listening for new associations on a socket;
4373 o Enabling ancillary data
4374 o Enabling notifications
4375 o Using ancillary data with sendmsg() and recvmsg()
4376 o Using MSG_EOR to determine if an entire message has been read
4377 o Handling notifications
4380 #include <sys/types.h>
4381 #include <sys/socket.h>
4382 #include <netinet/in.h>
4383 #include <arpa/inet.h>
4386 #include <netinet/sctp.h>
4387 #include <sys/uio.h>
4392 handle_event(void *buf)
4394 struct sctp_assoc_change *sac;
4395 struct sctp_send_failed *ssf;
4396 struct sctp_paddr_change *spc;
4397 struct sctp_remote_error *sre;
4398 union sctp_notification *snp;
4399 char addrbuf[INET6_ADDRSTRLEN];
4401 struct sockaddr_in *sin;
4402 struct sockaddr_in6 *sin6;
4406 switch (snp->sn_header.sn_type) {
4407 case SCTP_ASSOC_CHANGE:
4408 sac = &snp->sn_assoc_change;
4409 printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu "
4410 "outstr=%hu\n", sac->sac_state, sac->sac_error,
4411 sac->sac_inbound_streams, sac->sac_outbound_streams);
4413 case SCTP_SEND_FAILED:
4414 ssf = &snp->sn_send_failed;
4415 printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length,
4419 case SCTP_PEER_ADDR_CHANGE:
4423 Stewart, et al. Expires June 14, 2007 [Page 79]
4425 Internet-Draft SCTP sockets API December 2006
4428 spc = &snp->sn_paddr_change;
4429 if (spc->spc_aaddr.ss_family == AF_INET) {
4430 sin = (struct sockaddr_in *)&spc->spc_aaddr;
4431 ap = inet_ntop(AF_INET, &sin->sin_addr,
4432 addrbuf, INET6_ADDRSTRLEN);
4434 sin6 = (struct sockaddr_in6 *)&spc->spc_aaddr;
4435 ap = inet_ntop(AF_INET6, &sin6->sin6_addr,
4436 addrbuf, INET6_ADDRSTRLEN);
4438 printf("^^^ intf_change: %s state=%d, error=%d\n", ap,
4439 spc->spc_state, spc->spc_error);
4441 case SCTP_REMOTE_ERROR:
4442 sre = &snp->sn_remote_error;
4443 printf("^^^ remote_error: err=%hu len=%hu\n",
4444 ntohs(sre->sre_error), ntohs(sre->sre_length));
4446 case SCTP_SHUTDOWN_EVENT:
4447 printf("^^^ shutdown event\n");
4450 printf("unknown type: %hu\n", snp->sn_header.sn_type);
4456 mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen,
4457 ssize_t *nrp, size_t cmsglen)
4459 ssize_t nr = 0, nnr = 0;
4460 struct iovec iov[1];
4463 iov->iov_base = buf;
4464 iov->iov_len = *buflen;
4466 msg->msg_iovlen = 1;
4471 #define MSG_XPG4_2 0
4473 msg->msg_flags = MSG_XPG4_2;
4474 msg->msg_controllen = cmsglen;
4479 Stewart, et al. Expires June 14, 2007 [Page 80]
4481 Internet-Draft SCTP sockets API December 2006
4484 nnr = recvmsg(fd, msg, 0);
4492 if ((msg->msg_flags & MSG_EOR) != 0) {
4497 /* Realloc the buffer? */
4498 if (*buflen == (size_t)nr) {
4499 buf = realloc(buf, *buflen * 2);
4501 fprintf(stderr, "out of memory\n");
4506 /* Set the next read offset */
4507 iov->iov_base = (char *)buf + nr;
4508 iov->iov_len = *buflen - nr;
4513 echo(int fd, int socketModeone_to_many)
4516 struct sctp_sndrcvinfo *sri;
4517 struct msghdr msg[1];
4518 struct cmsghdr *cmsg;
4519 char cbuf[sizeof (*cmsg) + sizeof (*sri)];
4522 struct iovec iov[1];
4523 size_t cmsglen = sizeof (*cmsg) + sizeof (*sri);
4524 /* Allocate the initial data buffer */
4526 if (!(buf = malloc(BUFLEN))) {
4527 fprintf(stderr, "out of memory\n");
4531 /* Set up the msghdr structure for receiving */
4535 Stewart, et al. Expires June 14, 2007 [Page 81]
4537 Internet-Draft SCTP sockets API December 2006
4540 memset(msg, 0, sizeof (*msg));
4541 msg->msg_control = cbuf;
4542 msg->msg_controllen = cmsglen;
4544 cmsg = (struct cmsghdr *)cbuf;
4545 sri = (struct sctp_sndrcvinfo *)(cmsg + 1);
4547 /* Wait for something to echo */
4548 while (buf = mysctp_recvmsg(fd, msg,
4549 buf, &buflen, &nr, cmsglen)) {
4551 /* Intercept notifications here */
4552 if (msg->msg_flags & MSG_NOTIFICATION) {
4557 iov->iov_base = buf;
4560 msg->msg_iovlen = 1;
4562 printf("got %u bytes on stream %hu:\n", nr,
4567 msg->msg_flags = MSG_XPG4_2;
4568 if (sendmsg(fd, msg, 0) < 0) {
4577 if(socketModeone_to_many == 0)
4583 struct sctp_event_subscribe event;
4586 struct sockaddr_in sin[1];
4587 if ((lfd = socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)) == -1) {
4591 Stewart, et al. Expires June 14, 2007 [Page 82]
4593 Internet-Draft SCTP sockets API December 2006
4600 sin->sin_family = AF_INET;
4601 sin->sin_port = htons(7);
4602 sin->sin_addr.s_addr = INADDR_ANY;
4603 if (bind(lfd, (struct sockaddr *)sin, sizeof (*sin)) == -1) {
4608 if (listen(lfd, 1) == -1) {
4613 /* Wait for new associations */
4615 if ((cfd = accept(lfd, NULL, 0)) == -1) {
4620 /* Enable all events */
4621 event.sctp_data_io_event = 1;
4622 event.sctp_association_event = 1;
4623 event.sctp_address_event = 1;
4624 event.sctp_send_failure_event = 1;
4625 event.sctp_peer_error_event = 1;
4626 event.sctp_shutdown_event = 1;
4627 event.sctp_partial_delivery_event = 1;
4628 event.sctp_adaptation_layer_event = 1;
4629 if (setsockopt(cfd, IPPROTO_SCTP,
4630 SCTP_EVENTS, &event,
4631 sizeof(event)) != 0) {
4632 perror("setevent failed");
4635 /* Echo back any and all data */
4647 Stewart, et al. Expires June 14, 2007 [Page 83]
4649 Internet-Draft SCTP sockets API December 2006
4652 Appendix B. one-to-many style Code Example
4654 The following code is a simple implementation of an echo server over
4655 SCTP. The example shows how to use some features of one-to-many
4656 style IPv4 SCTP sockets, including:
4658 o Opening and binding of a socket;
4659 o Enabling ancillary data
4660 o Enabling notifications
4661 o Using ancillary data with sendmsg() and recvmsg()
4662 o Using MSG_EOR to determine if an entire message has been read
4663 o Handling notifications
4665 Note most functions defined in Appendix A are reused in this example.
4671 struct sockaddr_in sin[1];
4672 struct sctp_event_subscribe event;
4674 if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) {
4679 sin->sin_family = AF_INET;
4680 sin->sin_port = htons(7);
4681 sin->sin_addr.s_addr = INADDR_ANY;
4682 if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) {
4687 /* Enable all notifications and events */
4688 event.sctp_data_io_event = 1;
4689 event.sctp_association_event = 1;
4690 event.sctp_address_event = 1;
4691 event.sctp_send_failure_event = 1;
4692 event.sctp_peer_error_event = 1;
4693 event.sctp_shutdown_event = 1;
4694 event.sctp_partial_delivery_event = 1;
4695 event.sctp_adaptation_layer_event = 1;
4696 if (setsockopt(fd, IPPROTO_SCTP,
4697 SCTP_EVENTS, &event,
4698 sizeof(event)) != 0) {
4699 perror("setevent failed");
4703 Stewart, et al. Expires June 14, 2007 [Page 84]
4705 Internet-Draft SCTP sockets API December 2006
4710 /* Set associations to auto-close in 2 seconds of
4713 if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE,
4714 &idleTime, 4) < 0) {
4715 perror("setsockopt SCTP_AUTOCLOSE");
4719 /* Allow new associations to be accepted */
4720 if (listen(fd, 1) < 0) {
4725 /* Wait for new associations */
4727 /* Echo back any and all data */
4743 Email: rrs@cisco.com
4748 1501 W. Shure Drive, #2309
4749 Arlington Heights, IL 60004
4753 Email: qxie1@email.mot.com
4759 Stewart, et al. Expires June 14, 2007 [Page 85]
4761 Internet-Draft SCTP sockets API December 2006
4764 La Monte H.P. Yarroll
4767 Pittsburgh, PA 15222
4771 Email: piggy@acm.org
4775 Sun Microsystems, Inc.
4777 Santa Clara, CA 95054
4781 Email: kacheong.poon@sun.com
4785 Univ. of Applied Sciences Muenster
4790 Email: tuexen@fh-muenster.de
4815 Stewart, et al. Expires June 14, 2007 [Page 86]
4817 Internet-Draft SCTP sockets API December 2006
4820 Full Copyright Statement
4822 Copyright (C) The IETF Trust (2006).
4824 This document is subject to the rights, licenses and restrictions
4825 contained in BCP 78, and except as set forth therein, the authors
4826 retain all their rights.
4828 This document and the information contained herein are provided on an
4829 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
4830 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
4831 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
4832 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
4833 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
4834 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
4837 Intellectual Property
4839 The IETF takes no position regarding the validity or scope of any
4840 Intellectual Property Rights or other rights that might be claimed to
4841 pertain to the implementation or use of the technology described in
4842 this document or the extent to which any license under such rights
4843 might or might not be available; nor does it represent that it has
4844 made any independent effort to identify any such rights. Information
4845 on the procedures with respect to rights in RFC documents can be
4846 found in BCP 78 and BCP 79.
4848 Copies of IPR disclosures made to the IETF Secretariat and any
4849 assurances of licenses to be made available, or the result of an
4850 attempt made to obtain a general license or permission for the use of
4851 such proprietary rights by implementers or users of this
4852 specification can be obtained from the IETF on-line IPR repository at
4853 http://www.ietf.org/ipr.
4855 The IETF invites any interested party to bring to its attention any
4856 copyrights, patents or patent applications, or other proprietary
4857 rights that may cover technology that may be required to implement
4858 this standard. Please address the information to the IETF at
4864 Funding for the RFC Editor function is provided by the IETF
4865 Administrative Support Activity (IASA).
4871 Stewart, et al. Expires June 14, 2007 [Page 87]
projects / platform / upstream / lksctp-tools.git / blob