draft-ietf-tsvwg-sctpsocket-26.txt   draft-ietf-tsvwg-sctpsocket-27.txt 
Network Working Group R. Stewart Network Working Group R. Stewart
Internet-Draft Huawei Internet-Draft Huawei
Intended status: Informational M. Tuexen Intended status: Informational M. Tuexen
Expires: August 1, 2011 Muenster Univ. of Applied Expires: September 2, 2011 Muenster Univ. of Appl. Sciences
Sciences
K. Poon K. Poon
Oracle Corporation Oracle Corporation
P. Lei P. Lei
Cisco Systems, Inc. Cisco Systems, Inc.
V. Yasevich V. Yasevich
HP HP
January 28, 2011 March 1, 2011
Sockets API Extensions for Stream Control Transmission Protocol (SCTP) Sockets API Extensions for Stream Control Transmission Protocol (SCTP)
draft-ietf-tsvwg-sctpsocket-26.txt draft-ietf-tsvwg-sctpsocket-27.txt
Abstract Abstract
This document describes a mapping of the Stream Control Transmission This document describes a mapping of the Stream Control Transmission
Protocol (SCTP) into a sockets API. The benefits of this mapping Protocol (SCTP) into a sockets API. The benefits of this mapping
include compatibility for TCP applications, access to new SCTP include compatibility for TCP applications, access to new SCTP
features and a consolidated error and event notification scheme. features and a consolidated error and event notification scheme.
Status of this Memo Status of this Memo
skipping to change at page 1, line 41 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 1, 2011. This Internet-Draft will expire on September 2, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 11 skipping to change at page 3, line 11
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 8 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8
3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8
3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 9 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 10
3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 10
3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 11 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 11
3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 12 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 12
3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 14 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 14
3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 14 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 15
3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 15 3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 15
3.3. Special considerations . . . . . . . . . . . . . . . . . 16 3.3. Special considerations . . . . . . . . . . . . . . . . . 16
4. One-to-One Style Interface . . . . . . . . . . . . . . . . . 18 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . 18
4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 18 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 18
4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 19 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 19
4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 19 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 19
4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 21 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 21
4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . 21 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . 21
4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 22 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 22
4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 23 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 23
4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . 23 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . 23
4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 24 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 24
4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 24 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 25
5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 25 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 25
5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 25 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 25
5.2. Ancillary Data Considerations and Semantics . . . . . . . 26 5.2. Ancillary Data Considerations and Semantics . . . . . . . 26
5.2.1. Multiple Items and Ordering . . . . . . . . . . . . . 26 5.2.1. Multiple Items and Ordering . . . . . . . . . . . . . 26
5.2.2. Accessing and Manipulating Ancillary Data . . . . . . 27 5.2.2. Accessing and Manipulating Ancillary Data . . . . . . 27
5.2.3. Control Message Buffer Sizing . . . . . . . . . . . . 27 5.2.3. Control Message Buffer Sizing . . . . . . . . . . . . 27
5.3. SCTP msg_control Structures . . . . . . . . . . . . . . . 28 5.3. SCTP msg_control Structures . . . . . . . . . . . . . . . 28
5.3.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 29 5.3.1. SCTP Initiation Structure (SCTP_INIT) . . . . . . . . 29
5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) - 5.3.2. SCTP Header Information Structure (SCTP_SNDRCV) -
DEPRECATED . . . . . . . . . . . . . . . . . . . . . 30 DEPRECATED . . . . . . . . . . . . . . . . . . . . . 30
skipping to change at page 4, line 27 skipping to change at page 4, line 27
6.2.1. SCTP_EVENTS option - DEPRECATED . . . . . . . . . . . 53 6.2.1. SCTP_EVENTS option - DEPRECATED . . . . . . . . . . . 53
6.2.2. SCTP_EVENT option . . . . . . . . . . . . . . . . . . 55 6.2.2. SCTP_EVENT option . . . . . . . . . . . . . . . . . . 55
7. Common Operations for Both Styles . . . . . . . . . . . . . . 56 7. Common Operations for Both Styles . . . . . . . . . . . . . . 56
7.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . 56 7.1. send(), recv(), sendto(), and recvfrom() . . . . . . . . 56
7.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 58 7.2. setsockopt() and getsockopt() . . . . . . . . . . . . . . 58
7.3. read() and write() . . . . . . . . . . . . . . . . . . . 59 7.3. read() and write() . . . . . . . . . . . . . . . . . . . 59
7.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 59 7.4. getsockname() . . . . . . . . . . . . . . . . . . . . . . 59
7.5. Implicit Association Setup . . . . . . . . . . . . . . . 60 7.5. Implicit Association Setup . . . . . . . . . . . . . . . 60
8. Socket Options . . . . . . . . . . . . . . . . . . . . . . . 61 8. Socket Options . . . . . . . . . . . . . . . . . . . . . . . 61
8.1. Read / Write Options . . . . . . . . . . . . . . . . . . 62 8.1. Read / Write Options . . . . . . . . . . . . . . . . . . 62
8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . 62 8.1.1. Retransmission Timeout Parameters (SCTP_RTOINFO) . . 63
8.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 63 8.1.2. Association Parameters (SCTP_ASSOCINFO) . . . . . . . 63
8.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . 65 8.1.3. Initialization Parameters (SCTP_INITMSG) . . . . . . 65
8.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 65 8.1.4. SO_LINGER . . . . . . . . . . . . . . . . . . . . . . 65
8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . 66 8.1.5. SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . 66
8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 66 8.1.6. SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . 66
8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 66 8.1.7. SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . 66
8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . 66 8.1.8. Automatic Close of Associations (SCTP_AUTOCLOSE) . . 67
8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 67 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . 67
8.1.10. Set Adaptation Layer Indicator 8.1.10. Set Adaptation Layer Indicator
(SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 67 (SCTP_ADAPTATION_LAYER) . . . . . . . . . . . . . . . 67
8.1.11. Enable/Disable Message Fragmentation 8.1.11. Enable/Disable Message Fragmentation
(SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . 68 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . 68
8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 68 8.1.12. Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . 68
8.1.13. Set Default Send Parameters 8.1.13. Set Default Send Parameters
(SCTP_DEFAULT_SEND_PARAM) - DEPRECATED . . . . . . . 70 (SCTP_DEFAULT_SEND_PARAM) - DEPRECATED . . . . . . . 71
8.1.14. Set Notification and Ancillary Events 8.1.14. Set Notification and Ancillary Events
(SCTP_EVENTS) - DEPRECATED . . . . . . . . . . . . . 71 (SCTP_EVENTS) - DEPRECATED . . . . . . . . . . . . . 71
8.1.15. Set/Clear IPv4 Mapped Addresses 8.1.15. Set/Clear IPv4 Mapped Addresses
(SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . 71 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . 71
8.1.16. Get or Set the Maximum Fragmentation Size 8.1.16. Get or Set the Maximum Fragmentation Size
(SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 71 (SCTP_MAXSEG) . . . . . . . . . . . . . . . . . . . . 72
8.1.17. Get or Set the List of Supported HMAC Identifiers 8.1.17. Get or Set the List of Supported HMAC Identifiers
(SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 72 (SCTP_HMAC_IDENT) . . . . . . . . . . . . . . . . . . 72
8.1.18. Get or Set the Active Shared Key 8.1.18. Get or Set the Active Shared Key
(SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . 72 (SCTP_AUTH_ACTIVE_KEY) . . . . . . . . . . . . . . . 73
8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 73 8.1.19. Get or Set Delayed SACK Timer (SCTP_DELAYED_SACK) . . 74
8.1.20. Get or Set Fragmented Interleave 8.1.20. Get or Set Fragmented Interleave
(SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . 74 (SCTP_FRAGMENT_INTERLEAVE) . . . . . . . . . . . . . 74
8.1.21. Set or Get the SCTP Partial Delivery Point 8.1.21. Set or Get the SCTP Partial Delivery Point
(SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 75 (SCTP_PARTIAL_DELIVERY_POINT) . . . . . . . . . . . . 76
8.1.22. Set or Get the Use of Extended Receive Info 8.1.22. Set or Get the Use of Extended Receive Info
(SCTP_USE_EXT_RCVINFO) - DEPRECATED . . . . . . . . . 76 (SCTP_USE_EXT_RCVINFO) - DEPRECATED . . . . . . . . . 76
8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . 76 8.1.23. Set or Get the Auto ASCONF Flag (SCTP_AUTO_ASCONF) . 76
8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 76 8.1.24. Set or Get the Maximum Burst (SCTP_MAX_BURST) . . . . 77
8.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 77 8.1.25. Set or Get the Default Context (SCTP_CONTEXT) . . . . 77
8.1.26. Enable or Disable Explicit EOR Marking 8.1.26. Enable or Disable Explicit EOR Marking
(SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 77 (SCTP_EXPLICIT_EOR) . . . . . . . . . . . . . . . . . 78
8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . 78 8.1.27. Enable SCTP Port Reusage (SCTP_REUSE_PORT) . . . . . 78
8.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 78 8.1.28. Set Notification Event (SCTP_EVENT) . . . . . . . . . 78
8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as 8.1.29. Enable or Disable the Delivery of SCTP_RCVINFO as
Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 78 Ancillary Data (SCTP_RECVRCVINFO) . . . . . . . . . . 78
8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as 8.1.30. Enable or Disable the Delivery of SCTP_NXTINFO as
Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 78 Ancillary Data (SCTP_RECVNXTINFO) . . . . . . . . . . 79
8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . 79 8.1.31. Set Default Send Parameters (SCTP_DEFAULT_SNDINFO) . 79
8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 79 8.2. Read-Only Options . . . . . . . . . . . . . . . . . . . . 79
8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . 79 8.2.1. Association Status (SCTP_STATUS) . . . . . . . . . . 79
8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . 81 8.2.2. Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . 81
8.2.3. Get the List of Chunks the Peer Requires to be 8.2.3. Get the List of Chunks the Peer Requires to be
Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 82 Authenticated (SCTP_PEER_AUTH_CHUNKS) . . . . . . . . 82
8.2.4. Get the List of Chunks the Local Endpoint Requires 8.2.4. Get the List of Chunks the Local Endpoint Requires
to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . 82 to be Authenticated (SCTP_LOCAL_AUTH_CHUNKS) . . . . 83
8.2.5. Get the Current Number of Associations 8.2.5. Get the Current Number of Associations
(SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 83 (SCTP_GET_ASSOC_NUMBER) . . . . . . . . . . . . . . . 83
8.2.6. Get the Current Identifiers of Associations 8.2.6. Get the Current Identifiers of Associations
(SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . 83 (SCTP_GET_ASSOC_ID_LIST) . . . . . . . . . . . . . . 84
8.3. Write-Only Options . . . . . . . . . . . . . . . . . . . 84 8.3. Write-Only Options . . . . . . . . . . . . . . . . . . . 84
8.3.1. Set Peer Primary Address 8.3.1. Set Peer Primary Address
(SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . 84 (SCTP_SET_PEER_PRIMARY_ADDR) . . . . . . . . . . . . 84
8.3.2. Add a Chunk That Must Be Authenticated 8.3.2. Add a Chunk that must be Authenticated
(SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 84 (SCTP_AUTH_CHUNK) . . . . . . . . . . . . . . . . . . 85
8.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . 85 8.3.3. Set a Shared Key (SCTP_AUTH_KEY) . . . . . . . . . . 85
8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . 85 8.3.4. Deactivate a Shared Key (SCTP_AUTH_DEACTIVATE_KEY) . 86
8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . 86 8.3.5. Delete a Shared Key (SCTP_AUTH_DELETE_KEY) . . . . . 86
9. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 86 9. New Functions . . . . . . . . . . . . . . . . . . . . . . . . 87
9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . 87 9.1. sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . 87
9.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . 88 9.2. sctp_peeloff() . . . . . . . . . . . . . . . . . . . . . 89
9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . 89 9.3. sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . 89
9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 90 9.4. sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 90
9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . 90 9.5. sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . 90
9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 90 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 91
9.7. sctp_sendmsg() - DEPRECATED . . . . . . . . . . . . . . . 91 9.7. sctp_sendmsg() - DEPRECATED . . . . . . . . . . . . . . . 91
9.8. sctp_recvmsg() - DEPRECATED . . . . . . . . . . . . . . . 92 9.8. sctp_recvmsg() - DEPRECATED . . . . . . . . . . . . . . . 92
9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 93 9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 93
9.10. sctp_send() - DEPRECATED . . . . . . . . . . . . . . . . 94 9.10. sctp_send() - DEPRECATED . . . . . . . . . . . . . . . . 94
9.11. sctp_sendx() - DEPRECATED . . . . . . . . . . . . . . . . 95 9.11. sctp_sendx() - DEPRECATED . . . . . . . . . . . . . . . . 95
9.12. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . 96 9.12. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 96
9.13. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 98 9.13. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . 99
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 100 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 101
11. Security Considerations . . . . . . . . . . . . . . . . . . . 101 11. Security Considerations . . . . . . . . . . . . . . . . . . . 101
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 101 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 101
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 101 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 102
13.1. Normative References . . . . . . . . . . . . . . . . . . 101 13.1. Normative References . . . . . . . . . . . . . . . . . . 102
13.2. Informative References . . . . . . . . . . . . . . . . . 102 13.2. Informative References . . . . . . . . . . . . . . . . . 102
Appendix A. One-to-One Style Code Example . . . . . . . . . . . 102 Appendix A. One-to-One Style Code Example . . . . . . . . . . . 102
Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 105 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 105
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 110
1. Introduction 1. Introduction
The sockets API has provided a standard mapping of the Internet The sockets API has provided a standard mapping of the Internet
Protocol suite to many operating systems. Both TCP [RFC0793] and UDP Protocol suite to many operating systems. Both TCP [RFC0793] and UDP
[RFC0768] have benefited from this standard representation and access [RFC0768] have benefited from this standard representation and access
skipping to change at page 7, line 28 skipping to change at page 7, line 28
1. Maintain consistency with existing sockets APIs: We define a 1. Maintain consistency with existing sockets APIs: We define a
sockets mapping for SCTP that is consistent with other sockets sockets mapping for SCTP that is consistent with other sockets
API protocol mappings (for instance UDP, TCP, IPv4, and IPv6). API protocol mappings (for instance UDP, TCP, IPv4, and IPv6).
2. Support a one-to-many style interface: This set of semantics is 2. Support a one-to-many style interface: This set of semantics is
similar to that defined for connection-less protocols, such as similar to that defined for connection-less protocols, such as
UDP. A one-to-many style SCTP socket should be able to control UDP. A one-to-many style SCTP socket should be able to control
multiple SCTP associations. This is similar to a UDP socket, multiple SCTP associations. This is similar to a UDP socket,
which can communicate with many peer endpoints. Each of these which can communicate with many peer endpoints. Each of these
associations is assigned an association ID so that an application associations is assigned an association identifier so that an
can use the ID to differentiate them. Note that SCTP is application can use the ID to differentiate them. Note that SCTP
connection-oriented in nature, and it does not support broadcast is connection-oriented in nature, and it does not support
or multicast communications, as UDP does. broadcast or multicast communications, as UDP does.
3. Support a one-to-one style interface: This interface supports a 3. Support a one-to-one style interface: This interface supports a
similar semantics as sockets for connection-oriented protocols, similar semantics as sockets for connection-oriented protocols,
such as TCP. A one-to-one style SCTP socket should only control such as TCP. A one-to-one style SCTP socket should only control
one SCTP association. One purpose of defining this interface is one SCTP association. One purpose of defining this interface is
to allow existing applications built on other connection-oriented to allow existing applications built on other connection-oriented
protocols to be ported to use SCTP with very little effort. protocols to be ported to use SCTP with very little effort.
Developers familiar with these semantics can easily adapt to Developers familiar with these semantics can easily adapt to
SCTP. Another purpose is to make sure that existing mechanisms SCTP. Another purpose is to make sure that existing mechanisms
in most operating systems that support sockets, such as select(), in most operating systems that support sockets, such as select(),
skipping to change at page 9, line 10 skipping to change at page 9, line 10
o socket() o socket()
o sendmsg() o sendmsg()
o recvmsg() o recvmsg()
o close() o close()
In this style, by default, all the associations connected to the In this style, by default, all the associations connected to the
endpoint are represented with a single socket. Each association is endpoint are represented with a single socket. Each association is
assigned an association ID (type is sctp_assoc_t) so that an assigned an association identifier (type is sctp_assoc_t) so that an
application can use it to differentiate among them. In some application can use it to differentiate among them. In some
implementations, the peer endpoints' addresses can also be used for implementations, the peer endpoints' addresses can also be used for
this purpose. But this is not required for performance reasons. If this purpose. But this is not required for performance reasons. If
an implementation does not support using addresses to differentiate an implementation does not support using addresses to differentiate
between different associations, the sendto() call can only be used to between different associations, the sendto() call can only be used to
setup an association implicitly. It cannot be used to send data to setup an association implicitly. It cannot be used to send data to
an established association as the association ID cannot be specified. an established association as the association identifier cannot be
specified.
Once an association ID is assigned to an SCTP association, that ID Once an association identifier is assigned to an SCTP association,
will not be reused until the application explicitly terminates the that identifier will not be reused until the application explicitly
use of the association. The resources belonging to that association terminates the use of the association. The resources belonging to
will not be freed until that happens. This is similar to the close() that association will not be freed until that happens. This is
operation on a normal socket. The only exception is when the similar to the close() operation on a normal socket. The only
SCTP_AUTOCLOSE option (section 7.1.8) is set. In this case, after exception is when the SCTP_AUTOCLOSE option (section 7.1.8) is set.
the association is terminated gracefully and automatically, the In this case, after the association is terminated gracefully and
association ID assigned to it can be reused. All applications using automatically, the association identifier assigned to it can be
this option should be aware of this to avoid the possible problem of reused. All applications using this option should be aware of this
sending data to an incorrect peer endpoint. to avoid the possible problem of sending data to an incorrect peer
endpoint.
If the server or client wishes to branch an existing association off If the server or client wishes to branch an existing association off
to a separate socket, it is required to call sctp_peeloff() and to to a separate socket, it is required to call sctp_peeloff() and to
specify the association identifier. The sctp_peeloff() call will specify the association identifier. The sctp_peeloff() call will
return a new one-to-one style socket which can then be used with return a new one-to-one style socket which can then be used with
recv() and send() functions for message passing. See Section 9.2 for recv() and send() functions for message passing. See Section 9.2 for
more on branched-off associations. more on branched-off associations.
Once an association is branched off to a separate socket, it becomes Once an association is branched off to a separate socket, it becomes
completely separated from the original socket. All subsequent completely separated from the original socket. All subsequent
skipping to change at page 12, line 24 skipping to change at page 12, line 27
are accepted automatically, and notifications of the new associations are accepted automatically, and notifications of the new associations
are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if are delivered via recvmsg() with the SCTP_ASSOC_CHANGE event (if
these notifications are enabled). Clients will typically not call these notifications are enabled). Clients will typically not call
listen(), so that they can be assured that only actively initiated listen(), so that they can be assured that only actively initiated
associations are possible on the socket. Server or peer-to-peer associations are possible on the socket. Server or peer-to-peer
sockets, on the other hand, will always accept new associations, so a sockets, on the other hand, will always accept new associations, so a
well-written application using server one-to-many style sockets must well-written application using server one-to-many style sockets must
be prepared to handle new associations from unwanted peers. be prepared to handle new associations from unwanted peers.
Also note that the SCTP_ASSOC_CHANGE event provides the association Also note that the SCTP_ASSOC_CHANGE event provides the association
ID for a new association, so if applications wish to use the identifier for a new association, so if applications wish to use the
association ID as a parameter to other socket calls, they should association identifier as a parameter to other socket calls, they
ensure that the SCTP_ASSOC_CHANGE event is enabled. should ensure that the SCTP_ASSOC_CHANGE event is enabled.
3.1.4. sendmsg() and recvmsg() 3.1.4. sendmsg() and recvmsg()
An application uses the sendmsg() and recvmsg() call to transmit data An application uses the sendmsg() and recvmsg() call to transmit data
to and receive data from its peer. to and receive data from its peer.
The function prototypes are The function prototypes are
ssize_t sendmsg(int sd, ssize_t sendmsg(int sd,
const struct msghdr *message, const struct msghdr *message,
skipping to change at page 13, line 33 skipping to change at page 13, line 35
When sending user data with sendmsg(), the msg_name field in the When sending user data with sendmsg(), the msg_name field in the
msghdr structure will be filled with one of the transport addresses msghdr structure will be filled with one of the transport addresses
of the intended receiver. If there is no existing association of the intended receiver. If there is no existing association
between the sender and the intended receiver, the sender's SCTP stack between the sender and the intended receiver, the sender's SCTP stack
will set up a new association and then send the user data (see will set up a new association and then send the user data (see
Section 7.5 for more on implicit association setup). If sendmsg() is Section 7.5 for more on implicit association setup). If sendmsg() is
called with no data and there is no existing association, a new one called with no data and there is no existing association, a new one
will be established. The SCTP_INIT type ancillary data can be used will be established. The SCTP_INIT type ancillary data can be used
to change some of the parameters used to set up a new association. to change some of the parameters used to set up a new association.
If sendmsg() is called with NULL data, and there is no existing If sendmsg() is called with NULL data, and there is no existing
association but the SCTP_ABORT or SCTP_EOF flags are set, then -1 is association but the SCTP_ABORT or SCTP_EOF flags are set as described
returned and errno is set to EINVAL. Sending a message using in Section 5.3.4, then -1 is returned and errno is set to EINVAL.
sendmsg() is atomic unless explicit EOR marking is enabled on the Sending a message using sendmsg() is atomic unless explicit EOR
socket specified by sd (see Section 8.1.26). marking is enabled on the socket specified by sd (see
Section 8.1.26).
If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will If a peer sends a SHUTDOWN, an SCTP_SHUTDOWN_EVENT notification will
be delivered if that notification has been enabled, and no more data be delivered if that notification has been enabled, and no more data
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
the msghdr structure will be populated with the source transport the msghdr structure will be populated with the source transport
address of the user data. The caller of recvmsg() can use this address of the user data. The caller of recvmsg() can use this
address information to determine to which association the received address information to determine to which association the received
user message belongs. Note that if SCTP_ASSOC_CHANGE events are user message belongs. Note that if SCTP_ASSOC_CHANGE events are
disabled, applications must use the peer transport address provided disabled, applications must use the peer transport address provided
in the msg_name field by recvmsg() to perform correlation to an in the msg_name field by recvmsg() to perform correlation to an
association, since they will not have the association ID. association, since they will not have the association identifier.
If all data in a single message has been delivered, MSG_EOR will be If all data in a single message has been delivered, MSG_EOR will be
set in the msg_flags field of the msghdr structure (see Section 5.1). set in the msg_flags field of the msghdr structure (see Section 5.1).
If the application does not provide enough buffer space to completely If the application does not provide enough buffer space to completely
receive a data message, MSG_EOR will not be set in msg_flags. receive a data message, MSG_EOR will not be set in msg_flags.
Successive reads will consume more of the same message until the Successive reads will consume more of the same message until the
entire message has been delivered, and MSG_EOR will be set. entire message has been delivered, and MSG_EOR will be set.
If the SCTP stack is running low on buffers, it may partially deliver If the SCTP stack is running low on buffers, it may partially deliver
skipping to change at page 14, line 44 skipping to change at page 14, line 47
sd: The socket descriptor of the associations to be closed. sd: The socket descriptor of the associations to be closed.
0 is returned on success and -1 in case of an error. 0 is returned on success and -1 in case of an error.
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 include the SCTP_EOF flag. A user may optionally terminate an and include the SCTP_EOF flag. A user may optionally terminate an
association non-gracefully by sending with the SCTP_ABORT flag set association non-gracefully by sending with the SCTP_ABORT flag set
and possibly passing a user specified abort code in the data field. and possibly passing a user specified abort code in the data field.
Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data Both flags SCTP_EOF and SCTP_ABORT are passed with ancillary data
(see Section 5.3.2) in the sendmsg() call. (see Section 5.3.4) in the sendmsg() call.
If sd in the close() call is a branched-off socket representing only If sd in the close() call is a branched-off socket representing only
one association, the shutdown is performed on that association only. one association, the shutdown is performed on that association only.
3.1.6. connect() 3.1.6. connect()
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 function prototype is The function prototype is
skipping to change at page 16, line 4 skipping to change at page 16, line 9
Some SCTP application may wish to avoid being blocked when calling a Some SCTP application may wish to avoid being blocked when calling a
socket interface function. socket interface function.
Once a bind() and/or subsequent sctp_bindx() calls are complete on a Once a bind() and/or subsequent sctp_bindx() calls are complete on a
one-to-many style socket, an application may set the non-blocking one-to-many style socket, an application may set the non-blocking
option by a fcntl() (such as O_NONBLOCK). After setting the socket option by a fcntl() (such as O_NONBLOCK). After setting the socket
to non-blocking mode, the sendmsg() function returns immediately. to non-blocking mode, the sendmsg() function returns immediately.
The success or failure of sending the data message (with possible The success or failure of sending the data message (with possible
SCTP_INITMSG ancillary data) will be signaled by the SCTP_INITMSG ancillary data) will be signaled by the
SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or SCTP_CANT_START_ASSOC. SCTP_ASSOC_CHANGE event with SCTP_COMM_UP or SCTP_CANT_START_ASSOC.
If user data could not be sent (due to a SCTP_CANT_START_ASSOC), the If user data could not be sent (due to a SCTP_CANT_START_ASSOC), the
sender will also receive an SCTP_SEND_FAILED_EVENT event. Events can sender will also receive an SCTP_SEND_FAILED_EVENT event. Events can
be received by the user calling recvmsg(). A server (having called be received by the user calling recvmsg(). A server (having called
listen()) is also notified of an association up event by the listen()) is also notified of an association up event by the
reception of an SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling reception of an SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling
of recvmsg() and possibly the reception of the first data message. of recvmsg() and possibly the reception of the first data message.
To shutdown the association gracefully, the user must call sendmsg() To shutdown the association gracefully, the user must call sendmsg()
with no data and with the SCTP_EOF flag set. The function returns with no data and with the SCTP_EOF flag set as described in
immediately, and completion of the graceful shutdown is indicated by Section 5.3.4. The function returns immediately, and completion of
an SCTP_ASSOC_CHANGE notification of type SHUTDOWN_COMPLETE (see the graceful shutdown is indicated by an SCTP_ASSOC_CHANGE
Section 6.1.1). Note that this can also be done using the notification of type SHUTDOWN_COMPLETE (see Section 6.1.1). Note
sctp_send() call described in Section 9.10. that this can also be done using the sctp_sendv() call described in
Section 9.12.
An application is recommended to use caution when using select() (or An application is recommended to use caution when using select() (or
poll()) for writing on a one-to-many style socket. The reason being poll()) for writing on a one-to-many style socket. The reason being
that the interpretation of select on write is implementation that the interpretation of select on write is implementation
specific. Generally a positive return on a select on write would specific. Generally a positive return on a select on write would
only indicate that one of the associations represented by the one-to- only indicate that one of the associations represented by the one-to-
many socket is writable. An application that writes after the many socket is writable. An application that writes after the
select() returns may still block since the association that was select() returns may still block since the association that was
writeable is not the destination association of the write call. writeable is not the destination association of the write call.
Likewise select() (or poll()) for reading from a one-to-many socket Likewise select() (or poll()) for reading from a one-to-many socket
skipping to change at page 16, line 45 skipping to change at page 16, line 50
Note some implementations may have an extended select call such as Note some implementations may have an extended select call such as
epoll or kqueue that may escape this limitation and allow a select on epoll or kqueue that may escape this limitation and allow a select on
a specific association of a one-to-many socket, but this is an a specific association of a one-to-many socket, but this is an
implementation specific detail that a portable application cannot implementation specific detail that a portable application cannot
depend on. depend on.
3.3. Special considerations 3.3. Special considerations
The fact that a one-to-many style socket can provide access to many The fact that a one-to-many style socket can provide access to many
SCTP associations through a single socket descriptor has important SCTP associations through a single socket descriptor, has important
implications for both application programmers and system programmers implications for both application programmers and system programmers
implementing this API. A key issue is how buffer space inside the implementing this API. A key issue is how buffer space inside the
sockets layer is managed. Because this implementation detail sockets layer is managed. Because this implementation detail
directly affects how application programmers must write their code to directly affects how application programmers must write their code to
ensure correct operation and portability, this section provides some ensure correct operation and portability, this section provides some
guidance to both implementers and application programmers. guidance to both implementers and application programmers.
An important feature that SCTP shares with TCP is flow control. An important feature that SCTP shares with TCP is flow control.
Specifically, a sender may not send data faster than the receiver can Specifically, a sender may not send data faster than the receiver can
consume it. consume it.
For TCP, flow control is typically provided for in the sockets API as For TCP, flow control is typically provided for in the sockets API as
follows. If the reader stops reading, the sender queues messages in follows. If the reader stops reading, the sender queues messages in
the socket layer until it uses all of its socket buffer space the socket layer until the send socket buffer is completely filled.
allocation creating a "stalled connection". Further attempts to This results in a "stalled connection". Further attempts to write to
write to the socket will block or return the error EAGAIN or the socket will block or return the error EAGAIN or EWOULDBLOCK for a
EWOULDBLOCK for a non-blocking socket. At some point, either the non-blocking socket. At some point, either the connection is closed,
connection is closed, or the receiver begins to read again freeing or the receiver begins to read again freeing space in the output
space in the output queue. queue.
For one-to-one style SCTP sockets (this includes sockets descriptors For one-to-one style SCTP sockets (this includes sockets descriptors
that were separated from a one-to-many style socket with that were separated from a one-to-many style socket with
sctp_peeloff()) the behavior is identical. For one-to-many style sctp_peeloff()) the behavior is identical. For one-to-many style
SCTP sockets there are multiple associations for a single socket, SCTP sockets there are multiple associations for a single socket,
which makes the situation more complicated. If the implementation which makes the situation more complicated. If the implementation
uses a single buffer space allocation shared by all associations, a uses a single buffer space allocation shared by all associations, a
single stalled association can prevent the further sending of data on single stalled association can prevent the further sending of data on
all associations active on a particular one-to-many style socket. all associations active on a particular one-to-many style socket.
skipping to change at page 24, line 28 skipping to change at page 24, line 34
To perform the ABORT operation described in [RFC4960] Section 10.1, To perform the ABORT operation described in [RFC4960] Section 10.1,
an application can use the socket option SO_LINGER. It is described an application can use the socket option SO_LINGER. It is described
in Section 8.1.4. in Section 8.1.4.
4.1.8. sendmsg() and recvmsg() 4.1.8. sendmsg() and recvmsg()
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 (see Section 3.1.3), with the following differences: style (see Section 3.1.4), 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 preferred peer address if the sender wishes to discourage the
stack from sending the message to the primary address of the stack from sending the message to the primary address of the
receiver. If the socket is connected and the transport address receiver. If the socket is connected and the transport address
given is not part of the current association, the data will not given is not part of the current association, the data will not
be sent and an SCTP_SEND_FAILED_EVENT event will be delivered to be sent and an SCTP_SEND_FAILED_EVENT event will be delivered to
the application if send failure events are enabled. the application if send failure events are enabled.
skipping to change at page 26, line 23 skipping to change at page 26, line 23
}; };
struct cmsghdr { struct cmsghdr {
socklen_t cmsg_len; /* #bytes, including this header */ socklen_t cmsg_len; /* #bytes, including this header */
int cmsg_level; /* originating protocol */ int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */ int cmsg_type; /* protocol-specific type */
/* followed by unsigned char cmsg_data[]; */ /* followed by unsigned char cmsg_data[]; */
}; };
In the msghdr structure, the usage of msg_name has been discussed in In the msghdr structure, the usage of msg_name has been discussed in
previous sections (see Section 3.1.3 and Section 4.1.8). previous sections (see Section 3.1.4 and Section 4.1.8).
The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov The scatter/gather buffers, or I/O vectors (pointed to by the msg_iov
field) are treated by SCTP as a single user message for both field) are treated by SCTP as a single user message for both
sendmsg() and recvmsg(). sendmsg() and recvmsg().
SCTP stack uses the ancillary data (msg_control field) to communicate SCTP stack uses the ancillary data (msg_control field) to communicate
the attributes, such as SCTP_RCVINFO, of the message stored in the attributes, such as SCTP_RCVINFO, of the message stored in
msg_iov to the socket end point. The different ancillary data types msg_iov to the socket end point. The different ancillary data types
are described in Section 5.3. are described in Section 5.3.
skipping to change at page 34, line 34 skipping to change at page 34, line 34
SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that SCTP_NEXT_MSG_IS_NOTIFICATION: This bit, when set, indicates that
the next message to be received is not a message from the peer, the next message to be received is not a message from the peer,
but instead is a MSG_NOTIFICATION from the local SCTP stack. but instead is a MSG_NOTIFICATION from the local SCTP stack.
serinfo_next_stream: This value, when valid (see serinfo_next_stream: This value, when valid (see
serinfo_next_flags), contains the next stream number that will be serinfo_next_flags), contains the next stream number that will be
received on a subsequent call to one of the receive message received on a subsequent call to one of the receive message
functions. functions.
serinfo_next_aid: This value, when valid (see serinfo_next_flags), serinfo_next_aid: This value, when valid (see serinfo_next_flags),
contains the next association identification that will be received contains the next association identifier that will be received on
on a subsequent call to one of the receive message functions. a subsequent call to one of the receive message functions.
serinfo_next_length: This value, when valid (see serinfo_next_length: This value, when valid (see
serinfo_next_flags), contains the length of the next message that serinfo_next_flags), contains the length of the next message that
will be received on a subsequent call to one of the receive will be received on a subsequent call to one of the receive
message functions. Note that this length may be a partial length message functions. Note that this length may be a partial length
depending on the settings of next_flags. depending on the settings of next_flags.
serinfo_next_ppid: This value, when valid (see serinfo_next_flags), serinfo_next_ppid: This value, when valid (see serinfo_next_flags),
contains the ppid of the next message that will be received on a contains the ppid of the next message that will be received on a
subsequent call to one of the receive message functions. subsequent call to one of the receive message functions.
skipping to change at page 40, line 29 skipping to change at page 40, line 29
This cmsghdr structure specifies SCTP options for sendmsg(). This cmsghdr structure specifies SCTP options for sendmsg().
+--------------+----------------+----------------+ +--------------+----------------+----------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+----------------+----------------+ +--------------+----------------+----------------+
| IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr | | IPPROTO_SCTP | SCTP_DSTADDRV4 | struct in_addr |
+--------------+----------------+----------------+ +--------------+----------------+----------------+
This ancillary data can be used to provide more than one destination This ancillary data can be used to provide more than one destination
address to sendmsg(). It can be used to implement sctp_sendv() using address to sendmsg(). It can be used to implement sctp_sendv() using
send_msg(). sendmsg().
5.3.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6) 5.3.10. SCTP Destination Address Structure (IPv6) (SCTP_DSTADDRV6)
This cmsghdr structure specifies SCTP options for sendmsg(). This cmsghdr structure specifies SCTP options for sendmsg().
+--------------+----------------+-----------------+ +--------------+----------------+-----------------+
| cmsg_level | cmsg_type | cmsg_data[] | | cmsg_level | cmsg_type | cmsg_data[] |
+--------------+----------------+-----------------+ +--------------+----------------+-----------------+
| IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr | | IPPROTO_SCTP | SCTP_DSTADDRV6 | struct in6_addr |
+--------------+----------------+-----------------+ +--------------+----------------+-----------------+
This ancillary data can be used to provide more than one destination This ancillary data can be used to provide more than one destination
address to sendmsg(). It can be used to implement sctp_sendv() using address to sendmsg(). It can be used to implement sctp_sendv() using
send_msg(). sendmsg().
6. SCTP Events and Notifications 6. SCTP Events and Notifications
An SCTP application may need to understand and process events and An SCTP application may need to understand and process events and
errors that happen on the SCTP stack. These events include network errors that happen on the SCTP stack. These events include network
status changes, association startups, remote operational errors and status changes, association startups, remote operational errors and
undeliverable messages. All of these can be essential for the undeliverable messages. All of these can be essential for the
application. application.
When an SCTP application layer does a recvmsg() the message read is When an SCTP application layer does a recvmsg() the message read is
skipping to change at page 44, line 22 skipping to change at page 44, line 22
SCTP_COMM_LOST) any relevant error information is available in SCTP_COMM_LOST) any relevant error information is available in
this field. This corresponds to the protocol error codes defined this field. This corresponds to the protocol error codes defined
in [RFC4960]. in [RFC4960].
sac_outbound_streams: sac_outbound_streams:
sac_inbound_streams: The maximum number of streams allowed in each sac_inbound_streams: The maximum number of streams allowed in each
direction are available in sac_outbound_streams and sac_inbound direction are available in sac_outbound_streams and sac_inbound
streams. streams.
sac_assoc_id: The association id field holds the identifier for the sac_assoc_id: The sac_assoc_id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was sac_info: If the sac_state is SCTP_COMM_LOST and an ABORT chunk was
received for this association, sac_info[] contains the complete received for this association, sac_info[] contains the complete
ABORT chunk as defined in the SCTP specification [RFC4960] Section ABORT chunk as defined in the SCTP specification [RFC4960] Section
3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info 3.3.7. If the sac_state is SCTP_COMM_UP or SCTP_RESTART, sac_info
may contain an array of uint8_t describing the features that the may contain an array of uint8_t describing the features that the
current association supports. Features may include current association supports. Features may include
skipping to change at page 46, line 5 skipping to change at page 46, line 5
SCTP_ADDR_ADDED: The address is now part of the association. SCTP_ADDR_ADDED: The address is now part of the association.
SCTP_ADDR_MADE_PRIM: This address has now been made to be the SCTP_ADDR_MADE_PRIM: This address has now been made to be the
primary destination address. This notification is provided primary destination address. This notification is provided
whenever an address is made primary. whenever an address is made primary.
spc_error: If the state was reached due to any error condition (e.g. spc_error: If the state was reached due to any error condition (e.g.
SCTP_ADDR_UNREACHABLE) any relevant error information is available SCTP_ADDR_UNREACHABLE) any relevant error information is available
in this field. in this field.
spc_assoc_id: The association id field holds the identifier for the spc_assoc_id: The spc_assoc_id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
6.1.3. SCTP_REMOTE_ERROR 6.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 an SCTP_REMOTE_ERROR event. Please refer to the SCTP included in an SCTP_REMOTE_ERROR event. Please refer to the SCTP
skipping to change at page 46, line 38 skipping to change at page 46, line 38
sre_type: It should be SCTP_REMOTE_ERROR. sre_type: It should be SCTP_REMOTE_ERROR.
sre_flags: Currently unused. sre_flags: Currently unused.
sre_length: This field is the total length of the notification data, sre_length: This field is the total length of the notification data,
including the notification header and the contents of sre_data. including the notification header and the contents of sre_data.
sre_error: This value represents one of the Operational Error causes sre_error: This value represents one of the Operational Error causes
defined in the SCTP specification, in network byte order. defined in the SCTP specification, in network byte order.
sre_assoc_id: The association id field holds the identifier for the sre_assoc_id: The sre_assoc_id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
sre_data: This contains the ERROR chunk as defined in the SCTP sre_data: This contains the ERROR chunk as defined in the SCTP
specification [RFC4960] Section 3.3.10. specification [RFC4960] Section 3.3.10.
6.1.4. SCTP_SEND_FAILED - DEPRECATED 6.1.4. SCTP_SEND_FAILED - DEPRECATED
Please note that this notification is deprecated. Use Please note that this notification is deprecated. Use
skipping to change at page 47, line 47 skipping to change at page 47, line 47
message or only part of the message is returned in ssf_data. If message or only part of the message is returned in ssf_data. If
only part of the message is returned, it means that the part which only part of the message is returned, it means that the part which
is not present has been sent successfully to the peer. is not present has been sent successfully to the peer.
If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG
flags is set in ssf_info.sinfo_flags. If the first part of the flags is set in ssf_info.sinfo_flags. If the first part of the
message is sent successfully, the SCTP_DATA_LAST_FRAG is set. message is sent successfully, the SCTP_DATA_LAST_FRAG is set.
This means that the tail end of the message is returned in This means that the tail end of the message is returned in
ssf_data. ssf_data.
ssf_assoc_id: The association id field, ssf_assoc_id, holds the ssf_assoc_id: The ssf_assoc_id field, ssf_assoc_id, holds the
identifier for the association. All notifications for a given identifier for the association. All notifications for a given
association have the same association identifier. For a one-to- association have the same association identifier. For a one-to-
one style socket, this field is ignored. one style socket, this field is ignored.
ssf_data: The undelivered message or part of the undelivered message ssf_data: The undelivered message or part of the undelivered message
will be present in the ssf_data field. Note that the will be present in the ssf_data field. Note that the
ssf_info.sinfo_flags field as noted above should be used to ssf_info.sinfo_flags field as noted above should be used to
determine if a complete message is present or just a piece of the determine if a complete message is present or just a piece of the
message. Note that only user data is present in this field, any message. Note that only user data is present in this field, any
chunk headers or SCTP common headers must be removed by the SCTP chunk headers or SCTP common headers must be removed by the SCTP
skipping to change at page 48, line 35 skipping to change at page 48, line 35
sse_type: It should be SCTP_SHUTDOWN_EVENT. sse_type: It should be SCTP_SHUTDOWN_EVENT.
sse_flags: Currently unused. sse_flags: Currently unused.
sse_length: This field is the total length of the notification data, sse_length: This field is the total length of the notification data,
including the notification header. It will generally be including the notification header. It will generally be
sizeof(struct sctp_shutdown_event). sizeof(struct sctp_shutdown_event).
sse_flags: Currently unused. sse_flags: Currently unused.
sse_assoc_id: The association id field holds the identifier for the sse_assoc_id: The sse_assoc_id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
6.1.6. SCTP_ADAPTATION_INDICATION 6.1.6. SCTP_ADAPTATION_INDICATION
When a peer sends an Adaptation Layer Indication parameter as When a peer sends an Adaptation Layer Indication parameter as
described in [RFC5061], SCTP delivers this notification to inform the described in [RFC5061], SCTP delivers this notification to inform the
application about the peer's adaptation layer indication. application about the peer's adaptation layer indication.
skipping to change at page 49, line 15 skipping to change at page 49, line 15
sai_flags: Currently unused. sai_flags: Currently unused.
sai_length: This field is the total length of the notification data, sai_length: This field is the total length of the notification data,
including the notification header. It will generally be including the notification header. It will generally be
sizeof(struct sctp_adaptation_event). sizeof(struct sctp_adaptation_event).
sai_adaptation_ind: This field holds the bit array sent by the peer sai_adaptation_ind: This field holds the bit array sent by the peer
in the adaptation layer indication parameter. in the adaptation layer indication parameter.
sai_assoc_id: The association id field holds the identifier for the sai_assoc_id: The sai_assoc_id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket, this same association identifier. For a one-to-one style socket, this
field is ignored. field is ignored.
6.1.7. SCTP_PARTIAL_DELIVERY_EVENT 6.1.7. SCTP_PARTIAL_DELIVERY_EVENT
When a receiver is engaged in a partial delivery of a message this When a receiver is engaged in a partial delivery of a message this
notification will be used to indicate various events. notification will be used to indicate various events.
struct sctp_pdapi_event { struct sctp_pdapi_event {
skipping to change at page 50, line 11 skipping to change at page 50, line 11
example, if an association is aborted while a partial delivery example, if an association is aborted while a partial delivery
is going on or the user message gets abandoned using PR-SCTP is going on or the user message gets abandoned using PR-SCTP
while the partial delivery of this message is going on. while the partial delivery of this message is going on.
pdapi_stream: This field holds the stream on which the partial pdapi_stream: This field holds the stream on which the partial
delivery event happened. delivery event happened.
pdapi_seq: This field holds the stream sequence number which was pdapi_seq: This field holds the stream sequence number which was
being partially delivered. being partially delivered.
pdapi_assoc_id: The association id field holds the identifier for pdapi_assoc_id: The pdapi_assoc_id field holds the identifier for
the association. All notifications for a given association have the association. All notifications for a given association have
the same association identifier. For a one-to-one style socket the same association identifier. For a one-to-one style socket
this field is ignored. this field is ignored.
6.1.8. SCTP_AUTHENTICATION_EVENT 6.1.8. SCTP_AUTHENTICATION_EVENT
[RFC4895] defines an extension to authenticate SCTP messages. The [RFC4895] defines an extension to authenticate SCTP messages. The
following notification is used to report different events relating to following notification is used to report different events relating to
the use of this extension. the use of this extension.
skipping to change at page 51, line 12 skipping to change at page 51, line 12
the active key. The auth_keynumber field holds the user the active key. The auth_keynumber field holds the user
specified key number. specified key number.
SCTP_AUTH_NO_AUTH: This report indicates that the peer does not SCTP_AUTH_NO_AUTH: This report indicates that the peer does not
support SCTP AUTH as defined in [RFC4895]. support SCTP AUTH as defined in [RFC4895].
SCTP_AUTH_FREE_KEY: This report indicates that the SCTP SCTP_AUTH_FREE_KEY: This report indicates that the SCTP
implementation will no longer use the key identifier specified implementation will no longer use the key identifier specified
in auth_keynumber. in auth_keynumber.
auth_assoc_id: The association id field holds the identifier for the auth_assoc_id: The auth_assoc_id field holds the identifier for the
association. All notifications for a given association have the association. All notifications for a given association have the
same association identifier. For a one-to-one style socket this same association identifier. For a one-to-one style socket this
field is ignored. field is ignored.
6.1.9. SCTP_SENDER_DRY_EVENT 6.1.9. SCTP_SENDER_DRY_EVENT
When the SCTP stack has no more user data to send or retransmit, this When the SCTP stack has no more user data to send or retransmit, this
notification is given to the user. Also, at the time when a user app notification is given to the user. Also, at the time when a user app
subscribes to this event, if there is no data to be sent or subscribes to this event, if there is no data to be sent or
retransmit, the stack will immediately send up this notification. retransmit, the stack will immediately send up this notification.
skipping to change at page 51, line 39 skipping to change at page 51, line 39
}; };
sender_dry_type: It should be SCTP_SENDER_DRY_EVENT. sender_dry_type: It should be SCTP_SENDER_DRY_EVENT.
sender_dry_flags: Currently unused. sender_dry_flags: Currently unused.
sender_dry_length: This field is the total length of the sender_dry_length: This field is the total length of the
notification data, including the notification header. It will notification data, including the notification header. It will
generally be sizeof(struct sctp_sender_dry_event). generally be sizeof(struct sctp_sender_dry_event).
sender_dry_assoc_id: The association id field holds the identifier sender_dry_assoc_id: The sender_dry_assoc_id field holds the
for the association. All notifications for a given association identifier for the association. All notifications for a given
have the same association identifier. For a one-to-one style association have the same association identifier. For a one-to-
socket this field is ignored. one style socket this field is ignored.
6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT 6.1.10. SCTP_NOTIFICATIONS_STOPPED_EVENT
SCTP notifications, when subscribed to, are reliable. They are SCTP notifications, when subscribed to, are reliable. They are
always delivered as long as there is space in the socket receive always delivered as long as there is space in the socket receive
buffer. However, if an implementation experiences a notification buffer. However, if an implementation experiences a notification
storm, it may run out of socket buffer space. When this occurs it storm, it may run out of socket buffer space. When this occurs it
may wish to disable notifications. If the implementation chooses to may wish to disable notifications. If the implementation chooses to
do this, it will append a final notification do this, it will append a final notification
SCTP_NOTIFICATIONS_STOPPED_EVENT. This notification is a union SCTP_NOTIFICATIONS_STOPPED_EVENT. This notification is a union
skipping to change at page 53, line 18 skipping to change at page 53, line 18
message or only part of the message is returned in ssf_data. If message or only part of the message is returned in ssf_data. If
only part of the message is returned, it means that the part which only part of the message is returned, it means that the part which
is not present has been sent successfully to the peer. is not present has been sent successfully to the peer.
If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG If the complete message cannot be sent, the SCTP_DATA_NOT_FRAG
flags is set in ssfe_info.sinfo_flags. If the first part of the flags is set in ssfe_info.sinfo_flags. If the first part of the
message is sent successfully, the SCTP_DATA_LAST_FRAG is set. message is sent successfully, the SCTP_DATA_LAST_FRAG is set.
This means that the tail end of the message is returned in This means that the tail end of the message is returned in
ssf_data. ssf_data.
ssfe_assoc_id: The association id field, ssf_assoc_id, holds the ssfe_assoc_id: The ssfe_assoc_id field, ssf_assoc_id, holds the
identifier for the association. All notifications for a given identifier for the association. All notifications for a given
association have the same association identifier. For a one-to- association have the same association identifier. For a one-to-
one style socket, this field is ignored. one style socket, this field is ignored.
ssfe_data: The undelivered message or part of the undelivered ssfe_data: The undelivered message or part of the undelivered
message will be present in the ssf_data field. Note that the message will be present in the ssf_data field. Note that the
ssf_info.sinfo_flags field as noted above should be used to ssf_info.sinfo_flags field as noted above should be used to
determine if a complete message is present or just a piece of the determine if a complete message is present or just a piece of the
message. Note that only user data is present in this field, any message. Note that only user data is present in this field, any
chunk headers or SCTP common headers must be removed by the SCTP chunk headers or SCTP common headers must be removed by the SCTP
skipping to change at page 54, line 49 skipping to change at page 54, line 49
0 will disable adaptation layer event notifications. 0 will disable adaptation layer event notifications.
sctp_authentication_event: Setting this flag to 1 will enable the sctp_authentication_event: Setting this flag to 1 will enable the
reception of authentication layer notifications. Setting the flag reception of authentication layer notifications. Setting the flag
to 0 will disable authentication layer event notifications. to 0 will disable authentication layer event notifications.
sctp_sender_dry_event: Setting this flag to 1 will enable the sctp_sender_dry_event: Setting this flag to 1 will enable the
reception of sender dry notifications. Setting the flag to 0 will reception of sender dry notifications. Setting the flag to 0 will
disable sender dry event notifications. disable sender dry event notifications.
An example where an application would like to receive data io events An example where an application would like to receive data_io_events
and association events but no others would be as follows: and association_events but no others would be as follows:
{ {
struct sctp_event_subscribe events; struct sctp_event_subscribe events;
memset(&events,0,sizeof(events)); memset(&events,0,sizeof(events));
events.sctp_data_io_event = 1; events.sctp_data_io_event = 1;
events.sctp_association_event = 1; events.sctp_association_event = 1;
setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events)); setsockopt(fd, IPPROTO_SCTP, SCTP_EVENTS, &events, sizeof(events));
skipping to change at page 55, line 43 skipping to change at page 55, line 43
is used with the following structure: is used with the following structure:
struct sctp_event { struct sctp_event {
sctp_assoc_t se_assoc_id; sctp_assoc_t se_assoc_id;
uint16_t se_type; uint16_t se_type;
uint8_t se_on; uint8_t se_on;
}; };
se_assoc_id: The se_assoc_id field is ignored for one-to-one style se_assoc_id: The se_assoc_id field is ignored for one-to-one style
sockets. For one-to-many style sockets this field can be a sockets. For one-to-many style sockets this field can be a
particular association id or SCTP_{FUTURE|CURRENT|ALL}_ASSOC. particular association identifier or SCTP_{FUTURE|CURRENT|
ALL}_ASSOC.
se_type: The se_type field can be filled with any value that would se_type: The se_type field can be filled with any value that would
show up in the respective sn_type field (in the sctp_tlv structure show up in the respective sn_type field (in the sctp_tlv structure
of the notification). of the notification).
se_on: The se_on field is set to 1 to turn on an event and set to 0 se_on: The se_on field is set to 1 to turn on an event and set to 0
to turn off an event. to turn off an event.
To use this option the user fills in this structure and then calls To use this option the user fills in this structure and then calls
the setsockopt to turn on or off an individual event. The following the setsockopt to turn on or off an individual event. The following
skipping to change at page 57, line 18 skipping to change at page 57, line 23
int flags, int flags,
struct sockaddr *from, struct sockaddr *from,
socklen_t *fromlen); socklen_t *fromlen);
and the arguments are and the arguments are
sd: The socket descriptor of an SCTP endpoint. sd: The socket descriptor of an SCTP endpoint.
msg: The message to be sent. msg: The message to be sent.
len: the size of the message or the size of the buffer. len: The size of the message or the size of the buffer.
to: one of the peer addresses of the association to be used to send to: One of the peer addresses of the association to be used to send
the message. the message.
tolen: The size of the address. tolen: The size of the address.
buf: The buffer to store a received message. buf: The buffer to store a received message.
from: The buffer to store the peer address used to send the received from: The buffer to store the peer address used to send the received
message. message.
fromlen: The size of the from address. fromlen: The size of the from address.
skipping to change at page 59, line 19 skipping to change at page 59, line 20
optval: The buffer to store the value of the option. optval: The buffer to store the value of the option.
optlen: The size of the buffer (or the length of the option optlen: The size of the buffer (or the length of the option
returned). returned).
They return 0 on success and -1 in case of an error. They return 0 on success and -1 in case of an error.
All socket options set on a one-to-one style listening socket also All socket options set on a one-to-one style listening socket also
apply to all future accepted sockets. For one-to-many style sockets apply to all future accepted sockets. For one-to-many style sockets
often a socket option will pass a structure that includes an assoc_id often a socket option will pass a structure that includes an assoc_id
field. This field can be filled with the association id of a field. This field can be filled with the association identifier of a
particular association and unless otherwise specified can be filled particular association and unless otherwise specified can be filled
with one of the following constants: with one of the following constants:
SCTP_FUTURE_ASSOC: Specifies that only future associations created SCTP_FUTURE_ASSOC: Specifies that only future associations created
after this socket option will be affected by this call. after this socket option will be affected by this call.
SCTP_CURRENT_ASSOC: Specifies that only currently existing SCTP_CURRENT_ASSOC: Specifies that only currently existing
associations will be affected by this call, future associations associations will be affected by this call, future associations
will still receive the previous default value. will still receive the previous default value.
skipping to change at page 60, line 42 skipping to change at page 60, line 43
Whenever sendmsg() or sendto() is called and the SCTP stack at the Whenever sendmsg() or sendto() is called and the SCTP stack at the
sender finds that no association exists between the sender and the sender finds that no association exists between the sender and the
intended receiver (identified by the address passed either in the intended receiver (identified by the address passed either in the
msg_name field of msghdr structure in the sendmsg() call or the msg_name field of msghdr structure in the sendmsg() call or the
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 an SCTP_COMM_UP notification Upon the successful association setup an 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.4).
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
[RFC4960]. [RFC4960].
When the SCTP stack sets up a new association implicitly, the When the SCTP stack sets up a new association implicitly, the
SCTP_INIT type ancillary data may also be passed along (see SCTP_INIT type ancillary data may also be passed along (see
Section 5.3.1 for details of the data structures) to change some Section 5.3.1 for details of the data structures) to change some
parameters used in setting up a new association. parameters used in setting up a new association.
skipping to change at page 61, line 21 skipping to change at page 61, line 22
Implicit association setup cannot be initiated by send() calls. Implicit association setup cannot be initiated by send() calls.
8. Socket Options 8. Socket Options
The following sub-section describes various SCTP level socket options The following sub-section describes various SCTP level socket options
that are common to both styles. SCTP associations can be multi- that are common to both styles. SCTP associations can be multi-
homed. Therefore, certain option parameters include a homed. Therefore, certain option parameters include a
sockaddr_storage structure to select which peer address the option sockaddr_storage structure to select which peer address the option
should be applied to. should be applied to.
For the one-to-many style sockets, an sctp_assoc_t (association ID) For the one-to-many style sockets, an sctp_assoc_t (association
parameter is used to identify the association instance that the identifier) parameter is used to identify the association instance
operation affects. So it must be set when using this style. that 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 9.2) this association ID parameter is ignored. sockets (see Section 9.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, the options will be This means that for one-to-many style sockets, the options will be
applied to all associations (similar to using SCTP_ALL_ASSOC as the applied to all associations (similar to using SCTP_ALL_ASSOC as the
association ID) belonging to the socket. For one-to-one style, these association identifier) belonging to the socket. For one-to-one
options will be applied to all peer addresses of the association style, these options will be applied to all peer addresses of the
controlled by the socket. Applications should be careful in setting association controlled by the socket. Applications should be careful
those options. in setting those options.
For some IP stacks getsockopt() is read-only; so a new interface will For some IP stacks getsockopt() is read-only; so a new interface will
be needed when information must be passed both into and out of the be needed when information must be passed both into and out of the
SCTP stack. The syntax for sctp_opt_info() is SCTP stack. The syntax for sctp_opt_info() is
int sctp_opt_info(int sd, int sctp_opt_info(int sd,
sctp_assoc_t id, sctp_assoc_t id,
int opt, int opt,
void *arg, void *arg,
socklen_t *size); socklen_t *size);
skipping to change at page 63, line 22 skipping to change at page 63, line 27
uint32_t srto_min; uint32_t srto_min;
}; };
srto_initial: This contains the initial RTO value. srto_initial: This contains the initial RTO value.
srto_max and srto_min: These contain the maximum and minimum bounds srto_max and srto_min: These contain the maximum and minimum bounds
for all RTOs. for all RTOs.
srto_assoc_id: This parameter is ignored for one-to-one style srto_assoc_id: This parameter is ignored for one-to-one style
sockets. For one-to-many style sockets the application may fill sockets. For one-to-many style sockets the application may fill
in an association identification or SCTP_FUTURE_ASSOC. It is an in an association identifier or SCTP_FUTURE_ASSOC. It is an error
error to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id. to use SCTP_{CURRENT|ALL}_ASSOC in srto_assoc_id.
All times are given in milliseconds. A value of 0, when modifying All times are given in milliseconds. A value of 0, when modifying
the parameters, indicates that the current value should not be the parameters, indicates that the current value should not be
changed. changed.
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.
8.1.2. Association Parameters (SCTP_ASSOCINFO) 8.1.2. Association Parameters (SCTP_ASSOCINFO)
skipping to change at page 64, line 4 skipping to change at page 64, line 13
parameters: 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;
}; };
sasoc_assoc_id: This parameter is ignored for one-to-one style sasoc_assoc_id: This parameter is ignored for one-to-one style
sockets. For one-to-many style sockets the application may fill sockets. For one-to-many style sockets the application may fill
in an association identification or SCTP_FUTURE_ASSOC. It is an in an association identifier or SCTP_FUTURE_ASSOC. It is an error
error to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id. to use SCTP_{CURRENT|ALL}_ASSOC in sasoc_assoc_id.
sasoc_asocmaxrxt: This contains the maximum retransmission attempts sasoc_asocmaxrxt: This contains the maximum retransmission attempts
to make for the association. to make for the association.
sasoc_number_peer_destinations: This is the number of destination sasoc_number_peer_destinations: This is the number of destination
addresses that the peer has. addresses that the peer has.
sasoc_peer_rwnd: This holds the current value of the peers rwnd sasoc_peer_rwnd: This holds the current value of the peers rwnd
(reported in the last SACK) minus any outstanding data (i.e. data (reported in the last SACK) minus any outstanding data (i.e. data
in flight). in flight).
skipping to change at page 65, line 6 skipping to change at page 65, line 16
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()
may return an error. The reason for this, from [RFC4960] Section may return an error. The reason for this, from [RFC4960] 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' (sasoc_maxrxt in this having the value of 'Association.Max.Retrans' (sasoc_maxrxt in this
option) larger than the summation of the 'Path.Max.Retrans' (see option) larger than the summation of the 'Path.Max.Retrans' (see
Section 8.1.2 on spp_pathmaxrxt) of all the destination addresses for Section 8.1.12 on spp_pathmaxrxt) of all the destination addresses
the remote endpoint. Otherwise, all the destination addresses may for the remote endpoint. Otherwise, all the destination addresses
become inactive while the endpoint still considers the peer endpoint may become inactive while the endpoint still considers the peer
reachable. endpoint reachable.
8.1.3. Initialization Parameters (SCTP_INITMSG) 8.1.3. Initialization Parameters (SCTP_INITMSG)
Applications can specify protocol parameters for the default Applications can specify protocol parameters for the default
association initialization. The structure used to access and modify association initialization. The structure used to access and modify
these parameters is defined in Section 5.3.1. The option name these parameters is defined in Section 5.3.1. The option name
argument to setsockopt() and getsockopt() is SCTP_INITMSG. argument to setsockopt() and getsockopt() is SCTP_INITMSG.
Setting initialization parameters is effective only on an unconnected Setting initialization parameters is effective only on an unconnected
socket (for one-to-many style sockets only future associations are socket (for one-to-many style sockets only future associations are
skipping to change at page 65, line 40 skipping to change at page 65, line 50
struct linger { struct linger {
int l_onoff; /* option on/off */ int l_onoff; /* option on/off */
int l_linger; /* linger time */ int l_linger; /* linger time */
}; };
To enable the option, set l_onoff to 1. If the l_linger value is set To enable the option, set l_onoff to 1. If the l_linger value is set
to 0, calling close() is the same as the ABORT primitive. If the to 0, calling close() is the same as the ABORT primitive. If the
value is set to a negative value, the setsockopt() call will return value is set to a negative value, the setsockopt() call will return
an error. If the value is set to a positive value linger_time, the an error. If the value is set to a positive value linger_time, the
close() can be blocked for at most linger_time. Please note that the close() can be blocked for at most linger_time. Please note that the
time unit is ms according to Posix, but might be different on time unit is ms according to POSIX, but might be different on
specific platforms. If the graceful shutdown phase does not finish specific platforms. If the graceful shutdown phase does not finish
during this period, close() will return but the graceful shutdown during this period, close() will return but the graceful shutdown
phase will continue in the system. phase will continue in the system.
Note, this is a socket level option, not an SCTP level option. When Note, this is a socket level option, not an SCTP level option. When
using this option, an application must specify a level of SOL_SOCKET using this option, an application must specify a level of SOL_SOCKET
in the call. in the call.
8.1.5. SCTP_NODELAY 8.1.5. SCTP_NODELAY
skipping to change at page 67, line 10 skipping to change at page 67, line 20
graceful shutdown procedure. An association being idle is defined as graceful shutdown procedure. An association being idle is defined as
an association that has not sent or received user data. The special an association that has not sent or received user data. The special
value of '0' indicates that no automatic close of any association value of '0' indicates that no automatic close of any association
should be performed, this is the default value. This option expects should be performed, this is the default value. This option expects
an integer defining the number of seconds of idle time before an an integer defining the number of seconds of idle time before an
association is closed. association is closed.
An application using this option should enable receiving the An application using this option should enable receiving the
association change notification. This is the only mechanism an association change notification. This is the only mechanism an
application is informed about the closing of an association. After application is informed about the closing of an association. After
an association is closed, the association ID assigned to it can be an association is closed, the association identifier assigned to it
reused. An application should be aware of this to avoid the possible can be reused. An application should be aware of this to avoid the
problem of sending data to an incorrect peer endpoint. possible problem of sending data to an incorrect peer endpoint.
8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR) 8.1.9. Set Primary Address (SCTP_PRIMARY_ADDR)
Requests that the local SCTP stack uses the enclosed peer address as Requests that the local SCTP stack uses the enclosed peer address as
the association's primary. The enclosed address must be one of the the association's primary. The enclosed address must be one of the
association peer's addresses. association peer's addresses.
The following structure is used to make a set peer primary request: The following structure is used to make a set peer primary request:
struct sctp_setprim { struct sctp_setprim {
skipping to change at page 74, line 48 skipping to change at page 75, line 20
the partially delivered message. the partially delivered message.
level 1: Allows interleaving of messages that are from different level 1: Allows interleaving of messages that are from different
associations. For the one-to-one model, level 0 and level 1 thus associations. For the one-to-one model, level 0 and level 1 thus
have the same meaning since a one-to-one socket always receives have the same meaning since a one-to-one socket always receives
messages from the same association. Note that setting the one-to- messages from the same association. Note that setting the one-to-
many model to this level may cause multiple partial deliveries many model to this level may cause multiple partial deliveries
from different associations but for any given association, only from different associations but for any given association, only
one message will be delivered until all parts of a message have one message will be delivered until all parts of a message have
been delivered. This means that one large message, being read been delivered. This means that one large message, being read
with an association identification of "X", will block other with an association identifier of "X", will block other messages
messages from association "X" from being delivered. from association "X" from being delivered.
level 2: Allows complete interleaving of messages. This level level 2: Allows complete interleaving of messages. This level
requires that the sender carefully observes not only the peer requires that the sender carefully observes not only the peer
association identification (or address) but must also pay careful association identifier (or address) but must also pay careful
attention to the stream number. With this option enabled a attention to the stream number. With this option enabled a
partially delivered message may begin being delivered for partially delivered message may begin being delivered for
association "X" stream "Y" and the next subsequent receive may association "X" stream "Y" and the next subsequent receive may
return a message from association "X" stream "Z". Note that no return a message from association "X" stream "Z". Note that no
other messages would be delivered for association "X" stream "Y" other messages would be delivered for association "X" stream "Y"
until all of stream "Y"'s partially delivered message was read. until all of stream "Y"'s partially delivered message was read.
Note that this option also affects the one-to-one model. Also Note that this option also affects the one-to-one model. Also
note that for the one-to-many model not only another stream's note that for the one-to-many model not only another stream's
message from the same association may be delivered upon the next message from the same association may be delivered upon the next
receive, some other association's message may be delivered upon receive, some other association's message may be delivered upon
the next receive. the next receive.
An implementation should default the one-to-many model to level 1. An implementation should default the one-to-many model to level 1.
The reason for this is that otherwise it is possible that a peer The reason for this is that otherwise it is possible that a peer
could begin sending a partial message and thus block all other peers could begin sending a partial message and thus block all other peers
from sending data. However a setting of level 2 requires the from sending data. However a setting of level 2 requires the
application to not only be aware of the association (via the application to not only be aware of the association (via the
association id or peer's address) but also the stream number. The association identifier or peer's address) but also the stream number.
stream number is not present unless the user has subscribed to the The stream number is not present unless the user has subscribed to
sctp_data_io_events (see Section 6.2). This is also why we recommend the sctp_data_io_event (see Section 6.2). This is also why we
that the one-to-one model be defaulted to level 0 (level 1 for the recommend that the one-to-one model be defaulted to level 0 (level 1
one-to-one model has no effect). Note that an implementation should for the one-to-one model has no effect). Note that an implementation
return an error if an application attempts to set the level to 2 and should return an error if an application attempts to set the level to
has not subscribed to the sctp_data_io_events. 2 and has not subscribed to the sctp_data_io_event.
For applications that have subscribed to events, those events appear For applications that have subscribed to events, those events appear
in the normal socket buffer data stream. This means that unless the in the normal socket buffer data stream. This means that unless the
user has set the fragmentation interleave level to 0, notifications user has set the fragmentation interleave level to 0, notifications
may also be interleaved with partially delivered messages. may also be interleaved with partially delivered messages.
8.1.21. Set or Get the SCTP Partial Delivery Point 8.1.21. Set or Get the SCTP Partial Delivery Point
(SCTP_PARTIAL_DELIVERY_POINT) (SCTP_PARTIAL_DELIVERY_POINT)
This option will set or get the SCTP partial delivery point. This This option will set or get the SCTP partial delivery point. This
skipping to change at page 81, line 32 skipping to change at page 81, line 49
}; };
spinfo_assoc_id: This parameter is ignored for one-to-one style spinfo_assoc_id: This parameter is ignored for one-to-one style
sockets. For one-to-many style sockets the following applies: sockets. For one-to-many style sockets the following applies:
This field may be filled by the application, if so, this field This field may be filled by the application, if so, this field
will have priority in looking up the association instead of using will have priority in looking up the association instead of using
the address specified in spinfo_address. Note that if the address the address specified in spinfo_address. Note that if the address
does not belong to the association specified then this call will does not belong to the association specified then this call will
fail. If the application does not fill in the spinfo_assoc_id, fail. If the application does not fill in the spinfo_assoc_id,
then the address will be used to lookup the association and on then the address will be used to lookup the association and on
return this field will have the valid association id. In other return this field will have the valid association identifier. In
words, this call can be used to translate an address into an other words, this call can be used to translate an address into an
association id. Note that the predefined constants are not association identifier. Note that the predefined constants are
allowed on this option. not allowed on this option.
spinfo_address: This is filled by the application, and contains the spinfo_address: This is filled by the application, and contains the
peer address of interest. peer address of interest.
spinfo_state: This contains the peer address' state: spinfo_state: This contains the peer address' state:
SCTP_UNCONFIRMED: The initial state of a peer address. SCTP_UNCONFIRMED: The initial state of a peer address.
SCTP_ACTIVE: The state is entered the first time after path SCTP_ACTIVE: The state is entered the first time after path
verification. It can also be entered if the state is verification. It can also be entered if the state is
skipping to change at page 84, line 28 skipping to change at page 84, line 48
primary (see [RFC5061]). The enclosed address must be one of the primary (see [RFC5061]). The enclosed address must be one of the
association's locally bound addresses. association's locally bound addresses.
The following structure is used to make a set peer primary request: The following structure is used to make a set peer primary request:
struct sctp_setpeerprim { struct sctp_setpeerprim {
sctp_assoc_t sspp_assoc_id; sctp_assoc_t sspp_assoc_id;
struct sockaddr_storage sspp_addr; struct sockaddr_storage sspp_addr;
}; };
sspp_addr: The address to set as primary.
sspp_assoc_id: This parameter is ignored for one-to-one style sspp_assoc_id: This parameter is ignored for one-to-one style
sockets. For one-to-many style sockets it identifies the sockets. For one-to-many style sockets it identifies the
association for this request. Note that the predefined constants association for this request. Note that the predefined constants
are not allowed on this option. are not allowed on this option.
8.3.2. Add a Chunk That Must Be Authenticated (SCTP_AUTH_CHUNK) sspp_addr: The address to set as primary.
8.3.2. Add a Chunk that must be Authenticated (SCTP_AUTH_CHUNK)
This set option adds a chunk type that the user is requesting to be This set option adds a chunk type that the user is requesting to be
received only in an authenticated way. Changes to the list of chunks received only in an authenticated way. Changes to the list of chunks
will only affect future associations on the socket. will only affect future associations on the socket.
The following structure is used to add a chunk: The following structure is used to add a chunk:
struct sctp_authchunk { struct sctp_authchunk {
uint8_t sauth_chunk; uint8_t sauth_chunk;
}; };
skipping to change at page 91, line 4 skipping to change at page 91, line 26
On success, sctp_getladdrs() returns the number of local addresses On success, sctp_getladdrs() returns the number of local addresses
bound to the socket. If the socket is unbound, sctp_getladdrs() bound to the socket. If the socket is unbound, sctp_getladdrs()
returns 0, and the value of *addrs is undefined. If an error occurs, returns 0, and the value of *addrs is undefined. If an error occurs,
sctp_getladdrs() returns -1, and the value of *addrs is undefined. sctp_getladdrs() returns -1, and the value of *addrs is undefined.
9.6. sctp_freeladdrs() 9.6. sctp_freeladdrs()
sctp_freeladdrs() frees all resources allocated by sctp_getladdrs(). sctp_freeladdrs() frees all resources allocated by sctp_getladdrs().
The function prototype is The function prototype is
void sctp_freeladdrs(struct sockaddr *addrs); void sctp_freeladdrs(struct sockaddr *addrs);
and addrs is the array of local addresses returned by and addrs is the array of local addresses returned by
sctp_getladdrs(). sctp_getladdrs().
9.7. sctp_sendmsg() - DEPRECATED 9.7. sctp_sendmsg() - DEPRECATED
This function is deprecated, sctp_sendv() (see Section 9.13) should This function is deprecated, sctp_sendv() (see Section 9.12) should
be used instead. be used instead.
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. call) to assist the user with the advanced features of SCTP.
The function prototype is The function prototype 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,
skipping to change at page 92, line 19 skipping to change at page 92, line 39
Sending a message using sctp_sendmsg() is atomic (unless explicit EOR Sending a message using sctp_sendmsg() is atomic (unless explicit EOR
marking is enabled on the socket specified by sd). marking is enabled on the socket specified by sd).
Using sctp_sendmsg() on a non-connected one-to-one style socket for Using sctp_sendmsg() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP implicit connection setup may or may not work depending on the SCTP
implementation. implementation.
9.8. sctp_recvmsg() - DEPRECATED 9.8. sctp_recvmsg() - DEPRECATED
This function is deprecated, sctp_recvv() (see Section 9.12) should This function is deprecated, sctp_recvv() (see Section 9.13) should
be used instead. be used instead.
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_event with the
the SCTP_EVENTS option. Note that the setting of the SCTP_EVENTS option. Note that the setting of the
SCTP_USE_EXT_RCVINFO will affect this function as well, causing the SCTP_USE_EXT_RCVINFO will affect this function as well, causing the
sctp_sndrcvinfo information to be extended. sctp_sndrcvinfo information to be extended.
The function prototype is The function prototype is
ssize_t sctp_recvmsg(int sd, ssize_t sctp_recvmsg(int sd,
void *msg, void *msg,
size_t len, size_t len,
struct sockaddr *from, struct sockaddr *from,
socklen_t *fromlen socklen_t *fromlen
struct sctp_sndrcvinfo *sinfo struct sctp_sndrcvinfo *sinfo
int *msg_flags); int *msg_flags);
and the arguments are and the arguments are
skipping to change at page 94, line 8 skipping to change at page 94, line 24
and the arguments are: and the arguments are:
sd: The socket descriptor. sd: The socket descriptor.
addrs: An array of addresses. addrs: An array of addresses.
addrcnt: The number of addresses in the array. addrcnt: The number of addresses in the array.
id: An output parameter that if passed in as a non-NULL will return id: An output parameter that if passed in as a non-NULL will return
the association identification for the newly created association the association identifier for the newly created association (if
(if successful). successful).
The call returns 0 on success or -1 if an error occurred. The The call returns 0 on success or -1 if an error occurred. The
variable errno is then set appropriately. variable errno is then set appropriately.
9.10. sctp_send() - DEPRECATED 9.10. sctp_send() - DEPRECATED
This function is deprecated, sctp_sendv() should be used instead. This function is deprecated, sctp_sendv() should be used instead.
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
skipping to change at page 94, line 48 skipping to change at page 95, line 19
sinfo: A pointer to an sctp_sndrcvinfo structure used as described sinfo: A pointer to an sctp_sndrcvinfo structure used as described
in Section 5.3.2 for a sendmsg() call. in Section 5.3.2 for a sendmsg() call.
flags: The same flags as used by the sendmsg() call flags (e.g. flags: The same flags as used by the sendmsg() call flags (e.g.
MSG_DONTROUTE). MSG_DONTROUTE).
The call returns the number of bytes sent, or -1 if an error The call returns the number of bytes sent, or -1 if an error
occurred. The variable errno is then set appropriately. occurred. The variable errno is then set appropriately.
This function call may also be used to terminate an association using This function call may also be used to terminate an association using
an association identification by setting the sinfo.sinfo_flags to an association identifier 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 can be zero. to be terminated. In such a case the len of the message can be zero.
Using sctp_send() on a non-connected one-to-one style socket for Using sctp_send() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP implicit connection setup may or may not work depending on the SCTP
implementation. implementation.
Sending a message using sctp_send() is atomic unless explicit EOR Sending a message using sctp_send() is atomic unless explicit EOR
marking is enabled on the socket specified by sd. marking is enabled on the socket specified by sd.
skipping to change at page 95, line 40 skipping to change at page 96, line 11
int flags); int flags);
and the arguments are: and the arguments are:
sd: The socket descriptor. sd: The socket descriptor.
msg: The message to be sent. msg: The message to be sent.
len: The length of the message. len: The length of the message.
addrs: is an array of addresses. addrs: Is an array of addresses.
addrcnt: The number of addresses in the array. addrcnt: The number of addresses in the array.
sinfo: A pointer to an sctp_sndrcvinfo structure used as described sinfo: A pointer to an sctp_sndrcvinfo structure used as described
in Section 5.3.2 for a sendmsg() call. in Section 5.3.2 for a sendmsg() call.
flags: The same flags as used by the sendmsg() call flags (e.g. flags: The same flags as used by the sendmsg() call flags (e.g.
MSG_DONTROUTE). MSG_DONTROUTE).
The call returns the number of bytes sent, or -1 if an error The call returns the number of bytes sent, or -1 if an error
occurred. The variable errno is then set appropriately. occurred. The variable errno is then set appropriately.
Note that in case of implicit connection setup, on return from this Note that in case of implicit connection setup, on return from this
call the sinfo_assoc_id field of the sinfo structure will contain the call the sinfo_assoc_id field of the sinfo structure will contain the
new association id. new association identifier.
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 identifier 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.
Sending a message using sctp_sendx() is atomic unless explicit EOR Sending a message using sctp_sendx() is atomic unless explicit EOR
marking is enabled on the socket specified by sd. marking is enabled on the socket specified by sd.
Using sctp_sendx() on a non-connected one-to-one style socket for Using sctp_sendx() on a non-connected one-to-one style socket for
implicit connection setup may or may not work depending on the SCTP implicit connection setup may or may not work depending on the SCTP
implementation. implementation.
9.12. sctp_recvv() 9.12. sctp_sendv()
The function prototype is
ssize_t sctp_recvv(int sd,
const struct iovec *iov,
int iovlen,
struct sockaddr *from,
socklen_t *fromlen,
void *info,
socklen_t *infolen,
unsigned int *infotype,
int *flags);
The function sctp_recvv() provides an extensible way for the SCTP
stack to pass up different SCTP attributes associated with a received
message to an application. An implementation may provide
sctp_recvv() as a library function or as a system call.
This document defines two types of attributes which can be returned
by this call, the attribute of the received message and the attribute
of the next message in receive buffer. The caller enables the
SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these
attributes respectively. Attributes of the received message are
returned in struct sctp_rcvinfo (Section 5.3.5) and attributes of the
next message are returned in struct sctp_nxtinfo (Section 5.3.6). If
both options are enabled, both attributes are returned using the
following structure.
struct sctp_recvv_rn {
struct sctp_rcvinfo recvv_rcvinfo;
struct sctp_nxtinfo recvv_nxtinfo;
};
In future, new structures can be defined to hold new types of
attributes. The new structures do not need to be based on struct
sctp_recvv_rn or struct sctp_rcvinfo.
This function takes the following arguments:
sd: The socket descriptor.
iov: The scatter buffer. Only one user message is returned in this
buffer.
iovlen: The number of elements in iov.
from: A pointer to an address to be filled with the sender of the
received message's address.
fromlen: An in/out parameter describing the from length.
info: A pointer to the buffer to hold the attributes of the received
message. The structure type of info is determined by the
info_type parameter.
infolen: An in/out parameter describing the size of the info buffer.
infotype: In return, *info_type is set to the type of the info
buffer. The current defined values are:
SCTP_RECVV_NOINFO: If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO
options are not enabled, no attribute will be returned. If
only the SCTP_RECVNXTINFO option is enabled but there is no
next message in the buffer, there will also no attribute be
returned. In these cases *info_type will be set to
SCTP_RECVV_NOINFO.
SCTP_RECVV_RCVINFO: The type of info is struct sctp_rcvinfo and
the attribute is about the received message.
SCTP_RECVV_NXTINFO: The type of info is struct sctp_nxtinfo and
the attribute is about the next message in receive buffer.
This is the case when only the SCTP_RECVNXTINFO option is
enabled and there is a next message in buffer.
SCTP_RECVV_RN: The type of info is struct sctp_recvv_rn. The
recvv_rcvinfo field is the attribute of the received message
and the recvv_nxtinfo field is the attribute of the next
message in buffer. This is the case when both SCTP_RECVRCVINFO
and SCTP_RECVNXTINFO options are enabled and there is a next
message in the receive buffer.
flags: A pointer to an integer to be filled with any message flags
(e.g. MSG_NOTIFICATION). Note that this field is an in/out
parameter. Options for the receive may also be passed into the
value (e.g. MSG_PEEK). On return from the call, the flags value
will be different than what was sent in to the call. If
implemented via a recvmsg() call, the flags should only contain
the value of the flags from the recvmsg() call when calling
sctp_recvv() and on return it has the value from msg_flags.
The call returns the number of bytes received, or -1 if an error
occurred. The variable errno is then set appropriately.
9.13. sctp_sendv()
The function prototype is The function prototype is
ssize_t sctp_sendv(int sd, ssize_t sctp_sendv(int sd,
const struct iovec *iov, const struct iovec *iov,
int iovcnt, int iovcnt,
struct sockaddr *addrs, struct sockaddr *addrs,
int addrcnt, int addrcnt,
void *info, void *info,
socklen_t infolen, socklen_t infolen,
skipping to change at page 100, line 26 skipping to change at page 98, line 39
attribute must always be used in order to specify the association the attribute must always be used in order to specify the association the
message is to be sent on. The only case where it is not needed is message is to be sent on. The only case where it is not needed is
when this call is used to set up a new association. when this call is used to set up a new association.
The caller provides a list of addresses in the addrs parameter to set The caller provides a list of addresses in the addrs parameter to set
up an association. This function will behave like calling up an association. This function will behave like calling
sctp_connectx() (see Section 9.9) first using the list of addresses sctp_connectx() (see Section 9.9) first using the list of addresses
and then calling sendmsg() with the given message and attributes. and then calling sendmsg() with the given message and attributes.
For an one-to-many style socket, if struct sctp_sndinfo attribute is For an one-to-many style socket, if struct sctp_sndinfo attribute is
provided, the snd_assoc_id field must be 0. When this function provided, the snd_assoc_id field must be 0. When this function
returns, the snd_assoc_id field will contain the association ID of returns, the snd_assoc_id field will contain the association
the newly established association. Note that struct sctp_sndinfo identifier of the newly established association. Note that struct
attribute is not required to set up an association for one-to-many sctp_sndinfo attribute is not required to set up an association for
style socket. If this attribute is not provided, the caller can one-to-many style socket. If this attribute is not provided, the
enable the SCTP_ASSOC_CHANGE notification and use the SCTP_COMM_UP caller can enable the SCTP_ASSOC_CHANGE notification and use the
message to find out the association ID. SCTP_COMM_UP message to find out the association identifier.
If the caller wants to send the message to a specific peer address If the caller wants to send the message to a specific peer address
(hence overriding the primary address), it can provide the specific (hence overriding the primary address), it can provide the specific
address in the addrs parameter and provide a struct sctp_sndinfo address in the addrs parameter and provide a struct sctp_sndinfo
attribute with the field snd_flags set to SCTP_ADDR_OVER. attribute with the field snd_flags set to SCTP_ADDR_OVER.
This function call may also be used to terminate an association. The This function call may also be used to terminate an association. The
caller provides an sctp_sndinfo attribute with the snd_flags set to caller provides an sctp_sndinfo attribute with the snd_flags set to
SCTP_EOF. In this case the len of the message would be zero. SCTP_EOF. In this case the len of the message would be zero.
Sending a message using sctp_sendv() is atomic unless explicit EOR Sending a message using sctp_sendv() is atomic unless explicit EOR
marking is enabled on the socket specified by sd. marking is enabled on the socket specified by sd.
9.13. sctp_recvv()
The function prototype is
ssize_t sctp_recvv(int sd,
const struct iovec *iov,
int iovlen,
struct sockaddr *from,
socklen_t *fromlen,
void *info,
socklen_t *infolen,
unsigned int *infotype,
int *flags);
The function sctp_recvv() provides an extensible way for the SCTP
stack to pass up different SCTP attributes associated with a received
message to an application. An implementation may provide
sctp_recvv() as a library function or as a system call.
This document defines two types of attributes which can be returned
by this call, the attribute of the received message and the attribute
of the next message in receive buffer. The caller enables the
SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these
attributes respectively. Attributes of the received message are
returned in struct sctp_rcvinfo (Section 5.3.5) and attributes of the
next message are returned in struct sctp_nxtinfo (Section 5.3.6). If
both options are enabled, both attributes are returned using the
following structure.
struct sctp_recvv_rn {
struct sctp_rcvinfo recvv_rcvinfo;
struct sctp_nxtinfo recvv_nxtinfo;
};
In future, new structures can be defined to hold new types of
attributes. The new structures do not need to be based on struct
sctp_recvv_rn or struct sctp_rcvinfo.
This function takes the following arguments:
sd: The socket descriptor.
iov: The scatter buffer. Only one user message is returned in this
buffer.
iovlen: The number of elements in iov.
from: A pointer to an address to be filled with the sender of the
received message's address.
fromlen: An in/out parameter describing the from length.
info: A pointer to the buffer to hold the attributes of the received
message. The structure type of info is determined by the
info_type parameter.
infolen: An in/out parameter describing the size of the info buffer.
infotype: In return, *info_type is set to the type of the info
buffer. The current defined values are:
SCTP_RECVV_NOINFO: If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO
options are not enabled, no attribute will be returned. If
only the SCTP_RECVNXTINFO option is enabled but there is no
next message in the buffer, there will also no attribute be
returned. In these cases *info_type will be set to
SCTP_RECVV_NOINFO.
SCTP_RECVV_RCVINFO: The type of info is struct sctp_rcvinfo and
the attribute is about the received message.
SCTP_RECVV_NXTINFO: The type of info is struct sctp_nxtinfo and
the attribute is about the next message in receive buffer.
This is the case when only the SCTP_RECVNXTINFO option is
enabled and there is a next message in buffer.
SCTP_RECVV_RN: The type of info is struct sctp_recvv_rn. The
recvv_rcvinfo field is the attribute of the received message
and the recvv_nxtinfo field is the attribute of the next
message in buffer. This is the case when both SCTP_RECVRCVINFO
and SCTP_RECVNXTINFO options are enabled and there is a next
message in the receive buffer.
flags: A pointer to an integer to be filled with any message flags
(e.g. MSG_NOTIFICATION). Note that this field is an in/out
parameter. Options for the receive may also be passed into the
value (e.g. MSG_PEEK). On return from the call, the flags value
will be different than what was sent in to the call. If
implemented via a recvmsg() call, the flags should only contain
the value of the flags from the recvmsg() call when calling
sctp_recvv() and on return it has the value from msg_flags.
The call returns the number of bytes received, or -1 if an error
occurred. The variable errno is then set appropriately.
10. IANA Considerations 10. IANA Considerations
This document requires no actions from IANA. This document requires no actions from IANA.
11. Security Considerations 11. 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.
skipping to change at page 101, line 34 skipping to change at page 101, line 44
Applications using the one-to-many style sockets and using the Applications using the one-to-many style sockets and using the
interleave level if 0 are subject to denial of service attacks as interleave level if 0 are subject to denial of service attacks as
described in Section 8.1.20. described in Section 8.1.20.
12. Acknowledgments 12. Acknowledgments
Special acknowledgment is given to Ken Fujita, Jonathan Woods, Special acknowledgment is given to Ken Fujita, Jonathan Woods,
Qiaobing Xie, and La Monte Yarroll, who helped extensively in the Qiaobing Xie, and La Monte Yarroll, who helped extensively in the
early formation of this document. 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,
Berger, Mark Butler, Scott Kimble, Renee Revis, Andreas Fink, Martin Becke, Jon Berger, Mark Butler, Thomas Dreibholz, Scott
Jonathan Leighton, Irene Ruengeler, and many others on the TSVWG Kimble, Renee Revis, Andreas Fink, Jonathan Leighton, Irene
mailing list for contributing valuable comments. Ruengeler, and many others on the TSVWG mailing list for contributing
valuable comments.
A special thanks to Phillip Conrad, for his suggested text, quick and A special thanks to Phillip Conrad, for his suggested text, quick and
constructive insights, and most of all his persistent fighting to constructive insights, and most of all his persistent fighting to
keep the interface to SCTP usable for the application programmer. keep the interface to SCTP usable for the application programmer.
13. References 13. References
13.1. Normative References 13.1. Normative References
[RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
 End of changes. 86 change blocks. 
248 lines changed or deleted 253 lines changed or added

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