draft-ietf-tsvwg-sctpsocket-15.txt   draft-ietf-tsvwg-sctpsocket-16.txt 
Network Working Group R. Stewart Network Working Group R. Stewart
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Expires: January 10, 2008 Q. Xie Intended status: Informational Q. Xie
Motorola, Inc. Expires: August 27, 2008 Motorola, Inc.
L. Yarroll L. Yarroll
TimeSys Corp TimeSys Corp
K. Poon K. Poon
Sun Microsystems, Inc. Sun Microsystems, Inc.
M. Tuexen M. Tuexen
Univ. of Applied Sciences Muenster Univ. of Applied Sciences Muenster
July 9, 2007 V. Yasevich
HP
February 24, 2008
Sockets API Extensions for Stream Control Transmission Protocol (SCTP) Sockets API Extensions for Stream Control Transmission Protocol (SCTP)
draft-ietf-tsvwg-sctpsocket-15.txt draft-ietf-tsvwg-sctpsocket-16.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of 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), its areas, and its working groups. Note that
skipping to change at page 1, line 41 skipping to change at page 1, line 43
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 The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 10, 2008. This Internet-Draft will expire on August 27, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2007).
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.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6
3. one-to-many style Interface . . . . . . . . . . . . . . . . . 6 3. one-to-many style Interface . . . . . . . . . . . . . . . . . 6
3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 6
3.1.1. socket() - one-to-many style socket . . . . . . . . . 7 3.1.1. socket() - one-to-many style socket . . . . . . . . . 7
3.1.2. bind() - one-to-many style socket . . . . . . . . . . 8 3.1.2. bind() - one-to-many style socket . . . . . . . . . . 8
3.1.3. listen() - One-to-many style socket . . . . . . . . . 9 3.1.3. listen() - One-to-many style socket . . . . . . . . . 9
3.1.4. sendmsg() and recvmsg() - one-to-many style socket . . 9 3.1.4. sendmsg() and recvmsg() - one-to-many style socket . . 9
3.1.5. close() - one-to-many style socket . . . . . . . . . . 11 3.1.5. close() - one-to-many style socket . . . . . . . . . . 11
3.1.6. connect() - one-to-many style socket . . . . . . . . . 11 3.1.6. connect() - one-to-many style socket . . . . . . . . . 12
3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12 3.2. Implicit Association Setup . . . . . . . . . . . . . . . . 12
3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 3.3. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13
3.4. Special considerations . . . . . . . . . . . . . . . . . . 13 3.4. Special considerations . . . . . . . . . . . . . . . . . . 14
4. one-to-one style Interface . . . . . . . . . . . . . . . . . . 15 4. one-to-one style Interface . . . . . . . . . . . . . . . . . . 15
4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 15 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 15
4.1.1. socket() - one-to-one style socket . . . . . . . . . . 16 4.1.1. socket() - one-to-one style socket . . . . . . . . . . 16
4.1.2. bind() - one-to-one style socket . . . . . . . . . . . 16 4.1.2. bind() - one-to-one style socket . . . . . . . . . . . 17
4.1.3. listen() - one-to-one style socket . . . . . . . . . . 17 4.1.3. listen() - one-to-one style socket . . . . . . . . . . 18
4.1.4. accept() - one-to-one style socket . . . . . . . . . . 18 4.1.4. accept() - one-to-one style socket . . . . . . . . . . 18
4.1.5. connect() - one-to-one style socket . . . . . . . . . 18 4.1.5. connect() - one-to-one style socket . . . . . . . . . 18
4.1.6. close() - one-to-one style socket . . . . . . . . . . 19 4.1.6. close() - one-to-one style socket . . . . . . . . . . 19
4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 19 4.1.7. shutdown() - one-to-one style socket . . . . . . . . . 20
4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20 4.1.8. sendmsg() and recvmsg() - one-to-one style socket . . 20
4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 20 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 21
5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 21
5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 21
5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22 5.2. SCTP msg_control Structures . . . . . . . . . . . . . . . 22
5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23 5.2.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 23
5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 24 5.2.2. SCTP Header Information Structure (SCTP_SNDRCV) . . . 25
5.2.3. Extended SCTP Header Information Structure 5.2.3. Extended SCTP Header Information Structure
(SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 27 (SCTP_EXTRCV) . . . . . . . . . . . . . . . . . . . . 27
5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 29 5.3. SCTP Events and Notifications . . . . . . . . . . . . . . 29
5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 29 5.3.1. SCTP Notification Structure . . . . . . . . . . . . . 30
5.4. Ancillary Data Considerations and Semantics . . . . . . . 40 5.4. Ancillary Data Considerations and Semantics . . . . . . . 41
5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 40 5.4.1. Multiple Items and Ordering . . . . . . . . . . . . . 41
5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 40 5.4.2. Accessing and Manipulating Ancillary Data . . . . . . 42
5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 41 5.4.3. Control Message Buffer Sizing . . . . . . . . . . . . 42
6. Common Operations for Both Styles . . . . . . . . . . . . . . 42 6. Common Operations for Both Styles . . . . . . . . . . . . . . 43
6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 42 6.1. send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 43
6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 43 6.2. setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 44
6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 44 6.3. read() and write() . . . . . . . . . . . . . . . . . . . . 45
6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 44 6.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 45
7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 45 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . . . 46
7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 46 7.1. Read / Write Options . . . . . . . . . . . . . . . . . . . 48
7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 46 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . . 48
7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 47 7.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 48
7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 49 7.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . . 50
7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 49 7.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 50
7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 49 7.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . 50
7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 49 7.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 51
7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 50 7.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 51
7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 50 7.1.8. Automatic Close of associations (SCTP_AUTOCLOSE) . . . 51
7.1.9. Set Peer Primary Address 7.1.9. Set Peer Primary Address
(SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 50 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . . 51
7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 51 7.1.10. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 52
7.1.11. Set Adaptation Layer Indicator 7.1.11. Set Adaptation Layer Indicator
(SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 51 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 52
7.1.12. Enable/Disable message fragmentation 7.1.12. Enable/Disable message fragmentation
(SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 51 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . 53
7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 52 7.1.13. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 53
7.1.14. Set default send parameters 7.1.14. Set default send parameters
(SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 54 (SCTP_DEFAULT_SEND_PARAM) . . . . . . . . . . . . . . 55
7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 54 7.1.15. Set notification and ancillary events (SCTP_EVENTS) . 56
7.1.16. Set/clear IPv4 mapped addresses 7.1.16. Set/clear IPv4 mapped addresses
(SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 54 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . 56
7.1.17. Get or set the maximum fragmentation size 7.1.17. Get or set the maximum fragmentation size
(SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 55 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 56
7.1.18. Add a chunk that must be authenticated 7.1.18. Add a chunk that must be authenticated
(SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 55 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 57
7.1.19. Get or set the list of supported HMAC Identifiers 7.1.19. Get or set the list of supported HMAC Identifiers
(SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 56 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 57
7.1.20. Set a shared key (SCTP_AUTH_KEY) . . . . . . . . . . . 56 7.1.20. Set a shared key (SCTP_AUTH_KEY) . . . . . . . . . . . 58
7.1.21. Get or set the active shared key 7.1.21. Get or set the active shared key
(SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 57 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . . 58
7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) . . . . . . 58 7.1.22. Delete a shared key (SCTP_AUTH_DELETE_KEY) . . . . . . 59
7.1.23. Get or set delayed ack timer (SCTP_DELAYED_SACK) . . . 58 7.1.23. Get or set delayed ack timer (SCTP_DELAYED_SACK) . . . 60
7.1.24. Get or set fragmented interleave 7.1.24. Get or set fragmented interleave
(SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 59 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . . 60
7.1.25. Set or Get the sctp partial delivery point 7.1.25. Set or Get the sctp partial delivery point
(SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 60 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 62
7.1.26. Set or Get the use of extended receive info 7.1.26. Set or Get the use of extended receive info
(SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 60 (SCTP_USE_EXT_RCVINFO) . . . . . . . . . . . . . . . . 62
7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) . . 61 7.1.27. Set or Get the auto asconf flag (SCTP_AUTO_ASCONF) . . 62
7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) . . . . 61 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) . . . . 62
7.1.29. Set or Get the default context (SCTP_CONTEXT) . . . . 61 7.1.29. Set or Get the default context (SCTP_CONTEXT) . . . . 63
7.1.30. Enable or disable explicit EOR marking 7.1.30. Enable or disable explicit EOR marking
(SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 62 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 63
7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 62 7.1.31. Enable SCTP port reusage (SCTP_REUSE_PORT) . . . . . . 64
7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 62 7.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 64
7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 63 7.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . . 64
7.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . 65
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) . . . . . . . . 64 authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 66
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) . . . . . 65 to be authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . . 67
7.2.5. Get the current number of associations 7.2.5. Get the current number of associations
(SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 65 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 67
7.2.6. Get the current identifiers of associations 7.2.6. Get the current identifiers of associations
(SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 65 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . . 67
7.3. Ancillary Data and Notification Interest Options . . . . . 66 7.3. Ancillary Data and Notification Interest Options . . . . . 68
8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 68 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 70
8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 68 8.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 70
8.2. Branched-off Association . . . . . . . . . . . . . . . . . 69 8.2. Branched-off Association . . . . . . . . . . . . . . . . . 72
8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 70 8.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 72
8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 71 8.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 73
8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 71 8.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 73
8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 72 8.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 74
8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 72 8.7. sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 74
8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 72 8.8. sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 75
8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 73 8.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 75
8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 74 8.10. sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 76
8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 75 8.11. sctp_sendx() . . . . . . . . . . . . . . . . . . . . . . . 77
8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 76 8.12. sctp_getaddrlen . . . . . . . . . . . . . . . . . . . . . 78
9. Preprocessor Constants . . . . . . . . . . . . . . . . . . . . 76 9. IANA considerations . . . . . . . . . . . . . . . . . . . . . 78
10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 77 10. Security Considerations . . . . . . . . . . . . . . . . . . . 78
11. Security Considerations . . . . . . . . . . . . . . . . . . . 77 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 79
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 77 12. Normative references . . . . . . . . . . . . . . . . . . . . . 79
13. Normative references . . . . . . . . . . . . . . . . . . . . . 77 Appendix A. one-to-one style Code Example . . . . . . . . . . . . 80
Appendix A. one-to-one style Code Example . . . . . . . . . . . . 78 Appendix B. one-to-many style Code Example . . . . . . . . . . . 85
Appendix B. one-to-many style Code Example . . . . . . . . . . . 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 86
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 85 Intellectual Property and Copyright Statements . . . . . . . . . . 89
Intellectual Property and Copyright Statements . . . . . . . . . . 87
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 RFC793 [RFC0793] Protocol suite to many operating systems. Both TCP [RFC0793] and UDP
and UDP RFC768 [RFC0768] have benefited from this standard [RFC0768] have benefited from this standard representation and access
representation and access method across many diverse platforms. SCTP method across many diverse platforms. SCTP is a new protocol that
is a new protocol that provides many of the characteristics of TCP provides many of the characteristics of TCP but also incorporates
but also incorporates semantics more akin to UDP. This document semantics more akin to UDP. This document defines a method to map
defines a method to map the existing sockets API for use with SCTP, the existing sockets API for use with SCTP, providing both a base for
providing both a base for access to new features and compatibility so access to new features and compatibility so that most existing TCP
that most existing TCP applications can be migrated to SCTP with few applications can be migrated to SCTP with few (if any) changes.
(if any) changes.
There are three basic design objectives: There are three basic design objectives:
1) Maintain consistency with existing sockets APIs: 1) Maintain consistency with existing sockets APIs:
We define a sockets mapping for SCTP that is consistent with other We define a sockets mapping for SCTP that is consistent with other
sockets API protocol mappings (for instance, UDP, TCP, IPv4, and sockets API protocol mappings (for instance, UDP, TCP, IPv4, and
IPv6). IPv6).
2) Support a one-to-many style interface 2) Support a one-to-many style interface
This set of semantics is similar to that defined for connection- This set of semantics is similar to that defined for connection-
less protocols, such as UDP. A one-to-many style SCTP socket less protocols, such as UDP. A one-to-many style SCTP socket
skipping to change at page 8, line 32 skipping to change at page 8, line 32
Applications use bind() to specify which local address the SCTP Applications use bind() to specify which local address the SCTP
endpoint should associate itself with. endpoint should associate itself with.
An SCTP endpoint can be associated with multiple addresses. To do An SCTP endpoint can be associated with multiple addresses. To do
this, sctp_bindx() is introduced in section Section 8.1 to help this, sctp_bindx() is introduced in section Section 8.1 to help
applications do the job of associating multiple addresses. applications do the job of associating multiple addresses.
These addresses associated with a socket are the eligible transport These addresses associated with a socket are the eligible transport
addresses for the endpoint to send and receive data. The endpoint addresses for the endpoint to send and receive data. The endpoint
will also present these addresses to its peers during the association will also present these addresses to its peers during the association
initialization process, see RFC2960 [RFC2960]. initialization process, see [RFC4960].
After calling bind(), if the endpoint wishes to accept new After calling bind(), if the endpoint wishes to accept new
associations on the socket, it must call listen() (see section associations on the socket, it must call listen() (see section
Section 3.1.3). Section 3.1.3).
The syntax of bind() is, The syntax of bind() is,
ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen);
sd - the socket descriptor returned by socket(). sd - the socket descriptor returned by socket().
addr - the address structure (struct sockaddr_in or struct addr - the address structure (struct sockaddr_in or struct
sockaddr_in6 RFC2553 [RFC2553]). sockaddr_in6 [RFC2553]).
addrlen - the size of the address structure. addrlen - the size of the address structure.
If sd is an IPv4 socket, the address passed must be an IPv4 address. If sd is an IPv4 socket, the address passed must be an IPv4 address.
If the sd is an IPv6 socket, the address passed can either be an IPv4 If the sd is an IPv6 socket, the address passed can either be an IPv4
or an IPv6 address. or an IPv6 address.
Applications cannot call bind() multiple times to associate multiple Applications cannot call bind() multiple times to associate multiple
addresses to an endpoint. After the first call to bind(), all addresses to an endpoint. After the first call to bind(), all
subsequent calls will return an error. subsequent calls will return an error.
skipping to change at page 10, line 29 skipping to change at page 10, line 29
specifying options for sending each user message. Those options, specifying options for sending each user message. Those options,
depending on whether sending or receiving, include stream number, depending on whether sending or receiving, include stream number,
stream sequence number, various flags, context and payload protocol stream sequence number, various flags, context and payload protocol
Id, etc. Id, etc.
When sending user data with sendmsg(), the msg_name field in msghdr When sending user data with sendmsg(), the msg_name field in msghdr
structure will be filled with one of the transport addresses of the structure will be filled with one of the transport addresses of the
intended receiver. If there is no association existing between the intended receiver. If there is no association existing between the
sender and the intended receiver, the sender's SCTP stack will set up sender and the intended receiver, the sender's SCTP stack will set up
a new association and then send the user data (see Section 3.2 for a new association and then send the user data (see Section 3.2 for
more on implicit association setup). more on implicit association setup). If an SCTP_INIT cmsg structure
is used with NULL data, an association will be established using the
parameters from the struct sctp_initmsg structure. If no SCTP_INIT
cmsg structure is used in combination with NULL data, an association
is established using the default parameters. If NULL data is used,
no association exists and the SCTP_ABORT or SCTP_EOF -1 MUST be
returned and an errno SHOULD be set to something like EDONOTBESTUPID.
Sending a message using sendmsg() is atomic unless explicit EOR
marking is enabled on the socket specified by sd.
If a peer sends a SHUTDOWN, a SCTP_SHUTDOWN_EVENT notification will If a peer sends a SHUTDOWN, a 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
can be sent to that association. Any attempt to send more data will can be sent to that association. Any attempt to send more data will
cause sendmsg() to return with an ESHUTDOWN error. Note that the cause sendmsg() to return with an ESHUTDOWN error. Note that the
socket is still open for reading at this point so it is possible to socket is still open for reading at this point so it is possible to
retrieve notifications. retrieve notifications.
When receiving a user message with recvmsg(), the msg_name field in When receiving a user message with recvmsg(), the msg_name field in
msghdr structure will be populated with the source transport address msghdr structure will be populated with the source transport address
skipping to change at page 11, line 24 skipping to change at page 11, line 31
one-to-many model sockets. Please consult Section 7.1.24 for further one-to-many model sockets. Please consult Section 7.1.24 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() - one-to-many style socket 3.1.5. close() - one-to-many style socket
Applications use close() to perform graceful shutdown (as described Applications use close() to perform graceful shutdown (as described
in Section 10.1 of RFC2960 [RFC2960]) on ALL the associations in Section 10.1 of [RFC4960]) on ALL the associations currently
currently represented by a one-to-many style socket. represented by a one-to-many style socket.
The syntax is: The syntax is:
ret = close(int sd); ret = close(int sd);
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-
to-many style socket, an application should use the sendmsg() call, to-many style socket, an application should use the sendmsg() call,
and including the SCTP_EOF flag. A user may optionally terminate an and including the SCTP_EOF flag. A user may optionally terminate an
skipping to change at page 12, line 9 skipping to change at page 12, line 16
An application may use the connect() call in the one-to-many style to An application may use the connect() call in the one-to-many style to
initiate an association without sending data. initiate an association without sending data.
The syntax is: The syntax is:
ret = connect(int sd, const struct sockaddr *nam, socklen_t len); ret = connect(int sd, const struct sockaddr *nam, socklen_t len);
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 (either struct sockaddr_in or struct nam - the address structure (either struct sockaddr_in or struct
sockaddr_in6 defined in RFC2553 [RFC2553]). sockaddr_in6 defined in [RFC2553]).
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. Implicit Association Setup
Once the bind() call is complete on a one-to-many style socket, the Once the bind() call is complete on a one-to-many style socket, the
application can begin sending and receiving data using the sendmsg()/ application can begin sending and receiving data using the sendmsg()/
recvmsg() or sendto()/recvfrom() calls, without going through any recvmsg() or sendto()/recvfrom() calls, without going through any
skipping to change at page 12, line 37 skipping to change at page 12, line 44
dest_addr field in the sendto() call), the SCTP stack will dest_addr field in the sendto() call), the SCTP stack will
automatically setup an association to the intended receiver. automatically setup an association to the intended receiver.
Upon the successful association setup a SCTP_COMM_UP notification Upon the successful association setup a SCTP_COMM_UP notification
will be dispatched to the socket at both the sender and receiver will be dispatched to the socket at both the sender and receiver
side. This notification can be read by the recvmsg() system call side. This notification can be read by the recvmsg() system call
(see Section 3.1.3). (see Section 3.1.3).
Note, if the SCTP stack at the sender side supports bundling, the Note, if the SCTP stack at the sender side supports bundling, the
first user message may be bundled with the COOKIE ECHO message first user message may be bundled with the COOKIE ECHO message
RFC2960 [RFC2960]. [RFC4960].
When the SCTP stack sets up a new association implicitly, it first When the SCTP stack sets up a new association implicitly, it first
consults the sctp_initmsg structure, which is passed along within the consults the sctp_initmsg structure, which is passed along within the
ancillary data in the sendmsg() call (see Section 5.2.1 for details ancillary data in the sendmsg() call (see Section 5.2.1 for details
of the data structures), for any special options to be used on the of the data structures), for any special options to be used on the
new association. new association.
If this information is not present in the sendmsg() call, or if the If this information is not present in the sendmsg() call, or if the
implicit association setup is triggered by a sendto() call, the implicit association setup is triggered by a sendto() call, the
default association initialization parameters will be used. These default association initialization parameters will be used. These
skipping to change at page 17, line 8 skipping to change at page 17, line 17
Applications use bind() to pass an address to be associated with an Applications use bind() to pass an address to be associated with an
SCTP endpoint to the system. bind() allows only either a single SCTP endpoint to the system. bind() allows only either a single
address or a IPv4 or IPv6 wildcard address to be bound. An SCTP address or a IPv4 or IPv6 wildcard address to be bound. An SCTP
endpoint can be associated with multiple addresses. To do this, endpoint can be associated with multiple addresses. To do this,
sctp_bindx() is introduced in Section 8.1 to help applications do the sctp_bindx() is introduced in Section 8.1 to help applications do the
job of associating multiple addresses. job of associating multiple addresses.
These addresses associated with a socket are the eligible transport These addresses associated with a socket are the eligible transport
addresses for the endpoint to send and receive data. The endpoint addresses for the endpoint to send and receive data. The endpoint
will also present these addresses to its peers during the association will also present these addresses to its peers during the association
initialization process, see RFC2960 [RFC2960]. initialization process, see [RFC4960].
The syntax is: The syntax is:
int bind(int sd, struct sockaddr *addr, socklen_t addrlen); int bind(int sd, struct sockaddr *addr, socklen_t addrlen);
sd: the socket descriptor returned by socket() call. sd: the socket descriptor returned by socket() call.
addr: the address structure (either struct sockaddr_in or struct addr: the address structure (either struct sockaddr_in or struct
sockaddr_in6 defined in RFC2553 [RFC2553]). sockaddr_in6 defined in [RFC2553]).
addrlen: the size of the address structure. addrlen: the size of the address structure.
If sd is an IPv4 socket, the address passed must be an IPv4 address. If sd is an IPv4 socket, the address passed must be an IPv4 address.
Otherwise, i.e., the sd is an IPv6 socket, the address passed can Otherwise, i.e., the sd is an IPv6 socket, the address passed can
either be an IPv4 or an IPv6 address. either be an IPv4 or an IPv6 address.
Applications cannot call bind() multiple times to associate multiple Applications cannot call bind() multiple times to associate multiple
addresses to the endpoint. After the first call to bind(), all addresses to the endpoint. After the first call to bind(), all
subsequent calls will return an error. subsequent calls will return an error.
skipping to change at page 18, line 4 skipping to change at page 18, line 13
with an SCTP ABORT. with an SCTP ABORT.
4.1.3. listen() - one-to-one style socket 4.1.3. listen() - one-to-one style socket
Applications use listen() to ready the SCTP endpoint for accepting Applications use listen() to ready the SCTP endpoint for accepting
inbound associations. inbound associations.
The syntax is: The syntax is:
int listen(int sd, int backlog); int listen(int sd, int backlog);
sd: the socket descriptor of the SCTP endpoint. sd: the socket descriptor of the SCTP endpoint.
backlog: this specifies the max number of outstanding associations backlog: this specifies the max number of outstanding associations
allowed in the socket's accept queue. These are the associations allowed in the socket's accept queue. These are the associations
that have finished the four-way initiation handshake (see Section that have finished the four-way initiation handshake (see Section
5 of RFC2960 [RFC2960]) and are in the ESTABLISHED state. Note, a 5 of [RFC4960]) and are in the ESTABLISHED state. Note, a backlog
backlog of '0' indicates that the caller no longer wishes to of '0' indicates that the caller no longer wishes to receive new
receive new associations. associations.
4.1.4. accept() - one-to-one style socket 4.1.4. accept() - one-to-one style socket
Applications use accept() call to remove an established SCTP Applications use accept() call to remove an established SCTP
association from the accept queue of the endpoint. A new socket association from the accept queue of the endpoint. A new socket
descriptor will be returned from accept() to represent the newly descriptor will be returned from accept() to represent the newly
formed association. formed association.
The syntax is: The syntax is:
skipping to change at page 18, line 39 skipping to change at page 19, line 4
4.1.5. connect() - one-to-one style socket 4.1.5. connect() - one-to-one style socket
Applications use connect() to initiate an association to a peer. Applications use connect() to initiate an association to a peer.
The syntax is: The syntax is:
int connect(int sd, const struct sockaddr *addr, socklen_t addrlen); int connect(int sd, const struct sockaddr *addr, socklen_t addrlen);
sd - the socket descriptor of the endpoint. sd - the socket descriptor of the endpoint.
addr - the peer's address. addr - the peer's address.
addrlen - the size of the address. addrlen - the size of the address.
This operation corresponds to the ASSOCIATE primitive described in This operation corresponds to the ASSOCIATE primitive described in
section 10.1 of RFC2960 [RFC2960]. section 10.1 of [RFC4960].
By default, the new association created has only one outbound stream. By default, the new association created has only one outbound stream.
The SCTP_INITMSG option described in Section 7.1.3 should be used The SCTP_INITMSG option described in Section 7.1.3 should be used
before connecting to change the number of outbound streams. before connecting to change the number 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 for IPv4 and IPv6 socket binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket
respectively. One of those addresses will be the primary address for respectively. One of those 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],
[RFC1644], during the association set up phase. If an application during the association set up phase. If an application wants to do
wants to do this, it cannot use connect() call. Instead, it should this, it cannot use connect() call. Instead, it should use sendto()
use sendto() or sendmsg() to initiate an association. If it uses or sendmsg() to initiate an association. If it uses sendto() and it
sendto() and it wants to change initialization behavior, it needs to wants to change initialization behavior, it needs to use the
use the SCTP_INITMSG socket option before calling sendto(). Or it SCTP_INITMSG socket option before calling sendto(). Or it can use
can use SCTP_INIT type sendmsg() to initiate an association without SCTP_INIT type sendmsg() to initiate an association without doing the
doing the setsockopt(). Note that some sockets implementations may setsockopt(). Note that some sockets implementations may not support
not support the sending of data to initiate an association with the the sending of data to initiate an association with the one-to-one
one-to-one style (implementations that do not support T/TCP normally style (implementations that do not support T/TCP normally have this
have this restriction). Implementations which allow sending of data restriction). Implementations which allow sending of data to
to initiate an association without calling connect() define the initiate an association without calling connect() define the
preprocessor constant HAVE_SCTP_NOCONNECT to 1. preprocessor constant HAVE_SCTP_NOCONNECT to 1.
SCTP does not support half close semantics. This means that unlike SCTP does not support half close semantics. This means that unlike
T/TCP, MSG_EOF should not be set in the flags parameter when calling T/TCP, MSG_EOF should not be set in the flags parameter when calling
sendto() or sendmsg() when the call is used to initiate a connection. sendto() or sendmsg() when the call is used to initiate a connection.
MSG_EOF is not an acceptable flag with SCTP socket. MSG_EOF is not an acceptable flag with SCTP socket.
4.1.6. close() - one-to-one style socket 4.1.6. close() - one-to-one style socket
Applications use close() to gracefully close down an association. Applications use close() to gracefully close down an association.
skipping to change at page 20, line 21 skipping to change at page 20, line 36
initiates the SCTP shutdown sequence. initiates the SCTP shutdown sequence.
The major difference between SCTP and TCP shutdown() is that SCTP The major difference between SCTP and TCP shutdown() is that SCTP
SHUT_WR initiates immediate and full protocol shutdown, whereas TCP SHUT_WR initiates immediate and full protocol shutdown, whereas TCP
SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves SHUT_WR causes TCP to go into the half closed state. SHUT_RD behaves
the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close the same for SCTP as TCP. The purpose of SCTP SHUT_WR is to close
the SCTP association while still leaving the socket descriptor open, the SCTP association while still leaving the socket descriptor open,
so that the caller can receive back any data SCTP was unable to so that the caller can receive back any data SCTP was unable to
deliver (see Section 5.3.1.4 for more information). deliver (see Section 5.3.1.4 for more information).
To perform the ABORT operation described in RFC2960 [RFC2960] section To perform the ABORT operation described in [RFC4960] section 10.1,
10.1, an application can use the socket option SO_LINGER. It is an application can use the socket option SO_LINGER. It is described
described in Section 7.1.4. in Section 7.1.4.
4.1.8. sendmsg() and recvmsg() - one-to-one style socket 4.1.8. sendmsg() and recvmsg() - one-to-one style socket
With a one-to-one style socket, the application can also use With a one-to-one style socket, the application can also use
sendmsg() and recvmsg() to transmit data to and receive data from its sendmsg() and recvmsg() to transmit data to and receive data from its
peer. The semantics is similar to those used in the one-to-many peer. The semantics is similar to those used in the one-to-many
style (section Section 3.1.3), with the following differences: style (section Section 3.1.3), with the following differences:
1. When sending, the msg_name field in the msghdr is not used to
1) When sending, the msg_name field in the msghdr is not used to
specify the intended receiver, rather it is used to indicate a specify the intended receiver, rather it is used to indicate a
preferred peer address if the sender wishes to discourage the stack preferred peer address if the sender wishes to discourage the
from sending the message to the primary address of the receiver. If stack from sending the message to the primary address of the
the transport address given is not part of the current association, receiver. If the socket is connected and the transport address
the data will not be sent and a SCTP_SEND_FAILED event will be given is not part of the current association, the data will not
delivered to the application if send failure events are enabled. be sent and a SCTP_SEND_FAILED event will be delivered to the
application if send failure events are enabled.
2. Using sendmsg() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the
SCTP implementation.
4.1.9. getpeername() 4.1.9. getpeername()
Applications use getpeername() to retrieve the primary socket address Applications use getpeername() to retrieve the primary socket address
of the peer. This call is for TCP compatibility, and is not multi- of the peer. This call is for TCP compatibility, and is not multi-
homed. It does not work with one-to-many style sockets. See homed. It does not work with one-to-many style sockets. See
Section 8.3 for a multi-homed/one-to-many style version of the call. Section 8.3 for a multi-homed/one-to-many style version of the call.
The syntax is: The syntax is:
skipping to change at page 21, line 30 skipping to change at page 21, line 48
and notifications. and 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 details in RFC2292 [RFC2292]. Here we will cite their discussed in details in [RFC2292]. Here we will cite their
definitions from RFC2292 [RFC2292]. definitions from [RFC2292].
The msghdr structure: 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 */
skipping to change at page 23, line 7 skipping to change at page 23, line 20
report parameters on individual messages in a stream. See report parameters on individual messages in a stream. See
Section 5.2.2 for how to use SNDRCV ancillary data. Section 5.2.2 for how to use SNDRCV ancillary data.
By default on a one-to-one style socket, SCTP will pass no ancillary By default on a one-to-one style socket, SCTP will pass no ancillary
data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV data; on a one-to-many style socket, SCTP will only pass SCTP_SNDRCV
and SCTP_ASSOC_CHANGE information. Specific ancillary data items can and SCTP_ASSOC_CHANGE information. Specific ancillary data items can
be enabled with socket options defined for SCTP; see Section 7.3. be enabled with socket options defined for SCTP; see Section 7.3.
Note that all ancillary types are fixed length; see Section 5.4 for Note that all ancillary types are fixed length; see Section 5.4 for
further discussion on this. These data structures use struct further discussion on this. These data structures use struct
sockaddr_storage (defined in RFC2553 [RFC2553]) as a portable, fixed sockaddr_storage (defined in [RFC2553]) as a portable, fixed length
length address format. address format.
Other protocols may also provide ancillary data to the socket layer Other protocols may also provide ancillary data to the socket layer
consumer. These ancillary data items from other protocols may consumer. These ancillary data items from other protocols may
intermingle with SCTP data. For example, the IPv6 socket API intermingle with SCTP data. For example, the IPv6 socket API
definitions (RFC2292 [RFC2292] and RFC2553 [RFC2553]) define a number definitions ([RFC2292] and [RFC2553]) define a number of ancillary
of ancillary data items. If a socket API consumer enables delivery data items. If a socket API consumer enables delivery of both SCTP
of both SCTP and IPv6 ancillary data, they both may appear in the and IPv6 ancillary data, they both may appear in the same msg_control
same msg_control buffer in any order. An application may thus need buffer in any order. An application may thus need to handle other
to handle other types of ancillary data besides that passed by SCTP. types of ancillary data besides that passed by SCTP.
The sockets application must provide a buffer large enough to The sockets application must provide a buffer large enough to
accommodate all ancillary data provided via recvmsg(). If the buffer accommodate all ancillary data provided via recvmsg(). If the buffer
is not large enough, the ancillary data will be truncated and the is not large enough, the ancillary data will be truncated and the
msghdr's msg_flags will include MSG_CTRUNC. msghdr's msg_flags will include MSG_CTRUNC.
5.2.1. SCTP Initiation Structure (SCTP_INIT) 5.2.1. SCTP Initiation Structure (SCTP_INIT)
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
skipping to change at page 24, line 46 skipping to change at page 25, line 21
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: Here is the definition of sctp_sndrcvinfo:
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;
uint16_t sinfo_pr_policy;
uint32_t sinfo_ppid; uint32_t sinfo_ppid;
uint32_t sinfo_context; uint32_t sinfo_context;
uint32_t sinfo_timetolive; uint32_t sinfo_pr_value;
uint32_t sinfo_tsn; uint32_t sinfo_tsn;
uint32_t sinfo_cumtsn; uint32_t sinfo_cumtsn;
sctp_assoc_t sinfo_assoc_id; sctp_assoc_t sinfo_assoc_id;
}; };
sinfo_stream: 16 bits (unsigned integer) sinfo_stream: 16 bits (unsigned integer)
For recvmsg() the SCTP stack places the message's stream number in For recvmsg() the SCTP stack places the message's stream number in
this value. For sendmsg() this value holds the stream number that this value. For sendmsg() this value holds the stream number that
the application wishes to send this message to. If a sender the application wishes to send this message to. If a sender
skipping to change at page 26, line 34 skipping to change at page 27, line 10
procedures on the specified association. Graceful shutdown procedures on the specified association. Graceful shutdown
assures that all data enqueued by both endpoints is successfully assures that all data enqueued 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).
SCTP_SENDALL - This flag, if set, will cause a one-to-many model SCTP_SENDALL - This flag, if set, will cause a one-to-many model
socket to send the message to all associations that are currently socket to send the message to all associations that are currently
established on this socket. For the one-to-one socket, this flag established on this socket. For the one-to-one socket, this flag
has no effect. has no effect.
sinfo_timetolive: 32 bit (unsigned integer) sinfo_pr_policy: 16 bits (unsigned integer)
For the sending side, this field contains the message time to live in For the sending side, this specifies which PR-SCTP policy is used.
milliseconds. The sending side will expire the message within the Using SCTP_PR_SCTP_NONE results in a reliable transmission. When
specified time period if the message as not been sent to the peer SCTP_PR_SCTP_TTL is used, the PR-SCTP policy "timed reliabilility"
within this time period. This value will override any default value defined in [RFC3758] is used. In this case, the lifetime is provided
set using any socket option. Also note that the value of 0 is in sinfo_pr_value.
special in that it indicates no timeout should occur on this message.
sinfo_pr_value: 32 bit (unsigned integer)
The meaning of this field depends of the PR-SCTP policy specified by
the sinfo_pr_policy field. It is ignored when SCTP_PR_SCTP_NONE is
specified. In case of SCTP_PR_SCTP_TTL the lifetime is specified.
sinfo_tsn: 32 bit (unsigned integer) sinfo_tsn: 32 bit (unsigned integer)
For the receiving side, this field holds a TSN that was assigned to For the receiving side, this field holds a TSN that was assigned to
one of the SCTP Data Chunks. one of the SCTP Data Chunks.
sinfo_cumtsn: 32 bit (unsigned integer) sinfo_cumtsn: 32 bit (unsigned integer)
This field will hold the current cumulative TSN as known by the This field will hold the current cumulative TSN as known by the
underlying SCTP layer. Note this field is ignored when sending and underlying SCTP layer. Note this field is ignored when sending and
skipping to change at page 29, line 51 skipping to change at page 30, line 31
uint32_t sn_length; uint32_t sn_length;
} sn_header; } sn_header;
struct sctp_assoc_change sn_assoc_change; struct sctp_assoc_change sn_assoc_change;
struct sctp_paddr_change sn_paddr_change; struct sctp_paddr_change sn_paddr_change;
struct sctp_remote_error sn_remote_error; struct sctp_remote_error sn_remote_error;
struct sctp_send_failed sn_send_failed; struct sctp_send_failed sn_send_failed;
struct sctp_shutdown_event sn_shutdown_event; struct sctp_shutdown_event sn_shutdown_event;
struct sctp_adaptation_event sn_adaptation_event; struct sctp_adaptation_event sn_adaptation_event;
struct sctp_pdapi_event sn_pdapi_event; struct sctp_pdapi_event sn_pdapi_event;
struct sctp_authkey_event sn_auth_event; struct sctp_authkey_event sn_auth_event;
struct sctp_no_auth_event sn_no_auth_event;
}; };
sn_type: 16 bits (unsigned integer) sn_type: 16 bits (unsigned integer)
The following list describes the SCTP notification and event types The following list describes the SCTP notification and event types
for the field sn_type. for the field sn_type.
SCTP_ASSOC_CHANGE: This tag indicates that an association has either SCTP_ASSOC_CHANGE: This tag indicates that an association has either
been opened or closed. Refer to Section 5.3.1.1 for details. been opened or closed. Refer to Section 5.3.1.1 for details.
SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is SCTP_PEER_ADDR_CHANGE: This tag indicates that an address that is
part of an existing association has experienced a change of state part of an existing association has experienced a change of state
(e.g. a failure or return to service of the reachability of a (e.g. a failure or return to service of the reachability of a
skipping to change at page 30, line 35 skipping to change at page 31, line 20
should be sent on this socket. should be sent on this socket.
SCTP_ADAPTATION_INDICATION: This notification holds the peers SCTP_ADAPTATION_INDICATION: This notification holds the peers
indicated adaptation layer. Please see Section 5.3.1.6. indicated adaptation layer. Please see Section 5.3.1.6.
SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a SCTP_PARTIAL_DELIVERY_EVENT: This notification is used to tell a
receiver that the partial delivery has been aborted. This may receiver that the partial delivery has been aborted. This may
indicate the association is about to be aborted. Please see indicate the association is about to be aborted. Please see
Section 5.3.1.7 Section 5.3.1.7
SCTP_AUTHENTICATION_EVENT: This notification is used to tell a SCTP_AUTHENTICATION_EVENT: This notification is used to tell a
receiver that either an error occurred on authentication, or a new receiver that either an error occurred on authentication, or a new
key was made active. Section 5.3.1.8 key was made active. Section 5.3.1.8
SCTP_NO_AUTHENTICATION_EVENT: This notification is used to tell a
receiver that the peer does not support SCTP-AUTH.
Section 5.3.1.9
All standard values for sn_type are greater than 2^15. Values from All standard values for sn_type are greater than 2^15. Values from
2^15 and down are reserved. 2^15 and down are reserved.
sn_flags: 16 bits (unsigned integer) sn_flags: 16 bits (unsigned integer)
These are notification-specific flags. These are notification-specific flags.
sn_length: 32 bits (unsigned integer) sn_length: 32 bits (unsigned integer)
skipping to change at page 31, line 16 skipping to change at page 31, line 52
struct sctp_assoc_change { struct sctp_assoc_change {
uint16_t sac_type; uint16_t sac_type;
uint16_t sac_flags; uint16_t sac_flags;
uint32_t sac_length; uint32_t sac_length;
uint16_t sac_state; uint16_t sac_state;
uint16_t sac_error; uint16_t sac_error;
uint16_t sac_outbound_streams; uint16_t sac_outbound_streams;
uint16_t sac_inbound_streams; uint16_t sac_inbound_streams;
sctp_assoc_t sac_assoc_id; sctp_assoc_t sac_assoc_id;
uint8_t sac_info[0]; uint8_t sac_info[];
}; };
sac_type: sac_type:
It should be SCTP_ASSOC_CHANGE. It should be SCTP_ASSOC_CHANGE.
sac_flags: 16 bits (unsigned integer) sac_flags: 16 bits (unsigned integer)
Currently unused. Currently unused.
skipping to change at page 32, line 16 skipping to change at page 32, line 46
SCTP_CANT_STR_ASSOC - The association failed to setup. If non SCTP_CANT_STR_ASSOC - The association failed to setup. If non
blocking mode is set and data was sent (in the udp mode), a blocking mode is set and data was sent (in the udp mode), a
SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED SCTP_CANT_STR_ASSOC is followed by a series of SCTP_SEND_FAILED
events, one for each outstanding message. events, one for each outstanding message.
sac_error: 16 bits (signed integer) sac_error: 16 bits (signed integer)
If the state was reached due to a error condition (e.g. If the state was reached due to a error condition (e.g.
SCTP_COMM_LOST) any relevant error information is available in this SCTP_COMM_LOST) any relevant error information is available in this
field. This corresponds to the protocol error codes defined in field. This corresponds to the protocol error codes defined in
RFC2960 [RFC2960]. [RFC4960].
sac_outbound_streams: 16 bits (unsigned integer) sac_outbound_streams: 16 bits (unsigned integer)
sac_inbound_streams: 16 bits (unsigned integer) sac_inbound_streams: 16 bits (unsigned integer)
The maximum number of streams allowed in each direction are available The maximum number of streams allowed in each direction are available
in sac_outbound_streams and sac_inbound streams. in sac_outbound_streams and sac_inbound streams.
sac_assoc_id: sizeof (sctp_assoc_t) sac_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
All notifications for a given association have the same association All notifications for a given association have the same association
identifier. For one-to-one style socket, this field is ignored. identifier. For one-to-one style socket, this field is ignored.
sac_info: variable sac_info: variable
skipping to change at page 32, line 35 skipping to change at page 33, line 17
sac_assoc_id: sizeof (sctp_assoc_t) sac_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
All notifications for a given association have the same association All notifications for a given association have the same association
identifier. For one-to-one style socket, this field is ignored. identifier. For one-to-one style socket, this field is ignored.
sac_info: variable sac_info: variable
If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received If the sac_state is SCTP_COMM_LOST and an ABORT chunk was received
for this association, sac_info[] contains the complete ABORT chunk as for this association, sac_info[] contains the complete ABORT chunk as
defined in the SCTP specification RFC2960 [RFC2960] section 3.3.7. defined in the SCTP specification [RFC4960] section 3.3.7.
5.3.1.2. SCTP_PEER_ADDR_CHANGE 5.3.1.2. SCTP_PEER_ADDR_CHANGE
When a destination address on a multi-homed peer encounters a change When a destination address on a multi-homed peer encounters a change
an interface details event is sent. The information has the an interface details event is sent. The information has the
following structure: following structure:
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 34, line 4 skipping to change at page 34, line 36
spc_error: 32 bits (signed integer) spc_error: 32 bits (signed integer)
If the state was reached due to any error condition (e.g. If the state was reached due to any error condition (e.g.
SCTP_ADDR_UNREACHABLE) any relevant error information is available in SCTP_ADDR_UNREACHABLE) any relevant error information is available in
this field. this field.
spc_assoc_id: sizeof (sctp_assoc_t) spc_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
All notifications for a given association have the same association All notifications for a given association have the same association
identifier. For one-to-one style socket, this field is ignored. identifier. For one-to-one style socket, this field is ignored.
5.3.1.3. SCTP_REMOTE_ERROR 5.3.1.3. SCTP_REMOTE_ERROR
A remote peer may send an Operational Error message to its peer. A remote peer may send an Operational Error message to its peer.
This message indicates a variety of error conditions on an This message indicates a variety of error conditions on an
association. The entire ERROR chunk as it appears on the wire is association. The entire ERROR chunk as it appears on the wire is
included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP included in a SCTP_REMOTE_ERROR event. Please refer to the SCTP
specification RFC2960 [RFC2960] and any extensions for a list of specification [RFC4960] and any extensions for a list of possible
possible error formats. SCTP error notifications have the format: error formats. SCTP error notifications have the format:
struct sctp_remote_error { struct sctp_remote_error {
uint16_t sre_type; uint16_t sre_type;
uint16_t sre_flags; uint16_t sre_flags;
uint32_t sre_length; uint32_t sre_length;
uint16_t sre_error; uint16_t sre_error;
sctp_assoc_t sre_assoc_id; sctp_assoc_t sre_assoc_id;
uint8_t sre_data[0]; uint8_t sre_data[];
}; };
sre_type: sre_type:
It should be SCTP_REMOTE_ERROR. It should be SCTP_REMOTE_ERROR.
sre_flags: 16 bits (unsigned integer) sre_flags: 16 bits (unsigned integer)
Currently unused. Currently unused.
skipping to change at page 35, line 4 skipping to change at page 35, line 39
This value represents one of the Operational Error causes defined in This value represents one of the Operational Error causes defined in
the SCTP specification, in network byte order. the SCTP specification, in network byte order.
sre_assoc_id: sizeof (sctp_assoc_t) sre_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
All notifications for a given association have the same association All notifications for a given association have the same association
identifier. For one-to-one style socket, this field is ignored. identifier. For one-to-one style socket, this field is ignored.
sre_data: variable sre_data: variable
This contains the ERROR chunk as defined in the SCTP specification This contains the ERROR chunk as defined in the SCTP specification
RFC2960 [RFC2960] section 3.3.10. [RFC4960] section 3.3.10.
5.3.1.4. SCTP_SEND_FAILED 5.3.1.4. SCTP_SEND_FAILED
If SCTP cannot deliver a message it may return the message as a If SCTP cannot deliver a message it may return the message as a
notification. notification.
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;
sctp_assoc_t ssf_assoc_id; sctp_assoc_t ssf_assoc_id;
uint8_t ssf_data[0]; uint8_t ssf_data[];
}; };
ssf_type: ssf_type:
It should be SCTP_SEND_FAILED. It should be SCTP_SEND_FAILED.
ssf_flags: 16 bits (unsigned integer) ssf_flags: 16 bits (unsigned integer)
The flag value will take one of the following values: The flag value will take one of the following values:
skipping to change at page 35, line 44 skipping to change at page 36, line 37
successfully delivered. successfully delivered.
ssf_length: 32 bits (unsigned integer) ssf_length: 32 bits (unsigned integer)
This field is the total length of the notification data, including This field is the total length of the notification data, including
the notification header and the payload in ssf_data. the notification header and the payload in ssf_data.
ssf_error: 16 bits (unsigned integer) ssf_error: 16 bits (unsigned integer)
This value represents the reason why the send failed, and if set, This value represents the reason why the send failed, and if set,
will be a SCTP protocol error code as defined in RFC2960 [RFC2960] will be a SCTP protocol error code as defined in [RFC4960] section
section 3.3.10. 3.3.10.
ssf_info: sizeof (struct sctp_sndrcvinfo) ssf_info: sizeof (struct sctp_sndrcvinfo)
The original send information associated with the undelivered The original send information associated with the undelivered
message. message.
ssf_assoc_id: sizeof (sctp_assoc_t) ssf_assoc_id: sizeof (sctp_assoc_t)
The association id field, sf_assoc_id, holds the identifier for the The association id field, sf_assoc_id, holds the identifier for the
association. All notifications for a given association have the same association. All notifications for a given association have the same
skipping to change at page 40, line 16 skipping to change at page 41, line 6
made active (used for the first time by the peer) and is now the made active (used for the first time by the peer) and is now the
active key. The auth_keynumber field holds the user specified key active key. The auth_keynumber field holds the user specified key
number. number.
auth_assoc_id: sizeof (sctp_assoc_t) auth_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
All notifications for a given association have the same association All notifications for a given association have the same association
identifier. identifier.
5.3.1.9. SCTP_AUTHENTICATION_EVENT
When an association is set up and the peer does not support SCTP-AUTH
this notification is provided by the kernel to the user.
struct sctp_no_auth_event {
uint16_t no_auth_type;
uint16_t no_auth_flags;
uint32_t no_auth_length;
sctp_assoc_t no_auth_assoc_id;
};
no_auth_type
It should be SCTP_NO_AUTHENTICATION_EVENT
no_auth_flags: 16 bits (unsigned integer)
Currently unused.
no_auth_length: 32 bits (unsigned integer)
This field is the total length of the notification data, including
the notification header. It will generally be sizeof (struct
sctp_no_auth_event).
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 40, line 44 skipping to change at page 42, line 14
5.4.2. Accessing and Manipulating Ancillary Data 5.4.2. Accessing and Manipulating Ancillary Data
Applications can infer the presence of data or ancillary data by Applications can infer the presence of data or ancillary data by
examining the msg_iovlen and msg_controllen msghdr members, examining the msg_iovlen and msg_controllen msghdr members,
respectively. respectively.
Implementations may have different padding requirements for ancillary Implementations may have different padding requirements for ancillary
data, so portable applications should make use of the macros data, so portable applications should make use of the macros
CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_DATA, CMSG_SPACE, and CMSG_LEN. See
RFC2292 [RFC2292] and your SCTP implementation's documentation for [RFC2292] and your SCTP implementation's documentation for more
more information. Following is an example, from RFC2292 [RFC2292], information. Following is an example, from [RFC2292], demonstrating
demonstrating the use of these macros to access ancillary data: the use of these macros to access ancillary data:
struct msghdr msg; struct msghdr msg;
struct cmsghdr *cmsgptr; struct cmsghdr *cmsgptr;
/* fill in msg */ /* fill in msg */
/* call recvmsg() */ /* call recvmsg() */
for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL;
cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) {
skipping to change at page 41, line 45 skipping to change at page 43, line 9
the buffer is too small, and crucial data is truncated, it may pose a the buffer is too small, and crucial data is truncated, it may pose a
fatal error condition. fatal error condition.
Thus it is essential that applications be able to deterministically Thus it is essential that applications be able to deterministically
calculate the maximum required buffer size to pass to recvmsg(). One calculate the maximum required buffer size to pass to recvmsg(). One
constraint imposed on this specification that makes this possible is constraint imposed on this specification that makes this possible is
that all ancillary data definitions are of a fixed length. One way that all ancillary data definitions are of a fixed length. One way
to calculate the maximum required buffer size might be to take the to calculate the maximum required buffer size might be to take the
sum the sizes of all enabled ancillary data item structures, as sum the sizes of all enabled ancillary data item structures, as
calculated by CMSG_SPACE. For example, if we enabled calculated by CMSG_SPACE. For example, if we enabled
SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO RFC2292 [RFC2292], we would SCTP_SNDRCV_INFO and IPV6_RECVPKTINFO [RFC2292], we would calculate
calculate and allocate the buffer size as follows: and allocate the buffer size as follows:
size_t total; size_t total;
void *buf; void *buf;
total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) + total = CMSG_SPACE(sizeof (struct sctp_sndrcvinfo)) +
CMSG_SPACE(sizeof (struct in6_pktinfo)); CMSG_SPACE(sizeof (struct in6_pktinfo));
buf = malloc(total); buf = malloc(total);
We could then use this buffer for msg_control on each call to We could then use this buffer for msg_control on each call to
skipping to change at page 43, line 17 skipping to change at page 44, line 30
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 which 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. recv() and recvfrom() cannot distinguish message combining them. Sending a message using send() or sendto() is atomic
unless explicit EOR marking is enabled on the socket specified by sd.
Using sendto() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP
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 RFC2960 [RFC2960]. to send a Data chunk with no user data [RFC4960].
6.2. setsockopt(), getsockopt() 6.2. setsockopt(), 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 sockets calls. They are described in Section 7 behavior of sockets calls. They are described in Section 7
The syntax is: The syntax is:
ret = getsockopt(int sd, int level, int optname, void *optval, ret = getsockopt(int sd, int level, int optname, void *optval,
skipping to change at page 45, line 14 skipping to change at page 46, line 27
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 structure For the one-to-many style sockets, an sctp_assoc_t structure
(association ID) is used to identify the the association instance (association ID) is used to identify the association instance that
that the operation affects. So it must be set when using this style. the 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, those options will be
applied to all associations belonging to the socket. And for one-to- applied to all associations belonging to the socket. And for one-to-
one style, those options will be applied to all peer addresses of the one style, those options will be applied to all peer addresses of the
association controlled by the socket. Applications should be very association controlled by the socket. Applications should be very
careful in setting those options. careful in setting those options.
skipping to change at page 46, line 48 skipping to change at page 48, line 15
c) If neither the sockaddr_storage or association identification is c) If neither the sockaddr_storage or association identification is
set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and set, i.e. the sockaddr_storage is set to all 0's (INADDR_ANY) and
the association identification is 0, the settings are a default the association identification is 0, the settings are a default
and to be applied to the endpoint (all future associations). and to be applied to the endpoint (all future associations).
7.1. Read / Write Options 7.1. Read / Write Options
7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) 7.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO)
The protocol parameters used to initialize and bound retransmission The protocol parameters used to initialize and bound retransmission
timeout (RTO) are tunable. See RFC2960 [RFC2960] for more timeout (RTO) are tunable. See [RFC4960] for more information on how
information on how these parameters are used in RTO calculation. these parameters are used in RTO calculation.
The following structure is used to access and modify these The following structure is used to access and modify these
parameters: parameters:
struct sctp_rtoinfo { struct sctp_rtoinfo {
sctp_assoc_t srto_assoc_id; sctp_assoc_t srto_assoc_id;
uint32_t srto_initial; uint32_t srto_initial;
uint32_t srto_max; uint32_t srto_max;
uint32_t srto_min; uint32_t srto_min;
}; };
skipping to change at page 47, line 34 skipping to change at page 48, line 49
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_RTOINFO. SCTP_RTOINFO.
7.1.2. Association Parameters (SCTP_ASSOCINFO) 7.1.2. Association Parameters (SCTP_ASSOCINFO)
This option is used to both examine and set various association and This option is used to both examine and set various association and
endpoint parameters. endpoint parameters.
See RFC2960 [RFC2960] for more information on how this parameter is See [RFC4960] for more information on how this parameter is used.
used. The sasoc_assoc_id parameter is ignored for one-to-one style The sasoc_assoc_id parameter is ignored for one-to-one style socket.
socket.
The following structure is used to access and modify this parameters: The following structure is used to access and modify this parameters:
struct sctp_assocparams { struct sctp_assocparams {
sctp_assoc_t sasoc_assoc_id; sctp_assoc_t sasoc_assoc_id;
uint16_t sasoc_asocmaxrxt; uint16_t sasoc_asocmaxrxt;
uint16_t sasoc_number_peer_destinations; uint16_t sasoc_number_peer_destinations;
uint32_t sasoc_peer_rwnd; uint32_t sasoc_peer_rwnd;
uint32_t sasoc_local_rwnd; uint32_t sasoc_local_rwnd;
uint32_t sasoc_cookie_life; uint32_t sasoc_cookie_life;
skipping to change at page 48, line 43 skipping to change at page 50, line 4
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
than the sum of all maximum retransmission parameters, setsockopt() than the sum of all maximum retransmission parameters, setsockopt()
shall return an error. The reason for this, from RFC2960 [RFC2960] shall return an error. The reason for this, from [RFC4960] section
section 8.2: 8.2:
Note: When configuring the SCTP endpoint, the user should avoid Note: When configuring the SCTP endpoint, the user should avoid
having the value of 'Association.Max.Retrans' larger than the having the value of 'Association.Max.Retrans' larger than the
summation of the 'Path.Max.Retrans' of all the destination addresses summation of the 'Path.Max.Retrans' of all the destination addresses
for the remote endpoint. Otherwise, all the destination addresses for the remote endpoint. Otherwise, all the destination addresses
may become inactive while the endpoint still considers the peer may become inactive while the endpoint still considers the peer
endpoint reachable. endpoint reachable.
7.1.3. Initialization Parameters (SCTP_INITMSG) 7.1.3. Initialization Parameters (SCTP_INITMSG)
skipping to change at page 54, line 34 skipping to change at page 55, line 43
sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option. sctp_opt_info() with the SCTP_PEER_ADDR_PARAMS option.
7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM) 7.1.14. Set default send parameters (SCTP_DEFAULT_SEND_PARAM)
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
in to this call the sctp_sndrcvinfo structure defined in in to this call the sctp_sndrcvinfo structure defined in
Section 5.2.2) The input parameters accepted by this call include Section 5.2.2. The input parameters accepted by this call include
sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_pr_policy
sinfo_timetolive. The sinfo_assoc_id field specifies the association and sinfo_pr_value. The sinfo_flags is composed of a bitwise OR of
to apply the parameters to in a one-to-many style sockets. It is SCTP_UNORDERED, SCTP_EOF, and SCTP_SENDALL. The sinfo_assoc_id field
ignored on the one-to-one style. Note that setting the specifies the association to apply the parameters to in a one-to-many
sinfo_assoc_id field to zero indicates that the users wishes to set style sockets. It is ignored on the one-to-one style. Note that
the endpoint default send parameters for all future associations. setting the sinfo_assoc_id field to zero indicates that the users
wishes to set the endpoint default send parameters for all future
associations.
7.1.15. Set notification and ancillary events (SCTP_EVENTS) 7.1.15. Set notification and ancillary events (SCTP_EVENTS)
This socket option is used to specify various notifications and This socket option is used to specify various notifications and
ancillary data the user wishes to receive. Please see Section 7.3) ancillary data the user wishes to receive. Please see Section 7.3)
for a full description of this option and its usage. for a full description of this option and its usage.
7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR) 7.1.16. Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR)
This socket option is a boolean flag which turns on or off mapped V4 This socket option is a boolean flag which turns on or off mapped V4
skipping to change at page 56, line 20 skipping to change at page 57, line 33
Note that this option is write-only. Using this option in a Note that this option is write-only. Using this option in a
getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. getsockopt() or sctp_opt_info() call will return EOPNOTSUPP.
7.1.19. Get or set the list of supported HMAC Identifiers 7.1.19. Get or set the list of supported HMAC Identifiers
(SCTP_HMAC_IDENT) (SCTP_HMAC_IDENT)
This option gets or sets the list of HMAC algorithms that the local This option gets or sets the list of HMAC algorithms that the local
endpoint requires the peer to use. endpoint requires the peer to use.
struct sctp_hmacalgo { struct sctp_hmacalgo {
uint32_t shmac_number_of_idents;
uint16_t shmac_idents[]; uint16_t shmac_idents[];
}; };
shmac_number_of_idents - This field gives the number of elements
present in the array shmac_idents.
shmac_idents - This parameter contains an array of HMAC Identifiers shmac_idents - This parameter contains an array of HMAC Identifiers
that the local endpoint is requesting the peer to use, in priority that the local endpoint is requesting the peer to use, in priority
order. The following identifiers are valid: order. The following identifiers are valid:
1) SCTP_AUTH_HMAC_ID_SHA1 1) SCTP_AUTH_HMAC_ID_SHA1
2) SCTP_AUTH_HMAC_ID_SHA256 (optional) 2) SCTP_AUTH_HMAC_ID_SHA256 (optional)
3) SCTP_AUTH_HMAC_ID_SHA224 (optional) 3) SCTP_AUTH_HMAC_ID_SHA224 (optional)
4) SCTP_AUTH_HMAC_ID_SHA384 (optional) 4) SCTP_AUTH_HMAC_ID_SHA384 (optional)
4) SCTP_AUTH_HMAC_ID_SHA512 (optional) 4) SCTP_AUTH_HMAC_ID_SHA512 (optional)
skipping to change at page 56, line 48 skipping to change at page 58, line 22
cause the set option to fail and return an error. cause the set option to fail and return an error.
7.1.20. Set a shared key (SCTP_AUTH_KEY) 7.1.20. 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 which is used to build an
association shared key. association shared key.
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;
uint8_t sca_key[]; uint8_t sca_key[];
}; };
sca_assoc_id - This parameter, if non-zero, indicates what sca_assoc_id - This parameter, if non-zero, indicates what
association that the shared key is being set upon. Note that if association that the shared key is being set upon. Note that if
this element contains zero, then the shared key is set upon the this element contains zero, then the shared key is set upon the
endpoint and all future associations will use this key (if not endpoint and all future associations will use this key (if not
changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one
sockets, this parameter is ignored. Note, however, that this sockets, this parameter is ignored. Note, however, that this
option will set a key on the association if the socket is option will set a key on the association if the socket is
connected, otherwise this will set a key on the endpoint. connected, otherwise this will set a key on the endpoint.
sca_keynumber - this parameter is the shared key identifier by which sca_keynumber - this parameter is the shared key identifier by which
the application will refer to this key. If a key of the specified the application will refer to this key. If a key of the specified
skipping to change at page 57, line 17 skipping to change at page 58, line 39
endpoint and all future associations will use this key (if not endpoint and all future associations will use this key (if not
changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one changed by subsequent calls to SCTP_AUTH_KEY). For one-to-one
sockets, this parameter is ignored. Note, however, that this sockets, this parameter is ignored. Note, however, that this
option will set a key on the association if the socket is option will set a key on the association if the socket is
connected, otherwise this will set a key on the endpoint. connected, otherwise this will set a key on the endpoint.
sca_keynumber - this parameter is the shared key identifier by which sca_keynumber - this parameter is the shared key identifier by which
the application will refer to this key. If a key of the specified the application will refer to this key. If a key of the specified
index already exists, then this new key will replace the old index already exists, then this new key will replace the old
existing key. Note that shared key identifier '0' defaults to a existing key. Note that shared key identifier '0' defaults to a
null key. null key.
sca_keylength - this parameter is the length of the array sca_key.
sca_key - This parameter contains an array of bytes that is to be sca_key - This parameter contains an array of bytes that is to be
used by the endpoint (or association) as the shared secret key. used by the endpoint (or association) as the shared secret key.
Note, if the length of this field is zero, a null key is set. Note, if the length of this field is zero, a null key is set.
Note that this option is write-only. Using this option in a Note that this option is write-only. Using this option in a
getsockopt() or sctp_opt_info() call will return EOPNOTSUPP. getsockopt() or sctp_opt_info() call will return EOPNOTSUPP.
7.1.21. Get or set the active shared key (SCTP_AUTH_ACTIVE_KEY) 7.1.21. Get or set the active shared key (SCTP_AUTH_ACTIVE_KEY)
This option will get or set the active shared key to be used to build This option will get or set the active shared key to be used to build
skipping to change at page 61, line 29 skipping to change at page 62, line 50
control that turns the asconf feature off no matter what setting the control that turns the asconf feature off no matter what setting the
socket option may have. socket option may have.
7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST) 7.1.28. Set or Get the maximum burst (SCTP_MAX_BURST)
This option will allow a user to change the maximum burst of packets This option will allow a user to change the maximum burst of packets
that can be emitted by this association. Note that the default value that can be emitted by this association. Note that the default value
is 4, and some implementations may restrict this setting so that it is 4, and some implementations may restrict this setting so that it
can only be lowered. can only be lowered.
To set or get this option the user fills in the following structure:
struct sctp_assoc_value {
sctp_assoc_t assoc_id;
uint32_t assoc_value;
};
assoc_id - This parameter, indicates which association the user is
performing an action upon. Note that if this field's value is
zero then the endpoints default value is changed (effecting future
associations only).
assoc_value - This parameter contains the maximum burst.
7.1.29. Set or Get the default context (SCTP_CONTEXT) 7.1.29. Set or Get the default context (SCTP_CONTEXT)
The context field in the sctp_sndrcvinfo structure is normally only The context field in the sctp_sndrcvinfo structure is normally only
used when a failed message is retrieved holding the value that was used when a failed message is retrieved holding the value that was
sent down on the actual send call. This option allows the setting of sent down on the actual send call. This option allows the setting of
a default context on an association basis that will be received on a default context on an association basis that will be received on
reading messages from the peer. This is especially helpful in the reading messages from the peer. This is especially helpful in the
one-2-many model for an application to keep some reference to an one-2-many model for an application to keep some reference to an
internal state machine that is processing messages on the internal state machine that is processing messages on the
association. Note that the setting of this value only effects association. Note that the setting of this value only effects
skipping to change at page 62, line 20 skipping to change at page 64, line 6
7.1.30. Enable or disable explicit EOR marking (SCTP_EXPLICIT_EOR) 7.1.30. Enable or disable explicit EOR marking (SCTP_EXPLICIT_EOR)
This boolean flag is used to enable or disable explict end of record This boolean flag is used to enable or disable explict end of record
(EOR) marking. When this option is enabled, a user may make multiple (EOR) marking. When this option is enabled, a user may make multiple
send system calls to send a record and must indicate that they are send system calls to send a record and must indicate that they are
finished sending a particular record by including on the send the finished sending a particular record by including on the send the
SCTP_EOR flag. If this boolean flag is disabled then each individual SCTP_EOR flag. If this boolean flag is disabled then each individual
send system call is considered to have a SCTP_EOR indicator set on it send system call is considered to have a SCTP_EOR indicator set on it
implicitly without the user having to explicitly add this flag. implicitly without the user having to explicitly add this flag.
7.1.31. Enable SCTP port reusage (SCTP_REUSE_PORT)
This option only supports one-to-one style SCTP sockets. If used on
a one-to-many style SCTP socket an error is indicated.
The setsockopt() call MUST NOT be used after calling bind() or
sctp_bindx() for an one-to-one style SCTP socket. If using bind() or
sctp_bindx() on a socket with the SCTP_REUSE_PORT option, all other
SCTP sockets bound to the same port MUST have set the
SCTP_REUSE_PORT. Calling bind() or sctp_bindx() for a socket without
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
the same port may be listening.
It should be noted that the behaviour of the socket level socket
option to reuse ports and/or addresses for SCTP sockets in
unspecified.
7.2. Read-Only Options 7.2. Read-Only Options
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
association, including association state, peer receiver window size, association, including association state, peer receiver window size,
number of unacked data chunks, and number of data chunks pending number of unacked data chunks, and number of data chunks pending
receipt. This information is read-only. The following structure is receipt. This information is read-only. The following structure is
used to access this information: used to access this information:
skipping to change at page 64, line 40 skipping to change at page 66, line 42
SCTP_GET_PEER_ADDR_INFO options. SCTP_GET_PEER_ADDR_INFO options.
7.2.3. Get the list of chunks the peer requires to be authenticated 7.2.3. Get the list of chunks the peer requires to be authenticated
(SCTP_PEER_AUTH_CHUNKS) (SCTP_PEER_AUTH_CHUNKS)
This option gets a list of chunks for a specified association that This option gets a list of chunks for a specified association that
the peer requires to be received authenticated only. the peer requires to be received authenticated only.
struct sctp_authchunks { struct sctp_authchunks {
sctp_assoc_t gauth_assoc_id; sctp_assoc_t gauth_assoc_id;
guint32_t gauth_number_of_chunks
uint8_t gauth_chunks[]; uint8_t gauth_chunks[];
}; };
gauth_assoc_id - This parameter, indicates which association the gauth_assoc_id - This parameter, indicates which association the
user is requesting the list of peer authenticated chunks. For user is requesting the list of peer authenticated chunks. For
one-to-one sockets, this parameter is ignored. one-to-one sockets, this parameter is ignored.
gauth_number_of_chunks - This parameter gives the number of elements
in the array gauth_chunks.
gauth_chunks - This parameter contains an array of chunks that the gauth_chunks - This parameter contains an array of chunks that the
peer is requesting to be authenticated. peer is requesting to be authenticated.
7.2.4. Get the list of chunks the local endpoint requires to be 7.2.4. Get the list of chunks the local endpoint requires to be
authenticated (SCTP_LOCAL_AUTH_CHUNKS) authenticated (SCTP_LOCAL_AUTH_CHUNKS)
This option gets a list of chunks for a specified association that This option gets a list of chunks for a specified association that
the local endpoint requires to be received authenticated only. the local endpoint requires to be received authenticated only.
struct sctp_authchunks { struct sctp_authchunks {
sctp_assoc_t gauth_assoc_id; sctp_assoc_t gauth_assoc_id;
uint32_t gauth_number_of_chunks;
uint8_t gauth_chunks[]; uint8_t gauth_chunks[];
}; };
gauth_assoc_id - This parameter, indicates which association the gauth_assoc_id - This parameter, indicates which association the
user is requesting the list of local authenticated chunks. For user is requesting the list of local authenticated chunks. For
one-to-one sockets, this parameter is ignored. one-to-one sockets, this parameter is ignored.
gauth_number_of_chunks - This parameter gives the number of elements
in the array gauth_chunks.
gauth_chunks - This parameter contains an array of chunks that the gauth_chunks - This parameter contains an array of chunks that the
local endpoint is requesting to be authenticated. local endpoint is requesting to be authenticated.
7.2.5. Get the current number of associations (SCTP_GET_ASSOC_NUMBER) 7.2.5. Get the current number of associations (SCTP_GET_ASSOC_NUMBER)
This option gets the current number of associations that are attached This option gets the current number of associations that are attached
to a one-to-many style socket. The option value is an uint32_t. to a one-to-many style socket. The option value is an uint32_t.
7.2.6. Get the current identifiers of associations 7.2.6. Get the current identifiers of associations
(SCTP_GET_ASSOC_ID_LIST) (SCTP_GET_ASSOC_ID_LIST)
This option gets the current list of SCTP association identifiers of This option gets the current list of SCTP association identifiers of
the SCTP associations handled by a one-to-many style socket. The the SCTP associations handled by a one-to-many style socket. The
option value has the structure option value has the structure
struct sctp_assoc_ids { struct sctp_assoc_ids {
sctp_assoc_t gaids_assoc_id[0]; uint32_t gaids_number_of_ids;
sctp_assoc_t gaids_assoc_id[];
}; };
The caller MUST provide a large enough buffer to hold all association The caller MUST provide a large enough buffer to hold all association
identifiers. If the buffer is too small, an error MUST be returned. identifiers. If the buffer is too small, an error MUST be returned.
The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an The user can use the SCTP_GET_ASSOC_NUMBER socket option to get an
idea how large the buffer has to be. idea how large the buffer has to be. gaids_number_of_ids gives the
number of elements in the array gaids_assoc_id.
7.3. Ancillary Data and Notification Interest Options 7.3. 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:
1. SCTP_SNDRCV (sctp_data_io_event): Per-message information (i.e. 1. 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 68, line 49 skipping to change at page 70, line 50
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 would be returned. For a IPv4 socket, an array of sockaddr_in6 would be returned. For a IPv4
socket, an array of sockaddr_in would be returned. The caller socket, an array of sockaddr_in would be returned. The caller
specifies the number of addresses in the array with addrcnt. Note specifies the number of addresses in the array with addrcnt. Note
that the wildcard addresses cannot be used with this function, doing that the wildcard addresses cannot be used in combination with non
so will result in an error. wildcard addresses 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
the following currently defined flags: the following currently defined flags:
skipping to change at page 69, line 38 skipping to change at page 71, line 40
socket is associated with so that no new association accepted will be socket is associated with so that no new association accepted will be
associated with those addresses. If the endpoint supports dynamic associated with those addresses. If the endpoint supports dynamic
address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause a
endpoint to send the appropriate message to the peer to change the endpoint to send the appropriate message to the peer to change the
peers address lists. peers address lists.
Adding and removing addresses from a connected association is Adding and removing addresses from a connected association is
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_binx() can be called on an already bound socket or on an unbound sctp_bindx() can be called on an already bound socket or on an
socket. If the socket is unbound and the first port number in the unbound socket. If the socket is unbound and the first port number
addrs is zero, the kernel will chose a port number. All port number in the addrs is zero, the kernel will chose a port number. All port
after the first one being 0 MUST also be zero. If the first port numbers after the first one being 0 MUST also be zero. If the first
number is not zero, the following port numbers MUST be zero or have port number is not zero, the following port numbers MUST be zero or
the same value as the first one. For an already bound socket, all have the same value as the first one. For an already bound socket,
port numbers provided MUST the the bound one or 0. all port numbers provided MUST be the bound one or 0.
bindx() is an atomic operation. Therefore the binding will be either
successful on all addresses or fail on all addresses. If multiple
addresses are provided and the bindx() call fails there is no
indication which address is responsable for the failure. The only
way to get an specific error indication is to call bindx() with only
one address sequentially.
8.2. Branched-off Association 8.2. Branched-off Association
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 those
skipping to change at page 72, line 29 skipping to change at page 74, line 34
sctp_sendmsg(). Its syntax is, sctp_sendmsg(). Its syntax is,
ssize_t sctp_sendmsg(int sd, ssize_t sctp_sendmsg(int sd,
const void *msg, const void *msg,
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 timetolive, uint32_t pr_value,
uint32_t context) uint32_t context)
sd - is the socket descriptor sd - is the socket descriptor
msg - is the message to be sent. msg - is the message to be sent.
len - is the length of the message. len - is the length of the message.
to - is the destination address of the message. to - is the destination address of the message.
tolen - is the length of the destination address. tolen - is the length of the destination address.
ppid - is the same as sinfo_ppid (see section 5.2.2) ppid - is the same as sinfo_ppid (see section 5.2.2)
flags - is the same as sinfo_flags (see section 5.2.2) flags - is the same as sinfo_flags (see section 5.2.2)
stream_no - is the same as sinfo_stream (see section 5.2.2) stream_no - is the same as sinfo_stream (see section 5.2.2)
timetolive - is the same as sinfo_timetolive (see section 5.2.2) pr_value - is the same as sinfo_pr_value (see section 5.2.2).
context - is the same as sinfo_context (see section 5.2.2) context - is 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 marking is
enabled on the socket specified by sd. Using sendto() on a non-
connected one-to-one style socket for implicit connection setup may
or may not work depending on the SCTP implementation.
8.8. sctp_recvmsg() 8.8. sctp_recvmsg()
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 effect this function as well, causing the SCTP_USE_EXT_RCVINFO will effect this function as well, causing the
sctp_sndrcvinfo information to be extended. sctp_sndrcvinfo information to be extended.
skipping to change at page 74, line 19 skipping to change at page 76, line 25
int addrcnt, int addrcnt,
sctp_assoc_t *id) sctp_assoc_t *id)
sd - is the socket descriptor sd - is the socket descriptor
addrs - is an array of addresses. addrs - is an array of addresses.
addrcnt - is the number of addresses in the array. addrcnt - is the number of addresses in the array.
id - is an output parameter that if passed in as a non-NULL will id - is an output parameter that if passed in as a non-NULL will
return the association identification for the newly created return the association identification for the newly created
association (if successful). association (if successful).
The call returns 0 on success or -1 if an error occured. 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()
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. The function takes the following use of the CMSG header structures. The function takes the following
form: form:
sctp_send(). Its syntax is, sctp_send(). Its syntax is,
skipping to change at page 75, line 5 skipping to change at page 77, line 15
in 5.2.2 for a sendmsg call. in 5.2.2 for a sendmsg call.
flags - is used in the same format as the sendmsg call flags (e.g. flags - is used in the same format as the sendmsg call flags (e.g.
MSG_DONTROUTE). MSG_DONTROUTE).
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.
The call returns the number of characters sent, or -1 if an error Using sctp_send() on a non-connected one-to-one style socket for
occurred. The variable errno is then set appropriately. implicit connection setup may or may not work depending on the SCTP
implementation.
Sending a message using sctp_send() is atomic unless explicit EOR
marking is enabled on the socket specified by sd. The call returns
the number of characters sent, or -1 if an error occurred. The
variable errno is then set appropriately.
8.11. sctp_sendx() 8.11. sctp_sendx()
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).
skipping to change at page 75, line 48 skipping to change at page 78, line 21
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
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.
The call returns the number of characters sent, or -1 if an error Sending a message using sctp_send() is atomic unless explicit EOR
occurred. The variable errno is then set appropriately. marking is enabled on the socket specified by sd. The call returns
the number of characters sent, or -1 if an error occurred. The
variable errno is then set appropriately.
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
implementation.
8.12. sctp_getaddrlen 8.12. sctp_getaddrlen
For application binary portability it is sometimes desirable to know For application binary portability it is sometimes desirable to know
what the kernel thinks is the length of a socket address family. what the kernel thinks is the length of a socket address family.
This function, when called with a valid family type will return the This function, when called with a valid family type will return the
length that the operating system uses in the specified family's length that the operating system uses in the specified family's
socket address structure. socket address structure.
int sctp_getaddrlen(sa_family_t family); int sctp_getaddrlen(sa_family_t family);
9. Preprocessor Constants 9. IANA considerations
For application portability it is desirable to define pre-processor
constants for determination if sctp is present and supports various
features. The following pre-processor constants should be defined in
a include file, sctp.h.
HAVE_SCTP - If this constant is defined, then an implementation of
SCTP is available.
HAVE_KERNEL_SCTP - If this constant is defined, then a kernel SCTP
implementation is available through the sockets interface.
HAVE_SCTP_PRSCTP - If this constant is defined, then the SCTP
implementation supports the partial reliability extension to SCTP.
HAVE_SCTP_ADDIP - If this constant is defined, then the SCTP
implementation supports the dynamic address extension to SCTP.
HAVE_SCTP_CANSET_PRIMARY - If this constant is defined, then the
SCTP implementation supports the ability to request setting of the
remote primary address.
HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined, then
the SCTP implementation supports the satellite network extension
to SCTP.
HAVE_SCTP_MULTIBUF - If this constant is defined to 1, then the SCTP
implementation dedicates separate buffer space to each association
on a one-to-many socket. If this constant is defined to 0, then
the implementation provides a single block of shared buffer space
for a one-to-many socket.
HAVE_SCTP_NOCONNECT - If this constant is defined, then the SCTP
implementation supports initiating an association on a one-to-one
style socket without the use of connect(), as outlined in
Section 4.1.5.
HAVE_SCTP_EXT_RCVINFO - If this constant is defined, then the SCTP
implementation supports the use of the extended style sndrecinfo
structure, sctp_extrcvinfo.
10. IANA considerations
This document contains no IANA considerations. This document contains no IANA considerations.
11. 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 which 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:
struct sctp_rtoinfo 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.
12. Acknowledgments 11. Acknowledgments
Special acknowledgment is given to Ken Fujita and Jonathan Woods who Special acknowledgment is given to Ken Fujita and Jonathan Woods who
helped extensively in the early formation of this document. helped extensively in the early formation of this document.
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, and Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink,
many others on the TSVWG mailing list for contributing valuable Jonathan Leighton and many others on the TSVWG mailing list for
comments. 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.
13. Normative references 12. Normative references
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, September 1981. RFC 793, September 1981.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
August 1980. August 1980.
[RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions
Functional Specification", RFC 1644, July 1994. Functional Specification", RFC 1644, July 1994.
skipping to change at page 78, line 21 skipping to change at page 80, line 10
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2292] Stevens, W. and M. Thomas, "Advanced Sockets API for [RFC2292] Stevens, W. and M. Thomas, "Advanced Sockets API for
IPv6", RFC 2292, February 1998. IPv6", RFC 2292, February 1998.
[RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens, [RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens,
"Basic Socket Interface Extensions for IPv6", RFC 2553, "Basic Socket Interface Extensions for IPv6", RFC 2553,
March 1999. March 1999.
[RFC2960] Stewart, R., Xie, Q., Morneault, K., Sharp, C., [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P.
Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., Conrad, "Stream Control Transmission Protocol (SCTP)
Zhang, L., and V. Paxson, "Stream Control Transmission Partial Reliability Extension", RFC 3758, May 2004.
Protocol", RFC 2960, October 2000.
[RFC4960] Stewart, R., "Stream Control Transmission Protocol",
RFC 4960, September 2007.
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
skipping to change at page 87, line 5 skipping to change at page 88, line 12
Phone: Phone:
Email: kacheong.poon@sun.com Email: kacheong.poon@sun.com
Michael Tuexen Michael Tuexen
Univ. of Applied Sciences Muenster Univ. of Applied Sciences Muenster
Stegerwaldstr. 39 Stegerwaldstr. 39
48565 Steinfurt 48565 Steinfurt
Germany Germany
Email: tuexen@fh-muenster.de Email: tuexen@fh-muenster.de
Vladislav Yasevich
HP
110 Spitrook Rd
Nashua, NH, 03062
USA
Email: vladislav.yasevich@hp.com
Full Copyright Statement Full Copyright Statement
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors contained in BCP 78, and except as set forth therein, the authors
retain all their rights. retain all their rights.
This document and the information contained herein are provided on an This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
skipping to change at page 87, line 44 skipping to change at line 4058
attempt made to obtain a general license or permission for the use of attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr. http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at this standard. Please address the information to the IETF at
ietf-ipr@ietf.org. ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
 End of changes. 108 change blocks. 
252 lines changed or deleted 345 lines changed or added

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