Provided by: freebsd-manpages_7.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
             dynammically 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(2):

     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)