draft-ietf-tsvwg-sctpsocket-22.txt   draft-ietf-tsvwg-sctpsocket-23.txt 
Network Working Group R. Stewart Network Working Group R. Stewart
Internet-Draft Huawei Internet-Draft Huawei
Intended status: Informational K. Poon Intended status: Informational K. Poon
Expires: September 8, 2010 Sun Microsystems, Inc. Expires: January 13, 2011 Oracle Corporation
M. Tuexen M. Tuexen
Muenster Univ. of Applied Sciences Muenster Univ. of Applied Sciences
V. Yasevich V. Yasevich
HP HP
P. Lei P. Lei
Cisco Systems, Inc. Cisco Systems, Inc.
March 7, 2010 July 12, 2010
Sockets API Extensions for Stream Control Transmission Protocol (SCTP) Sockets API Extensions for Stream Control Transmission Protocol (SCTP)
draft-ietf-tsvwg-sctpsocket-22.txt draft-ietf-tsvwg-sctpsocket-23.txt
Abstract Abstract
This document describes a mapping of the Stream Control Transmission This document describes a mapping of the Stream Control Transmission
Protocol SCTP into a sockets API. The benefits of this mapping Protocol SCTP into a sockets API. The benefits of this mapping
include compatibility for TCP applications, access to new SCTP include compatibility for TCP applications, access to new SCTP
features and a consolidated error and event notification scheme. features and a consolidated error and event notification scheme.
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF). Note that other groups may also distribute
other groups may also distribute working documents as Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at This Internet-Draft will expire on January 13, 2011.
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 8, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
skipping to change at page 2, line 15 skipping to change at page 2, line 9
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the BSD License. described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this 10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process. modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 7
2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 7 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8
3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 7 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8
3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 9
3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 11
3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 10 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 11
3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 12 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 13 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 14
3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 13 3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14
3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14 3.3. Special considerations . . . . . . . . . . . . . . . . . . 15
3.4. Special considerations . . . . . . . . . . . . . . . . . . 15
4. One-to-One Style Interface . . . . . . . . . . . . . . . . . . 16 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . . 16
4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 16 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 17
4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 17 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . . 17
4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 18 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . . 18
4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 19 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . . 19
4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . . 19 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . . 19
4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 20 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 20
4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 21 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 21
4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . . 21 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . . 21
4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 22 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 22
4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 22 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 22
5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 23 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 23
5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 23 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 23
5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 24 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 24
5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 24 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 25
5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 25 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 26
5.2.3. Extended SCTP Header Information Structure 5.2.3. Extended SCTP Header Information Structure
(SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 28 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 28
5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) . . . . 29 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) . . . . 29
5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 31 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) . . 31
5.2.6. SCTP Next Receive Information Structure 5.2.6. SCTP Next Receive Information Structure
(SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . . 32 (SCTP_NXTINFO) . . . . . . . . . . . . . . . . . . . . 32
5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . . 32 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) . . . 32
5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) . . . 33 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) . . . 33
5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 33 5.2.9. SCTP Destination Address Structure (IPv4)
5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 34 (SCTP_DSTADDRV4) . . . . . . . . . . . . . . . . . . . 33
5.3.2. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 35 5.2.10. SCTP Destination Address Structure (IPv6)
(SCTP_DSTADDRV6) . . . . . . . . . . . . . . . . . . . 34
5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 34
5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 35
5.3.2. SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . 36
5.3.3. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 37 5.3.3. SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . 37
5.3.4. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 38 5.3.4. SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . 38
5.3.5. SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . 38 5.3.5. SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . 39
5.3.6. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 39 5.3.6. SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . 40
5.3.7. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . . 40 5.3.7. SCTP_ADAPTATION_INDICATION . . . . . . . . . . . . . . 41
5.3.8. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 41 5.3.8. SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . 42
5.3.9. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 41 5.3.9. SCTP_AUTHENTICATION_EVENT . . . . . . . . . . . . . . 42
5.3.10. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 42 5.3.10. SCTP_SENDER_DRY_EVENT . . . . . . . . . . . . . . . . 43
5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . . 43 5.3.11. SCTP_NOTIFICATIONS_STOPPED_EVENT . . . . . . . . . . . 44
5.4. Ancillary Data Considerations and Semantics . . . . . . . 43 5.3.12. SCTP_SEND_FAILED_EVENT . . . . . . . . . . . . . . . . 44
5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 43 5.4. Ancillary Data Considerations and Semantics . . . . . . . 45
5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 43 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 45
5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 44 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 46
6. Common Operations for Both Styles . . . . . . . . . . . . . . 45 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 46
6.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . . 45 6. Common Operations for Both Styles . . . . . . . . . . . . . . 47
6.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 47 6.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . . 47
6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 48 6.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 49
6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 48 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 50
7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 49 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 50
7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 50 6.5. Implicit Association Setup . . . . . . . . . . . . . . . . 51
7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 50 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 52
7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 51 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 54
7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 53 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 54
7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 53 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 54
7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 53 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 56
7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 54 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 56
7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 54 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 57
7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . . 54 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 57
7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 54 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 57
7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . . 57
7.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 58
7.1.10. Set Adaptation Layer Indicator 7.1.10. Set Adaptation Layer Indicator
(SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 55 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 58
7.1.11. Enable/Disable Message Fragmentation 7.1.11. Enable/Disable Message Fragmentation
(SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 55 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 58
7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 55 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 58
7.1.13. Set Default Send Parameters 7.1.13. Set Default Send Parameters
(SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 58 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 61
7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) . 58 7.1.14. Set Notification and Ancillary Events (SCTP_EVENTS) . 61
7.1.15. Set/Clear IPv4 Mapped Addresses 7.1.15. Set/Clear IPv4 Mapped Addresses
(SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 58 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 61
7.1.16. Get or Set the Maximum Fragmentation Size 7.1.16. Get or Set the Maximum Fragmentation Size
(SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 58 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 61
7.1.17. Get or Set the List of Supported HMAC Identifiers 7.1.17. Get or Set the List of Supported HMAC Identifiers
(SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 59 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 62
7.1.18. Get or Set the Active Shared Key 7.1.18. Get or Set the Active Shared Key
(SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 60 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 63
7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 60 7.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 63
7.1.20. Get or Set Fragmented Interleave 7.1.20. Get or Set Fragmented Interleave
(SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 61 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 64
7.1.21. Set or Get the SCTP Partial Delivery Point 7.1.21. Set or Get the SCTP Partial Delivery Point
(SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 62 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 65
7.1.22. Set or Get the Use of Extended Receive Info 7.1.22. Set or Get the Use of Extended Receive Info
(SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 63 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 66
7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . . 63 7.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . . 66
7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 63 7.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 66
7.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 64 7.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 67
7.1.26. Enable or Disable Explicit EOR Marking 7.1.26. Enable or Disable Explicit EOR Marking
(SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 64 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 67
7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . . 64 7.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . . 67
7.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 65 7.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 68
7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 65 7.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as
7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 65 Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 68
7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 66 7.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as
Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 68
7.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . . 68
7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 68
7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 69
7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 70
7.2.3. Get the List of Chunks the Peer Requires to be 7.2.3. Get the List of Chunks the Peer Requires to be
Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 67 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 71
7.2.4. Get the List of Chunks the Local Endpoint Requires 7.2.4. Get the List of Chunks the Local Endpoint Requires
to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 68 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 71
7.2.5. Get the Current Number of Associations 7.2.5. Get the Current Number of Associations
(SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 68 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 72
7.2.6. Get the Current Identifiers of Associations 7.2.6. Get the Current Identifiers of Associations
(SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 68 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 72
7.3. Write-Only Options . . . . . . . . . . . . . . . . . . . . 69 7.3. Write-Only Options . . . . . . . . . . . . . . . . . . . . 72
7.3.1. Set Peer Primary Address 7.3.1. Set Peer Primary Address
(SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 69 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 72
7.3.2. Add a Chunk That Must Be Authenticated 7.3.2. Add a Chunk That Must Be Authenticated
(SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 69 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 73
7.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . . 70 7.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . . 73
7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . . 70 7.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . . 74
7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . . 71 7.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . . 74
7.4. Ancillary Data and Notification Interest Options . . . . . 71 7.4. Ancillary Data and Notification Interest Options . . . . . 75
8. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 74 8. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 78
8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 75 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 78
8.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . . 76 8.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . . 80
8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 77 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 80
8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 77 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 81
8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 78 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 81
8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 78 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 82
8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 78 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 82
8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 79 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 83
8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 80 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 84
8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 81 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 85
8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 82 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 86
8.12. sctp_getaddrlen() . . . . . . . . . . . . . . . . . . . . 83 8.12. sctp_recvxxx() . . . . . . . . . . . . . . . . . . . . . . 87
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83 8.13. sctp_sendxxx() . . . . . . . . . . . . . . . . . . . . . . 88
10. Security Considerations . . . . . . . . . . . . . . . . . . . 83 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 89
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 84 10. Security Considerations . . . . . . . . . . . . . . . . . . . 89
12. Normative References . . . . . . . . . . . . . . . . . . . . . 84 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 89
Appendix A. One-to-One Style Code Example . . . . . . . . . . . . 85 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 90 12.1. Normative References . . . . . . . . . . . . . . . . . . . 90
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 91 12.2. Informative References . . . . . . . . . . . . . . . . . . 90
Appendix A. One-to-One Style Code Example . . . . . . . . . . . . 90
Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 96
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 97
1. Introduction 1. Introduction
The sockets API has provided a standard mapping of the Internet The sockets API has provided a standard mapping of the Internet
Protocol suite to many operating systems. Both TCP [RFC0793] and UDP Protocol suite to many operating systems. Both TCP [RFC0793] and UDP
[RFC0768] have benefited from this standard representation and access [RFC0768] have benefited from this standard representation and access
method across many diverse platforms. SCTP is a new protocol that method across many diverse platforms. SCTP is a new protocol that
provides many of the characteristics of TCP but also incorporates provides many of the characteristics of TCP but also incorporates
semantics more akin to UDP. This document defines a method to map semantics more akin to UDP. This document defines a method to map
the existing sockets API for use with SCTP, providing both a base for the existing sockets API for use with SCTP, providing both a base for
skipping to change at page 6, line 35 skipping to change at page 7, line 35
which can communicate with many peer endpoints. Each of these which can communicate with many peer endpoints. Each of these
associations is assigned an association ID so that an application associations is assigned an association ID so that an application
can use the ID to differentiate them. Note that SCTP is can use the ID to differentiate them. Note that SCTP is
connection-oriented in nature, and it does not support broadcast connection-oriented in nature, and it does not support broadcast
or multicast communications, as UDP does. or multicast communications, as UDP does.
3. Support a one-to-one style interface: This interface supports a 3. Support a one-to-one style interface: This interface supports a
similar semantics as sockets for connection-oriented protocols, similar semantics as sockets for connection-oriented protocols,
such as TCP. A one-to-one style SCTP socket should only control such as TCP. A one-to-one style SCTP socket should only control
one SCTP association. One purpose of defining this interface is one SCTP association. One purpose of defining this interface is
to allow existing applications built on other connection-oriented to allow existing applications built on other connection-oriented
protocols be ported to use SCTP with very little effort. And protocols be ported to use SCTP with very little effort.
developers familiar with those semantics can easily adapt to Developers familiar with these semantics can easily adapt to
SCTP. Another purpose is to make sure that existing mechanisms SCTP. Another purpose is to make sure that existing mechanisms
in most operating systems dealing with sockets, such as select(), in most operating systems that support sockets, such as select(),
should continue to work with this style of socket. Extensions should continue to work with this style of socket. Extensions
are added to this mapping to provide mechanisms to exploit new are added to this mapping to provide mechanisms to exploit new
features of SCTP. features of SCTP.
Goals 2 and 3 are not compatible, so in this document we define two Goals 2 and 3 are not compatible, so this document defines two modes
modes of mapping, namely the one-to-many style mapping and the one- of mapping, namely the one-to-many style mapping and the one-to-one
to-one style mapping. These two modes share some common data style mapping. These two modes share some common data structures and
structures and operations, but will require the use of two different operations, but will require the use of two different application
application programming styles. Note that all new SCTP features can programming styles. Note that all new SCTP features can be used with
be used with both styles of socket. The decision on which one to use both styles of socket. The decision on which one to use depends
depends mainly on the nature of applications. mainly on the nature of applications.
A mechanism is defined to extract a one-to-many style SCTP A mechanism is defined to extract a one-to-many style SCTP
association into a one-to-one style socket. association into a one-to-one style socket.
Some of the SCTP mechanisms cannot be adequately mapped to an Some of the SCTP mechanisms cannot be adequately mapped to an
existing socket interface. In some cases, it is more desirable to existing socket interface. In some cases, it is more desirable to
have a new interface instead of using existing socket calls. have a new interface instead of using existing socket calls.
Section 8 of this document describes those new interfaces. Section 8 of this document describes these new interfaces.
2. Data Types 2. Data Types
Whenever possible, data types from Draft 6.6 (March 1997) of POSIX Whenever possible, data types from Draft 6.6 (March 1997) of POSIX
1003.1g are used: uintN_t means an unsigned integer of exactly N bits 1003.1g are used: uintN_t means an unsigned integer of exactly N bits
(e.g. uint16_t). We also assume the argument data types from 1003.1g (e.g. uint16_t). This document also assumes the argument data types
when possible (e.g. the final argument to setsockopt() is a size_t from 1003.1g when possible (e.g. the final argument to setsockopt()
value). Whenever buffer sizes are specified, the POSIX 1003.1 size_t is a size_t value). Whenever buffer sizes are specified, the POSIX
data type is used. 1003.1 size_t data type is used.
3. One-to-Many Style Interface 3. One-to-Many Style Interface
The one-to-many style interface has the following characteristics: The one-to-many style interface has the following characteristics:
o Outbound association setup is implicit. o Outbound association setup is implicit.
o Messages are delivered in complete messages (with one notable o Messages are delivered in complete messages (with one notable
exception). exception).
o There is a 1 to MANY relationship between socket and association. o There is a 1 to many relationship between socket and association.
3.1. Basic Operation 3.1. Basic Operation
A typical server in this style uses the following socket calls in A typical server in this style uses the following socket calls in
sequence to prepare an endpoint for servicing requests: sequence to prepare an endpoint for servicing requests:
o socket() o socket()
o bind() o bind()
o listen() o listen()
o recvmsg() o recvmsg()
o sendmsg() o sendmsg()
skipping to change at page 8, line 34 skipping to change at page 9, line 34
functions for message passing. See Section 8.2 for more on branched- functions for message passing. See Section 8.2 for more on branched-
off associations. The returned socket is a one-to-one style socket. off associations. The returned socket is a one-to-one style socket.
Once an association is branched off to a separate socket, it becomes Once an association is branched off to a separate socket, it becomes
completely separated from the original socket. All subsequent completely separated from the original socket. All subsequent
control and data operations to that association must be done through control and data operations to that association must be done through
the new socket. For example, the close operation on the original the new socket. For example, the close operation on the original
socket will not terminate any associations that have been branched socket will not terminate any associations that have been branched
off to a different socket. off to a different socket.
We will discuss the one-to-many style socket calls in more detail in One-to-many style socket calls are discussed in more detail in the
the following subsections. following subsections.
3.1.1. socket() 3.1.1. socket()
Applications use socket() to create a socket descriptor to represent Applications use socket() to create a socket descriptor to represent
an SCTP endpoint. an SCTP endpoint.
The function prototype is The function prototype is
int socket(int domain, int socket(int domain,
int type, int type,
skipping to change at page 10, line 36 skipping to change at page 11, line 36
sd: The socket descriptor of the endpoint. sd: The socket descriptor of the endpoint.
backlog: If backlog is non-zero, enable listening else disable backlog: If backlog is non-zero, enable listening else disable
listening. listening.
Note that one-to-many style socket consumers do not need to call Note that one-to-many style socket consumers do not need to call
accept to retrieve new associations. Calling accept() on a one-to- accept to retrieve new associations. Calling accept() on a one-to-
many style socket should return EOPNOTSUPP. Rather, new associations many style socket should return EOPNOTSUPP. Rather, new associations
are accepted automatically, and notifications of the new associations are accepted automatically, and notifications of the new associations
are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if
these notifications are enabled). Clients will typically not call these notifications are enabled). Clients will typically not call
listen(), so that they can be assured that the only associations on listen(), so that they can be assured that only actively initiated
the socket will be the ones those actively initiated. Server or associations are on the socket. Server or peer-to-peer sockets, on
peer-to-peer sockets, on the other hand, will always accept new the other hand, will always accept new associations, so a well-
associations, so a well-written application using server one-to-many written application using server one-to-many style sockets must be
style sockets must be prepared to handle new associations from prepared to handle new associations from unwanted peers.
unwanted peers.
Also note that the SCTP_ASSOC_CHANGE event provides the association Also note that the SCTP_ASSOC_CHANGE event provides the association
ID for a new association, so if applications wish to use the ID for a new association, so if applications wish to use the
association ID as input to other socket calls, they should ensure association ID as input to other socket calls, they should ensure
that the SCTP_ASSOC_CHANGE event is enabled. that the SCTP_ASSOC_CHANGE event is enabled.
3.1.4. sendmsg() and recvmsg() 3.1.4. sendmsg() and recvmsg()
An application uses the sendmsg() and recvmsg() call to transmit data An application uses the sendmsg() and recvmsg() call to transmit data
to and receive data from its peer. to and receive data from its peer.
skipping to change at page 11, line 37 skipping to change at page 12, line 37
data is used to specify the sent behavior, such as the SCTP stream data is used to specify the sent behavior, such as the SCTP stream
number to use. When receiving, the ancillary data is used to number to use. When receiving, the ancillary data is used to
describe the received data, such as the SCTP stream sequence number describe the received data, such as the SCTP stream sequence number
of the message. of the message.
When sending user data with sendmsg(), the msg_name field in the When sending user data with sendmsg(), the msg_name field in the
msghdr structure will be filled with one of the transport addresses msghdr structure will be filled with one of the transport addresses
of the intended receiver. If there is no existing association of the intended receiver. If there is no existing association
between the sender and the intended receiver, the sender's SCTP stack between the sender and the intended receiver, the sender's SCTP stack
will set up a new association and then send the user data (see will set up a new association and then send the user data (see
Section 3.2 for more on implicit association setup). If sendmsg() is Section 6.5 for more on implicit association setup). If sendmsg() is
called with no data and there is no existing assocation, a new one called with no data and there is no existing association, a new one
will be established. The SCTP_INIT type ancillary data can be used will be established. The SCTP_INIT type ancillary data can be used
to change some of the parameters used to set up a new association. to change some of the parameters used to set up a new association.
If sendmsg() is called with NULL data, and there is no existing If sendmsg() is called with NULL data, and there is no existing
association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is
retured and errno is set to EINVAL. Sending a message using retured and errno is set to EINVAL. Sending a message using
sendmsg() is atomic unless explicit EOR marking is enabled on the sendmsg() is atomic unless explicit EOR marking is enabled on the
socket specified by sd (see Section 7.1.26). socket specified by sd (see Section 7.1.26).
If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will
be delivered if that notification has been enabled, and no more data be delivered if that notification has been enabled, and no more data
skipping to change at page 12, line 39 skipping to change at page 13, line 39
one-to-many model sockets. Please consult Section 7.1.20 for further one-to-many model sockets. Please consult Section 7.1.20 for further
details on message delivery options. details on message delivery options.
Note, if the socket is a branched-off socket that only represents one Note, if the socket is a branched-off socket that only represents one
association (see Section 3.1), the msg_name field can be used to association (see Section 3.1), the msg_name field can be used to
override the primary address when sending data. override the primary address when sending data.
3.1.5. close() 3.1.5. close()
Applications use close() to perform graceful shutdown (as described Applications use close() to perform graceful shutdown (as described
in Section 10.1 of [RFC4960]) on ALL the associations currently in Section 10.1 of [RFC4960]) on all the associations currently
represented by a one-to-many style socket. represented by a one-to-many style socket.
The function prototype is The function prototype is
int close(int sd); int close(int sd);
and the argument is and the argument is
sd: The socket descriptor of the associations to be closed. sd: The socket descriptor of the associations to be closed.
To gracefully shutdown a specific association represented by the one- To gracefully shutdown a specific association represented by the one-
skipping to change at page 13, line 32 skipping to change at page 14, line 32
and the arguments are and the arguments are
sd: The socket descriptor to have a new association added to. sd: The socket descriptor to have a new association added to.
nam: The address structure (struct sockaddr_in for an IPv4 address nam: The address structure (struct sockaddr_in for an IPv4 address
or struct sockaddr_in6 for an IPv6 address, see [RFC3493]). or struct sockaddr_in6 for an IPv6 address, see [RFC3493]).
len: The size of the address. len: The size of the address.
Multiple connect() calls can be made on the same socket to create Multiple connect() calls can be made on the same socket to create
multiple associations. This is different from the semantics of multiple associations. This is different from the semantics of
connect() on a UDP socket. connect() on a UDP socket.
3.2. Implicit Association Setup 3.2. Non-blocking mode
Implicit association setup applies only to one-to-many style sockets.
For one-to-one style sockets implicit association setup must not be
used.
Once the bind() call is complete on a one-to-many style socket, the
application can begin sending and receiving data using the sendmsg()/
recvmsg() or sendto()/recvfrom() calls, without going through any
explicit association setup procedures (i.e., no connect() calls
required).
Whenever sendmsg() or sendto() is called and the SCTP stack at the
sender finds that there is no association existing between the sender
and the intended receiver (identified by the address passed either in
the msg_name field of msghdr structure in the sendmsg() call or the
dest_addr field in the sendto() call), the SCTP stack will
automatically setup an association to the intended receiver.
Upon the successful association setup an SCTP_COMM_UP notification
will be dispatched to the socket at both the sender and receiver
side. This notification can be read by the recvmsg() system call
(see Section 3.1.3).
Note, if the SCTP stack at the sender side supports bundling, the
first user message may be bundled with the COOKIE ECHO message
[RFC4960].
When the SCTP stack sets up a new association implicitly, the
SCTP_INIT type ancillary data may also be passed along (see
Section 5.2.1 for details of the data structures) to change some
parameters used in setting up new association.
If this information is not present in the sendmsg() call, or if the
implicit association setup is triggered by a sendto() call, the
default association initialization parameters will be used. These
default association parameters may be set with respective
setsockopt() calls or be left to the system defaults.
Implicit association setup cannot be initiated by send() calls.
3.3. Non-blocking mode
Some SCTP users might want to avoid blocking when they call socket Some SCTP application may wish to avoid being blocked when calling a
interface function. socket interface function.
Once a bind() and/or subsequent sctp_bindx() calls are complete on a Once a bind() and/or subsequent sctp_bindx() calls are complete on a
one-to-many style socket, an application may set the non-blocking one-to-many style socket, an application may set the non-blocking
option by a fcntl() (such as O_NONBLOCK). After setting the socket option by a fcntl() (such as O_NONBLOCK). After setting the socket
to non-blocking mode, the sendmsg() function returns immediately. to non-blocking mode, the sendmsg() function returns immediately.
The success or failure of sending the data message (with possible The success or failure of sending the data message (with possible
SCTP_INITMSG ancillary data) will be signaled by the SCTP_INITMSG ancillary data) will be signaled by the
SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or CANT_START_ASSOC. If SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or CANT_START_ASSOC. If
user data could not be sent (due to a CANT_START_ASSOC), the sender user data could not be sent (due to a CANT_START_ASSOC), the sender
will also receive an SCTP_SEND_FAILED event. Events can be received will also receive an SCTP_SEND_FAILED event. Events can be received
by the user calling recvmsg(). A server (having called listen()) is by the user calling recvmsg(). A server (having called listen()) is
also notified of an association up event by the reception of an also notified of an association up event by the reception of an
SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and
possibly the reception of the first data message. possibly the reception of the first data message.
In order to shutdown the association gracefully, the user must call To shutdown the association gracefully, the user must call sendmsg()
sendmsg() with no data and with the SCTP_EOF flag set. The function with no data and with the SCTP_EOF flag set. The function returns
returns immediately, and completion of the graceful shutdown is immediately, and completion of the graceful shutdown is indicated by
indicated by an SCTP_ASSOC_CHANGE notification of type an SCTP_ASSOC_CHANGE notification of type SHUTDOWN_COMPLETE (see
SHUTDOWN_COMPLETE (see Section 5.3.2). Note that this can also be Section 5.3.2). Note that this can also be done using the
done using the sctp_send() call described in Section 8.10. sctp_send() call described in Section 8.10.
An application is recommended to use caution when using select() (or An application is recommended to use caution when using select() (or
poll()) for writing on a one-to-many style socket. The reason being poll()) for writing on a one-to-many style socket. The reason being
that the interpretation of select on write is implementation that the interpretation of select on write is implementation
specific. Generally a positive return on a select on write would specific. Generally a positive return on a select on write would
only indicate that one of the associations represented by the one-to- only indicate that one of the associations represented by the one-to-
many socket is writable. An application that writes after the many socket is writable. An application that writes after the
select() returns may still block since the association that was select() returns may still block since the association that was
writeable is not the destination association of the write call. writeable is not the destination association of the write call.
Likewise select() (or poll()) for reading from a one-to-many socket Likewise select() (or poll()) for reading from a one-to-many socket
will only return an indication that one of the associations will only return an indication that one of the associations
represented by the socket has data to be read. represented by the socket has data to be read.
An application that wishes to know that a particular association is An application that wishes to know that a particular association is
ready for reading or writing should either use the one-to-one style ready for reading or writing should either use the one-to-one style
or use the sctp_peeloff() (see Section 8.2) function to separate the or use the sctp_peeloff() (see Section 8.2) function to separate the
association of interest from the one-to-many socket. association of interest from the one-to-many socket.
3.4. Special considerations 3.3. Special considerations
The fact that a one-to-many style socket can provide access to many The fact that a one-to-many style socket can provide access to many
SCTP associations through a single socket descriptor has important SCTP associations through a single socket descriptor has important
implications for both application programmers and system programmers implications for both application programmers and system programmers
implementing this API. A key issue is how buffer space inside the implementing this API. A key issue is how buffer space inside the
sockets layer is managed. Because this implementation detail sockets layer is managed. Because this implementation detail
directly affects how application programmers must write their code to directly affects how application programmers must write their code to
ensure correct operation and portability, this section provides some ensure correct operation and portability, this section provides some
guidance to both implementers and application programmers. guidance to both implementers and application programmers.
skipping to change at page 15, line 47 skipping to change at page 16, line 6
the socket layer until it uses all of its socket buffer space the socket layer until it uses all of its socket buffer space
allocation creating a "stalled connection". Further attempts to allocation creating a "stalled connection". Further attempts to
write to the socket will block or return the error EAGAIN or write to the socket will block or return the error EAGAIN or
EWOULDBLOCK for a non-blocking socket. At some point, either the EWOULDBLOCK for a non-blocking socket. At some point, either the
connection is closed, or the receiver begins to read again freeing connection is closed, or the receiver begins to read again freeing
space in the output queue. space in the output queue.
For one-to-one style SCTP sockets (this includes sockets descriptors For one-to-one style SCTP sockets (this includes sockets descriptors
that were separated from a one-to-many style socket with that were separated from a one-to-many style socket with
sctp_peeloff()) the behavior is identical. For one-to-many style sctp_peeloff()) the behavior is identical. For one-to-many style
SCTP sockets, the fact that we have multiple associations on a single SCTP sockets there are multiple associations for a single socket,
socket makes the situation more complicated. If the implementation which makes the situation more complicated. If the implementation
uses a single buffer space allocation shared by all associations, a uses a single buffer space allocation shared by all associations, a
single stalled association can prevent the further sending of data on single stalled association can prevent the further sending of data on
all associations active on a particular one-to-many style socket. all associations active on a particular one-to-many style socket.
For a blocking socket, it should be clear that a single stalled For a blocking socket, it should be clear that a single stalled
association can block the entire socket. For this reason, association can block the entire socket. For this reason,
application programmers may want to use non-blocking one-to-many application programmers may want to use non-blocking one-to-many
style sockets. The application should at least be able to send style sockets. The application should at least be able to send
messages to the non-stalled associations. messages to the non-stalled associations.
skipping to change at page 16, line 27 skipping to change at page 16, line 34
The API implementer can solve this problem by providing each The API implementer can solve this problem by providing each
association with its own allocation of outbound buffer space. Each association with its own allocation of outbound buffer space. Each
association should conceptually have as much buffer space as it would association should conceptually have as much buffer space as it would
have if it had its own socket. As a bonus, this simplifies the have if it had its own socket. As a bonus, this simplifies the
implementation of sctp_peeloff(). implementation of sctp_peeloff().
To ensure that a given stalled association will not prevent other To ensure that a given stalled association will not prevent other
non-stalled associations from being writable, application programmers non-stalled associations from being writable, application programmers
should either: should either:
o demand that the underlying implementation dedicates independent o demand that the underlying implementation dedicates independent
buffer space allotments to each association (as suggested above), buffer space reservation to each association (as suggested above),
or or
o verify that their application layer protocol does not permit large o verify that their application layer protocol does not permit large
amounts of unread data at the receiver (this is true of some amounts of unread data at the receiver (this is true of some
request-response protocols, for example), or request-response protocols, for example), or
o use one-to-one style sockets for association which may potentially o use one-to-one style sockets for association which may potentially
stall (either from the beginning, or by using sctp_peeloff before stall (either from the beginning, or by using sctp_peeloff before
sending large amounts of data that may cause a stalled condition). sending large amounts of data that may cause a stalled condition).
4. One-to-One Style Interface 4. One-to-One Style Interface
The goal of this style is to follow as closely as possible the The goal of this style is to follow as closely as possible the
current practice of using the sockets interface for a connection current practice of using the sockets interface for a connection
oriented protocol, such as TCP. This style enables existing oriented protocol, such as TCP. This style enables existing
applications using connection oriented protocols to be ported to SCTP applications using connection oriented protocols to be ported to SCTP
with very little effort. with very little effort.
One-to-one style sockets can be connected (explicitly or implicitly)
at most once, simular to TCP sockets.
Note that some new SCTP features and some new SCTP socket options can Note that some new SCTP features and some new SCTP socket options can
only be utilized through the use of sendmsg() and recvmsg() calls, only be utilized through the use of sendmsg() and recvmsg() calls,
see Section 4.1.8. see Section 4.1.8.
4.1. Basic Operation 4.1. Basic Operation
A typical server in one-to-one style uses the following system call A typical server in one-to-one style uses the following system call
sequence to prepare an SCTP endpoint for servicing requests: sequence to prepare an SCTP endpoint for servicing requests:
o socket() o socket()
o bind() o bind()
o listen() o listen()
o accept() o accept()
The accept() call blocks until a new association is set up. It The accept() call blocks until a new association is set up. It
returns with a new socket descriptor. The server then uses the new returns with a new socket descriptor. The server then uses the new
socket descriptor to communicate with the client, using recv() and socket descriptor to communicate with the client, using recv() and
send() calls to get requests and send back responses. send() calls to get requests and send back responses.
skipping to change at page 18, line 49 skipping to change at page 19, line 10
If the IP address part of addr is specified as a wildcard (INADDR_ANY If the IP address part of addr is specified as a wildcard (INADDR_ANY
for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an for an IPv4 address, or as IN6ADDR_ANY_INIT or in6addr_any for an
IPv6 address), the operating system will associate the endpoint with IPv6 address), the operating system will associate the endpoint with
an optimal address set of the available interfaces. If the IPv4 an optimal address set of the available interfaces. If the IPv4
sin_port or IPv6 sin6_port is set to 0, the operating system will sin_port or IPv6 sin6_port is set to 0, the operating system will
choose an ephemeral port for the endpoint. choose an ephemeral port for the endpoint.
If a bind() is not called prior to the connect() call, the system If a bind() is not called prior to the connect() call, the system
picks an ephemeral port and will choose an address set equivalent to picks an ephemeral port and will choose an address set equivalent to
binding with a wildcard address. One of those addresses will be the binding with a wildcard address. One of these addresses will be the
primary address for the association. This automatically enables the primary address for the association. This automatically enables the
multi-homing capability of SCTP. multi-homing capability of SCTP.
The completion of this bind() process does not ready the SCTP The completion of this bind() process does not ready the SCTP
endpoint to accept inbound SCTP association requests. Until a endpoint to accept inbound SCTP association requests. Until a
listen() system call, described below, is performed on the socket, listen() system call, described below, is performed on the socket,
the SCTP endpoint will promptly reject an inbound SCTP INIT request the SCTP endpoint will promptly reject an inbound SCTP INIT request
with an SCTP ABORT. with an SCTP ABORT.
4.1.3. listen() 4.1.3. listen()
skipping to change at page 20, line 32 skipping to change at page 20, line 41
section 10.1 of [RFC4960]. section 10.1 of [RFC4960].
The number of outbound streams the new association has is stack The number of outbound streams the new association has is stack
dependent. Applications can use the SCTP_INITMSG option described in dependent. Applications can use the SCTP_INITMSG option described in
Section 7.1.3 should be used before connecting to change the number Section 7.1.3 should be used before connecting to change the number
of outbound streams. of outbound streams.
If a bind() is not called prior to the connect() call, the system If a bind() is not called prior to the connect() call, the system
picks an ephemeral port and will choose an address set equivalent to picks an ephemeral port and will choose an address set equivalent to
binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket binding with INADDR_ANY and IN6ADDR_ANY_INIT for IPv4 and IPv6 socket
respectively. One of those addresses will be the primary address for respectively. One of the addresses will be the primary address for
the association. This automatically enables the multi-homing the association. This automatically enables the multi-homing
capability of SCTP. capability of SCTP.
Note that SCTP allows data exchange, similar to T/TCP [RFC1644], Note that SCTP allows data exchange, similar to T/TCP [RFC1644],
during the association set up phase. If an application wants to do during the association set up phase. If an application wants to do
this, it cannot use the connect() call. Instead, it should use this, it cannot use the connect() call. Instead, it should use
sendto() or sendmsg() to initiate an association. If it uses sendto() or sendmsg() to initiate an association. If it uses
sendto() and it wants to change the initialization behavior, it needs sendto() and it wants to change the initialization behavior, it needs
to use the SCTP_INITMSG socket option before calling sendto(). Or it to use the SCTP_INITMSG socket option before calling sendto(). Or it
can use sendmsg() with SCTP_INIT type ancillary data to initiate an can use sendmsg() with SCTP_INIT type ancillary data to initiate an
skipping to change at page 23, line 7 skipping to change at page 23, line 17
IPv4. If the socket is an IPv6 socket, the address will be either IPv4. If the socket is an IPv6 socket, the address will be either
an IPv6 or IPv4 address. an IPv6 or IPv4 address.
len: The caller should set the length of address here. On return, len: The caller should set the length of address here. On return,
this is set to the length of the returned address. this is set to the length of the returned address.
If the actual length of the address is greater than the length of the If the actual length of the address is greater than the length of the
supplied sockaddr structure, the stored address will be truncated. supplied sockaddr structure, the stored address will be truncated.
5. Data Structures 5. Data Structures
In this section we discuss important data structures which are This section discusses important data structures which are specific
specific to SCTP and are used with sendmsg() and recvmsg() calls to to SCTP and are used with sendmsg() and recvmsg() calls to control
control SCTP endpoint operations and to access ancillary information SCTP endpoint operations and to access ancillary information and
and notifications. notifications.
5.1. The msghdr and cmsghdr Structures 5.1. The msghdr and cmsghdr Structures
The msghdr structure used in the sendmsg() and recvmsg() calls, as The msghdr structure used in the sendmsg() and recvmsg() calls, as
well as the ancillary data carried in the structure, is the key for well as the ancillary data carried in the structure, is the key for
the application to set and get various control information from the the application to set and get various control information from the
SCTP endpoint. SCTP endpoint.
The msghdr and the related cmsghdr structures are defined and The msghdr and the related cmsghdr structures are defined and
discussed in detail in [RFC3542]. Here we will cite their discussed in detail in [RFC3542]. They are defined as:
definitions from [RFC3542].
The msghdr structure:
struct msghdr { struct msghdr {
void *msg_name; /* ptr to socket address structure */ void *msg_name; /* ptr to socket address structure */
socklen_t msg_namelen; /* size of socket address structure */ socklen_t msg_namelen; /* size of socket address structure */
struct iovec *msg_iov; /* scatter/gather array */ struct iovec *msg_iov; /* scatter/gather array */
size_t msg_iovlen; /* # elements in msg_iov */ size_t msg_iovlen; /* # elements in msg_iov */
void *msg_control; /* ancillary data */ void *msg_control; /* ancillary data */
socklen_t msg_controllen; /* ancillary data buffer length */ socklen_t msg_controllen; /* ancillary data buffer length */
int msg_flags; /* flags on received message */ int msg_flags; /* flags on received message */
}; };
and the cmsghdr structure:
struct cmsghdr { struct cmsghdr {
socklen_t cmsg_len; /* #bytes, including this header */ socklen_t cmsg_len; /* #bytes, including this header */
int cmsg_level; /* originating protocol */ int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */ int cmsg_type; /* protocol-specific type */
/* followed by unsigned char cmsg_data[]; */ /* followed by unsigned char cmsg_data[]; */
}; };
In the msghdr structure, the usage of msg_name has been discussed in In the msghdr structure, the usage of msg_name has been discussed in
previous sections (see Section 3.1.3 and Section 4.1.8). previous sections (see Section 3.1.3 and Section 4.1.8).
skipping to change at page 25, line 11 skipping to change at page 25, line 17
This cmsghdr structure provides information for initializing new SCTP This cmsghdr structure provides information for initializing new SCTP
associations with sendmsg(). The SCTP_INITMSG socket option uses associations with sendmsg(). The SCTP_INITMSG socket option uses
this same data structure. This structure is not used for recvmsg(). this same data structure. This structure is not used for recvmsg().
+--------------+-----------+---------------------+ +--------------+-----------+---------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+-----------+---------------------+ +--------------+-----------+---------------------+
| IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg | | IPPROTO_SCTP | SCTP_INIT | struct sctp_initmsg |
+--------------+-----------+---------------------+ +--------------+-----------+---------------------+
Here is the definition of the sctp_initmsg structure: The sctp_initmsg structure is defined below:
struct sctp_initmsg { struct sctp_initmsg {
uint16_t sinit_num_ostreams; uint16_t sinit_num_ostreams;
uint16_t sinit_max_instreams; uint16_t sinit_max_instreams;
uint16_t sinit_max_attempts; uint16_t sinit_max_attempts;
uint16_t sinit_max_init_timeo; uint16_t sinit_max_init_timeo;
}; };
sinit_num_ostreams: This is an integer number representing the sinit_num_ostreams: This is an integer number representing the
number of streams that the application wishes to be able to send number of streams that the application wishes to be able to send
skipping to change at page 26, line 4 skipping to change at page 26, line 10
'RTO.Max'. This value must not influence 'RTO.Max' during data 'RTO.Max'. This value must not influence 'RTO.Max' during data
transmission and is only used to bound the initial setup time. A transmission and is only used to bound the initial setup time. A
default value of 0 indicates to use the endpoints default value. default value of 0 indicates to use the endpoints default value.
This is normally set to the system's 'RTO.Max' value (60 seconds). This is normally set to the system's 'RTO.Max' value (60 seconds).
5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV)
This cmsghdr structure specifies SCTP options for sendmsg() and This cmsghdr structure specifies SCTP options for sendmsg() and
describes SCTP header information about a received message through describes SCTP header information about a received message through
recvmsg(). This structure mixes the send and receive path. recvmsg(). This structure mixes the send and receive path.
SCTP_SNDINFO described in Section 5.2.4 and SCTP_RCVINFO described in SCTP_SNDINFO described in Section 5.2.4 and SCTP_RCVINFO described in
Section 5.2.5 split this information. These structures should be Section 5.2.5 split this information. These structures should be
used, when possible, since SCTP_SNDRCV might be deprecated in the used, when possible, since SCTP_SNDRCV is deprecated.
future.
+--------------+-------------+------------------------+ +--------------+-------------+------------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+-------------+------------------------+ +--------------+-------------+------------------------+
| IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo | | IPPROTO_SCTP | SCTP_SNDRCV | struct sctp_sndrcvinfo |
+--------------+-------------+------------------------+ +--------------+-------------+------------------------+
Here is the definition of sctp_sndrcvinfo: The sctp_sndrcvinfo structure is defined below:
struct sctp_sndrcvinfo { struct sctp_sndrcvinfo {
uint16_t sinfo_stream; uint16_t sinfo_stream;
uint16_t sinfo_ssn; uint16_t sinfo_ssn;
uint16_t sinfo_flags; uint16_t sinfo_flags;
uint32_t sinfo_ppid; uint32_t sinfo_ppid;
uint32_t sinfo_context; uint32_t sinfo_context;
uint32_t sinfo_pr_value; uint32_t sinfo_pr_value;
uint32_t sinfo_tsn; uint32_t sinfo_tsn;
uint32_t sinfo_cumtsn; uint32_t sinfo_cumtsn;
skipping to change at page 28, line 27 skipping to change at page 28, line 34
SCTP_NXTINFO described in Section 5.2.6 should be used when possible, SCTP_NXTINFO described in Section 5.2.6 should be used when possible,
since SCTP_EXTRCV is considered deprecated. since SCTP_EXTRCV is considered deprecated.
+--------------+-------------+------------------------+ +--------------+-------------+------------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+-------------+------------------------+ +--------------+-------------+------------------------+
| IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo | | IPPROTO_SCTP | SCTP_EXTRCV | struct sctp_extrcvinfo |
+--------------+-------------+------------------------+ +--------------+-------------+------------------------+
Here is the definition of sctp_extrcvinfo structure: The sctp_extrcvinfo structure is defined below:
struct sctp_extrcvinfo { struct sctp_extrcvinfo {
uint16_t sinfo_stream; uint16_t sinfo_stream;
uint16_t sinfo_ssn; uint16_t sinfo_ssn;
uint16_t sinfo_flags; uint16_t sinfo_flags;
uint32_t sinfo_ppid; uint32_t sinfo_ppid;
uint32_t sinfo_context; uint32_t sinfo_context;
uint32_t sinfo_pr_value; uint32_t sinfo_pr_value;
uint32_t sinfo_tsn; uint32_t sinfo_tsn;
uint32_t sinfo_cumtsn; uint32_t sinfo_cumtsn;
skipping to change at page 29, line 50 skipping to change at page 30, line 5
5.2.4. SCTP Send Information Structure (SCTP_SNDINFO) 5.2.4. SCTP Send Information Structure (SCTP_SNDINFO)
This cmsghdr structure specifies SCTP options for sendmsg(). This cmsghdr structure specifies SCTP options for sendmsg().
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
| IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo | | IPPROTO_SCTP | SCTP_SNDINFO | struct sctp_sndinfo |
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
Here is the definition of the sctp_sndinfo structure: The sctp_sndinfo structure is defined below:
struct sctp_sndinfo { struct sctp_sndinfo {
uint16_t snd_sid; uint16_t snd_sid;
uint16_t snd_flags; uint16_t snd_flags;
uint32_t snd_ppid; uint32_t snd_ppid;
uint32_t snd_context; uint32_t snd_context;
sctp_assoc_t snd_assoc_id; sctp_assoc_t snd_assoc_id;
}; };
snd_sid: This value holds the stream number that the application snd_sid: This value holds the stream number that the application
wishes to send this message to. If a sender specifies an invalid wishes to send this message to. If a sender specifies an invalid
stream number an error indication is returned and the call fails. stream number an error indication is returned and the call fails.
snd_flags: This field may contain any of the following flags and is snd_flags: This field may contain any of the following flags and is
composed of a bitwise OR of these values. composed of a bitwise OR of these values.
SCTP_UNORDERED: This flag requests the un-ordered delivery of the SCTP_UNORDERED: This flag requests the un-ordered delivery of the
message. If this flag is clear the datagram is considered an message. If this flag is clear the datagram is considered an
ordered send. ordered send.
SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the SCTP_ADDR_OVER: This flag, in the one-to-many style, requests the
SCTP stack to override the primary destination address with the SCTP stack to override the primary destination address with the
address found with the sendto/sendmsg call. address found with the sendto()/sendmsg call.
SCTP_ABORT: Setting this flag causes the specified association to SCTP_ABORT: Setting this flag causes the specified association to
abort by sending an ABORT message to the peer (one-to-many abort by sending an ABORT message to the peer (one-to-many
style only). The ABORT chunk will contain an error cause 'User style only). The ABORT chunk will contain an error cause 'User
Initiated Abort' with cause code 12. The cause specific Initiated Abort' with cause code 12. The cause specific
information of this error cause is provided in msg_iov. information of this error cause is provided in msg_iov.
SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown
procedures on the specified association. Graceful shutdown procedures on the specified association. Graceful shutdown
assures that all data queued by both endpoints is successfully assures that all data queued by both endpoints is successfully
transmitted before closing the association (one-to-many style transmitted before closing the association (one-to-many style
only). only).
skipping to change at page 31, line 4 skipping to change at page 31, line 5
For example, if the DATA chunk has to contain a given value in For example, if the DATA chunk has to contain a given value in
network byte order, the SCTP user has to perform the htonl() network byte order, the SCTP user has to perform the htonl()
computation. computation.
snd_context: This value is an opaque 32 bit context datum that is snd_context: This value is an opaque 32 bit context datum that is
used in the sendmsg() function. This value is passed back to the used in the sendmsg() function. This value is passed back to the
upper layer if an error occurs on the send of a message and is upper layer if an error occurs on the send of a message and is
retrieved with each undelivered message (Note: if an endpoint has retrieved with each undelivered message (Note: if an endpoint has
done multiple sends, all of which fail, multiple different done multiple sends, all of which fail, multiple different
sinfo_context values will be returned. One with each user data sinfo_context values will be returned. One with each user data
message). message).
snd_assoc_id: The association handle field, sinfo_assoc_id, holds snd_assoc_id: The association handle field, sinfo_assoc_id, holds
the identifier for the association announced in the SCTP_COMM_UP the identifier for the association announced in the SCTP_COMM_UP
notification. All notifications for a given association have the notification. All notifications for a given association have the
same identifier. Ignored for one-to-one style sockets. same identifier. Ignored for one-to-one style sockets.
An sctp_sndinfo item always corresponds to the data in msg_iov. An sctp_sndinfo item always corresponds to the data in msg_iov.
5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO) 5.2.5. SCTP Receive Information Structure (SCTP_RCVINFO)
This cmsghdr structure describes SCTP header information about a This cmsghdr structure describes SCTP receive information about a
received message through recvmsg(). received message through recvmsg().
To receive this information an application must subscribe to the To enable the delivery of this information an application must use
SCTP_RCV_EVENT using the SCTP_EVENT option (see Section 5.4. the SCTP_RECVRCVINFO socket option (see Section 7.1.29).
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
| IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo | | IPPROTO_SCTP | SCTP_RCVINFO | struct sctp_rcvinfo |
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
Here is the definition of the sctp_rcvinfo structure: The sctp_rcvinfo structure is defined below:
struct sctp_rcvinfo { struct sctp_rcvinfo {
uint16_t rcv_sid; uint16_t rcv_sid;
uint16_t rcv_ssn; uint16_t rcv_ssn;
uint16_t rcv_flags; uint16_t rcv_flags;
uint32_t rcv_ppid; uint32_t rcv_ppid;
uint32_t rcv_tsn; uint32_t rcv_tsn;
uint32_t rcv_cumtsn; uint32_t rcv_cumtsn;
sctp_assoc_t rcv_assoc_id; sctp_assoc_t rcv_assoc_id;
}; };
skipping to change at page 32, line 25 skipping to change at page 32, line 25
the identifier for the association announced in the SCTP_COMM_UP the identifier for the association announced in the SCTP_COMM_UP
notification. All notifications for a given association have the notification. All notifications for a given association have the
same identifier. Ignored for one-to-one style sockets. same identifier. Ignored for one-to-one style sockets.
A sctp_rcvinfo item always corresponds to the data in msg_iov. A sctp_rcvinfo item always corresponds to the data in msg_iov.
5.2.6. SCTP Next Receive Information Structure (SCTP_NXTINFO) 5.2.6. SCTP Next Receive Information Structure (SCTP_NXTINFO)
This cmsghdr structure describes SCTP receive information of the next This cmsghdr structure describes SCTP receive information of the next
message which will be delivered through recvmsg() if this information message which will be delivered through recvmsg() if this information
is available. It uses the same structure as the SCTP Receive is already available when delivering the current message.
Information Structure.
To receive this information an application must subscribe to the It uses the same structure as the SCTP Receive Information Structure.
SCTP_NXT_EVENT using the SCTP_EVENT option (see Section 5.4).
To enable the delivery of this information an application must use
the SCTP_RECVNXTINFO socket option (see Section 7.1.30).
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
| IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_rcvinfo | | IPPROTO_SCTP | SCTP_NXTINFO | struct sctp_rcvinfo |
+--------------+--------------+---------------------+ +--------------+--------------+---------------------+
5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO) 5.2.7. SCTP PR-SCTP Information Structure (SCTP_PRINFO)
This cmsghdr structure specifies SCTP options for sendmsg(). This cmsghdr structure specifies SCTP options for sendmsg().
+--------------+-------------+--------------------+ +--------------+-------------+--------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+-------------+--------------------+ +--------------+-------------+--------------------+
| IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo | | IPPROTO_SCTP | SCTP_PRINFO | struct sctp_prinfo |
+--------------+-------------+--------------------+ +--------------+-------------+--------------------+
Here is the definition of the sctp_prinfo structure: The sctp_prinfo structure is defined below:
struct sctp_prinfo { struct sctp_prinfo {
uint16_t pr_policy; uint16_t pr_policy;
uint32_t pr_value; uint32_t pr_value;
}; };
pr_policy: This specifies which PR-SCTP policy is used. Using pr_policy: This specifies which PR-SCTP policy is used. Using
SCTP_PR_SCTP_NONE results in a reliable transmission. When SCTP_PR_SCTP_NONE results in a reliable transmission. When
SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability" SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliability"
defined in [RFC3758] is used. In this case, the lifetime is defined in [RFC3758] is used. In this case, the lifetime is
provided in pr_value. provided in pr_value.
pr_value: The meaning of this field depends on the PR-SCTP policy pr_value: The meaning of this field depends on the PR-SCTP policy
specified by the sinfo_pr_policy field. It is ignored when specified by the pr_policy field. It is ignored when
SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL the
lifetime in milliseconds is specified. lifetime in milliseconds is specified.
An sctp_prinfo item always corresponds to the data in msg_iov. An sctp_prinfo item always corresponds to the data in msg_iov.
5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO) 5.2.8. SCTP AUTH Information Structure (SCTP_AUTHINFO)
This cmsghdr structure specifies SCTP options for sendmsg(). This cmsghdr structure specifies SCTP options for sendmsg().
+--------------+---------------+----------------------+ +--------------+---------------+----------------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+---------------+----------------------+ +--------------+---------------+----------------------+
| IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo | | IPPROTO_SCTP | SCTP_AUTHINFO | struct sctp_authinfo |
+--------------+---------------+----------------------+ +--------------+---------------+----------------------+
Here is the definition of the sctp_authinfo structure: The sctp_authinfo structure is defined below:
struct sctp_authinfo { struct sctp_authinfo {
uint16_t auth_keyid; uint16_t auth_keyid;
}; };
auth_keyid: This specifies the shared key identifier used for auth_keyid: This specifies the shared key identifier used for
sending the user message. sending the user message.
An sctp_authinfo item always corresponds to the data in msg_iov. An sctp_authinfo item always corresponds to the data in msg_iov.
Please note that the SCTP implementation must not bundle user Please note that the SCTP implementation must not bundle user
messages which should be authenticated using different shared key messages that needs to be authenticated using different shared key
identifiers. identifiers.
5.2.9. SCTP Destination Address Structure (IPv4) (SCTP_DSTADDRV4)
This cmsghdr structure specifies SCTP options for sendmsg().
+--------------+----------------+----------------+
| cmsg_level | cmsg_type | cmsg_data[] |
+--------------+----------------+----------------+
| IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr |
+--------------+----------------+----------------+
This ancillary data can be used to provide more than one destination
address to sendmsg(). It can be used to implement sctp_sendxxx()
using send_msg().
5.2.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6)
This cmsghdr structure specifies SCTP options for sendmsg().
+--------------+----------------+-----------------+
| cmsg_level | cmsg_type | cmsg_data[] |
+--------------+----------------+-----------------+
| IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr |
+--------------+----------------+-----------------+
This ancillary data can be used to provide more than one destination
address to sendmsg(). It can be used to implement sctp_sendxxx()
using send_msg().
5.3. SCTP Events and Notifications 5.3. SCTP Events and Notifications
An SCTP application may need to understand and process events and An SCTP application may need to understand and process events and
errors that happen on the SCTP stack. These events include network errors that happen on the SCTP stack. These events include network
status changes, association startups, remote operational errors and status changes, association startups, remote operational errors and
undeliverable messages. All of these can be essential for the undeliverable messages. All of these can be essential for the
application. application.
When an SCTP application layer does a recvmsg() the message read is When an SCTP application layer does a recvmsg() the message read is
normally a data message from a peer endpoint. If the application normally a data message from a peer endpoint. If the application
skipping to change at page 36, line 41 skipping to change at page 37, line 31
direction are available in sac_outbound_streams and sac_inbound direction are available in sac_outbound_streams and sac_inbound
streams. streams.
sac_assoc_id: The association id field holds the identifier for the sac_assoc_id: The association id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was
received for this association, sac_info[] contains the complete received for this association, sac_info[] contains the complete
ABORT chunk as defined in the SCTP specification [RFC4960] section ABORT chunk as defined in the SCTP specification [RFC4960] section
3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info
may contain an array of features that the current association may contain an array of uint8_t describing the features that the
supports. Features may include current association supports. Features may include
SCTP_PR: Both endpoints support the protocol extension described SCTP_ASSOC_SUPPORTS_PR: Both endpoints support the protocol
in [RFC3758]. extension described in [RFC3758].
SCTP_AUTH: Both endpoints support the protocol extension SCTP_ASSOC_SUPPORTS_AUTH: Both endpoints support the protocol
described in [RFC4895]. extension described in [RFC4895].
SCTP_ASCONF: Both endpoints support the protocol extension SCTP_ASSOC_SUPPORTS_ASCONF: Both endpoints support the protocol
described in [RFC5061]. extension described in [RFC5061].
SCTP_ASSOC_SUPPORTS_MULTIBUF: For a one-to-many style socket, the
SCTP_MULTIBUF: For a one-to-many style socket, the local local endpoints use separate send and/or receive buffers for
endpoints use separate send and/or receive buffers for each each SCTP association.
SCTP association.
5.3.3. SCTP_PEER_ADDR_CHANGE 5.3.3. SCTP_PEER_ADDR_CHANGE
When a destination address of a multi-homed peer encounters a state When a destination address of a multi-homed peer encounters a state
change a peer address change event is sent. The notification has the change a peer address change event is sent. The notification has the
following format: following format:
struct sctp_paddr_change { struct sctp_paddr_change {
uint16_t spc_type; uint16_t spc_type;
uint16_t spc_flags; uint16_t spc_flags;
skipping to change at page 37, line 33 skipping to change at page 38, line 23
} }
spc_type: It should be SCTP_PEER_ADDR_CHANGE. spc_type: It should be SCTP_PEER_ADDR_CHANGE.
spc_flags: Currently unused. spc_flags: Currently unused.
spc_length: This field is the total length of the notification data, spc_length: This field is the total length of the notification data,
including the notification header. including the notification header.
spc_aaddr: The affected address field holds the remote peer's spc_aaddr: The affected address field holds the remote peer's
address that is encountering the change of state. address that is encountering the change of state.
spc_state: This field holds one of a number of values that spc_state: This field holds one of a number of values that
communicate the event that happened to the address. They include: communicate the event that happened to the address. They include:
SCTP_ADDR_AVAILABLE: This address is now reachable. SCTP_ADDR_AVAILABLE: This address is now reachable. This
notification is provided whenever an address becomes reachable
and was unreachable.
SCTP_ADDR_UNREACHABLE: The address specified can no longer be SCTP_ADDR_UNREACHABLE: The address specified can no longer be
reached. Any data sent to this address is rerouted to an reached. Any data sent to this address is rerouted to an
alternate until this address becomes reachable. alternate until this address becomes reachable. This
notification is provided whenever an address becomes
unreachable and was reachable.
SCTP_ADDR_REMOVED: The address is no longer part of the SCTP_ADDR_REMOVED: The address is no longer part of the
association. association.
SCTP_ADDR_ADDED: The address is now part of the association. SCTP_ADDR_ADDED: The address is now part of the association.
SCTP_ADDR_MADE_PRIM: This address has now been made to be the SCTP_ADDR_MADE_PRIM: This address has now been made to be the
primary destination address. primary destination address.
SCTP_ADDR_CONFIRMED: This address has now been confirmed as a SCTP_ADDR_CONFIRMED: This address has now been confirmed as a
valid address. valid address. This notification is provided once for each
address as soon as the address is confirmed.
spc_error: If the state was reached due to any error condition (e.g. spc_error: If the state was reached due to any error condition (e.g.
SCTP_ADDR_UNREACHABLE) any relevant error information is available SCTP_ADDR_UNREACHABLE) any relevant error information is available
in this field. in this field.
spc_assoc_id: The association id field holds the identifier for the spc_assoc_id: The association id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
5.3.4. SCTP_REMOTE_ERROR 5.3.4. SCTP_REMOTE_ERROR
skipping to change at page 38, line 38 skipping to change at page 39, line 31
defined in the SCTP specification, in network byte order. defined in the SCTP specification, in network byte order.
sre_assoc_id: The association id field holds the identifier for the sre_assoc_id: The association id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
sre_data: This contains the ERROR chunk as defined in the SCTP sre_data: This contains the ERROR chunk as defined in the SCTP
specification [RFC4960] section 3.3.10. specification [RFC4960] section 3.3.10.
5.3.5. SCTP_SEND_FAILED 5.3.5. SCTP_SEND_FAILED
Please note that this notification is deprecated.
If SCTP cannot deliver a message, it can return back the message as a If SCTP cannot deliver a message, it can return back the message as a
notification if the SCTP_SEND_FAILED event is enabled. The notification if the SCTP_SEND_FAILED event is enabled. The
notification has the following format: notification has the following format:
struct sctp_send_failed { struct sctp_send_failed {
uint16_t ssf_type; uint16_t ssf_type;
uint16_t ssf_flags; uint16_t ssf_flags;
uint32_t ssf_length; uint32_t ssf_length;
uint32_t ssf_error; uint32_t ssf_error;
struct sctp_sndrcvinfo ssf_info; struct sctp_sndrcvinfo ssf_info;
skipping to change at page 41, line 28 skipping to change at page 42, line 28
}; };
pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT. pdapi_type: It should be SCTP_PARTIAL_DELIVERY_EVENT.
pdapi_flags: Currently unused. pdapi_flags: Currently unused.
pdapi_length: This field is the total length of the notification pdapi_length: This field is the total length of the notification
data, including the notification header. It will generally be data, including the notification header. It will generally be
sizeof(struct sctp_pdapi_event). sizeof(struct sctp_pdapi_event).
pdapi_indication: This field holds the indication being sent to the pdapi_indication: This field holds the indication being sent to the
application. Currently there is only one defined value: application. Currently there is only one defined value:
SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial SCTP_PARTIAL_DELIVERY_ABORTED: This indicates that the partial
delivery of a user message has been aborted. delivery of a user message has been aborted. This happens, for
example, if an association is aborted while a partial delivery
is going on or the user message gets abandoned using PR-SCTP
while the partial delivery of this message is going on.
pdapi_stream: This field holds the stream on which the partial pdapi_stream: This field holds the stream on which the partial
delivery event happened. delivery event happened.
pdapi_seq: This field holds the stream sequence number which was pdapi_seq: This field holds the stream sequence number which was
being partially delivered. being partially delivered.
pdapi_assoc_id: The association id field holds the identifier for pdapi_assoc_id: The association id field holds the identifier for
the association. All notifications for a given association have the association. All notifications for a given association have
the same association identifier. For a one-to-one style socket the same association identifier. For a one-to-one style socket
this field is ignored. this field is ignored.
5.3.9. SCTP_AUTHENTICATION_EVENT 5.3.9. SCTP_AUTHENTICATION_EVENT
[RFC4895] defines an extension to authenticate SCTP messages. The [RFC4895] defines an extension to authenticate SCTP messages. The
following notification is used to report different events relating to following notification is used to report different events relating to
the use of this extension. the use of this extension.
struct sctp_authkey_event { struct sctp_authkey_event {
uint16_t auth_type; uint16_t auth_type;
uint16_t auth_flags; uint16_t auth_flags;
uint32_t auth_length; uint32_t auth_length;
uint16_t auth_keynumber; uint16_t auth_keynumber;
uint16_t auth_altkeynumber;
uint32_t auth_indication; uint32_t auth_indication;
sctp_assoc_t auth_assoc_id; sctp_assoc_t auth_assoc_id;
}; };
auth_type: It should be SCTP_AUTHENTICATION_EVENT. auth_type: It should be SCTP_AUTHENTICATION_EVENT.
auth_flags: Currently unused. auth_flags: Currently unused.
auth_length: This field is the total length of the notification auth_length: This field is the total length of the notification
data, including the notification header. It will generally be data, including the notification header. It will generally be
sizeof (struct sctp_authkey_event). sizeof (struct sctp_authkey_event).
auth_keynumber: This field holds the keynumber for the affected key auth_keynumber: This field holds the keynumber for the affected key
indicated in the event (depends on auth_indication). If more than indicated in the event (depends on auth_indication).
one key is involved, this will contain one of the keys involved in
the notification.
auth_altkeynumber: This field holds an alternate keynumber which is
used by some notifications.
auth_indication: This field holds the error or indication being auth_indication: This field holds the error or indication being
reported. The following values are currently defined: reported. The following values are currently defined:
SCTP_AUTH_NEWKEY: This report indicates that a new key has been SCTP_AUTH_NEW_KEY: This report indicates that a new key has been
made active (used for the first time by the peer) and is now made active (used for the first time by the peer) and is now
the active key. The auth_keynumber field holds the user the active key. The auth_keynumber field holds the user
specified key number. specified key number.
SCTP_AUTH_NO_AUTH: This report indicates that the peer does not SCTP_AUTH_NO_AUTH: This report indicates that the peer does not
support SCTP AUTH as defined in [RFC4895]. support SCTP AUTH as defined in [RFC4895].
SCTP_AUTH_FREE_KEY: This report indicates that the SCTP SCTP_AUTH_FREE_KEY: This report indicates that the SCTP
implementation will not use the key identifier specified in implementation will not use the key identifier specified in
auth_keynumber anymore. auth_keynumber anymore.
auth_assoc_id: The association id field holds the identifier for the auth_assoc_id: The association id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
skipping to change at page 43, line 27 skipping to change at page 44, line 28
This notification is an union sctp_notification, where only the This notification is an union sctp_notification, where only the
struct sctp_tlv (see the union above) is used. That merely has this struct sctp_tlv (see the union above) is used. That merely has this
type in the sn_type field, the sn_length field set to the sizeof an type in the sn_type field, the sn_length field set to the sizeof an
sctp_tlv structure and the sn_flags set to 0. If an application sctp_tlv structure and the sn_flags set to 0. If an application
receives this notification, it will need to resubscribe to any receives this notification, it will need to resubscribe to any
notifications of interest to it, except for the data io event. notifications of interest to it, except for the data io event.
An endpoint is automatically subscribed to this event as soon as it An endpoint is automatically subscribed to this event as soon as it
is subscribed to any event other than data io events. is subscribed to any event other than data io events.
5.3.12. SCTP_SEND_FAILED_EVENT
If SCTP cannot deliver a message, it can return back the message as a
notification if the SCTP_SEND_FAILED_EVENT event is enabled. The
notification has the following format:
struct sctp_send_failed {
uint16_t ssf_type;
uint16_t ssf_flags;
uint32_t ssf_length;
uint32_t ssf_error;
struct sctp_sndinfo ssf_info;
sctp_assoc_t ssf_assoc_id;
uint8_t ssf_data[];
};
ssf_type: It should be SCTP_SEND_FAILED_EVENT.
ssf_flags: The flag value will take one of the following values:
SCTP_DATA_UNSENT: Indicates that the data was never put on the
wire.
SCTP_DATA_SENT: Indicates that the data was put on the wire.
Note that this does not necessarily mean that the data was (or
was not) successfully delivered.
ssf_length: This field is the total length of the notification data,
including the notification header and the payload in ssf_data.
ssf_error: This value represents the reason why the send failed, and
if set, will be an SCTP protocol error code as defined in
[RFC4960] section 3.3.10.
ssf_info: The send information associated with the undelivered
message. The ssf_info.snd_flags field will also contain an
indication if the beginning of the message and/or end of the
message is present. In cases where no data has been sent on the
wire, this field will have or'ed in the value SCTP_DATA_NOT_FRAG,
which is a composition of both a "BEGIN" and "END" fragmentation
bit. In cases where only part of the data has been sent, this
field will have or'ed in the value SCTP_DATA_LAST_FRAG, which
corresponds to the "END" bit. Note that the message itself may be
more than one chunk. If the ssf_info.snd_flags field holds
neither of these two values then a piece that has been fragmented
and sent but not acknowledged is present. This piece is from an
unspecified position in the message and the application can make
no assumptions about the data itself. Applications wanting to
examine a recovered message should look for the
SCTP_DATA_NOT_FRAG. Without this flag the application should
assume part of the message arrived and take appropriate steps to
audit and recover any lost or missing data.
ssf_assoc_id: The association id field, ssf_assoc_id, holds the
identifier for the association. All notifications for a given
association have the same association identifier. For a one-to-
one style socket, this field is ignored.
ssf_data: The undelivered message or part of the undelivered message
will be present in the ssf_data field. Note that the
ssf_info.sinfo_flags field as noted above should be used to
determine if a complete message is present or just a piece of the
message. Note that only user data is present in this field, any
chunk headers or SCTP common headers must be removed by the SCTP
stack.
5.4. Ancillary Data Considerations and Semantics 5.4. Ancillary Data Considerations and Semantics
Programming with ancillary socket data contains some subtleties and Programming with ancillary socket data contains some subtleties and
pitfalls, which are discussed below. pitfalls, which are discussed below.
5.4.1. Multiple Items and Ordering 5.4.1. Multiple Items and Ordering
Multiple ancillary data items may be included in any call to Multiple ancillary data items may be included in any call to
sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP
items, or both. items, or both.
skipping to change at page 46, line 41 skipping to change at page 49, line 7
above calls do not allow the caller to specify on which stream a above calls do not allow the caller to specify on which stream a
message should be sent. The system uses stream 0 as the default message should be sent. The system uses stream 0 as the default
stream for send() and sendto(). recv() and recvfrom() return data stream for send() and sendto(). recv() and recvfrom() return data
from any stream, but the caller can not distinguish the different from any stream, but the caller can not distinguish the different
streams. This may result in data seeming to arrive out of order. streams. This may result in data seeming to arrive out of order.
Similarly, if a data chunk is sent unordered, recv() and recvfrom() Similarly, if a data chunk is sent unordered, recv() and recvfrom()
provide no indication. provide no indication.
SCTP is message based. The msg buffer above in send() and sendto() SCTP is message based. The msg buffer above in send() and sendto()
is considered to be a single message. This means that if the caller is considered to be a single message. This means that if the caller
wants to send a message which is composed by several buffers, the wants to send a message that is composed by several buffers, the
caller needs to combine them before calling send() or sendto(). caller needs to combine them before calling send() or sendto().
Alternately, the caller can use sendmsg() to do that without Alternately, the caller can use sendmsg() to do that without
combining them. Sending a message using send() or sendto() is atomic combining them. Sending a message using send() or sendto() is atomic
unless explicit EOR marking is enabled on the socket specified by sd. unless explicit EOR marking is enabled on the socket specified by sd.
Using sendto() on a non-connected one-to-one style socket for Using sendto() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP implicit connection setup may or may not work depending on the SCTP
implementation. recv() and recvfrom() cannot distinguish message implementation. recv() and recvfrom() cannot distinguish message
boundaries. boundaries.
In receiving, if the buffer supplied is not large enough to hold a In receiving, if the buffer supplied is not large enough to hold a
complete message, the receive call acts like a stream socket and complete message, the receive call acts like a stream socket and
returns as much data as will fit in the buffer. returns as much data as will fit in the buffer.
Note, the send() and recv() calls may not be used for a one-to-many Note, the send() and recv() calls may not be used for a one-to-many
style socket. style socket.
Note, if an application calls a send function with no user data and Note, if an application calls a send function with no user data and
no ancillary data the SCTP implementation should reject the request no ancillary data the SCTP implementation should reject the request
with an appropriate error message. An implementation is NOT allowed with an appropriate error message. An implementation is not allowed
to send a DATA chunk with no user data [RFC4960]. to send a DATA chunk with no user data [RFC4960].
6.2. setsockopt() and getsockopt() 6.2. setsockopt() and getsockopt()
Applications use setsockopt() and getsockopt() to set or retrieve Applications use setsockopt() and getsockopt() to set or retrieve
socket options. Socket options are used to change the default socket options. Socket options are used to change the default
behavior of socket calls. They are described in Section 7. behavior of socket calls. They are described in Section 7.
The function prototypes are The function prototypes are
skipping to change at page 49, line 5 skipping to change at page 51, line 18
address will be either an IPv6 or IPv4 address. address will be either an IPv6 or IPv4 address.
len: The caller should set the length of the address here. On len: The caller should set the length of the address here. On
return, this is set to the length of the returned address. return, this is set to the length of the returned address.
If the actual length of the address is greater than the length of the If the actual length of the address is greater than the length of the
supplied sockaddr structure, the stored address will be truncated. supplied sockaddr structure, the stored address will be truncated.
If the socket has not been bound to a local name, the value stored in If the socket has not been bound to a local name, the value stored in
the object pointed to by address is unspecified. the object pointed to by address is unspecified.
6.5. Implicit Association Setup
Once the bind() call is complete, the application can begin sending
and receiving data using the sendmsg()/recvmsg() or sendto()/
recvfrom() calls, without going through any explicit association
setup procedures (i.e., no connect() calls required).
Whenever sendmsg() or sendto() is called and the SCTP stack at the
sender finds that no association exists between the sender and the
intended receiver (identified by the address passed either in the
msg_name field of msghdr structure in the sendmsg() call or the
dest_addr field in the sendto() call), the SCTP stack will
automatically setup an association to the intended receiver.
Upon the successful association setup an SCTP_COMM_UP notification
will be dispatched to the socket at both the sender and receiver
side. This notification can be read by the recvmsg() system call
(see Section 3.1.3).
Note, if the SCTP stack at the sender side supports bundling, the
first user message may be bundled with the COOKIE ECHO message
[RFC4960].
When the SCTP stack sets up a new association implicitly, the
SCTP_INIT type ancillary data may also be passed along (see
Section 5.2.1 for details of the data structures) to change some
parameters used in setting up new association.
If this information is not present in the sendmsg() call, or if the
implicit association setup is triggered by a sendto() call, the
default association initialization parameters will be used. These
default association parameters may be set with respective
setsockopt() calls or be left to the system defaults.
Implicit association setup cannot be initiated by send() calls.
7. Socket Options 7. Socket Options
The following sub-section describes various SCTP level socket options The following sub-section describes various SCTP level socket options
that are common to both styles. SCTP associations can be multi- that are common to both styles. SCTP associations can be multi-
homed. Therefore, certain option parameters include a homed. Therefore, certain option parameters include a
sockaddr_storage structure to select which peer address the option sockaddr_storage structure to select which peer address the option
should be applied to. should be applied to.
For the one-to-many style sockets, an sctp_assoc_t (association ID) For the one-to-many style sockets, an sctp_assoc_t (association ID)
parameter is used to identify the association instance that the parameter is used to identify the association instance that the
operation affects. So it must be set when using this style. operation affects. So it must be set when using this style.
For the one-to-one style sockets and branched off one-to-many style For the one-to-one style sockets and branched off one-to-many style
sockets (see Section 8.2) this association ID parameter is ignored. sockets (see Section 8.2) this association ID parameter is ignored.
Note that socket or IP level options are set or retrieved per socket. Note that socket or IP level options are set or retrieved per socket.
This means that for one-to-many style sockets, those options will be This means that for one-to-many style sockets, the options will be
applied to all associations (similar to using SCTP_ALL_ASSOC as the applied to all associations (similar to using SCTP_ALL_ASSOC as the
association ID) belonging to the socket. And for one-to-one style, association ID) belonging to the socket. For one-to-one style, these
those options will be applied to all peer addresses of the options will be applied to all peer addresses of the association
association controlled by the socket. Applications should be very controlled by the socket. Applications should be careful in setting
careful in setting those options. those options.
For some IP stacks getsockopt() is read-only; so a new interface will For some IP stacks getsockopt() is read-only; so a new interface will
be needed when information must be passed both into and out of the be needed when information must be passed both into and out of the
SCTP stack. The syntax for sctp_opt_info() is SCTP stack. The syntax for sctp_opt_info() is
int sctp_opt_info(int sd, int sctp_opt_info(int sd,
sctp_assoc_t id, sctp_assoc_t id,
int opt, int opt,
void *arg, void *arg,
socklen_t *size); socklen_t *size);
The sctp_opt_info() call is a replacement for getsockopt() only and The sctp_opt_info() call is a replacement for getsockopt() only and
will not set any options associated with the specified socket. A will not set any options associated with the specified socket. A
setsockopt() must be used to set any writeable option. setsockopt() must be used to set any writeable option.
For one-to-many style sockets, id specifies the association to query. For one-to-many style sockets, id specifies the association to query.
For one-to-one style sockets, id is ignored. Note that For one-to-one style sockets, id is ignored. For one-to-many
SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used here. Using sockets, any association identifier in the structure provided as arg
them will result in an error (returning -1 and errno set to EINVAL). is ignored and id takes precedence.
SCTP_FUTURE_ASSOC can be used to query information for future
associations. Note that SCTP_CURRENT_ASSOC and SCTP_ALL_ASSOC cannot be used here.
Using them will result in an error (returning -1 and errno set to
EINVAL). SCTP_FUTURE_ASSOC can be used to query information for
future associations.
The field opt specifies which SCTP socket option to get. It can get The field opt specifies which SCTP socket option to get. It can get
any socket option currently supported that requests information any socket option currently supported that requests information
(either read/write options or read only) such as: (either read/write options or read only) such as:
SCTP_RTOINFO SCTP_RTOINFO
SCTP_ASSOCINFO SCTP_ASSOCINFO
SCTP_DEFAULT_SEND_PARAM SCTP_DEFAULT_SEND_PARAM
SCTP_GET_PEER_ADDR_INFO SCTP_GET_PEER_ADDR_INFO
SCTP_PRIMARY_ADDR SCTP_PRIMARY_ADDR
SCTP_PEER_ADDR_PARAMS SCTP_PEER_ADDR_PARAMS
SCTP_STATUS SCTP_STATUS
SCTP_CONTEXT SCTP_CONTEXT
SCTP_AUTH_ACTIVE_KEY SCTP_AUTH_ACTIVE_KEY
SCTP_PEER_AUTH_CHUNKS SCTP_PEER_AUTH_CHUNKS
skipping to change at page 52, line 30 skipping to change at page 55, line 40
The values of the sasoc_peer_rwnd is meaningless when examining The values of the sasoc_peer_rwnd is meaningless when examining
endpoint information. endpoint information.
All time values are given in milliseconds. A value of 0, when All time values are given in milliseconds. A value of 0, when
modifying the parameters, indicates that the current value should not modifying the parameters, indicates that the current value should not
be changed. be changed.
The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set
on either an endpoint or association basis. The rwnd and destination on either an endpoint or association basis. The rwnd and destination
counts (sasoc_number_peer_destinations, sasoc_peer_rwnd, counts (sasoc_number_peer_destinations, sasoc_peer_rwnd,
sasoc_local_rwnd) are NOT settable and any value placed in these is sasoc_local_rwnd) are not settable and any value placed in these is
ignored. ignored.
To access or modify these parameters, the application should call To access or modify these parameters, the application should call
getsockopt() or setsockopt() respectively with the option name getsockopt() or setsockopt() respectively with the option name
SCTP_ASSOCINFO. SCTP_ASSOCINFO.
The maximum number of retransmissions before an address is considered The maximum number of retransmissions before an address is considered
unreachable is also tunable, but is address-specific, so it is unreachable is also tunable, but is address-specific, so it is
covered in a separate option. If an application attempts to set the covered in a separate option. If an application attempts to set the
value of the association maximum retransmission parameter to more value of the association maximum retransmission parameter to more
skipping to change at page 53, line 38 skipping to change at page 56, line 47
}; };
To enable the option, set l_onoff to 1. If the l_linger value is set To enable the option, set l_onoff to 1. If the l_linger value is set
to 0, calling close() is the same as the ABORT primitive. If the to 0, calling close() is the same as the ABORT primitive. If the
value is set to a negative value, the setsockopt() call will return value is set to a negative value, the setsockopt() call will return
an error. If the value is set to a positive value linger_time, the an error. If the value is set to a positive value linger_time, the
close() can be blocked for at most linger_time ms. If the graceful close() can be blocked for at most linger_time ms. If the graceful
shutdown phase does not finish during this period, close() will shutdown phase does not finish during this period, close() will
return but the graceful shutdown phase will continue in the system. return but the graceful shutdown phase will continue in the system.
Note, this is a socket level option NOT an SCTP level option. So Note, this is a socket level option not an SCTP level option. So
when setting SO_LINGER an application must specify a level of when setting SO_LINGER an application must specify a level of
SOL_SOCKET in the setsockopt() call. SOL_SOCKET in the setsockopt() call.
7.1.5. SCTP_NODELAY 7.1.5. SCTP_NODELAY
Turn on/off any Nagle-like algorithm. This means that packets are Turn on/off any Nagle-like algorithm. This means that packets are
generally sent as soon as possible and no unnecessary delays are generally sent as soon as possible and no unnecessary delays are
introduced, at the cost of more packets in the network. Expects an introduced, at the cost of more packets in the network. Expects an
integer boolean flag. Turning this option on disables any Nagle-like integer boolean flag. Turning this option on disables any Nagle-like
algorithm. algorithm.
skipping to change at page 54, line 21 skipping to change at page 57, line 29
descriptor or it might control the receive buffer for the whole descriptor or it might control the receive buffer for the whole
socket. The call expects an integer. socket. The call expects an integer.
7.1.7. SO_SNDBUF 7.1.7. SO_SNDBUF
Sets the send buffer size. For SCTP one-to-one style sockets, this Sets the send buffer size. For SCTP one-to-one style sockets, this
controls the amount of data SCTP may have waiting in internal buffers controls the amount of data SCTP may have waiting in internal buffers
to be sent. This option therefore bounds the maximum size of data to be sent. This option therefore bounds the maximum size of data
that can be sent in a single send call. For one-to-many style that can be sent in a single send call. For one-to-many style
sockets, the effect is the same, except that it applies to one or all sockets, the effect is the same, except that it applies to one or all
associations (see Section 3.4) bound to the socket descriptor used in associations (see Section 3.3) bound to the socket descriptor used in
the setsockopt() or getsockopt() call. The option applies to each the setsockopt() or getsockopt() call. The option applies to each
association's window size separately. The call expects an integer. association's window size separately. The call expects an integer.
7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) 7.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE)
This socket option is applicable to the one-to-many style socket This socket option is applicable to the one-to-many style socket
only. When set it will cause associations that are idle for more only. When set it will cause associations that are idle for more
than the specified number of seconds to automatically close using the than the specified number of seconds to automatically close using the
graceful shutdown procedure. An association being idle is defined as graceful shutdown procedure. An association being idle is defined as
an association that has NOT sent or received user data. The special an association that has not sent or received user data. The special
value of '0' indicates that no automatic close of any association value of '0' indicates that no automatic close of any association
should be performed, this is the default value. The option expects should be performed, this is the default value. The option expects
an integer defining the number of seconds of idle time before an an integer defining the number of seconds of idle time before an
association is closed. association is closed.
An application using this option should enable receiving the An application using this option should enable receiving the
association change notification. This is the only mechanism an association change notification. This is the only mechanism an
application is informed about the closing of an association. After application is informed about the closing of an association. After
an association is closed, the association ID assigned to it can be an association is closed, the association ID assigned to it can be
reused. An application should be aware of this to avoid the possible reused. An application should be aware of this to avoid the possible
skipping to change at page 55, line 35 skipping to change at page 58, line 43
}; };
ssb_adaptation_ind: The adaptation layer indicator that will be ssb_adaptation_ind: The adaptation layer indicator that will be
included in any outgoing Adaptation Layer Indication parameter. included in any outgoing Adaptation Layer Indication parameter.
7.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS) 7.1.11. Enable/Disable Message Fragmentation (SCTP_DISABLE_FRAGMENTS)
This option is a on/off flag and is passed as an integer where a non- This option is a on/off flag and is passed as an integer where a non-
zero is on and a zero is off. If enabled no SCTP message zero is on and a zero is off. If enabled no SCTP message
fragmentation will be performed. Instead, if a message being sent fragmentation will be performed. Instead, if a message being sent
exceeds the current PMTU size, the message will NOT be sent and exceeds the current PMTU size, the message will not be sent and
instead an error will be indicated to the user. instead an error will be indicated to the user.
7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) 7.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS)
Applications can enable or disable heartbeats for any peer address of Applications can enable or disable heartbeats for any peer address of
an association, modify an address's heartbeat interval, force a an association, modify an address's heartbeat interval, force a
heartbeat to be sent immediately, and adjust the address's maximum heartbeat to be sent immediately, and adjust the address's maximum
number of retransmissions sent before an address is considered number of retransmissions sent before an address is considered
unreachable. unreachable.
skipping to change at page 56, line 19 skipping to change at page 59, line 22
uint16_t spp_pathmaxrxt; uint16_t spp_pathmaxrxt;
uint32_t spp_pathmtu; uint32_t spp_pathmtu;
uint32_t spp_flags; uint32_t spp_flags;
uint32_t spp_ipv6_flowlabel; uint32_t spp_ipv6_flowlabel;
uint8_t spp_ipv4_tos; uint8_t spp_ipv4_tos;
}; };
spp_assoc_id: This parameter is ignored for one-to-one style spp_assoc_id: This parameter is ignored for one-to-one style
sockets. For one-to-many style sockets it identifies the sockets. For one-to-many style sockets it identifies the
association for this query. Note that the predefined constants association for this query. Note that the predefined constants
are NOT allowed. are not allowed.
spp_address: This specifies which address is of interest. If a spp_address: This specifies which address is of interest. If a
wildcard address is provided it applies to all current and future wildcard address is provided it applies to all current and future
paths. paths.
spp_hbinterval: This contains the value of the heartbeat interval, spp_hbinterval: This contains the value of the heartbeat interval,
in milliseconds (HB.Interval in [RFC4960]). Note that unless the in milliseconds (HB.Interval in [RFC4960]). Note that unless the
spp_flag is set to SPP_HB_ENABLE the value of this field is spp_flag is set to SPP_HB_ENABLE the value of this field is
ignored. Note also that a value of zero indicates the current ignored. Note also that a value of zero indicates the current
setting should be left unchanged. To set an actual value of zero setting should be left unchanged. To set an actual value of zero
the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when the use of the flag SPP_HB_TIME_IS_ZERO should be used. Even when
it is set to 0, it does not mean that SCTP will continuously send it is set to 0, it does not mean that SCTP will continuously send
out heartbeat since the actual interval also includes a the out heartbeat since the actual interval also includes a the
current RTO and jitter (see Section 8.3 in [RFC4960]). current RTO and jitter (see Section 8.3 in [RFC4960]).
spp_pathmaxrxt: This contains the maximum number of retransmissions spp_pathmaxrxt: This contains the maximum number of retransmissions
before this address shall be considered unreachable. Note that a before this address shall be considered unreachable. Note that a
value of zero indicates the current setting should be left value of zero indicates the current setting should be left
unchanged. unchanged.
spp_pathmtu: When Path MTU discovery is disabled the value specified
here will be the "fixed" path MTU (i.e. the value of the spp_flags
field must include the flag SPP_PMTUD_DISABLE). Note also that
this option cannot be set on the endpoint, but must be set on each
individual association. Also, when disabling PMTU discovery, the
implementation may disallow this behavior if the "fixed" path MTU
is below the constant value SCTP_SMALLEST_PMTU.
spp_ipv6_flowlabel: This field is used in conjunction with the spp_ipv6_flowlabel: This field is used in conjunction with the
SPP_IPV6_FLOWLABEL flag. SPP_IPV6_FLOWLABEL flag. This setting has precedence over any
IPv6 layer setting.
spp_ipv4_tos: This field is used in conjunction with the spp_ipv4_tos: This field is used in conjunction with the
SPP_IPV4_TOS flag. SPP_IPV4_TOS flag. This setting has precedence over any IPv4
layer setting.
spp_flags: These flags are used to control various features on an spp_flags: These flags are used to control various features on an
association. The flag field is a bit mask which may contain zero association. The flag field is a bit mask which may contain zero
or more of the following options: or more of the following options:
SPP_HB_ENABLE: Enable heartbeats on the specified address. SPP_HB_ENABLE: Enable heartbeats on the specified address.
SPP_HB_DISABLE: Disable heartbeats on the specified address. SPP_HB_DISABLE: Disable heartbeats on the specified address.
Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually
exclusive, only one of these two should be specified. Enabling exclusive, only one of these two should be specified. Enabling
both fields will have undetermined results. both fields will have undetermined results.
SPP_HB_DEMAND: Request a user initiated heartbeat to be made SPP_HB_DEMAND: Request a user initiated heartbeat to be made
immediately. This must not be used in conjunction with a immediately. This must not be used in conjunction with a
wildcard address. wildcard address.
SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay SPP_HB_TIME_IS_ZERO: Specifies that the time for heartbeat delay
is to be set to the value of 0 milliseconds. is to be set to the value of 0 milliseconds.
SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the SPP_PMTUD_ENABLE: This field will enable PMTU discovery upon the
skipping to change at page 58, line 7 skipping to change at page 61, line 7
returned. If just an association is specified then the returned. If just an association is specified then the
association default TOS is returned. If neither an association association default TOS is returned. If neither an association
nor an destination is specified, then the sockets default TOS nor an destination is specified, then the sockets default TOS
is returned. is returned.
To read or modify these parameters, the application should call To read or modify these parameters, the application should call
sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option.
7.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM) 7.1.13. Set Default Send Parameters (SCTP_DEFAULT_SEND_PARAM)
Please note that this options is deprecated. Section 7.1.31 should
be used instead.
Applications that wish to use the sendto() system call may wish to Applications that wish to use the sendto() system call may wish to
specify a default set of parameters that would normally be supplied specify a default set of parameters that would normally be supplied
through the inclusion of ancillary data. This socket option allows through the inclusion of ancillary data. This socket option allows
such an application to set the default sctp_sndrcvinfo structure. such an application to set the default sctp_sndrcvinfo structure.
The application that wishes to use this socket option simply passes The application that wishes to use this socket option simply passes
the sctp_sndrcvinfo structure defined in Section 5.2.2 to this call. the sctp_sndrcvinfo structure defined in Section 5.2.2 to this call.
The input parameters accepted by this call include sinfo_stream, The input parameters accepted by this call include sinfo_stream,
sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy and sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy and
sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of
SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field
skipping to change at page 58, line 38 skipping to change at page 61, line 41
option. See Section 7.4 for a full description of that option as option. See Section 7.4 for a full description of that option as
well. well.
7.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 7.1.15. Set/Clear IPv4 Mapped Addresses (SCTP_I_WANT_MAPPED_V4_ADDR)
This socket option is a boolean flag which turns on or off the This socket option is a boolean flag which turns on or off the
mapping of IPv4 addresses. If this option is turned on and the mapping of IPv4 addresses. If this option is turned on and the
socket is type PF_INET6, then IPv4 addresses will be mapped to V6 socket is type PF_INET6, then IPv4 addresses will be mapped to V6
representation. If this option is turned off, then no mapping will representation. If this option is turned off, then no mapping will
be done of V4 addresses and a user will receive both PF_INET6 and be done of V4 addresses and a user will receive both PF_INET6 and
PF_INET type addresses on the socket. PF_INET type addresses on the socket. See [RFC3542] for more details
on mapped V6 addresses.
By default this option is turned off and expects an integer to be By default this option is turned off and expects an integer to be
passed where non-zero turns on the option and zero turns off the passed where non-zero turns on the option and zero turns off the
option. option.
7.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG) 7.1.16. Get or Set the Maximum Fragmentation Size (SCTP_MAXSEG)
This option will get or set the maximum size to put in any outgoing This option will get or set the maximum size to put in any outgoing
SCTP DATA chunk. If a message is larger than this size it will be SCTP DATA chunk. If a message is larger than this size it will be
fragmented by SCTP into the specified size. Note that the underlying fragmented by SCTP into the specified size. Note that the underlying
SCTP implementation may fragment into smaller sized chunks when the SCTP implementation may fragment into smaller sized chunks when the
PMTU of the underlying association is smaller than the value set by PMTU of the underlying association is smaller than the value set by
the user. The default value for this option is '0' which indicates the user. The default value for this option is '0' which indicates
the user is NOT limiting fragmentation and only the PMTU will affect the user is not limiting fragmentation and only the PMTU will affect
SCTP's choice of DATA chunk size. Note also that values set larger SCTP's choice of DATA chunk size. Note also that values set larger
than the maximum size of an IP datagram will effectively let SCTP than the maximum size of an IP datagram will effectively let SCTP
control fragmentation (i.e. the same as setting this option to 0). control fragmentation (i.e. the same as setting this option to 0).
The following structure is used to access and modify this parameter: The following structure is used to access and modify this parameter:
struct sctp_assoc_value { struct sctp_assoc_value {
sctp_assoc_t assoc_id; sctp_assoc_t assoc_id;
uint32_t assoc_value; uint32_t assoc_value;
}; };
skipping to change at page 62, line 26 skipping to change at page 65, line 26
message from the same association be delivered from the next message from the same association be delivered from the next
receive, some other associations message may be delivered upon the receive, some other associations message may be delivered upon the
next receive. next receive.
An implementation should default the one-to-many model to level 1. An implementation should default the one-to-many model to level 1.
The reason for this is that otherwise it is possible that a peer The reason for this is that otherwise it is possible that a peer
could begin sending a partial message and thus block all other peers could begin sending a partial message and thus block all other peers
from sending data. However a setting of level 2 requires the from sending data. However a setting of level 2 requires the
application to not only be aware of the association (via the application to not only be aware of the association (via the
association id or peer's address) but also the stream number. The association id or peer's address) but also the stream number. The
stream number is NOT present unless the user has subscribed to the stream number is not present unless the user has subscribed to the
sctp_data_io_events (see Section 7.4). This is also why we recommend sctp_data_io_events (see Section 7.4). This is also why we recommend
that the one-to-one model be defaulted to level 0 (level 1 for the that the one-to-one model be defaulted to level 0 (level 1 for the
one-to-one model has no effect). Note that an implementation should one-to-one model has no effect). Note that an implementation should
return an error if an application attempts to set the level to 2 and return an error if an application attempts to set the level to 2 and
has NOT subscribed to the sctp_data_io_events. has not subscribed to the sctp_data_io_events.
For applications that have subscribed to events those events appear For applications that have subscribed to events those events appear
in the normal socket buffer data stream. This means that unless the in the normal socket buffer data stream. This means that unless the
user has set the fragmentation interleave level to 0, notifications user has set the fragmentation interleave level to 0, notifications
may also be interleaved with partially delivered messages. may also be interleaved with partially delivered messages.
7.1.21. Set or Get the SCTP Partial Delivery Point 7.1.21. Set or Get the SCTP Partial Delivery Point
(SCTP_PARTIAL_DELIVERY_POINT) (SCTP_PARTIAL_DELIVERY_POINT)
This option will set or get the SCTP partial delivery point. This This option will set or get the SCTP partial delivery point. This
skipping to change at page 65, line 14 skipping to change at page 68, line 14
having set the SCTP_REUSE_PORT option will fail if there are other having set the SCTP_REUSE_PORT option will fail if there are other
sockets bound to the same port. At most one socket being bound to sockets bound to the same port. At most one socket being bound to
the same port may be listening. the same port may be listening.
It should be noted that the behavior of the socket level socket It should be noted that the behavior of the socket level socket
option to reuse ports and/or addresses for SCTP sockets is option to reuse ports and/or addresses for SCTP sockets is
unspecified. unspecified.
7.1.28. Set Notification Event (SCTP_EVENT) 7.1.28. Set Notification Event (SCTP_EVENT)
This socket option is used to set a specific notification or This socket option is used to set a specific notification option.
ancillary data option. Please see Section 7.4 for a full description Please see Section 7.4 for a full description of this option and its
of this option and its usage. usage.
7.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as Ancillary
Data (SCTP_RECVRCVINFO)
Setting this option specifies that SCTP_RCVINFO defined in
Section 5.2.5 is returned as ancillary data by recvmsg(). The call
expects an integer.
7.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as Ancillary
Data (SCTP_RECVNXTINFO)
Setting this option specifies that SCTP_NXTINFO defined in
Section 5.2.6 is returned as ancillary data by recvmsg(). The call
expects an integer.
7.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO)
Applications that wish to use the sendto() system call may wish to
specify a default set of parameters that would normally be supplied
through the inclusion of ancillary data. This socket option allows
such an application to set the default sctp_sndrcvinfo structure.
The application that wishes to use this socket option simply passes
the sctp_sndinfo structure defined in Section 5.2.4 to this call.
The input parameters accepted by this call include snd_sid,
snd_flags, snd_ppid, snd_context. The snd_flags is composed of a
bitwise OR of SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The
snd_assoc_id field specifies the association to apply the parameters
to. In a one-to-many style sockets any of the predefined constants
are also allowed in this field. The field is ignored on the one-to-
one style.
7.2. Read-Only Options 7.2. Read-Only Options
The options defined in this subsection are read-only. Using this The options defined in this subsection are read-only. Using this
option in a setsockopt() call will result in an error indicating option in a setsockopt() call will result in an error indicating
EOPNOTSUPP. EOPNOTSUPP.
7.2.1. Association Status (SCTP_STATUS) 7.2.1. Association Status (SCTP_STATUS)
Applications can retrieve current status information about an Applications can retrieve current status information about an
skipping to change at page 67, line 4 skipping to change at page 70, line 35
struct sctp_paddrinfo { struct sctp_paddrinfo {
sctp_assoc_t spinfo_assoc_id; sctp_assoc_t spinfo_assoc_id;
struct sockaddr_storage spinfo_address; struct sockaddr_storage spinfo_address;
int32_t spinfo_state; int32_t spinfo_state;
uint32_t spinfo_cwnd; uint32_t spinfo_cwnd;
uint32_t spinfo_srtt; uint32_t spinfo_srtt;
uint32_t spinfo_rto; uint32_t spinfo_rto;
uint32_t spinfo_mtu; uint32_t spinfo_mtu;
}; };
spinfo_assoc_id: This parameter is ignored for one-to-one style spinfo_assoc_id: This parameter is ignored for one-to-one style
sockets. For one-to-many style sockets the following applies: sockets. For one-to-many style sockets the following applies:
This field may be filled by the application, if so, this field This field may be filled by the application, if so, this field
will have priority in looking up the association using the address will have priority in looking up the association using the address
specified in spinfo_address. Note that if the address does not specified in spinfo_address. Note that if the address does not
belong to the association specified then this call will fail. If belong to the association specified then this call will fail. If
the application does NOT fill in the spinfo_assoc_id, then the the application does not fill in the spinfo_assoc_id, then the
address will be used to lookup the association and on return this address will be used to lookup the association and on return this
field will have the valid association id. In other words, this field will have the valid association id. In other words, this
call can be used to translate an address into an association id. call can be used to translate an address into an association id.
Note that the predefined constants are not allowed on this option. Note that the predefined constants are not allowed on this option.
spinfo_address: This is filled by the application, and contains the spinfo_address: This is filled by the application, and contains the
peer address of interest. peer address of interest.
spinfo_state: This contains the peer address' state (either spinfo_state: This contains the peer address' state (either
SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier SCTP_ACTIVE or SCTP_INACTIVE and possibly the modifier
SCTP_UNCONFIRMED). SCTP_UNCONFIRMED).
spinfo_cwnd: This contains the peer address' current congestion spinfo_cwnd: This contains the peer address' current congestion
window. window.
spinfo_srtt: This contains the peer address' current smoothed round- spinfo_srtt: This contains the peer address' current smoothed round-
trip time calculation in milliseconds. trip time calculation in milliseconds.
spinfo_rto: This contains the peer address' current retransmission spinfo_rto: This contains the peer address' current retransmission
timeout value in milliseconds. timeout value in milliseconds.
spinfo_mtu: The current P-MTU of this address. spinfo_mtu: The current P-MTU of this address.
skipping to change at page 70, line 15 skipping to change at page 73, line 41
requesting to be authenticated. requesting to be authenticated.
The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH The chunk types for INIT, INIT-ACK, SHUTDOWN-COMPLETE, and AUTH
chunks must not be used. If they are used, an error must be chunks must not be used. If they are used, an error must be
returned. The usage of this option enables SCTP AUTH in cases where returned. The usage of this option enables SCTP AUTH in cases where
it is not required by other means (for example the use of dynamic it is not required by other means (for example the use of dynamic
address reconfiguration). address reconfiguration).
7.3.3. Set a Shared Key (SCTP_AUTH_KEY) 7.3.3. Set a Shared Key (SCTP_AUTH_KEY)
This option will set a shared secret key which is used to build an This option will set a shared secret key that is used to build an
association shared key. association shared key.
The following structure is used to access and modify these The following structure is used to access and modify these
parameters: parameters:
struct sctp_authkey { struct sctp_authkey {
sctp_assoc_t sca_assoc_id; sctp_assoc_t sca_assoc_id;
uint16_t sca_keynumber; uint16_t sca_keynumber;
uint16_t sca_keylength; uint16_t sca_keylength;
uint8_t sca_key[]; uint8_t sca_key[];
skipping to change at page 71, line 46 skipping to change at page 75, line 24
option will delete the key from the association if the socket is option will delete the key from the association if the socket is
connected, otherwise this will delete the key from the endpoint. connected, otherwise this will delete the key from the endpoint.
scact_keynumber: This parameter is the shared key identifier which scact_keynumber: This parameter is the shared key identifier which
the application is requesting to be deleted. The key identifier the application is requesting to be deleted. The key identifier
must correspond to an existing shared key and must not be in use must correspond to an existing shared key and must not be in use
for any packet being sent by the SCTP implementation. This means for any packet being sent by the SCTP implementation. This means
in particular, that it must be deactivated first. Note if this in particular, that it must be deactivated first. Note if this
parameter is zero, use of the null key identifier '0' is deleted parameter is zero, use of the null key identifier '0' is deleted
from the endpoint and/or association. from the endpoint and/or association.
Only deactivated keys which are no longer used by the association can Only deactivated keys that are no longer used by the association can
be deleted. be deleted.
7.4. Ancillary Data and Notification Interest Options 7.4. Ancillary Data and Notification Interest Options
Applications can receive per-message ancillary information and Applications can receive per-message ancillary information and
notifications of certain SCTP events with recvmsg(). notifications of certain SCTP events with recvmsg().
The following optional information is available to the application: The following optional information is available to the application:
SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e.
stream number, TSN, SSN, etc. described in Section 5.2.2) stream number, TSN, SSN, etc. described in Section 5.2.2)
skipping to change at page 73, line 48 skipping to change at page 77, line 33
memset(&events,0,sizeof(events)); memset(&events,0,sizeof(events));
events.sctp_data_io_event = 1; events.sctp_data_io_event = 1;
events.sctp_association_event = 1; events.sctp_association_event = 1;
setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events));
} }
Note that for one-to-many style SCTP sockets, the caller of recvmsg() Note that for one-to-many style SCTP sockets, the caller of recvmsg()
receives ancillary data and notifications for ALL associations bound receives ancillary data and notifications for all associations bound
to the file descriptor. For one-to-one style SCTP sockets, the to the file descriptor. For one-to-one style SCTP sockets, the
caller receives ancillary data and notifications only for the single caller receives ancillary data and notifications only for the single
association bound to the file descriptor. association bound to the file descriptor.
The SCTP_EVENTS socket option has one issue for future compatibility. The SCTP_EVENTS socket option has one issue for future compatibility.
As new features are added the structure (sctp_event_subscribe) must As new features are added the structure (sctp_event_subscribe) must
be expanded. This can cause an ABI issue unless an implementation be expanded. This can cause an application binary interface (ABI)
has added padding at the end of the structure. To avoid this issue unless an implementation has added padding at the end of the
problem, SCTP_EVENTS has been deprecated and a new option SCTP_EVENT structure. To avoid this problem, SCTP_EVENTS has been deprecated
socket option has taken its place. The option is used with the and a new option SCTP_EVENT socket option has taken its place. The
following structure: option is used with the following structure:
struct sctp_event { struct sctp_event {
sctp_assoc_t se_assoc_id; sctp_assoc_t se_assoc_id;
uint16_t se_type; uint16_t se_type;
uint8_t se_on; uint8_t se_on;
}; };
se_assoc_id: The se_assoc_id field is ignored for one-to-one style se_assoc_id: The se_assoc_id field is ignored for one-to-one style
sockets. For one-to-many style sockets any this field can be a sockets. For one-to-many style sockets any this field can be a
particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC.
se_type: The se_type field can be filled with any value that would se_type: The se_type field can be filled with any value that would
show up in the respective sn_type field (in the sctp_tlv structure show up in the respective sn_type field (in the sctp_tlv structure
of the notification). In addition SCTP_SNDRCV_EVENT, of the notification).
SCTP_RCV_EVENT, and SCTP_NXT_EVENT can be used.
se_on: The se_on field is set to 1 to turn on an event and set to 0 se_on: The se_on field is set to 1 to turn on an event and set to 0
to turn off an event. to turn off an event.
To use this option the user fills in this structure and then calls To use this option the user fills in this structure and then calls
the setsockopt to turn on or off an individual event. The following the setsockopt to turn on or off an individual event. The following
is an example use of this option: is an example use of this option:
{ {
struct sctp_event event; struct sctp_event event;
skipping to change at page 75, line 28 skipping to change at page 79, line 12
If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. If sd is an IPv4 socket, the addresses passed must be IPv4 addresses.
If the sd is an IPv6 socket, the addresses passed can either be IPv4 If the sd is an IPv6 socket, the addresses passed can either be IPv4
or IPv6 addresses. or IPv6 addresses.
A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see
Section 3.1.2 for this usage. Section 3.1.2 for this usage.
addrs is a pointer to an array of one or more socket addresses. Each addrs is a pointer to an array of one or more socket addresses. Each
address is contained in its appropriate structure. For an IPv6 address is contained in its appropriate structure. For an IPv6
socket, an array of sockaddr_in6 is used. For a IPv4 socket, an socket, an array of sockaddr_in6 is used. For a IPv4 socket, an
array of sockaddr_in would is used. The caller specifies the number array of sockaddr_in is used. The caller specifies the number of
of addresses in the array with addrcnt. Note that the wildcard addresses in the array with addrcnt. Note that the wildcard
addresses cannot be used in combination with non wildcard addresses addresses cannot be used in combination with non wildcard addresses
on a socket with this function, doing so will result in an error. on a socket with this function, doing so will result in an error.
On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns
-1 and sets errno to the appropriate error code. -1 and sets errno to the appropriate error code.
For SCTP, the port given in each socket address must be the same, or For SCTP, the port given in each socket address must be the same, or
sctp_bindx() will fail, setting errno to EINVAL. sctp_bindx() will fail, setting errno to EINVAL.
The flags parameter is formed from the bitwise OR of zero or more of The flags parameter is formed from the bitwise OR of zero or more of
skipping to change at page 76, line 5 skipping to change at page 79, line 38
association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the given
addresses from the association. The two flags are mutually addresses from the association. The two flags are mutually
exclusive; if both are given, sctp_bindx() will fail with EINVAL. A exclusive; if both are given, sctp_bindx() will fail with EINVAL. A
caller may not remove all addresses from an association; sctp_bindx() caller may not remove all addresses from an association; sctp_bindx()
will reject such an attempt with EINVAL. will reject such an attempt with EINVAL.
An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate
additional addresses with an endpoint after calling bind(). Or use additional addresses with an endpoint after calling bind(). Or use
sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening
socket is associated with, so that no new association accepted will socket is associated with, so that no new association accepted will
be associated with those addresses. If the endpoint supports dynamic be associated with these addresses. If the endpoint supports dynamic
address reconfiguration an SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR address reconfiguration an SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR
may cause an endpoint to send the appropriate message to the peer to may cause an endpoint to send the appropriate message to the peer to
change the peer's address lists. change the peer's address lists.
Adding and removing addresses from a connected association is an Adding and removing addresses from a connected association is an
optional functionality. Implementations that do not support this optional functionality. Implementations that do not support this
functionality should return EOPNOTSUPP. functionality should return EOPNOTSUPP.
sctp_bindx() can be called on an already bound socket or on an sctp_bindx() can be called on an already bound socket or on an
unbound socket. If the socket is unbound and the first port number unbound socket. If the socket is unbound and the first port number
skipping to change at page 76, line 37 skipping to change at page 80, line 22
with only one address sequentially. with only one address sequentially.
8.2. sctp_peeloff() 8.2. sctp_peeloff()
After an association is established on a one-to-many style socket, After an association is established on a one-to-many style socket,
the application may wish to branch off the association into a the application may wish to branch off the association into a
separate socket/file descriptor. separate socket/file descriptor.
This is particularly desirable when, for instance, the application This is particularly desirable when, for instance, the application
wishes to have a number of sporadic message senders/receivers remain wishes to have a number of sporadic message senders/receivers remain
under the original one-to-many style socket but branch off those under the original one-to-many style socket, but branch off these
associations carrying high volume data traffic into their own associations carrying high volume data traffic into their own
separate socket descriptors. separate socket descriptors.
The application uses the sctp_peeloff() call to branch off an The application uses the sctp_peeloff() call to branch off an
association into a separate socket (Note the semantics are somewhat association into a separate socket (Note the semantics are somewhat
changed from the traditional one-to-one style accept() call). Note changed from the traditional one-to-one style accept() call). Note
that the new socket is a one-to-one style socket. Thus it will be that the new socket is a one-to-one style socket. Thus it will be
confined to operations allowed for a one-to-one style socket. confined to operations allowed for a one-to-one style socket.
The function prototype is The function prototype is
skipping to change at page 78, line 14 skipping to change at page 81, line 48
sctp_getpaddrs(). sctp_getpaddrs().
8.5. sctp_getladdrs() 8.5. sctp_getladdrs()
sctp_getladdrs() returns all locally bound address(es) on a socket. sctp_getladdrs() returns all locally bound address(es) on a socket.
The function prototype is The function prototype is
int sctp_getladdrs(int sd, int sctp_getladdrs(int sd,
sctp_assoc_t id, sctp_assoc_t id,
struct sockaddr **ss); struct sockaddr **addrs);
On return, addrs will point to a dynamically allocated array of On return, addrs will point to a dynamically allocated array of
sockaddr structures of the appropriate type for the socket type. The sockaddr structures of the appropriate type for the socket type. The
caller should use sctp_freeladdrs() to free the memory. Note that caller should use sctp_freeladdrs() to free the memory. Note that
the in/out parameter addrs must not be NULL. the in/out parameter addrs must not be NULL.
If sd is an IPv4 socket, the addresses returned will be all IPv4 If sd is an IPv4 socket, the addresses returned will be all IPv4
addresses. If sd is an IPv6 socket, the addresses returned can be a addresses. If sd is an IPv6 socket, the addresses returned can be a
mix of IPv4 or IPv6 addresses. mix of IPv4 or IPv6 addresses.
skipping to change at page 79, line 19 skipping to change at page 83, line 4
size_t len, size_t len,
const struct sockaddr *to, const struct sockaddr *to,
socklen_t tolen, socklen_t tolen,
uint32_t ppid, uint32_t ppid,
uint32_t flags, uint32_t flags,
uint16_t stream_no, uint16_t stream_no,
uint32_t pr_value, uint32_t pr_value,
uint32_t context); uint32_t context);
and the arguments are: and the arguments are:
sd: The socket descriptor
sd: The socket descriptor.
msg: The message to be sent. msg: The message to be sent.
len: The length of the message. len: The length of the message.
to: The destination address of the message. to: The destination address of the message.
tolen: The length of the destination address. tolen: The length of the destination address.
ppid: The same as sinfo_ppid (see Section 5.2.2) ppid: The same as sinfo_ppid (see Section 5.2.2).
flags: The same as sinfo_flags (see Section 5.2.2) flags: The same as sinfo_flags (see Section 5.2.2).
stream_no: The same as sinfo_stream (see Section 5.2.2) stream_no: The same as sinfo_stream (see Section 5.2.2).
pr_value: The same as sinfo_pr_value (see Section 5.2.2). pr_value: The same as sinfo_pr_value (see Section 5.2.2).
context: The same as sinfo_context (see Section 5.2.2) context: The same as sinfo_context (see Section 5.2.2).
The call returns the number of characters sent, or -1 if an error The call returns the number of characters sent, or -1 if an error
occurred. The variable errno is then set appropriately. occurred. The variable errno is then set appropriately.
Sending a message using sctp_sendmsg() is atomic (unless explicit EOR Sending a message using sctp_sendmsg() is atomic (unless explicit EOR
marking is enabled on the socket specified by sd). marking is enabled on the socket specified by sd).
Using sctp_sendmsg() on a non-connected one-to-one style socket for Using sctp_sendmsg() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP implicit connection setup may or may not work depending on the SCTP
implementation. implementation.
8.8. sctp_recvmsg() 8.8. sctp_recvmsg()
This function is deprecated.
An implementation may provide a library function (or possibly system An implementation may provide a library function (or possibly system
call) to assist the user with the advanced features of SCTP. Note call) to assist the user with the advanced features of SCTP. Note
that in order for the sctp_sndrcvinfo structure to be filled in by that in order for the sctp_sndrcvinfo structure to be filled in by
sctp_recvmsg() the caller must enable the sctp_data_io_events with sctp_recvmsg() the caller must enable the sctp_data_io_events with
the SCTP_EVENTS option. Note that the setting of the the SCTP_EVENTS option. Note that the setting of the
SCTP_USE_EXT_RCVINFO will affect this function as well, causing the SCTP_USE_EXT_RCVINFO will affect this function as well, causing the
sctp_sndrcvinfo information to be extended. sctp_sndrcvinfo information to be extended.
The function prototype is The function prototype is
ssize_t sctp_recvmsg(int sd, ssize_t sctp_recvmsg(int sd,
void *msg, void *msg,
size_t len, size_t len,
struct sockaddr *from, struct sockaddr *from,
socklen_t *fromlen socklen_t *fromlen
struct sctp_sndrcvinfo *sinfo struct sctp_sndrcvinfo *sinfo
int *msg_flags); int *msg_flags);
and the arguments are and the arguments are
sd: The socket descriptor. sd: The socket descriptor.
skipping to change at page 81, line 22 skipping to change at page 85, line 15
addrcnt: The number of addresses in the array. addrcnt: The number of addresses in the array.
id: An output parameter that if passed in as a non-NULL will return id: An output parameter that if passed in as a non-NULL will return
the association identification for the newly created association the association identification for the newly created association
(if successful). (if successful).
The call returns 0 on success or -1 if an error occurred. The The call returns 0 on success or -1 if an error occurred. The
variable errno is then set appropriately. variable errno is then set appropriately.
8.10. sctp_send() 8.10. sctp_send()
This function is deprecated.
An implementation may provide another alternative function or system An implementation may provide another alternative function or system
call to assist an application with the sending of data without the call to assist an application with the sending of data without the
use of the CMSG header structures. use of the CMSG header structures.
The function prototype is The function prototype is
ssize_t sctp_send(int sd, ssize_t sctp_send(int sd,
const void *msg, const void *msg,
size_t len, size_t len,
const struct sctp_sndrcvinfo *sinfo, const struct sctp_sndrcvinfo *sinfo,
int flags); int flags);
and the arguments are and the arguments are
sd: The socket descriptor. sd: The socket descriptor.
msg: The message to be sent. msg: The message to be sent.
len: The length of the message. len: The length of the message.
sinfo: A pointer to an sctp_sndrcvinfo structure used as described sinfo: A pointer to an sctp_sndrcvinfo structure used as described
in Section 5.2.2 for a sendmsg call. in Section 5.2.2 for a sendmsg call.
flags: The same flags as used by the sendmsg call flags (e.g. flags: The same flags as used by the sendmsg() call flags (e.g.
MSG_DONTROUTE). MSG_DONTROUTE).
The call returns the number of bytes sent, or -1 if an error The call returns the number of bytes sent, or -1 if an error
occurred. The variable errno is then set appropriately. occurred. The variable errno is then set appropriately.
This function call may also be used to terminate an association using This function call may also be used to terminate an association using
an association identification by setting the sinfo.sinfo_flags to an association identification by setting the sinfo.sinfo_flags to
SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs SCTP_EOF and the sinfo.sinfo_assoc_id to the association that needs
to be terminated. In such a case the len of the message would be to be terminated. In such a case the len of the message would be
zero. zero.
Using sctp_send() on a non-connected one-to-one style socket for Using sctp_send() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP implicit connection setup may or may not work depending on the SCTP
implementation. implementation.
Sending a message using sctp_send() is atomic unless explicit EOR Sending a message using sctp_send() is atomic unless explicit EOR
marking is enabled on the socket specified by sd. marking is enabled on the socket specified by sd.
8.11. sctp_sendx() 8.11. sctp_sendx()
This function is deprecated.
An implementation may provide another alternative function or system An implementation may provide another alternative function or system
call to assist an application with the sending of data without the call to assist an application with the sending of data without the
use of the CMSG header structures that also gives a list of use of the CMSG header structures that also gives a list of
addresses. The list of addresses is provided for implicit addresses. The list of addresses is provided for implicit
association setup. In such a case the list of addresses serves the association setup. In such a case the list of addresses serves the
same purpose as the addresses given in sctp_connectx() (see same purpose as the addresses given in sctp_connectx() (see
Section 8.9). Section 8.9).
The function prototype is The function prototype is
skipping to change at page 82, line 37 skipping to change at page 86, line 34
struct sctp_sndrcvinfo *sinfo, struct sctp_sndrcvinfo *sinfo,
int flags); int flags);
and the arguments are: and the arguments are:
sd: The socket descriptor. sd: The socket descriptor.
msg: The message to be sent. msg: The message to be sent.
len: The length of the message. len: The length of the message.
addrs: is an array of addresses. addrs: is an array of addresses.
addrcnt: The number of addresses in the array. addrcnt: The number of addresses in the array.
sinfo: A pointer to a sctp_sndrcvinfo structure used as described in sinfo: A pointer to a sctp_sndrcvinfo structure used as described in
Section 5.2.2 for a sendmsg call. Section 5.2.2 for a sendmsg() call.
flags: The same flags as used by the sendmsg call flags (e.g. flags: The same flags as used by the sendmsg() call flags (e.g.
MSG_DONTROUTE). MSG_DONTROUTE).
The call returns the number of bytes sent, or -1 if an error The call returns the number of bytes sent, or -1 if an error
occurred. The variable errno is then set appropriately. occurred. The variable errno is then set appropriately.
Note that on return from this call the sinfo structure will have Note that on return from this call the sinfo structure will have
changed in that the sinfo_assoc_id will be filled in with the new changed in that the sinfo_assoc_id will be filled in with the new
association id. association id.
This function call may also be used to terminate an association using This function call may also be used to terminate an association using
an association identification by setting the sinfo.sinfo_flags to an association identification by setting the sinfo.sinfo_flags to
skipping to change at page 83, line 12 skipping to change at page 87, line 9
to be terminated. In such a case the len of the message would be to be terminated. In such a case the len of the message would be
zero. zero.
Sending a message using sctp_send() is atomic unless explicit EOR Sending a message using sctp_send() is atomic unless explicit EOR
marking is enabled on the socket specified by sd. marking is enabled on the socket specified by sd.
Using sctp_sendx() on a non-connected one-to-one style socket for Using sctp_sendx() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP implicit connection setup may or may not work depending on the SCTP
implementation. implementation.
8.12. sctp_getaddrlen() 8.12. sctp_recvxxx()
For application binary portability it is sometimes desirable to know An implementation may provide a library function (or possibly system
what the kernel thinks is the length of a socket address family. call) to assist the user with the advanced features of SCTP. Note
that in order for the sctp_recvinfo structure to be filled in by
sctp_recvxxx() the caller must set the SCTP_RECVRCVINFO and
SCTP_RECVNXTINFO socket option.
The function prototype is: The function prototype is
int sctp_getaddrlen(sa_family_t family); struct sctp_recvinfo {
uint16_t recv_version;
uint16_t recv_length;
struct sctp_rcvinfo recv_rcvinfo;
struct sctp_rcvinfo recv_nxtinfo;
};
This function, when called with a valid family type returns the ssize_t sctp_recvxxx(int sd,
length that the operating system uses in the specified family's void *msg,
socket address structure. In case of an error, -1 is returned and size_t len,
the variable errno is then set appropriately. struct sockaddr *from,
socklen_t *fromlen
struct sctp_recvinfo *info
int *msg_flags);
and the arguments are
sd: The socket descriptor.
msg: The message buffer to be filled.
len: The length of the message buffer.
from: A pointer to an address to be filled with the sender of this
messages address.
fromlen: An in/out parameter describing the from length.
info: A pointer to an sctp_recvinfo structure to be filled upon
receipt of the message.
msg_flags: A pointer to an integer to be filled with any message
flags (e.g. MSG_NOTIFICATION). Note that this field is an in-out
field. Options for the receive may also be passed into the value
(e.g. MSG_PEEK). On return from the call, the msg_flags value
will be different than what was sent in to the call. If
implemented via a recvmsg() call, the msg_flags should only
contain the value of the flags from the recvmsg() call.
The call returns the number of bytes received, or -1 if an error
occurred. The variable errno is then set appropriately.
8.13. sctp_sendxxx()
An implementation may provide another alternative function or system
call to assist an application with the sending of data without the
use of the CMSG header structures that also gives a list of
addresses. The list of addresses is provided for implicit
association setup. In such a case the list of addresses serves the
same purpose as the addresses given in sctp_connectx() (see
Section 8.9).
The function prototype is
struct sctp_sendinfo {
uint16_t send_version;
uint16_t send_length;
struct sctp_sndinfo send_sndinfo;
struct sctp_prinfo send_prinfo;
struct sctp_authinfo send_authinfo;
};
ssize_t sctp_sendxxx(int sd,
const void *msg,
size_t len,
struct sockaddr *addrs,
int addrcnt,
struct sctp_sendinfo *info,
int flags);
and the arguments are:
sd: The socket descriptor.
msg: The message to be sent.
len: The length of the message.
addrs: is an array of addresses.
addrcnt: The number of addresses in the array.
sinfo: A pointer to a sctp_sendinfo structure.
flags: The same flags as used by the sendmsg() call flags (e.g.
MSG_DONTROUTE).
The call returns the number of bytes sent, or -1 if an error
occurred. The variable errno is then set appropriately.
Note that on return from this call the sinfo structure will have
changed in that the send_sndinfo.snd_sid will be filled in with the
new association id.
This function call may also be used to terminate an association using
an association identification by setting the send_sndinfo.snd_flags
to SCTP_EOF and the send_sndinfo.snd_sid to the association that
needs to be terminated. In such a case the len of the message would
be zero.
Sending a message using sctp_sendxxx() is atomic unless explicit EOR
marking is enabled on the socket specified by sd.
Using sctp_sendxxx() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP
implementation.
9. IANA Considerations 9. IANA Considerations
This document requires no actions from IANA. This document requires no actions from IANA.
10. Security Considerations 10. Security Considerations
Many TCP and UDP implementations reserve port numbers below 1024 for Many TCP and UDP implementations reserve port numbers below 1024 for
privileged users. If the target platform supports privileged users, privileged users. If the target platform supports privileged users,
the SCTP implementation should restrict the ability to call bind() or the SCTP implementation should restrict the ability to call bind() or
sctp_bindx() on these port numbers to privileged users. sctp_bindx() on these port numbers to privileged users.
Similarly unprivileged users should not be able to set protocol Similarly unprivileged users should not be able to set protocol
parameters which could result in the congestion control algorithm parameters that could result in the congestion control algorithm
being more aggressive than permitted on the public Internet. These being more aggressive than permitted on the public Internet. These
parameters are: parameters are:
o struct sctp_rtoinfo o struct sctp_rtoinfo
If an unprivileged user inherits a one-to-many style socket with open If an unprivileged user inherits a one-to-many style socket with open
associations on a privileged port, it may be permitted to accept new associations on a privileged port, it may be permitted to accept new
associations, but it should not be permitted to open new associations, but it should not be permitted to open new
associations. This could be relevant for the r* family of protocols. associations. This could be relevant for the r* family of protocols.
Applications using the one-to-many style sockets and using the Applications using the one-to-many style sockets and using the
skipping to change at page 84, line 20 skipping to change at page 90, line 9
The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon The authors also wish to thank Kavitha Baratakke, Mike Bartlett, Jon
Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink,
Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG
mailing list for contributing valuable comments. mailing list for contributing valuable comments.
A special thanks to Phillip Conrad, for his suggested text, quick and A special thanks to Phillip Conrad, for his suggested text, quick and
constructive insights, and most of all his persistent fighting to constructive insights, and most of all his persistent fighting to
keep the interface to SCTP usable for the application programmer. keep the interface to SCTP usable for the application programmer.
12. Normative References 12. References
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, September 1981.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
August 1980.
[RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions 12.1. Normative References
Functional Specification", RFC 1644, July 1994.
[RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
Stevens, "Basic Socket Interface Extensions for IPv6", Stevens, "Basic Socket Interface Extensions for IPv6",
RFC 3493, February 2003. RFC 3493, February 2003.
[RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei,
"Advanced Sockets Application Program Interface (API) for "Advanced Sockets Application Program Interface (API) for
IPv6", RFC 3542, May 2003. IPv6", RFC 3542, May 2003.
[RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P.
skipping to change at page 85, line 7 skipping to change at page 90, line 37
Protocol (SCTP)", RFC 4895, August 2007. Protocol (SCTP)", RFC 4895, August 2007.
[RFC4960] Stewart, R., "Stream Control Transmission Protocol", [RFC4960] Stewart, R., "Stream Control Transmission Protocol",
RFC 4960, September 2007. RFC 4960, September 2007.
[RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M. [RFC5061] Stewart, R., Xie, Q., Tuexen, M., Maruyama, S., and M.
Kozuka, "Stream Control Transmission Protocol (SCTP) Kozuka, "Stream Control Transmission Protocol (SCTP)
Dynamic Address Reconfiguration", RFC 5061, Dynamic Address Reconfiguration", RFC 5061,
September 2007. September 2007.
12.2. Informative References
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, September 1981.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
August 1980.
[RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions
Functional Specification", RFC 1644, July 1994.
Appendix A. One-to-One Style Code Example Appendix A. One-to-One Style Code Example
The following code is a simple implementation of an echo server over The following code is a simple implementation of an echo server over
SCTP. The example shows how to use some features of one-to-one style SCTP. The example shows how to use some features of one-to-one style
IPv4 SCTP sockets, including: IPv4 SCTP sockets, including:
o Opening, binding, and listening for new associations on a socket o Opening, binding, and listening for new associations on a socket
o Enabling ancillary data o Enabling ancillary data
o Enabling notifications o Enabling notifications
o Using ancillary data with sendmsg() and recvmsg() o Using ancillary data with sendmsg() and recvmsg()
o Using MSG_EOR to determine if an entire message has been read o Using MSG_EOR to determine if an entire message has been read
skipping to change at page 86, line 50 skipping to change at page 92, line 43
static void * static void *
mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, mysctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen,
ssize_t *nrp, size_t cmsglen) ssize_t *nrp, size_t cmsglen)
{ {
ssize_t nr = 0, nnr = 0; ssize_t nr = 0, nnr = 0;
struct iovec iov; struct iovec iov;
*nrp = 0; *nrp = 0;
iov.iov_base = buf; iov.iov_base = buf;
iov.iov_len = *buflen; iov.iov_len = *buflen;
msg->msg_iov = � msg->msg_iov = &iov;
msg->msg_iovlen = 1; msg->msg_iovlen = 1;
for (;;) { for (;;) {
#ifndef MSG_XPG4_2 #ifndef MSG_XPG4_2
#define MSG_XPG4_2 0 #define MSG_XPG4_2 0
#endif #endif
msg->msg_flags = MSG_XPG4_2; msg->msg_flags = MSG_XPG4_2;
msg->msg_controllen = cmsglen; msg->msg_controllen = cmsglen;
nnr = recvmsg(fd, msg, 0); nnr = recvmsg(fd, msg, 0);
if (nnr <= 0) { if (nnr <= 0) {
/* EOF or error */ /* EOF or error */
*nrp = nr; *nrp = nr;
return (NULL); return (NULL);
} }
nr += nnr; nr += nnr;
if ((msg->msg_flags & MSG_EOR) != 0) { if ((msg->msg_flags & MSG_EOR) != 0) {
*nrp = nr; *nrp = nr;
skipping to change at page 88, line 30 skipping to change at page 94, line 23
buf, &buflen, &nr, cmsglen)) { buf, &buflen, &nr, cmsglen)) {
/* Intercept notifications here */ /* Intercept notifications here */
if (msg.msg_flags & MSG_NOTIFICATION) { if (msg.msg_flags & MSG_NOTIFICATION) {
handle_event(buf); handle_event(buf);
continue; continue;
} }
iov.iov_base = buf; iov.iov_base = buf;
iov.iov_len = nr; iov.iov_len = nr;
msg.msg_iov = &#65533; msg.msg_iov = &iov;
msg.msg_iovlen = 1; msg.msg_iovlen = 1;
printf("got %u bytes on stream %hu:\n", nr, printf("got %u bytes on stream %hu:\n", nr,
sri->sinfo_stream); sri->sinfo_stream);
write(0, buf, nr); write(0, buf, nr);
/* Echo it back */ /* Echo it back */
msg.msg_flags = MSG_XPG4_2; msg.msg_flags = MSG_XPG4_2;
if (sendmsg(fd, &msg, 0) < 0) { if (sendmsg(fd, &msg, 0) < 0) {
perror("sendmsg"); perror("sendmsg");
skipping to change at page 91, line 41 skipping to change at page 97, line 38
Authors' Addresses Authors' Addresses
Randall R. Stewart Randall R. Stewart
Huawei Huawei
Chapin, SC 29036 Chapin, SC 29036
USA USA
Email: rstewart@huawei.com Email: rstewart@huawei.com
Kacheong Poon Kacheong Poon
Sun Microsystems, Inc. Oracle Corporation
4150 Network Circle
Santa Clara, CA 95054 Email: ka-cheong.poon@oracle.com
USA
Email: kacheong.poon@sun.com
Michael Tuexen Michael Tuexen
Muenster Univ. of Applied Sciences Muenster University of Applied Sciences
Stegerwaldstr. 39 Stegerwaldstr. 39
48565 Steinfurt 48565 Steinfurt
Germany Germany
Email: tuexen@fh-muenster.de Email: tuexen@fh-muenster.de
Vladislav Yasevich Vladislav Yasevich
HP HP
110 Spitrook Rd 110 Spitrook Rd
Nashua, NH, 03062 Nashua, NH 03062
USA USA
Email: vladislav.yasevich@hp.com Email: vladislav.yasevich@hp.com
Peter Lei Peter Lei
Cisco Systems, Inc. Cisco Systems, Inc.
8735 West Higgins Road 8735 West Higgins Road
Suite 300 Suite 300
Chicago, IL 60631 Chicago, IL 60631
USA USA
 End of changes. 148 change blocks. 
343 lines changed or deleted 561 lines changed or added

This html diff was produced by rfcdiff 1.38. The latest version is available from http://tools.ietf.org/tools/rfcdiff/