.TH gen_sctp 3 "kernel  2.12.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
gen_sctp \- The gen_sctp module provides functions for communicating with sockets using the SCTP protocol\&.
.SH DESCRIPTION
.LP
The \fIgen_sctp\fR module provides functions for communicating with sockets using the SCTP protocol\&. The implementation assumes that the OS kernel supports SCTP (RFC2960) <http://www\&.rfc-archive\&.org/getrfc\&.php?rfc=2960> through the user-level Sockets API Extensions\&. <http://tools\&.ietf\&.org/html/draft-ietf-tsvwg-sctpsocket-13> During development this implementation was tested on Linux Fedora Core 5\&.0 (kernel 2\&.6\&.15-2054 or later is needed), and on Solaris 10, 11\&. During OTP adaptation it was tested on 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, and later on 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\&.
.LP
Record definitions for the \fIgen_sctp\fR module can be found using:

.nf
  -include_lib("kernel/include/inet_sctp\&.hrl")\&.    
.fi
.LP
These record definitions use the "new" spelling \&'adaptation\&', not the deprecated \&'adaption\&', regardless of which spelling the underlying C API uses\&.

.SH CONTENTS
.RS 2
.TP 2
*
DATA TYPES
.TP 2
*
EXPORTS
.TP 2
*
SCTP SOCKET OPTIONS
.TP 2
*
SCTP EXAMPLES
.TP 2
*
SEE ALSO
.TP 2
*
AUTHORS
.RE
.SH DATA TYPES
.RS 2
.TP 4
.B
\fIassoc_id()\fR:
An opaque term returned in for example #sctp_paddr_change{} that identifies an association for an SCTP socket\&. The term is opaque except for the special value \fI0\fR that has a meaning such as "the whole endpoint" or "all future associations"\&.
.RS 4
.LP

.RE
.TP 4
.B
\fIcharlist() = [char()]\fR:

.TP 4
.B
\fIiolist() = [char() | binary()]\fR:

.TP 4
.B
\fIip_address()\fR:
Represents an address of an SCTP socket\&. It is a tuple as explained in inet(3)\&.
.RS 4
.LP

.RE
.TP 4
.B
\fIport_number() = 0 \&.\&. 65535\fR:

.TP 4
.B
\fIposix()\fR:
See inet(3); POSIX Error Codes\&.
.RS 4
.LP

.RE
.TP 4
.B
\fIsctp_option()\fR:
One of the SCTP Socket Options\&.
.RS 4
.LP

