draft-ietf-tsvwg-sctpsocket-05.txt   draft-ietf-tsvwg-sctpsocket-06.txt 
Network Working Group R. Stewart Network Working Group R. Stewart
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Expires: April 2, 2003 Q. Xie Expires: August 27, 2003 Q. Xie
L. Yarroll L. Yarroll
Motorola, Inc. Motorola, Inc.
J. Wood J. Wood
DoCoMo USA Labs DoCoMo USA Labs
K. Poon K. Poon
Sun Microsystems, Inc. Consultant
K. Fujita K. Fujita
NEC USA, Inc. NEC USA, Inc.
M. Tuexen M. Tuexen
Siemens AG February 26, 2003
October 2, 2002
Sockets API Extensions for Stream Control Transmission Protocol Sockets API Extensions for Stream Control Transmission Protocol
(SCTP) (SCTP)
draft-ietf-tsvwg-sctpsocket-05.txt draft-ietf-tsvwg-sctpsocket-06.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 Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as
Drafts. Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at 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 April 2, 2003. This Internet-Draft will expire on August 27, 2003.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved. Copyright (C) The Internet Society (2003). 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 . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 7 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6
2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6
3. UDP-style Interface . . . . . . . . . . . . . . . . . . . 8 3. UDP-style Interface . . . . . . . . . . . . . . . . . . . 7
3.1 3.1 Basic Operation . . . . . . . . . . . . . . . . . . . 8 3.1 3.1 Basic Operation . . . . . . . . . . . . . . . . . . . 7
3.1.1 socket() - UDP Style Syntax . . . . . . . . . . . . . . . 9 3.1.1 socket() - UDP Style Syntax . . . . . . . . . . . . . . . 8
3.1.2 bind() - UDP Style Syntax . . . . . . . . . . . . . . . . 9 3.1.2 bind() - UDP Style Syntax . . . . . . . . . . . . . . . . 8
3.1.3 listen() - UDP Style Syntax . . . . . . . . . . . . . . . 10 3.1.3 listen() - UDP Style Syntax . . . . . . . . . . . . . . . 9
3.1.4 sendmsg() and recvmsg() - UDP Style Syntax . . . . . . . . 11 3.1.4 sendmsg() and recvmsg() - UDP Style Syntax . . . . . . . . 10
3.1.5 close() - UDP Style Syntax . . . . . . . . . . . . . . . . 12 3.1.5 close() - UDP Style Syntax . . . . . . . . . . . . . . . . 11
3.1.6 connect() - UDP Style Syntax . . . . . . . . . . . . . . . 13 3.1.6 connect() - UDP Style Syntax . . . . . . . . . . . . . . . 12
3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 13 3.2 Implicit Association Setup . . . . . . . . . . . . . . . . 12
3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 14 3.3 Non-blocking mode . . . . . . . . . . . . . . . . . . . . 13
3.4 Special considerations . . . . . . . . . . . . . . . . . . 14 3.4 Special considerations . . . . . . . . . . . . . . . . . . 13
4. TCP-style Interface . . . . . . . . . . . . . . . . . . . 17 4. TCP-style Interface . . . . . . . . . . . . . . . . . . . 16
4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 17 4.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . 16
4.1.1 socket() - TCP Style Syntax . . . . . . . . . . . . . . . 18 4.1.1 socket() - TCP Style Syntax . . . . . . . . . . . . . . . 17
4.1.2 bind() - TCP Style Syntax . . . . . . . . . . . . . . . . 18 4.1.2 bind() - TCP Style Syntax . . . . . . . . . . . . . . . . 17
4.1.3 listen() - TCP Style Syntax . . . . . . . . . . . . . . . 19 4.1.3 listen() - TCP Style Syntax . . . . . . . . . . . . . . . 18
4.1.4 accept() - TCP Style Syntax . . . . . . . . . . . . . . . 19 4.1.4 accept() - TCP Style Syntax . . . . . . . . . . . . . . . 19
4.1.5 connect() - TCP Style Syntax . . . . . . . . . . . . . . . 20 4.1.5 connect() - TCP Style Syntax . . . . . . . . . . . . . . . 19
4.1.6 close() - TCP Style Syntax . . . . . . . . . . . . . . . . 21 4.1.6 close() - TCP Style Syntax . . . . . . . . . . . . . . . . 20
4.1.7 shutdown() - TCP Style Syntax . . . . . . . . . . . . . . 21 4.1.7 shutdown() - TCP Style Syntax . . . . . . . . . . . . . . 20
4.1.8 sendmsg() and recvmsg() - TCP Style Syntax . . . . . . . . 22 4.1.8 sendmsg() and recvmsg() - TCP Style Syntax . . . . . . . . 21
4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 23 4.1.9 getpeername() . . . . . . . . . . . . . . . . . . . . . . 22
5. Data Structures . . . . . . . . . . . . . . . . . . . . . 24 5. Data Structures . . . . . . . . . . . . . . . . . . . . . 23
5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 24 5.1 The msghdr and cmsghdr Structures . . . . . . . . . . . . 23
5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 25 5.2 SCTP msg_control Structures . . . . . . . . . . . . . . . 24
5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 26 5.2.1 SCTP Initiation Structure (SCTP_INIT) . . . . . . . . . . 25
5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 27 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) . . . . . 26
5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 30 5.3 SCTP Events and Notifications . . . . . . . . . . . . . . 29
5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 30 5.3.1 SCTP Notification Structure . . . . . . . . . . . . . . . 29
5.3.1.1 SCTP_ASSOC_CHANGE . . . . . . . . . . . . . . . . . . . . 32 5.4 Ancillary Data Considerations and Semantics . . . . . . . 39
5.3.1.2 SCTP_PEER_ADDR_CHANGE . . . . . . . . . . . . . . . . . . 34 5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 39
5.3.1.3 SCTP_REMOTE_ERROR . . . . . . . . . . . . . . . . . . . . 35 5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 39
5.3.1.4 SCTP_SEND_FAILED . . . . . . . . . . . . . . . . . . . . . 36 5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 40
5.3.1.5 SCTP_SHUTDOWN_EVENT . . . . . . . . . . . . . . . . . . . 38 6. Common Operations for Both Styles . . . . . . . . . . . . 42
5.3.1.6 SCTP_ADAPTION_INDICATION . . . . . . . . . . . . . . . . . 38 6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 42
5.3.1.7 SCTP_PARTIAL_DELIVERY_EVENT . . . . . . . . . . . . . . . 39 6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 43
5.4 Ancillary Data Considerations and Semantics . . . . . . . 40 6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 43
5.4.1 Multiple Items and Ordering . . . . . . . . . . . . . . . 40 6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 43
5.4.2 Accessing and Manipulating Ancillary Data . . . . . . . . 40 7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 45
5.4.3 Control Message Buffer Sizing . . . . . . . . . . . . . . 41 7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 46
6. Common Operations for Both Styles . . . . . . . . . . . . 43 7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 46
6.1 send(), recv(), sendto(), recvfrom() . . . . . . . . . . . 43 7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 47
6.2 setsockopt(), getsockopt() . . . . . . . . . . . . . . . . 44 7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 49
6.3 read() and write() . . . . . . . . . . . . . . . . . . . . 44 7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 49
6.4 getsockname() . . . . . . . . . . . . . . . . . . . . . . 44 7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 49
7. Socket Options . . . . . . . . . . . . . . . . . . . . . . 46 7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 50
7.1 Read / Write Options . . . . . . . . . . . . . . . . . . . 48 7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 50
7.1.1 Retransmission Timeout Parameters (SCTP_RTOINFO) . . . . . 48 7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 50
7.1.2 Association Parameters (SCTP_ASSOCINFO) . . . . . . . . . 49 7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) . . . . . . . 50
7.1.3 Initialization Parameters (SCTP_INITMSG) . . . . . . . . . 50 7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 51
7.1.4 SO_LINGER . . . . . . . . . . . . . . . . . . . . . . . . 50 7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER) . . 51
7.1.5 SCTP_NODELAY . . . . . . . . . . . . . . . . . . . . . . . 51 7.1.12 Enable/Disable message fragmentation
7.1.6 SO_RCVBUF . . . . . . . . . . . . . . . . . . . . . . . . 51 (SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 51
7.1.7 SO_SNDBUF . . . . . . . . . . . . . . . . . . . . . . . . 51 7.1.13 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) . . . 51
7.1.8 Automatic Close of associations (SCTP_AUTOCLOSE) . . . . . 51 7.1.14 Set default send parameters (SET_DEFAULT_SEND_PARAM) . . . 52
7.1.9 Set Primary Address (SCTP_SET_PRIMARY_ADDR) . . . . . . . 51 7.1.15 Set notification and ancillary events (SCTP_SET_EVENTS) . 52
7.1.10 Set Peer Primary Address (SCTP_SET_PEER_PRIMARY_ADDR) . . 52 7.1.16 Set/clear IPv4 mapped addresses
7.1.11 Set Adaption Layer Indicator (SCTP_SET_ADAPTION_LAYER) . . 52 (SCTP_I_WANT_MAPPED_V4_ADDR) . . . . . . . . . . . . . . . 53
7.1.12 Set default message time outs (SCTP_SET_STREAM_TIMEOUTS) . 52 7.1.17 Set the maximum fragrmentation size (SCTP_MAXSEG) . . . . 53
7.1.13 Enable/Disable message fragmentation 7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 53
(SCTP_DISABLE_FRAGMENTS) . . . . . . . . . . . . . . . . . 53 7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 53
7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) . . . 53 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 54
7.1.15 Set default send parameters (SET_DEFAULT_SEND_PARAM) . . . 54 7.3 Ancillary Data and Notification Interest Options . . . . . 55
7.1.16 Set notification and ancillary events (SCTP_SET_EVENTS) . 54 8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 58
7.2 Read-Only Options . . . . . . . . . . . . . . . . . . . . 54 8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 58
7.2.1 Association Status (SCTP_STATUS) . . . . . . . . . . . . . 55 8.2 Branched-off Association . . . . . . . . . . . . . . . . . 59
7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO) . . . . 56 8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 59
7.3 Ancillary Data and Notification Interest Options . . . . . 57 8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 60
8. New Interfaces . . . . . . . . . . . . . . . . . . . . . . 60 8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 60
8.1 sctp_bindx() . . . . . . . . . . . . . . . . . . . . . . . 60 8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 61
8.2 Branched-off Association . . . . . . . . . . . . . . . . . 61 8.7 sctp_sndmsg() . . . . . . . . . . . . . . . . . . . . . . 61
8.3 sctp_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 61 9. Preprocessor Constants . . . . . . . . . . . . . . . . . . 62
8.4 sctp_freepaddrs() . . . . . . . . . . . . . . . . . . . . 62 10. Security Considerations . . . . . . . . . . . . . . . . . 63
8.5 sctp_getladdrs() . . . . . . . . . . . . . . . . . . . . . 62 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 64
8.6 sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 63 References . . . . . . . . . . . . . . . . . . . . . . . . 65
9. Security Considerations . . . . . . . . . . . . . . . . . 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 65
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 65 A. TCP-style Code Example . . . . . . . . . . . . . . . . . . 68
References . . . . . . . . . . . . . . . . . . . . . . . . 66 B. UDP-style Code Example . . . . . . . . . . . . . . . . . . 74
Authors' Addresses . . . . . . . . . . . . . . . . . . . . 66 Intellectual Property and Copyright Statements . . . . . . 76
A. TCP-style Code Example . . . . . . . . . . . . . . . . . . 69
B. UDP-style Code Example . . . . . . . . . . . . . . . . . . 75
Full Copyright Statement . . . . . . . . . . . . . . . . . 77
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 Protocol suite to many operating systems. Both TCP RFC793 [1] and
UDP RFC768 [2] have benefited from this standard representation and UDP 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 11, line 46 skipping to change at page 11, line 46
Applications use close() to perform graceful shutdown (as described Applications use close() to perform graceful shutdown (as described
in Section 10.1 of RFC2960 [8]) on ALL the associations currently in Section 10.1 of RFC2960 [8]) on ALL the associations currently
represented by a UDP-style socket. represented by a UDP-style socket.
The syntax is: The syntax is:
ret = close(int sd); ret = close(int sd);
sd - the socket descriptor of the associations to be closed. sd - the socket descriptor of the associations to be closed.
To gracefully shutdown a specific association represented by the UDP- To gracefully shutdown a specific association represented by the
style socket, an application should use the sendmsg() call, passing UDP-style socket, an application should use the sendmsg() call,
no user data, but including the MSG_EOF flag in the ancillary data possibly passing a user specified abort code in the data field, and
(see Section 5.2.2). including the MSG_EOF flag in the 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 3.1.6 connect() - UDP Style Syntax
An application may use the connect() call in the UDP model to An application may use the connect() call in the UDP model to
initiate an association without sending data. initiate an association without sending data.
The syntax is: The syntax is:
skipping to change at page 14, line 14 skipping to change at page 14, line 14
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 non- write to the socket will block or return the error EAGAIN (for a
blocking socket). At some point, either the connection is closed, or non-blocking socket). At some point, either the connection is
the receiver begins to read again freeing space in the output queue. closed, or the receiver begins to read again freeing space in the
output queue.
For TCP-style SCTP sockets (this includes sockets descriptors that For TCP-style SCTP sockets (this includes sockets descriptors that
were separated from a UDP style socket with sctp_peeloff()) the were separated from a UDP style socket with sctp_peeloff()) the
behavior is identical. For UDP-style SCTP sockets, the fact that we behavior is identical. For UDP-style SCTP sockets, the fact that we
have multiple associations on a single socket makes the situation have multiple associations on a single socket makes the situation
more complicated. If the implementation uses a single buffer space more complicated. If the implementation uses a single buffer space
allocation shared by all associations, a single stalled association allocation shared by all associations, a single stalled association
can prevent the further sending of data on all associations active on can prevent the further sending of data on all associations active on
a particular UDP-style socket. a particular UDP-style socket.
skipping to change at page 20, line 32 skipping to change at page 20, line 36
sd - the socket descriptor of the association to be closed. sd - the socket descriptor of the association to be closed.
After an application calls close() on a socket descriptor, no further After an application calls close() on a socket descriptor, no further
socket operations will succeed on that descriptor. socket operations will succeed on that descriptor.
4.1.7 shutdown() - TCP Style Syntax 4.1.7 shutdown() - TCP Style Syntax
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 TCP- shutdown() call, and solves some different problems. Full
compatibility is not provided, so developers porting TCP applications TCP-compatibility is not provided, so developers porting TCP
to SCTP may need to recode sections that use shutdown(). (Note that applications to SCTP may need to recode sections that use shutdown().
it is possible to achieve the same results as half close in SCTP (Note that it is possible to achieve the same results as half close
using SCTP streams.) in SCTP using SCTP streams.)
The syntax is: The syntax is:
int shutdown(int socket, int how); int shutdown(int socket, 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:
skipping to change at page 21, line 51 skipping to change at page 21, line 51
Section 3.1.3), with the following differences: Section 3.1.3), with the following differences:
1) When sending, the msg_name field in the msghdr is not used to 1) When sending, the msg_name field in the msghdr is not used to
specify the intended receiver, rather it is used to indicate a specify the intended receiver, rather it is used to indicate a
different peer address if the sender does not want to send the different peer address if the sender does not want to send the
message over the primary address of the receiver. If the transport message over the primary address of the receiver. If the transport
address given is not part of the current association, the data will address given is not part of the current association, the data will
not be sent and a SCTP_SEND_FAILED event will be delivered to the not be sent and a SCTP_SEND_FAILED event will be delivered to the
application if send failure events are enabled. application if send failure events are enabled.
When receiving, if a message is not received from the primary
address, the SCTP stack will fill in the msg_name field on return so
that the application can retrieve the source address information of
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 do sendmsg(). The system returns an error if an application tries to do
so. so.
4.1.9 getpeername() 4.1.9 getpeername()
Applications use getpeername() to retrieve the primary socket address Applications use getpeername() to retrieve the primary socket address
of the peer. This call is for TCP compatibility, and is not multi- of the peer. This call is for TCP compatibility, and is not
homed. It does not work with UDP-style sockets. See Section 8.3 for multi-homed. It does not work with UDP-style sockets. See Section
a multi-homed/UDP-sockets version of the call. 8.3 for a multi-homed/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);
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
skipping to change at page 24, line 26 skipping to change at page 24, line 26
ancillary data to specify and access SCTP-specific data via the ancillary data to specify and access SCTP-specific data via the
struct msghdr's msg_control member used in sendmsg() and recvmsg(). struct msghdr's msg_control member used in sendmsg() and recvmsg().
Fine-grained control over initialization and sending parameters are Fine-grained control over initialization and sending parameters are
handled with ancillary data. handled with ancillary data.
Each ancillary data item is proceeded by a struct cmsghdr (see Each ancillary data item is proceeded by a struct cmsghdr (see
Section 5.1), which defines the function and purpose of the data Section 5.1), which defines the function and purpose of the data
contained in in the cmsg_data[] member. contained in in the cmsg_data[] member.
There are two kinds of ancillary data used by SCTP: initialization There are two kinds of ancillary data used by SCTP: initialization
data, and, header information (SNDRCV). Initialization data (UDP- data, and, header information (SNDRCV). Initialization data
style only) sets protocol parameters for new associations. Section (UDP-style only) sets protocol parameters for new associations.
5.2.1 provides more details. Header information can set or report Section 5.2.1 provides more details. Header information can set or
parameters on individual messages in a stream. See Section 5.2.2 for report parameters on individual messages in a stream. See Section
how to use SNDRCV ancillary data. 5.2.2 for how to use SNDRCV ancillary data.
By default on a TCP-style socket, SCTP will pass no ancillary data; By default on a TCP-style socket, SCTP will pass no ancillary data;
on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and on a UDP-style socket, SCTP will only pass SCTP_SNDRCV and
SCTP_ASSOC_CHANGE information. Specific ancillary data items can be SCTP_ASSOC_CHANGE information. Specific ancillary data items can be
enabled with socket options defined for SCTP; see Section 7.3. enabled with socket options defined for SCTP; see Section 7.3.
Note that all ancillary types are fixed length; see Section 5.4 for Note that all ancillary types are fixed length; see Section 5.4 for
further discussion on this. These data structures use struct further discussion on this. These data structures use struct
sockaddr_storage (defined in RFC2553 [7]) as a portable, fixed length sockaddr_storage (defined in RFC2553 [7]) as a portable, fixed length
address format. address format.
skipping to change at page 26, line 4 skipping to change at page 26, line 4
sinit_max_attempts: 16 bits (unsigned integer) sinit_max_attempts: 16 bits (unsigned integer)
This integer specifies how many attempts the SCTP endpoint should This integer specifies how many attempts the SCTP endpoint should
make at resending the INIT. This value overrides the system SCTP make at resending the INIT. This value overrides the system SCTP
'Max.Init.Retransmits' value. The default value of 0 indicates to 'Max.Init.Retransmits' value. The default value of 0 indicates to
use the endpoint's default value. This is normally set to the use the endpoint's default value. This is normally set to the
system's default 'Max.Init.Retransmit' value. system's default 'Max.Init.Retransmit' value.
sinit_max_init_timeo: 16 bits (unsigned integer) sinit_max_init_timeo: 16 bits (unsigned integer)
This value represents the largest Time-Out or RTO value to use in This value represents the largest Time-Out or RTO value (in
attempting a INIT. Normally the 'RTO.Max' is used to limit the milliseconds) to use inattempting a INIT. Normally the 'RTO.Max' is
doubling of the RTO upon timeout. For the INIT message this value used to limit the doubling of the RTO upon timeout. For the INIT
MAY override 'RTO.Max'. This value MUST NOT influence 'RTO.Max' message this value MAY override 'RTO.Max'. This value MUST NOT
during data transmission and is only used to bound the initial setup influence 'RTO.Max' during data transmission and is only used to
time. A default value of 0 indicates to use the endpoint's default bound the initial setup time. A default value of 0 indicates to use
value. This is normally set to the system's 'RTO.Max' value (60 the endpoint's default value. This is normally set to the system's
seconds). 'RTO.Max' value (60 seconds).
5.2.2 SCTP Header Information Structure (SCTP_SNDRCV) 5.2.2 SCTP Header Information Structure (SCTP_SNDRCV)
This cmsghdr structure specifies SCTP options for sendmsg() and This cmsghdr structure specifies SCTP options for sendmsg() and
describes SCTP header information about a received message through describes SCTP header information about a received message through
recvmsg(). recvmsg().
cmsg_level cmsg_type cmsg_data[] cmsg_level cmsg_type cmsg_data[]
------------ ------------ ---------------------- ------------ ------------ ----------------------
IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo IPPROTO_SCTP SCTP_SNDRCV struct sctp_sndrcvinfo
skipping to change at page 30, line 10 skipping to change at page 30, line 10
5.3.1 SCTP Notification Structure 5.3.1 SCTP Notification Structure
The notification structure is defined as the union of all The notification structure is defined as the union of all
notification types. notification types.
union sctp_notification { union sctp_notification {
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; } sn_header;
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_adaption_event sn_adaption_event;
struct sctp_rcv_pdapi_event sn_rcv_pdapi_event; struct sctp_rcv_pdapi_event sn_rcv_pdapi_event;
}; };
sn_type: 16 bits (unsigned integer) sn_type: 16 bits (unsigned integer)
skipping to change at page 45, line 8 skipping to change at page 45, line 8
If the actual length of the address is greater than the length of the If the actual length of the address is greater than the length of the
supplied sockaddr structure, the stored address will be truncated. supplied sockaddr structure, the stored address will be truncated.
If the socket has not been bound to a local name, the value stored in If the socket has not been bound to a local name, the value stored in
the object pointed to by address is unspecified. the object pointed to by address is unspecified.
7. Socket Options 7. Socket Options
The following sub-section describes various SCTP level socket options The following sub-section describes various SCTP level socket options
that are common to both models. SCTP associations can be multi- that are common to both models. SCTP associations can be
homed. Therefore, certain option parameters include a multi-homed. Therefore, certain option parameters include a
sockaddr_storage structure to select which peer address the option sockaddr_storage structure to select which peer address the option
should be applied to. should be applied to.
For the UDP-style sockets, an sctp_assoc_t structure (association ID) For the UDP-style sockets, an sctp_assoc_t structure (association ID)
is used to identify the the association instance that the operation is used to identify the the association instance that the operation
affects. So it must be set when using this model. affects. So it must be set when using this model.
For the TCP-style sockets and branched off UDP-style sockets (see For the TCP-style sockets and branched off UDP-style sockets (see
Section 8.2) this association ID parameter is ignored. In the cases Section 8.2) this association ID parameter is ignored. In the cases
noted below where the parameter is ignored, an application can pass noted below where the parameter is ignored, an application can pass
skipping to change at page 46, line 9 skipping to change at page 46, line 9
TCP-style sockets, id is ignored. TCP-style sockets, id is ignored.
opt specifies which SCTP socket option to get. It can any socket opt specifies which SCTP socket option to get. It can any socket
option currently supported that requests information (either read/ option currently supported that requests information (either read/
write options or read only) such as: write options or read only) such as:
SCTP_RTOINFO SCTP_RTOINFO
SCTP_ASSOCINFO SCTP_ASSOCINFO
SCTP_SET_PRIMARY_ADDR SCTP_SET_PRIMARY_ADDR
SCTP_SET_PEER_PRIMARY_ADDR SCTP_SET_PEER_PRIMARY_ADDR
SCTP_SET_STREAM_TIMEOUTS
SCTP_SET_PEER_ADDR_PARAMS SCTP_SET_PEER_ADDR_PARAMS
SCTP_STATUS SCTP_STATUS
SCTP_GET_PEER_ADDR_INFO SCTP_GET_PEER_ADDR_INFO
arg is an option-specific structure buffer provided by the caller. arg is an option-specific structure buffer provided by the caller.
See Section 8.5) subsections for more information on these options See Section 8.5) subsections for more information on these options
and option-specific structures. and option-specific structures.
sctp_opt_info() returns 0 on success, or on failure returns -1 and sctp_opt_info() returns 0 on success, or on failure returns -1 and
sets errno to the appropriate error code. 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_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 All options that support specific settings on an association by
filling in either an association id variable or a sockaddr_storage filling in either an association id variable or a sockaddr_storage
SHOULD also support setting of the same value for the entire endpoint SHOULD also support setting of the same value for the entire endpoint
(i.e. future associations). To accomplish this the following logic (i.e. future associations). To accomplish this the following logic
is used when setting one of these options: is used when setting one of these options:
a) If an address is specified via a sockaddr_storage that is included 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 in the structure the address is used to lookup the association and
the settings are applied to the specific address (if appropriate) the settings are applied to the specific address (if appropriate)
or to the entire association. or to the entire association.
skipping to change at page 49, line 4 skipping to change at page 48, line 43
endpoint information. endpoint information.
The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set The values of the sasoc_asocmaxrxt and sasoc_cookie_life may be set
on either an endpoint or association basis. The rwnd and destination on either an endpoint or association basis. The rwnd and destination
counts (sasoc_number_peer_destinations, counts (sasoc_number_peer_destinations,
sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value sasoc_peer_rwnd,sasoc_local_rwnd) are NOT settable and any value
placed in these is ignored. 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_ASSOCINFO.
The maximum number of retransmissions before an address is considered The maximum number of retransmissions before an address is considered
unreachable is also tunable, but is address-specific, so it is unreachable is also tunable, but is address-specific, so it is
covered in a separate option. If an application attempts to set the covered in a separate option. If an application attempts to set the
value of the association maximum retransmission parameter to more value of the association maximum retransmission parameter to more
than the sum of all maximum retransmission parameters, setsockopt() than the sum of all maximum retransmission parameters, setsockopt()
shall return an error. The reason for this, from RFC2960 [8] section shall return an error. The reason for this, from RFC2960 [8] section
8.2: 8.2:
Note: When configuring the SCTP endpoint, the user should avoid Note: When configuring the SCTP endpoint, the user should avoid
skipping to change at page 50, line 5 skipping to change at page 49, line 42
}; };
To enable the option, set l_onoff to 1. If the l_linger value is set To enable the option, set l_onoff to 1. If the l_linger value is set
to 0, calling close() is the same as the ABORT primitive. If the to 0, calling close() is the same as the ABORT primitive. If the
value is set to a negative value, the setsockopt() call will return value is set to a negative value, the setsockopt() call will return
an error. If the value is set to a positive value linger_time, the an error. If the value is set to a positive value linger_time, the
close() can be blocked for at most linger_time ms. If the graceful close() can be blocked for at most linger_time ms. If the graceful
shutdown phase does not finish during this period, close() will shutdown phase does not finish during this period, close() will
return but the graceful shutdown phase continues in the system. return but the graceful shutdown phase continues in the system.
Note, this is a socket level option NOT an SCTP level option. So
when setting SO_LINGER you must specify a level of SOL_SOCKET in the
setsockopt() call.
7.1.5 SCTP_NODELAY 7.1.5 SCTP_NODELAY
Turn on/off any Nagle-like algorithm. This means that packets are Turn on/off any Nagle-like algorithm. This means that packets are
generally sent as soon as possible and no unnecessary delays are generally sent as soon as possible and no unnecessary delays are
introduced, at the cost of more packets in the network. Expects an introduced, at the cost of more packets in the network. Expects an
integer boolean flag. integer boolean flag.
7.1.6 SO_RCVBUF 7.1.6 SO_RCVBUF
Sets receive buffer size. For SCTP TCP-style sockets, this controls Sets receive buffer size. For SCTP TCP-style sockets, this controls
skipping to change at page 51, line 47 skipping to change at page 51, line 36
Indication parameter for all future INIT and INIT-ACK exchanges. Indication parameter for all future INIT and INIT-ACK exchanges.
struct sctp_setadaption { struct sctp_setadaption {
u_int32_t ssb_adaption_ind; u_int32_t ssb_adaption_ind;
}; };
ssb_adaption_ind The adaption layer indicator 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) 7.1.12 Enable/Disable message fragmentation (SCTP_DISABLE_FRAGMENTS)
This option requests that the requested stream apply a default time-
out for messages in queue. The default value is used when the
application does not specify a timeout in the sendrcvinfo structure
(sinfo_timetolive element see Section 5.2.2).
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 identifier to apply this
default against.
ssto_streamid_end The ending stream identifier 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 This option is a on/off flag. If enabled no SCTP message
fragmentation will be performed. Instead if a message being sent fragmentation will be performed. Instead if a message being sent
exceeds the current PMTU size, the message will NOT be sent and exceeds the current PMTU size, the message will NOT be sent and
instead a error will be indicated to the user. instead a error will be indicated to the user.
7.1.14 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS) 7.1.13 Peer Address Parameters (SCTP_SET_PEER_ADDR_PARAMS)
Applications can enable or disable heartbeats for any peer address of Applications can enable or disable heartbeats for any peer address of
an association, modify an address's heartbeat interval, force a an association, modify an address's heartbeat interval, force a
heartbeat to be sent immediately, and adjust the address's maximum heartbeat to be sent immediately, and adjust the address's maximum
number of retransmissions sent before an address is considered number of retransmissions sent before an address is considered
unreachable. The following structure is used to access and modify an unreachable. The following structure is used to access and modify an
address's parameters: address's parameters:
struct sctp_paddrparams { struct sctp_paddrparams {
sctp_assoc_t spp_assoc_id; sctp_assoc_t spp_assoc_id;
skipping to change at page 53, line 30 skipping to change at page 52, line 31
specifies that a heartbeat should be sent specifies that a heartbeat should be sent
immediately to the peer address, and the current immediately to the peer address, and the current
interval should remain unchanged. interval should remain unchanged.
spp_pathmaxrxt - This contains the maximum number of spp_pathmaxrxt - This contains the maximum number of
retransmissions before this address shall be retransmissions before this address shall be
considered unreachable. considered unreachable.
To read or modify these parameters, the application should call To read or modify these parameters, the application should call
sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option. sctp_opt_info() with the SCTP_SET_PEER_ADDR_PARAMS option.
7.1.15 Set default send parameters (SET_DEFAULT_SEND_PARAM) 7.1.14 Set default send parameters (SET_DEFAULT_SEND_PARAM)
Applications that wish to use the sendto() system call may wish to Applications that wish to use the sendto() system call may wish to
specify a default set of parameters that would normally be supplied specify a default set of parameters that would normally be supplied
through the inclusion of ancillary data. This socket option allows through the inclusion of ancillary data. This socket option allows
such an application to set the default sctp_sndrcvinfo structure. such an application to set the default sctp_sndrcvinfo structure.
The application that wishes to use this socket option simply passes The application that wishes to use this socket option simply passes
in to this call the sctp_sndrcvinfo structure defined in Section in to this call the sctp_sndrcvinfo structure defined in Section
5.2.2) The input parameters accepted by this call include 5.2.2) The input parameters accepted by this call include
sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context,
sinfo_timetolive. The user must provide the sinfo_assoc_id field in sinfo_timetolive. The user must provide the sinfo_assoc_id field in
to this call if the caller is using the UDP model. to this call if the caller is using the UDP model.
7.1.16 Set notification and ancillary events (SCTP_SET_EVENTS) 7.1.15 Set notification and ancillary events (SCTP_SET_EVENTS)
This socket option is used to specify various notifications and This socket option is used to specify various notifications and
ancillary data the user wishes to receive. Please see Section 7.3) ancillary data the user wishes to receive. Please see Section 7.3)
for a full description of this option and its usage. for a full description of this option and its usage.
7.1.16 Set/clear IPv4 mapped addresses (SCTP_I_WANT_MAPPED_V4_ADDR)
This socket option is a boolean flag which turns on or off mapped V4
addresses. If this option is turned on and the socket is type
PF_INET6, then IPv4 addresses will be mapped to V6 representation.
If this option is turned off, then no mapping will be done of V4
addresses and a user will receive both PF_INET6 and PF_INET type
addresses on the socket.
By default this option is turned on.
7.1.17 Set the maximum fragrmentation size (SCTP_MAXSEG)
This socket option specifies the maximum size to put in any outgoing
SCTP chunk. If a message is larger than this size it will be
fragmented by SCTP into the specified size. Note that the underlying
SCTP implementation may fragment into smaller sized chunks when the
PMTU of the underlying association is smaller than the value set by
the user.
7.2 Read-Only Options 7.2 Read-Only Options
7.2.1 Association Status (SCTP_STATUS) 7.2.1 Association Status (SCTP_STATUS)
Applications can retrieve current status information about an Applications can retrieve current status information about an
association, including association state, peer receiver window size, association, including association state, peer receiver window size,
number of unacked data chunks, and number of data chunks pending number of unacked data chunks, and number of data chunks pending
receipt. This information is read-only. The following structure is receipt. This information is read-only. The following structure is
used to access this information: used to access this information:
skipping to change at page 55, line 19 skipping to change at page 54, line 39
will occur. 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) 7.2.2 Peer Address Information (SCTP_GET_PEER_ADDR_INFO)
Applications can retrieve information about a specific peer address Applications can retrieve information about a specific peer address
of an association, including its reachability state, congestion of an association, including its reachability state, congestion
window, and retransmission timer values. This information is read- window, and retransmission timer values. This information is
only. The following structure is used to access this information: read-only. The following structure is used to access this
information:
struct sctp_paddrinfo { struct sctp_paddrinfo {
sctp_assoc_t spinfo_assoc_id; sctp_assoc_t spinfo_assoc_id;
struct sockaddr_storage spinfo_address; struct sockaddr_storage spinfo_address;
int32_t spinfo_state; int32_t spinfo_state;
uint32_t spinfo_cwnd; uint32_t spinfo_cwnd;
uint32_t spinfo_srtt; uint32_t spinfo_srtt;
uint32_t spinfo_rto; uint32_t spinfo_rto;
uint32_t spinfo_mtu; uint32_t spinfo_mtu;
}; };
skipping to change at page 60, line 40 skipping to change at page 59, line 40
new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id); new_sd = sctp_peeloff(int sd, sctp_assoc_t *assoc_id);
the new socket descriptor representing the branched-off the new socket descriptor representing the branched-off
association. association.
the original UDP-style socket descriptor returned from the 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).
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 TCP- off to a separate file descriptor (Note, in a traditional
style accept() call, this would be an out parameter, but for the TCP-style accept() call, this would be an out parameter, but for
UDP-style call, this is an in parameter). 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
should use sctp_freepaddrs() to free the memory. addrs must not be should use sctp_freepaddrs() 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
skipping to change at page 63, line 5 skipping to change at page 61, line 22
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(). addrs is the array of peer addresses returned by sctp_getladdrs().
9. Security Considerations 8.7 sctp_sndmsg()
An implementation may provide a library function (or possibly system
call) to assist the user with the advanced features of SCTP.
sctp_sendmsg(). Its syntax is,
void sctp_sendmsg(int s, const void *msg, size_t len,
uint32_t ppid,
uint32_t flags,
uint16_t stream_no,
uint32_t timetolive,
uint32_t context)
s - is the socket descriptor
msg - is the message to be sent.
len - is the length of the message.
ppid - is the same as sinfo_ppid (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)
timetolive - is the same as sinfo_timetolive (see section 5.2.2)
context - is the same as sinfo_context (see section 5.2.2)
9. Preprocessor Constants
For application portability it is desireable to define pre-processor
constants for determination if sctp is present and supports various
features. The following pre-processor constants should be defined in
a include file, sctp.h.
HAVE_SCTP - If this constant is defined to 1, then an implementation
of SCTP is available.
HAVE_KERNEL_SCTP - If this constant is defined to 1, then a kernel
SCTP implementation is available through the sockets interface.
HAVE_SCTP_PRSCTP - If this constant is defined to 1, then the SCTP
implementation supports the partial reliablility extension to
SCTP.
HAVE_SCTP_ADDIP - If this constant is defined to 1, then the SCTP
implementation supports the dynamic address extension to SCTP.
HAVE_SCTP_CANSET_PRIMARY - If this constant is defined to 1, then the
SCTP implementation supports the ability to request setting of the
remote primary address.
HAVE_SCTP_SAT_NETWORK_CAPABILITY - If this constant is defined to 1,
then the SCTP implementation supports the satellite network
extension to SCTP.
10. Security Considerations
Many TCP and UDP implementations reserve port numbers below 1024 for Many TCP and UDP implementations reserve port numbers below 1024 for
privileged users. If the target platform supports privileged users, privileged users. If the target platform supports privileged users,
the SCTP implementation SHOULD restrict the ability to call bind() or the SCTP implementation SHOULD restrict the ability to call bind() or
sctp_bindx() on these port numbers to privileged users. sctp_bindx() on these port numbers to privileged users.
Similarly unprevledged users should not be able to set protocol Similarly unprevledged users should not be able to set protocol
parameters which could result in the congestion control algorithm parameters which could result in the congestion control algorithm
being more aggressive than permitted on the public Internet. These being more aggressive than permitted on the public Internet. These
parameters are: parameters are:
struct sctp_rtoinfo struct sctp_rtoinfo
If an unprivileged user inherits a 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 protocols. associations. This could be relevant for the r* family of protocols.
10. Acknowledgments 11. Acknowledgments
The authors wish to thank Kavitha Baratakke, Mike Bartlett, Jon The authors wish to thank Kavitha Baratakke, Mike Bartlett, Jon
Berger, Scott Kimble, Renee Revis, and many others on the TSVWG Berger, Scott Kimble, Renee Revis, and many others on the TSVWG
mailing list for contributing valuable comments. mailing list for contributing valuable comments.
A special thanks to Phillip Conrad, for his suggested text, quick and A special thanks to Phillip Conrad, for his suggested text, quick and
constructive insights, and most of all his persistent fighting to constructive insights, and most of all his persistent fighting to
keep the interface to SCTP usable for the application programmer. keep the interface to SCTP usable for the application programmer.
References References
skipping to change at page 66, line 32 skipping to change at page 66, line 26
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
Sun Microsystems, Inc. Consultant
901 San Antonio Road
Palo Alto, CA 94303 Milpitas, CA
USA
Phone: Phone:
EMail: kcpoon@yahoo.com EMail: kcpoon@yahoo.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
skipping to change at page 67, line 4 skipping to change at page 66, line 41
EMail: kcpoon@yahoo.com EMail: kcpoon@yahoo.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
Siemens AG
ICN WN CC SE 7
D-81359 Munich
Germany Germany
Phone: Phone:
EMail: Michael.Tuexen@siemens.com
EMail: tuexen@fh-muenster.de
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
skipping to change at page 68, line 50 skipping to change at page 68, line 50
struct sctp_paddr_change *spc; struct sctp_paddr_change *spc;
struct sctp_remote_error *sre; struct sctp_remote_error *sre;
union sctp_notification *snp; union sctp_notification *snp;
char addrbuf[INET6_ADDRSTRLEN]; char addrbuf[INET6_ADDRSTRLEN];
const char *ap; const char *ap;
struct sockaddr_in *sin; struct sockaddr_in *sin;
struct sockaddr_in6 *sin6; struct sockaddr_in6 *sin6;
snp = buf; snp = buf;
switch (snp->sn_type) { switch (snp->sn_header.sn_type) {
case SCTP_ASSOC_CHANGE: case SCTP_ASSOC_CHANGE:
sac = &snp->sn_assoc_change; sac = &snp->sn_assoc_change;
printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu " printf("^^^ assoc_change: state=%hu, error=%hu, instr=%hu "
"outstr=%hu\n", sac->sac_state, sac->sac_error, "outstr=%hu\n", sac->sac_state, sac->sac_error,
sac->sac_inbound_streams, sac->sac_outbound_streams); sac->sac_inbound_streams, sac->sac_outbound_streams);
break; break;
case SCTP_SEND_FAILED: case SCTP_SEND_FAILED:
ssf = &snp->sn_send_failed; ssf = &snp->sn_send_failed;
printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length, printf("^^^ sendfailed: len=%hu err=%d\n", ssf->ssf_length,
skipping to change at page 69, line 39 skipping to change at page 69, line 39
break; break;
case SCTP_REMOTE_ERROR: case SCTP_REMOTE_ERROR:
sre = &snp->sn_remote_error; sre = &snp->sn_remote_error;
printf("^^^ remote_error: err=%hu len=%hu\n", printf("^^^ remote_error: err=%hu len=%hu\n",
ntohs(sre->sre_error), ntohs(sre->sre_len)); ntohs(sre->sre_error), ntohs(sre->sre_len));
break; break;
case SCTP_SHUTDOWN_EVENT: case SCTP_SHUTDOWN_EVENT:
printf("^^^ shutdown event\n"); printf("^^^ shutdown event\n");
break; break;
default: default:
printf("unknown type: %hu\n", snp->sn_type); printf("unknown type: %hu\n", snp->sn_header.sn_type);
break; break;
} }
} }
static void * static void *
sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen, sctp_recvmsg(int fd, struct msghdr *msg, void *buf, size_t *buflen,
ssize_t *nrp, size_t cmsglen) ssize_t *nrp, size_t cmsglen)
{ {
ssize_t nr = 0; ssize_t nr = 0, nnr = 0;
struct iovec iov[1]; struct iovec iov[1];
*nrp = 0; *nrp = 0;
iov->iov_base = buf; iov->iov_base = buf;
iov->iov_len = *buflen;
msg->msg_iov = iov; msg->msg_iov = iov;
msg->msg_iovlen = 1; msg->msg_iovlen = 1;
for (;;) { for (;;) {
#ifndef MSG_XPG4_2 #ifndef MSG_XPG4_2
#define MSG_XPG4_2 0 #define MSG_XPG4_2 0
#endif #endif
msg->msg_flags = MSG_XPG4_2; msg->msg_flags = MSG_XPG4_2;
msg->msg_iov->iov_len = *buflen;
msg->msg_controllen = cmsglen; msg->msg_controllen = cmsglen;
nr += recvmsg(fd, msg, 0); nnr = recvmsg(fd, msg, 0);
if (nr <= 0) { if (nnr <= 0) {
/* EOF or error */ /* EOF or error */
*nrp = nr; *nrp = nr;
return (NULL); return (NULL);
} }
nr += nnr;
if ((msg->msg_flags & MSG_EOR) != 0) { if ((msg->msg_flags & MSG_EOR) != 0) {
*nrp = nr; *nrp = nr;
return (buf); return (buf);
} }
/* Realloc the buffer? */ /* Realloc the buffer? */
if (*buflen == nr) { if (*buflen == nr) {
buf = realloc(buf, *buflen * 2); buf = realloc(buf, *buflen * 2);
if (buf == 0) { if (buf == 0) {
skipping to change at page 72, line 50 skipping to change at page 73, line 4
/* Enable all events */ /* Enable all events */
event.sctp_data_io_event = 1; event.sctp_data_io_event = 1;
event.sctp_association_event = 1; event.sctp_association_event = 1;
event.sctp_address_event = 1; event.sctp_address_event = 1;
event.sctp_send_failure_event = 1; event.sctp_send_failure_event = 1;
event.sctp_peer_error_event = 1; event.sctp_peer_error_event = 1;
event.sctp_shutdown_event = 1; event.sctp_shutdown_event = 1;
event.sctp_partial_delivery_event = 1; event.sctp_partial_delivery_event = 1;
event.sctp_adaption_layer_event = 1; event.sctp_adaption_layer_event = 1;
if (setsockopt(r->fd, IPPROTO_SCTP, if (setsockopt(cfd, IPPROTO_SCTP,
SCTP_SET_EVENTS, &event, SCTP_SET_EVENTS, &event,
sizeof(event)) != 0) { sizeof(event)) != 0) {
perror("setevent failed"); perror("setevent failed");
exit(1); exit(1);
} }
/* Echo back any and all data */ /* Echo back any and all data */
echo(cfd,0); echo(cfd,0);
} }
} }
skipping to change at page 74, line 31 skipping to change at page 74, line 31
o Handling notifications o Handling notifications
Note most functions defined in Appendix A are reused in this example. Note most functions defined in Appendix A are reused in this example.
int main() int main()
{ {
int fd; int fd;
int onoff = 1; int onoff = 1;
int idleTime = 2; int idleTime = 2;
struct sockaddr_in sin[1]; struct sockaddr_in sin[1];
struct sctp_event_subscribe event;
if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) { if ((fd = socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP)) == -1) {
perror("socket"); perror("socket");
exit(1); exit(1);
} }
sin->sin_family = AF_INET; sin->sin_family = AF_INET;
sin->sin_port = htons(7); sin->sin_port = htons(7);
sin->sin_addr.s_addr = INADDR_ANY; sin->sin_addr.s_addr = INADDR_ANY;
if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) { if (bind(fd, (struct sockaddr *)sin, sizeof (*sin)) == -1) {
skipping to change at page 75, line 5 skipping to change at page 75, line 6
/* Enable all notifications and events */ /* Enable all notifications and events */
event.sctp_data_io_event = 1; event.sctp_data_io_event = 1;
event.sctp_association_event = 1; event.sctp_association_event = 1;
event.sctp_address_event = 1; event.sctp_address_event = 1;
event.sctp_send_failure_event = 1; event.sctp_send_failure_event = 1;
event.sctp_peer_error_event = 1; event.sctp_peer_error_event = 1;
event.sctp_shutdown_event = 1; event.sctp_shutdown_event = 1;
event.sctp_partial_delivery_event = 1; event.sctp_partial_delivery_event = 1;
event.sctp_adaption_layer_event = 1; event.sctp_adaption_layer_event = 1;
if (setsockopt(r->fd, IPPROTO_SCTP, if (setsockopt(fd, IPPROTO_SCTP,
SCTP_SET_EVENTS, &event, SCTP_SET_EVENTS, &event,
sizeof(event)) != 0) { sizeof(event)) != 0) {
perror("setevent failed"); perror("setevent failed");
exit(1); exit(1);
} }
/* Set associations to auto-close in 2 seconds of /* Set associations to auto-close in 2 seconds of
* inactivity * inactivity
*/ */
if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE, if (setsockopt(fd, IPPROTO_SCTP, SCTP_AUTOCLOSE,
&idleTime, 4) < 0) { &idleTime, 4) < 0) {
skipping to change at page 76, line 5 skipping to change at page 76, line 5
exit(1); exit(1);
} }
/* Wait for new associations */ /* Wait for new associations */
while(1){ while(1){
/* Echo back any and all data */ /* Echo back any and all data */
echo(fd,1); echo(fd,1);
} }
} }
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved. Copyright (C) The Internet Society (2003). 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
developing Internet standards in which case the procedures for developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than followed, or as required to translate it into languages other than
English. English.
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 assigns. 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 Acknowledgement
 End of changes. 

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