draft-ietf-tsvwg-sctpsocket-02.txt   draft-ietf-tsvwg-sctpsocket-03.txt 
Network Working Group R. R. Stewart Network Working Group R. R. Stewart
INTERNET-DRAFT Cisco INTERNET-DRAFT Cisco
Q. Xie Q. Xie
L Yarroll L Yarroll
Motorola Motorola
J. Wood J. Wood
DoCoMo USA Labs
K. Poon K. Poon
Sun Microsystems Sun Microsystems
K. Fujita K. Fujita
NEC NEC
expires in six months November 19, 2001 expires in six months January 29, 2002
Sockets API Extensions for SCTP Sockets API Extensions for SCTP
<draft-ietf-tsvwg-sctpsocket-02.txt> <draft-ietf-tsvwg-sctpsocket-03.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]. Internet-Drafts are all provisions of Section 10 of [RFC2026]. Internet-Drafts are
working documents of the Internet Engineering Task Force (IETF), its working documents of the Internet Engineering Task Force (IETF), its
areas, and its working groups. Note that other groups may also areas, and its working groups. Note that other groups may also
distribute working documents as Internet-Drafts. distribute working documents as Internet-Drafts.
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
skipping to change at page 1, line 52 skipping to change at page 1, line 53
1. Introduction............................................ 3 1. Introduction............................................ 3
2. Conventions............................................. 4 2. Conventions............................................. 4
2.1 Data Types............................................ 4 2.1 Data Types............................................ 4
3. UDP-style Interface..................................... 4 3. UDP-style Interface..................................... 4
3.1 Basic Operation....................................... 4 3.1 Basic Operation....................................... 4
3.1.1 socket() - UDP Style Syntax...................... 5 3.1.1 socket() - UDP Style Syntax...................... 5
3.1.2 bind() - UDP Style Syntax........................ 5 3.1.2 bind() - UDP Style Syntax........................ 5
3.1.3 listen() - UDP Style Syntax...................... 6 3.1.3 listen() - UDP Style Syntax...................... 6
3.1.4 sendmsg() and recvmsg() - UDP Style Syntax....... 7 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax....... 7
3.1.5 close() - UDP Style Syntax....................... 8 3.1.5 close() - UDP Style Syntax....................... 8
3.2 Implicit Association Setup............................ 8 3.1.6 connect() - UDP Style Syntax..................... 8
3.2 Implicit Association Setup............................ 9
3.3 Non-blocking mode..................................... 9 3.3 Non-blocking mode..................................... 9
4. TCP-style Interface.....................................10 4. TCP-style Interface.....................................10
4.1 Basic Operation.......................................10 4.1 Basic Operation.......................................10
4.1.1 socket() - TCP Style Syntax........................10 4.1.1 socket() - TCP Style Syntax........................11
4.1.2 bind() - TCP Style Syntax..........................11 4.1.2 bind() - TCP Style Syntax..........................11
4.1.3 listen() - TCP Style Syntax........................12 4.1.3 listen() - TCP Style Syntax........................12
4.1.4 accept() - TCP Style Syntax........................12 4.1.4 accept() - TCP Style Syntax........................13
4.1.5 connect() - TCP Style Syntax.......................12 4.1.5 connect() - TCP Style Syntax.......................13
4.1.6 close() - TCP Style Syntax.........................13 4.1.6 close() - TCP Style Syntax.........................14
4.1.7 shutdown() - TCP Style Syntax......................13 4.1.7 shutdown() - TCP Style Syntax......................14
4.1.8 sendmsg() and recvmsg() - TCP Style Syntax.........14 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax.........15
4.1.9 getsockname() .....................................15 4.1.9 getpeername() .....................................15
4.1.10 getpeername() ....................................15
5. Data Structures..........................................16 5. Data Structures..........................................16
5.1 The msghdr and cmsghdr Structures......................16 5.1 The msghdr and cmsghdr Structures......................16
5.2 SCTP msg_control Structures............................17 5.2 SCTP msg_control Structures............................17
5.2.1 SCTP Initiation Structure (SCTP_INIT)...............18 5.2.1 SCTP Initiation Structure (SCTP_INIT)...............17
5.2.2 SCTP Header Information Structure (SCTP_SNDRCV).....19 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV).....19
5.3 SCTP Events and Notifications..........................21 5.3 SCTP Events and Notifications..........................21
5.3.1 SCTP Notification Structure.........................21 5.3.1 SCTP Notification Structure.........................21
5.3.1.1 SCTP_ASSOC_CHANGE................................22 5.3.1.1 SCTP_ASSOC_CHANGE................................23
5.3.1.2 SCTP_PEER_ADDR_CHANGE............................24 5.3.1.2 SCTP_PEER_ADDR_CHANGE............................24
5.3.1.3 SCTP_REMOTE_ERROR................................25 5.3.1.3 SCTP_REMOTE_ERROR................................25
5.3.1.4 SCTP_SEND_FAILE..................................26 5.3.1.4 SCTP_SEND_FAILED.................................26
5.3.1.5 SCTP_SHUTDOWN_EVENT..............................27 5.3.1.5 SCTP_SHUTDOWN_EVENT..............................27
5.3.1.6 SCTP_ADAPTION_INDICATION.........................28 5.3.1.6 SCTP_ADAPTION_INDICATION.........................28
5.4 Ancillary Data Considerations and Semantics...........29 5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT......................29
5.4.1 Multiple Items and Ordering........................29 5.4 Ancillary Data Considerations and Semantics...........30
5.4.2 Accessing and Manipulating Ancillary Data..........29 5.4.1 Multiple Items and Ordering........................30
5.4.2 Accessing and Manipulating Ancillary Data..........30
5.4.3 Control Message Buffer Sizing......................30 5.4.3 Control Message Buffer Sizing......................30
6. Common Operations for Both Styles.......................30 6. Common Operations for Both Styles.......................31
6.1 send(), recv(), sendto(), recvfrom()..................30 6.1 send(), recv(), sendto(), recvfrom()..................31
6.2 setsockopt(), getsockopt()............................31 6.2 setsockopt(), getsockopt()............................32
6.3 read() and write()....................................32 6.3 read() and write()....................................33
7. Socket Options..........................................32 6.4 getsockname().........................................33
7.1 Read / Write Options..................................32 7. Socket Options..........................................33
7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO)...32 7.1 Read / Write Options..................................36
7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO)...36
7.1.2 Association Retransmission Parameter 7.1.2 Association Retransmission Parameter
(SCTP_ASSOCRTXINFO)................................33 (SCTP_ASSOCRTXINFO)................................36
7.1.3 Initialization Parameters (SCTP_INITMSG)...........34 7.1.3 Initialization Parameters (SCTP_INITMSG)...........37
7.1.4 SO_LINGER..........................................34 7.1.4 SO_LINGER..........................................37
7.1.5 SO_NODELAY.........................................34 7.1.5 SO_NODELAY.........................................37
7.1.6 SO_RCVBUF..........................................34 7.1.6 SO_RCVBUF..........................................37
7.1.7 SO_SNDBUF..........................................35 7.1.7 SO_SNDBUF..........................................37
7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE)...35 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE)...39
7.1.9 SCTP_SET_PRIMARY_ADDR..............................35 7.1.9 SCTP_SET_PRIMARY_ADDR..............................39
7.1.10 SCTP_SET_PEER_PRIMARY_ADDR........................35 7.1.10 SCTP_SET_PEER_PRIMARY_ADDR........................39
7.1.11 Set Adaption Layer Bits...........................36 7.1.11 Set Adaption Layer Bits...........................39
7.2 Read-Only Options.....................................36 7.1.12 Set default message time outs
7.2.1 Association Status (SCTP_STATUS)...................36 (SCTP_SET_STREAM_TIMEOUTS)........................40
7.3. Ancillary Data and Notification Interest Options.....37 7.1.13 Enable/Disable message fragmentation
8. New Interfaces..........................................38 (SCTP_DISABLE_FRAGMENTS)..........................40
8.1 sctp_bindx()..........................................38 7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS
8.2 Branched-off Association, sctp_peeloff()..............39 /SCTP_GET_PEER_ADDR_PARAMS)....40
8.3 sctp_getpaddrs()......................................39 7.2 Read-Only Options.....................................41
8.4 sctp_freepaddrs().....................................40 7.2.1 Association Status (SCTP_STATUS)...................41
8.5 sctp_getladdrs()......................................40 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO).42
8.6 sctp_freeladdrs().....................................40 7.3. Ancillary Data and Notification Interest Options.....43
8.7 sctp_opt_info().......................................41 8. New Interfaces..........................................45
8.7.1 Peer Address Parameters............................41 8.1 sctp_bindx()..........................................45
8.7.2 Peer Address Information...........................42 8.2 Branched-off Association, sctp_peeloff()..............46
9. Security Considerations.................................42 8.3 sctp_getpaddrs()......................................47
10. Acknowledgements......................................43 8.4 sctp_freepaddrs().....................................47
11. Authors' Addresses....................................43 8.5 sctp_getladdrs()......................................47
12. References............................................44 8.6 sctp_freeladdrs().....................................48
Appendix A: TCP-style Code Example.........................44 9. Security Considerations.................................48
Appendix B: UDP-style Code Example.........................49 10. Acknowledgements......................................48
11. Authors' Addresses....................................48
12. References............................................49
Appendix A: TCP-style Code Example.........................50
Appendix B: UDP-style Code Example.........................54
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] and UDP Protocol suite to many operating systems. Both TCP [RFC793] and UDP
[RFC768] have benefited from this standard representation and access [RFC768] have benefited from this standard representation and access
method across many diverse platforms. SCTP is a new protocol that method across many diverse platforms. SCTP is a new protocol that
provides many of the characteristics of TCP but also incorporates provides many of the characteristics of TCP but also incorporates
semantics more akin to UDP. This document defines a method to map semantics more akin to UDP. This document defines a method to map
the existing sockets API for use with SCTP, providing both a base the existing sockets API for use with SCTP, providing both a base
skipping to change at page 8, line 47 skipping to change at page 8, line 53
sd - the socket descriptor of the associations to be closed. sd - the socket descriptor of the associations to be closed.
To gracefully shutdown a specific association represented by the To gracefully shutdown a specific association represented by the
UDP-style socket, an application should use the sendmsg() call, UDP-style socket, an application should use the sendmsg() call,
passing no user data, but including the MSG_EOF flag in the passing no user data, but including the MSG_EOF flag in the
ancillary data (see Section 5.2.2). ancillary data (see Section 5.2.2).
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() - UDP Style Syntax
An application may use the connect() call in the UDP model to
initiate an association without sending data.
The syntax is
ret = connect(int sd, const struct sockaddr *nam, int len);
sd - the socket descriptor to have a new association added
to.
nam - the address structure (either struct sockaddr_in or struct
sockaddr_in6 defined in [RFC 2553]).
len - the size of the address.
3.2 Implicit Association Setup 3.2 Implicit Association Setup
Once all bind() calls are complete on a UDP-style socket, the Once all bind() calls are complete on a UDP-style socket, the
application can begin sending and receiving data using the application can begin sending and receiving data using the
sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going sendmsg()/recvmsg() or sendto()/recvfrom() calls, without going
through any explicit association setup procedures (i.e., no through any explicit association setup procedures (i.e., no
connect() calls required). connect() calls 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 finds that there is no association existing between the
skipping to change at page 15, line 11 skipping to change at page 15, line 36
address, the SCTP stack will fill in the msg_name field on return so address, the SCTP stack will fill in the msg_name field on return so
that the application can retrieve the source address information of that the application can retrieve the source address information of
the received message. the received message.
2) An application must use close() to gracefully shutdown an 2) An application must use close() to gracefully shutdown an
association, or use SO_LINGER option with close() to abort an association, or use SO_LINGER option with close() to abort an
association. It must not use the MSG_ABORT or MSG_EOF flag in association. It must not use the MSG_ABORT or MSG_EOF flag in
sendmsg(). The system returns an error if an application tries to sendmsg(). The system returns an error if an application tries to
do so. do so.
4.1.9 getsockname() 4.1.9 getpeername()
Applications use getsockname() to retrieve the locally-bound socket
address of the specified socket. This is especially useful if the
caller let SCTP chose a local port. This call is for where the
endpoint is not multihomed. It does not work well with multi-homed
sockets. See section 8.5 for a multihomed version of the call.
The syntax is:
int getsockname(int socket, struct sockaddr *address,
socklen_t *len);
sd - the socket descriptor to be queried.
address - On return, one locally bound address (chosen by
the SCTP stack) is stored in this buffer. If the
socket is an IPv4 socket, the address will be IPv4.
If the socket is an IPv6 socket, the address will
be either an IPv6 or mapped IPv4 address.
len - The caller should set the length of address here.
On return, this is set to the length of the returned
address.
If the actual length of the address is greater than the length of
the supplied sockaddr structure, the stored address will be
truncated.
If the socket has not been bound to a local name, the value stored
in the object pointed to by address is unspecified.
4.1.10 getpeername()
Applications use getpeername() to retrieve the primary socket Applications use getpeername() to retrieve the primary socket
address of the peer. This call is for TCP compatibility, and is not address of the peer. This call is for TCP compatibility, and is not
multihomed.It does not work with UDP-style sockets. See section 8.3 multihomed.It does not work with UDP-style sockets. See section 8.3
for a multihomed/UDP-sockets version of the call. for a multihomed/UDP-sockets version of the call.
The syntax is: The syntax is:
int getpeername(int socket, struct sockaddr *address, int getpeername(int socket, struct sockaddr *address,
socklen_t *len); socklen_t *len);
skipping to change at page 19, line 30 skipping to change at page 19, line 24
Here is the defintion of sctp_sndrcvinfo: Here is the defintion of sctp_sndrcvinfo:
struct sctp_sndrcvinfo { struct sctp_sndrcvinfo {
uint16_t sinfo_stream; uint16_t sinfo_stream;
uint16_t sinfo_ssn; uint16_t sinfo_ssn;
uint16_t sinfo_flags; uint16_t sinfo_flags;
uint32_t sinfo_ppid; uint32_t sinfo_ppid;
uint32_t sinfo_context; uint32_t sinfo_context;
uint32_t sinfo_timetolive; uint32_t sinfo_timetolive;
uint32_t sinfo_tsn;
sctp_assoc_t sinfo_assoc_id; sctp_assoc_t sinfo_assoc_id;
}; };
sinfo_stream: 16 bits (unsigned integer) sinfo_stream: 16 bits (unsigned integer)
For recvmsg() the SCTP stack places the message's stream number in For recvmsg() the SCTP stack places the message's stream number in
this value. For sendmsg() this value holds the stream number that this value. For sendmsg() this value holds the stream number that
the application wishes to send this message to. If a sender the application wishes to send this message to. If a sender
specifies an invalid stream number an error indication is returned specifies an invalid stream number an error indication is returned
and the call fails. and the call fails.
skipping to change at page 20, line 52 skipping to change at page 20, line 45
endpoints is successfully transmitted before closing endpoints is successfully transmitted before closing
the association (UDP-style only). the association (UDP-style only).
sinfo_timetolive: 32 bit (unsigned integer) sinfo_timetolive: 32 bit (unsigned integer)
For the sending side, this field contains the message time For the sending side, this field contains the message time
to live in milliseconds. The sending side wil expire the to live in milliseconds. The sending side wil expire the
message within the specified time period if the message as message within the specified time period if the message as
not been sent to the peer within this time period. not been sent to the peer within this time period.
sinfo_tsn: 32 bit (unsigned integer)
For the receiving side, this field holds a TSN that was
assigned to one of the SCTP Data Chunks.
sinfo_assoc_id: sizeof (sctp_assoc_t) sinfo_assoc_id: sizeof (sctp_assoc_t)
The association handle field, sinfo_assoc_id, holds the identifier The association handle field, sinfo_assoc_id, holds the identifier
for the association announced in the COMMUNICATION_UP notification. for the association announced in the COMMUNICATION_UP notification.
All notifications for a given association have the same identifier. All notifications for a given association have the same identifier.
Ignored for TCP-style sockets. Ignored for TCP-style sockets.
A sctp_sndrcvinfo item always corresponds to the data in msg_iov. A sctp_sndrcvinfo item always corresponds to the data in msg_iov.
5.3 SCTP Events and Notifications 5.3 SCTP Events and Notifications
skipping to change at page 21, line 53 skipping to change at page 21, line 51
struct { struct {
uint16_t sn_type; /* Notification type. */ uint16_t sn_type; /* Notification type. */
uint16_t sn_flags; uint16_t sn_flags;
uint32_t sn_length; uint32_t sn_length;
} h; } h;
struct sctp_assoc_change sn_assoc_change; struct sctp_assoc_change sn_assoc_change;
struct sctp_paddr_change sn_padr_change; struct sctp_paddr_change sn_padr_change;
struct sctp_remote_error sn_remote_error; struct sctp_remote_error sn_remote_error;
struct sctp_send_failed sn_send_failed; struct sctp_send_failed sn_send_failed;
struct sctp_shutdown_event sn_shutdown_event; struct sctp_shutdown_event sn_shutdown_event;
struct sctp_adaption_event sn_adaption_event;
struct sctp_rcv_pdapi_event sn_rcv_pdapi_event;
}; };
sn_type: 16 bits (unsigned integer) sn_type: 16 bits (unsigned integer)
The following table describes the SCTP notification and event types The following table describes the SCTP notification and event types
for the field sn_type. for the field sn_type.
sn_type Description sn_type Description
--------- --------------------------- --------- ---------------------------
SCTP_ASSOC_CHANGE This tag indicates that an SCTP_ASSOC_CHANGE This tag indicates that an
association has either been association has either been
opened or closed. Refer to opened or closed. Refer to
5.3.1.1 for details. 5.3.1.1 for details.
skipping to change at page 22, line 41 skipping to change at page 22, line 43
This structure includes the This structure includes the
original SCTP_SNDRCVINFO original SCTP_SNDRCVINFO
that was used in sending this that was used in sending this
message i.e. this structure message i.e. this structure
uses the sctp_sndrecvinfo per uses the sctp_sndrecvinfo per
section 5.3.1.4. section 5.3.1.4.
SCTP_SHUTDOWN_EVENT The peer has sent a SHUTDOWN. No further SCTP_SHUTDOWN_EVENT The peer has sent a SHUTDOWN. No further
data should be sent on this socket. data should be sent on this socket.
SCTP_ADAPTION_INDICATION This notification holds the
peers indicated adaption layer.
Please see 5.3.1.6.
SCTP_PARTIAL_DELIVERY_EVENT This notitifcation is used to
tell a receiver that the partial
delivery has been aborted. This
may indicate the association is
about to be aborted. Please see
5.3.1.7.
All standard values for sn_type flags are greater than 2^15. All standard values for sn_type flags are greater than 2^15.
Values from 2^15 and down are reserved. Values from 2^15 and down are reserved.
sn_flags: 16 bits (unsigned integer) sn_flags: 16 bits (unsigned integer)
These are notification-specific flags. These are notification-specific flags.
sn_length: 32 bits (unsigned integer) sn_length: 32 bits (unsigned integer)
This is the length of the whole sctp_notification structure This is the length of the whole sctp_notification structure
skipping to change at page 27, line 46 skipping to change at page 28, line 6
5.3.1.5 SCTP_SHUTDOWN_EVENT 5.3.1.5 SCTP_SHUTDOWN_EVENT
When a peer sends a SHUTDOWN, SCTP delivers this notification to When a peer sends a SHUTDOWN, SCTP delivers this notification to
inform the application that it should cease sending data. inform the application that it should cease sending data.
struct sctp_shutdown_event { struct sctp_shutdown_event {
uint16_t sse_type; uint16_t sse_type;
uint16_t sse_flags; uint16_t sse_flags;
uint32_t sse_length; uint32_t sse_length;
uint16_t sse_flags;
sctp_assoc_t sse_assoc_id; sctp_assoc_t sse_assoc_id;
}; };
sse_type sse_type
It should be SCTP_SHUTDOWN_EVENT It should be SCTP_SHUTDOWN_EVENT
sse_flags: 16 bits (unsigned integer) sse_flags: 16 bits (unsigned integer)
Currently unused. Currently unused.
skipping to change at page 29, line 4 skipping to change at page 29, line 15
the notification header. It will generally be the notification header. It will generally be
sizeof (struct sctp_adaption_event). sizeof (struct sctp_adaption_event).
sai_adaption_bits: 32 bits (unsigned integer) sai_adaption_bits: 32 bits (unsigned integer)
This field holds the bit array sent by the peer in the This field holds the bit array sent by the peer in the
adaption layer indication parameter. The bits are in adaption layer indication parameter. The bits are in
network byte order. network byte order.
sai_assoc_id: sizeof (sctp_assoc_t) sai_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association. The association id field, holds the identifier for the association.
All notifications for a given association have the same association All notifications for a given association have the same association
identifier. For TCP style socket, this field is ignored. identifier. For TCP style socket, this field is ignored.
5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT
When a reciever is engaged in a partial delivery of a
message this notification will be used to inidicate
various events.
struct sctp_rcv_pdapi_event {
uint16_t pdapi_type;
uint16_t pdapi_flags;
uint32_t pdapi_length;
uint32_t pdapi_indication;
sctp_assoc_t pdapi_assoc_id;
};
pdapi_type
It should be SCTP_ADAPTION_INDICATION
pdapi_flags: 16 bits (unsigned integer)
Currently unused.
pdapi_length: 32 bits (unsigned integer)
This field is the total length of the notification data, including
the notification header. It will generally be
sizeof (struct sctp_rcv_pdapi_event).
pdapi_indication: 32 bits (unsigned integer)
This field holds the indication being sent to the
application possible values include:
SCTP_PARTIAL_DELIVERY_ABORTED
pdapi_assoc_id: sizeof (sctp_assoc_t)
The association id field, holds the identifier for the association.
All notifications for a given association have the same association
identifier. For TCP style socket, this field is ignored.
5.4 Ancillary Data Considerations and Semantics 5.4 Ancillary Data Considerations and Semantics
Programming with ancillary socket data contains some subtleties and Programming with ancillary socket data contains some subtleties and
pitfalls, which are discussed below. pitfalls, which are discussed below.
5.4.1 Multiple Items and Ordering 5.4.1 Multiple Items and Ordering
Multiple ancillary data items may be included in any call to Multiple ancillary data items may be included in any call to
sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP sendmsg() or recvmsg(); these may include multiple SCTP or non-SCTP
items, or both. items, or both.
skipping to change at page 31, line 45 skipping to change at page 32, line 45
combining them. recv() and recvfrom() cannot distinguish message combining them. recv() and recvfrom() cannot distinguish message
boundaries. boundaries.
In receiving, if the buffer supplied is not large enough to hold a In receiving, if the buffer supplied is not large enough to hold a
complete message, the receive call acts like a stream socket and complete message, the receive call acts like a stream socket and
returns as much data as will fit in the buffer. returns as much data as will fit in the buffer.
Note, the send and recv calls, when used in the UDP-style model, may Note, the send and recv calls, when used in the UDP-style model, may
only be used with branched off socket descriptors (see Section 8.2). only be used with branched off socket descriptors (see Section 8.2).
Note, if an application calls a send function with no user data
and no ancillary data the SCTP implementation should reject the
request with an appropriate error message. An implementation is
NOT allowed to send a Data chunk with no user data [RFC2960].
6.2 setsockopt(), getsockopt() 6.2 setsockopt(), getsockopt()
Applications use setsockopt() and getsockopt() to set or retrieve Applications use setsockopt() and getsockopt() to set or retrieve
socket options. Socket options are used to change the default socket options. Socket options are used to change the default
behavior of sockets calls. They are described in Section 7. behavior of sockets calls. They are described in Section 7.
The syntax is: The syntax is:
ret = getsockopt(int sd, int level, int optname, void *optval, ret = getsockopt(int sd, int level, int optname, void *optval,
size_t *optlen); size_t *optlen);
skipping to change at page 32, line 20 skipping to change at page 33, line 26
6.3 read() and write() 6.3 read() and write()
Applications can use read() and write() to send and receive data to Applications can use read() and write() to send and receive data to
and from peer. They have the same semantics as send() and recv() and from peer. They have the same semantics as send() and recv()
except that the flags parameter cannot be used. except that the flags parameter cannot be used.
Note, these calls, when used in the UDP-style model, may only be Note, these calls, when used in the UDP-style model, may only be
used with branched off socket descriptors (see Section 8.2). used with branched off socket descriptors (see Section 8.2).
7. Socket Options 6.4 getsockname()
Applications use getsockname() to retrieve the locally-bound socket
address of the specified socket. This is especially useful if the
caller let SCTP chose a local port. This call is for where the
endpoint is not multihomed. It does not work well with multi-homed
sockets. See section 8.5 for a multihomed version of the call.
The syntax is:
int getsockname(int socket, struct sockaddr *address,
socklen_t *len);
sd - the socket descriptor to be queried.
address - On return, one locally bound address (chosen by
the SCTP stack) is stored in this buffer. If the
socket is an IPv4 socket, the address will be IPv4.
If the socket is an IPv6 socket, the address will
be either an IPv6 or mapped IPv4 address.
len - The caller should set the length of address here.
On return, this is set to the length of the returned
address.
If the actual length of the address is greater than the length of
the supplied sockaddr structure, the stored address will be
truncated.
If the socket has not been bound to a local name, the value stored
in the object pointed to by address is unspecified.
7. Socket Options
The following sub-section describes various SCTP level socket The following sub-section describes various SCTP level socket
options that are common to both models. SCTP associations can be options that are common to both models. SCTP associations can be
multihomed. Therefore, certain option parameters include a multihomed. 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 UDP-style sockets, an sctp_assoc_t structure (association For the UDP-style sockets, an sctp_assoc_t structure (association
ID) is used to identify the the association instance that the ID) is used to identify the the association instance that the
operation affects. So it must be set when using this model. operation affects. So it must be set when using this model.
skipping to change at page 32, line 49 skipping to change at page 34, line 31
does this, it should also specify an appropriate optlen value does this, it should also specify an appropriate optlen value
(i.e. sizeof (option parameter) - sizeof (struct sctp_assoc_t)). (i.e. sizeof (option parameter) - sizeof (struct sctp_assoc_t)).
Note that socket or IP level options is set or retrieved per socket. Note that socket or IP level options is set or retrieved per socket.
This means that for UDP-style sockets, those options will be applied This means that for UDP-style sockets, those options will be applied
to all associations belonging to the socket. And for TCP-style to all associations belonging to the socket. And for TCP-style
model, those options will be applied to all peer addresses of the model, those options will be applied to all peer addresses of the
association controlled by the socket. Applications should be very association controlled by the socket. Applications should be very
careful in setting those options. careful in setting those options.
sctp_opt_info()
For some implementations getsockopt() is read-only, so a new
interface will be needed when information must be passed both in
to and out of the SCTP stack. The syntax for scpt_opt_info() is,
int sctp_opt_info(int sd,
sctp_assoc_t id,
int opt,
void *arg,
size_t *size);
For UDP-style sockets, id specifies the association to query. For
TCP-style sockets, id is ignored.
opt specifies which SCTP socket option to get. It can
any socket option currently supported that requests information
(either read/write options or read only) such as:
SCTP_RTOINFO
SCTP_ASSOCINFO
SCTP_SET_PRIMARY_ADDR
SCTP_SET_PEER_PRIMARY_ADDR
SCTP_SET_STREAM_TIMEOUTS
SCTP_SET_PEER_ADDR_PARAMS
SCTP_GET_PEER_ADDR_PARAMS
SCTP_STATUS
SCTP_GET_PEER_ADDR_INFO
arg is an option-specific structure buffer provided by the caller.
See 8.5 subsections for more information on these options and
option-specific structures.
sctp_opt_info() returns 0 on success, or on failure returns -1 and
sets errno to the appropriate error code.
For those implementations that DO support a read/write
getsocketopt interface a simple macro wrapper can be
created to support the sctp_opt_info() interface such as:
#define sctp_opt_info(fd,asoc,opt,arg,sz) \
do { \
if((opt == SCTP_RTOINFO) || \
(opt == SCTP_ASSOCINFO) || \
(opt == SCTP_SET_PRIMARY_ADDR) || \
(opt == SCTP_SET_PEER_PRIMARY_ADDR) || \
(opt == SCTP_SET_STREAM_TIMEOUTS) || \
(opt == SCTP_SET_PEER_ADDR_PARAMS) || \
(opt == SCTP_GET_PEER_ADDR_PARAMS) || \
(opt == SCTP_STATUS) || \
(opt == SCTP_GET_PEER_ADDR_INFO)){ \
*(sctp_assoc_t *)arg = asoc; \
return(getsockopt(fd,IPPROTO_SCTP,opt,arg,sz)); \
}else{ \
return(ENOTSUP); \
} \
}while(0);
All options that support specific settings on an association
by filling in either an association id variable or a
sockaddr_storage SHOULD also support setting of the same
value for the entire endpoint (i.e. future associations).
To accomplish this the following logic is used when
setting one of these options:
a) If an address is specified via a sockaddr_storage that
is included in the structure the address is used to
lookup the association and the settings are applied to
the specific address (if appropriate) or to the entire
association.
b) If an association identification is filled in but not a
sockaddr_storage (if present) the association is found
using the association identification and the settings
should be applied to the entire association (since a specific
address is specified). Note this also applies to options that
hold an association identification in their structure but do not
have a sockaddr_storage field.
c) If neither the sockaddr_storage or association identification is set
i.e. the sockadd_storage is set to all 0's (INADDR_ANY) and the
association identification is 0, the settings are a default and
to be applied to the endpoint (all future associations).
7.1 Read / Write Options 7.1 Read / Write Options
7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO)
The protocol parameters used to initialize and bound retransmission The protocol parameters used to initialize and bound retransmission
timeout (RTO) are tunable. See [SCTP] for more information on how timeout (RTO) are tunable. See [SCTP] for more information on how
these parameters are used in RTO calculation. The peer address these parameters are used in RTO calculation. The peer address
parameter is ignored for TCP style socket. parameter is ignored for TCP style socket.
The following structure is used to access and modify these The following structure is used to access and modify these
parameters: parameters:
struct sctp_rtoinfo { struct sctp_rtoinfo {
sctp_assoc_t srto_assoc_id;
uint32_t srto_initial; uint32_t srto_initial;
uint32_t srto_max; uint32_t srto_max;
uint32_t srto_min; uint32_t srto_min;
sctp_assoc_t srto_assoc_id;
}; };
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 minumum bounds srto_max and srto_min - These contain the maximum and minumum bounds
for all RTOs. for all RTOs.
srto_assoc_id - (UDP style socket) This is filled in the application, srto_assoc_id - (UDP style socket) This is filled in the application,
and identifies the association for this query. If and identifies the association for this query. If
this parameter is missing (on a UDP style socket), this parameter is missing (on a UDP style socket),
then the change effects the entire endpoint. then the change effects the entire endpoint.
All parameters are time values, in milliseconds. A value of 0, when All parameters are time values, in milliseconds. A value of 0, when
modifying the parameters, indicates that the current value should modifying the parameters, indicates that the current value should
not be changed. not be 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.
7.1.2 Association Retransmission Parameter (SCTP_ASSOCRTXINFO) 7.1.2 Association Parameters (SCTP_ASSOCINFO)
This option is used to both examine and set various association
and endpoint parameters.
The protocol parameter used to set the number of retransmissions
sent before an association is considered unreachable.
See [SCTP] for more information on how this parameter is used. The See [SCTP] for more information on how this parameter is used. The
peer address parameter is ignored for TCP style socket. peer address parameter is ignored for TCP style socket.
The following structure is used to access and modify this The following structure is used to access and modify this
parameters: parameters:
struct sctp_assocparams { struct sctp_assocparams {
uint16_t sasoc_asocmaxrxt;
sctp_assoc_t sasoc_assoc_id; sctp_assoc_t sasoc_assoc_id;
uint16_t sasoc_asocmaxrxt;
uint16_t sasoc_number_peer_destinations;
uint32_t sasoc_peer_rwnd;
uint32_t sasoc_local_rwnd;
uint32_t sasoc_cookie_life;
}; };
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
address that the peer considers
valid.
sasoc_peer_rwnd - This holds the current value of the peers
rwnd (reported in the last SACK) minus any
outstanding data (i.e. data inflight).
sasoc_local_rwnd - This holds the last reported rwnd that was
sent to the peer.
sasoc_cookie_life - This is the associations cookie life value
used when issueing cookies.
sasoc_assoc_id - (UDP style socket) This is filled in the application, sasoc_assoc_id - (UDP style socket) This is filled in the application,
and identifies the association for this query. and identifies the association for this query.
This information may be examined for either the
endpoint or a specific association. To examine a endpoints
default parameters the association id (sasoc_assoc_id) should
must be set to the value '0'. The values of the sasoc_peer_rwnd
is meaningless when examining endpoint information.
The values of the sasoc_asocmaxrxt and sasoc_cookie_life may
be set on either an endpoint or association basis. The
rwnd and destination counts (sasoc_number_peer_destinations,
sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any
value placed in these is ignored.
To access or modify these parameters, the application should call To access or modify these parameters, the application should call
getsockopt or setsockopt() respectively with the option name getsockopt or setsockopt() respectively with the option name
SCTP_ASSOCRTXINFO. SCTP_ASSOCRTXINFO.
The maximum number of retransmissions before an address is The maximum number of retransmissions before an address is
considered unreachable is also tunable, but is address-specific, so considered unreachable is also tunable, but is address-specific, so
it is covered in a seperate option. If an application attempts to it is covered in a seperate option. If an application attempts to
set the value of the association maximum retransmission parameter to set the value of the association maximum retransmission parameter to
more than the sum of all maximum retransmission parameters, more than the sum of all maximum retransmission parameters,
setsockopt() shall return an error. The reason for this, from setsockopt() shall return an error. The reason for this, from
skipping to change at page 35, line 39 skipping to change at page 39, line 27
an association is closed. an association is closed.
7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) 7.1.9 Set Primary Address (SCTP_SET_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_setprim { struct sctp_setprim {
struct sockaddr_storage ssp_addr;
sctp_assoc_t ssp_assoc_id; sctp_assoc_t ssp_assoc_id;
struct sockaddr_storage ssp_addr;
}; };
ssp_addr The address to set as primary ssp_addr The address to set as primary
ssp_assoc_id (UDP style socket) This is filled in by the ssp_assoc_id (UDP style socket) This is filled in by the
application, and identifies the association application, and identifies the association
for this request. for this request.
This functionality is optional. Implementations that do not support This functionality is optional. Implementations that do not support
this functionality should return EOPNOTSUPP. this functionality should return EOPNOTSUPP.
7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR)
Requests that the local SCTP stack use the enclosed peer address as Requests that the local SCTP stack use the enclosed peer address as
the association primary. The enclosed address must be one of the the association primary. The enclosed address must be one of the
association peer's addresses. The following structure is used to association peer's addresses. The following structure is used to
make a set peer primary request: make a set peer primary request:
struct sctp_setpeerprim { struct sctp_setpeerprim {
struct sockaddr_storage sspp_addr;
sctp_assoc_t sspp_assoc_id; sctp_assoc_t sspp_assoc_id;
struct sockaddr_storage sspp_addr;
}; };
sspp_addr The address to set as primary sspp_addr The address to set as primary
sspp_assoc_id (UDP style socket) This is filled in by the sspp_assoc_id (UDP style socket) This is filled in by the
application, and identifies the association application, and identifies the association
for this request. for this request.
7.1.11 Set Adaption Layer Bits (SCTP_SET_ADAPTION_LAYER_BITS) 7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER)
Requests that the local endpoint set the specified Adaption Layer
Requests that the local endpoint set the indicated bits Indication parameter for all future
in its Adaption Layer Indication parameter for all future
INIT and INIT-ACK exchanges. INIT and INIT-ACK exchanges.
struct sctp_setadaption_bits { struct sctp_setadaption {
u_int32_t ssb_bit_array; u_int32_t ssb_adaption_ind;
} }
ssb_bit_array The adaption layer bits that will be included ssb_adaption_ind The adaption layer indicator that will be included
in any outgoing Adaption Layer Indication in any outgoing Adaption Layer Indication
parameter. parameter.
7.1.12 Set default message time outs (SCTP_SET_STREAM_TIMEOUTS)
This option requests that the requested stream apply a
default time-out for messages in queue.
struct sctp_setstrm_timeout {
sctp_assoc_t ssto_assoc_id;
u_int32_t ssto_timeout;
u_int16_t ssto_streamid_start;
u_int16_t ssto_streamid_end;
};
ssto_assoc_id (UDP style socket) This is filled in by the
application, and identifies the association
for this request.
ssto_timeout The maximum time in milliseconds that messages
should be held inqueue before failure.
ssto_streamid_start The beginning stream identifer to apply this
default against.
ssto_streamid_end The ending stream identifer to apply this
default against.
Note that a timeout value of 0 indicates that no inqueue timeout
should be applied against the stream.
7.1.13 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS)
This option is a on/off flag. If enabled no SCTP message
fragmentation will be performed. Instead if a message
being sent exceeds the current PMTU size, the message will
NOT be sent and instead a error will be indicated to the user.
7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS/
SCTP_GET_PEER_ADDR_PARAMS)
Applications can enable or disable heartbeats for any peer address
of an association, modify an address's heartbeat interval, force a
heartbeat to be sent immediately, and adjust the address's maximum
number of retransmissions sent before an address is considered
unreachable. The following structure is used to access and modify an
address's parameters:
struct sctp_paddrparams {
sctp_assoc_t spp_assoc_id;
struct sockaddr_storage spp_address;
uint32_t spp_hbinterval;
uint16_t spp_pathmaxrxt;
};
spp_assoc_id - (UDP style socket) This is filled in the application,
and identifies the association for this query.
spp_address - This specifies which address is of interest.
spp_hbinterval - This contains the value of the heartbeat interval,
in milliseconds. A value of 0, when modifying the
parameter, specifies that the heartbeat on this
address should be disabled. A value of UINT32_MAX
(4294967295), when modifying the parameter,
specifies that a heartbeat should be sent
immediately to the peer address, and the current
interval should remain unchanged.
spp_pathmaxrxt - This contains the maximum number of
retransmissions before this address shall be
considered unreachable.
To modify these parameters, the application should call
sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. To get
these parameters, the application should use
SCTP_GET_PEER_ADDR_PARAMS.
7.2 Read-Only Options 7.2 Read-Only Options
7.2.1 Association Status (SCTP_STATUS) 7.2.1 Association Status (SCTP_STATUS)
Applications can retrieve current status information about an Applications can retrieve current status information about an
association, including association state, peer receiver window size, association, including association state, peer receiver window size,
number of unacked data chunks, and number of data chunks pending number of unacked data chunks, and number of data chunks pending
receipt. This information is read-only. The following structure is receipt. This information is read-only. The following structure is
used to access this information: used to access this information:
struct sctp_status { struct sctp_status {
sctp_assoc_t sstat_assoc_id;
int32_t sstat_state; int32_t sstat_state;
uint32_t sstat_rwnd; uint32_t sstat_rwnd;
uint16_t sstat_unackdata; uint16_t sstat_unackdata;
uint16_t sstat_penddata; uint16_t sstat_penddata;
uint16_t sstat_instrms;
uint16_t sstat_outstrms;
uint32_t sstat_fragmentation_point;
struct sctp_paddrinfo sstat_primary; struct sctp_paddrinfo sstat_primary;
sctp_assoc_t sstat_assoc_id;
}; };
sstat_state - This contains the association's current state one sstat_state - This contains the association's current state one
of the following values: of the following values:
SCTP_CLOSED SCTP_CLOSED
SCTP_BOUND SCTP_BOUND
SCTP_LISTEN SCTP_LISTEN
SCTP_COOKIE_WAIT SCTP_COOKIE_WAIT
SCTP_COOKIE_ECHOED SCTP_COOKIE_ECHOED
skipping to change at page 37, line 18 skipping to change at page 42, line 24
sstat_rwnd - This contains the association peer's current sstat_rwnd - This contains the association peer's current
receiver window size. receiver window size.
sstat_unackdata - This is the number of unacked data chunks. sstat_unackdata - This is the number of unacked data chunks.
sstat_penddata - This is the number of data chunks pending receipt. sstat_penddata - This is the number of data chunks pending receipt.
sstat_primary - This is information on the current primary peer sstat_primary - This is information on the current primary peer
address. address.
sstat_assoc_id - (UDP style socket) This holds the an identifier for the sstat_assoc_id - (UDP style socket) This holds the an identifier for the
association. All notifications for a given association association. All notifications for a given association
have the same association identifier. have the same association identifier.
sstat_instrms - The number of streams that the peer will
be using inbound.
sstat_outstrms - The number of streams that the endpoint is
allowed to use outbound.
sstat_fragmentation_point - The size at which SCTP fragmentation
will occur.
To access these status values, the application calls getsockopt() To access these status values, the application calls getsockopt()
with the option name SCTP_STATUS. The sstat_assoc_id parameter is with the option name SCTP_STATUS. The sstat_assoc_id parameter is
ignored for TCP style socket. ignored for TCP style socket.
7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO)
Applications can retrieve information about a specific peer address
of an association, including its reachability state, congestion
window, and retransmission timer values. This information is
read-only. The following structure is used to access this
information:
struct sctp_paddrinfo {
sctp_assoc_t spinfo_assoc_id;
struct sockaddr_storage spinfo_address;
int32_t spinfo_state;
uint32_t spinfo_cwnd;
uint32_t spinfo_srtt;
uint32_t spinfo_rto;
uint32_t spinfo_mtu;
};
spinfo_address - This is filled in the application, and contains
the peer address of interest.
On return from getsockopt():
spinfo_state - This contains the peer addresses's state (either
SCTP_ACTIVE or SCTP_INACTIVE).
spinfo_cwnd - This contains the peer addresses's current congestion
window.
spinfo_srtt - This contains the peer addresses's current smoothed
round-trip time calculation in milliseconds.
spinfo_rto - This contains the peer addresses's current
retransmission timeout value in milliseconds.
spinfo_mtu - The current P-MTU of this address.
spinfo_assoc_id - (UDP style socket) This is filled in the application,
and identifies the association for this query.
To retrieve this information, use sctp_opt_info() with the
SCTP_GET_PEER_ADDR_INFO options.
7.3. Ancillary Data and Notification Interest Options 7.3. Ancillary Data and Notification Interest Options
Applications can receive per-message ancillary information and Applications can receive per-message ancillary information and
notifications of certain SCTP events with recvmsg(). notifications of certain SCTP events with recvmsg().
The following optional information is available to the application: The following optional information is available to the application:
1. SCTP_RECVDATAIOEVNT: Per-message information (i.e. stream number, 1. SCTP_SNDRCV: Per-message information (i.e. stream number,
TSN, SSN, etc. described in section 5.2.2) TSN, SSN, etc. described in section 5.2.2)
2. SCTP_RECVASSOCEVNT: (described in section 5.3.1.1) 2. SCTP_ASSOC_CHANGE: (described in section 5.3.1.1)
3. SCTP_RECVPADDREVNT: (described in section 5.3.1.2) 3. SCTP_PEER_ADDR_CHANGE: (described in section 5.3.1.2)
4. SCTP_RECVPEERERR: (described in section 5.3.1.3) 4. SCTP_REMOTE_ERROR: (described in section 5.3.1.3)
5. SCTP_RECVSENDFAILEVNT: (described in section 5.3.1.4) 5. SCTP_SEND_FAILED: (described in section 5.3.1.4)
6. SCTP_RECVSHUTDOWNEVNT: (described in section 5.3.1.5) 6. SCTP_SHUTDOWN_EVENT: (described in section 5.3.1.5)
7. SCTP_ADAPTION_INDICATION: (described in section 5.3.1.6) 7. SCTP_ADAPTION_INDICATION: (described in section 5.3.1.6)
8. SCTP_PARTIAL_DELIVERY_EVENT: (described in section 5.3.1.7)
To receive any ancillary data or notifications, first the To receive any ancillary data or notifications, first the
application registers it's interest by calling setsockopt() to turn application registers it's interest by calling the SCTP_SET_EVENTS
on the corresponding flag: setsockopt() with the following structure.
int on = 1; struct sctp_event_subscribe{
u_int8_t sctp_data_io_event;
u_int8_t sctp_association_event;
u_int8_t sctp_address_event;
u_int8_t sctp_send_failure_event;
u_int8_t sctp_peer_error_event;
u_int8_t sctp_shutdown_event;
u_int8_t sctp_partial_delivery_event;
u_int8_t sctp_adaption_layer_event;
};
setsockopt(fd, IPPROTO_SCTP, SCTP_RECVDATAIOEVNT, &on, sizeof(on)); sctp_data_io_event - Setting this flag to 1 will cause the
setsockopt(fd, IPPROTO_SCTP, SCTP_RECVASSOCEVNT, &on, sizeof(on)); reception of SCTP_SNDRCV information on a per message basis.
setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPADDREVNT, &on, sizeof(on)); The application will need to use the recvmsg() interface so
setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSENDFAILEVNT, &on, sizeof(on)); that it can receive the event information contained in the
setsockopt(fd, IPPROTO_SCTP, SCTP_RECVPEERERR, &on, sizeof(on)); msg_control field. Please see section 5.2 for further details.
setsockopt(fd, IPPROTO_SCTP, SCTP_RECVSHUTDOWNEVNT, &on, sizeof(on)); Setting the flag to 0 will disable reception of the message
setsockopt(fd, IPPROTO_SCTP, SCTP_ADAPTION_INDICATION, &on, sizeof(on)); control information.
sctp_association_event - Setting this flag to 1 will enable
the reception of association event notifications. Setting
the flag to 0 will disable association event notifications.
For more information on event notifications please see section
5.3.
sctp_address_event - Setting this flag to 1 will enable
the reception of address event notifications. Setting
the flag to 0 will disable address event notifications.
For more information on event notifications please see section
5.3.
sctp_send_failure_event - Setting this flag to 1 will enable
the reception of send failure event notifications. Setting
the flag to 0 will disable send failure event notifications.
For more information on event notifications please see section
5.3.
sctp_peer_error_event - Setting this flag to 1 will enable
the reception of peer error event notifications. Setting
the flag to 0 will disable peer error event notifications.
For more information on event notifications please see section
5.3.
sctp_shutdown_event - Setting this flag to 1 will enable
the reception of shutdown event notifications. Setting
the flag to 0 will disable shutdown event notifications.
For more information on event notifications please see section
5.3.
sctp_partial_delivery_event - Setting this flag to 1 will enable
the reception of partial delivery notifications. Setting
the flag to 0 will disable partial delivery event notifications.
For more information on event notifications please see section
5.3.
sctp_adaption_layer_event - Setting this flag to 1 will enable
the reception of adaption layer notifications. Setting
the flag to 0 will disable adaption layer event notifications.
For more information on event notifications please see section
5.3.
An example where an application would like to recieve data
io events and association events but no others would be
as follows:
{
struct sctp_event_subscribe event;
memset(&event,0,sizeof(event));
event.sctp_data_io_event = 1;
event.sctp_association_event = 1;
setsockopt(fd, IPPROTO_SCTP, SCTP_SET_EVENT, &event, sizeof(event));
}
Note that for UDP-style SCTP sockets, the caller of recvmsg() Note that for UDP-style SCTP sockets, the caller of recvmsg()
receives ancillary data and notifications for ALL associations bound receives ancillary data and notifications for ALL associations bound
to the file descriptor. For TCP-style SCTP sockets, the caller to the file descriptor. For TCP-style SCTP sockets, the caller
receives ancillary data and notifications for only the single receives ancillary data and notifications for only the single
association bound to the file descriptor. association bound to the file descriptor.
By default a TCP-style socket has all options off. By default a TCP-style socket has all options off.
By default a UDP-style socket has SCTP_RECVDATAIOEVNT and By default a UDP-style socket has sctp_data_io_event and
SCTP_RECVASSOCEVNT on and all other options off. sctp_association_event on and all other options off.
8. New Interfaces 8. New Interfaces
Depending on the system, the following interface can be implemented Depending on the system, the following interface can be implemented
as a system call or library funtion. as a system call or library funtion.
8.1 sctp_bindx() 8.1 sctp_bindx()
The syntax of sctp_bindx() is, The syntax of sctp_bindx() is,
skipping to change at page 38, line 57 skipping to change at page 46, line 19
association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the association, and SCTP_BINDX_REM_ADDR directs SCTP to remove the
given addresses from the association. The two flags are mutually given addresses from the association. The two flags are mutually
exclusive; if both are given, sctp_bindx() will fail with EINVAL. A exclusive; if both are given, sctp_bindx() will fail with EINVAL. A
caller may not remove all addresses from an association; caller may not remove all addresses from an association;
sctp_bindx() will reject such an attempt with EINVAL. sctp_bindx() will reject such an attempt with EINVAL.
An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate An application can use sctp_bindx(SCTP_BINDX_ADD_ADDR) to associate
additional addresses with an endpoint after calling bind(). Or use additional addresses with an endpoint after calling bind(). Or use
sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening sctp_bindx(SCTP_BINDX_REM_ADDR) to remove some addresses a listening
socket is associated with so that no new association accepted will socket is associated with so that no new association accepted will
be associated with those addresses. be associated with those addresses. If the endpoint supports dynamic
address a SCTP_BINDX_REM_ADDR or SCTP_BINDX_ADD_ADDR may cause
a endpoint to send the appropriate message to the peer to
change the peers address lists.
Adding and removing addresses from a connected association is Adding and removing addresses from a connected association is
optional functionality. Implementations that do not support this optional functionality. Implementations that do not support this
functionality should return EOPNOTSUPP. functionality should return EOPNOTSUPP.
8.2 Branched-off Association 8.2 Branched-off Association
After an association is established on a UDP-style socket, the After an association is established on a UDP-style socket, the
application may wish to branch off the association into a separate application may wish to branch off the association into a separate
socket/file descriptor. socket/file descriptor.
skipping to change at page 39, line 27 skipping to change at page 46, line 46
under the original UDP-style socket but branch off those under the original UDP-style socket but branch off those
associations carrying high volume data traffic into their own associations carrying high volume data traffic into their own
separate socket descriptors. separate socket descriptors.
The application uses sctp_peeloff() call to branch off an The application uses sctp_peeloff() call to branch off an
association into a separate socket (Note the semantics are somewhat association into a separate socket (Note the semantics are somewhat
changed from the traditional TCP-style accept() call). changed from the traditional TCP-style accept() call).
The syntax is: The syntax is:
new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id, int *addrlen) new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id)
new_sd - the new socket descriptor representing the branched-off new_sd - the new socket descriptor representing the branched-off
association. association.
sd - the original UDP-style socket descriptor returned from the sd - the original UDP-style socket descriptor returned from the
socket() system call (see Section 3.1.1). socket() system call (see Section 3.1.1).
assoc_id - the specified identifier of the association that is to be assoc_id - the specified identifier of the association that is to be
branched off to a separate file descriptor (Note, in a branched off to a separate file descriptor (Note, in a
traditional TCP-style accept() call, this would be an out traditional TCP-style accept() call, this would be an out
parameter, but for the UDP-style call, this is an in parameter, but for the UDP-style call, this is an in
parameter). parameter).
addrlen - an integer pointer to the size of the sockaddr structure
addr (in a traditional TCP-style call, this would be a out
parameter, but for the UDP-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_storage **addrs); struct sockaddr_storage **addrs);
On return, addrs will point to a dynamically allocated array of On return, addrs will point to a dynamically allocated array of
struct sockaddr_storages, one for each peer address. The caller struct sockaddr_storages, one for each peer address. The caller
skipping to change at page 40, line 47 skipping to change at page 48, line 6
should use sctp_freeladdrs() to free the memory. addrs must not be should use sctp_freeladdrs() to free the memory. addrs must not be
NULL. 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 UDP-style sockets, id specifies the association to query. For For UDP-style sockets, id specifies the association to query. For
TCP-style sockets, id is ignored. TCP-style sockets, id is ignored.
If the id field is set to the value '0' then the locally bound
addresses are returned without regard to any particular association.
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.
8.6 sctp_freeladdrs() 8.6 sctp_freeladdrs()
sctp_freeladdrs() frees all resources allocated by sctp_freeladdrs() frees all resources allocated by
sctp_getladdrs(). Its syntax is, sctp_getladdrs(). Its syntax is,
void sctp_freeladdrs(struct sockaddr_storage *addrs); void sctp_freeladdrs(struct sockaddr_storage *addrs);
addrs is the array of peer addresses returned by sctp_getladdrs().
8.7 sctp_opt_info()
getsockopt() is read-only, so a new interface is required when
information must be passed both in to and out of the SCTP stack. The
syntax for scpt_opt_info() is,
int sctp_opt_info(int sd, sctp_assoc_t id, int opt, void *arg);
For UDP-style sockets, id specifies the association to query. For
TCP-style sockets, id is ignored.
opt specifies which SCTP option to get or set. It can be one of the
following:
SCTP_SET_PEER_ADDR_PARAMS
SCTP_GET_PEER_ADDR_PARAMS
SCTP_GET_PEER_ADDR_INFO
arg is an option-specific structure buffer provided by the caller.
See 8.5 subsections for more information on these options and
option-specific structures.
sctp_opt_info() returns 0 on success, or on failure returns -1 and
sets errno to the appropriate error code.
8.7.1 Peer Address Parameters
Applications can enable or disable heartbeats for any peer address
of an association, modify an address's heartbeat interval, force a
heartbeat to be sent immediately, and adjust the address's maximum
number of retransmissions sent before an address is considered
unreachable. The following structure is used to access and modify an
address's parameters:
struct sctp_paddrparams {
struct sockaddr_storage spp_address;
uint32_t spp_hbinterval;
uint16_t spp_pathmaxrxt;
sctp_assoc_t spp_assoc_id;
};
spp_address - This specifies which address is of interest.
spp_hbinterval - This contains the value of the heartbeat interval,
in milliseconds. A value of 0, when modifying the
parameter, specifies that the heartbeat on this
address should be disabled. A value of UINT32_MAX
(4294967295), when modifying the parameter,
specifies that a heartbeat should be sent
immediately to the peer address, and the current
interval should remain unchanged.
spp_pathmaxrxt - This contains the maximum number of
retransmissions before this address shall be
considered unreachable.
spp_assoc_id - (UDP style socket) This is filled in the application,
and identifies the association for this query.
To modify these parameters, the application should call
sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. To get
these parameters, the application should use
SCTP_GET_PEER_ADDR_PARAMS.
8.7.2 Peer Address Information
Applications can retrieve information about a specific peer address
of an association, including its reachability state, congestion
window, and retransmission timer values. This information is
read-only. The following structure is used to access this
information:
struct sctp_paddrinfo {
struct sockaddr_storage spinfo_address;
int32_t spinfo_state;
uint32_t spinfo_cwnd;
uint32_t spinfo_srtt;
uint32_t spinfo_rto;
sctp_assoc_t spinfo_assoc_id;
};
spinfo_address - This is filled in the application, and contains
the peer address of interest.
On return from getsockopt():
spinfo_state - This contains the peer addresses's state (either
SCTP_ACTIVE or SCTP_INACTIVE).
spinfo_cwnd - This contains the peer addresses's current congestion
window.
spinfo_srtt - This contains the peer addresses's current smoothed
round-trip time calculation in milliseconds.
spinfo_rto - This contains the peer addresses's current
retransmission timeout value in milliseconds.
spinfo_assoc_id - (UDP style socket) This is filled in the application,
and identifies the association for this query.
To retrieve this information, use sctp_opt_info() with the addrs is the array of peer addresses returned by sctp_getladdrs().
SCTP_GET_PEER_ADDR_INFO options.
9. Security Considerations 9. 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() the SCTP implementation SHOULD restrict the ability to call bind()
or sctp_bindx() on these port numbers to privileged users. or sctp_bindx() on these port numbers to privileged users.
Similarly unprivelged users should not be able to set protocol Similarly unprivelged users should not be able to set protocol
parameters which could result in the congestion control algorithm parameters which could result in the congestion control algorithm
skipping to change at page 43, line 20 skipping to change at page 48, line 45
struct sctp_rtoinfo struct sctp_rtoinfo
If an unprivileged user inherits a UDP-style socket with open If an unprivileged user inherits a UDP-style socket with open
associations on a privileged port, it MAY be permitted to accept new associations on a privileged port, it MAY be permitted to accept new
associations, but it SHOULD NOT be permitted to open new associations, but it SHOULD NOT be permitted to open new
associations. This could be relevant for the r* family of associations. This could be relevant for the r* family of
protocols. protocols.
10. Acknowledgements 10. Acknowledgements
The authors wish to thank Mike Bartlett, Jon Berger, Renee Ravis, The authors wish to thank Kavitha Baratakke, Mike Bartlett,
and many others on the TSVWG mailing list for contributing valuable Jon Berger, Scott Kimble, Renee Revis, and many others on
comments. the TSVWG mailing list for contributing valuable comments.
11. Authors' Addresses 11. Authors' Addresses
Randall R. Stewart Tel: +1-815-477-2127 Randall R. Stewart Tel: +1-815-477-2127
Cisco Systems, Inc. EMail: rrs@cisco.com Cisco Systems, Inc. EMail: rrs@cisco.com
Crystal Lake, IL 60012 Crystal Lake, IL 60012
USA USA
Qiaobing Xie Tel: +1-847-632-3028 Qiaobing Xie Tel: +1-847-632-3028
Motorola, Inc. EMail: qxie1@email.mot.com Motorola, Inc. EMail: qxie1@email.mot.com
skipping to change at page 43, line 44 skipping to change at page 49, line 16
Arlington Heights, IL 60004 Arlington Heights, IL 60004
USA USA
La Monte H.P. Yarroll NIC Handle: LY La Monte H.P. Yarroll NIC Handle: LY
Motorola, Inc. EMail: piggy@acm.org Motorola, Inc. EMail: piggy@acm.org
1501 W. Shure Drive, IL27-2315 1501 W. Shure Drive, IL27-2315
Arlington Heights, IL 60004 Arlington Heights, IL 60004
USA USA
Jonathan Wood Jonathan Wood
Sun Microsystems, Inc. Email: jonathan.wood@sun.com DoCoMo USA Labs Email: jonwood@speakeasy.net
901 San Antonio Road 181 Metro Drive, Suite 300
Palo Alto, CA 94303 San Jose, CA 95110
USA USA
Kacheong Poon Kacheong Poon
Sun Microsystems, Inc. Email: kacheong.poon@sun.com Sun Microsystems, Inc. Email: kacheong.poon@sun.com
901 San Antonio Road 901 San Antonio Road
Palo Alto, CA 94303 Palo Alto, CA 94303
USA USA
Ken Fujita Tel: +81-471-82-1131 Ken Fujita Tel: +81-471-82-1131
NEC Corporation Email: fken@cd.jp.nec.com NEC Corporation Email: fken@cd.jp.nec.com
skipping to change at page 44, line 32 skipping to change at page 50, line 4
RFC 2292, February 1998. RFC 2292, February 1998.
[RFC2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens. "Basic Socket [RFC2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens. "Basic Socket
Interface Extensions for IPv6," RFC 2553, March 1999. Interface Extensions for IPv6," RFC 2553, March 1999.
[SCTP] R.R. Stewart, Q. Xie, K. Morneault, C. Sharp, H.J. Schwarzbauer, [SCTP] R.R. Stewart, Q. Xie, K. Morneault, C. Sharp, H.J. Schwarzbauer,
T. Taylor, I. Rytina, M. Kalla, L. Zhang, and, V. Paxson, T. Taylor, I. Rytina, M. Kalla, L. Zhang, and, V. Paxson,
"Stream Control Transmission Protocol," RFC2960, October 2000. "Stream Control Transmission Protocol," RFC2960, October 2000.
[STEVENS] W.R. Stevens, M. Thomas, E. Nordmark, "Advanced Sockets API for [STEVENS] W.R. Stevens, M. Thomas, E. Nordmark, "Advanced Sockets API for
IPv6," <draft-ietf-ipngwg-rfc2292bis-01.txt>, December 1999 IPv6," <draft-ietf-ipngwg-rfc2292bis-03.txt>, November 2001
(Work in progress) (Work in progress)
Appendix A: TCP-style Code Example Appendix A: TCP-style Code Example
The following code is a simple implementation of an echo server over The following code is a simple implementation of an echo server over
SCTP. The example shows how to use some features of TCP-style IPv4 SCTP. The example shows how to use some features of TCP-style IPv4
SCTP sockets, including: SCTP sockets, including:
o Opening, binding, and listening for new associations on a socket; o Opening, binding, and listening for new associations on a socket;
o Enabling ancillary data o Enabling ancillary data
 End of changes. 

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