1gen_sctp(3) Erlang Module Definition gen_sctp(3)
2
6 gen_sctp - Functions for communicating with sockets using the SCTP
7 protocol.
8
10 This module provides functions for communicating with sockets using the
11 SCTP protocol. The implementation assumes that the OS kernel supports
12 SCTP (RFC 2960) through the user-level Sockets API Extensions.
13 During development, this implementation was tested on:
15 * Linux Fedora Core 5.0 (kernel 2.6.15-2054 or later is needed)
17 * Solaris 10, 11
19 During OTP adaptation it was tested on:
21 * SUSE Linux Enterprise Server 10 (x86_64) kernel 2.6.16.27-0.6-smp,
23 with lksctp-tools-1.0.6
24 * Briefly on Solaris 10
26 * SUSE Linux Enterprise Server 10 Service Pack 1 (x86_64) kernel
28 2.6.16.54-0.2.3-smp with lksctp-tools-1.0.7
29 * FreeBSD 8.2
31 This module was written for one-to-many style sockets (type seqpacket).
33 With the addition of peeloff/2, one-to-one style sockets (type stream)
34 were introduced.
35 Record definitions for this module can be found using:
37 -include_lib("kernel/include/inet_sctp.hrl").
39 These record definitions use the "new" spelling 'adaptation', not the
41 deprecated 'adaption', regardless of which spelling the underlying C
42 API uses.
43
45 assoc_id()
46 An opaque term returned in, for example, #sctp_paddr_change{},
48 which identifies an association for an SCTP socket. The term is
49 opaque except for the special value 0, which has a meaning such
50 as "the whole endpoint" or "all future associations".
51 option() =
53 {active, true | false | once | -32768..32767} |
54 {buffer, integer() >= 0} |
55 {dontroute, boolean()} |
56 {high_msgq_watermark, integer() >= 1} |
57 {linger, {boolean(), integer() >= 0}} |
58 {low_msgq_watermark, integer() >= 1} |
59 {mode, list | binary} |
60 list | binary |
61 {priority, integer() >= 0} |
62 {recbuf, integer() >= 0} |
63 {reuseaddr, boolean()} |
64 {ipv6_v6only, boolean()} |
65 {sctp_adaptation_layer, #sctp_setadaptation{}} |
66 {sctp_associnfo, #sctp_assocparams{}} |
67 {sctp_autoclose, integer() >= 0} |
68 {sctp_default_send_param, #sctp_sndrcvinfo{}} |
69 {sctp_delayed_ack_time, #sctp_assoc_value{}} |
70 {sctp_disable_fragments, boolean()} |
71 {sctp_events, #sctp_event_subscribe{}} |
72 {sctp_get_peer_addr_info, #sctp_paddrinfo{}} |
73 {sctp_i_want_mapped_v4_addr, boolean()} |
74 {sctp_initmsg, #sctp_initmsg{}} |
75 {sctp_maxseg, integer() >= 0} |
76 {sctp_nodelay, boolean()} |
77 {sctp_peer_addr_params, #sctp_paddrparams{}} |
78 {sctp_primary_addr, #sctp_prim{}} |
79 {sctp_rtoinfo, #sctp_rtoinfo{}} |
80 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}} |
81 {sctp_status, #sctp_status{}} |
82 {sndbuf, integer() >= 0} |
83 {tos, integer() >= 0} |
84 {tclass, integer() >= 0} |
85 {ttl, integer() >= 0} |
86 {recvtos, boolean()} |
87 {recvtclass, boolean()} |
88 {recvttl, boolean()}
89 One of the SCTP Socket Options.
91 option_name() =
93 active | buffer | dontroute | high_msgq_watermark | linger |
94 low_msgq_watermark | mode | priority | recbuf | reuseaddr |
95 ipv6_v6only | sctp_adaptation_layer | sctp_associnfo |
96 sctp_autoclose | sctp_default_send_param |
97 sctp_delayed_ack_time | sctp_disable_fragments | sctp_events |
98 sctp_get_peer_addr_info | sctp_i_want_mapped_v4_addr |
99 sctp_initmsg | sctp_maxseg | sctp_nodelay |
100 sctp_peer_addr_params | sctp_primary_addr | sctp_rtoinfo |
101 sctp_set_peer_primary_addr | sctp_status | sndbuf | tos |
102 tclass | ttl | recvtos | recvtclass | recvttl
103 sctp_socket()
105 Socket identifier returned from open/*.
107
109 abort(Socket, Assoc) -> ok | {error, inet:posix()}
110 Types:
112 Socket = sctp_socket()
114 Assoc = #sctp_assoc_change{}
115 Abnormally terminates the association specified by Assoc, with‐
117 out flushing of unsent data. The socket itself remains open.
118 Other associations opened on this socket are still valid, and
119 the socket can be used in new associations.
120 close(Socket) -> ok | {error, inet:posix()}
122 Types:
124 Socket = sctp_socket()
126 Closes the socket and all associations on it. The unsent data is
128 flushed as in eof/2. The close/1 call is blocking or otherwise
129 depending of the value of the linger socket option. If close
130 does not linger or linger time-out expires, the call returns and
131 the data is flushed in the background.
132 connect(Socket, Addr, Port, Opts) ->
134 {ok, #sctp_assoc_change{state = comm_up}} |
135 {error, #sctp_assoc_change{state = cant_assoc}} |
136 {error, inet:posix()}
137 Types:
139 Socket = sctp_socket()
141 Addr = inet:ip_address() | inet:hostname()
142 Port = inet:port_number()
143 Opts = [Opt :: option()]
144 Same as connect(Socket, Addr, Port, Opts, infinity).
146 connect(Socket, Addr, Port, Opts, Timeout) ->
148 {ok, #sctp_assoc_change{state = comm_up}} |
149 {error, #sctp_assoc_change{state = cant_assoc}} |
150 {error, inet:posix()}
151 Types:
153 Socket = sctp_socket()
155 Addr = inet:ip_address() | inet:hostname()
156 Port = inet:port_number()
157 Opts = [Opt :: option()]
158 Timeout = timeout()
159 Establishes a new association for socket Socket, with the peer
161 (SCTP server socket) specified by Addr and Port. Timeout, is ex‐
162 pressed in milliseconds. A socket can be associated with multi‐
163 ple peers.
164 Warning:
166 Using a value of Timeout less than the maximum time taken by the
167 OS to establish an association (around 4.5 minutes if the de‐
168 fault values from RFC 4960 are used), can result in inconsistent
169 or incorrect return values. This is especially relevant for as‐
170 sociations sharing the same Socket (that is, source address and
171 port), as the controlling process blocks until connect/* re‐
172 turns. connect_init/* provides an alternative without this limi‐
173 tation.
174 The result of connect/* is an #sctp_assoc_change{} event that
177 contains, in particular, the new Association ID:
178 #sctp_assoc_change{
180 state = atom(),
181 error = integer(),
182 outbound_streams = integer(),
183 inbound_streams = integer(),
184 assoc_id = assoc_id()
185 }
186 The number of outbound and inbound streams can be set by giving
188 an sctp_initmsg option to connect as in:
189 connect(Socket, Ip, Port>,
191 [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
192 max_instreams=MaxInStreams}}])
193 All options Opt are set on the socket before the association is
195 attempted. If an option record has undefined field values, the
196 options record is first read from the socket for those values.
197 In effect, Opt option records only define field values to change
198 before connecting.
199 The returned outbound_streams and inbound_streams are the stream
201 numbers on the socket. These can be different from the requested
202 values (OutStreams and MaxInStreams, respectively) if the peer
203 requires lower values.
204 state can have the following values:
206 comm_up:
208 Association is successfully established. This indicates a
209 successful completion of connect.
210 cant_assoc:
212 The association cannot be established (connect/* failure).
213 Other states do not normally occur in the output from connect/*.
215 Rather, they can occur in #sctp_assoc_change{} events received
216 instead of data in recv/* calls. All of them indicate losing the
217 association because of various error conditions, and are listed
218 here for the sake of completeness:
219 comm_lost:
221 restart:
224 shutdown_comp:
227 Field error can provide more detailed diagnostics. The error
230 field value can be converted into a string using error_string/1.
231 connect_init(Socket, Addr, Port, Opts) ->
233 ok | {error, inet:posix()}
234 Types:
236 Socket = sctp_socket()
238 Addr = inet:ip_address() | inet:hostname()
239 Port = inet:port_number()
240 Opts = [option()]
241 Same as connect_init(Socket, Addr, Port, Opts, infinity).
243 connect_init(Socket, Addr, Port, Opts, Timeout) ->
245 ok | {error, inet:posix()}
246 Types:
248 Socket = sctp_socket()
250 Addr = inet:ip_address() | inet:hostname()
251 Port = inet:port_number()
252 Opts = [option()]
253 Timeout = timeout()
254 Initiates a new association for socket Socket, with the peer
256 (SCTP server socket) specified by Addr and Port.
257 The fundamental difference between this API and connect/* is
259 that the return value is that of the underlying OS connect(2)
260 system call. If ok is returned, the result of the association
261 establishment is received by the calling process as an #sctp_as‐
262 soc_change{} event. The calling process must be prepared to re‐
263 ceive this, or poll for it using recv/*, depending on the value
264 of the active option.
265 The parameters are as described in connect/*, except the Timeout
267 value.
268 The timer associated with Timeout only supervises IP resolution
270 of Addr.
271 controlling_process(Socket, Pid) -> ok | {error, Reason}
273 Types:
275 Socket = sctp_socket()
277 Pid = pid()
278 Reason = closed | not_owner | badarg | inet:posix()
279 Assigns a new controlling process Pid to Socket. Same implemen‐
281 tation as gen_udp:controlling_process/2.
282 eof(Socket, Assoc) -> ok | {error, Reason}
284 Types:
286 Socket = sctp_socket()
288 Assoc = #sctp_assoc_change{}
289 Reason = term()
290 Gracefully terminates the association specified by Assoc, with
292 flushing of all unsent data. The socket itself remains open.
293 Other associations opened on this socket are still valid. The
294 socket can be used in new associations.
295 error_string(ErrorNumber) -> ok | string() | unknown_error
297 Types:
299 ErrorNumber = integer()
301 Translates an SCTP error number from, for example, #sctp_re‐
303 mote_error{} or #sctp_send_failed{} into an explanatory string,
304 or one of the atoms ok for no error or undefined for an unrecog‐
305 nized error.
306 listen(Socket, IsServer) -> ok | {error, Reason}
308 listen(Socket, Backlog) -> ok | {error, Reason}
310 Types:
312 Socket = sctp_socket()
314 Backlog = integer()
315 Reason = term()
316 Sets up a socket to listen on the IP address and port number it
318 is bound to.
319 For type seqpacket, sockets (the default) IsServer must be true
321 or false. In contrast to TCP, there is no listening queue length
322 in SCTP. If IsServer is true, the socket accepts new associa‐
323 tions, that is, it becomes an SCTP server socket.
324 For type stream, sockets Backlog define the backlog queue length
326 just like in TCP.
327 open() -> {ok, Socket} | {error, inet:posix()}
329 open(Port) -> {ok, Socket} | {error, inet:posix()}
331 open(Opts) -> {ok, Socket} | {error, inet:posix()}
333 open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
335 Types:
337 Opts = [Opt]
339 Opt =
340 {ip, IP} |
341 {ifaddr, IP} |
342 inet:address_family() |
343 {port, Port} |
344 {type, SockType} |
345 option()
346 IP = inet:ip_address() | any | loopback
347 Port = inet:port_number()
348 SockType = seqpacket | stream
349 Socket = sctp_socket()
350 Creates an SCTP socket and binds it to the local addresses spec‐
352 ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
353 feature is called SCTP multi-homing). The default IP and Port
354 are any and 0, meaning bind to all local addresses on any free
355 port.
356 Other options:
358 inet6:
360 Sets up the socket for IPv6.
361 inet:
363 Sets up the socket for IPv4. This is the default.
364 A default set of socket options is used. In particular, the
366 socket is opened in binary and passive mode, with SockType seq‐
367 packet, and with reasonably large kernel and driver buffers.
368 If the socket is in passive mode data can be received through
370 the recv/1,2 calls.
371 If the socket is in active mode data received data is delivered
373 to the controlling process as messages:
374 {sctp, Socket, FromIP, FromPort, {AncData, Data}}
376 See recv/1,2 for a description of the message fields.
379 Note:
381 This message format unfortunately differs slightly from the
382 gen_udp message format with ancillary data, and from the
383 recv/1,2 return tuple format.
384 peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
387 Types:
389 Socket = sctp_socket()
391 Assoc = #sctp_assoc_change{} | assoc_id()
392 NewSocket = sctp_socket()
393 Reason = term()
394 Branches off an existing association Assoc in a socket Socket of
396 type seqpacket (one-to-many style) into a new socket NewSocket
397 of type stream (one-to-one style).
398 The existing association argument Assoc can be either a
400 #sctp_assoc_change{} record as returned from, for example,
401 recv/*, connect/*, or from a listening socket in active mode. It
402 can also be just the field assoc_id integer from such a record.
403 recv(Socket) ->
405 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
406 recv(Socket, Timeout) ->
408 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
409 Types:
411 Socket = sctp_socket()
413 Timeout = timeout()
414 FromIP = inet:ip_address()
415 FromPort = inet:port_number()
416 AncData = [#sctp_sndrcvinfo{} | inet:ancillary_data()]
417 Data =
418 binary() |
419 string() |
420 #sctp_sndrcvinfo{} |
421 #sctp_assoc_change{} |
422 #sctp_paddr_change{} |
423 #sctp_adaptation_event{}
424 Reason =
425 inet:posix() |
426 #sctp_send_failed{} |
427 #sctp_paddr_change{} |
428 #sctp_pdapi_event{} |
429 #sctp_remote_error{} |
430 #sctp_shutdown_event{}
431 Receives the Data message from any association of the socket. If
433 the receive times out, {error,timeout} is returned. The default
434 time-out is infinity. FromIP and FromPort indicate the address
435 of the sender.
436 AncData is a list of ancillary data items that can be received
438 along with the main Data. This list can be empty, or contain a
439 single #sctp_sndrcvinfo{} record if receiving of such ancillary
440 data is enabled (see option sctp_events). It is enabled by de‐
441 fault, as such ancillary data provides an easy way of determin‐
442 ing the association and stream over which the message is re‐
443 ceived. (An alternative way is to get the association ID from
444 FromIP and FromPort using socket option sctp_get_peer_addr_info,
445 but this does still not produce the stream number).
446 AncData may also contain ancillary data from the socket op‐
448 tions recvtos, recvtclass or recvttl, if that is supported by
449 the platform for the socket.
450 The Data received can be a binary() or a list() of bytes (inte‐
452 gers in the range 0 through 255) depending on the socket mode,
453 or an SCTP event.
454 Possible SCTP events:
456 * #sctp_sndrcvinfo{}
458 * #sctp_assoc_change{}
460 *
462 #sctp_paddr_change{
465 addr = {ip_address(),port()},
466 state = atom(),
467 error = integer(),
468 assoc_id = assoc_id()
469 }
470 Indicates change of the status of the IP address of the peer
472 specified by addr within association assoc_id. Possible val‐
473 ues of state (mostly self-explanatory) include:
474 addr_unreachable:
476 addr_available:
479 addr_removed:
482 addr_added:
485 addr_made_prim:
488 addr_confirmed:
491 In case of an error (for example, addr_unreachable), field
494 error provides more diagnostics. In such cases, event
495 #sctp_paddr_change{} is automatically converted into an er‐
496 ror term returned by recv. The error field value can be con‐
497 verted into a string using error_string/1.
498 *
500 #sctp_send_failed{
503 flags = true | false,
504 error = integer(),
505 info = #sctp_sndrcvinfo{},
506 assoc_id = assoc_id()
507 data = binary()
508 }
509 The sender can receive this event if a send operation fails.
511 flags:
513 A Boolean specifying if the data has been transmitted over
514 the wire.
515 error:
517 Provides extended diagnostics, use error_string/1.
518 info:
520 The original #sctp_sndrcvinfo{} record used in the failed
521 send/*.
522 data:
524 The whole original data chunk attempted to be sent.
525 In the current implementation of the Erlang/SCTP binding,
527 this event is internally converted into an error term re‐
528 turned by recv/*.
529 *
531 #sctp_adaptation_event{
534 adaptation_ind = integer(),
535 assoc_id = assoc_id()
536 }
537 Delivered when a peer sends an adaptation layer indication
539 parameter (configured through option sctp_adaptation_layer).
540 Notice that with the current implementation of the Er‐
541 lang/SCTP binding, this event is disabled by default.
542 *
544 #sctp_pdapi_event{
547 indication = sctp_partial_delivery_aborted,
548 assoc_id = assoc_id()
549 }
550 A partial delivery failure. In the current implementation of
552 the Erlang/SCTP binding, this event is internally converted
553 into an error term returned by recv/*.
554 send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
556 Types:
558 Socket = sctp_socket()
560 SndRcvInfo = #sctp_sndrcvinfo{}
561 Data = binary() | iolist()
562 Reason = term()
563 Sends the Data message with all sending parameters from a
565 #sctp_sndrcvinfo{} record. This way, the user can specify the
566 PPID (passed to the remote end) and context (passed to the local
567 SCTP layer), which can be used, for example, for error identifi‐
568 cation. However, such a fine level of user control is rarely re‐
569 quired. The function send/4 is sufficient for most applications.
570 send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
572 Types:
574 Socket = sctp_socket()
576 Assoc = #sctp_assoc_change{} | assoc_id()
577 Stream = integer()
578 Data = binary() | iolist()
579 Reason = term()
580 Sends a Data message over an existing association and specified
582 stream.
583
585 The set of admissible SCTP socket options is by construction orthogonal
586 to the sets of TCP, UDP, and generic inet options. Only options listed
587 here are allowed for SCTP sockets. Options can be set on the socket us‐
588 ing open/1,2 or inet:setopts/2, retrieved using inet:getopts/2. Options
589 can be changed when calling connect/4,5.
590 {mode, list|binary} or just list or binary:
592 Determines the type of data returned from recv/1,2.
593 {active, true|false|once|N}:
595 * If false (passive mode, the default), the caller must do an ex‐
598 plicit recv call to retrieve the available data from the socket.
599 * If true|once|N (active modes) received data or events are sent to
601 the owning process. See open/0..2 for the message format.
602 * If true (full active mode) there is no flow control.
604 Note:
606 Note that this can cause the message queue to overflow causing for
607 example the virtual machine to run out of memory and crash.
608 * If once, only one message is automatically placed in the message
611 queue, and after that the mode is automatically reset to passive.
612 This provides flow control and the possibility for the receiver
613 to listen for its incoming SCTP data interleaved with other in‐
614 ter-process messages.
615 * If active is specified as an integer N in the range -32768 to
617 32767 (inclusive), that number is added to the socket's counting
618 of data messages to be delivered to the controlling process. If
619 the result of the addition is negative, the count is set to 0.
620 Once the count reaches 0, either through the delivery of messages
621 or by being explicitly set with inet:setopts/2, the socket mode
622 is automatically reset to passive ({active, false}). When a
623 socket in this active mode transitions to passive mode, the mes‐
624 sage {sctp_passive, Socket} is sent to the controlling process to
625 notify it that if it wants to receive more data messages from the
626 socket, it must call inet:setopts/2 to set the socket back into
627 an active mode.
628 {tos, integer()}:
630 Sets the Type-Of-Service field on the IP datagrams that are sent,
631 to the specified value. This effectively determines a prioritiza‐
632 tion policy for the outbound packets. The acceptable values are
633 system-dependent.
634 {priority, integer()}:
636 A protocol-independent equivalent of tos above. Setting priority
637 implies setting tos as well.
638 {dontroute, true|false}:
640 Defaults to false. If true, the kernel does not send packets
641 through any gateway, only sends them to directly connected hosts.
642 {reuseaddr, true|false}:
644 Defaults to false. If true, the local binding address {IP,Port} of
645 the socket can be reused immediately. No waiting in state
646 CLOSE_WAIT is performed (can be required for high-throughput
647 servers).
648 {sndbuf, integer()}:
650 The size, in bytes, of the OS kernel send buffer for this socket.
651 Sending errors would occur for datagrams larger than val(sndbuf).
652 Setting this option also adjusts the size of the driver buffer (see
653 buffer above).
654 {recbuf, integer()}:
656 The size, in bytes, of the OS kernel receive buffer for this
657 socket. Sending errors would occur for datagrams larger than
658 val(recbuf). Setting this option also adjusts the size of the
659 driver buffer (see buffer above).
660 {sctp_module, module()}:
662 Overrides which callback module is used. Defaults to inet_sctp for
663 IPv4 and inet6_sctp for IPv6.
664 {sctp_rtoinfo, #sctp_rtoinfo{}}:
666 #sctp_rtoinfo{
669 assoc_id = assoc_id(),
670 initial = integer(),
671 max = integer(),
672 min = integer()
673 }
674 Determines retransmission time-out parameters, in milliseconds, for
676 the association(s) specified by assoc_id.
677 assoc_id = 0 (default) indicates the whole endpoint. See RFC 2960
679 and Sockets API Extensions for SCTP for the exact semantics of the
680 field values.
681 {sctp_associnfo, #sctp_assocparams{}}:
683 #sctp_assocparams{
686 assoc_id = assoc_id(),
687 asocmaxrxt = integer(),
688 number_peer_destinations = integer(),
689 peer_rwnd = integer(),
690 local_rwnd = integer(),
691 cookie_life = integer()
692 }
693 Determines association parameters for the association(s) specified
695 by assoc_id.
696 assoc_id = 0 (default) indicates the whole endpoint. See Sockets
698 API Extensions for SCTP for the discussion of their semantics.
699 Rarely used.
700 {sctp_initmsg, #sctp_initmsg{}}:
702 #sctp_initmsg{
705 num_ostreams = integer(),
706 max_instreams = integer(),
707 max_attempts = integer(),
708 max_init_timeo = integer()
709 }
710 Determines the default parameters that this socket tries to negoti‐
712 ate with its peer while establishing an association with it. Is to
713 be set after open/* but before the first connect/*. #sctp_initmsg{}
714 can also be used as ancillary data with the first call of send/* to
715 a new peer (when a new association is created).
716 num_ostreams:
718 Number of outbound streams
719 max_instreams:
721 Maximum number of inbound streams
722 max_attempts:
724 Maximum retransmissions while establishing an association
725 max_init_timeo:
727 Time-out, in milliseconds, for establishing an association
728 {sctp_autoclose, integer() >= 0}:
730 Determines the time, in seconds, after which an idle association is
731 automatically closed. 0 means that the association is never auto‐
732 matically closed.
733 {sctp_nodelay, true|false}:
735 Turns on|off the Nagle algorithm for merging small packets into
736 larger ones. This improves throughput at the expense of latency.
737 {sctp_disable_fragments, true|false}:
739 If true, induces an error on an attempt to send a message larger
740 than the current PMTU size (which would require fragmentation/re‐
741 assembling). Notice that message fragmentation does not affect the
742 logical atomicity of its delivery; this option is provided for per‐
743 formance reasons only.
744 {sctp_i_want_mapped_v4_addr, true|false}:
746 Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
747 the socket address family is AF_INET6).
748 {sctp_maxseg, integer()}:
750 Determines the maximum chunk size if message fragmentation is used.
751 If 0, the chunk size is limited by the Path MTU only.
752 {sctp_primary_addr, #sctp_prim{}}:
754 #sctp_prim{
757 assoc_id = assoc_id(),
758 addr = {IP, Port}
759 }
760 IP = ip_address()
761 Port = port_number()
762 For the association specified by assoc_id, {IP,Port} must be one of
764 the peer addresses. This option determines that the specified ad‐
765 dress is treated by the local SCTP stack as the primary address of
766 the peer.
767 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
769 #sctp_setpeerprim{
772 assoc_id = assoc_id(),
773 addr = {IP, Port}
774 }
775 IP = ip_address()
776 Port = port_number()
777 When set, informs the peer to use {IP, Port} as the primary address
779 of the local endpoint for the association specified by assoc_id.
780 {sctp_adaptation_layer, #sctp_setadaptation{}}:
782 #sctp_setadaptation{
785 adaptation_ind = integer()
786 }
787 When set, requests that the local endpoint uses the value specified
789 by adaptation_ind as the Adaptation Indication parameter for estab‐
790 lishing new associations. For details, see RFC 2960 and Sockets API
791 Extenstions for SCTP.
792 {sctp_peer_addr_params, #sctp_paddrparams{}}:
794 #sctp_paddrparams{
797 assoc_id = assoc_id(),
798 address = {IP, Port},
799 hbinterval = integer(),
800 pathmaxrxt = integer(),
801 pathmtu = integer(),
802 sackdelay = integer(),
803 flags = list()
804 }
805 IP = ip_address()
806 Port = port_number()
807 Determines various per-address parameters for the association spec‐
809 ified by assoc_id and the peer address address (the SCTP protocol
810 supports multi-homing, so more than one address can correspond to a
811 specified association).
812 hbinterval:
814 Heartbeat interval, in milliseconds
815 pathmaxrxt:
817 Maximum number of retransmissions before this address is consid‐
818 ered unreachable (and an alternative address is selected)
819 pathmtu:
821 Fixed Path MTU, if automatic discovery is disabled (see flags be‐
822 low)
823 sackdelay:
825 Delay, in milliseconds, for SAC messages (if the delay is en‐
826 abled, see flags below)
827 flags:
829 The following flags are available:
830 hb_enable:
832 Enables heartbeat
833 hb_disable:
835 Disables heartbeat
836 hb_demand:
838 Initiates heartbeat immediately
839 pmtud_enable:
841 Enables automatic Path MTU discovery
842 pmtud_disable:
844 Disables automatic Path MTU discovery
845 sackdelay_enable:
847 Enables SAC delay
848 sackdelay_disable:
850 Disables SAC delay
851 {sctp_default_send_param, #sctp_sndrcvinfo{}}:
853 #sctp_sndrcvinfo{
856 stream = integer(),
857 ssn = integer(),
858 flags = list(),
859 ppid = integer(),
860 context = integer(),
861 timetolive = integer(),
862 tsn = integer(),
863 cumtsn = integer(),
864 assoc_id = assoc_id()
865 }
866 #sctp_sndrcvinfo{} is used both in this socket option, and as an‐
868 cillary data while sending or receiving SCTP messages. When set as
869 an option, it provides default values for subsequent send calls on
870 the association specified by assoc_id.
871 assoc_id = 0 (default) indicates the whole endpoint.
873 The following fields typically must be specified by the sender:
875 sinfo_stream:
877 Stream number (0-base) within the association to send the mes‐
878 sages through;
879 sinfo_flags:
881 The following flags are recognised:
882 unordered:
884 The message is to be sent unordered
885 addr_over:
887 The address specified in send overwrites the primary peer ad‐
888 dress
889 abort:
891 Aborts the current association without flushing any unsent data
892 eof:
894 Gracefully shuts down the current association, with flushing of
895 unsent data
896 Other fields are rarely used. For complete information, see RFC
898 2960 and Sockets API Extensions for SCTP.
899 {sctp_events, #sctp_event_subscribe{}}:
901 #sctp_event_subscribe{
904 data_io_event = true | false,
905 association_event = true | false,
906 address_event = true | false,
907 send_failure_event = true | false,
908 peer_error_event = true | false,
909 shutdown_event = true | false,
910 partial_delivery_event = true | false,
911 adaptation_layer_event = true | false
912 }
913 This option determines which SCTP Events are to be received
915 (through recv/*) along with the data. The only exception is
916 data_io_event, which enables or disables receiving of #sctp_sndrcv‐
917 info{} ancillary data, not events. By default, all flags except
918 adaptation_layer_event are enabled, although sctp_data_io_event and
919 association_event are used by the driver itself and not exported to
920 the user level.
921 {sctp_delayed_ack_time, #sctp_assoc_value{}}:
923 #sctp_assoc_value{
926 assoc_id = assoc_id(),
927 assoc_value = integer()
928 }
929 Rarely used. Determines the ACK time (specified by assoc_value, in
931 milliseconds) for the specified association or the whole endpoint
932 if assoc_value = 0 (default).
933 {sctp_status, #sctp_status{}}:
935 #sctp_status{
938 assoc_id = assoc_id(),
939 state = atom(),
940 rwnd = integer(),
941 unackdata = integer(),
942 penddata = integer(),
943 instrms = integer(),
944 outstrms = integer(),
945 fragmentation_point = integer(),
946 primary = #sctp_paddrinfo{}
947 }
948 This option is read-only. It determines the status of the SCTP as‐
950 sociation specified by assoc_id. The following are the possible
951 values of state (the state designations are mostly self-explana‐
952 tory):
953 sctp_state_empty:
955 Default. Means that no other state is active.
956 sctp_state_closed:
958 sctp_state_cookie_wait:
961 sctp_state_cookie_echoed:
964 sctp_state_established:
967 sctp_state_shutdown_pending:
970 sctp_state_shutdown_sent:
973 sctp_state_shutdown_received:
976 sctp_state_shutdown_ack_sent:
979 Semantics of the other fields:
982 sstat_rwnd:
984 Current receiver window size of the association
985 sstat_unackdata:
987 Number of unacked data chunks
988 sstat_penddata:
990 Number of data chunks pending receipt
991 sstat_instrms:
993 Number of inbound streams
994 sstat_outstrms:
996 Number of outbound streams
997 sstat_fragmentation_point:
999 Message size at which SCTP fragmentation occurs
1000 sstat_primary:
1002 Information on the current primary peer address (see below for
1003 the format of #sctp_paddrinfo{})
1004 {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1006 #sctp_paddrinfo{
1009 assoc_id = assoc_id(),
1010 address = {IP, Port},
1011 state = inactive | active | unconfirmed,
1012 cwnd = integer(),
1013 srtt = integer(),
1014 rto = integer(),
1015 mtu = integer()
1016 }
1017 IP = ip_address()
1018 Port = port_number()
1019 This option is read-only. It determines the parameters specific to
1021 the peer address specified by address within the association speci‐
1022 fied by assoc_id. Field address fmust be set by the caller; all
1023 other fields are filled in on return. If assoc_id = 0 (default),
1024 the address is automatically translated into the corresponding as‐
1025 sociation ID. This option is rarely used. For the semantics of all
1026 fields, see RFC 2960 and Sockets API Extensions for SCTP.
1027
1029 Example of an Erlang SCTP server that receives SCTP messages and prints
1030 them on the standard output:
1031 -module(sctp_server).
1033 -export([server/0,server/1,server/2]).
1035 -include_lib("kernel/include/inet.hrl").
1036 -include_lib("kernel/include/inet_sctp.hrl").
1037 server() ->
1039 server(any, 2006).
1040 server([Host,Port]) when is_list(Host), is_list(Port) ->
1042 {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1043 io:format("~w -> ~w~n", [Host, IP]),
1044 server([IP, list_to_integer(Port)]).
1045 server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1047 is_integer(Port) ->
1048 {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1049 io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1050 ok = gen_sctp:listen(S, true),
1051 server_loop(S).
1052 server_loop(S) ->
1054 case gen_sctp:recv(S) of
1055 {error, Error} ->
1056 io:format("SCTP RECV ERROR: ~p~n", [Error]);
1057 Data ->
1058 io:format("Received: ~p~n", [Data])
1059 end,
1060 server_loop(S).
1061 Example of an Erlang SCTP client interacting with the above server. No‐
1063 tice that in this example the client creates an association with the
1064 server with 5 outbound streams. Therefore, sending of "Test 0" over
1065 stream 0 succeeds, but sending of "Test 5" over stream 5 fails. The
1066 client then aborts the association, which results in that the corre‐
1067 sponding event is received on the server side.
1068 -module(sctp_client).
1070 -export([client/0, client/1, client/2]).
1072 -include_lib("kernel/include/inet.hrl").
1073 -include_lib("kernel/include/inet_sctp.hrl").
1074 client() ->
1076 client([localhost]).
1077 client([Host]) ->
1079 client(Host, 2006);
1080 client([Host, Port]) when is_list(Host), is_list(Port) ->
1082 client(Host,list_to_integer(Port)),
1083 init:stop().
1084 client(Host, Port) when is_integer(Port) ->
1086 {ok,S} = gen_sctp:open(),
1087 {ok,Assoc} = gen_sctp:connect
1088 (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1089 io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1090 io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1092 io:nl(),
1093 timer:sleep(10000),
1094 io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1095 io:nl(),
1096 timer:sleep(10000),
1097 io:write(gen_sctp:abort(S, Assoc)),
1098 io:nl(),
1099 timer:sleep(1000),
1101 gen_sctp:close(S).
1102 A simple Erlang SCTP client that uses the connect_init API:
1104 -module(ex3).
1106 -export([client/4]).
1108 -include_lib("kernel/include/inet.hrl").
1109 -include_lib("kernel/include/inet_sctp.hrl").
1110 client(Peer1, Port1, Peer2, Port2)
1112 when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1113 {ok,S} = gen_sctp:open(),
1114 SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1115 ActiveOpt = {active, true},
1116 Opts = [SctpInitMsgOpt, ActiveOpt],
1117 ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1118 ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1119 io:format("Connections initiated~n", []),
1120 client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1121 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1123 receive
1124 {sctp, S, Peer1, Port1, {_Anc, SAC}}
1125 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1126 io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1127 [SAC#sctp_assoc_change.state,
1128 SAC#sctp_assoc_change.assoc_id]),
1129 client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1130 Peer2, Port2, AssocId2);
1131 {sctp, S, Peer2, Port2, {_Anc, SAC}}
1133 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1134 io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1135 [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1136 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1137 SAC#sctp_assoc_change.assoc_id);
1138 {sctp, S, Peer1, Port1, Data} ->
1140 io:format("Association 1: received ~p~n", [Data]),
1141 client_loop(S, Peer1, Port1, AssocId1,
1142 Peer2, Port2, AssocId2);
1143 {sctp, S, Peer2, Port2, Data} ->
1145 io:format("Association 2: received ~p~n", [Data]),
1146 client_loop(S, Peer1, Port1, AssocId1,
1147 Peer2, Port2, AssocId2);
1148 Other ->
1150 io:format("Other ~p~n", [Other]),
1151 client_loop(S, Peer1, Port1, AssocId1,
1152 Peer2, Port2, AssocId2)
1153 after 5000 ->
1155 ok
1156 end.
1157
1159 gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control Transmission
1160 Protocol), Sockets API Extensions for SCTP
1161Ericsson AB kernel 8.1.3 gen_sctp(3)