Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SCTP(4)                FreeBSD Kernel Interfaces Manual                SCTP(4)

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)

FreeBSD 11.0-PRERELEASE        December 15, 2006       FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sctp&sektion=4&manpath=FreeBSD+8.3-RELEASE>

home | help