diff options
Diffstat (limited to 'lib/kernel/doc/src/gen_sctp.xml')
| -rw-r--r-- | lib/kernel/doc/src/gen_sctp.xml | 1075 |
1 files changed, 1075 insertions, 0 deletions
diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml new file mode 100644 index 0000000000..de41178a17 --- /dev/null +++ b/lib/kernel/doc/src/gen_sctp.xml @@ -0,0 +1,1075 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2007</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>gen_sctp</title> + <prepared>[email protected]</prepared> + <responsible></responsible> + <docno>1</docno> + <approved></approved> + <checked></checked> + <date>2007-03-21</date> + <rev>A</rev> + <file>gen_sctp.sgml</file> + </header> + <module>gen_sctp</module> + <modulesummary>The gen_sctp module provides functions for communicating with sockets using the SCTP protocol.</modulesummary> + <description> + <p>The <c>gen_sctp</c> module provides functions for communicating with + sockets using the SCTP protocol. The implementation assumes that + the OS kernel supports SCTP + <url href="http://www.rfc-archive.org/getrfc.php?rfc=2960">(RFC2960)</url> through the user-level + <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">Sockets API Extensions.</url> + 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.</p> + <p>Record definitions for the <c>gen_sctp</c> module can be found using:</p> + <pre> + -include_lib("kernel/include/inet_sctp.hrl"). </pre> + <p>These record definitions use the "new" spelling 'adaptation', + not the deprecated 'adaption', regardless of which + spelling the underlying C API uses.</p> + </description> + + <section> + <marker id="contents"></marker> + <title>CONTENTS</title> + <list type="bulleted"> + <item><seealso marker="#types">DATA TYPES</seealso></item> + <item><seealso marker="#exports">EXPORTS</seealso></item> + <item><seealso marker="#options">SCTP SOCKET OPTIONS</seealso></item> + <item><seealso marker="#examples">SCTP EXAMPLES</seealso></item> + <item><seealso marker="#seealso">SEE ALSO</seealso></item> + <item><seealso marker="#authors">AUTHORS</seealso></item> + </list> + </section> + + <section> + <marker id="types"></marker> + <title>DATA TYPES</title> + <marker id="type-assoc_id"></marker> + <taglist> + <tag><c>assoc_id()</c></tag> + <item> + <p>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 <c>0</c> that has a + meaning such as "the whole endpoint" or "all future associations".</p> + <marker id="type-charlist"></marker> + </item> + <tag><c>charlist() = [char()]</c></tag> + <item> <marker id="type-iolist"></marker> +</item> + <tag><c>iolist() = [char() | binary()]</c></tag> + <item> <marker id="type-ip_address"></marker> +</item> + <tag><c>ip_address()</c></tag> + <item> + <p>Represents an address of an SCTP socket. + It is a tuple as explained in + <seealso marker="inet">inet(3)</seealso>.</p> + <marker id="type-port_number"></marker> + </item> + <tag><c>port_number() = 0 .. 65535</c></tag> + <item> <marker id="type-posix"></marker> +</item> + <tag><c>posix()</c></tag> + <item> + <p>See + <seealso marker="inet#error_codes">inet(3); POSIX Error Codes.</seealso></p> + <marker id="type-sctp_option"></marker> + </item> + <tag><c>sctp_option()</c></tag> + <item> + <p>One of the + <seealso marker="#options">SCTP Socket Options.</seealso></p> + <marker id="type-sctp_socket"></marker> + </item> + <tag><c>sctp_socket()</c></tag> + <item> + <p>Socket identifier returned from <c>open/*</c>.</p> + <marker id="type-timeout"></marker> + </item> + <tag><c>timeout() = int() | infinity</c></tag> + <item> + <p>Timeout used in SCTP connect and receive calls.</p> + </item> + </taglist> + <marker id="exports"></marker> + </section> + <funcs> + <func> + <name>abort(sctp_socket(), Assoc) -> ok | {error, posix()}</name> + <fsummary>Abnormally terminate the association given by Assoc, without flushing of unsent data</fsummary> + <type> + <v>Assoc = #sctp_assoc_change{}</v> + </type> + <desc> + <p>Abnormally terminates the association given by <c>Assoc</c>, 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.</p> + </desc> + </func> + <func> + <name>close(sctp_socket()) -> ok | {error, posix()}</name> + <fsummary>Completely close the socket and all associations on it</fsummary> + <desc> + <p>Completely closes the socket and all associations on it. The unsent + data is flushed as in <c>eof/2</c>. The <c>close/1</c> call + is blocking or otherwise depending of the value of + the <seealso marker="#option-linger">linger</seealso> socket + <seealso marker="#options">option</seealso>. + If <c>close</c> does not linger or linger timeout expires, + the call returns and the data is flushed in the background.</p> + </desc> + </func> + <func> + <name>connect(Socket, Addr, Port, Opts) -> {ok,Assoc} | {error, posix()}</name> + <fsummary>Same as <c>connect(Socket, Addr, Port, Opts, infinity)</c>.</fsummary> + <desc> + <p>Same as <c>connect(Socket, Addr, Port, Opts, infinity)</c>.</p> + </desc> + </func> + <func> + <name>connect(Socket, Addr, Port, [Opt], Timeout) -> {ok, Assoc} | {error, posix()}</name> + <fsummary>Establish a new association for the socket <c>Socket</c>, with a peer (SCTP server socket)</fsummary> + <type> + <v>Socket = sctp_socket()</v> + <v>Addr = ip_address() | Host</v> + <v>Port = port_number()</v> + <v>Opt = sctp_option()</v> + <v>Timeout = timeout()</v> + <v>Host = atom() | string()</v> + <v>Assoc = #sctp_assoc_change{}</v> + </type> + <desc> + <p>Establishes a new association for the socket <c>Socket</c>, + with the peer (SCTP server socket) given by + <c>Addr</c> and <c>Port</c>. The <c>Timeout</c>, + is expressed in milliseconds.</p> + <p>A socket can be associated with multiple peers. + <marker id="record-sctp_assoc_change"></marker> + + The result of <c>connect/*</c> is an <c>#sctp_assoc_change{}</c> + event which contains, in particular, the new + <seealso marker="#type-assoc_id">Association ID:</seealso></p> + <pre> + #sctp_assoc_change{ + state = atom(), + error = atom(), + outbound_streams = int(), + inbound_streams = int(), + assoc_id = assoc_id() + } </pre> + <p>The number of outbound and inbound streams can be set by + giving an <c>sctp_initmsg</c> option to <c>connect</c> + as in:</p> + <pre> + connect(Socket, Ip, Port, + [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams, + max_instreams=MaxInStreams}}]) </pre> + <p>All options <c>Opt</c> 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, <c>Opt</c> option records only + define field values to change before connecting.</p> + <p>The returned <c>outbound_streams</c> and <c>inbound_streams</c> + are the actual stream numbers on the socket, which may be different + from the requested values (<c>OutStreams</c> and <c>MaxInStreams</c> + respectively) if the peer requires lower values.</p> + <p>The following values of <c>state</c> are possible:</p> + <list type="bulleted"> + <item> + <p><c>comm_up</c>: association successfully established. This + indicates a successful completion of <c>connect</c>.</p> + </item> + <item> + <p><c>cant_assoc</c>: association cannot be established + (<c>connect/*</c> failure).</p> + </item> + </list> + <p>All other states do not normally occur in the output from + <c>connect/*</c>. Rather, they may occur in + <c>#sctp_assoc_change{}</c> events received instead of data in + <seealso marker="#recv/1">recv/*</seealso> calls. + All of them indicate losing the association due to various + error conditions, and are listed here for the sake of completeness. + The <c>error</c> field may provide more detailed diagnostics.</p> + <list type="bulleted"> + <item> + <p><c>comm_lost</c>;</p> + </item> + <item> + <p><c>restart</c>;</p> + </item> + <item> + <p><c>shutdown_comp</c>.</p> + </item> + </list> + </desc> + </func> + <func> + <name>controlling_process(sctp_socket(), pid()) -> ok</name> + <fsummary>Assign a new controlling process pid to the socket</fsummary> + <desc> + <p>Assigns a new controlling process Pid to Socket. Same implementation + as <c>gen_udp:controlling_process/2</c>.</p> + </desc> + </func> + <func> + <name>eof(Socket, Assoc) -> ok | {error, Reason}</name> + <fsummary>Gracefully terminate the association given by Assoc, with flushing of all unsent data</fsummary> + <type> + <v>Socket = sctp_socket()</v> + <v>Assoc = #sctp_assoc_change{}</v> + </type> + <desc> + <p>Gracefully terminates the association given by <c>Assoc</c>, 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.</p> + </desc> + </func> + <func> + <name>listen(Socket, IsServer) -> ok | {error, Reason}</name> + <fsummary>Set up a socket to listen.</fsummary> + <type> + <v>Socket = sctp_socket()</v> + <v>IsServer = bool()</v> + </type> + <desc> + <p>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.</p> + </desc> + </func> + <func> + <name>open() -> {ok, Socket} | {error, posix()}</name> + <name>open(Port) -> {ok, Socket} | {error, posix()}</name> + <name>open([Opt]) -> {ok, Socket} | {error, posix()}</name> + <name>open(Port, [Opt]) -> {ok, Socket} | {error, posix()}</name> + <fsummary>Create an SCTP socket and bind it to local addresses</fsummary> + <type> + <v>Opt = {ip,IP} | {ifaddr,IP} | {port,Port} | sctp_option()</v> + <v>IP = ip_address() | any | loopback</v> + <v>Port = port_number()</v> + </type> + <desc> + <p>Creates an SCTP socket and binds it to the local addresses + specified by all <c>{ip,IP}</c> (or synonymously <c>{ifaddr,IP}</c>) + options (this feature is called SCTP multi-homing). + The default <c>IP</c> and <c>Port</c> are <c>any</c> + and <c>0</c>, meaning bind to all local addresses on any + one free port.</p> + <p>A default set of socket <seealso marker="#options">options</seealso> + is used. In particular, the socket is opened in + <seealso marker="#option-binary">binary</seealso> and + <seealso marker="#option-active">passive</seealso> mode, + and with reasonably large + <seealso marker="#option-sndbuf">kernel</seealso> and driver + <seealso marker="#option-buffer">buffers.</seealso></p> + </desc> + </func> + <func> + <name>recv(sctp_socket()) -> {ok, {FromIP, FromPort, AncData, BinMsg}} | {error, Reason}</name> + <name>recv(sctp_socket(), timeout()) -> {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}</name> + <fsummary>Receive a message from a socket</fsummary> + <type> + <v>FromIP = ip_address()</v> + <v>FromPort = port_number()</v> + <v>AncData = [#sctp_sndrcvinfo{}]</v> + <v>Data = binary() | charlist() | #sctp_sndrcvinfo{} | + #sctp_assoc_change{} | #sctp_paddr_change{} | + #sctp_adaptation_event{} </v> + <v>Reason = posix() | #sctp_send_failed{} | #scpt_paddr_change{} | + #sctp_pdapi_event{} | #sctp_remote_error{} | + #sctp_shutdown_event{}</v> + </type> + <desc> + <p>Receives the <c>Data</c> message from any association of the socket. + If the receive times out <c>{error,timeout</c> is returned. + The default timeout is <c>infinity</c>. + <c>FromIP</c> and <c>FromPort</c> indicate the sender's address.</p> + <p><c>AncData</c> is a list of Ancillary Data items which + may be received along with the main <c>Data</c>. + This list can be empty, or contain a single + <seealso marker="#record-sctp_sndrcvinfo">#sctp_sndrcvinfo{}</seealso> + record, if receiving of such ancillary data is enabled + (see option + <seealso marker="#option-sctp_events">sctp_events</seealso>). + 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 + <c>FromIP</c> and <c>FromPort</c> using the + <seealso marker="#option-sctp_get_peer_addr_info">sctp_get_peer_addr_info</seealso> socket option, + but this would still not produce the Stream number).</p> + <p>The actual <c>Data</c> received may be a <c>binary()</c>, + or <c>list()</c> of bytes (integers in the range 0 through 255) + depending on the socket mode, or an SCTP Event. + <marker id="sctp_events"></marker> + + The following SCTP Events are possible:</p> + <list type="bulleted"> + <item> + <p><seealso marker="#record-sctp_sndrcvinfo">#sctp_sndrcvinfo{}</seealso></p> + </item> + <item> + <p><seealso marker="#record-sctp_assoc_change">#sctp_assoc_change{}</seealso>;</p> + </item> + <item> + <pre> + #sctp_paddr_change{ + addr = {ip_address(),port()}, + state = atom(), + error = int(), + assoc_id = assoc_id() + } </pre> + <p>Indicates change of the status of the peer's IP address given by + <c>addr</c> within the association <c>assoc_id</c>. + Possible values of <c>state</c> (mostly self-explanatory) include:</p> + <list type="bulleted"> + <item> + <p><c>addr_unreachable</c>;</p> + </item> + <item> + <p><c>addr_available</c>;</p> + </item> + <item> + <p><c>addr_removed</c>;</p> + </item> + <item> + <p><c>addr_added</c>;</p> + </item> + <item> + <p><c>addr_made_prim</c>.</p> + </item> + <item> + <p><c>addr_confirmed</c>.</p> + </item> + </list> + <p>In case of an error (e.g. <c>addr_unreachable</c>), the + <c>error</c> field provides additional diagnostics. In such cases, + the <c>#sctp_paddr_change{}</c> Event is automatically + converted into an <c>error</c> term returned by + <c>gen_sctp:recv</c>. The <c>error</c> field value can be + converted into a string using <c>error_string/1</c>.</p> + </item> + <item> + <pre> + #sctp_send_failed{ + flags = true | false, + error = int(), + info = #sctp_sndrcvinfo{}, + assoc_id = assoc_id() + data = binary() + } </pre> + <p>The sender may receive this event if a send operation fails. + The <c>flags</c> is a Boolean specifying whether the data have + actually been transmitted over the wire; <c>error</c> provides + extended diagnostics, use <c>error_string/1</c>; + <c>info</c> is the original + <seealso marker="#record-sctp_sndrcvinfo">#sctp_sndrcvinfo{}</seealso> record used in the failed + <seealso marker="#send/3">send/*,</seealso> and <c>data</c> + is the whole original data chunk attempted to be sent.</p> + <p>In the current implementation of the Erlang/SCTP binding, + this Event is internally converted into an <c>error</c> term + returned by <c>recv/*</c>.</p> + </item> + <item> + <pre> + #sctp_adaptation_event{ + adaptation_ind = int(), + assoc_id = assoc_id() + } </pre> + <p>Delivered when a peer sends an Adaptation Layer Indication + parameter (configured through the option + <seealso marker="#option-sctp_adaptation_layer">sctp_adaptation_layer</seealso>). + Note that with the current implementation of + the Erlang/SCTP binding, this event is disabled by default.</p> + </item> + <item> + <pre> + #sctp_pdapi_event{ + indication = sctp_partial_delivery_aborted, + assoc_id = assoc_id() + } </pre> + <p>A partial delivery failure. In the current implementation of + the Erlang/SCTP binding, this Event is internally converted + into an <c>error</c> term returned by <c>recv/*</c>.</p> + </item> + </list> + </desc> + </func> + <func> + <name>send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}</name> + <fsummary>Send a message using an <c>#sctp_sndrcvinfo{}</c>record</fsummary> + <type> + <v>Socket = sctp_socket()</v> + <v>SndRcvInfo = #sctp_sndrcvinfo{}</v> + <v>Data = binary() | iolist()</v> + </type> + <desc> + <p>Sends the <c>Data</c> message with all sending parameters from a + <seealso marker="#record-sctp_sndrcvinfo">#sctp_sndrcvinfo{}</seealso> 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.</p> + </desc> + </func> + <func> + <name>send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}</name> + <fsummary>Send a message over an existing association and given stream</fsummary> + <type> + <v>Socket = sctp_socket()</v> + <v>Assoc = #sctp_assoc_change{} | assoc_id()</v> + <v>Stream = integer()</v> + <v>Data = binary() | iolist()</v> + </type> + <desc> + <p>Sends <c>Data</c> message over an existing association and given + stream.</p> + </desc> + </func> + <func> + <name>error_string(integer()) -> ok | string() | undefined</name> + <fsummary>Translate an SCTP error number into a string</fsummary> + <desc> + <p>Translates an SCTP error number from for example + <c>#sctp_remote_error{}</c> or <c>#sctp_send_failed{}</c> into + an explanatory string, or one of the atoms <c>ok</c> for no + error and <c>undefined</c> for an unrecognized error.</p> + </desc> + </func> + </funcs> + + <section> + <marker id="options"></marker> + <title>SCTP SOCKET OPTIONS</title> + <p>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 + <c>gen_sctp:open/1,2</c> or <c>inet:setopts/2</c>, + retrieved using <c>inet:getopts/2</c>, and when calling + <c>gen_sctp:connect/4,5</c> options can be changed.</p> + <marker id="option-binary"></marker> + <marker id="option-list"></marker> + <taglist> + <tag><c>{mode, list|binary}</c>or just <c>list</c> or <c>binary</c>.</tag> + <item> + <p>Determines the type of data returned from <c>gen_sctp:recv/1,2</c>.</p> + <marker id="option-active"></marker> + </item> + <tag><c>{active, true|false|once}</c></tag> + <item> + <list type="bulleted"> + <item> + <p>If <c>false</c> (passive mode, the default), + the caller needs to do an explicit <c>gen_sctp:recv</c> call + in order to retrieve the available data from the socket.</p> + </item> + <item> + <p>If <c>true</c> (full active mode), the pending data or events are + sent to the owning process.</p> + <p><em>NB:</em> This can cause the message queue to overflow, + as there is no way to throttle the sender in this case + (no flow control!).</p> + </item> + <item> + <p>If <c>once</c>, 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.</p> + </item> + </list> + <marker id="option-buffer"></marker> + </item> + <tag><c>{buffer, int()}</c></tag> + <item> + <p>Determines the size of the user-level software buffer used by + the SCTP driver. Not to be confused with <c>sndbuf</c> + and <c>recbuf</c> options which correspond to + the kernel socket buffers. It is recommended + to have <c>val(buffer) >= max(val(sndbuf),val(recbuf))</c>. + In fact, the <c>val(buffer)</c> is automatically set to + the above maximum when <c>sndbuf</c> or <c>recbuf</c> values are set.</p> + </item> + <tag><c>{tos, int()}</c></tag> + <item> + <p>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.</p> + </item> + <tag><c>{priority, int()}</c></tag> + <item> + <p>A protocol-independent equivalent of <c>tos</c> above. Setting + priority implies setting tos as well.</p> + </item> + <tag><c>{dontroute, true|false}</c></tag> + <item> + <p>By default <c>false</c>. If <c>true</c>, the kernel does not + send packets via any gateway, only sends them to directly + connected hosts.</p> + </item> + <tag><c>{reuseaddr, true|false}</c></tag> + <item> + <p>By default <c>false</c>. If true, the local binding address + <c>{IP,Port}</c> of the socket can be re-used immediately: + no waiting in the CLOSE_WAIT state is performed (may be + required for high-throughput servers).</p> + <marker id="option-linger"></marker> + </item> + <tag><c>{linger, {true|false, int()}</c></tag> + <item> + <p>Determines the timeout in seconds for flushing unsent data in the + <c>gen_sctp:close/1</c> socket call. If the 1st component of the value + tuple is <c>false</c>, the 2nd one is ignored, which means that + <c>gen_sctp:close/1</c> returns immediately not waiting + for data to be flushed. Otherwise, the 2nd component is + the flushing time-out in seconds.</p> + <marker id="option-sndbuf"></marker> + </item> + <tag><c>{sndbuf, int()}</c></tag> + <item> + <p>The size, in bytes, of the *kernel* send buffer for this socket. + Sending errors would occur for datagrams larger than + <c>val(sndbuf)</c>. Setting this option also adjusts + the size of the driver buffer (see <c>buffer</c> above).</p> + </item> + <tag><c>{recbuf, int()}</c></tag> + <item> + <p>The size, in bytes, of the *kernel* recv buffer for this socket. + Sending errors would occur for datagrams larger than + <c>val(sndbuf)</c>. Setting this option also adjusts + the size of the driver buffer (see <c>buffer</c> above).</p> + </item> + <tag><c>{sctp_rtoinfo, #sctp_rtoinfo{}}</c></tag> + <item> + <pre> + #sctp_rtoinfo{ + assoc_id = assoc_id(), + initial = int(), + max = int(), + min = int() + } </pre> + <p>Determines re-transmission time-out parameters, in milliseconds, + for the association(s) given by <c>assoc_id</c>. + If <c>assoc_id = 0</c> (default) indicates the whole endpoint. See + <url href="http://www.rfc-archive.org/getrfc.php?rfc=2960">RFC2960</url> and + <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">Sockets API Extensions for SCTP</url> for the exact semantics of the fields values.</p> + </item> + <tag><c>{sctp_associnfo, #sctp_assocparams{}}</c></tag> + <item> + <pre> + #sctp_assocparams{ + assoc_id = assoc_id(), + asocmaxrxt = int(), + number_peer_destinations = int(), + peer_rwnd = int(), + local_rwnd = int(), + cookie_life = int() + } </pre> + <p>Determines association parameters for the association(s) given by + <c>assoc_id</c>. <c>assoc_id = 0</c> (default) indicates + the whole endpoint. See + <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">Sockets API Extensions for SCTP</url> for the discussion of their semantics. Rarely used.</p> + </item> + <tag><c>{sctp_initmsg, #sctp_initmsg{}}</c></tag> + <item> + <pre> + #sctp_initmsg{ + num_ostreams = int(), + max_instreams = int(), + max_attempts = int(), + max_init_timeo = int() + } </pre> + <p>Determines the default parameters which this socket attempts + to negotiate with its peer while establishing an association with it. + Should be set after <c>open/*</c> but before the first + <c>connect/*</c>. <c>#sctp_initmsg{}</c> can also be used + as ancillary data with the first call of <c>send/*</c> to + a new peer (when a new association is created).</p> + <list type="bulleted"> + <item> + <p><c>num_ostreams</c>: number of outbound streams;</p> + </item> + <item> + <p><c>max_instreams</c>: max number of in-bound streams;</p> + </item> + <item> + <p><c>max_attempts</c>: max re-transmissions while + establishing an association;</p> + </item> + <item> + <p><c>max_init_timeo</c>: time-out in milliseconds + for establishing an association.</p> + </item> + </list> + <p></p> + </item> + <tag><c>{sctp_autoclose, int()|infinity}</c></tag> + <item> + <p>Determines the time (in seconds) after which an idle association is + automatically closed.</p> + </item> + <tag><c>{sctp_nodelay, true|false}</c></tag> + <item> + <p>Turns on|off the Nagle algorithm for merging small packets + into larger ones (which improves throughput at the expense + of latency).</p> + </item> + <tag><c>{sctp_disable_fragments, true|false}</c></tag> + <item> + <p>If <c>true</c>, 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.</p> + </item> + <tag><c>{sctp_i_want_mapped_v4_addr, true|false}</c></tag> + <item> + <p>Turns on|off automatic mapping of IPv4 addresses into IPv6 ones + (if the socket address family is AF_INET6).</p> + </item> + <tag><c>{sctp_maxseg, int()}</c></tag> + <item> + <p>Determines the maximum chunk size if message fragmentation is used. + If <c>0</c>, the chunk size is limited by the Path MTU only.</p> + </item> + <tag><c>{sctp_primary_addr, #sctp_prim{}}</c></tag> + <item> + <pre> + #sctp_prim{ + assoc_id = assoc_id(), + addr = {IP, Port} + } + IP = ip_address() + Port = port_number() </pre> + <p>For the association given by <c>assoc_id</c>, + <c>{IP,Port}</c> 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.</p> + </item> + <tag><c>{sctp_set_peer_primary_addr, #sctp_setpeerprim{}}</c></tag> + <item> + <pre> + #sctp_setpeerprim{ + assoc_id = assoc_id(), + addr = {IP, Port} + } + IP = ip_address() + Port = port_number() </pre> + <p>When set, informs the peer that it should use <c>{IP, Port}</c> + as the primary address of the local endpoint for the association + given by <c>assoc_id</c>.</p> + <marker id="option-sctp_adaptation_layer"></marker> + </item> + <tag><c>{sctp_adaptation_layer, #sctp_setadaptation{}}</c></tag> + <item> + <marker id="record-sctp_setadaptation"></marker> + <pre> + #sctp_setadaptation{ + adaptation_ind = int() + } </pre> + <p>When set, requests that the local endpoint uses the value given by + <c>adaptation_ind</c> as the Adaptation Indication parameter for + establishing new associations. See + <url href="http://www.rfc-archive.org/getrfc.php?rfc=2960">RFC2960</url> and + <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">Sockets API Extenstions for SCTP</url> for more details.</p> + </item> + <tag><c>{sctp_peer_addr_params, #sctp_paddrparams{}}</c></tag> + <item> + <pre> + #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() </pre> + <p>This option determines various per-address parameters for + the association given by <c>assoc_id</c> and the peer address + <c>address</c> (the SCTP protocol supports multi-homing, + so more than 1 address can correspond to a given association).</p> + <list type="bulleted"> + <item> + <p><c>hbinterval</c>: heartbeat interval, in milliseconds;</p> + </item> + <item> + <p><c>pathmaxrxt</c>: max number of retransmissions + before this address is considered unreachable (and an + alternative address is selected);</p> + </item> + <item> + <p><c>pathmtu</c>: fixed Path MTU, if automatic discovery is + disabled (see <c>flags</c> below);</p> + </item> + <item> + <p><c>sackdelay</c>: delay in milliseconds for SAC messages + (if the delay is enabled, see <c>flags</c> below);</p> + </item> + <item> + <p><c>flags</c>: the following flags are available:</p> + <list type="bulleted"> + <item> + <p><c>hb_enable</c>: enable heartbeat; </p> + </item> + <item> + <p><c>hb_disable</c>: disable heartbeat;</p> + </item> + <item> + <p><c>hb_demand</c>: initiate heartbeat immediately;</p> + </item> + <item> + <p><c>pmtud_enable</c>: enable automatic Path MTU discovery;</p> + </item> + <item> + <p><c>pmtud_disable</c>: disable automatic Path MTU discovery;</p> + </item> + <item> + <p><c>sackdelay_enable</c>: enable SAC delay;</p> + </item> + <item> + <p><c>sackdelay_disable</c>: disable SAC delay.</p> + </item> + </list> + <p></p> + </item> + </list> + <p></p> + </item> + <tag><c>{sctp_default_send_param, #sctp_sndrcvinfo{}}</c></tag> + <item> + <marker id="record-sctp_sndrcvinfo"></marker> + <pre> + #sctp_sndrcvinfo{ + stream = int(), + ssn = int(), + flags = list(), + ppid = int(), + context = int(), + timetolive = int(), + tsn = int(), + cumtsn = int(), + assoc_id = assoc_id() + } </pre> + <p><c>#sctp_sndrcvinfo{}</c> 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 + <c>gen_sctp:send</c>calls on the association given by + <c>assoc_id</c>. <c>assoc_id = 0</c> (default) indicates + the whole endpoint. The following fields typically need + to be specified by the sender:</p> + <list type="bulleted"> + <item> + <p><c>sinfo_stream</c>: stream number (0-base) within the association + to send the messages through;</p> + </item> + <item> + <p><c>sinfo_flags</c>: the following flags are recognised:</p> + <list type="bulleted"> + <item> + <p><c>unordered</c>: the message is to be sent unordered;</p> + </item> + <item> + <p><c>addr_over</c>: the address specified in + <c>gen_sctp:send</c> overwrites the primary peer address;</p> + </item> + <item> + <p><c>abort</c>: abort the current association without + flushing any unsent data;</p> + </item> + <item> + <p><c>eof</c>: gracefully shut down the current + association, with flushing of unsent data.</p> + </item> + </list> + <p></p> + <p>Other fields are rarely used. See + <url href="http://www.rfc-archive.org/getrfc.php?rfc=2960">RFC2960</url> and + <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">Sockets API Extensions for SCTP</url> for full information.</p> + </item> + </list> + <p></p> + <marker id="option-sctp_events"></marker> + </item> + <tag><c>{sctp_events, #sctp_event_subscribe{}}</c></tag> + <item> + <marker id="record-sctp_event_subscribe"></marker> + <pre> + #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 + } </pre> + <p>This option determines which + <seealso marker="#sctp_events">SCTP Events</seealso> are to be + received (via <seealso marker="#recv/1">recv/*</seealso>) + along with the data. The only + exception is <c>data_io_event</c> which enables or disables + receiving of + <seealso marker="#record-sctp_sndrcvinfo">#sctp_sndrcvinfo{}</seealso> + ancillary data, not events. + By default, all flags except <c>adaptation_layer_event</c> are + enabled, although <c>sctp_data_io_event</c> and + <c>association_event</c> are used by the driver itself and not + exported to the user level.</p> + </item> + <tag><c>{sctp_delayed_ack_time, #sctp_assoc_value{}}</c></tag> + <item> + <pre> + #sctp_assoc_value{ + assoc_id = assoc_id(), + assoc_value = int() + } </pre> + <p>Rarely used. Determines the ACK time + (given by <c>assoc_value</c> in milliseconds) for + the given association or the whole endpoint + if <c>assoc_value = 0</c> (default).</p> + </item> + <tag><c>{sctp_status, #sctp_status{}}</c></tag> + <item> + <pre> + #sctp_status{ + assoc_id = assoc_id(), + state = atom(), + rwnd = int(), + unackdata = int(), + penddata = int(), + instrms = int(), + outstrms = int(), + fragmentation_point = int(), + primary = #sctp_paddrinfo{} + } </pre> + <p>This option is read-only. It determines the status of + the SCTP association given by <c>assoc_id</c>. Possible values of + <c>state</c> follows. The state designations are mostly + self-explanatory. <c>state_empty</c> is the default which means + that no other state is active:</p> + <list type="bulleted"> + <item> + <p><c>sctp_state_empty</c></p> + </item> + <item> + <p><c>sctp_state_closed</c></p> + </item> + <item> + <p><c>sctp_state_cookie_wait</c></p> + </item> + <item> + <p><c>sctp_state_cookie_echoed</c></p> + </item> + <item> + <p><c>sctp_state_established</c></p> + </item> + <item> + <p><c>sctp_state_shutdown_pending</c></p> + </item> + <item> + <p><c>sctp_state_shutdown_sent</c></p> + </item> + <item> + <p><c>sctp_state_shutdown_received</c></p> + </item> + <item> + <p><c>sctp_state_shutdown_ack_sent</c></p> + </item> + </list> + <p>The semantics of other fields is the following:</p> + <list type="bulleted"> + <item> + <p><c>sstat_rwnd</c>: the association peer's current receiver + window size;</p> + </item> + <item> + <p><c>sstat_unackdata</c>: number of unacked data chunks;</p> + </item> + <item> + <p><c>sstat_penddata</c>: number of data chunks pending receipt;</p> + </item> + <item> + <p><c>sstat_instrms</c>: number of inbound streams;</p> + </item> + <item> + <p><c>sstat_outstrms</c>: number of outbound streams;</p> + </item> + <item> + <p><c>sstat_fragmentation_point</c>: message size at which SCTP + fragmentation will occur;</p> + </item> + <item> + <p><c>sstat_primary</c>: information on the current primary peer + address (see below for the format of <c>#sctp_paddrinfo{}</c>).</p> + </item> + </list> + <p></p> + <marker id="option-sctp_get_peer_addr_info"></marker> + </item> + <tag><c>{sctp_get_peer_addr_info, #sctp_paddrinfo{}}</c></tag> + <item> + <marker id="record-sctp_paddrinfo"></marker> + <pre> + #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() </pre> + <p>This option is read-only. It determines the parameters specific to + the peer's address given by <c>address</c> within the association + given by <c>assoc_id</c>. The <c>address</c> field must be set by the + caller; all other fields are filled in on return. + If <c>assoc_id = 0</c> (default), the <c>address</c> + is automatically translated into the corresponding + association ID. This option is rarely used; see + <url href="http://www.rfc-archive.org/getrfc.php?rfc=2960">RFC2960</url> and + <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">Sockets API Extensions for SCTP</url> for the semantics of all fields.</p> + </item> + </taglist> + </section> + + <section> + <marker id="examples"></marker> + <title>SCTP EXAMPLES</title> + <list type="bulleted"> + <item> + <p>Example of an Erlang SCTP Server which receives SCTP messages and + prints them on the standard output:</p> + <pre> + -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) orelse IP == any orelse IP == loopback, + is_integer(Port) -> + {ok,S} = gen_sctp:open([{ip,IP},{port,Port}],[{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("Received: ~p~n", [Data]) + end, + server_loop(S). </pre> + <p></p> + </item> + <item> + <p>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 <c>abort</c>s the association, + which results in the corresponding Event being received on + the Server side.</p> + <pre> + -module(sctp_client). + + -export([client/0, client/1, client/2]). + -include_lib("kernel/include/inet.hrl"). + -include_lib("kernel/include/inet_sctp.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). </pre> + <p></p> + </item> + </list> + </section> + + <section> + <marker id="seealso"></marker> + <title>SEE ALSO</title> + <p><seealso marker="inet">inet(3)</seealso>, + <seealso marker="gen_tcp">gen_tcp(3)</seealso>, + <seealso marker="gen_udp">gen_upd(3)</seealso>, + <url href="http://www.rfc-archive.org/getrfc.php?rfc=2960">RFC2960</url> (Stream Control Transmission Protocol), + <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">Sockets API Extensions for SCTP.</url></p> + <marker id="authors"></marker> + </section> +</erlref> + |