path: root/static/netbsd/man4/sctp.4 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">SCTP(4)</td>
    <td class="head-vol">Device Drivers Manual</td>
    <td class="head-rtitle">SCTP(4)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">sctp</code> &#x2014; <span class="Nd">Internet
    Stream Control Transmission Protocol</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
    &lt;<a class="In">sys/types.h</a>&gt;</code>
  <br/>
  <code class="In">#include &lt;<a class="In">sys/socket.h</a>&gt;</code>
  <br/>
  <code class="In">#include &lt;<a class="In">netinet/sctp.h</a>&gt;</code></p>
<p class="Pp"><var class="Ft">int</var>
  <br/>
  <code class="Fn">socket</code>(<var class="Fa" style="white-space: nowrap;">AF_INET</var>,
    <var class="Fa" style="white-space: nowrap;">SOCK_STREAM</var>,
    <var class="Fa" style="white-space: nowrap;">IPPROTO_SCTP</var>);</p>
<p class="Pp"><var class="Ft">int</var>
  <br/>
  <code class="Fn">socket</code>(<var class="Fa" style="white-space: nowrap;">AF_INET</var>,
    <var class="Fa" style="white-space: nowrap;">SOCK_SEQPACKET</var>,
    <var class="Fa" style="white-space: nowrap;">IPPROTO_SCTP</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The SCTP protocol provides reliable, flow-controlled, two-way
    transmission of data. It is a message oriented protocol and can support the
    <code class="Dv">SOCK_STREAM</code> and
    <code class="Dv">SOCK_SEQPACKET</code> abstractions. SCTP uses the standard
    Internet address format and, in addition, provides a per-host collection of
    &#x201C;port addresses&#x201D;. 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.</p>
<p class="Pp">There are two models of programming in SCTP. The first uses the
    <code class="Dv">SOCK_STREAM</code> abstraction. In this abstraction sockets
    utilizing the SCTP protocol are either &#x201C;active&#x201D; or
    &#x201C;passive&#x201D;. Active sockets initiate connections to passive
    sockets. By default, SCTP sockets are created active; to create a passive
    socket, the <a class="Xr">listen(2)</a> system call must be used after
    binding the socket with the <a class="Xr">bind(2)</a> or
    <a class="Xr">sctp_bindx(3)</a> system calls. Only passive sockets may use
    the <a class="Xr">accept(2)</a> call to accept incoming connections. Only
    active sockets may use the <a class="Xr">connect(2)</a> call to initiate
    connections.</p>
<p class="Pp">The other abstraction <code class="Dv">SOCK_SEQPACKET</code>
    provides a &#x201C;connectionless&#x201D; 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 <a class="Xr">listen(2)</a> to allow the socket to accept connections.
    Calling <a class="Xr">listen(2)</a> however does not restrict the user from
    still initiating implicit connections to other peers.</p>
<p class="Pp">The SCTP protocol directly supports multi-homing. So when binding
    a socket with the &#x201C;wildcard&#x201D; address
    <code class="Dv">INADDR_ANY</code>, 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.</p>
<p class="Pp">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 <a class="Xr">sctp_send(3)</a> 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.</p>
<p class="Pp">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.</p>
<section class="Ss">
<h2 class="Ss" id="Extensions"><a class="permalink" href="#Extensions">Extensions</a></h2>
<p class="Pp">The NetBSD implementation of SCTP also supports the following
    extensions:</p>
<dl class="Bl-hang">
  <dt>sctp partial reliability</dt>
  <dd>This extension allows one to have message be skipped and not delivered
      based on some user specified parameters.</dd>
  <dt>sctp dynamic addressing</dt>
  <dd>This extension allows addresses to be added and deleted dynamically from
      an existing association.</dd>
  <dt>sctp authentication</dt>
  <dd>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.</dd>
  <dt>packet drop</dt>
  <dd>Some routers support a special satellite protocol that will report losses
      due to corruption. This allows retransmissions without subsequent loss in
      bandwidth utilization.</dd>
  <dt>stream reset</dt>
  <dd>This extension allows a user on either side to reset the stream sequence
      numbers used by any or all streams.</dd>
</dl>
<p class="Pp">SCTP supports a number of socket options which can be set with
    <a class="Xr">setsockopt(2)</a> and tested with
    <a class="Xr">getsockopt(2)</a> or <a class="Xr">sctp_opt_info(3)</a>:</p>
<dl class="Bl-tag">
  <dt id="SCTP_NODELAY"><a class="permalink" href="#SCTP_NODELAY"><code class="Dv">SCTP_NODELAY</code></a></dt>
  <dd>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
      <code class="Dv">SCTP_NODELAY</code> defeats this algorithm.</dd>
  <dt id="SCTP_RTOINFO"><a class="permalink" href="#SCTP_RTOINFO"><code class="Dv">SCTP_RTOINFO</code></a></dt>
  <dd>This option returns specific information about an associations
      &#x201C;Retransmission Time Out&#x201D;. It can also be used to change the
      default values.</dd>
  <dt id="SCTP_ASSOCINFO"><a class="permalink" href="#SCTP_ASSOCINFO"><code class="Dv">SCTP_ASSOCINFO</code></a></dt>
  <dd>This option returns specific information about the requested
    association.</dd>
  <dt id="SCTP_INITMSG"><a class="permalink" href="#SCTP_INITMSG"><code class="Dv">SCTP_INITMSG</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_AUTOCLOSE"><a class="permalink" href="#SCTP_AUTOCLOSE"><code class="Dv">SCTP_AUTOCLOSE</code></a></dt>
  <dd>For the one-to-many model (<code class="Dv">SOCK_SEQPACKET</code>)
      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).</dd>
  <dt id="SCTP_SET_PEER_PRIMARY_ADDR"><a class="permalink" href="#SCTP_SET_PEER_PRIMARY_ADDR"><code class="Dv">SCTP_SET_PEER_PRIMARY_ADDR</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_PRIMARY_ADDR"><a class="permalink" href="#SCTP_PRIMARY_ADDR"><code class="Dv">SCTP_PRIMARY_ADDR</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_ADAPTATION_LAYER"><a class="permalink" href="#SCTP_ADAPTATION_LAYER"><code class="Dv">SCTP_ADAPTATION_LAYER</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_DISABLE_FRAGMENTS"><a class="permalink" href="#SCTP_DISABLE_FRAGMENTS"><code class="Dv">SCTP_DISABLE_FRAGMENTS</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_PEER_ADDR_PARAMS"><a class="permalink" href="#SCTP_PEER_ADDR_PARAMS"><code class="Dv">SCTP_PEER_ADDR_PARAMS</code></a></dt>
  <dd>This option will allow a user to set or get specific peer address
      parameters.</dd>
  <dt id="SCTP_DEFAULT_SEND_PARAM"><a class="permalink" href="#SCTP_DEFAULT_SEND_PARAM"><code class="Dv">SCTP_DEFAULT_SEND_PARAM</code></a></dt>
  <dd>When a user does not use one of the extended send calls (e.g.,
      <a class="Xr">sctp_sendmsg(3)</a>) 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).</dd>
  <dt id="SCTP_EVENTS"><a class="permalink" href="#SCTP_EVENTS"><code class="Dv">SCTP_EVENTS</code></a></dt>
  <dd>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 <code class="Dv">MSG_NOTIFICATION</code> 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.</dd>
  <dt id="SCTP_I_WANT_MAPPED_V4_ADDR"><a class="permalink" href="#SCTP_I_WANT_MAPPED_V4_ADDR"><code class="Dv">SCTP_I_WANT_MAPPED_V4_ADDR</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_MAXSEG"><a class="permalink" href="#SCTP_MAXSEG"><code class="Dv">SCTP_MAXSEG</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_DELAYED_ACK_TIME"><a class="permalink" href="#SCTP_DELAYED_ACK_TIME"><code class="Dv">SCTP_DELAYED_ACK_TIME</code></a></dt>
  <dd>This option lets the user both set and get the delayed ack time (in
      milliseconds) that SCTP is using. The default is 200 milliseconds.</dd>
  <dt id="SCTP_PARTIAL_DELIVERY_POINT"><a class="permalink" href="#SCTP_PARTIAL_DELIVERY_POINT"><code class="Dv">SCTP_PARTIAL_DELIVERY_POINT</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_FRAGMENT_INTERLEAVE"><a class="permalink" href="#SCTP_FRAGMENT_INTERLEAVE"><code class="Dv">SCTP_FRAGMENT_INTERLEAVE</code></a></dt>
  <dd>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).</dd>
  <dt id="SCTP_AUTH_CHUNK"><a class="permalink" href="#SCTP_AUTH_CHUNK"><code class="Dv">SCTP_AUTH_CHUNK</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_AUTH_KEY"><a class="permalink" href="#SCTP_AUTH_KEY"><code class="Dv">SCTP_AUTH_KEY</code></a></dt>
  <dd>This option allows a user to specify a shared key that can be later used
      to authenticate a peer.</dd>
  <dt id="SCTP_HMAC_IDENT"><a class="permalink" href="#SCTP_HMAC_IDENT"><code class="Dv">SCTP_HMAC_IDENT</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_AUTH_ACTIVE_KEY"><a class="permalink" href="#SCTP_AUTH_ACTIVE_KEY"><code class="Dv">SCTP_AUTH_ACTIVE_KEY</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_AUTH_DELETE_KEY"><a class="permalink" href="#SCTP_AUTH_DELETE_KEY"><code class="Dv">SCTP_AUTH_DELETE_KEY</code></a></dt>
  <dd>This option allows you to delete an old key.</dd>
  <dt id="SCTP_USE_EXT_RECVINFO"><a class="permalink" href="#SCTP_USE_EXT_RECVINFO"><code class="Dv">SCTP_USE_EXT_RECVINFO</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_AUTO_ASCONF"><a class="permalink" href="#SCTP_AUTO_ASCONF"><code class="Dv">SCTP_AUTO_ASCONF</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_MAXBURST"><a class="permalink" href="#SCTP_MAXBURST"><code class="Dv">SCTP_MAXBURST</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_CONTEXT"><a class="permalink" href="#SCTP_CONTEXT"><code class="Dv">SCTP_CONTEXT</code></a></dt>
  <dd>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.</dd>
  <dt id="SCTP_EXPLICIT_EOR"><a class="permalink" href="#SCTP_EXPLICIT_EOR"><code class="Dv">SCTP_EXPLICIT_EOR</code></a></dt>
  <dd>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 <code class="Dv">SCTP_EOR</code> 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 <code class="Dv">SCTP_EOR</code> is passed
      to SCTP else an error will be returned.</dd>
  <dt id="SCTP_STATUS"><a class="permalink" href="#SCTP_STATUS"><code class="Dv">SCTP_STATUS</code></a></dt>
  <dd>This option is a read only option that returns various status information
      about the specified association.</dd>
  <dt id="SCTP_GET_PEER_ADDR_INFO"><a class="permalink" href="#SCTP_GET_PEER_ADDR_INFO"><code class="Dv">SCTP_GET_PEER_ADDR_INFO</code></a></dt>
  <dd>This read only option returns information about a peer address.</dd>
  <dt id="SCTP_PEER_AUTH_CHUNKS"><a class="permalink" href="#SCTP_PEER_AUTH_CHUNKS"><code class="Dv">SCTP_PEER_AUTH_CHUNKS</code></a></dt>
  <dd>This read only option returns a list of the chunks the peer requires to be
      authenticated.</dd>
  <dt id="SCTP_LOCAL_AUTH_CHUNKS"><a class="permalink" href="#SCTP_LOCAL_AUTH_CHUNKS"><code class="Dv">SCTP_LOCAL_AUTH_CHUNKS</code></a></dt>
  <dd>This read only option returns a list of the locally required chunks that
      must be authenticated.</dd>
  <dt id="SCTP_RESET_STREAMS"><a class="permalink" href="#SCTP_RESET_STREAMS"><code class="Dv">SCTP_RESET_STREAMS</code></a></dt>
  <dd>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.</dd>
</dl>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">accept(2)</a>, <a class="Xr">bind(2)</a>,
    <a class="Xr">connect(2)</a>, <a class="Xr">listen(2)</a>,
    <a class="Xr">sctp_bindx(3)</a>, <a class="Xr">sctp_connectx(3)</a>,
    <a class="Xr">sctp_opt_info(3)</a>, <a class="Xr">sctp_recvmsg(3)</a>,
    <a class="Xr">sctp_sendmsg(3)</a></p>
<p class="Pp"><cite class="Rs"><span class="RsT">Stream Control Transmission
    Protocol</span>, <span class="RsR">RFC</span>,
    <span class="RsN">4960</span>, <span class="RsD">September
    2007</span>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">sctp</code> protocol appeared in
    <span class="Ux">NetBSD 8.0</span>.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">July 31, 2018</td>
    <td class="foot-os">NetBSD 10.1</td>
  </tr>
</table>