Provided by: freebsd-manpages_11.1-3_all 
NAME
sctp — Internet Stream Control Transmission Protocol
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/sctp.h>
int
socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP);
int
socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
DESCRIPTION
The SCTP protocol provides reliable, flow-controlled, two-way transmission of data. It is a
message oriented protocol and can support the SOCK_STREAM and SOCK_SEQPACKET abstractions.
SCTP uses the standard Internet address format and, in addition, provides a per-host
collection of “port addresses”. Thus, each address is composed of an Internet address
specifying the host and network, with a specific SCTP port on the host identifying the peer
entity.
There are two models of programming in SCTP. The first uses the SOCK_STREAM abstraction.
In this abstraction sockets utilizing the SCTP protocol are either “active” or “passive”.
Active sockets initiate connections to passive sockets. By default, SCTP sockets are
created active; to create a passive socket, the listen(2) system call must be used after
binding the socket with the bind(2) or sctp_bindx(3) system calls. Only passive sockets may
use the accept(2) call to accept incoming connections. Only active sockets may use the
connect(2) call to initiate connections.
The other abstraction SOCK_SEQPACKET provides a “connectionless” mode of operation in that
the user may send to an address (using any of the valid send calls that carry a socket
address) and an association will be setup implicitly by the underlying SCTP transport stack.
This abstraction is the only one capable of sending data on the third leg of the four-way
handshake. A user must still call listen(2) to allow the socket to accept connections.
Calling listen(2) however does not restrict the user from still initiating implicit
connections to other peers.
The SCTP protocol directly supports multi-homing. So when binding a socket with the
“wildcard” address INADDR_ANY, the SCTP stack will inform the peer about all of the local
addresses that are deemed in scope of the peer. The peer will then possibly have multiple
paths to reach the local host.
The SCTP transport protocol is also multi-streamed. Multi-streaming refers to the ability
to send sub-ordered flows of messages. A user performs this by specifying a specific stream
in one of the extended send calls such as the sctp_send(3) function call. Sending messages
on different streams will allow parallel delivery of data i.e., a message loss in stream 1
will not block the delivery of messages sent in stream 2.
The SCTP transport protocol also provides a unordered service as well. The unordered
service allows a message to be sent and delivered with no regard to the ordering of any
other message.
Extensions
The FreeBSD implementation of SCTP also supports the following extensions:
sctp partial reliability This extension allows one to have message be skipped and not
delivered based on some user specified parameters.
sctp dynamic addressing This extension allows addresses to be added and deleted dynamically
from an existing association.
sctp authentication This extension allows the user to authenticate specific peer chunks
(including data) to validate that the peer who sent the message is in fact the peer
who setup the association. A shared key option is also provided for so that two
stacks can pre-share keys.
packet drop Some routers support a special satellite protocol that will report losses due to
corruption. This allows retransmissions without subsequent loss in bandwidth
utilization.
stream reset This extension allows a user on either side to reset the stream sequence
numbers used by any or all streams.
SCTP supports a number of socket options which can be set with setsockopt(2) and tested with
getsockopt(2) or sctp_opt_info(3):
SCTP_NODELAY Under most circumstances, SCTP sends data when it is presented;
when outstanding data has not yet been acknowledged, it gathers
small amounts of output to be sent in a single packet once an
acknowledgement is received. For some clients, such as window
systems that send a stream of mouse events which receive no
replies, this packetization may cause significant delays. The
boolean option SCTP_NODELAY defeats this algorithm.
SCTP_RTOINFO This option returns specific information about an associations
“Retransmission Time Out”. It can also be used to change the
default values.
SCTP_ASSOCINFO This option returns specific information about the requested
association.
SCTP_INITMSG This option allows you to get or set the default sending
parameters when an association is implicitly setup. It allows
you to change such things as the maximum number of streams
allowed inbound and the number of streams requested of the peer.
SCTP_AUTOCLOSE For the one-to-many model (SOCK_SEQPACKET) associations are
setup implicitly. This option allows the user to specify a
default number of idle seconds to allow the association be
maintained. After the idle timer (where no user message have
been sent or have been received from the peer) the association
will be gracefully closed. The default for this value is 0, or
unlimited (i.e., no automatic close).
SCTP_SET_PEER_PRIMARY_ADDR The dynamic address extension allows a peer to also request a
particular address of its be made into the primary address.
This option allows the caller to make such a request to a peer.
Note that if the peer does not also support the dynamic address
extension, this call will fail. Note the caller must provide a
valid local address that the peer has been told about during
association setup or dynamically.
SCTP_PRIMARY_ADDR This option allows the setting of the primary address that the
caller wishes to send to. The caller provides the address of a
peer that is to be made primary.
SCTP_ADAPTATION_LAYER The dynamic address extension also allows a user to pass a 32
bit opaque value upon association setup. This option allows a
user to set or get this value.
SCTP_DISABLE_FRAGMENTS By default SCTP will fragment user messages into multiple pieces
that will fit on the network and then later, upon reception,
reassemble the pieces into a single user message. If this
option is enabled instead, any send that exceeds the path
maximum transfer unit (P-MTU) will fail and the message will NOT
be sent.
SCTP_PEER_ADDR_PARAMS This option will allow a user to set or get specific peer
address parameters.
SCTP_DEFAULT_SEND_PARAM When a user does not use one of the extended send calls (e.g.,
sctp_sendmsg(3)) a set of default values apply to each send.
These values include things like the stream number to send to as
well as the per-protocol id. This option lets a caller both get
and set these values. If the user changes these default values,
then these new values will be used as the default whenever no
information is provided by the sender (i.e., the non-extended
API is used).
SCTP_EVENTS SCTP has non-data events that it can communicate to its
application. By default these are all disabled since they
arrive in the data path with a special flag MSG_NOTIFICATION set
upon the received message. This option lets a caller both get
what events are current being received as well as set different
events that they may be interested in receiving.
SCTP_I_WANT_MAPPED_V4_ADDR SCTP supports both IPV4 and IPV6. An association may span both
IPV4 and IPV6 addresses since SCTP is multi-homed. By default,
when opening an IPV6 socket, when data arrives on the socket
from a peer's V4 address the V4 address will be presented with
an address family of AF_INET. If this is undesirable, then this
option can be enabled which will then convert all V4 addresses
into mapped V6 representations.
SCTP_MAXSEG By default SCTP chooses its message fragmentation point based
upon the smallest P-MTU of the peer. This option lets the
caller set it to a smaller value. Note that while the user can
change this value, if the P-MTU is smaller than the value set by
the user, then the P-MTU value will override any user setting.
SCTP_DELAYED_ACK_TIME This option lets the user both set and get the delayed ack time
(in milliseconds) that SCTP is using. The default is 200
milliseconds.
SCTP_PARTIAL_DELIVERY_POINT
SCTP at times may need to start delivery of a very large message
before the entire message has arrived. By default SCTP waits
until the incoming message is larger than one fourth of the
receive buffer. This option allows the stacks value to be
overridden with a smaller value.
SCTP_FRAGMENT_INTERLEAVE SCTP at times will start partial delivery (as mentioned above).
In the normal case successive reads will continue to return the
rest of the message, blocking if needed, until all of that
message is read. However this means other messages may have
arrived and be ready for delivery and be blocked behind the
message being partially delivered. If this option is enabled,
when a partial delivery message has no more data to be received,
then a subsequent read may return a different message that is
ready for delivery. By default this option is off since the
user must be using the extended API's to be able to tell the
difference between messages (via the stream and stream sequence
number).
SCTP_AUTH_CHUNK By default only the dynamic addressing chunks are authenticated.
This option lets a user request an additional chunk be
authenticated as well. Note that successive calls to this
option will work and continue to add more chunks that require
authentication. Note that this option only effects future
associations and not existing ones.
SCTP_AUTH_KEY This option allows a user to specify a shared key that can be
later used to authenticate a peer.
SCTP_HMAC_IDENT This option will let you get or set the list of HMAC algorithms
used to authenticate peers. Note that the HMAC values are in
priority order where the first HMAC identifier is the most
preferred and the last is the least preferred.
SCTP_AUTH_ACTIVE_KEY This option allows you to make a key active for the generation
of authentication information. Note that the peer must have the
same key or else the data will be discarded.
SCTP_AUTH_DELETE_KEY This option allows you to delete an old key.
SCTP_USE_EXT_RECVINFO The sockets api document allows an extended send/receive
information structure to be used. The extended structure
includes additional fields related to the next message to be
received (after the current receive completes) if such
information is known. By default the system will not pass this
information. This option allows the user to request this
information.
SCTP_AUTO_ASCONF By default when bound to all address and the system
administrator has enables automatic dynamic addresses, the SCTP
stack will automatically generate address changes into add and
delete requests to any peers by setting this option to true.
This option allows an endpoint to disable that behavior.
SCTP_MAXBURST By default SCTP implements micro-burst control so that as the
congestion window opens up no large burst of packets can be
generated. The default burst limit is four. This option lets
the user change this value.
SCTP_CONTEXT Many sctp extended calls have a context field. The context
field is a 32 bit opaque value that will be returned in send
failures. This option lets the caller set the default context
value to use when none is provided by the user.
SCTP_EXPLICIT_EOR By default, a single send is a complete message. SCTP generates
an implied record boundary. If this option is enabled, then all
sends are part of the same message until the user indicates an
end of record with the special flag SCTP_EOR passed in the
sctp_sndrcvinfo flags field. This effectively makes all sends
part of the same message until the user specifies differently.
This means that a caller must NOT change the stream number until
after the SCTP_EOR is passed to SCTP else an error will be
returned.
SCTP_STATUS This option is a read-only option that returns various status
information about the specified association.
SCTP_GET_PEER_ADDR_INFO This read-only option returns information about a peer address.
SCTP_PEER_AUTH_CHUNKS This read-only option returns a list of the chunks the peer
requires to be authenticated.
SCTP_LOCAL_AUTH_CHUNKS This read-only option returns a list of the locally required
chunks that must be authenticated.
SCTP_RESET_STREAMS This socket option is used to cause a stream sequence number or
all stream sequence numbers to be reset. Note that the peer
SCTP endpoint must also support the stream reset extension as
well.
SEE ALSO
accept(2), bind(2), connect(2), listen(2), sctp_bindx(3), sctp_connectx(3),
sctp_opt_info(3), sctp_recvmsg(3), sctp_sendmsg(3)