.RE
.TP 4
.B
\fIsctp_socket()\fR:
Socket identifier returned from \fIopen/*\fR\&.
.RS 4
.LP

.RE
.TP 4
.B
\fItimeout() = int() | infinity\fR:
Timeout used in SCTP connect and receive calls\&.
.RE
.SH EXPORTS
.LP
.B
abort(sctp_socket(), Assoc) -> ok | {error, posix()}
.br
.RS
.TP
Types
Assoc = #sctp_assoc_change{}
.br
.RE
.RS
.LP
Abnormally terminates the association given by \fIAssoc\fR, without flushing of unsent data\&. The socket itself remains open\&. Other associations opened on this socket are still valid, and it can be used in new associations\&.
.RE
.LP
.B
close(sctp_socket()) -> ok | {error, posix()}
.br
.RS
.LP
Completely closes the socket and all associations on it\&. The unsent data is flushed as in \fIeof/2\fR\&. The \fIclose/1\fR call is blocking or otherwise depending of the value of the linger socket option\&. If \fIclose\fR does not linger or linger timeout expires, the call returns and the data is flushed in the background\&.
.RE
.LP
.B
connect(Socket, Addr, Port, Opts) -> {ok,Assoc} | {error, posix()}
.br
.RS
.LP
Same as \fIconnect(Socket, Addr, Port, Opts, infinity)\fR\&.
.RE
.LP
.B
connect(Socket, Addr, Port, [Opt], Timeout) -> {ok, Assoc} | {error, posix()}
.br
.RS
.TP
Types
Socket = sctp_socket()
.br
Addr = ip_address() | Host
.br
Port = port_number()
.br
Opt = sctp_option()
.br
Timeout = timeout()
.br
Host = atom() | string()
.br
Assoc = #sctp_assoc_change{}
.br
.RE
.RS
.LP
Establishes a new association for the socket \fISocket\fR, with the peer (SCTP server socket) given by \fIAddr\fR and \fIPort\fR\&. The \fITimeout\fR, is expressed in milliseconds\&.
.LP
A socket can be associated with multiple peers\&.  The result of \fIconnect/*\fR is an \fI#sctp_assoc_change{}\fR event which contains, in particular, the new Association ID:

.nf
  #sctp_assoc_change{
        state             = atom(),
        error             = atom(),
        outbound_streams  = int(),
        inbound_streams   = int(),
        assoc_id          = assoc_id()
  }        
.fi
.LP
The number of outbound and inbound streams can be set by giving an \fIsctp_initmsg\fR option to \fIconnect\fR as in:

.nf
  connect(Socket, Ip, Port,
        [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
                                     max_instreams=MaxInStreams}}])        
.fi
.LP
All options \fIOpt\fR are set on the socket before the association is attempted\&. If an option record has got undefined field values, the options record is first read from the socket for those values\&. In effect, \fIOpt\fR option records only define field values to change before connecting\&.
.LP
The returned \fIoutbound_streams\fR and \fIinbound_streams\fR are the actual stream numbers on the socket, which may be different from the requested values (\fIOutStreams\fR and \fIMaxInStreams\fR respectively) if the peer requires lower values\&.
.LP
The following values of \fIstate\fR are possible:
.RS 2
.TP 2
*
\fIcomm_up\fR: association successfully established\&. This indicates a successful completion of \fIconnect\fR\&.
.TP 2
*
\fIcant_assoc\fR: association cannot be established (\fIconnect/*\fR failure)\&.
.RE
.LP
All other states do not normally occur in the output from \fIconnect/*\fR\&. Rather, they may occur in \fI#sctp_assoc_change{}\fR events received instead of data in recv/* calls\&. All of them indicate losing the association due to various error conditions, and are listed here for the sake of completeness\&. The \fIerror\fR field may provide more detailed diagnostics\&.
.RS 2
.TP 2
*
\fIcomm_lost\fR;
.TP 2
*
\fIrestart\fR;
.TP 2
*
\fIshutdown_comp\fR\&.
.RE
.RE
.LP
.B
controlling_process(sctp_socket(), pid()) -> ok
.br
.RS
.LP
Assigns a new controlling process Pid to Socket\&. Same implementation as \fIgen_udp:controlling_process/2\fR\&.
.RE
.LP
.B
eof(Socket, Assoc) -> ok | {error, Reason}
.br
.RS
.TP
Types
Socket = sctp_socket()
.br
Assoc = #sctp_assoc_change{}
.br
.RE
.RS
.LP
Gracefully terminates the association given by \fIAssoc\fR, with flushing of all unsent data\&. The socket itself remains open\&. Other associations opened on this socket are still valid, and it can be used in new associations\&.
.RE
.LP
.B
listen(Socket, IsServer) -> ok | {error, Reason}
.br
.RS
.TP
Types
Socket = sctp_socket()
.br
IsServer = bool()
.br
.RE
.RS
.LP
Sets up a socket to listen on the IP address and port number it is bound to\&. IsServer must be \&'true\&' or \&'false\&'\&. In the contrast to TCP, in SCTP there is no listening queue length\&. If IsServer is \&'true\&' the socket accepts new associations, i\&.e\&. it will become an SCTP server socket\&.
.RE
.LP
.B
open() -> {ok, Socket} | {error, posix()}
.br
.B
open(Port) -> {ok, Socket} | {error, posix()}
.br
.B
open([Opt]) -> {ok, Socket} | {error, posix()}
.br
.B
open(Port, [Opt]) -> {ok, Socket} | {error, posix()}
.br
.RS
.TP
Types
Opt = {ip, IP} | {ifaddr, IP} | {port, Port} | sctp_option()
.br
IP = ip_address() | any | loopback
.br
Port = port_number()
.br
.RE
.RS
.LP
Creates an SCTP socket and binds it to the local addresses specified by all \fI{ip, IP}\fR (or synonymously \fI{ifaddr, IP}\fR) options (this feature is called SCTP multi-homing)\&. The default \fIIP\fR and \fIPort\fR are \fIany\fR and \fI0\fR, meaning bind to all local addresses on any one free port\&.
.LP
A default set of socket options is used\&. In particular, the socket is opened in binary and passive mode, and with reasonably large kernel and driver buffers\&.
.RE
.LP
.B
recv(sctp_socket()) -> {ok, {FromIP, FromPort, AncData, BinMsg}} | {error, Reason}
.br
.B
recv(sctp_socket(), timeout()) -> {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
.br
.RS
.TP
Types
FromIP = ip_address()
.br
FromPort = port_number()
.br
AncData = [#sctp_sndrcvinfo{}]
.br
Data = binary() | charlist() | #sctp_sndrcvinfo{} | #sctp_assoc_change{} | #sctp_paddr_change{} | #sctp_adaptation_event{} 
.br
Reason = posix() | #sctp_send_failed{} | #scpt_paddr_change{} | #sctp_pdapi_event{} | #sctp_remote_error{} | #sctp_shutdown_event{}
.br
.RE
.RS
.LP
Receives the \fIData\fR message from any association of the socket\&. If the receive times out \fI{error, timeout\fR is returned\&. The default timeout is \fIinfinity\fR\&. \fIFromIP\fR and \fIFromPort\fR indicate the sender\&'s address\&.
.LP
\fIAncData\fR is a list of Ancillary Data items which may be received along with the main \fIData\fR\&. 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, since such ancillary data provide an easy way of determining the association and stream over which the message has been received\&. (An alternative way would be to get the Association ID from the \fIFromIP\fR and \fIFromPort\fR using the sctp_get_peer_addr_info socket option, but this would still not produce the Stream number)\&.
.LP
The actual \fIData\fR received may be a \fIbinary()\fR, or \fIlist()\fR of bytes (integers in the range 0 through 255) depending on the socket mode, or an SCTP Event\&.  The following SCTP Events are possible:
.RS 2
.TP 2
*
#sctp_sndrcvinfo{}
.TP 2
*
#sctp_assoc_change{};
.TP 2
*

.nf
  #sctp_paddr_change{
        addr      = ip_address(),
        state     = atom(),
        error     = int(),
        assoc_id  = assoc_id()
  }            
.fi
.RS 2
.LP

.LP
Indicates change of the status of the peer\&'s IP address given by \fIaddr\fR within the association \fIassoc_id\fR\&. Possible values of \fIstate\fR (mostly self-explanatory) include:
.LP

.RS 2
.TP 2
-
\fIaddr_unreachable\fR;
.TP 2
-
\fIaddr_available\fR;
.TP 2
-
\fIaddr_removed\fR;
.TP 2
-
\fIaddr_added\fR;
.TP 2
-
\fIaddr_made_prim\fR\&.
.RE
.LP

.LP
In case of an error (e\&.g\&. \fIaddr_unreachable\fR), the \fIerror\fR field provides additional diagnostics\&. In such cases, the \fI#sctp_paddr_change{}\fR Event is automatically converted into an \fIerror\fR term returned by \fIgen_sctp:recv\fR\&. The \fIerror\fR field value can be converted into a string using \fIerror_string/1\fR\&.
.RE
.TP 2
*

.nf
  #sctp_send_failed{
        flags     = true | false,
        error     = int(),
        info      = #sctp_sndrcvinfo{},
        assoc_id  = assoc_id()
        data      = binary()
  }            
.fi
.RS 2
.LP

.LP
The sender may receive this event if a send operation fails\&. The \fIflags\fR is a Boolean specifying whether the data have actually been transmitted over the wire; \fIerror\fR provides extended diagnostics, use \fIerror_string/1\fR; \fIinfo\fR is the original #sctp_sndrcvinfo{} record used in the failed send/*, and \fIdata\fR is the whole original data chunk attempted to be sent\&.
.LP

.LP
In the current implementation of the Erlang/SCTP binding, this Event is internally converted into an \fIerror\fR term returned by \fIrecv/*\fR\&.
.RE
.TP 2
*

.nf
  #sctp_adaptation_event{
        adaptation_ind = int(),
        assoc_id       = assoc_id()
  }            
.fi
.RS 2
.LP

.LP
Delivered when a peer sends an Adaptation Layer Indication parameter (configured through the option sctp_adaptation_layer)\&. Note that with the current implementation of the Erlang/SCTP binding, this event is disabled by default\&.
.RE
.TP 2
*

.nf
  #sctp_pdapi_event{
        indication = sctp_partial_delivery_aborted,
        assoc_id   = assoc_id()
  }            
.fi
.RS 2
.LP

.LP
A partial delivery failure\&. In the current implementation of the Erlang/SCTP binding, this Event is internally converted into an \fIerror\fR term returned by \fIrecv/*\fR\&.
.RE
.RE
.RE
.LP
.B
send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
.br
.RS
.TP
Types
Socket = sctp_socket()
.br
SndRcvInfo = #sctp_sndrcvinfo{}
.br
Data = binary() | iolist()
.br
.RE
.RS
.LP
Sends the \fIData\fR 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 send/4 function is sufficient for most applications\&.
.RE
.LP
.B
send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
.br
.RS
.TP
Types
Socket = sctp_socket()
.br
Assoc = #sctp_assoc_change{} | assoc_id()
.br
Stream = integer()
.br
Data = binary() | iolist()
.br
.RE
.RS
.LP
Sends \fIData\fR message over an existing association and given stream\&.
.RE
.LP
.B
error_string(integer()) -> ok | string() | undefined
.br
.RS
.LP
Translates an SCTP error number from for example \fI#sctp_remote_error{}\fR or \fI#sctp_send_failed{}\fR into an explanatory string, or one of the atoms \fIok\fR for no error and \fIundefined\fR for an unrecognized error\&.
.RE
.SH SCTP SOCKET OPTIONS
.LP
The set of admissible SCTP socket options is by construction orthogonal to the sets of TCP, UDP and generic INET options: only those options which are explicitly listed below are allowed for SCTP sockets\&. Options can be set on the socket using \fIgen_sctp:open/1, 2\fR or \fIinet:setopts/2\fR, retrieved using \fIinet:getopts/2\fR, and when calling \fIgen_sctp:connect/4, 5\fR options can be changed\&.
.RS 2
.TP 4
.B
\fI{mode, list|binary}\fRor just \fIlist\fR or \fIbinary\fR\&.:
Determines the type of data returned from \fIgen_sctp:recv/1, 2\fR\&.
.RS 4
.LP

.RE
.TP 4
.B
\fI{active, true|false|once}\fR:
.RS 2
.TP 2
*
If \fIfalse\fR (passive mode, the default), the caller needs to do an explicit \fIgen_sctp:recv\fR call in order to retrieve the available data from the socket\&.
.TP 2
*
If \fItrue\fR (full active mode), the pending data or events are sent to the owning process\&.
.RS 2
.LP

.LP
\fINB:\fR This can cause the message queue to overflow, as there is no way to throttle the sender in this case (no flow control!)\&.
.RE
.TP 2
*
If \fIonce\fR, only one message is automatically placed in the message queue, after that the mode is automatically re-set to passive\&. This provides flow control as well as the possibility for the receiver to listen for its incoming SCTP data interleaved with other inter-process messages\&.
.RE
.RS 4
.LP

.RE
.TP 4
.B
\fI{buffer, int()}\fR:
Determines the size of the user-level software buffer used by the SCTP driver\&. Not to be confused with \fIsndbuf\fR and \fIrecbuf\fR options which correspond to the kernel socket buffers\&. It is recommended to have \fIval(buffer) >= max(val(sndbuf), val(recbuf))\fR\&. In fact, the \fIval(buffer)\fR is automatically set to the above maximum when \fIsndbuf\fR or \fIrecbuf\fR values are set\&.
.TP 4
.B
\fI{tos, int()}\fR:
Sets the Type-Of-Service field on the IP datagrams being sent, to the given value, which effectively determines a prioritization policy for the outbound packets\&. The acceptable values are system-dependent\&. TODO: we do not provide symbolic names for these values yet\&.
.TP 4
.B
\fI{priority, int()}\fR:
A protocol-independent equivalent of \fItos\fR above\&. Setting priority implies setting tos as well\&.
.TP 4
.B
\fI{dontroute, true|false}\fR:
By default \fIfalse\fR\&. If \fItrue\fR, the kernel does not send packets via any gateway, only sends them to directly connected hosts\&.
.TP 4
.B
\fI{reuseaddr, true|false}\fR:
By default \fIfalse\fR\&. If true, the local binding address \fI{IP, Port}\fR of the socket can be re-used immediately: no waiting in the CLOSE_WAIT state is performed (may be required for high-throughput servers)\&.
.RS 4
.LP

.RE
.TP 4
.B
\fI{linger, {true|false, int()}\fR:
Determines the timeout in seconds for flushing unsent data in the \fIgen_sctp:close/1\fR socket call\&. If the 1st component of the value tuple is \fIfalse\fR, the 2nd one is ignored, which means that \fIgen_sctp:close/1\fR returns immediately not waiting for data to be flushed\&. Otherwise, the 2nd component is the flushing time-out in seconds\&.
.RS 4
.LP

.RE
.TP 4
.B
\fI{sndbuf, int()}\fR:
The size, in bytes, of the *kernel* send buffer for this socket\&. Sending errors would occur for datagrams larger than \fIval(sndbuf)\fR\&. Setting this option also adjusts the size of the driver buffer (see \fIbuffer\fR above)\&.
.TP 4
.B
\fI{recbuf, int()}\fR:
The size, in bytes, of the *kernel* recv buffer for this socket\&. Sending errors would occur for datagrams larger than \fIval(sndbuf)\fR\&. Setting this option also adjusts the size of the driver buffer (see \fIbuffer\fR above)\&.
.TP 4
.B
\fI{sctp_rtoinfo, #sctp_rtoinfo{}}\fR:

.nf
  #sctp_rtoinfo{
        assoc_id = assoc_id(),
        initial  = int(),
        max      = int(),
        min      = int()
  }        
.fi
.RS 4
.LP

.LP
Determines re-transmission time-out parameters, in milliseconds, for the association(s) given by \fIassoc_id\fR\&. If \fIassoc_id = 0\fR (default) indicates the whole endpoint\&. See RFC2960 <http://www\&.rfc-archive\&.org/getrfc\&.php?rfc=2960> and Sockets API Extensions for SCTP <http://tools\&.ietf\&.org/html/draft-ietf-tsvwg-sctpsocket-13> for the exact semantics of the fields values\&.
.RE
.TP 4
.B
\fI{sctp_associnfo, #sctp_assocparams{}}\fR:

.nf
  #sctp_assocparams{
        assoc_id                 = assoc_id(),
        asocmaxrxt               = int(),
        number_peer_destinations = int(),
        peer_rwnd                = int(),
        local_rwnd               = int(),
        cookie_life              = int()
  }        
.fi
.RS 4
.LP

.LP
Determines association parameters for the association(s) given by \fIassoc_id\fR\&. \fIassoc_id = 0\fR (default) indicates the whole endpoint\&. See Sockets API Extensions for SCTP <http://tools\&.ietf\&.org/html/draft-ietf-tsvwg-sctpsocket-13> for the discussion of their semantics\&. Rarely used\&.
.RE
.TP 4
.B
\fI{sctp_initmsg, #sctp_initmsg{}}\fR:

.nf
  #sctp_initmsg{
       num_ostreams   = int(),
       max_instreams  = int(),
       max_attempts   = int(),
       max_init_timeo = int()
  }        
.fi
.RS 4
.LP

.LP
Determines the default parameters which this socket attempts to negotiate with its peer while establishing an association with it\&. Should be set after \fIopen/*\fR but before the first \fIconnect/*\fR\&. \fI#sctp_initmsg{}\fR can also be used as ancillary data with the first call of \fIsend/*\fR to a new peer (when a new association is created)\&.
.LP

.RS 2
.TP 2
*
\fInum_ostreams\fR: number of outbound streams;
.TP 2
*
\fImax_instreams\fR: max number of in-bound streams;
.TP 2
*
\fImax_attempts\fR: max re-transmissions while establishing an association;
.TP 2
*
\fImax_init_timeo\fR: time-out in milliseconds for establishing an association\&.
.RE
.LP

.LP

.RE
.TP 4
.B
\fI{sctp_autoclose, int()|infinity}\fR:
Determines the time (in seconds) after which an idle association is automatically closed\&.
.TP 4
.B
\fI{sctp_nodelay, true|false}\fR:
Turns on|off the Nagle algorithm for merging small packets into larger ones (which improves throughput at the expense of latency)\&.
.TP 4
.B
\fI{sctp_disable_fragments, true|false}\fR:
If \fItrue\fR, induces an error on an attempt to send a message which is larger than the current PMTU size (which would require fragmentation/re-assembling)\&. Note that message fragmentation does not affect the logical atomicity of its delivery; this option is provided for performance reasons only\&.
.TP 4
.B
\fI{sctp_i_want_mapped_v4_addr, true|false}\fR:
Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if the socket address family is AF_INET6)\&.
.TP 4
.B
\fI{sctp_maxseg, int()}\fR:
Determines the maximum chunk size if message fragmentation is used\&. If \fI0\fR, the chunk size is limited by the Path MTU only\&.
.TP 4
.B
\fI{sctp_primary_addr, #sctp_prim{}}\fR:

.nf
  #sctp_prim{
        assoc_id = assoc_id(),
        addr     = {IP, Port}
  }
  IP = ip_address()
  Port = port_number()        
.fi
.RS 4
.LP

.LP
For the association given by \fIassoc_id\fR, \fI{IP, Port}\fR must be one of the peer\&'s addresses\&. This option determines that the given address is treated by the local SCTP stack as the peer\&'s primary address\&.
.RE
.TP 4
.B
\fI{sctp_set_peer_primary_addr, #sctp_setpeerprim{}}\fR:

.nf
  #sctp_setpeerprim{
        assoc_id = assoc_id(),
        addr     = {IP, Port}
  }
  IP = ip_address()
  Port = port_number()        
.fi
.RS 4
.LP

.LP
When set, informs the peer that it should use \fI{IP, Port}\fR as the primary address of the local endpoint for the association given by \fIassoc_id\fR\&.
.LP

.RE
.TP 4
.B
\fI{sctp_adaptation_layer, #sctp_setadaptation{}}\fR:
 
.RS 4

.nf
  #sctp_setadaptation{
        adaptation_ind = int()
  }        
.fi
.LP

.LP
When set, requests that the local endpoint uses the value given by \fIadaptation_ind\fR as the Adaptation Indication parameter for establishing new associations\&. See RFC2960 <http://www\&.rfc-archive\&.org/getrfc\&.php?rfc=2960> and Sockets API Extenstions for SCTP <http://tools\&.ietf\&.org/html/draft-ietf-tsvwg-sctpsocket-13> for more details\&.
.RE
.TP 4
.B
\fI{sctp_peer_addr_params, #sctp_paddrparams{}}\fR:

.nf
  #sctp_paddrparams{
        assoc_id   = assoc_id(),
        address    = {IP, Port},
        hbinterval = int(),
        pathmaxrxt = int(),
        pathmtu    = int(),
        sackdelay  = int(),
        flags      = list()
  }
  IP = ip_address()
  Port = port_number()        
.fi
.RS 4
.LP

.LP
This option determines various per-address parameters for the association given by \fIassoc_id\fR and the peer address \fIaddress\fR (the SCTP protocol supports multi-homing, so more than 1 address can correspond to a given association)\&.
.LP

.RS 2
.TP 2
*
\fIhbinterval\fR: heartbeat interval, in milliseconds;
.TP 2
*
\fIpathmaxrxt\fR: max number of retransmissions before this address is considered unreachable (and an alternative address is selected);
.TP 2
*
\fIpathmtu\fR: fixed Path MTU, if automatic discovery is disabled (see \fIflags\fR below);
.TP 2
*
\fIsackdelay\fR: delay in milliseconds for SAC messages (if the delay is enabled, see \fIflags\fR below);
.TP 2
*
\fIflags\fR: the following flags are available:
.RS 2
.LP

.RS 2
.TP 2
-
\fIhb_enable\fR: enable heartbeat; 
.TP 2
-
\fIhb_disable\fR: disable heartbeat;
.TP 2
-
\fIhb_demand\fR: initiate heartbeat immediately;
.TP 2
-
\fIpmtud_enable\fR: enable automatic Path MTU discovery;
.TP 2
-
\fIpmtud_disable\fR: disable automatic Path MTU discovery;
.TP 2
-
\fIsackdelay_enable\fR: enable SAC delay;
.TP 2
-
\fIsackdelay_disable\fR: disable SAC delay\&.
.RE
.LP

.LP

.RE
.RE
.LP

.LP

.RE
.TP 4
.B
\fI{sctp_default_send_param, #sctp_sndrcvinfo{}}\fR:
 
.RS 4

.nf
  #sctp_sndrcvinfo{
        stream     = int(),
        ssn        = int(),
        flags      = list(),
        ppid       = int(),
        context    = int(),
        timetolive = int(),
        tsn        = int(),
        cumtsn     = int(),
        assoc_id   = assoc_id()
  }        
.fi
.LP

.LP
\fI#sctp_sndrcvinfo{}\fR is used both in this socket option, and as ancillary data while sending or receiving SCTP messages\&. When set as an option, it provides a default values for subsequent \fIgen_sctp:send\fRcalls on the association given by \fIassoc_id\fR\&. \fIassoc_id = 0\fR (default) indicates the whole endpoint\&. The following fields typically need to be specified by the sender:
.LP

.RS 2
.TP 2
*
\fIsinfo_stream\fR: stream number (0-base) within the association to send the messages through;
.TP 2
*
\fIsinfo_flags\fR: the following flags are recognised:
.RS 2
.LP

.RS 2
.TP 2
-
\fIunordered\fR: the message is to be sent unordered;
.TP 2
-
\fIaddr_over\fR: the address specified in \fIgen_sctp:send\fR overwrites the primary peer address;
.TP 2
-
\fIabort\fR: abort the current association without flushing any unsent data;
.TP 2
-
\fIeof\fR: gracefully shut down the current association, with flushing of unsent data\&.
.RE
.LP

.LP

.LP

.LP
Other fields are rarely used\&. See RFC2960 <http://www\&.rfc-archive\&.org/getrfc\&.php?rfc=2960> and Sockets API Extensions for SCTP <http://tools\&.ietf\&.org/html/draft-ietf-tsvwg-sctpsocket-13> for full information\&.
.RE
.RE
.LP

.LP

.LP

.RE
.TP 4
.B
\fI{sctp_events, #sctp_event_subscribe{}}\fR:
 
.RS 4

.nf
  #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
    }        
.fi
.LP

.LP
This option determines which SCTP Events are to be received (via recv/*) along with the data\&. The only exception is \fIdata_io_event\fR which enables or disables receiving of #sctp_sndrcvinfo{} ancillary data, not events\&. By default, all flags except \fIadaptation_layer_event\fR are enabled, although \fIsctp_data_io_event\fR and \fIassociation_event\fR are used by the driver itself and not exported to the user level\&.
.RE
.TP 4
.B
\fI{sctp_delayed_ack_time, #sctp_assoc_value{}}\fR:

.nf
  #sctp_assoc_value{
        assoc_id    = assoc_id(),
        assoc_value = int()
  }        
.fi
.RS 4
.LP

.LP
Rarely used\&. Determines the ACK time (given by \fIassoc_value\fR in milliseconds) for the given association or the whole endpoint if \fIassoc_value = 0\fR (default)\&.
.RE
.TP 4
.B
\fI{sctp_status, #sctp_status{}}\fR:

.nf
  #sctp_status{
        assoc_id            = assoc_id(),
        state               = atom(),
        rwnd                = int(),
        unackdata           = int(),
        penddata            = int(),
        instrms             = int(),
        outstrms            = int(),
        fragmentation_point = int(),
        primary             = #sctp_paddrinfo{}
  }        
.fi
.RS 4
.LP

.LP
This option is read-only\&. It determines the status of the SCTP association given by \fIassoc_id\fR\&. Possible values of \fIstate\fR follows\&. The state designations are mostly self-explanatory\&. \fIstate_empty\fR is the default which means that no other state is active:
.LP

.RS 2
.TP 2
*
\fIsctp_state_empty\fR
.TP 2
*
\fIsctp_state_closed\fR
.TP 2
*
\fIsctp_state_cookie_wait\fR
.TP 2
*
\fIsctp_state_cookie_echoed\fR
.TP 2
*
\fIsctp_state_established\fR
.TP 2
*
\fIsctp_state_shutdown_pending\fR
.TP 2
*
\fIsctp_state_shutdown_sent\fR
.TP 2
*
\fIsctp_state_shutdown_received\fR
.TP 2
*
\fIsctp_state_shutdown_ack_sent\fR
.RE
.LP

.LP
The semantics of other fields is the following:
.LP

.RS 2
.TP 2
*
\fIsstat_rwnd\fR: the association peer\&'s current receiver window size;
.TP 2
*
\fIsstat_unackdata\fR: number of unacked data chunks;
.TP 2
*
\fIsstat_penddata\fR: number of data chunks pending receipt;
.TP 2
*
\fIsstat_instrms\fR: number of inbound streams;
.TP 2
*
\fIsstat_outstrms\fR: number of outbound streams;
.TP 2
*
\fIsstat_fragmentation_point\fR: message size at which SCTP fragmentation will occur;
.TP 2
*
\fIsstat_primary\fR: information on the current primary peer address (see below for the format of \fI#sctp_paddrinfo{}\fR)\&.
.RE
.LP

.LP

.LP

.RE
.TP 4
.B
\fI{sctp_get_peer_addr_info, #sctp_paddrinfo{}}\fR:
 
.RS 4

.nf
  #sctp_paddrinfo{
        assoc_id  = assoc_id(),
        address   = {IP, Port},
        state     = inactive | active,
        cwnd      = int(),
        srtt      = int(),
        rto       = int(),
        mtu       = int()
  }
  IP = ip_address()
  Port = port_number()        
.fi
.LP

.LP
This option is read-only\&. It determines the parameters specific to the peer\&'s address given by \fIaddress\fR within the association given by \fIassoc_id\fR\&. The \fIaddress\fR field must be set by the caller; all other fields are filled in on return\&. If \fIassoc_id = 0\fR (default), the \fIaddress\fR is automatically translated into the corresponding association ID\&. This option is rarely used; see RFC2960 <http://www\&.rfc-archive\&.org/getrfc\&.php?rfc=2960> and Sockets API Extensions for SCTP <http://tools\&.ietf\&.org/html/draft-ietf-tsvwg-sctpsocket-13> for the semantics of all fields\&.
.RE
.RE
.SH SCTP EXAMPLES
.RS 2
.TP 2
*
Example of an Erlang SCTP Server which receives SCTP messages and prints them on the standard output:
.RS 2
.LP


.nf
  -module(sctp_server)\&.
  
  -export([server/0,server/1,server/2])\&.
  -include_lib("kernel/include/inet\&.hrl")\&.
  -include_lib("kernel/include/inet_sctp\&.hrl")\&.
  
  server() ->
      server([any,2006])\&.
  
  server([Host,Port]) when is_list(Host), is_list(Port) ->
      {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
      io:format("~w -> ~w~n", [Host, IP]),
      server([IP, list_to_integer(Port)]);
  
  server(IP, Port) when is_tuple(IP) orlese IP == any orelse IP == loopback,
                        is_integer(Port) ->
      {ok,S} = gen_sctp:open([{ip,IP},{port,Port}],[{sctp_recbuf,65536}]),
      io:format("Listening on ~w:~w\&. ~w~n", [IP,Port,S]),
      ok     = gen_sctp:listen(S, true),
      server_loop(S)\&.
  
  server_loop(S) ->
      case gen_sctp:recv(S) of
      {error, Error} ->
          io:format("SCTP RECV ERROR: ~p~n", [Error]);
      Data ->
          io:format("Error: ~p~n", [Data])
      end,
      server_loop(S)\&.        
.fi
.LP

.LP

.RE
.TP 2
*
Example of an Erlang SCTP Client which interacts with the above Server\&. Note that in this example, the Client creates an association with the Server with 5 outbound streams\&. For this reason, sending of "Test 0" over Stream 0 succeeds, but sending of "Test 5" over Stream 5 fails\&. The client then \fIabort\fRs the association, which results in the corresponding Event being received on the Server side\&.
.RS 2
.LP


.nf
  -module(sctp_client)\&.
  
  -export([client/0, client/1, client/2])\&.
  -include("inet\&.hrl")\&.
 
  client() ->
      client([localhost])\&.
  
  client([Host]) ->
      client([Host,2006]);
  
  client([Host, Port]) when is_list(Host), is_list(Port) ->
      client(Host,list_to_integer(Port)),
      init:stop();
  
  client(Host, Port) when is_integer(Port) ->
      {ok,S}     = gen_sctp:open(),
      {ok Assoc} = gen_sctp:connect
          (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
      io:format("Connection Successful, Assoc=~p~n", [Assoc]),
      
      io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
      io:nl(),
      timer:sleep(10000),
      io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
      io:nl(),
      timer:sleep(10000),
      io:write(gen_sctp:abort(S, Assoc)),
      io:nl(),
      
      timer:sleep(1000),
      gen_sctp:close(S)\&.        
.fi
.LP

.LP

.RE
.RE
.SH SEE ALSO
.LP
inet(3), gen_tcp(3), gen_upd(3), RFC2960 <http://www\&.rfc-archive\&.org/getrfc\&.php?rfc=2960> (Stream Control Transmission Protocol), Sockets API Extensions for SCTP\&. <http://tools\&.ietf\&.org/html/draft-ietf-tsvwg-sctpsocket-13>