Provided by: freebsd-manpages_8.2-1_all bug

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 maxium 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 undesireable, 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
                                 prefered and the last is the least prefered.

     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 specifices 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)