The gen_sctp module provides functions for communicating with sockets using the SCTP protocol. The implementation assumes that the OS kernel supports SCTP (RFC2960) through the user-level Sockets API Extensions. 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.
Record definitions for the gen_sctp module can be found using:
-include_lib("kernel/include/inet_sctp.hrl").
These record definitions use the "new" spelling 'adaptation', not the deprecated 'adaption', regardless of which spelling the underlying C API uses.
abort(sctp_socket(), Assoc) -> ok | {error, posix()}
Types:
Assoc = #sctp_assoc_change{}
Abnormally terminates the association given by Assoc, 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.
close(sctp_socket()) -> ok | {error, posix()}
Completely 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 timeout expires, the call returns and the data is flushed in the background.
connect(Socket, Addr, Port, Opts) -> {ok,Assoc} | {error, posix()}
Same as connect(Socket, Addr, Port, Opts, infinity).
connect(Socket, Addr, Port, [Opt], Timeout) -> {ok, Assoc} | {error, posix()}
Types:
Socket = sctp_socket()
Addr = ip_address() | Host
Port = port_number()
Opt = sctp_option()
Timeout = timeout()
Host = atom() | string()
Assoc = #sctp_assoc_change{}
Establishes a new association for the socket Socket, with the peer (SCTP server socket) given by Addr and Port. The Timeout, is expressed in milliseconds.
A socket can be associated with multiple peers. The result of connect/* is an #sctp_assoc_change{} event which contains, in particular, the new Association ID:
#sctp_assoc_change{
state = atom(),
error = atom(),
outbound_streams = int(),
inbound_streams = int(),
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 got 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 actual stream numbers on the socket, which may be different from the requested values (OutStreams and MaxInStreams respectively) if the peer requires lower values.
The following values of state are possible:
All other states do not normally occur in the output from connect/*. Rather, they may occur in #sctp_assoc_change{} 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 error field may provide more detailed diagnostics.
controlling_process(sctp_socket(), pid()) -> ok
Assigns a new controlling process Pid to Socket. Same implementation as gen_udp:controlling_process/2.
eof(Socket, Assoc) -> ok | {error, Reason}
Types:
Socket = sctp_socket()
Assoc = #sctp_assoc_change{}
Gracefully terminates the association given by Assoc, 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.
listen(Socket, IsServer) -> ok | {error, Reason}
Types:
Socket = sctp_socket()
IsServer = bool()
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.
open() -> {ok, Socket} | {error, posix()}
open(Port) -> {ok, Socket} | {error, posix()}
open([Opt]) -> {ok, Socket} | {error, posix()}
open(Port, [Opt]) -> {ok, Socket} | {error, posix()}
Types:
Opt = {ip,IP} | {ifaddr,IP} | {port,Port} | sctp_option()
IP = ip_address() | any | loopback
Port = port_number()
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 one free port.
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.
recv(sctp_socket()) -> {ok, {FromIP, FromPort, AncData, BinMsg}} | {error, Reason}
recv(sctp_socket(), timeout()) -> {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
Types:
FromIP = ip_address()
FromPort = port_number()
AncData = [#sctp_sndrcvinfo{}]
Data = binary() | charlist() | #sctp_sndrcvinfo{} |
#sctp_assoc_change{} | #sctp_paddr_change{} |
#sctp_adaptation_event{}
Reason = posix() | #sctp_send_failed{} | #scpt_paddr_change{} |
#sctp_pdapi_event{} | #sctp_remote_error{} |
#sctp_shutdown_event{}
Receives the Data message from any association of the socket. If the receive times out {error,timeout is returned. The default timeout is infinity. FromIP and FromPort indicate the sender's address.
AncData is a list of Ancillary Data items which may 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, 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 FromIP and FromPort using the sctp_get_peer_addr_info socket option, but this would still not produce the Stream number).
The actual Data received may be a binary(), or list() of bytes (integers in the range 0 through 255) depending on the socket mode, or an SCTP Event. The following SCTP Events are possible:
#sctp_paddr_change{
addr = ip_address(),
state = atom(),
error = int(),
assoc_id = assoc_id()
}
#sctp_send_failed{
flags = true | false,
error = int(),
info = #sctp_sndrcvinfo{},
assoc_id = assoc_id()
data = binary()
}
#sctp_adaptation_event{
adaptation_ind = int(),
assoc_id = assoc_id()
}
#sctp_pdapi_event{
indication = sctp_partial_delivery_aborted,
assoc_id = assoc_id()
}
send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
Types:
Socket = sctp_socket()
SndRcvInfo = #sctp_sndrcvinfo{}
Data = binary() | iolist()
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 send/4 function is sufficient for most applications.
send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
Types:
Socket = sctp_socket()
Assoc = #sctp_assoc_change{} | assoc_id()
Stream = integer()
Data = binary() | iolist()
Sends Data message over an existing association and given stream.
error_string(integer()) -> ok | string() | undefined
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 and undefined for an unrecognized error.
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 gen_sctp:open/1,2 or inet:setopts/2, retrieved using inet:getopts/2, and when calling gen_sctp:connect/4,5 options can be changed.
#sctp_rtoinfo{
assoc_id = assoc_id(),
initial = int(),
max = int(),
min = int()
}
#sctp_assocparams{
assoc_id = assoc_id(),
asocmaxrxt = int(),
number_peer_destinations = int(),
peer_rwnd = int(),
local_rwnd = int(),
cookie_life = int()
}
#sctp_initmsg{
num_ostreams = int(),
max_instreams = int(),
max_attempts = int(),
max_init_timeo = int()
}
#sctp_prim{
assoc_id = assoc_id(),
addr = {IP, Port}
}
IP = ip_address()
Port = port_number()
#sctp_setpeerprim{
assoc_id = assoc_id(),
addr = {IP, Port}
}
IP = ip_address()
Port = port_number()
#sctp_setadaptation{
adaptation_ind = int()
}
#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()
#sctp_sndrcvinfo{
stream = int(),
ssn = int(),
flags = list(),
ppid = int(),
context = int(),
timetolive = int(),
tsn = int(),
cumtsn = int(),
assoc_id = assoc_id()
}
#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_assoc_value{
assoc_id = assoc_id(),
assoc_value = int()
}
#sctp_status{
assoc_id = assoc_id(),
state = atom(),
rwnd = int(),
unackdata = int(),
penddata = int(),
instrms = int(),
outstrms = int(),
fragmentation_point = int(),
primary = #sctp_paddrinfo{}
}
#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()
-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).
-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).
inet(3), gen_tcp(3), gen_upd(3), RFC2960 (Stream Control Transmission Protocol), Sockets API Extensions for SCTP.