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 |
61 binary |
62 {priority, integer() >= 0} |
63 {recbuf, integer() >= 0} |
64 {reuseaddr, boolean()} |
65 {ipv6_v6only, boolean()} |
66 {sctp_adaptation_layer, #sctp_setadaptation{}} |
67 {sctp_associnfo, #sctp_assocparams{}} |
68 {sctp_autoclose, integer() >= 0} |
69 {sctp_default_send_param, #sctp_sndrcvinfo{}} |
70 {sctp_delayed_ack_time, #sctp_assoc_value{}} |
71 {sctp_disable_fragments, boolean()} |
72 {sctp_events, #sctp_event_subscribe{}} |
73 {sctp_get_peer_addr_info, #sctp_paddrinfo{}} |
74 {sctp_i_want_mapped_v4_addr, boolean()} |
75 {sctp_initmsg, #sctp_initmsg{}} |
76 {sctp_maxseg, integer() >= 0} |
77 {sctp_nodelay, boolean()} |
78 {sctp_peer_addr_params, #sctp_paddrparams{}} |
79 {sctp_primary_addr, #sctp_prim{}} |
80 {sctp_rtoinfo, #sctp_rtoinfo{}} |
81 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}} |
82 {sctp_status, #sctp_status{}} |
83 {sndbuf, integer() >= 0} |
84 {tos, integer() >= 0}
85 One of the SCTP Socket Options.
87 option_name() =
89 active |
90 buffer |
91 dontroute |
92 high_msgq_watermark |
93 linger |
94 low_msgq_watermark |
95 mode |
96 priority |
97 recbuf |
98 reuseaddr |
99 ipv6_v6only |
100 sctp_adaptation_layer |
101 sctp_associnfo |
102 sctp_autoclose |
103 sctp_default_send_param |
104 sctp_delayed_ack_time |
105 sctp_disable_fragments |
106 sctp_events |
107 sctp_get_peer_addr_info |
108 sctp_i_want_mapped_v4_addr |
109 sctp_initmsg |
110 sctp_maxseg |
111 sctp_nodelay |
112 sctp_peer_addr_params |
113 sctp_primary_addr |
114 sctp_rtoinfo |
115 sctp_set_peer_primary_addr |
116 sctp_status |
117 sndbuf |
118 tos
119 sctp_socket()
121 Socket identifier returned from open/*.
123
125 abort(Socket, Assoc) -> ok | {error, inet:posix()}
126 Types:
128 Socket = sctp_socket()
130 Assoc = #sctp_assoc_change{}
131 Abnormally terminates the association specified by Assoc, with‐
133 out flushing of unsent data. The socket itself remains open.
134 Other associations opened on this socket are still valid, and
135 the socket can be used in new associations.
136 close(Socket) -> ok | {error, inet:posix()}
138 Types:
140 Socket = sctp_socket()
142 Closes the socket and all associations on it. The unsent data is
144 flushed as in eof/2. The close/1 call is blocking or otherwise
145 depending of the value of the linger socket option. If close
146 does not linger or linger time-out expires, the call returns and
147 the data is flushed in the background.
148 connect(Socket, Addr, Port, Opts) ->
150 {ok, Assoc} | {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 Assoc = #sctp_assoc_change{}
159 Same as connect(Socket, Addr, Port, Opts, infinity).
161 connect(Socket, Addr, Port, Opts, Timeout) ->
163 {ok, Assoc} | {error, inet:posix()}
164 Types:
166 Socket = sctp_socket()
168 Addr = inet:ip_address() | inet:hostname()
169 Port = inet:port_number()
170 Opts = [Opt :: option()]
171 Timeout = timeout()
172 Assoc = #sctp_assoc_change{}
173 Establishes a new association for socket Socket, with the peer
175 (SCTP server socket) specified by Addr and Port. Timeout, is
176 expressed in milliseconds. A socket can be associated with mul‐
177 tiple peers.
178 Warning:
180 Using a value of Timeout less than the maximum time taken by the
181 OS to establish an association (around 4.5 minutes if the
182 default values from RFC 4960 are used), can result in inconsis‐
183 tent or incorrect return values. This is especially relevant for
184 associations sharing the same Socket (that is, source address
185 and port), as the controlling process blocks until connect/*
186 returns. connect_init/* provides an alternative without this
187 limitation.
188 The result of connect/* is an #sctp_assoc_change{} event that
191 contains, in particular, the new Association ID:
192 #sctp_assoc_change{
194 state = atom(),
195 error = atom(),
196 outbound_streams = integer(),
197 inbound_streams = integer(),
198 assoc_id = assoc_id()
199 }
200 The number of outbound and inbound streams can be set by giving
202 an sctp_initmsg option to connect as in:
203 connect(Socket, Ip, Port>,
205 [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
206 max_instreams=MaxInStreams}}])
207 All options Opt are set on the socket before the association is
209 attempted. If an option record has undefined field values, the
210 options record is first read from the socket for those values.
211 In effect, Opt option records only define field values to change
212 before connecting.
213 The returned outbound_streams and inbound_streams are the stream
215 numbers on the socket. These can be different from the requested
216 values (OutStreams and MaxInStreams, respectively) if the peer
217 requires lower values.
218 state can have the following values:
220 comm_up:
222 Association is successfully established. This indicates a
223 successful completion of connect.
224 cant_assoc:
226 The association cannot be established (connect/* failure).
227 Other states do not normally occur in the output from connect/*.
229 Rather, they can occur in #sctp_assoc_change{} events received
230 instead of data in recv/* calls. All of them indicate losing the
231 association because of various error conditions, and are listed
232 here for the sake of completeness:
233 comm_lost:
235 restart:
238 shutdown_comp:
241 Field error can provide more detailed diagnostics.
244 connect_init(Socket, Addr, Port, Opts) ->
246 ok | {error, inet:posix()}
247 Types:
249 Socket = sctp_socket()
251 Addr = inet:ip_address() | inet:hostname()
252 Port = inet:port_number()
253 Opts = [option()]
254 Same as connect_init(Socket, Addr, Port, Opts, infinity).
256 connect_init(Socket, Addr, Port, Opts, Timeout) ->
258 ok | {error, inet:posix()}
259 Types:
261 Socket = sctp_socket()
263 Addr = inet:ip_address() | inet:hostname()
264 Port = inet:port_number()
265 Opts = [option()]
266 Timeout = timeout()
267 Initiates a new association for socket Socket, with the peer
269 (SCTP server socket) specified by Addr and Port.
270 The fundamental difference between this API and connect/* is
272 that the return value is that of the underlying OS connect(2)
273 system call. If ok is returned, the result of the association
274 establishment is received by the calling process as an
275 #sctp_assoc_change{} event. The calling process must be prepared
276 to receive this, or poll for it using recv/*, depending on the
277 value of the active option.
278 The parameters are as described in connect/*, except the Timeout
280 value.
281 The timer associated with Timeout only supervises IP resolution
283 of Addr.
284 controlling_process(Socket, Pid) -> ok | {error, Reason}
286 Types:
288 Socket = sctp_socket()
290 Pid = pid()
291 Reason = closed | not_owner | badarg | inet:posix()
292 Assigns a new controlling process Pid to Socket. Same implemen‐
294 tation as gen_udp:controlling_process/2.
295 eof(Socket, Assoc) -> ok | {error, Reason}
297 Types:
299 Socket = sctp_socket()
301 Assoc = #sctp_assoc_change{}
302 Reason = term()
303 Gracefully terminates the association specified by Assoc, with
305 flushing of all unsent data. The socket itself remains open.
306 Other associations opened on this socket are still valid. The
307 socket can be used in new associations.
308 error_string(ErrorNumber) -> ok | string() | unknown_error
310 Types:
312 ErrorNumber = integer()
314 Translates an SCTP error number from, for example,
316 #sctp_remote_error{} or #sctp_send_failed{} into an explanatory
317 string, or one of the atoms ok for no error or undefined for an
318 unrecognized error.
319 listen(Socket, IsServer) -> ok | {error, Reason}
321 listen(Socket, Backlog) -> ok | {error, Reason}
323 Types:
325 Socket = sctp_socket()
327 Backlog = integer()
328 Reason = term()
329 Sets up a socket to listen on the IP address and port number it
331 is bound to.
332 For type seqpacket, sockets (the default) IsServer must be true
334 or false. In contrast to TCP, there is no listening queue length
335 in SCTP. If IsServer is true, the socket accepts new associa‐
336 tions, that is, it becomes an SCTP server socket.
337 For type stream, sockets Backlog define the backlog queue length
339 just like in TCP.
340 open() -> {ok, Socket} | {error, inet:posix()}
342 open(Port) -> {ok, Socket} | {error, inet:posix()}
344 open(Opts) -> {ok, Socket} | {error, inet:posix()}
346 open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
348 Types:
350 Opts = [Opt]
352 Opt =
353 {ip, IP} |
354 {ifaddr, IP} |
355 inet:address_family() |
356 {port, Port} |
357 {type, SockType} |
358 option()
359 IP = inet:ip_address() | any | loopback
360 Port = inet:port_number()
361 SockType = seqpacket | stream
362 Socket = sctp_socket()
363 Creates an SCTP socket and binds it to the local addresses spec‐
365 ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
366 feature is called SCTP multi-homing). The default IP and Port
367 are any and 0, meaning bind to all local addresses on any free
368 port.
369 Other options:
371 inet6:
373 Sets up the socket for IPv6.
374 inet:
376 Sets up the socket for IPv4. This is the default.
377 A default set of socket options is used. In particular, the
379 socket is opened in binary and passive mode, with SockType seq‐
380 packet, and with reasonably large kernel and driver buffers.
381 peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
383 Types:
385 Socket = sctp_socket()
387 Assoc = #sctp_assoc_change{} | assoc_id()
388 NewSocket = sctp_socket()
389 Reason = term()
390 Branches off an existing association Assoc in a socket Socket of
392 type seqpacket (one-to-many style) into a new socket NewSocket
393 of type stream (one-to-one style).
394 The existing association argument Assoc can be either a
396 #sctp_assoc_change{} record as returned from, for example,
397 recv/*, connect/*, or from a listening socket in active mode. It
398 can also be just the field assoc_id integer from such a record.
399 recv(Socket) ->
401 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
402 recv(Socket, Timeout) ->
404 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
405 Types:
407 Socket = sctp_socket()
409 Timeout = timeout()
410 FromIP = inet:ip_address()
411 FromPort = inet:port_number()
412 AncData = [#sctp_sndrcvinfo{}]
413 Data =
414 binary() |
415 string() |
416 #sctp_sndrcvinfo{} |
417 #sctp_assoc_change{} |
418 #sctp_paddr_change{} |
419 #sctp_adaptation_event{}
420 Reason =
421 inet:posix() |
422 #sctp_send_failed{} |
423 #sctp_paddr_change{} |
424 #sctp_pdapi_event{} |
425 #sctp_remote_error{} |
426 #sctp_shutdown_event{}
427 Receives the Data message from any association of the socket. If
429 the receive times out, {error,timeout} is returned. The default
430 time-out is infinity. FromIP and FromPort indicate the address
431 of the sender.
432 AncData is a list of ancillary data items that can be received
434 along with the main Data. This list can be empty, or contain a
435 single #sctp_sndrcvinfo{} record if receiving of such ancillary
436 data is enabled (see option sctp_events). It is enabled by
437 default, as such ancillary data provides an easy way of deter‐
438 mining the association and stream over which the message is
439 received. (An alternative way is to get the association ID from
440 FromIP and FromPort using socket option sctp_get_peer_addr_info,
441 but this does still not produce the stream number).
442 The Data received can be a binary() or a list() of bytes (inte‐
444 gers in the range 0 through 255) depending on the socket mode,
445 or an SCTP event.
446 Possible SCTP events:
448 * #sctp_sndrcvinfo{}
450 * #sctp_assoc_change{}
452 *
454 #sctp_paddr_change{
457 addr = {ip_address(),port()},
458 state = atom(),
459 error = integer(),
460 assoc_id = assoc_id()
461 }
462 Indicates change of the status of the IP address of the peer
464 specified by addr within association assoc_id. Possible val‐
465 ues of state (mostly self-explanatory) include:
466 addr_unreachable:
468 addr_available:
471 addr_removed:
474 addr_added:
477 addr_made_prim:
480 addr_confirmed:
483 In case of an error (for example, addr_unreachable), field
486 error provides more diagnostics. In such cases, event
487 #sctp_paddr_change{} is automatically converted into an
488 error term returned by recv. The error field value can be
489 converted into a string using error_string/1.
490 *
492 #sctp_send_failed{
495 flags = true | false,
496 error = integer(),
497 info = #sctp_sndrcvinfo{},
498 assoc_id = assoc_id()
499 data = binary()
500 }
501 The sender can receive this event if a send operation fails.
503 flags:
505 A Boolean specifying if the data has been transmitted over
506 the wire.
507 error:
509 Provides extended diagnostics, use error_string/1.
510 info:
512 The original #sctp_sndrcvinfo{} record used in the failed
513 send/*.
514 data:
516 The whole original data chunk attempted to be sent.
517 In the current implementation of the Erlang/SCTP binding,
519 this event is internally converted into an error term
520 returned by recv/*.
521 *
523 #sctp_adaptation_event{
526 adaptation_ind = integer(),
527 assoc_id = assoc_id()
528 }
529 Delivered when a peer sends an adaptation layer indication
531 parameter (configured through option sctp_adaptation_layer).
532 Notice that with the current implementation of the
533 Erlang/SCTP binding, this event is disabled by default.
534 *
536 #sctp_pdapi_event{
539 indication = sctp_partial_delivery_aborted,
540 assoc_id = assoc_id()
541 }
542 A partial delivery failure. In the current implementation of
544 the Erlang/SCTP binding, this event is internally converted
545 into an error term returned by recv/*.
546 send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
548 Types:
550 Socket = sctp_socket()
552 SndRcvInfo = #sctp_sndrcvinfo{}
553 Data = binary() | iolist()
554 Reason = term()
555 Sends the Data message with all sending parameters from a
557 #sctp_sndrcvinfo{} record. This way, the user can specify the
558 PPID (passed to the remote end) and context (passed to the local
559 SCTP layer), which can be used, for example, for error identifi‐
560 cation. However, such a fine level of user control is rarely
561 required. The function send/4 is sufficient for most applica‐
562 tions.
563 send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
565 Types:
567 Socket = sctp_socket()
569 Assoc = #sctp_assoc_change{} | assoc_id()
570 Stream = integer()
571 Data = binary() | iolist()
572 Reason = term()
573 Sends a Data message over an existing association and specified
575 stream.
576
578 The set of admissible SCTP socket options is by construction orthogonal
579 to the sets of TCP, UDP, and generic inet options. Only options listed
580 here are allowed for SCTP sockets. Options can be set on the socket
581 using open/1,2 or inet:setopts/2, retrieved using inet:getopts/2.
582 Options can be changed when calling connect/4,5.
583 {mode, list|binary} or just list or binary:
585 Determines the type of data returned from recv/1,2.
586 {active, true|false|once|N}:
588 * If false (passive mode, the default), the caller must do an
591 explicit recv call to retrieve the available data from the
592 socket.
593 * If true (full active mode), the pending data or events are sent
595 to the owning process.
596 Notice that this can cause the message queue to overflow, as
598 there is no way to throttle the sender in this case (no flow con‐
599 trol).
600 * If once, only one message is automatically placed in the message
602 queue, and after that the mode is automatically reset to passive.
603 This provides flow control and the possibility for the receiver
604 to listen for its incoming SCTP data interleaved with other
605 inter-process messages.
606 * If active is specified as an integer N in the range -32768 to
608 32767 (inclusive), that number is added to the socket's counting
609 of data messages to be delivered to the controlling process. If
610 the result of the addition is negative, the count is set to 0.
611 Once the count reaches 0, either through the delivery of messages
612 or by being explicitly set with inet:setopts/2, the socket mode
613 is automatically reset to passive ({active, false}). When a
614 socket in this active mode transitions to passive mode, the mes‐
615 sage {sctp_passive, Socket} is sent to the controlling process to
616 notify it that if it wants to receive more data messages from the
617 socket, it must call inet:setopts/2 to set the socket back into
618 an active mode.
619 {tos, integer()}:
621 Sets the Type-Of-Service field on the IP datagrams that are sent,
622 to the specified value. This effectively determines a prioritiza‐
623 tion policy for the outbound packets. The acceptable values are
624 system-dependent.
625 {priority, integer()}:
627 A protocol-independent equivalent of tos above. Setting priority
628 implies setting tos as well.
629 {dontroute, true|false}:
631 Defaults to false. If true, the kernel does not send packets
632 through any gateway, only sends them to directly connected hosts.
633 {reuseaddr, true|false}:
635 Defaults to false. If true, the local binding address {IP,Port} of
636 the socket can be reused immediately. No waiting in state
637 CLOSE_WAIT is performed (can be required for high-throughput
638 servers).
639 {sndbuf, integer()}:
641 The size, in bytes, of the OS kernel send buffer for this socket.
642 Sending errors would occur for datagrams larger than val(sndbuf).
643 Setting this option also adjusts the size of the driver buffer (see
644 buffer above).
645 {recbuf, integer()}:
647 The size, in bytes, of the OS kernel receive buffer for this
648 socket. Sending errors would occur for datagrams larger than
649 val(recbuf). Setting this option also adjusts the size of the
650 driver buffer (see buffer above).
651 {sctp_module, module()}:
653 Overrides which callback module is used. Defaults to inet_sctp for
654 IPv4 and inet6_sctp for IPv6.
655 {sctp_rtoinfo, #sctp_rtoinfo{}}:
657 #sctp_rtoinfo{
660 assoc_id = assoc_id(),
661 initial = integer(),
662 max = integer(),
663 min = integer()
664 }
665 Determines retransmission time-out parameters, in milliseconds, for
667 the association(s) specified by assoc_id.
668 assoc_id = 0 (default) indicates the whole endpoint. See RFC 2960
670 and Sockets API Extensions for SCTP for the exact semantics of the
671 field values.
672 {sctp_associnfo, #sctp_assocparams{}}:
674 #sctp_assocparams{
677 assoc_id = assoc_id(),
678 asocmaxrxt = integer(),
679 number_peer_destinations = integer(),
680 peer_rwnd = integer(),
681 local_rwnd = integer(),
682 cookie_life = integer()
683 }
684 Determines association parameters for the association(s) specified
686 by assoc_id.
687 assoc_id = 0 (default) indicates the whole endpoint. See Sockets
689 API Extensions for SCTP for the discussion of their semantics.
690 Rarely used.
691 {sctp_initmsg, #sctp_initmsg{}}:
693 #sctp_initmsg{
696 num_ostreams = integer(),
697 max_instreams = integer(),
698 max_attempts = integer(),
699 max_init_timeo = integer()
700 }
701 Determines the default parameters that this socket tries to negoti‐
703 ate with its peer while establishing an association with it. Is to
704 be set after open/* but before the first connect/*. #sctp_initmsg{}
705 can also be used as ancillary data with the first call of send/* to
706 a new peer (when a new association is created).
707 num_ostreams:
709 Number of outbound streams
710 max_instreams:
712 Maximum number of inbound streams
713 max_attempts:
715 Maximum retransmissions while establishing an association
716 max_init_timeo:
718 Time-out, in milliseconds, for establishing an association
719 {sctp_autoclose, integer() >= 0}:
721 Determines the time, in seconds, after which an idle association is
722 automatically closed. 0 means that the association is never auto‐
723 matically closed.
724 {sctp_nodelay, true|false}:
726 Turns on|off the Nagle algorithm for merging small packets into
727 larger ones. This improves throughput at the expense of latency.
728 {sctp_disable_fragments, true|false}:
730 If true, induces an error on an attempt to send a message larger
731 than the current PMTU size (which would require fragmenta‐
732 tion/reassembling). Notice that message fragmentation does not
733 affect the logical atomicity of its delivery; this option is pro‐
734 vided for performance reasons only.
735 {sctp_i_want_mapped_v4_addr, true|false}:
737 Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
738 the socket address family is AF_INET6).
739 {sctp_maxseg, integer()}:
741 Determines the maximum chunk size if message fragmentation is used.
742 If 0, the chunk size is limited by the Path MTU only.
743 {sctp_primary_addr, #sctp_prim{}}:
745 #sctp_prim{
748 assoc_id = assoc_id(),
749 addr = {IP, Port}
750 }
751 IP = ip_address()
752 Port = port_number()
753 For the association specified by assoc_id, {IP,Port} must be one of
755 the peer addresses. This option determines that the specified
756 address is treated by the local SCTP stack as the primary address
757 of the peer.
758 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
760 #sctp_setpeerprim{
763 assoc_id = assoc_id(),
764 addr = {IP, Port}
765 }
766 IP = ip_address()
767 Port = port_number()
768 When set, informs the peer to use {IP, Port} as the primary address
770 of the local endpoint for the association specified by assoc_id.
771 {sctp_adaptation_layer, #sctp_setadaptation{}}:
773 #sctp_setadaptation{
776 adaptation_ind = integer()
777 }
778 When set, requests that the local endpoint uses the value specified
780 by adaptation_ind as the Adaptation Indication parameter for estab‐
781 lishing new associations. For details, see RFC 2960 and Sockets API
782 Extenstions for SCTP.
783 {sctp_peer_addr_params, #sctp_paddrparams{}}:
785 #sctp_paddrparams{
788 assoc_id = assoc_id(),
789 address = {IP, Port},
790 hbinterval = integer(),
791 pathmaxrxt = integer(),
792 pathmtu = integer(),
793 sackdelay = integer(),
794 flags = list()
795 }
796 IP = ip_address()
797 Port = port_number()
798 Determines various per-address parameters for the association spec‐
800 ified by assoc_id and the peer address address (the SCTP protocol
801 supports multi-homing, so more than one address can correspond to a
802 specified association).
803 hbinterval:
805 Heartbeat interval, in milliseconds
806 pathmaxrxt:
808 Maximum number of retransmissions before this address is consid‐
809 ered unreachable (and an alternative address is selected)
810 pathmtu:
812 Fixed Path MTU, if automatic discovery is disabled (see flags
813 below)
814 sackdelay:
816 Delay, in milliseconds, for SAC messages (if the delay is
817 enabled, see flags below)
818 flags:
820 The following flags are available:
821 hb_enable:
823 Enables heartbeat
824 hb_disable:
826 Disables heartbeat
827 hb_demand:
829 Initiates heartbeat immediately
830 pmtud_enable:
832 Enables automatic Path MTU discovery
833 pmtud_disable:
835 Disables automatic Path MTU discovery
836 sackdelay_enable:
838 Enables SAC delay
839 sackdelay_disable:
841 Disables SAC delay
842 {sctp_default_send_param, #sctp_sndrcvinfo{}}:
844 #sctp_sndrcvinfo{
847 stream = integer(),
848 ssn = integer(),
849 flags = list(),
850 ppid = integer(),
851 context = integer(),
852 timetolive = integer(),
853 tsn = integer(),
854 cumtsn = integer(),
855 assoc_id = assoc_id()
856 }
857 #sctp_sndrcvinfo{} is used both in this socket option, and as
859 ancillary data while sending or receiving SCTP messages. When set
860 as an option, it provides default values for subsequent send calls
861 on the association specified by assoc_id.
862 assoc_id = 0 (default) indicates the whole endpoint.
864 The following fields typically must be specified by the sender:
866 sinfo_stream:
868 Stream number (0-base) within the association to send the mes‐
869 sages through;
870 sinfo_flags:
872 The following flags are recognised:
873 unordered:
875 The message is to be sent unordered
876 addr_over:
878 The address specified in send overwrites the primary peer
879 address
880 abort:
882 Aborts the current association without flushing any unsent data
883 eof:
885 Gracefully shuts down the current association, with flushing of
886 unsent data
887 Other fields are rarely used. For complete information, see RFC
889 2960 and Sockets API Extensions for SCTP.
890 {sctp_events, #sctp_event_subscribe{}}:
892 #sctp_event_subscribe{
895 data_io_event = true | false,
896 association_event = true | false,
897 address_event = true | false,
898 send_failure_event = true | false,
899 peer_error_event = true | false,
900 shutdown_event = true | false,
901 partial_delivery_event = true | false,
902 adaptation_layer_event = true | false
903 }
904 This option determines which SCTP Events are to be received
906 (through recv/*) along with the data. The only exception is
907 data_io_event, which enables or disables receiving of #sctp_sndrcv‐
908 info{} ancillary data, not events. By default, all flags except
909 adaptation_layer_event are enabled, although sctp_data_io_event and
910 association_event are used by the driver itself and not exported to
911 the user level.
912 {sctp_delayed_ack_time, #sctp_assoc_value{}}:
914 #sctp_assoc_value{
917 assoc_id = assoc_id(),
918 assoc_value = integer()
919 }
920 Rarely used. Determines the ACK time (specified by assoc_value, in
922 milliseconds) for the specified association or the whole endpoint
923 if assoc_value = 0 (default).
924 {sctp_status, #sctp_status{}}:
926 #sctp_status{
929 assoc_id = assoc_id(),
930 state = atom(),
931 rwnd = integer(),
932 unackdata = integer(),
933 penddata = integer(),
934 instrms = integer(),
935 outstrms = integer(),
936 fragmentation_point = integer(),
937 primary = #sctp_paddrinfo{}
938 }
939 This option is read-only. It determines the status of the SCTP
941 association specified by assoc_id. The following are the possible
942 values of state (the state designations are mostly self-explana‐
943 tory):
944 sctp_state_empty:
946 Default. Means that no other state is active.
947 sctp_state_closed:
949 sctp_state_cookie_wait:
952 sctp_state_cookie_echoed:
955 sctp_state_established:
958 sctp_state_shutdown_pending:
961 sctp_state_shutdown_sent:
964 sctp_state_shutdown_received:
967 sctp_state_shutdown_ack_sent:
970 Semantics of the other fields:
973 sstat_rwnd:
975 Current receiver window size of the association
976 sstat_unackdata:
978 Number of unacked data chunks
979 sstat_penddata:
981 Number of data chunks pending receipt
982 sstat_instrms:
984 Number of inbound streams
985 sstat_outstrms:
987 Number of outbound streams
988 sstat_fragmentation_point:
990 Message size at which SCTP fragmentation occurs
991 sstat_primary:
993 Information on the current primary peer address (see below for
994 the format of #sctp_paddrinfo{})
995 {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
997 #sctp_paddrinfo{
1000 assoc_id = assoc_id(),
1001 address = {IP, Port},
1002 state = inactive | active | unconfirmed,
1003 cwnd = integer(),
1004 srtt = integer(),
1005 rto = integer(),
1006 mtu = integer()
1007 }
1008 IP = ip_address()
1009 Port = port_number()
1010 This option is read-only. It determines the parameters specific to
1012 the peer address specified by address within the association speci‐
1013 fied by assoc_id. Field address fmust be set by the caller; all
1014 other fields are filled in on return. If assoc_id = 0 (default),
1015 the address is automatically translated into the corresponding
1016 association ID. This option is rarely used. For the semantics of
1017 all fields, see RFC 2960 and Sockets API Extensions for SCTP.
1018
1020 Example of an Erlang SCTP server that receives SCTP messages and prints
1021 them on the standard output:
1022 -module(sctp_server).
1024 -export([server/0,server/1,server/2]).
1026 -include_lib("kernel/include/inet.hrl").
1027 -include_lib("kernel/include/inet_sctp.hrl").
1028 server() ->
1030 server(any, 2006).
1031 server([Host,Port]) when is_list(Host), is_list(Port) ->
1033 {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1034 io:format("~w -> ~w~n", [Host, IP]),
1035 server([IP, list_to_integer(Port)]).
1036 server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1038 is_integer(Port) ->
1039 {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1040 io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1041 ok = gen_sctp:listen(S, true),
1042 server_loop(S).
1043 server_loop(S) ->
1045 case gen_sctp:recv(S) of
1046 {error, Error} ->
1047 io:format("SCTP RECV ERROR: ~p~n", [Error]);
1048 Data ->
1049 io:format("Received: ~p~n", [Data])
1050 end,
1051 server_loop(S).
1052 Example of an Erlang SCTP client interacting with the above server.
1054 Notice that in this example the client creates an association with the
1055 server with 5 outbound streams. Therefore, sending of "Test 0" over
1056 stream 0 succeeds, but sending of "Test 5" over stream 5 fails. The
1057 client then aborts the association, which results in that the corre‐
1058 sponding event is received on the server side.
1059 -module(sctp_client).
1061 -export([client/0, client/1, client/2]).
1063 -include_lib("kernel/include/inet.hrl").
1064 -include_lib("kernel/include/inet_sctp.hrl").
1065 client() ->
1067 client([localhost]).
1068 client([Host]) ->
1070 client(Host, 2006);
1071 client([Host, Port]) when is_list(Host), is_list(Port) ->
1073 client(Host,list_to_integer(Port)),
1074 init:stop().
1075 client(Host, Port) when is_integer(Port) ->
1077 {ok,S} = gen_sctp:open(),
1078 {ok,Assoc} = gen_sctp:connect
1079 (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1080 io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1081 io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1083 io:nl(),
1084 timer:sleep(10000),
1085 io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1086 io:nl(),
1087 timer:sleep(10000),
1088 io:write(gen_sctp:abort(S, Assoc)),
1089 io:nl(),
1090 timer:sleep(1000),
1092 gen_sctp:close(S).
1093 A simple Erlang SCTP client that uses the connect_init API:
1095 -module(ex3).
1097 -export([client/4]).
1099 -include_lib("kernel/include/inet.hrl").
1100 -include_lib("kernel/include/inet_sctp.hrl").
1101 client(Peer1, Port1, Peer2, Port2)
1103 when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1104 {ok,S} = gen_sctp:open(),
1105 SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1106 ActiveOpt = {active, true},
1107 Opts = [SctpInitMsgOpt, ActiveOpt],
1108 ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1109 ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1110 io:format("Connections initiated~n", []),
1111 client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1112 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1114 receive
1115 {sctp, S, Peer1, Port1, {_Anc, SAC}}
1116 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1117 io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1118 [SAC#sctp_assoc_change.state,
1119 SAC#sctp_assoc_change.assoc_id]),
1120 client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1121 Peer2, Port2, AssocId2);
1122 {sctp, S, Peer2, Port2, {_Anc, SAC}}
1124 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1125 io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1126 [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1127 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1128 SAC#sctp_assoc_change.assoc_id);
1129 {sctp, S, Peer1, Port1, Data} ->
1131 io:format("Association 1: received ~p~n", [Data]),
1132 client_loop(S, Peer1, Port1, AssocId1,
1133 Peer2, Port2, AssocId2);
1134 {sctp, S, Peer2, Port2, Data} ->
1136 io:format("Association 2: received ~p~n", [Data]),
1137 client_loop(S, Peer1, Port1, AssocId1,
1138 Peer2, Port2, AssocId2);
1139 Other ->
1141 io:format("Other ~p~n", [Other]),
1142 client_loop(S, Peer1, Port1, AssocId1,
1143 Peer2, Port2, AssocId2)
1144 after 5000 ->
1146 ok
1147 end.
1148
1150 gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control Transmission
1151 Protocol), Sockets API Extensions for SCTP
1152Ericsson AB kernel 5.4.3.2 gen_sctp(3)