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 = integer(),
182 outbound_streams = integer(),
183 inbound_streams = integer(),
184 assoc_id = assoc_id()
185 }
186 The number of outbound and inbound streams can be set by giving
188 an sctp_initmsg option to connect as in:
189 connect(Socket, Ip, Port>,
191 [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
192 max_instreams=MaxInStreams}}])
193 All options Opt are set on the socket before the association is
195 attempted. If an option record has undefined field values, the
196 options record is first read from the socket for those values.
197 In effect, Opt option records only define field values to change
198 before connecting.
199 The returned outbound_streams and inbound_streams are the stream
201 numbers on the socket. These can be different from the requested
202 values (OutStreams and MaxInStreams, respectively) if the peer
203 requires lower values.
204 state can have the following values:
206 comm_up:
208 Association is successfully established. This indicates a
209 successful completion of connect.
210 cant_assoc:
212 The association cannot be established (connect/* failure).
213 Other states do not normally occur in the output from connect/*.
215 Rather, they can occur in #sctp_assoc_change{} events received
216 instead of data in recv/* calls. All of them indicate losing the
217 association because of various error conditions, and are listed
218 here for the sake of completeness:
219 comm_lost:
221 restart:
224 shutdown_comp:
227 Field error can provide more detailed diagnostics. The error
230 field value can be converted into a string using error_string/1.
231 connect_init(Socket, Addr, Port, Opts) ->
233 ok | {error, inet:posix()}
234 Types:
236 Socket = sctp_socket()
238 Addr = inet:ip_address() | inet:hostname()
239 Port = inet:port_number()
240 Opts = [option()]
241 Same as connect_init(Socket, Addr, Port, Opts, infinity).
243 connect_init(Socket, Addr, Port, Opts, Timeout) ->
245 ok | {error, inet:posix()}
246 Types:
248 Socket = sctp_socket()
250 Addr = inet:ip_address() | inet:hostname()
251 Port = inet:port_number()
252 Opts = [option()]
253 Timeout = timeout()
254 Initiates a new association for socket Socket, with the peer
256 (SCTP server socket) specified by Addr and Port.
257 The fundamental difference between this API and connect/* is
259 that the return value is that of the underlying OS connect(2)
260 system call. If ok is returned, the result of the association
261 establishment is received by the calling process as an
262 #sctp_assoc_change{} event. The calling process must be prepared
263 to receive this, or poll for it using recv/*, depending on the
264 value of the active option.
265 The parameters are as described in connect/*, except the Timeout
267 value.
268 The timer associated with Timeout only supervises IP resolution
270 of Addr.
271 controlling_process(Socket, Pid) -> ok | {error, Reason}
273 Types:
275 Socket = sctp_socket()
277 Pid = pid()
278 Reason = closed | not_owner | badarg | inet:posix()
279 Assigns a new controlling process Pid to Socket. Same implemen‐
281 tation as gen_udp:controlling_process/2.
282 eof(Socket, Assoc) -> ok | {error, Reason}
284 Types:
286 Socket = sctp_socket()
288 Assoc = #sctp_assoc_change{}
289 Reason = term()
290 Gracefully terminates the association specified by Assoc, with
292 flushing of all unsent data. The socket itself remains open.
293 Other associations opened on this socket are still valid. The
294 socket can be used in new associations.
295 error_string(ErrorNumber) -> ok | string() | unknown_error
297 Types:
299 ErrorNumber = integer()
301 Translates an SCTP error number from, for example,
303 #sctp_remote_error{} or #sctp_send_failed{} into an explanatory
304 string, or one of the atoms ok for no error or undefined for an
305 unrecognized error.
306 listen(Socket, IsServer) -> ok | {error, Reason}
308 listen(Socket, Backlog) -> ok | {error, Reason}
310 Types:
312 Socket = sctp_socket()
314 Backlog = integer()
315 Reason = term()
316 Sets up a socket to listen on the IP address and port number it
318 is bound to.
319 For type seqpacket, sockets (the default) IsServer must be true
321 or false. In contrast to TCP, there is no listening queue length
322 in SCTP. If IsServer is true, the socket accepts new associa‐
323 tions, that is, it becomes an SCTP server socket.
324 For type stream, sockets Backlog define the backlog queue length
326 just like in TCP.
327 open() -> {ok, Socket} | {error, inet:posix()}
329 open(Port) -> {ok, Socket} | {error, inet:posix()}
331 open(Opts) -> {ok, Socket} | {error, inet:posix()}
333 open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
335 Types:
337 Opts = [Opt]
339 Opt =
340 {ip, IP} |
341 {ifaddr, IP} |
342 inet:address_family() |
343 {port, Port} |
344 {type, SockType} |
345 option()
346 IP = inet:ip_address() | any | loopback
347 Port = inet:port_number()
348 SockType = seqpacket | stream
349 Socket = sctp_socket()
350 Creates an SCTP socket and binds it to the local addresses spec‐
352 ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
353 feature is called SCTP multi-homing). The default IP and Port
354 are any and 0, meaning bind to all local addresses on any free
355 port.
356 Other options:
358 inet6:
360 Sets up the socket for IPv6.
361 inet:
363 Sets up the socket for IPv4. This is the default.
364 A default set of socket options is used. In particular, the
366 socket is opened in binary and passive mode, with SockType seq‐
367 packet, and with reasonably large kernel and driver buffers.
368 If the socket is in passive mode data can be received through
370 the recv/1,2 calls.
371 If the socket is in active mode data received data is delivered
373 to the controlling process as messages:
374 {sctp, Socket, FromIP, FromPort, {AncData, Data}}
376 See recv/1,2 for a description of the message fields.
379 Note:
381 This message format unfortunately differs slightly from the
382 gen_udp message format with ancillary data, and from the
383 recv/1,2 return tuple format.
384 peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
387 Types:
389 Socket = sctp_socket()
391 Assoc = #sctp_assoc_change{} | assoc_id()
392 NewSocket = sctp_socket()
393 Reason = term()
394 Branches off an existing association Assoc in a socket Socket of
396 type seqpacket (one-to-many style) into a new socket NewSocket
397 of type stream (one-to-one style).
398 The existing association argument Assoc can be either a
400 #sctp_assoc_change{} record as returned from, for example,
401 recv/*, connect/*, or from a listening socket in active mode. It
402 can also be just the field assoc_id integer from such a record.
403 recv(Socket) ->
405 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
406 recv(Socket, Timeout) ->
408 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
409 Types:
411 Socket = sctp_socket()
413 Timeout = timeout()
414 FromIP = inet:ip_address()
415 FromPort = inet:port_number()
416 AncData = [#sctp_sndrcvinfo{} | inet:ancillary_data()]
417 Data =
418 binary() |
419 string() |
420 #sctp_sndrcvinfo{} |
421 #sctp_assoc_change{} |
422 #sctp_paddr_change{} |
423 #sctp_adaptation_event{}
424 Reason =
425 inet:posix() |
426 #sctp_send_failed{} |
427 #sctp_paddr_change{} |
428 #sctp_pdapi_event{} |
429 #sctp_remote_error{} |
430 #sctp_shutdown_event{}
431 Receives the Data message from any association of the socket. If
433 the receive times out, {error,timeout} is returned. The default
434 time-out is infinity. FromIP and FromPort indicate the address
435 of the sender.
436 AncData is a list of ancillary data items that can be received
438 along with the main Data. This list can be empty, or contain a
439 single #sctp_sndrcvinfo{} record if receiving of such ancillary
440 data is enabled (see option sctp_events). It is enabled by
441 default, as such ancillary data provides an easy way of deter‐
442 mining the association and stream over which the message is
443 received. (An alternative way is to get the association ID from
444 FromIP and FromPort using socket option sctp_get_peer_addr_info,
445 but this does still not produce the stream number).
446 AncData may also contain ancillary data from the socket
448 options recvtos, recvtclass or recvttl, if that is supported by
449 the platform for the socket.
450 The Data received can be a binary() or a list() of bytes (inte‐
452 gers in the range 0 through 255) depending on the socket mode,
453 or an SCTP event.
454 Possible SCTP events:
456 * #sctp_sndrcvinfo{}
458 * #sctp_assoc_change{}
460 *
462 #sctp_paddr_change{
465 addr = {ip_address(),port()},
466 state = atom(),
467 error = integer(),
468 assoc_id = assoc_id()
469 }
470 Indicates change of the status of the IP address of the peer
472 specified by addr within association assoc_id. Possible val‐
473 ues of state (mostly self-explanatory) include:
474 addr_unreachable:
476 addr_available:
479 addr_removed:
482 addr_added:
485 addr_made_prim:
488 addr_confirmed:
491 In case of an error (for example, addr_unreachable), field
494 error provides more diagnostics. In such cases, event
495 #sctp_paddr_change{} is automatically converted into an
496 error term returned by recv. The error field value can be
497 converted into a string using error_string/1.
498 *
500 #sctp_send_failed{
503 flags = true | false,
504 error = integer(),
505 info = #sctp_sndrcvinfo{},
506 assoc_id = assoc_id()
507 data = binary()
508 }
509 The sender can receive this event if a send operation fails.
511 flags:
513 A Boolean specifying if the data has been transmitted over
514 the wire.
515 error:
517 Provides extended diagnostics, use error_string/1.
518 info:
520 The original #sctp_sndrcvinfo{} record used in the failed
521 send/*.
522 data:
524 The whole original data chunk attempted to be sent.
525 In the current implementation of the Erlang/SCTP binding,
527 this event is internally converted into an error term
528 returned by recv/*.
529 *
531 #sctp_adaptation_event{
534 adaptation_ind = integer(),
535 assoc_id = assoc_id()
536 }
537 Delivered when a peer sends an adaptation layer indication
539 parameter (configured through option sctp_adaptation_layer).
540 Notice that with the current implementation of the
541 Erlang/SCTP binding, this event is disabled by default.
542 *
544 #sctp_pdapi_event{
547 indication = sctp_partial_delivery_aborted,
548 assoc_id = assoc_id()
549 }
550 A partial delivery failure. In the current implementation of
552 the Erlang/SCTP binding, this event is internally converted
553 into an error term returned by recv/*.
554 send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
556 Types:
558 Socket = sctp_socket()
560 SndRcvInfo = #sctp_sndrcvinfo{}
561 Data = binary() | iolist()
562 Reason = term()
563 Sends the Data message with all sending parameters from a
565 #sctp_sndrcvinfo{} record. This way, the user can specify the
566 PPID (passed to the remote end) and context (passed to the local
567 SCTP layer), which can be used, for example, for error identifi‐
568 cation. However, such a fine level of user control is rarely
569 required. The function send/4 is sufficient for most applica‐
570 tions.
571 send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
573 Types:
575 Socket = sctp_socket()
577 Assoc = #sctp_assoc_change{} | assoc_id()
578 Stream = integer()
579 Data = binary() | iolist()
580 Reason = term()
581 Sends a Data message over an existing association and specified
583 stream.
584
586 The set of admissible SCTP socket options is by construction orthogonal
587 to the sets of TCP, UDP, and generic inet options. Only options listed
588 here are allowed for SCTP sockets. Options can be set on the socket
589 using open/1,2 or inet:setopts/2, retrieved using inet:getopts/2.
590 Options can be changed when calling connect/4,5.
591 {mode, list|binary} or just list or binary:
593 Determines the type of data returned from recv/1,2.
594 {active, true|false|once|N}:
596 * If false (passive mode, the default), the caller must do an
599 explicit recv call to retrieve the available data from the
600 socket.
601 * If true|once|N (active modes) received data or events are sent to
603 the owning process. See open/0..2 for the message format.
604 * If true (full active mode) there is no flow control.
606 Note:
608 Note that this can cause the message queue to overflow causing for
609 example the virtual machine to run out of memory and crash.
610 * If once, only one message is automatically placed in the message
613 queue, and after that the mode is automatically reset to passive.
614 This provides flow control and the possibility for the receiver
615 to listen for its incoming SCTP data interleaved with other
616 inter-process messages.
617 * If active is specified as an integer N in the range -32768 to
619 32767 (inclusive), that number is added to the socket's counting
620 of data messages to be delivered to the controlling process. If
621 the result of the addition is negative, the count is set to 0.
622 Once the count reaches 0, either through the delivery of messages
623 or by being explicitly set with inet:setopts/2, the socket mode
624 is automatically reset to passive ({active, false}). When a
625 socket in this active mode transitions to passive mode, the mes‐
626 sage {sctp_passive, Socket} is sent to the controlling process to
627 notify it that if it wants to receive more data messages from the
628 socket, it must call inet:setopts/2 to set the socket back into
629 an active mode.
630 {tos, integer()}:
632 Sets the Type-Of-Service field on the IP datagrams that are sent,
633 to the specified value. This effectively determines a prioritiza‐
634 tion policy for the outbound packets. The acceptable values are
635 system-dependent.
636 {priority, integer()}:
638 A protocol-independent equivalent of tos above. Setting priority
639 implies setting tos as well.
640 {dontroute, true|false}:
642 Defaults to false. If true, the kernel does not send packets
643 through any gateway, only sends them to directly connected hosts.
644 {reuseaddr, true|false}:
646 Defaults to false. If true, the local binding address {IP,Port} of
647 the socket can be reused immediately. No waiting in state
648 CLOSE_WAIT is performed (can be required for high-throughput
649 servers).
650 {sndbuf, integer()}:
652 The size, in bytes, of the OS kernel send buffer for this socket.
653 Sending errors would occur for datagrams larger than val(sndbuf).
654 Setting this option also adjusts the size of the driver buffer (see
655 buffer above).
656 {recbuf, integer()}:
658 The size, in bytes, of the OS kernel receive buffer for this
659 socket. Sending errors would occur for datagrams larger than
660 val(recbuf). Setting this option also adjusts the size of the
661 driver buffer (see buffer above).
662 {sctp_module, module()}:
664 Overrides which callback module is used. Defaults to inet_sctp for
665 IPv4 and inet6_sctp for IPv6.
666 {sctp_rtoinfo, #sctp_rtoinfo{}}:
668 #sctp_rtoinfo{
671 assoc_id = assoc_id(),
672 initial = integer(),
673 max = integer(),
674 min = integer()
675 }
676 Determines retransmission time-out parameters, in milliseconds, for
678 the association(s) specified by assoc_id.
679 assoc_id = 0 (default) indicates the whole endpoint. See RFC 2960
681 and Sockets API Extensions for SCTP for the exact semantics of the
682 field values.
683 {sctp_associnfo, #sctp_assocparams{}}:
685 #sctp_assocparams{
688 assoc_id = assoc_id(),
689 asocmaxrxt = integer(),
690 number_peer_destinations = integer(),
691 peer_rwnd = integer(),
692 local_rwnd = integer(),
693 cookie_life = integer()
694 }
695 Determines association parameters for the association(s) specified
697 by assoc_id.
698 assoc_id = 0 (default) indicates the whole endpoint. See Sockets
700 API Extensions for SCTP for the discussion of their semantics.
701 Rarely used.
702 {sctp_initmsg, #sctp_initmsg{}}:
704 #sctp_initmsg{
707 num_ostreams = integer(),
708 max_instreams = integer(),
709 max_attempts = integer(),
710 max_init_timeo = integer()
711 }
712 Determines the default parameters that this socket tries to negoti‐
714 ate with its peer while establishing an association with it. Is to
715 be set after open/* but before the first connect/*. #sctp_initmsg{}
716 can also be used as ancillary data with the first call of send/* to
717 a new peer (when a new association is created).
718 num_ostreams:
720 Number of outbound streams
721 max_instreams:
723 Maximum number of inbound streams
724 max_attempts:
726 Maximum retransmissions while establishing an association
727 max_init_timeo:
729 Time-out, in milliseconds, for establishing an association
730 {sctp_autoclose, integer() >= 0}:
732 Determines the time, in seconds, after which an idle association is
733 automatically closed. 0 means that the association is never auto‐
734 matically closed.
735 {sctp_nodelay, true|false}:
737 Turns on|off the Nagle algorithm for merging small packets into
738 larger ones. This improves throughput at the expense of latency.
739 {sctp_disable_fragments, true|false}:
741 If true, induces an error on an attempt to send a message larger
742 than the current PMTU size (which would require fragmenta‐
743 tion/reassembling). Notice that message fragmentation does not
744 affect the logical atomicity of its delivery; this option is pro‐
745 vided for performance reasons only.
746 {sctp_i_want_mapped_v4_addr, true|false}:
748 Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
749 the socket address family is AF_INET6).
750 {sctp_maxseg, integer()}:
752 Determines the maximum chunk size if message fragmentation is used.
753 If 0, the chunk size is limited by the Path MTU only.
754 {sctp_primary_addr, #sctp_prim{}}:
756 #sctp_prim{
759 assoc_id = assoc_id(),
760 addr = {IP, Port}
761 }
762 IP = ip_address()
763 Port = port_number()
764 For the association specified by assoc_id, {IP,Port} must be one of
766 the peer addresses. This option determines that the specified
767 address is treated by the local SCTP stack as the primary address
768 of the peer.
769 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
771 #sctp_setpeerprim{
774 assoc_id = assoc_id(),
775 addr = {IP, Port}
776 }
777 IP = ip_address()
778 Port = port_number()
779 When set, informs the peer to use {IP, Port} as the primary address
781 of the local endpoint for the association specified by assoc_id.
782 {sctp_adaptation_layer, #sctp_setadaptation{}}:
784 #sctp_setadaptation{
787 adaptation_ind = integer()
788 }
789 When set, requests that the local endpoint uses the value specified
791 by adaptation_ind as the Adaptation Indication parameter for estab‐
792 lishing new associations. For details, see RFC 2960 and Sockets API
793 Extenstions for SCTP.
794 {sctp_peer_addr_params, #sctp_paddrparams{}}:
796 #sctp_paddrparams{
799 assoc_id = assoc_id(),
800 address = {IP, Port},
801 hbinterval = integer(),
802 pathmaxrxt = integer(),
803 pathmtu = integer(),
804 sackdelay = integer(),
805 flags = list()
806 }
807 IP = ip_address()
808 Port = port_number()
809 Determines various per-address parameters for the association spec‐
811 ified by assoc_id and the peer address address (the SCTP protocol
812 supports multi-homing, so more than one address can correspond to a
813 specified association).
814 hbinterval:
816 Heartbeat interval, in milliseconds
817 pathmaxrxt:
819 Maximum number of retransmissions before this address is consid‐
820 ered unreachable (and an alternative address is selected)
821 pathmtu:
823 Fixed Path MTU, if automatic discovery is disabled (see flags
824 below)
825 sackdelay:
827 Delay, in milliseconds, for SAC messages (if the delay is
828 enabled, see flags below)
829 flags:
831 The following flags are available:
832 hb_enable:
834 Enables heartbeat
835 hb_disable:
837 Disables heartbeat
838 hb_demand:
840 Initiates heartbeat immediately
841 pmtud_enable:
843 Enables automatic Path MTU discovery
844 pmtud_disable:
846 Disables automatic Path MTU discovery
847 sackdelay_enable:
849 Enables SAC delay
850 sackdelay_disable:
852 Disables SAC delay
853 {sctp_default_send_param, #sctp_sndrcvinfo{}}:
855 #sctp_sndrcvinfo{
858 stream = integer(),
859 ssn = integer(),
860 flags = list(),
861 ppid = integer(),
862 context = integer(),
863 timetolive = integer(),
864 tsn = integer(),
865 cumtsn = integer(),
866 assoc_id = assoc_id()
867 }
868 #sctp_sndrcvinfo{} is used both in this socket option, and as
870 ancillary data while sending or receiving SCTP messages. When set
871 as an option, it provides default values for subsequent send calls
872 on the association specified by assoc_id.
873 assoc_id = 0 (default) indicates the whole endpoint.
875 The following fields typically must be specified by the sender:
877 sinfo_stream:
879 Stream number (0-base) within the association to send the mes‐
880 sages through;
881 sinfo_flags:
883 The following flags are recognised:
884 unordered:
886 The message is to be sent unordered
887 addr_over:
889 The address specified in send overwrites the primary peer
890 address
891 abort:
893 Aborts the current association without flushing any unsent data
894 eof:
896 Gracefully shuts down the current association, with flushing of
897 unsent data
898 Other fields are rarely used. For complete information, see RFC
900 2960 and Sockets API Extensions for SCTP.
901 {sctp_events, #sctp_event_subscribe{}}:
903 #sctp_event_subscribe{
906 data_io_event = true | false,
907 association_event = true | false,
908 address_event = true | false,
909 send_failure_event = true | false,
910 peer_error_event = true | false,
911 shutdown_event = true | false,
912 partial_delivery_event = true | false,
913 adaptation_layer_event = true | false
914 }
915 This option determines which SCTP Events are to be received
917 (through recv/*) along with the data. The only exception is
918 data_io_event, which enables or disables receiving of #sctp_sndrcv‐
919 info{} ancillary data, not events. By default, all flags except
920 adaptation_layer_event are enabled, although sctp_data_io_event and
921 association_event are used by the driver itself and not exported to
922 the user level.
923 {sctp_delayed_ack_time, #sctp_assoc_value{}}:
925 #sctp_assoc_value{
928 assoc_id = assoc_id(),
929 assoc_value = integer()
930 }
931 Rarely used. Determines the ACK time (specified by assoc_value, in
933 milliseconds) for the specified association or the whole endpoint
934 if assoc_value = 0 (default).
935 {sctp_status, #sctp_status{}}:
937 #sctp_status{
940 assoc_id = assoc_id(),
941 state = atom(),
942 rwnd = integer(),
943 unackdata = integer(),
944 penddata = integer(),
945 instrms = integer(),
946 outstrms = integer(),
947 fragmentation_point = integer(),
948 primary = #sctp_paddrinfo{}
949 }
950 This option is read-only. It determines the status of the SCTP
952 association specified by assoc_id. The following are the possible
953 values of state (the state designations are mostly self-explana‐
954 tory):
955 sctp_state_empty:
957 Default. Means that no other state is active.
958 sctp_state_closed:
960 sctp_state_cookie_wait:
963 sctp_state_cookie_echoed:
966 sctp_state_established:
969 sctp_state_shutdown_pending:
972 sctp_state_shutdown_sent:
975 sctp_state_shutdown_received:
978 sctp_state_shutdown_ack_sent:
981 Semantics of the other fields:
984 sstat_rwnd:
986 Current receiver window size of the association
987 sstat_unackdata:
989 Number of unacked data chunks
990 sstat_penddata:
992 Number of data chunks pending receipt
993 sstat_instrms:
995 Number of inbound streams
996 sstat_outstrms:
998 Number of outbound streams
999 sstat_fragmentation_point:
1001 Message size at which SCTP fragmentation occurs
1002 sstat_primary:
1004 Information on the current primary peer address (see below for
1005 the format of #sctp_paddrinfo{})
1006 {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1008 #sctp_paddrinfo{
1011 assoc_id = assoc_id(),
1012 address = {IP, Port},
1013 state = inactive | active | unconfirmed,
1014 cwnd = integer(),
1015 srtt = integer(),
1016 rto = integer(),
1017 mtu = integer()
1018 }
1019 IP = ip_address()
1020 Port = port_number()
1021 This option is read-only. It determines the parameters specific to
1023 the peer address specified by address within the association speci‐
1024 fied by assoc_id. Field address fmust be set by the caller; all
1025 other fields are filled in on return. If assoc_id = 0 (default),
1026 the address is automatically translated into the corresponding
1027 association ID. This option is rarely used. For the semantics of
1028 all fields, see RFC 2960 and Sockets API Extensions for SCTP.
1029
1031 Example of an Erlang SCTP server that receives SCTP messages and prints
1032 them on the standard output:
1033 -module(sctp_server).
1035 -export([server/0,server/1,server/2]).
1037 -include_lib("kernel/include/inet.hrl").
1038 -include_lib("kernel/include/inet_sctp.hrl").
1039 server() ->
1041 server(any, 2006).
1042 server([Host,Port]) when is_list(Host), is_list(Port) ->
1044 {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1045 io:format("~w -> ~w~n", [Host, IP]),
1046 server([IP, list_to_integer(Port)]).
1047 server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1049 is_integer(Port) ->
1050 {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1051 io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1052 ok = gen_sctp:listen(S, true),
1053 server_loop(S).
1054 server_loop(S) ->
1056 case gen_sctp:recv(S) of
1057 {error, Error} ->
1058 io:format("SCTP RECV ERROR: ~p~n", [Error]);
1059 Data ->
1060 io:format("Received: ~p~n", [Data])
1061 end,
1062 server_loop(S).
1063 Example of an Erlang SCTP client interacting with the above server.
1065 Notice that in this example the client creates an association with the
1066 server with 5 outbound streams. Therefore, sending of "Test 0" over
1067 stream 0 succeeds, but sending of "Test 5" over stream 5 fails. The
1068 client then aborts the association, which results in that the corre‐
1069 sponding event is received on the server side.
1070 -module(sctp_client).
1072 -export([client/0, client/1, client/2]).
1074 -include_lib("kernel/include/inet.hrl").
1075 -include_lib("kernel/include/inet_sctp.hrl").
1076 client() ->
1078 client([localhost]).
1079 client([Host]) ->
1081 client(Host, 2006);
1082 client([Host, Port]) when is_list(Host), is_list(Port) ->
1084 client(Host,list_to_integer(Port)),
1085 init:stop().
1086 client(Host, Port) when is_integer(Port) ->
1088 {ok,S} = gen_sctp:open(),
1089 {ok,Assoc} = gen_sctp:connect
1090 (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1091 io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1092 io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1094 io:nl(),
1095 timer:sleep(10000),
1096 io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1097 io:nl(),
1098 timer:sleep(10000),
1099 io:write(gen_sctp:abort(S, Assoc)),
1100 io:nl(),
1101 timer:sleep(1000),
1103 gen_sctp:close(S).
1104 A simple Erlang SCTP client that uses the connect_init API:
1106 -module(ex3).
1108 -export([client/4]).
1110 -include_lib("kernel/include/inet.hrl").
1111 -include_lib("kernel/include/inet_sctp.hrl").
1112 client(Peer1, Port1, Peer2, Port2)
1114 when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1115 {ok,S} = gen_sctp:open(),
1116 SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1117 ActiveOpt = {active, true},
1118 Opts = [SctpInitMsgOpt, ActiveOpt],
1119 ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1120 ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1121 io:format("Connections initiated~n", []),
1122 client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1123 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1125 receive
1126 {sctp, S, Peer1, Port1, {_Anc, SAC}}
1127 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1128 io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1129 [SAC#sctp_assoc_change.state,
1130 SAC#sctp_assoc_change.assoc_id]),
1131 client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1132 Peer2, Port2, AssocId2);
1133 {sctp, S, Peer2, Port2, {_Anc, SAC}}
1135 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1136 io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1137 [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1138 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1139 SAC#sctp_assoc_change.assoc_id);
1140 {sctp, S, Peer1, Port1, Data} ->
1142 io:format("Association 1: received ~p~n", [Data]),
1143 client_loop(S, Peer1, Port1, AssocId1,
1144 Peer2, Port2, AssocId2);
1145 {sctp, S, Peer2, Port2, Data} ->
1147 io:format("Association 2: received ~p~n", [Data]),
1148 client_loop(S, Peer1, Port1, AssocId1,
1149 Peer2, Port2, AssocId2);
1150 Other ->
1152 io:format("Other ~p~n", [Other]),
1153 client_loop(S, Peer1, Port1, AssocId1,
1154 Peer2, Port2, AssocId2)
1155 after 5000 ->
1157 ok
1158 end.
1159
1161 gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control Transmission
1162 Protocol), Sockets API Extensions for SCTP
1163Ericsson AB kernel 7.3 gen_sctp(3)