draft-ietf-tsvwg-sctpsocket-07.txt   draft-ietf-tsvwg-sctpsocket-08.txt 
Network Working Group R. Stewart Network Working Group R. Stewart
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Expires: February 20, 2004 Q. Xie Expires: September 30, 2004 Q. Xie
Motorola, Inc. Motorola, Inc.
L. Yarroll L. Yarroll
USACE ERDC-CERL. USACE ERDC-CERL.
J. Wood J. Wood
DoCoMo USA Labs DoCoMo USA Labs
K. Poon K. Poon
Consultant Sun Microsystems, Inc.
K. Fujita K. Fujita
NEC USA, Inc. NEC USA, Inc.
M. Tuexen M. Tuexen
Univ. of Applied Sciences Muenster Univ. of Applied Sciences Muenster
August 22, 2003 April 1, 2004
Sockets API Extensions for Stream Control Transmission Protocol Sockets API Extensions for Stream Control Transmission Protocol
(SCTP) (SCTP)
draft-ietf-tsvwg-sctpsocket-07.txt draft-ietf-tsvwg-sctpsocket-08.txt
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts. groups may also distribute working documents as Internet-Drafts.
skipping to change at page 1, line 43 skipping to change at page 1, line 43
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http:// The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt. www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on February 20, 2004. This Internet-Draft will expire on September 30, 2004.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved. Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract Abstract
This document describes a mapping of the Stream Control Transmission This document describes a mapping of the Stream Control Transmission
Protocol SCTP RFC2960 [8] into a sockets API. The benefits of this Protocol SCTP RFC2960 [8] into a sockets API. The benefits of this
mapping include compatibility for TCP applications, access to new mapping include compatibility for TCP applications, access to new
SCTP features and a consolidated error and event notification scheme. SCTP features and a consolidated error and event notification scheme.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6
2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6
3. one-to-many style Interface . . . . . . . . . . . . . . . 7 3. one-to-many style Interface . . . . . . . . . . . . . . . 7
3.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 7 3.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 7
3.1.1 socket() - one-to-many style socket . . . . . . . . . . . 8 3.1.1 socket() - one-to-many style socket . . . . . . . . . . . 8
3.1.2 bind() - one-to-many style socket . . . . . . . . . . . . 8 3.1.2 bind() - one-to-many style socket . . . . . . . . . . . . 9
3.1.3 listen() - One-to-many style socket . . . . . . . . . . . 9 3.1.3 listen() - One-to-many style socket . . . . . . . . . . . 10
3.1.4 sendmsg() and recvmsg() - one-to-many style socket . . . . 10 3.1.4 sendmsg() and recvmsg() - one-to-many style socket . . . . 10
3.1.5 close() - one-to-many style socket . . . . . . . . . . . . 11 3.1.5 close() - one-to-many style socket . . . . . . . . . . . . 12
3.1.6 connect() - one-to-many style socket . . . . . . . . . . . 12 3.1.6 connect() - one-to-many style socket . . . . . . . . . . . 12
3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 12 3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 13
3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13 3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13
3.4 Special considerations . . . . . . . . . . . . . . . . . . 14 3.4 Special considerations . . . . . . . . . . . . . . . . . . 14
4. one-to-one style Interface . . . . . . . . . . . . . . . . 16 4. one-to-one style Interface . . . . . . . . . . . . . . . . 17
4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 16 4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 17
4.1.1 socket() - one-to-one style socket . . . . . . . . . . . . 17 4.1.1 socket() - one-to-one style socket . . . . . . . . . . . . 18
4.1.2 bind() - one-to-one style socket . . . . . . . . . . . . . 17 4.1.2 bind() - one-to-one style socket . . . . . . . . . . . . . 18
4.1.3 listen() - one-to-one style socket . . . . . . . . . . . . 18 4.1.3 listen() - one-to-one style socket . . . . . . . . . . . . 19
4.1.4 accept() - one-to-one style socket . . . . . . . . . . . . 19 4.1.4 accept() - one-to-one style socket . . . . . . . . . . . . 20
4.1.5 connect() - one-to-one style socket . . . . . . . . . . . 19 4.1.5 connect() - one-to-one style socket . . . . . . . . . . . 20
4.1.6 close() - one-to-one style socket . . . . . . . . . . . . 20 4.1.6 close() - one-to-one style socket . . . . . . . . . . . . 21
4.1.7 shutdown() - one-to-one style socket . . . . . . . . . . . 20 4.1.7 shutdown() - one-to-one style socket . . . . . . . . . . . 21
4.1.8 sendmsg() and recvmsg() - one-to-one style socket . . . . 21 4.1.8 sendmsg() and recvmsg() - one-to-one style socket . . . . 22
4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 22 4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 23
5. Data Structures . . . . . . . . . . . . . . . . . . . . . 23 5. Data Structures . . . . . . . . . . . . . . . . . . . . . 24
5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 23 5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 24
5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 24 5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 25
5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 25 5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 26
5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 26 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 27
5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 28 5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 30
5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 29 5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 30
5.4 Ancillary Data Considerations and Semantics . . . . . . . 38 5.4 Ancillary Data Considerations and Semantics . . . . . . . 40
5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 38 5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 40
5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 39 5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 40
5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 39 5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 41
6. Common Operations for Both Styles . . . . . . . . . . . . 41 6. Common Operations for Both Styles . . . . . . . . . . . . 43
6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 41 6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 43
6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 42 6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 44
6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 42 6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 44
6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 42 6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 44
7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 44 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 46
7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 45 7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 47
7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 45 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 47
7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 46 7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 48
7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 47 7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 50
7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 48 7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 50
7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 48 7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 50
7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 48 7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 51
7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 48 7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 51
7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 49 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 51
7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 49 7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 51
7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . . . 49 7.1.10 Set Primary Address (SCTP_PRIMARY_ADDR) . . . . . . . . . 52
7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) . . . . 50 7.1.11 Set Adaption Layer Indicator (SCTP_ADAPTION_LAYER) . . . . 52
7.1.12 Enable/Disable message fragmentation 7.1.12 Enable/Disable message fragmentation
(SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 50 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 53
7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . . . 50 7.1.13 Peer Address Parameters (SCTP_PEER_ADDR_PARAMS) . . . . . 53
7.1.14 Set default send parameters (SCTP_DEFAULT_SEND_PARAM) . . 51 7.1.14 Set default send parameters (SCTP_DEFAULT_SEND_PARAM) . . 53
7.1.15 Set notification and ancillary events (SCTP_EVENTS) . . . 51 7.1.15 Set notification and ancillary events (SCTP_EVENTS) . . . 54
7.1.16 Set/clear IPv4 mapped addresses 7.1.16 Set/clear IPv4 mapped addresses
(SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . . . 51 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . . . 54
7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) . . . . . 52 7.1.17 Set the maximum fragmentation size (SCTP_MAXSEG) . . . . . 54
7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 52 7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 54
7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 52 7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 54
7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 53 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 56
7.3 Ancillary Data and Notification Interest Options . . . . . 54 7.3 Ancillary Data and Notification Interest Options . . . . . 57
8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 57 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 60
8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 57 8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 60
8.2 Branched-off Association . . . . . . . . . . . . . . . . . 58 8.2 Branched-off Association . . . . . . . . . . . . . . . . . 61
8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 58 8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 61
8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 59 8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 62
8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 59 8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 62
8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 60 8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 63
8.7 sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 60 8.7 sctp_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 63
8.8 sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 61 8.8 sctp_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 64
8.9 sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 61 8.9 sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 65
9. Preprocessor Constants . . . . . . . . . . . . . . . . . . 63 8.10 sctp_send() . . . . . . . . . . . . . . . . . . . . . . . 66
10. Security Considerations . . . . . . . . . . . . . . . . . 64 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . 67
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 65 10. Security Considerations . . . . . . . . . . . . . . . . . 68
References . . . . . . . . . . . . . . . . . . . . . . . . 66 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 69
Authors' Addresses . . . . . . . . . . . . . . . . . . . . 66 References . . . . . . . . . . . . . . . . . . . . . . . . 70
A. one-to-one style Code Example . . . . . . . . . . . . . . 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 70
B. one-to-many style Code Example . . . . . . . . . . . . . . 75 A. one-to-one style Code Example . . . . . . . . . . . . . . 73
Intellectual Property and Copyright Statements . . . . . . 77 B. one-to-many style Code Example . . . . . . . . . . . . . . 79
Intellectual Property and Copyright Statements . . . . . . 81
1. Introduction 1. Introduction
The sockets API has provided a standard mapping of the Internet The sockets API has provided a standard mapping of the Internet
Protocol suite to many operating systems. Both TCP RFC793 [1] and UDP Protocol suite to many operating systems. Both TCP RFC793 [1] and UDP
RFC768 [2] have benefited from this standard representation and RFC768 [2] have benefited from this standard representation and
access method across many diverse platforms. SCTP is a new protocol access method across many diverse platforms. SCTP is a new protocol
that provides many of the characteristics of TCP but also that provides many of the characteristics of TCP but also
incorporates semantics more akin to UDP. This document defines a incorporates semantics more akin to UDP. This document defines a
method to map the existing sockets API for use with SCTP, providing method to map the existing sockets API for use with SCTP, providing
skipping to change at page 4, line 28 skipping to change at page 4, line 28
There are three basic design objectives: There are three basic design objectives:
1) Maintain consistency with existing sockets APIs: 1) Maintain consistency with existing sockets APIs:
We define a sockets mapping for SCTP that is consistent with other We define a sockets mapping for SCTP that is consistent with other
sockets API protocol mappings (for instance, UDP, TCP, IPv4, and sockets API protocol mappings (for instance, UDP, TCP, IPv4, and
IPv6). IPv6).
2) Support a one-to-many style interface 2) Support a one-to-many style interface
This set of semantics is similar to that defined for connection This set of semantics is similar to that defined for
less protocols, such as UDP. It is more efficient than a TCP-like connection-less protocols, such as UDP. A one-to-many style SCTP
connection-oriented (the one-to-one style) interface in terms of socket should be able to control multiple SCTP associations. This
exploring the new features of SCTP. But the one-to-one style is similar to an UDP socket, which can communicate with many peer
interface can also make use of most new SCTP features. end points. Each of these associations is assigned an association
ID so that an applications can use the ID to differentiate them.
Note that SCTP is connection-oriented in nature, and it does not Note that SCTP is connection-oriented in nature, and it does not
support broadcast or multicast communications, as UDP does. support broadcast or multicast communications, as UDP does.
3) Support a one-to-one style interface 3) Support a one-to-one style interface
This interface supports a similar semantics as sockets for This interface supports a similar semantics as sockets for
connection-oriented protocols, such as TCP. connection-oriented protocols, such as TCP. A one-to-one style
SCTP socket should only control one SCTP association.
The purpose of defining this interface is to allow existing One purpose of defining this interface is to allow existing
applications built on connection-oriented protocols be ported to applications built on other connection-oriented protocols be
use SCTP with very little effort, and developers familiar with ported to use SCTP with very little effort. And developers
those semantics can easily adapt to SCTP. familiar with those semantics can easily adapt to SCTP. Another
purpose is to make sure that existing mechanisms in most OSes to
deal with socket, such as select(), should continue to work with
this style of socket.
Extensions are added to this mapping to provide mechanisms to Extensions are added to this mapping to provide mechanisms to
exploit new features of SCTP. exploit new features of SCTP.
Goals 2 and 3 are not compatible, so in this document we define two Goals 2 and 3 are not compatible, so in this document we define two
modes of mapping, namely the one-to-many style mapping and the modes of mapping, namely the one-to-many style mapping and the
one-to-one style mapping. These two modes share some common data one-to-one style mapping. These two modes share some common data
structures and operations, but will require the use of two different structures and operations, but will require the use of two different
application programming styles. application programming styles. Note that all new SCTP features can
be used with both styles of socket. The decision on which one to use
depends mainly on the nature of applications.
A mechanism is defined to extract a one-to-many style SCTP A mechanism is defined to extract a one-to-many style SCTP
association into a one-to-one style socket. association into a one-to-one style socket.
Some of the SCTP mechanisms cannot be adequately mapped to existing Some of the SCTP mechanisms cannot be adequately mapped to existing
socket interface. In some cases, it is more desirable to have new socket interface. In some cases, it is more desirable to have new
interface instead of using existing socket calls. This document also interface instead of using existing socket calls. Section 8 of this
describes those new interface. document describes those new interface.
2. Conventions 2. Conventions
2.1 Data Types 2.1 Data Types
Whenever possible, data types from Draft 6.6 (March 1997) of POSIX Whenever possible, data types from Draft 6.6 (March 1997) of POSIX
1003.1g are used: uintN_t means an unsigned integer of exactly N bits 1003.1g are used: uintN_t means an unsigned integer of exactly N bits
(e.g., uint16_t). We also assume the argument data types from (e.g., uint16_t). We also assume the argument data types from
1003.1g when possible (e.g., the final argument to setsockopt() is a 1003.1g when possible (e.g., the final argument to setsockopt() is a
size_t value). Whenever buffer sizes are specified, the POSIX 1003.1 size_t value). Whenever buffer sizes are specified, the POSIX 1003.1
skipping to change at page 7, line 45 skipping to change at page 7, line 45
1. socket() 1. socket()
2. sendmsg() 2. sendmsg()
3. recvmsg() 3. recvmsg()
4. close() 4. 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. endpoint are represented with a single socket. Each associations is
assigned an association ID (type is sctp_assoc_t) so that an
application can use it to differentiate between them. In some
implementations, the peer end point's addresses can also be used for
this purpose. But this is not required for performance reasons. If
an implementation does not support using addresses to differentiate
between different associations, the sendto() call can only be used to
setup an association implicitly. It cannot be used to send data to
an established association as the association ID cannot be specified.
Once as association ID is assigned to an SCTP association, that ID
will not be reused until the application explicitly terminates the
association. The resources belonged to that association will not be
freed until that happens. This is similar to the close() operation
on a normal socket. The only exception is when the SCTP_AUTOCLOSE
option (section 7.1.8) is set. In this case, after the association
is terminated automatically, the association ID assigned to it can be
reused. All applications using this option should be aware of this
to avoid the possible problem of sending data to an incorrect peer
end point.
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 in to a separate socket, it is required to call sctp_peeloff() and in
the parameter specifies the association identification. The the parameter specifies the association identification. The
sctp_peeloff() call will return a new socket which can then be used sctp_peeloff() call will return a new socket which can then be used
with recv() and send() functions for message passing. See Section 8.2 with recv() and send() functions for message passing. See Section 8.2
for more on branched-off associations. for 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 8, line 49 skipping to change at page 9, line 20
An SCTP endpoint can be associated with multiple addresses. To do An SCTP endpoint can be associated with multiple addresses. To do
this, sctp_bindx() is introduced in section Section 8.1 to help this, sctp_bindx() is introduced in section Section 8.1 to help
applications do the job of associating multiple addresses. applications do the job of associating multiple addresses.
These addresses associated with a socket are the eligible transport These addresses associated with a socket are the eligible transport
addresses for the endpoint to send and receive data. The endpoint addresses for the endpoint to send and receive data. The endpoint
will also present these addresses to its peers during the association will also present these addresses to its peers during the association
initialization process, see RFC2960 [8]. initialization process, see RFC2960 [8].
After calling bind() or sctp_bindx(), if the endpoint wishes to After calling bind(), if the endpoint wishes to accept new
accept new associations on the socket, it must call listen() (see associations on the socket, it must call listen() (see section
section Section 3.1.3). Section 3.1.3).
The syntax of bind() is, The syntax of bind() is,
ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen); ret = bind(int sd, struct sockaddr *addr, socklen_t addrlen);
sd: the socket descriptor returned by socket(). sd: the socket descriptor returned by socket().
addr: the address structure (struct sockaddr_in or struct addr: the address structure (struct sockaddr_in or struct
sockaddr_in6 RFC2553 [7]). sockaddr_in6 RFC2553 [7]).
skipping to change at page 9, line 29 skipping to change at page 9, line 48
Applications cannot call bind() multiple times to associate multiple Applications cannot call bind() multiple times to associate multiple
addresses to an endpoint. After the first call to bind(), all addresses to an endpoint. After the first call to bind(), all
subsequent calls will return an error. subsequent calls will return an error.
If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, If addr is specified as a wildcard (INADDR_ANY for an IPv4 address,
or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the
operating system will associate the endpoint with an optimal address operating system will associate the endpoint with an optimal address
set of the available interfaces. set of the available interfaces.
If a bind() or sctp_bindx() is not called prior to a sendmsg() call If a bind() is not called prior to a sendmsg() call that initiates a
that initiates a new association, the system picks an ephemeral port new association, the system picks an ephemeral port and will choose
and will choose an address set equivalent to binding with a wildcard an address set equivalent to binding with a wildcard address. One of
address. One of those addresses will be the primary address for the those addresses will be the primary address for the association. This
association. This automatically enables the multi-homing capability automatically enables the multi-homing capability of SCTP.
of SCTP.
3.1.3 listen() - One-to-many style socket 3.1.3 listen() - One-to-many style socket
By default, new associations are not accepted for one-to-many style By default, new associations are not accepted for one-to-many style
sockets. An application uses listen() to mark a socket as being able sockets. An application uses listen() to mark a socket as being able
to accept new associations. The syntax is, to accept new associations. The syntax is,
int listen(int socket, int backlog); int listen(int sd, int backlog);
socket - the socket descriptor of the endpoint. sd - the socket descriptor of the endpoint.
backlog - if backlog is non-zero, enable listening else backlog - if backlog is non-zero, enable listening else
disable listening. disable listening.
Note that one-to-many style socket consumers do not need to call Note that one-to-many style socket consumers do not need to call
accept to retrieve new associations. Calling accept() on a accept to retrieve new associations. Calling accept() on a
one-to-many style socket should return EOPNOTSUPP. Rather, new one-to-many style socket should return EOPNOTSUPP. Rather, new
associations are accepted automatically, and notifications of the new associations are accepted automatically, and notifications of the new
associations are delivered via recvmsg() with the SCTP_ASSOC_CHANGE associations are delivered via recvmsg() with the SCTP_ASSOC_CHANGE
event (if these notifications are enabled). Clients will typically event (if these notifications are enabled). Clients will typically
not call listen(), so that they can be assured that the only not call listen(), so that they can be assured that the only
skipping to change at page 10, line 22 skipping to change at page 10, line 41
ID for a new association, so if applications wish to use the ID for a new association, so if applications wish to use the
association ID as input to other socket calls, they should ensure association ID as input to other socket calls, they should ensure
that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by that the SCTP_ASSOC_CHANGE event is enabled (it is enabled by
default). default).
3.1.4 sendmsg() and recvmsg() - one-to-many style socket 3.1.4 sendmsg() and recvmsg() - one-to-many style socket
An application uses sendmsg() and recvmsg() call to transmit data to An application uses sendmsg() and recvmsg() call to transmit data to
and receive data from its peer. and receive data from its peer.
ssize_t sendmsg(int socket, const struct msghdr *message, int flags); ssize_t sendmsg(int sd, const struct msghdr *message, int flags);
ssize_t recvmsg(int socket, struct msghdr *message, int flags); ssize_t recvmsg(int sd, struct msghdr *message, int flags);
socket: the socket descriptor of the endpoint. sd: the socket descriptor of the endpoint.
message: pointer to the msghdr structure which contains a single user message: pointer to the msghdr structure which contains a single user
message and possibly some ancillary data. See Section 5 for message and possibly some ancillary data. See Section 5 for
complete description of the data structures. complete description of the data structures.
flags: No new flags are defined for SCTP at this level. See Section 5 flags: No new flags are defined for SCTP at this level. See Section 5
for SCTP-specific flags used in the msghdr structure. for SCTP-specific flags used in the msghdr structure.
As we will see in Section 5, along with the user data, the ancillary As we will see in Section 5, along with the user data, the ancillary
data field is used to carry the sctp_sndrcvinfo and/or the data field is used to carry the sctp_sndrcvinfo and/or the
skipping to change at page 12, line 33 skipping to change at page 13, line 7
sockaddr_in6 defined in RFC2553 [7]). sockaddr_in6 defined in RFC2553 [7]).
len: the size of the address. len: the size of the address.
Multiple connect() calls can be made on the same socket to create Multiple connect() calls can be made on the same socket to create
multiple associations. This is different from the semantics of multiple associations. This is different from the semantics of
connect() on a UDP socket. connect() on a UDP socket.
3.2 Implicit Association Setup 3.2 Implicit Association Setup
Once all bind() calls are complete on a one-to-many style socket, the Once the bind() call is complete on a one-to-many style socket, the
application can begin sending and receiving data using the sendmsg()/ application can begin sending and receiving data using the sendmsg()/
recvmsg() or sendto()/recvfrom() calls, without going through any recvmsg() or sendto()/recvfrom() calls, without going through any
explicit association setup procedures (i.e., no connect() calls explicit association setup procedures (i.e., no connect() calls
required). required).
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 there is no association existing between the sender sender finds that there is no association existing between the sender
and the intended receiver (identified by the address passed either in and the intended receiver (identified by the address passed either in
the msg_name field of msghdr structure in the sendmsg() call or the 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
skipping to change at page 13, line 29 skipping to change at page 13, line 49
setsockopt() calls or be left to the system defaults. setsockopt() calls or be left to the system defaults.
Implicit association setup cannot be initiated by send()/recv() Implicit association setup cannot be initiated by send()/recv()
calls. calls.
3.3 Non-blocking mode 3.3 Non-blocking mode
Some SCTP users might want to avoid blocking when they call socket Some SCTP users might want to avoid blocking when they call socket
interface function. interface function.
Whenever the user which want to avoid blocking must call select()
before calling sendmsg()/sendto() and recvmsg()/recvfrom(), and check
the socket status is writable or readable. If the socket status is
not writable sendmsg() and sendto() return EAGAIN and do not transmit
the message. Similarly, if the status is not readable, recvmsg() and
recvfrom() return EAGAIN.
Once all bind() calls are complete on a one-to-many style socket, the Once all bind() calls are complete on a one-to-many style socket, the
application must set the non-blocking option by a fcntl() (such as application must set the non-blocking option by a fcntl() (such as
O_NONBLOCK). After which the sendmsg() function returns immediately, O_NONBLOCK). After which the sendmsg() function returns immediately,
and the success or failure of the data message (and possible and the success or failure of the data message (and possible
SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE SCTP_INITMSG parameters) will be signaled by the SCTP_ASSOC_CHANGE
event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not event with SCTP_COMM_UP or CANT_START_ASSOC. If user data could not
be sent (due to a CANT_START_ASSOC), the sender will also receive a be sent (due to a CANT_START_ASSOC), the sender will also receive a
SCTP_SEND_FAILED event. Those event(s) can be received by the user SCTP_SEND_FAILED event. Those event(s) can be received by the user
calling of recvmsg(). A server (having called listen()) is also calling of recvmsg(). A server (having called listen()) is also
notified of an association up event by the reception of a notified of an association up event by the reception of a
SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and SCTP_ASSOC_CHANGE with SCTP_COMM_UP via the calling of recvmsg() and
possibly the reception of the first data message. possibly the reception of the first data message.
In order to shutdown the association gracefully, the user must call In order to shutdown the association gracefully, the user must call
sendmsg() with no data and with the MSG_EOF flag set. The function sendmsg() with no data and with the MSG_EOF flag set. The function
returns immediately, and completion of the graceful shutdown is returns immediately, and completion of the graceful shutdown is
indicated by an SCTP_ASSOC_CHANGE notification of type indicated by an SCTP_ASSOC_CHANGE notification of type
SHUTDOWN_COMPLETE (see Section 5.3.1.1). SHUTDOWN_COMPLETE (see Section 5.3.1.1). Note that this can also be
done using the sctp_send() call described in Section 8.10.
An application is recommended to use caution when using select() (or
poll()) for writing on a one-to-many style socket. The reason being
that interpretation of select on write is implementation specific.
Generally a positive return on a select on write would only indicate
that one of the associations represented by the one-to-many socket is
writable. An application that writes after the select return may
still block since the association that was writeable is not the
destination association of the write call. Likewise select (or
poll()) for reading from a one-to-many socket will only return an
indication that one of the associations represented by the socket has
data to be read.
An application that wishes to know that a particular association is
ready for reading or writing should either use the one-to-one style
or use the sctp_peelloff() (see Section 8.2) function to seperate the
association of interest from the one-to-many socket.
3.4 Special considerations 3.4 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 directly sockets layer is managed. Because this implementation detail directly
affects how application programmers must write their code to ensure affects how application programmers must write their code to ensure
correct operation and portability, this section provides some correct operation and portability, this section provides some
guidance to both implementors and application programmers. guidance to both implementors 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 it uses all of its socket buffer space
allocation creating a "stalled connection". Further attempts to allocation creating a "stalled connection". Further attempts to
write to the socket will block or return the error EAGAIN (for a write to the socket will block or return the error EAGAIN or
non-blocking socket). At some point, either the connection is EWOULDBLOCK for a non-blocking socket. At some point, either the
closed, or the receiver begins to read again freeing space in the connection is closed, or the receiver begins to read again freeing
output queue. space in the output queue.
For one-to-one style SCTP sockets (this includes sockets descriptors For one-to-one style SCTP sockets (this includes sockets descriptors
that were separated from a one-to-many style socket with that were separated from a one-to-many style socket with
sctp_peeloff()) the behavior is identical. For one-to-many style sctp_peeloff()) the behavior is identical. For one-to-many style
SCTP sockets, the fact that we have multiple associations on a single SCTP sockets, the fact that we have multiple associations on a single
socket makes the situation more complicated. If the implementation socket 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 18, line 23 skipping to change at page 19, line 23
Applications cannot call bind() multiple times to associate multiple Applications cannot call bind() multiple times to associate multiple
addresses to the endpoint. After the first call to bind(), all addresses to the endpoint. After the first call to bind(), all
subsequent calls will return an error. subsequent calls will return an error.
If addr is specified as a wildcard (INADDR_ANY for an IPv4 address, If addr is specified as a wildcard (INADDR_ANY for an IPv4 address,
or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the or as IN6ADDR_ANY_INIT or in6addr_any for an IPv6 address), the
operating system will associate the endpoint with an optimal address operating system will associate the endpoint with an optimal address
set of the available interfaces. set of the available interfaces.
If a bind() or sctp_bindx() is not called prior to the connect() If a bind() is not called prior to the connect() call, the system
call, the system picks an ephemeral port and will choose an address picks an ephemeral port and will choose an address set equivalent to
set equivalent to binding with a wildcard address. One of those binding with a wildcard address. One of those addresses will be the
addresses will be the primary address for the association. This primary address for the association. This automatically enables the
automatically enables the multi-homing capability of SCTP. multi-homing capability of SCTP.
The completion of this bind() process does not ready the SCTP The completion of this bind() process does not ready the SCTP
endpoint to accept inbound SCTP association requests. Until a endpoint to accept inbound SCTP association requests. Until a
listen() system call, described below, is performed on the socket, listen() system call, described below, is performed on the socket,
the SCTP endpoint will promptly reject an inbound SCTP INIT request the SCTP endpoint will promptly reject an inbound SCTP INIT request
with an SCTP ABORT. with an SCTP ABORT.
4.1.3 listen() - one-to-one style socket 4.1.3 listen() - one-to-one style socket
Applications use listen() to ready the SCTP endpoint for accepting Applications use listen() to ready the SCTP endpoint for accepting
skipping to change at page 19, line 46 skipping to change at page 20, line 46
addrlen the size of the address. addrlen the size of the address.
This operation corresponds to the ASSOCIATE primitive described in This operation corresponds to the ASSOCIATE primitive described in
section 10.1 of RFC2960 [8]. section 10.1 of RFC2960 [8].
By default, the new association created has only one outbound stream. By default, the new association created has only one outbound stream.
The SCTP_INITMSG option described in Section 7.1.3 should be used The SCTP_INITMSG option described in Section 7.1.3 should be used
before connecting to change the number of outbound streams. before connecting to change the number of outbound streams.
If a bind() or sctp_bindx() is not called prior to the connect() If a bind() is not called prior to the connect() call, the system
call, the system picks an ephemeral port and will choose an address picks an ephemeral port and will choose an address set equivalent to
set equivalent to binding with INADDR_ANY and IN6ADDR_ANY for IPv4 binding with INADDR_ANY and IN6ADDR_ANY for IPv4 and IPv6 socket
and IPv6 socket respectively. One of those addresses will be the respectively. One of those addresses will be the primary address for
primary address for the association. This automatically enables the the association. This automatically enables the multi-homing
multi-homing capability of SCTP. capability of SCTP.
Note that SCTP allows data exchange, similar to T/TCP RFC1644 [3], Note that SCTP allows data exchange, similar to T/TCP RFC1644 [3],
during the association set up phase. If an application wants to do during the association set up phase. If an application wants to do
this, it cannot use connect() call. Instead, it should use sendto() this, it cannot use connect() call. Instead, it should use sendto()
or sendmsg() to initiate an association. If it uses sendto() and it or sendmsg() to initiate an association. If it uses sendto() and it
wants to change initialization behavior, it needs to use the wants to change initialization behavior, it needs to use the
SCTP_INITMSG socket option before calling sendto(). Or it can use SCTP_INITMSG socket option before calling sendto(). Or it can use
SCTP_INIT type sendmsg() to initiate an association without doing the SCTP_INIT type sendmsg() to initiate an association without doing the
setsockopt(). Note that some sockets implementations may not support setsockopt(). Note that some sockets implementations may not support
the sending of data to initiate an assocation with the one-to-one the sending of data to initiate an assocation with the one-to-one
skipping to change at page 20, line 49 skipping to change at page 22, line 5
SCTP differs from TCP in that it does not have half closed semantics. SCTP differs from TCP in that it does not have half closed semantics.
Hence the shutdown() call for SCTP is an approximation of the TCP Hence the shutdown() call for SCTP is an approximation of the TCP
shutdown() call, and solves some different problems. Full shutdown() call, and solves some different problems. Full
TCP-compatibility is not provided, so developers porting TCP TCP-compatibility is not provided, so developers porting TCP
applications to SCTP may need to recode sections that use shutdown(). applications to SCTP may need to recode sections that use shutdown().
(Note that it is possible to achieve the same results as half close (Note that it is possible to achieve the same results as half close
in SCTP using SCTP streams.) in SCTP using SCTP streams.)
The syntax is: The syntax is:
int shutdown(int socket, int how); int shutdown(int sd, int how);
sd - the socket descriptor of the association to be closed. sd - the socket descriptor of the association to be closed.
how - Specifies the type of shutdown. The values are how - Specifies the type of shutdown. The values are
as follows: as follows:
SHUT_RD SHUT_RD
Disables further receive operations. No SCTP Disables further receive operations. No SCTP
protocol action is taken. protocol action is taken.
skipping to change at page 22, line 14 skipping to change at page 23, line 18
4.1.9 getpeername() 4.1.9 getpeername()
Applications use getpeername() to retrieve the primary socket address Applications use getpeername() to retrieve the primary socket address
of the peer. This call is for TCP compatibility, and is not of the peer. This call is for TCP compatibility, and is not
multi-homed. It does not work with one-to-many style sockets. See multi-homed. It does not work with one-to-many style sockets. See
Section 8.3 for a multi-homed/one-to-many style version of the call. Section 8.3 for a multi-homed/one-to-many style version of the call.
The syntax is: The syntax is:
int getpeername(int socket, struct sockaddr *address, int getpeername(int sd, struct sockaddr *address,
socklen_t *len); socklen_t *len);
sd - the socket descriptor to be queried. sd - the socket descriptor to be queried.
address - On return, the peer primary address is stored in address - On return, the peer primary address is stored in
this buffer. If the socket is an IPv4 socket, the this buffer. If the socket is an IPv4 socket, the
address will be IPv4. If the socket is an IPv6 socket, address will be IPv4. If the socket is an IPv6 socket,
the address will be either an IPv6 or IPv4 the address will be either an IPv6 or IPv4
address. address.
skipping to change at page 43, line 11 skipping to change at page 45, line 11
6.4 getsockname() 6.4 getsockname()
Applications use getsockname() to retrieve the locally-bound socket Applications use getsockname() to retrieve the locally-bound socket
address of the specified socket. This is especially useful if the address of the specified socket. This is especially useful if the
caller let SCTP chose a local port. This call is for where the caller let SCTP chose a local port. This call is for where the
endpoint is not multi-homed. It does not work well with multi-homed endpoint is not multi-homed. It does not work well with multi-homed
sockets. See Section 8.5 for a multi-homed version of the call. sockets. See Section 8.5 for a multi-homed version of the call.
The syntax is: The syntax is:
int getsockname(int socket, struct sockaddr *address, int getsockname(int sd, struct sockaddr *address,
socklen_t *len); socklen_t *len);
sd - the socket descriptor to be queried. sd - the socket descriptor to be queried.
address - On return, one locally bound address (chosen by address - On return, one locally bound address (chosen by
the SCTP stack) is stored in this buffer. If the the SCTP stack) is stored in this buffer. If the
socket is an IPv4 socket, the address will be IPv4. socket is an IPv4 socket, the address will be IPv4.
If the socket is an IPv6 socket, the address will If the socket is an IPv6 socket, the address will
be either an IPv6 or IPv4 address. be either an IPv6 or IPv4 address.
skipping to change at page 49, line 13 skipping to change at page 51, line 35
associations (see Section 3.4) bound to the socket descriptor associations (see Section 3.4) bound to the socket descriptor
used in the setsockopt() or getsockopt() call. The option applies to used in the setsockopt() or getsockopt() call. The option applies to
each association's window size separately. The call expects an each association's window size separately. The call expects an
integer. integer.
7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE)
This socket option is applicable to the one-to-many style socket This socket option is applicable to the one-to-many style socket
only. When set it will cause associations that are idle for more than only. When set it will cause associations that are idle for more than
the specified number of seconds to automatically close. An the specified number of seconds to automatically close. An
association being idle is defined an association that has NOT sent or association being idle is defined as an association that has NOT sent
received user data. The special value of '0' indicates that no or received user data. The special value of '0' indicates that no
automatic close of any associations should be performed. The option automatic close of any associations should be performed, this is the
expects an integer defining the number of seconds of idle time before default value. The option expects an integer defining the number of
an association is closed. seconds of idle time before an association is closed.
An application using this option should enable receiving the
association change notification. This is the only mechanism an
application is informed about the closing of an association. After
an association is closed, the association ID assigned to it can be
reused. An application should be aware of this to avoid the possible
problem of sending data to an incorrect peer end point.
7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 7.1.9 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR)
Requests that the peer mark the enclosed address as the association Requests that the peer mark the enclosed address as the association
primary. The enclosed address must be one of the association's primary. The enclosed address must be one of the association's
locally bound addresses. The following structure is used to make a locally bound addresses. The following structure is used to make a
set primary request: set primary request:
struct sctp_setpeerprim { struct sctp_setpeerprim {
sctp_assoc_t sspp_assoc_id; sctp_assoc_t sspp_assoc_id;
skipping to change at page 55, line 4 skipping to change at page 57, line 35
5.3.1.3) 5.3.1.3)
6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in Section 6. SCTP_SHUTDOWN_EVENT (sctp_shtudown_event): (described in Section
5.3.1.5) 5.3.1.5)
7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event): 7. SCTP_PARTIAL_DELIVERY_EVENT (sctp_partial_delivery_event):
(described in Section 5.3.1.7) (described in Section 5.3.1.7)
8. SCTP_ADAPTION_INDICATION (sctp_adaption_layer_event): (described 8. SCTP_ADAPTION_INDICATION (sctp_adaption_layer_event): (described
in Section 5.3.1.6) in Section 5.3.1.6)
To receive any ancillary data or notifications, first the application To receive any ancillary data or notifications, first the application
registers it's interest by calling the SCTP_EVENTS setsockopt() with registers it's interest by calling the SCTP_EVENTS setsockopt() with
the following structure. the following structure.
struct sctp_event_subscribe{ struct sctp_event_subscribe{
u_int8_t sctp_data_io_event; uint8_t sctp_data_io_event;
u_int8_t sctp_association_event; uint8_t sctp_association_event;
u_int8_t sctp_address_event; uint8_t sctp_address_event;
u_int8_t sctp_send_failure_event; uint8_t sctp_send_failure_event;
u_int8_t sctp_peer_error_event; uint8_t sctp_peer_error_event;
u_int8_t sctp_shutdown_event; uint8_t sctp_shutdown_event;
u_int8_t sctp_partial_delivery_event; uint8_t sctp_partial_delivery_event;
u_int8_t sctp_adaption_layer_event; uint8_t sctp_adaption_layer_event;
}; };
sctp_data_io_event - Setting this flag to 1 will cause the reception sctp_data_io_event - Setting this flag to 1 will cause the reception
of SCTP_SNDRCV information on a per message basis. The application of SCTP_SNDRCV information on a per message basis. The application
will need to use the recvmsg() interface so that it can receive the will need to use the recvmsg() interface so that it can receive the
event information contained in the msg_control field. Please see event information contained in the msg_control field. Please see
Section 5.2 for further details. Setting the flag to 0 will disable Section 5.2 for further details. Setting the flag to 0 will disable
reception of the message control information. reception of the message control information.
sctp_association_event - Setting this flag to 1 will enable the sctp_association_event - Setting this flag to 1 will enable the
skipping to change at page 57, line 25 skipping to change at page 60, line 25
int flags); int flags);
If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. If sd is an IPv4 socket, the addresses passed must be IPv4 addresses.
If the sd is an IPv6 socket, the addresses passed can either be IPv4 If the sd is an IPv6 socket, the addresses passed can either be IPv4
or IPv6 addresses. or IPv6 addresses.
A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see A single address may be specified as INADDR_ANY or IN6ADDR_ANY, see
Section 3.1.2 for this usage. Section 3.1.2 for this usage.
addrs is a pointer to an array of one or more socket addresses. Each addrs is a pointer to an array of one or more socket addresses. Each
address is contained in its appropriate structure (i.e. struct address is contained in its appropriate structure. For an IPv6
sockaddr_in or struct sockaddr_in6) the family of the address type socket, an array of sockaddr_in6 would be returned. For a IPv4
must be used to distengish the address length (note that this socket, an array of sockaddr_in would be returned. The caller
representation is termed a "packed array" of addresses). The caller
specifies the number of addresses in the array with addrcnt. specifies the number of addresses in the array with addrcnt.
On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns On success, sctp_bindx() returns 0. On failure, sctp_bindx() returns
-1, and sets errno to the appropriate error code. -1, and sets errno to the appropriate error code.
For SCTP, the port given in each socket address must be the same, or For SCTP, the port given in each socket address must be the same, or
sctp_bindx() will fail, setting errno to EINVAL. sctp_bindx() will fail, setting errno to EINVAL.
The flags parameter is formed from the bitwise OR of zero or more of The flags parameter is formed from the bitwise OR of zero or more of
the following currently defined flags: the following currently defined flags:
skipping to change at page 59, line 5 skipping to change at page 62, line 4
the specified identifier of the association that is to be branched the specified identifier of the association that is to be branched
off to a separate file descriptor (Note, in a traditional off to a separate file descriptor (Note, in a traditional
one-to-one style accept() call, this would be an out parameter, one-to-one style accept() call, this would be an out parameter,
but for the one-to-many style call, this is an in parameter). but for the one-to-many style call, this is an in parameter).
8.3 sctp_getpaddrs() 8.3 sctp_getpaddrs()
sctp_getpaddrs() returns all peer addresses in an association. The sctp_getpaddrs() returns all peer addresses in an association. The
syntax is, syntax is,
int sctp_getpaddrs(int sd, sctp_assoc_t id, int sctp_getpaddrs(int sd, sctp_assoc_t id,
struct sockaddr **addrs); struct sockaddr **addrs);
On return, addrs will point to a dynamically allocated packed array On return, addrs will point to an array dynamically allocated
of sockaddr structures of the appropriate type for each address. The sockaddr structures of the appropriate type for the socket type. The
caller should use sctp_freepaddrs() to free the memory. Note that the caller should use sctp_freepaddrs() to free the memory. Note that the
in/out parameter addrs must not be NULL. in/out parameter addrs must not be NULL.
If sd is an IPv4 socket, the addresses returned will be all IPv4 If sd is an IPv4 socket, the addresses returned will be all IPv4
addresses. If sd is an IPv6 socket, the addresses returned can be a addresses. If sd is an IPv6 socket, the addresses returned can be a
mix of IPv4 or IPv6 addresses. mix of IPv4 or IPv6 addresses.
For one-to-many style sockets, id specifies the association to query. For one-to-many style sockets, id specifies the association to query.
For one-to-one style sockets, id is ignored. For one-to-one style sockets, id is ignored.
skipping to change at page 59, line 41 skipping to change at page 62, line 39
void sctp_freepaddrs(struct sockaddr *addrs); void sctp_freepaddrs(struct sockaddr *addrs);
addrs is the array of peer addresses returned by sctp_getpaddrs(). addrs is the array of peer addresses returned by sctp_getpaddrs().
8.5 sctp_getladdrs() 8.5 sctp_getladdrs()
sctp_getladdrs() returns all locally bound address(es) on a socket. sctp_getladdrs() returns all locally bound address(es) on a socket.
The syntax is, The syntax is,
int sctp_getladdrs(int sock, sctp_assoc_t id, int sctp_getladdrs(int sd, sctp_assoc_t id,
struct sockaddr **ss); struct sockaddr **ss);
On return, addrs will point to a dynamically allocated packed array On return, addrs will point to a dynamically allocated array of
of sockaddr structures of the appropriate type for each local sockaddr structures of the appropriate type for the socket type. The
address. The caller should use sctp_freeladdrs() to free the memory. caller should use sctp_freeladdrs() to free the memory. Note that the
Note that the in/out parameter addrs must not be NULL. in/out parameter addrs must not be NULL.
If sd is an IPv4 socket, the addresses returned will be all IPv4 If sd is an IPv4 socket, the addresses returned will be all IPv4
addresses. If sd is an IPv6 socket, the addresses returned can be a addresses. If sd is an IPv6 socket, the addresses returned can be a
mix of IPv4 or IPv6 addresses. mix of IPv4 or IPv6 addresses.
For one-to-many style sockets, id specifies the association to query. For one-to-many style sockets, id specifies the association to query.
For one-to-one style sockets, id is ignored. For one-to-one style sockets, id is ignored.
If the id field is set to the value '0' then the locally bound If the id field is set to the value '0' then the locally bound
addresses are returned without regard to any particular association. addresses are returned without regard to any particular association.
skipping to change at page 60, line 36 skipping to change at page 64, line 7
addrs is the array of peer addresses returned by sctp_getladdrs(). addrs is the array of peer addresses returned by sctp_getladdrs().
8.7 sctp_sendmsg() 8.7 sctp_sendmsg()
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.
sctp_sendmsg(). Its syntax is, sctp_sendmsg(). Its syntax is,
ssize_t sctp_sendmsg(int s, ssize_t sctp_sendmsg(int sd,
const void *msg, const void *msg,
size_t len, size_t len,
struct sockaddr *to, const struct sockaddr *to,
socklen_t tolen, socklen_t tolen,
uint32_t ppid, uint32_t ppid,
uint32_t flags, uint32_t flags,
uint16_t stream_no, uint16_t stream_no,
uint32_t timetolive, uint32_t timetolive,
uint32_t context) uint32_t context)
s - is the socket descriptor sd - is the socket descriptor
msg - is the message to be sent. msg - is the message to be sent.
len - is the length of the message. len - is the length of the message.
to - is the destination address of the message. to - is the destination address of the message.
tolen - is the length of the destination address. tolen - is the length of the destination address.
ppid - is the same as sinfo_ppid (see section 5.2.2) ppid - is the same as sinfo_ppid (see section 5.2.2)
flags - is the same as sinfo_flags (see section 5.2.2) flags - is the same as sinfo_flags (see section 5.2.2)
stream_no - is the same as sinfo_stream (see section 5.2.2) stream_no - is the same as sinfo_stream (see section 5.2.2)
timetolive - is the same as sinfo_timetolive (see section 5.2.2) timetolive - is the same as sinfo_timetolive (see section 5.2.2)
context - is the same as sinfo_context (see section 5.2.2) context - is the same as sinfo_context (see section 5.2.2)
8.8 sctp_recvmsg() 8.8 sctp_recvmsg()
An implementation may provide a library function (or possibly system An implementation may provide a library function (or possibly system
skipping to change at page 61, line 22 skipping to change at page 65, line 7
8.8 sctp_recvmsg() 8.8 sctp_recvmsg()
An implementation may provide a library function (or possibly system An implementation may provide a library function (or possibly system
call) to assist the user with the advanced features of SCTP. Note call) to assist the user with the advanced features of SCTP. Note
that in order for the sctp_sndrcvinfo structure to be filled in by that in order for the sctp_sndrcvinfo structure to be filled in by
sctp_recvmsg() the caller must enable the sctp_data_io_events with sctp_recvmsg() the caller must enable the sctp_data_io_events with
the SCTP_EVENTS option. the SCTP_EVENTS option.
sctp_recvmsg(). Its syntax is, sctp_recvmsg(). Its syntax is,
ssize_t sctp_recvmsg(int s, 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)
s - is the socket descriptor sd - is the socket descriptor
msg - is a message buffer to be filled. msg - is a message buffer to be filled.
len - is the length of the message buffer. len - is the length of the message buffer.
from - is a pointer to a address to be filled with from - is a pointer to a address to be filled with
the sender of this messages address. the sender of this messages address.
fromlen - is the from length. fromlen - is the from length.
sinfo - A pointer to a sctp_sndrcvinfo structure sinfo - A pointer to a sctp_sndrcvinfo structure
to be filled upon receipt of the message. to be filled upon receipt of the message.
msg_flags - A pointer to a integer to be filled with msg_flags - A pointer to a integer to be filled with
any message flags (e.g. MSG_NOTIFICATION). any message flags (e.g. MSG_NOTIFICATION).
8.9 sctp_connectx() 8.9 sctp_connectx()
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 associating to an endpoint that is call) to assist the user with associating to an endpoint that is
multi-homed. Much like sctp_bindx() this call allows a caller to multi-homed. Much like sctp_bindx() this call allows a caller to
specify multiple addresses at which a peer can be reached. specify multiple addresses at which a peer can be reached. The way
the SCTP stack uses the list of addresses to set up the association
is implementation dependant. This function only specifies that the
stack will try to make use of all the addresses in the list when
needed.
Note that the list of addresses passed in is only used for setting up
the association. It does not necessarily equal the set of addresses
the peer uses for the resulting association. If the caller wants to
find out the set of peer addresses, it must use sctp_getpaddrs() to
retrieve them after the association has been set up.
sctp_connectx(). Its syntax is, sctp_connectx(). Its syntax is,
int sctp_connectx(int s,
int sctp_connectx(int sd,
struct sockaddr *addrs, struct sockaddr *addrs,
int addrcnt) int addrcnt)
s - is the socket descriptor sd - is the socket descriptor
addrs - is an array of addresses. addrs - is an array of addresses.
addrcnt - is the number of addresses in the array. addrcnt - is the number of addresses in the array.
8.10 sctp_send()
An implementation may provide another alternative function or system
call to assist an application with the sending of data without the
use of the CMSG header structures. The function takes the following
form:
sctp_send(). Its syntax is,
int sctp_send(int sd,
const void *msg,
size_t len,
const struct sctp_sndrcvinfo *sinfo,
int flags);
sd - is the socket descriptor
msg - The message to be sent
len - The length of the message
sinfo - A pointer to a sctp_sndrcvinfo struture used
as described in 5.2.2 for a sendmsg call.
flags - is used in the same format as the sendmsg call
flags (e.g. MSG_DONTROUTE).
This function call may also be used to terminate an association using
an association identification by setting the sinfo.sinfo_flags to
MSG_EOF and the sinfo.sinf_associd to the association that needs to
be terminated. In such a case the len of the message would be zero.
9. Preprocessor Constants 9. Preprocessor Constants
For application portability it is desireable to define pre-processor For application portability it is desireable to define pre-processor
constants for determination if sctp is present and supports various constants for determination if sctp is present and supports various
features. The following pre-processor constants should be defined in features. The following pre-processor constants should be defined in
a include file, sctp.h. a include file, sctp.h.
HAVE_SCTP - If this constant is defined to 1, then an implementation HAVE_SCTP - If this constant is defined to 1, then an implementation
of SCTP is available. of SCTP is available.
skipping to change at page 67, line 32 skipping to change at page 71, line 32
Jonathan Wood Jonathan Wood
DoCoMo USA Labs DoCoMo USA Labs
181 Metro Drive, Suite 300 181 Metro Drive, Suite 300
San Jose, CA 95110 San Jose, CA 95110
USA USA
Phone: Phone:
EMail: jonwood@speakeasy.net EMail: jonwood@speakeasy.net
Kacheong Poon Kacheong Poon
Consultant Sun Microsystems, Inc.
4150 Network Circle
Milpitas, CA Santa Clara, CA 95054
USA
Phone: Phone:
EMail: kcpoon@yahoo.com EMail: kacheong.poon@sun.com
Ken Fujita Ken Fujita
NEC USA, Inc. NEC USA, Inc.
10080 Wolfe Road, Suite SW3-350 10080 Wolfe Road, Suite SW3-350
Cupertino, CA 95014 Cupertino, CA 95014
USA USA
Phone: Phone:
EMail: fken@ccrl.sj.nec.com EMail: fken@ccrl.sj.nec.com
Michael Tuexen Michael Tuexen
skipping to change at page 77, line 29 skipping to change at page 81, line 29
be obtained from the IETF Secretariat. be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive this standard. Please address the information to the IETF Executive
Director. Director.
Full Copyright Statement Full Copyright Statement
Copyright (C) The Internet Society (2003). All Rights Reserved. Copyright (C) The Internet Society (2004). All Rights Reserved.
This document and translations of it may be copied and furnished to This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of Internet organizations, except as needed for the purpose of
skipping to change at page 78, line 7 skipping to change at page 82, line 7
The limited permissions granted above are perpetual and will not be The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees. revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is currently provided by the
Internet Society. Internet Society.
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/