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 {tclass, integer() >= 0} |
86 {ttl, integer() >= 0} |
87 {recvtos, boolean()} |
88 {recvtclass, boolean()} |
89 {recvttl, boolean()}
90 One of the SCTP Socket Options.
92 option_name() =
94 active |
95 buffer |
96 dontroute |
97 high_msgq_watermark |
98 linger |
99 low_msgq_watermark |
100 mode |
101 priority |
102 recbuf |
103 reuseaddr |
104 ipv6_v6only |
105 sctp_adaptation_layer |
106 sctp_associnfo |
107 sctp_autoclose |
108 sctp_default_send_param |
109 sctp_delayed_ack_time |
110 sctp_disable_fragments |
111 sctp_events |
112 sctp_get_peer_addr_info |
113 sctp_i_want_mapped_v4_addr |
114 sctp_initmsg |
115 sctp_maxseg |
116 sctp_nodelay |
117 sctp_peer_addr_params |
118 sctp_primary_addr |
119 sctp_rtoinfo |
120 sctp_set_peer_primary_addr |
121 sctp_status |
122 sndbuf |
123 tos |
124 tclass |
125 ttl |
126 recvtos |
127 recvtclass |
128 recvttl
129 sctp_socket()
131 Socket identifier returned from open/*.
133
135 abort(Socket, Assoc) -> ok | {error, inet:posix()}
136 Types:
138 Socket = sctp_socket()
140 Assoc = #sctp_assoc_change{}
141 Abnormally terminates the association specified by Assoc, with‐
143 out flushing of unsent data. The socket itself remains open.
144 Other associations opened on this socket are still valid, and
145 the socket can be used in new associations.
146 close(Socket) -> ok | {error, inet:posix()}
148 Types:
150 Socket = sctp_socket()
152 Closes the socket and all associations on it. The unsent data is
154 flushed as in eof/2. The close/1 call is blocking or otherwise
155 depending of the value of the linger socket option. If close
156 does not linger or linger time-out expires, the call returns and
157 the data is flushed in the background.
158 connect(Socket, Addr, Port, Opts) ->
160 {ok, Assoc} | {error, inet:posix()}
161 Types:
163 Socket = sctp_socket()
165 Addr = inet:ip_address() | inet:hostname()
166 Port = inet:port_number()
167 Opts = [Opt :: option()]
168 Assoc = #sctp_assoc_change{}
169 Same as connect(Socket, Addr, Port, Opts, infinity).
171 connect(Socket, Addr, Port, Opts, Timeout) ->
173 {ok, Assoc} | {error, inet:posix()}
174 Types:
176 Socket = sctp_socket()
178 Addr = inet:ip_address() | inet:hostname()
179 Port = inet:port_number()
180 Opts = [Opt :: option()]
181 Timeout = timeout()
182 Assoc = #sctp_assoc_change{}
183 Establishes a new association for socket Socket, with the peer
185 (SCTP server socket) specified by Addr and Port. Timeout, is
186 expressed in milliseconds. A socket can be associated with mul‐
187 tiple peers.
188 Warning:
190 Using a value of Timeout less than the maximum time taken by the
191 OS to establish an association (around 4.5 minutes if the
192 default values from RFC 4960 are used), can result in inconsis‐
193 tent or incorrect return values. This is especially relevant for
194 associations sharing the same Socket (that is, source address
195 and port), as the controlling process blocks until connect/*
196 returns. connect_init/* provides an alternative without this
197 limitation.
198 The result of connect/* is an #sctp_assoc_change{} event that
201 contains, in particular, the new Association ID:
202 #sctp_assoc_change{
204 state = atom(),
205 error = atom(),
206 outbound_streams = integer(),
207 inbound_streams = integer(),
208 assoc_id = assoc_id()
209 }
210 The number of outbound and inbound streams can be set by giving
212 an sctp_initmsg option to connect as in:
213 connect(Socket, Ip, Port>,
215 [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
216 max_instreams=MaxInStreams}}])
217 All options Opt are set on the socket before the association is
219 attempted. If an option record has undefined field values, the
220 options record is first read from the socket for those values.
221 In effect, Opt option records only define field values to change
222 before connecting.
223 The returned outbound_streams and inbound_streams are the stream
225 numbers on the socket. These can be different from the requested
226 values (OutStreams and MaxInStreams, respectively) if the peer
227 requires lower values.
228 state can have the following values:
230 comm_up:
232 Association is successfully established. This indicates a
233 successful completion of connect.
234 cant_assoc:
236 The association cannot be established (connect/* failure).
237 Other states do not normally occur in the output from connect/*.
239 Rather, they can occur in #sctp_assoc_change{} events received
240 instead of data in recv/* calls. All of them indicate losing the
241 association because of various error conditions, and are listed
242 here for the sake of completeness:
243 comm_lost:
245 restart:
248 shutdown_comp:
251 Field error can provide more detailed diagnostics.
254 connect_init(Socket, Addr, Port, Opts) ->
256 ok | {error, inet:posix()}
257 Types:
259 Socket = sctp_socket()
261 Addr = inet:ip_address() | inet:hostname()
262 Port = inet:port_number()
263 Opts = [option()]
264 Same as connect_init(Socket, Addr, Port, Opts, infinity).
266 connect_init(Socket, Addr, Port, Opts, Timeout) ->
268 ok | {error, inet:posix()}
269 Types:
271 Socket = sctp_socket()
273 Addr = inet:ip_address() | inet:hostname()
274 Port = inet:port_number()
275 Opts = [option()]
276 Timeout = timeout()
277 Initiates a new association for socket Socket, with the peer
279 (SCTP server socket) specified by Addr and Port.
280 The fundamental difference between this API and connect/* is
282 that the return value is that of the underlying OS connect(2)
283 system call. If ok is returned, the result of the association
284 establishment is received by the calling process as an
285 #sctp_assoc_change{} event. The calling process must be prepared
286 to receive this, or poll for it using recv/*, depending on the
287 value of the active option.
288 The parameters are as described in connect/*, except the Timeout
290 value.
291 The timer associated with Timeout only supervises IP resolution
293 of Addr.
294 controlling_process(Socket, Pid) -> ok | {error, Reason}
296 Types:
298 Socket = sctp_socket()
300 Pid = pid()
301 Reason = closed | not_owner | badarg | inet:posix()
302 Assigns a new controlling process Pid to Socket. Same implemen‐
304 tation as gen_udp:controlling_process/2.
305 eof(Socket, Assoc) -> ok | {error, Reason}
307 Types:
309 Socket = sctp_socket()
311 Assoc = #sctp_assoc_change{}
312 Reason = term()
313 Gracefully terminates the association specified by Assoc, with
315 flushing of all unsent data. The socket itself remains open.
316 Other associations opened on this socket are still valid. The
317 socket can be used in new associations.
318 error_string(ErrorNumber) -> ok | string() | unknown_error
320 Types:
322 ErrorNumber = integer()
324 Translates an SCTP error number from, for example,
326 #sctp_remote_error{} or #sctp_send_failed{} into an explanatory
327 string, or one of the atoms ok for no error or undefined for an
328 unrecognized error.
329 listen(Socket, IsServer) -> ok | {error, Reason}
331 listen(Socket, Backlog) -> ok | {error, Reason}
333 Types:
335 Socket = sctp_socket()
337 Backlog = integer()
338 Reason = term()
339 Sets up a socket to listen on the IP address and port number it
341 is bound to.
342 For type seqpacket, sockets (the default) IsServer must be true
344 or false. In contrast to TCP, there is no listening queue length
345 in SCTP. If IsServer is true, the socket accepts new associa‐
346 tions, that is, it becomes an SCTP server socket.
347 For type stream, sockets Backlog define the backlog queue length
349 just like in TCP.
350 open() -> {ok, Socket} | {error, inet:posix()}
352 open(Port) -> {ok, Socket} | {error, inet:posix()}
354 open(Opts) -> {ok, Socket} | {error, inet:posix()}
356 open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
358 Types:
360 Opts = [Opt]
362 Opt =
363 {ip, IP} |
364 {ifaddr, IP} |
365 inet:address_family() |
366 {port, Port} |
367 {type, SockType} |
368 option()
369 IP = inet:ip_address() | any | loopback
370 Port = inet:port_number()
371 SockType = seqpacket | stream
372 Socket = sctp_socket()
373 Creates an SCTP socket and binds it to the local addresses spec‐
375 ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
376 feature is called SCTP multi-homing). The default IP and Port
377 are any and 0, meaning bind to all local addresses on any free
378 port.
379 Other options:
381 inet6:
383 Sets up the socket for IPv6.
384 inet:
386 Sets up the socket for IPv4. This is the default.
387 A default set of socket options is used. In particular, the
389 socket is opened in binary and passive mode, with SockType seq‐
390 packet, and with reasonably large kernel and driver buffers.
391 If the socket is in passive mode data can be received through
393 the recv/1,2 calls.
394 If the socket is in active mode data received data is delivered
396 to the controlling process as messages:
397 {sctp, Socket, FromIP, FromPort, {AncData, Data}}
399 See recv/1,2 for a description of the message fields.
402 Note:
404 This message format unfortunately differs slightly from the
405 gen_udp message format with ancillary data, and from the
406 recv/1,2 return tuple format.
407 peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
410 Types:
412 Socket = sctp_socket()
414 Assoc = #sctp_assoc_change{} | assoc_id()
415 NewSocket = sctp_socket()
416 Reason = term()
417 Branches off an existing association Assoc in a socket Socket of
419 type seqpacket (one-to-many style) into a new socket NewSocket
420 of type stream (one-to-one style).
421 The existing association argument Assoc can be either a
423 #sctp_assoc_change{} record as returned from, for example,
424 recv/*, connect/*, or from a listening socket in active mode. It
425 can also be just the field assoc_id integer from such a record.
426 recv(Socket) ->
428 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
429 recv(Socket, Timeout) ->
431 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
432 Types:
434 Socket = sctp_socket()
436 Timeout = timeout()
437 FromIP = inet:ip_address()
438 FromPort = inet:port_number()
439 AncData = [#sctp_sndrcvinfo{} | inet:ancillary_data()]
440 Data =
441 binary() |
442 string() |
443 #sctp_sndrcvinfo{} |
444 #sctp_assoc_change{} |
445 #sctp_paddr_change{} |
446 #sctp_adaptation_event{}
447 Reason =
448 inet:posix() |
449 #sctp_send_failed{} |
450 #sctp_paddr_change{} |
451 #sctp_pdapi_event{} |
452 #sctp_remote_error{} |
453 #sctp_shutdown_event{}
454 Receives the Data message from any association of the socket. If
456 the receive times out, {error,timeout} is returned. The default
457 time-out is infinity. FromIP and FromPort indicate the address
458 of the sender.
459 AncData is a list of ancillary data items that can be received
461 along with the main Data. This list can be empty, or contain a
462 single #sctp_sndrcvinfo{} record if receiving of such ancillary
463 data is enabled (see option sctp_events). It is enabled by
464 default, as such ancillary data provides an easy way of deter‐
465 mining the association and stream over which the message is
466 received. (An alternative way is to get the association ID from
467 FromIP and FromPort using socket option sctp_get_peer_addr_info,
468 but this does still not produce the stream number).
469 AncData may also contain ancillary data from the socket
471 options recvtos, recvtclass or recvttl, if that is supported by
472 the platform for the socket.
473 The Data received can be a binary() or a list() of bytes (inte‐
475 gers in the range 0 through 255) depending on the socket mode,
476 or an SCTP event.
477 Possible SCTP events:
479 * #sctp_sndrcvinfo{}
481 * #sctp_assoc_change{}
483 *
485 #sctp_paddr_change{
488 addr = {ip_address(),port()},
489 state = atom(),
490 error = integer(),
491 assoc_id = assoc_id()
492 }
493 Indicates change of the status of the IP address of the peer
495 specified by addr within association assoc_id. Possible val‐
496 ues of state (mostly self-explanatory) include:
497 addr_unreachable:
499 addr_available:
502 addr_removed:
505 addr_added:
508 addr_made_prim:
511 addr_confirmed:
514 In case of an error (for example, addr_unreachable), field
517 error provides more diagnostics. In such cases, event
518 #sctp_paddr_change{} is automatically converted into an
519 error term returned by recv. The error field value can be
520 converted into a string using error_string/1.
521 *
523 #sctp_send_failed{
526 flags = true | false,
527 error = integer(),
528 info = #sctp_sndrcvinfo{},
529 assoc_id = assoc_id()
530 data = binary()
531 }
532 The sender can receive this event if a send operation fails.
534 flags:
536 A Boolean specifying if the data has been transmitted over
537 the wire.
538 error:
540 Provides extended diagnostics, use error_string/1.
541 info:
543 The original #sctp_sndrcvinfo{} record used in the failed
544 send/*.
545 data:
547 The whole original data chunk attempted to be sent.
548 In the current implementation of the Erlang/SCTP binding,
550 this event is internally converted into an error term
551 returned by recv/*.
552 *
554 #sctp_adaptation_event{
557 adaptation_ind = integer(),
558 assoc_id = assoc_id()
559 }
560 Delivered when a peer sends an adaptation layer indication
562 parameter (configured through option sctp_adaptation_layer).
563 Notice that with the current implementation of the
564 Erlang/SCTP binding, this event is disabled by default.
565 *
567 #sctp_pdapi_event{
570 indication = sctp_partial_delivery_aborted,
571 assoc_id = assoc_id()
572 }
573 A partial delivery failure. In the current implementation of
575 the Erlang/SCTP binding, this event is internally converted
576 into an error term returned by recv/*.
577 send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
579 Types:
581 Socket = sctp_socket()
583 SndRcvInfo = #sctp_sndrcvinfo{}
584 Data = binary() | iolist()
585 Reason = term()
586 Sends the Data message with all sending parameters from a
588 #sctp_sndrcvinfo{} record. This way, the user can specify the
589 PPID (passed to the remote end) and context (passed to the local
590 SCTP layer), which can be used, for example, for error identifi‐
591 cation. However, such a fine level of user control is rarely
592 required. The function send/4 is sufficient for most applica‐
593 tions.
594 send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
596 Types:
598 Socket = sctp_socket()
600 Assoc = #sctp_assoc_change{} | assoc_id()
601 Stream = integer()
602 Data = binary() | iolist()
603 Reason = term()
604 Sends a Data message over an existing association and specified
606 stream.
607
609 The set of admissible SCTP socket options is by construction orthogonal
610 to the sets of TCP, UDP, and generic inet options. Only options listed
611 here are allowed for SCTP sockets. Options can be set on the socket
612 using open/1,2 or inet:setopts/2, retrieved using inet:getopts/2.
613 Options can be changed when calling connect/4,5.
614 {mode, list|binary} or just list or binary:
616 Determines the type of data returned from recv/1,2.
617 {active, true|false|once|N}:
619 * If false (passive mode, the default), the caller must do an
622 explicit recv call to retrieve the available data from the
623 socket.
624 * If true|once|N (active modes) received data or events are sent to
626 the owning process. See open/0..2 for the message format.
627 * If true (full active mode) there is no flow control.
629 Note:
631 Note that this can cause the message queue to overflow causing for
632 example the virtual machine to run out of memory and crash.
633 * If once, only one message is automatically placed in the message
636 queue, and after that the mode is automatically reset to passive.
637 This provides flow control and the possibility for the receiver
638 to listen for its incoming SCTP data interleaved with other
639 inter-process messages.
640 * If active is specified as an integer N in the range -32768 to
642 32767 (inclusive), that number is added to the socket's counting
643 of data messages to be delivered to the controlling process. If
644 the result of the addition is negative, the count is set to 0.
645 Once the count reaches 0, either through the delivery of messages
646 or by being explicitly set with inet:setopts/2, the socket mode
647 is automatically reset to passive ({active, false}). When a
648 socket in this active mode transitions to passive mode, the mes‐
649 sage {sctp_passive, Socket} is sent to the controlling process to
650 notify it that if it wants to receive more data messages from the
651 socket, it must call inet:setopts/2 to set the socket back into
652 an active mode.
653 {tos, integer()}:
655 Sets the Type-Of-Service field on the IP datagrams that are sent,
656 to the specified value. This effectively determines a prioritiza‐
657 tion policy for the outbound packets. The acceptable values are
658 system-dependent.
659 {priority, integer()}:
661 A protocol-independent equivalent of tos above. Setting priority
662 implies setting tos as well.
663 {dontroute, true|false}:
665 Defaults to false. If true, the kernel does not send packets
666 through any gateway, only sends them to directly connected hosts.
667 {reuseaddr, true|false}:
669 Defaults to false. If true, the local binding address {IP,Port} of
670 the socket can be reused immediately. No waiting in state
671 CLOSE_WAIT is performed (can be required for high-throughput
672 servers).
673 {sndbuf, integer()}:
675 The size, in bytes, of the OS kernel send buffer for this socket.
676 Sending errors would occur for datagrams larger than val(sndbuf).
677 Setting this option also adjusts the size of the driver buffer (see
678 buffer above).
679 {recbuf, integer()}:
681 The size, in bytes, of the OS kernel receive buffer for this
682 socket. Sending errors would occur for datagrams larger than
683 val(recbuf). Setting this option also adjusts the size of the
684 driver buffer (see buffer above).
685 {sctp_module, module()}:
687 Overrides which callback module is used. Defaults to inet_sctp for
688 IPv4 and inet6_sctp for IPv6.
689 {sctp_rtoinfo, #sctp_rtoinfo{}}:
691 #sctp_rtoinfo{
694 assoc_id = assoc_id(),
695 initial = integer(),
696 max = integer(),
697 min = integer()
698 }
699 Determines retransmission time-out parameters, in milliseconds, for
701 the association(s) specified by assoc_id.
702 assoc_id = 0 (default) indicates the whole endpoint. See RFC 2960
704 and Sockets API Extensions for SCTP for the exact semantics of the
705 field values.
706 {sctp_associnfo, #sctp_assocparams{}}:
708 #sctp_assocparams{
711 assoc_id = assoc_id(),
712 asocmaxrxt = integer(),
713 number_peer_destinations = integer(),
714 peer_rwnd = integer(),
715 local_rwnd = integer(),
716 cookie_life = integer()
717 }
718 Determines association parameters for the association(s) specified
720 by assoc_id.
721 assoc_id = 0 (default) indicates the whole endpoint. See Sockets
723 API Extensions for SCTP for the discussion of their semantics.
724 Rarely used.
725 {sctp_initmsg, #sctp_initmsg{}}:
727 #sctp_initmsg{
730 num_ostreams = integer(),
731 max_instreams = integer(),
732 max_attempts = integer(),
733 max_init_timeo = integer()
734 }
735 Determines the default parameters that this socket tries to negoti‐
737 ate with its peer while establishing an association with it. Is to
738 be set after open/* but before the first connect/*. #sctp_initmsg{}
739 can also be used as ancillary data with the first call of send/* to
740 a new peer (when a new association is created).
741 num_ostreams:
743 Number of outbound streams
744 max_instreams:
746 Maximum number of inbound streams
747 max_attempts:
749 Maximum retransmissions while establishing an association
750 max_init_timeo:
752 Time-out, in milliseconds, for establishing an association
753 {sctp_autoclose, integer() >= 0}:
755 Determines the time, in seconds, after which an idle association is
756 automatically closed. 0 means that the association is never auto‐
757 matically closed.
758 {sctp_nodelay, true|false}:
760 Turns on|off the Nagle algorithm for merging small packets into
761 larger ones. This improves throughput at the expense of latency.
762 {sctp_disable_fragments, true|false}:
764 If true, induces an error on an attempt to send a message larger
765 than the current PMTU size (which would require fragmenta‐
766 tion/reassembling). Notice that message fragmentation does not
767 affect the logical atomicity of its delivery; this option is pro‐
768 vided for performance reasons only.
769 {sctp_i_want_mapped_v4_addr, true|false}:
771 Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
772 the socket address family is AF_INET6).
773 {sctp_maxseg, integer()}:
775 Determines the maximum chunk size if message fragmentation is used.
776 If 0, the chunk size is limited by the Path MTU only.
777 {sctp_primary_addr, #sctp_prim{}}:
779 #sctp_prim{
782 assoc_id = assoc_id(),
783 addr = {IP, Port}
784 }
785 IP = ip_address()
786 Port = port_number()
787 For the association specified by assoc_id, {IP,Port} must be one of
789 the peer addresses. This option determines that the specified
790 address is treated by the local SCTP stack as the primary address
791 of the peer.
792 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
794 #sctp_setpeerprim{
797 assoc_id = assoc_id(),
798 addr = {IP, Port}
799 }
800 IP = ip_address()
801 Port = port_number()
802 When set, informs the peer to use {IP, Port} as the primary address
804 of the local endpoint for the association specified by assoc_id.
805 {sctp_adaptation_layer, #sctp_setadaptation{}}:
807 #sctp_setadaptation{
810 adaptation_ind = integer()
811 }
812 When set, requests that the local endpoint uses the value specified
814 by adaptation_ind as the Adaptation Indication parameter for estab‐
815 lishing new associations. For details, see RFC 2960 and Sockets API
816 Extenstions for SCTP.
817 {sctp_peer_addr_params, #sctp_paddrparams{}}:
819 #sctp_paddrparams{
822 assoc_id = assoc_id(),
823 address = {IP, Port},
824 hbinterval = integer(),
825 pathmaxrxt = integer(),
826 pathmtu = integer(),
827 sackdelay = integer(),
828 flags = list()
829 }
830 IP = ip_address()
831 Port = port_number()
832 Determines various per-address parameters for the association spec‐
834 ified by assoc_id and the peer address address (the SCTP protocol
835 supports multi-homing, so more than one address can correspond to a
836 specified association).
837 hbinterval:
839 Heartbeat interval, in milliseconds
840 pathmaxrxt:
842 Maximum number of retransmissions before this address is consid‐
843 ered unreachable (and an alternative address is selected)
844 pathmtu:
846 Fixed Path MTU, if automatic discovery is disabled (see flags
847 below)
848 sackdelay:
850 Delay, in milliseconds, for SAC messages (if the delay is
851 enabled, see flags below)
852 flags:
854 The following flags are available:
855 hb_enable:
857 Enables heartbeat
858 hb_disable:
860 Disables heartbeat
861 hb_demand:
863 Initiates heartbeat immediately
864 pmtud_enable:
866 Enables automatic Path MTU discovery
867 pmtud_disable:
869 Disables automatic Path MTU discovery
870 sackdelay_enable:
872 Enables SAC delay
873 sackdelay_disable:
875 Disables SAC delay
876 {sctp_default_send_param, #sctp_sndrcvinfo{}}:
878 #sctp_sndrcvinfo{
881 stream = integer(),
882 ssn = integer(),
883 flags = list(),
884 ppid = integer(),
885 context = integer(),
886 timetolive = integer(),
887 tsn = integer(),
888 cumtsn = integer(),
889 assoc_id = assoc_id()
890 }
891 #sctp_sndrcvinfo{} is used both in this socket option, and as
893 ancillary data while sending or receiving SCTP messages. When set
894 as an option, it provides default values for subsequent send calls
895 on the association specified by assoc_id.
896 assoc_id = 0 (default) indicates the whole endpoint.
898 The following fields typically must be specified by the sender:
900 sinfo_stream:
902 Stream number (0-base) within the association to send the mes‐
903 sages through;
904 sinfo_flags:
906 The following flags are recognised:
907 unordered:
909 The message is to be sent unordered
910 addr_over:
912 The address specified in send overwrites the primary peer
913 address
914 abort:
916 Aborts the current association without flushing any unsent data
917 eof:
919 Gracefully shuts down the current association, with flushing of
920 unsent data
921 Other fields are rarely used. For complete information, see RFC
923 2960 and Sockets API Extensions for SCTP.
924 {sctp_events, #sctp_event_subscribe{}}:
926 #sctp_event_subscribe{
929 data_io_event = true | false,
930 association_event = true | false,
931 address_event = true | false,
932 send_failure_event = true | false,
933 peer_error_event = true | false,
934 shutdown_event = true | false,
935 partial_delivery_event = true | false,
936 adaptation_layer_event = true | false
937 }
938 This option determines which SCTP Events are to be received
940 (through recv/*) along with the data. The only exception is
941 data_io_event, which enables or disables receiving of #sctp_sndrcv‐
942 info{} ancillary data, not events. By default, all flags except
943 adaptation_layer_event are enabled, although sctp_data_io_event and
944 association_event are used by the driver itself and not exported to
945 the user level.
946 {sctp_delayed_ack_time, #sctp_assoc_value{}}:
948 #sctp_assoc_value{
951 assoc_id = assoc_id(),
952 assoc_value = integer()
953 }
954 Rarely used. Determines the ACK time (specified by assoc_value, in
956 milliseconds) for the specified association or the whole endpoint
957 if assoc_value = 0 (default).
958 {sctp_status, #sctp_status{}}:
960 #sctp_status{
963 assoc_id = assoc_id(),
964 state = atom(),
965 rwnd = integer(),
966 unackdata = integer(),
967 penddata = integer(),
968 instrms = integer(),
969 outstrms = integer(),
970 fragmentation_point = integer(),
971 primary = #sctp_paddrinfo{}
972 }
973 This option is read-only. It determines the status of the SCTP
975 association specified by assoc_id. The following are the possible
976 values of state (the state designations are mostly self-explana‐
977 tory):
978 sctp_state_empty:
980 Default. Means that no other state is active.
981 sctp_state_closed:
983 sctp_state_cookie_wait:
986 sctp_state_cookie_echoed:
989 sctp_state_established:
992 sctp_state_shutdown_pending:
995 sctp_state_shutdown_sent:
998 sctp_state_shutdown_received:
1001 sctp_state_shutdown_ack_sent:
1004 Semantics of the other fields:
1007 sstat_rwnd:
1009 Current receiver window size of the association
1010 sstat_unackdata:
1012 Number of unacked data chunks
1013 sstat_penddata:
1015 Number of data chunks pending receipt
1016 sstat_instrms:
1018 Number of inbound streams
1019 sstat_outstrms:
1021 Number of outbound streams
1022 sstat_fragmentation_point:
1024 Message size at which SCTP fragmentation occurs
1025 sstat_primary:
1027 Information on the current primary peer address (see below for
1028 the format of #sctp_paddrinfo{})
1029 {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1031 #sctp_paddrinfo{
1034 assoc_id = assoc_id(),
1035 address = {IP, Port},
1036 state = inactive | active | unconfirmed,
1037 cwnd = integer(),
1038 srtt = integer(),
1039 rto = integer(),
1040 mtu = integer()
1041 }
1042 IP = ip_address()
1043 Port = port_number()
1044 This option is read-only. It determines the parameters specific to
1046 the peer address specified by address within the association speci‐
1047 fied by assoc_id. Field address fmust be set by the caller; all
1048 other fields are filled in on return. If assoc_id = 0 (default),
1049 the address is automatically translated into the corresponding
1050 association ID. This option is rarely used. For the semantics of
1051 all fields, see RFC 2960 and Sockets API Extensions for SCTP.
1052
1054 Example of an Erlang SCTP server that receives SCTP messages and prints
1055 them on the standard output:
1056 -module(sctp_server).
1058 -export([server/0,server/1,server/2]).
1060 -include_lib("kernel/include/inet.hrl").
1061 -include_lib("kernel/include/inet_sctp.hrl").
1062 server() ->
1064 server(any, 2006).
1065 server([Host,Port]) when is_list(Host), is_list(Port) ->
1067 {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1068 io:format("~w -> ~w~n", [Host, IP]),
1069 server([IP, list_to_integer(Port)]).
1070 server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1072 is_integer(Port) ->
1073 {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1074 io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1075 ok = gen_sctp:listen(S, true),
1076 server_loop(S).
1077 server_loop(S) ->
1079 case gen_sctp:recv(S) of
1080 {error, Error} ->
1081 io:format("SCTP RECV ERROR: ~p~n", [Error]);
1082 Data ->
1083 io:format("Received: ~p~n", [Data])
1084 end,
1085 server_loop(S).
1086 Example of an Erlang SCTP client interacting with the above server.
1088 Notice that in this example the client creates an association with the
1089 server with 5 outbound streams. Therefore, sending of "Test 0" over
1090 stream 0 succeeds, but sending of "Test 5" over stream 5 fails. The
1091 client then aborts the association, which results in that the corre‐
1092 sponding event is received on the server side.
1093 -module(sctp_client).
1095 -export([client/0, client/1, client/2]).
1097 -include_lib("kernel/include/inet.hrl").
1098 -include_lib("kernel/include/inet_sctp.hrl").
1099 client() ->
1101 client([localhost]).
1102 client([Host]) ->
1104 client(Host, 2006);
1105 client([Host, Port]) when is_list(Host), is_list(Port) ->
1107 client(Host,list_to_integer(Port)),
1108 init:stop().
1109 client(Host, Port) when is_integer(Port) ->
1111 {ok,S} = gen_sctp:open(),
1112 {ok,Assoc} = gen_sctp:connect
1113 (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1114 io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1115 io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1117 io:nl(),
1118 timer:sleep(10000),
1119 io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1120 io:nl(),
1121 timer:sleep(10000),
1122 io:write(gen_sctp:abort(S, Assoc)),
1123 io:nl(),
1124 timer:sleep(1000),
1126 gen_sctp:close(S).
1127 A simple Erlang SCTP client that uses the connect_init API:
1129 -module(ex3).
1131 -export([client/4]).
1133 -include_lib("kernel/include/inet.hrl").
1134 -include_lib("kernel/include/inet_sctp.hrl").
1135 client(Peer1, Port1, Peer2, Port2)
1137 when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1138 {ok,S} = gen_sctp:open(),
1139 SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1140 ActiveOpt = {active, true},
1141 Opts = [SctpInitMsgOpt, ActiveOpt],
1142 ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1143 ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1144 io:format("Connections initiated~n", []),
1145 client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1146 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1148 receive
1149 {sctp, S, Peer1, Port1, {_Anc, SAC}}
1150 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1151 io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1152 [SAC#sctp_assoc_change.state,
1153 SAC#sctp_assoc_change.assoc_id]),
1154 client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1155 Peer2, Port2, AssocId2);
1156 {sctp, S, Peer2, Port2, {_Anc, SAC}}
1158 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1159 io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1160 [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1161 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1162 SAC#sctp_assoc_change.assoc_id);
1163 {sctp, S, Peer1, Port1, Data} ->
1165 io:format("Association 1: received ~p~n", [Data]),
1166 client_loop(S, Peer1, Port1, AssocId1,
1167 Peer2, Port2, AssocId2);
1168 {sctp, S, Peer2, Port2, Data} ->
1170 io:format("Association 2: received ~p~n", [Data]),
1171 client_loop(S, Peer1, Port1, AssocId1,
1172 Peer2, Port2, AssocId2);
1173 Other ->
1175 io:format("Other ~p~n", [Other]),
1176 client_loop(S, Peer1, Port1, AssocId1,
1177 Peer2, Port2, AssocId2)
1178 after 5000 ->
1180 ok
1181 end.
1182
1184 gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control Transmission
1185 Protocol), Sockets API Extensions for SCTP
1186Ericsson AB kernel 6.3.1.1 gen_sctp(3)