*

Linux Fedora Core 5.0 (kernel 2.6.15-2054 or later is needed)

*

Solaris 10, 11

*

SUSE Linux Enterprise Server 10 (x86_64) kernel 2.6.16.27-0.6-smp, with lksctp-tools-1.0.6

*

Briefly on Solaris 10

*

SUSE Linux Enterprise Server 10 Service Pack 1 (x86_64) kernel 2.6.16.54-0.2.3-smp with lksctp-tools-1.0.7

*

FreeBSD 8.2

An opaque term returned in, for example, #sctp_paddr_change{}, which identifies an association for an SCTP socket. The term is opaque except for the special value 0, which has a meaning such as "the whole endpoint" or "all future associations".

One of the SCTP Socket Options.

Socket identifier returned from open/*.

Types:

Abnormally terminates the association specified by Assoc, without flushing of unsent data. The socket itself remains open. Other associations opened on this socket are still valid, and the socket can be used in new associations.

Types:

Closes the socket and all associations on it. The unsent data is flushed as in eof/2. The close/1 call is blocking or otherwise depending of the value of the linger socket option. If close does not linger or linger time-out expires, the call returns and the data is flushed in the background.

Types:

Same as connect(Socket, Addr, Port, Opts, infinity).

Types:

Establishes a new association for socket Socket, with the peer (SCTP server socket) specified by Addr and Port. Timeout, is expressed in milliseconds. A socket can be associated with multiple peers.

The result of connect/* is an #sctp_assoc_change{} event that contains, in particular, the new Association ID:

#sctp_assoc_change{
      state             = atom(),
      error             = integer(),
      outbound_streams  = integer(),
      inbound_streams   = integer(),
      assoc_id          = assoc_id()
}

The number of outbound and inbound streams can be set by giving an sctp_initmsg option to connect as in:

connect(Socket, Ip, Port>,
      [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
                                   max_instreams=MaxInStreams}}])

All options Opt are set on the socket before the association is attempted. If an option record has undefined field values, the options record is first read from the socket for those values. In effect, Opt option records only define field values to change before connecting.

The returned outbound_streams and inbound_streams are the stream numbers on the socket. These can be different from the requested values (OutStreams and MaxInStreams, respectively) if the peer requires lower values.

state can have the following values:

Other states do not normally occur in the output from connect/*. Rather, they can occur in #sctp_assoc_change{} events received instead of data in recv/* calls. All of them indicate losing the association because of various error conditions, and are listed here for the sake of completeness:

Field error can provide more detailed diagnostics. The error field value can be converted into a string using error_string/1.

Types:

Same as connect_init(Socket, Addr, Port, Opts, infinity).

Types:

Initiates a new association for socket Socket, with the peer (SCTP server socket) specified by Addr and Port.

The fundamental difference between this API and connect/* is that the return value is that of the underlying OS connect(2) system call. If ok is returned, the result of the association establishment is received by the calling process as an #sctp_assoc_change{} event. The calling process must be prepared to receive this, or poll for it using recv/*, depending on the value of the active option.

The parameters are as described in connect/*, except the Timeout value.

The timer associated with Timeout only supervises IP resolution of Addr.

Types:

Assigns a new controlling process Pid to Socket. Same implementation as gen_udp:controlling_process/2.

Types:

Gracefully terminates the association specified by Assoc, with flushing of all unsent data. The socket itself remains open. Other associations opened on this socket are still valid. The socket can be used in new associations.

Types:

Translates an SCTP error number from, for example, #sctp_remote_error{} or #sctp_send_failed{} into an explanatory string, or one of the atoms ok for no error or undefined for an unrecognized error.

Types:

Sets up a socket to listen on the IP address and port number it is bound to.

For type seqpacket, sockets (the default) IsServer must be true or false. In contrast to TCP, there is no listening queue length in SCTP. If IsServer is true, the socket accepts new associations, that is, it becomes an SCTP server socket.

For type stream, sockets Backlog define the backlog queue length just like in TCP.

Types:

Creates an SCTP socket and binds it to the local addresses specified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this feature is called SCTP multi-homing). The default IP and Port are any and 0, meaning bind to all local addresses on any free port.

Other options:

A default set of socket options is used. In particular, the socket is opened in binary and passive mode, with SockType seqpacket, and with reasonably large kernel and driver buffers.

If the socket is in passive mode data can be received through the recv/1,2 calls.

If the socket is in active mode data received data is delivered to the controlling process as messages:

{sctp, Socket, FromIP, FromPort, {AncData, Data}}
	

See recv/1,2 for a description of the message fields.

Types:

Branches off an existing association Assoc in a socket Socket of type seqpacket (one-to-many style) into a new socket NewSocket of type stream (one-to-one style).

The existing association argument Assoc can be either a #sctp_assoc_change{} record as returned from, for example, recv/*, connect/*, or from a listening socket in active mode. It can also be just the field assoc_id integer from such a record.

Types:

Receives the Data message from any association of the socket. If the receive times out, {error,timeout} is returned. The default time-out is infinity. FromIP and FromPort indicate the address of the sender.

AncData is a list of ancillary data items that can be received along with the main Data. This list can be empty, or contain a single #sctp_sndrcvinfo{} record if receiving of such ancillary data is enabled (see option sctp_events). It is enabled by default, as such ancillary data provides an easy way of determining the association and stream over which the message is received. (An alternative way is to get the association ID from FromIP and FromPort using socket option sctp_get_peer_addr_info, but this does still not produce the stream number).

AncData may also contain ancillary data from the socket options recvtos, recvtclass or recvttl, if that is supported by the platform for the socket.

The Data received can be a binary() or a list() of bytes (integers in the range 0 through 255) depending on the socket mode, or an SCTP event.

Possible SCTP events:

#sctp_paddr_change{
      addr      = {ip_address(),port()},
      state     = atom(),
      error     = integer(),
      assoc_id  = assoc_id()
}

#sctp_send_failed{
      flags     = true | false,
      error     = integer(),
      info      = #sctp_sndrcvinfo{},
      assoc_id  = assoc_id()
      data      = binary()
}

#sctp_adaptation_event{
      adaptation_ind = integer(),
      assoc_id       = assoc_id()
}

#sctp_pdapi_event{
      indication = sctp_partial_delivery_aborted,
      assoc_id   = assoc_id()
}

Types:

Sends the Data message with all sending parameters from a #sctp_sndrcvinfo{} record. This way, the user can specify the PPID (passed to the remote end) and context (passed to the local SCTP layer), which can be used, for example, for error identification. However, such a fine level of user control is rarely required. The function send/4 is sufficient for most applications.

Types:

Sends a Data message over an existing association and specified stream.

{mode, list|binary} or just list or binary:

Determines the type of data returned from recv/1,2.

{active, true|false|once|N}:

{tos, integer()}:

Sets the Type-Of-Service field on the IP datagrams that are sent, to the specified value. This effectively determines a prioritization policy for the outbound packets. The acceptable values are system-dependent.

{priority, integer()}:

A protocol-independent equivalent of tos above. Setting priority implies setting tos as well.

{dontroute, true|false}:

Defaults to false. If true, the kernel does not send packets through any gateway, only sends them to directly connected hosts.

{reuseaddr, true|false}:

Defaults to false. If true, the local binding address {IP,Port} of the socket can be reused immediately. No waiting in state CLOSE_WAIT is performed (can be required for high-throughput servers).

{sndbuf, integer()}:

The size, in bytes, of the OS kernel send buffer for this socket. Sending errors would occur for datagrams larger than val(sndbuf). Setting this option also adjusts the size of the driver buffer (see buffer above).

{recbuf, integer()}:

The size, in bytes, of the OS kernel receive buffer for this socket. Sending errors would occur for datagrams larger than val(recbuf). Setting this option also adjusts the size of the driver buffer (see buffer above).

{sctp_module, module()}:

Overrides which callback module is used. Defaults to inet_sctp for IPv4 and inet6_sctp for IPv6.

{sctp_rtoinfo, #sctp_rtoinfo{}}:

#sctp_rtoinfo{
      assoc_id = assoc_id(),
      initial  = integer(),
      max      = integer(),
      min      = integer()
}

{sctp_associnfo, #sctp_assocparams{}}:

#sctp_assocparams{
      assoc_id                 = assoc_id(),
      asocmaxrxt               = integer(),
      number_peer_destinations = integer(),
      peer_rwnd                = integer(),
      local_rwnd               = integer(),
      cookie_life              = integer()
}

{sctp_initmsg, #sctp_initmsg{}}:

#sctp_initmsg{
     num_ostreams   = integer(),
     max_instreams  = integer(),
     max_attempts   = integer(),
     max_init_timeo = integer()
}

{sctp_autoclose, integer() >= 0}:

Determines the time, in seconds, after which an idle association is automatically closed. 0 means that the association is never automatically closed.

{sctp_nodelay, true|false}:

Turns on|off the Nagle algorithm for merging small packets into larger ones. This improves throughput at the expense of latency.

{sctp_disable_fragments, true|false}:

If true, induces an error on an attempt to send a message larger than the current PMTU size (which would require fragmentation/reassembling). Notice that message fragmentation does not affect the logical atomicity of its delivery; this option is provided for performance reasons only.

{sctp_i_want_mapped_v4_addr, true|false}:

Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if the socket address family is AF_INET6).

{sctp_maxseg, integer()}:

Determines the maximum chunk size if message fragmentation is used. If 0, the chunk size is limited by the Path MTU only.

{sctp_primary_addr, #sctp_prim{}}:

#sctp_prim{
      assoc_id = assoc_id(),
      addr     = {IP, Port}
}
 IP = ip_address()
 Port = port_number()

{sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:

#sctp_setpeerprim{
      assoc_id = assoc_id(),
      addr     = {IP, Port}
}
 IP = ip_address()
 Port = port_number()

{sctp_adaptation_layer, #sctp_setadaptation{}}:

#sctp_setadaptation{
      adaptation_ind = integer()
}

{sctp_peer_addr_params, #sctp_paddrparams{}}:

#sctp_paddrparams{
      assoc_id   = assoc_id(),
      address    = {IP, Port},
      hbinterval = integer(),
      pathmaxrxt = integer(),
      pathmtu    = integer(),
      sackdelay  = integer(),
      flags      = list()
}
IP = ip_address()
Port = port_number()

{sctp_default_send_param, #sctp_sndrcvinfo{}}:

#sctp_sndrcvinfo{
      stream     = integer(),
      ssn        = integer(),
      flags      = list(),
      ppid       = integer(),
      context    = integer(),
      timetolive = integer(),
      tsn        = integer(),
      cumtsn     = integer(),
      assoc_id   = assoc_id()
}

{sctp_events, #sctp_event_subscribe{}}:

#sctp_event_subscribe{
        data_io_event          = true | false,
        association_event      = true | false,
        address_event          = true | false,
        send_failure_event     = true | false,
        peer_error_event       = true | false,
        shutdown_event         = true | false,
        partial_delivery_event = true | false,
        adaptation_layer_event = true | false
}

{sctp_delayed_ack_time, #sctp_assoc_value{}}:

#sctp_assoc_value{
      assoc_id    = assoc_id(),
      assoc_value = integer()
}

{sctp_status, #sctp_status{}}:

#sctp_status{
      assoc_id            = assoc_id(),
      state               = atom(),
      rwnd                = integer(),
      unackdata           = integer(),
      penddata            = integer(),
      instrms             = integer(),
      outstrms            = integer(),
      fragmentation_point = integer(),
      primary             = #sctp_paddrinfo{}
}

{sctp_get_peer_addr_info, #sctp_paddrinfo{}}:

#sctp_paddrinfo{
      assoc_id  = assoc_id(),
      address   = {IP, Port},
      state     = inactive | active | unconfirmed,
      cwnd      = integer(),
      srtt      = integer(),
      rto       = integer(),
      mtu       = integer()
}
IP = ip_address()
Port = port_number()