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
162 expressed in milliseconds. A socket can be associated with mul‐
163 tiple 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
168 default values from RFC 4960 are used), can result in inconsis‐
169 tent or incorrect return values. This is especially relevant for
170 associations sharing the same Socket (that is, source address
171 and port), as the controlling process blocks until connect/*
172 returns. connect_init/* provides an alternative without this
173 limitation.
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 = atom(),
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.
230 connect_init(Socket, Addr, Port, Opts) ->
232 ok | {error, inet:posix()}
233 Types:
235 Socket = sctp_socket()
237 Addr = inet:ip_address() | inet:hostname()
238 Port = inet:port_number()
239 Opts = [option()]
240 Same as connect_init(Socket, Addr, Port, Opts, infinity).
242 connect_init(Socket, Addr, Port, Opts, Timeout) ->
244 ok | {error, inet:posix()}
245 Types:
247 Socket = sctp_socket()
249 Addr = inet:ip_address() | inet:hostname()
250 Port = inet:port_number()
251 Opts = [option()]
252 Timeout = timeout()
253 Initiates a new association for socket Socket, with the peer
255 (SCTP server socket) specified by Addr and Port.
256 The fundamental difference between this API and connect/* is
258 that the return value is that of the underlying OS connect(2)
259 system call. If ok is returned, the result of the association
260 establishment is received by the calling process as an
261 #sctp_assoc_change{} event. The calling process must be prepared
262 to receive this, or poll for it using recv/*, depending on the
263 value of the active option.
264 The parameters are as described in connect/*, except the Timeout
266 value.
267 The timer associated with Timeout only supervises IP resolution
269 of Addr.
270 controlling_process(Socket, Pid) -> ok | {error, Reason}
272 Types:
274 Socket = sctp_socket()
276 Pid = pid()
277 Reason = closed | not_owner | badarg | inet:posix()
278 Assigns a new controlling process Pid to Socket. Same implemen‐
280 tation as gen_udp:controlling_process/2.
281 eof(Socket, Assoc) -> ok | {error, Reason}
283 Types:
285 Socket = sctp_socket()
287 Assoc = #sctp_assoc_change{}
288 Reason = term()
289 Gracefully terminates the association specified by Assoc, with
291 flushing of all unsent data. The socket itself remains open.
292 Other associations opened on this socket are still valid. The
293 socket can be used in new associations.
294 error_string(ErrorNumber) -> ok | string() | unknown_error
296 Types:
298 ErrorNumber = integer()
300 Translates an SCTP error number from, for example,
302 #sctp_remote_error{} or #sctp_send_failed{} into an explanatory
303 string, or one of the atoms ok for no error or undefined for an
304 unrecognized error.
305 listen(Socket, IsServer) -> ok | {error, Reason}
307 listen(Socket, Backlog) -> ok | {error, Reason}
309 Types:
311 Socket = sctp_socket()
313 Backlog = integer()
314 Reason = term()
315 Sets up a socket to listen on the IP address and port number it
317 is bound to.
318 For type seqpacket, sockets (the default) IsServer must be true
320 or false. In contrast to TCP, there is no listening queue length
321 in SCTP. If IsServer is true, the socket accepts new associa‐
322 tions, that is, it becomes an SCTP server socket.
323 For type stream, sockets Backlog define the backlog queue length
325 just like in TCP.
326 open() -> {ok, Socket} | {error, inet:posix()}
328 open(Port) -> {ok, Socket} | {error, inet:posix()}
330 open(Opts) -> {ok, Socket} | {error, inet:posix()}
332 open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
334 Types:
336 Opts = [Opt]
338 Opt =
339 {ip, IP} |
340 {ifaddr, IP} |
341 inet:address_family() |
342 {port, Port} |
343 {type, SockType} |
344 option()
345 IP = inet:ip_address() | any | loopback
346 Port = inet:port_number()
347 SockType = seqpacket | stream
348 Socket = sctp_socket()
349 Creates an SCTP socket and binds it to the local addresses spec‐
351 ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
352 feature is called SCTP multi-homing). The default IP and Port
353 are any and 0, meaning bind to all local addresses on any free
354 port.
355 Other options:
357 inet6:
359 Sets up the socket for IPv6.
360 inet:
362 Sets up the socket for IPv4. This is the default.
363 A default set of socket options is used. In particular, the
365 socket is opened in binary and passive mode, with SockType seq‐
366 packet, and with reasonably large kernel and driver buffers.
367 If the socket is in passive mode data can be received through
369 the recv/1,2 calls.
370 If the socket is in active mode data received data is delivered
372 to the controlling process as messages:
373 {sctp, Socket, FromIP, FromPort, {AncData, Data}}
375 See recv/1,2 for a description of the message fields.
378 Note:
380 This message format unfortunately differs slightly from the
381 gen_udp message format with ancillary data, and from the
382 recv/1,2 return tuple format.
383 peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
386 Types:
388 Socket = sctp_socket()
390 Assoc = #sctp_assoc_change{} | assoc_id()
391 NewSocket = sctp_socket()
392 Reason = term()
393 Branches off an existing association Assoc in a socket Socket of
395 type seqpacket (one-to-many style) into a new socket NewSocket
396 of type stream (one-to-one style).
397 The existing association argument Assoc can be either a
399 #sctp_assoc_change{} record as returned from, for example,
400 recv/*, connect/*, or from a listening socket in active mode. It
401 can also be just the field assoc_id integer from such a record.
402 recv(Socket) ->
404 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
405 recv(Socket, Timeout) ->
407 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
408 Types:
410 Socket = sctp_socket()
412 Timeout = timeout()
413 FromIP = inet:ip_address()
414 FromPort = inet:port_number()
415 AncData = [#sctp_sndrcvinfo{} | inet:ancillary_data()]
416 Data =
417 binary() |
418 string() |
419 #sctp_sndrcvinfo{} |
420 #sctp_assoc_change{} |
421 #sctp_paddr_change{} |
422 #sctp_adaptation_event{}
423 Reason =
424 inet:posix() |
425 #sctp_send_failed{} |
426 #sctp_paddr_change{} |
427 #sctp_pdapi_event{} |
428 #sctp_remote_error{} |
429 #sctp_shutdown_event{}
430 Receives the Data message from any association of the socket. If
432 the receive times out, {error,timeout} is returned. The default
433 time-out is infinity. FromIP and FromPort indicate the address
434 of the sender.
435 AncData is a list of ancillary data items that can be received
437 along with the main Data. This list can be empty, or contain a
438 single #sctp_sndrcvinfo{} record if receiving of such ancillary
439 data is enabled (see option sctp_events). It is enabled by
440 default, as such ancillary data provides an easy way of deter‐
441 mining the association and stream over which the message is
442 received. (An alternative way is to get the association ID from
443 FromIP and FromPort using socket option sctp_get_peer_addr_info,
444 but this does still not produce the stream number).
445 AncData may also contain ancillary data from the socket
447 options recvtos, recvtclass or recvttl, if that is supported by
448 the platform for the socket.
449 The Data received can be a binary() or a list() of bytes (inte‐
451 gers in the range 0 through 255) depending on the socket mode,
452 or an SCTP event.
453 Possible SCTP events:
455 * #sctp_sndrcvinfo{}
457 * #sctp_assoc_change{}
459 *
461 #sctp_paddr_change{
464 addr = {ip_address(),port()},
465 state = atom(),
466 error = integer(),
467 assoc_id = assoc_id()
468 }
469 Indicates change of the status of the IP address of the peer
471 specified by addr within association assoc_id. Possible val‐
472 ues of state (mostly self-explanatory) include:
473 addr_unreachable:
475 addr_available:
478 addr_removed:
481 addr_added:
484 addr_made_prim:
487 addr_confirmed:
490 In case of an error (for example, addr_unreachable), field
493 error provides more diagnostics. In such cases, event
494 #sctp_paddr_change{} is automatically converted into an
495 error term returned by recv. The error field value can be
496 converted into a string using error_string/1.
497 *
499 #sctp_send_failed{
502 flags = true | false,
503 error = integer(),
504 info = #sctp_sndrcvinfo{},
505 assoc_id = assoc_id()
506 data = binary()
507 }
508 The sender can receive this event if a send operation fails.
510 flags:
512 A Boolean specifying if the data has been transmitted over
513 the wire.
514 error:
516 Provides extended diagnostics, use error_string/1.
517 info:
519 The original #sctp_sndrcvinfo{} record used in the failed
520 send/*.
521 data:
523 The whole original data chunk attempted to be sent.
524 In the current implementation of the Erlang/SCTP binding,
526 this event is internally converted into an error term
527 returned by recv/*.
528 *
530 #sctp_adaptation_event{
533 adaptation_ind = integer(),
534 assoc_id = assoc_id()
535 }
536 Delivered when a peer sends an adaptation layer indication
538 parameter (configured through option sctp_adaptation_layer).
539 Notice that with the current implementation of the
540 Erlang/SCTP binding, this event is disabled by default.
541 *
543 #sctp_pdapi_event{
546 indication = sctp_partial_delivery_aborted,
547 assoc_id = assoc_id()
548 }
549 A partial delivery failure. In the current implementation of
551 the Erlang/SCTP binding, this event is internally converted
552 into an error term returned by recv/*.
553 send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
555 Types:
557 Socket = sctp_socket()
559 SndRcvInfo = #sctp_sndrcvinfo{}
560 Data = binary() | iolist()
561 Reason = term()
562 Sends the Data message with all sending parameters from a
564 #sctp_sndrcvinfo{} record. This way, the user can specify the
565 PPID (passed to the remote end) and context (passed to the local
566 SCTP layer), which can be used, for example, for error identifi‐
567 cation. However, such a fine level of user control is rarely
568 required. The function send/4 is sufficient for most applica‐
569 tions.
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
588 using open/1,2 or inet:setopts/2, retrieved using inet:getopts/2.
589 Options 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
598 explicit recv call to retrieve the available data from the
599 socket.
600 * If true|once|N (active modes) received data or events are sent to
602 the owning process. See open/0..2 for the message format.
603 * If true (full active mode) there is no flow control.
605 Note:
607 Note that this can cause the message queue to overflow causing for
608 example the virtual machine to run out of memory and crash.
609 * If once, only one message is automatically placed in the message
612 queue, and after that the mode is automatically reset to passive.
613 This provides flow control and the possibility for the receiver
614 to listen for its incoming SCTP data interleaved with other
615 inter-process messages.
616 * If active is specified as an integer N in the range -32768 to
618 32767 (inclusive), that number is added to the socket's counting
619 of data messages to be delivered to the controlling process. If
620 the result of the addition is negative, the count is set to 0.
621 Once the count reaches 0, either through the delivery of messages
622 or by being explicitly set with inet:setopts/2, the socket mode
623 is automatically reset to passive ({active, false}). When a
624 socket in this active mode transitions to passive mode, the mes‐
625 sage {sctp_passive, Socket} is sent to the controlling process to
626 notify it that if it wants to receive more data messages from the
627 socket, it must call inet:setopts/2 to set the socket back into
628 an active mode.
629 {tos, integer()}:
631 Sets the Type-Of-Service field on the IP datagrams that are sent,
632 to the specified value. This effectively determines a prioritiza‐
633 tion policy for the outbound packets. The acceptable values are
634 system-dependent.
635 {priority, integer()}:
637 A protocol-independent equivalent of tos above. Setting priority
638 implies setting tos as well.
639 {dontroute, true|false}:
641 Defaults to false. If true, the kernel does not send packets
642 through any gateway, only sends them to directly connected hosts.
643 {reuseaddr, true|false}:
645 Defaults to false. If true, the local binding address {IP,Port} of
646 the socket can be reused immediately. No waiting in state
647 CLOSE_WAIT is performed (can be required for high-throughput
648 servers).
649 {sndbuf, integer()}:
651 The size, in bytes, of the OS kernel send buffer for this socket.
652 Sending errors would occur for datagrams larger than val(sndbuf).
653 Setting this option also adjusts the size of the driver buffer (see
654 buffer above).
655 {recbuf, integer()}:
657 The size, in bytes, of the OS kernel receive buffer for this
658 socket. Sending errors would occur for datagrams larger than
659 val(recbuf). Setting this option also adjusts the size of the
660 driver buffer (see buffer above).
661 {sctp_module, module()}:
663 Overrides which callback module is used. Defaults to inet_sctp for
664 IPv4 and inet6_sctp for IPv6.
665 {sctp_rtoinfo, #sctp_rtoinfo{}}:
667 #sctp_rtoinfo{
670 assoc_id = assoc_id(),
671 initial = integer(),
672 max = integer(),
673 min = integer()
674 }
675 Determines retransmission time-out parameters, in milliseconds, for
677 the association(s) specified by assoc_id.
678 assoc_id = 0 (default) indicates the whole endpoint. See RFC 2960
680 and Sockets API Extensions for SCTP for the exact semantics of the
681 field values.
682 {sctp_associnfo, #sctp_assocparams{}}:
684 #sctp_assocparams{
687 assoc_id = assoc_id(),
688 asocmaxrxt = integer(),
689 number_peer_destinations = integer(),
690 peer_rwnd = integer(),
691 local_rwnd = integer(),
692 cookie_life = integer()
693 }
694 Determines association parameters for the association(s) specified
696 by assoc_id.
697 assoc_id = 0 (default) indicates the whole endpoint. See Sockets
699 API Extensions for SCTP for the discussion of their semantics.
700 Rarely used.
701 {sctp_initmsg, #sctp_initmsg{}}:
703 #sctp_initmsg{
706 num_ostreams = integer(),
707 max_instreams = integer(),
708 max_attempts = integer(),
709 max_init_timeo = integer()
710 }
711 Determines the default parameters that this socket tries to negoti‐
713 ate with its peer while establishing an association with it. Is to
714 be set after open/* but before the first connect/*. #sctp_initmsg{}
715 can also be used as ancillary data with the first call of send/* to
716 a new peer (when a new association is created).
717 num_ostreams:
719 Number of outbound streams
720 max_instreams:
722 Maximum number of inbound streams
723 max_attempts:
725 Maximum retransmissions while establishing an association
726 max_init_timeo:
728 Time-out, in milliseconds, for establishing an association
729 {sctp_autoclose, integer() >= 0}:
731 Determines the time, in seconds, after which an idle association is
732 automatically closed. 0 means that the association is never auto‐
733 matically closed.
734 {sctp_nodelay, true|false}:
736 Turns on|off the Nagle algorithm for merging small packets into
737 larger ones. This improves throughput at the expense of latency.
738 {sctp_disable_fragments, true|false}:
740 If true, induces an error on an attempt to send a message larger
741 than the current PMTU size (which would require fragmenta‐
742 tion/reassembling). Notice that message fragmentation does not
743 affect the logical atomicity of its delivery; this option is pro‐
744 vided for performance reasons only.
745 {sctp_i_want_mapped_v4_addr, true|false}:
747 Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
748 the socket address family is AF_INET6).
749 {sctp_maxseg, integer()}:
751 Determines the maximum chunk size if message fragmentation is used.
752 If 0, the chunk size is limited by the Path MTU only.
753 {sctp_primary_addr, #sctp_prim{}}:
755 #sctp_prim{
758 assoc_id = assoc_id(),
759 addr = {IP, Port}
760 }
761 IP = ip_address()
762 Port = port_number()
763 For the association specified by assoc_id, {IP,Port} must be one of
765 the peer addresses. This option determines that the specified
766 address is treated by the local SCTP stack as the primary address
767 of the peer.
768 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
770 #sctp_setpeerprim{
773 assoc_id = assoc_id(),
774 addr = {IP, Port}
775 }
776 IP = ip_address()
777 Port = port_number()
778 When set, informs the peer to use {IP, Port} as the primary address
780 of the local endpoint for the association specified by assoc_id.
781 {sctp_adaptation_layer, #sctp_setadaptation{}}:
783 #sctp_setadaptation{
786 adaptation_ind = integer()
787 }
788 When set, requests that the local endpoint uses the value specified
790 by adaptation_ind as the Adaptation Indication parameter for estab‐
791 lishing new associations. For details, see RFC 2960 and Sockets API
792 Extenstions for SCTP.
793 {sctp_peer_addr_params, #sctp_paddrparams{}}:
795 #sctp_paddrparams{
798 assoc_id = assoc_id(),
799 address = {IP, Port},
800 hbinterval = integer(),
801 pathmaxrxt = integer(),
802 pathmtu = integer(),
803 sackdelay = integer(),
804 flags = list()
805 }
806 IP = ip_address()
807 Port = port_number()
808 Determines various per-address parameters for the association spec‐
810 ified by assoc_id and the peer address address (the SCTP protocol
811 supports multi-homing, so more than one address can correspond to a
812 specified association).
813 hbinterval:
815 Heartbeat interval, in milliseconds
816 pathmaxrxt:
818 Maximum number of retransmissions before this address is consid‐
819 ered unreachable (and an alternative address is selected)
820 pathmtu:
822 Fixed Path MTU, if automatic discovery is disabled (see flags
823 below)
824 sackdelay:
826 Delay, in milliseconds, for SAC messages (if the delay is
827 enabled, see flags below)
828 flags:
830 The following flags are available:
831 hb_enable:
833 Enables heartbeat
834 hb_disable:
836 Disables heartbeat
837 hb_demand:
839 Initiates heartbeat immediately
840 pmtud_enable:
842 Enables automatic Path MTU discovery
843 pmtud_disable:
845 Disables automatic Path MTU discovery
846 sackdelay_enable:
848 Enables SAC delay
849 sackdelay_disable:
851 Disables SAC delay
852 {sctp_default_send_param, #sctp_sndrcvinfo{}}:
854 #sctp_sndrcvinfo{
857 stream = integer(),
858 ssn = integer(),
859 flags = list(),
860 ppid = integer(),
861 context = integer(),
862 timetolive = integer(),
863 tsn = integer(),
864 cumtsn = integer(),
865 assoc_id = assoc_id()
866 }
867 #sctp_sndrcvinfo{} is used both in this socket option, and as
869 ancillary data while sending or receiving SCTP messages. When set
870 as an option, it provides default values for subsequent send calls
871 on the association specified by assoc_id.
872 assoc_id = 0 (default) indicates the whole endpoint.
874 The following fields typically must be specified by the sender:
876 sinfo_stream:
878 Stream number (0-base) within the association to send the mes‐
879 sages through;
880 sinfo_flags:
882 The following flags are recognised:
883 unordered:
885 The message is to be sent unordered
886 addr_over:
888 The address specified in send overwrites the primary peer
889 address
890 abort:
892 Aborts the current association without flushing any unsent data
893 eof:
895 Gracefully shuts down the current association, with flushing of
896 unsent data
897 Other fields are rarely used. For complete information, see RFC
899 2960 and Sockets API Extensions for SCTP.
900 {sctp_events, #sctp_event_subscribe{}}:
902 #sctp_event_subscribe{
905 data_io_event = true | false,
906 association_event = true | false,
907 address_event = true | false,
908 send_failure_event = true | false,
909 peer_error_event = true | false,
910 shutdown_event = true | false,
911 partial_delivery_event = true | false,
912 adaptation_layer_event = true | false
913 }
914 This option determines which SCTP Events are to be received
916 (through recv/*) along with the data. The only exception is
917 data_io_event, which enables or disables receiving of #sctp_sndrcv‐
918 info{} ancillary data, not events. By default, all flags except
919 adaptation_layer_event are enabled, although sctp_data_io_event and
920 association_event are used by the driver itself and not exported to
921 the user level.
922 {sctp_delayed_ack_time, #sctp_assoc_value{}}:
924 #sctp_assoc_value{
927 assoc_id = assoc_id(),
928 assoc_value = integer()
929 }
930 Rarely used. Determines the ACK time (specified by assoc_value, in
932 milliseconds) for the specified association or the whole endpoint
933 if assoc_value = 0 (default).
934 {sctp_status, #sctp_status{}}:
936 #sctp_status{
939 assoc_id = assoc_id(),
940 state = atom(),
941 rwnd = integer(),
942 unackdata = integer(),
943 penddata = integer(),
944 instrms = integer(),
945 outstrms = integer(),
946 fragmentation_point = integer(),
947 primary = #sctp_paddrinfo{}
948 }
949 This option is read-only. It determines the status of the SCTP
951 association specified by assoc_id. The following are the possible
952 values of state (the state designations are mostly self-explana‐
953 tory):
954 sctp_state_empty:
956 Default. Means that no other state is active.
957 sctp_state_closed:
959 sctp_state_cookie_wait:
962 sctp_state_cookie_echoed:
965 sctp_state_established:
968 sctp_state_shutdown_pending:
971 sctp_state_shutdown_sent:
974 sctp_state_shutdown_received:
977 sctp_state_shutdown_ack_sent:
980 Semantics of the other fields:
983 sstat_rwnd:
985 Current receiver window size of the association
986 sstat_unackdata:
988 Number of unacked data chunks
989 sstat_penddata:
991 Number of data chunks pending receipt
992 sstat_instrms:
994 Number of inbound streams
995 sstat_outstrms:
997 Number of outbound streams
998 sstat_fragmentation_point:
1000 Message size at which SCTP fragmentation occurs
1001 sstat_primary:
1003 Information on the current primary peer address (see below for
1004 the format of #sctp_paddrinfo{})
1005 {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1007 #sctp_paddrinfo{
1010 assoc_id = assoc_id(),
1011 address = {IP, Port},
1012 state = inactive | active | unconfirmed,
1013 cwnd = integer(),
1014 srtt = integer(),
1015 rto = integer(),
1016 mtu = integer()
1017 }
1018 IP = ip_address()
1019 Port = port_number()
1020 This option is read-only. It determines the parameters specific to
1022 the peer address specified by address within the association speci‐
1023 fied by assoc_id. Field address fmust be set by the caller; all
1024 other fields are filled in on return. If assoc_id = 0 (default),
1025 the address is automatically translated into the corresponding
1026 association ID. This option is rarely used. For the semantics of
1027 all fields, see RFC 2960 and Sockets API Extensions for SCTP.
1028
1030 Example of an Erlang SCTP server that receives SCTP messages and prints
1031 them on the standard output:
1032 -module(sctp_server).
1034 -export([server/0,server/1,server/2]).
1036 -include_lib("kernel/include/inet.hrl").
1037 -include_lib("kernel/include/inet_sctp.hrl").
1038 server() ->
1040 server(any, 2006).
1041 server([Host,Port]) when is_list(Host), is_list(Port) ->
1043 {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1044 io:format("~w -> ~w~n", [Host, IP]),
1045 server([IP, list_to_integer(Port)]).
1046 server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1048 is_integer(Port) ->
1049 {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1050 io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1051 ok = gen_sctp:listen(S, true),
1052 server_loop(S).
1053 server_loop(S) ->
1055 case gen_sctp:recv(S) of
1056 {error, Error} ->
1057 io:format("SCTP RECV ERROR: ~p~n", [Error]);
1058 Data ->
1059 io:format("Received: ~p~n", [Data])
1060 end,
1061 server_loop(S).
1062 Example of an Erlang SCTP client interacting with the above server.
1064 Notice that in this example the client creates an association with the
1065 server with 5 outbound streams. Therefore, sending of "Test 0" over
1066 stream 0 succeeds, but sending of "Test 5" over stream 5 fails. The
1067 client then aborts the association, which results in that the corre‐
1068 sponding event is received on the server side.
1069 -module(sctp_client).
1071 -export([client/0, client/1, client/2]).
1073 -include_lib("kernel/include/inet.hrl").
1074 -include_lib("kernel/include/inet_sctp.hrl").
1075 client() ->
1077 client([localhost]).
1078 client([Host]) ->
1080 client(Host, 2006);
1081 client([Host, Port]) when is_list(Host), is_list(Port) ->
1083 client(Host,list_to_integer(Port)),
1084 init:stop().
1085 client(Host, Port) when is_integer(Port) ->
1087 {ok,S} = gen_sctp:open(),
1088 {ok,Assoc} = gen_sctp:connect
1089 (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1090 io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1091 io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1093 io:nl(),
1094 timer:sleep(10000),
1095 io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1096 io:nl(),
1097 timer:sleep(10000),
1098 io:write(gen_sctp:abort(S, Assoc)),
1099 io:nl(),
1100 timer:sleep(1000),
1102 gen_sctp:close(S).
1103 A simple Erlang SCTP client that uses the connect_init API:
1105 -module(ex3).
1107 -export([client/4]).
1109 -include_lib("kernel/include/inet.hrl").
1110 -include_lib("kernel/include/inet_sctp.hrl").
1111 client(Peer1, Port1, Peer2, Port2)
1113 when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1114 {ok,S} = gen_sctp:open(),
1115 SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1116 ActiveOpt = {active, true},
1117 Opts = [SctpInitMsgOpt, ActiveOpt],
1118 ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1119 ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1120 io:format("Connections initiated~n", []),
1121 client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1122 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1124 receive
1125 {sctp, S, Peer1, Port1, {_Anc, SAC}}
1126 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1127 io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1128 [SAC#sctp_assoc_change.state,
1129 SAC#sctp_assoc_change.assoc_id]),
1130 client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1131 Peer2, Port2, AssocId2);
1132 {sctp, S, Peer2, Port2, {_Anc, SAC}}
1134 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1135 io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1136 [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1137 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1138 SAC#sctp_assoc_change.assoc_id);
1139 {sctp, S, Peer1, Port1, Data} ->
1141 io:format("Association 1: received ~p~n", [Data]),
1142 client_loop(S, Peer1, Port1, AssocId1,
1143 Peer2, Port2, AssocId2);
1144 {sctp, S, Peer2, Port2, Data} ->
1146 io:format("Association 2: received ~p~n", [Data]),
1147 client_loop(S, Peer1, Port1, AssocId1,
1148 Peer2, Port2, AssocId2);
1149 Other ->
1151 io:format("Other ~p~n", [Other]),
1152 client_loop(S, Peer1, Port1, AssocId1,
1153 Peer2, Port2, AssocId2)
1154 after 5000 ->
1156 ok
1157 end.
1158
1160 gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control Transmission
1161 Protocol), Sockets API Extensions for SCTP
1162Ericsson AB kernel 6.5 gen_sctp(3)