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, SockAddr, 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 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
142 Opts = [Opt :: option()]
143 Same as connect(Socket, SockAddr, Opts, infinity).
145 connect(Socket, SockAddr, Opts, Timeout) ->
147 {ok, #sctp_assoc_change{state = comm_up}} |
148 {error, #sctp_assoc_change{state = cant_assoc}} |
149 {error, inet:posix()}
150 Types:
152 Socket = sctp_socket()
154 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
155 Opts = [Opt :: option()]
156 Timeout = timeout()
157 This is conceptually the same as connect/5, only with the dif‐
159 ference that we use a socket address, socket:sockaddr_in() or
160 socket:sockaddr_in6() instead of an address (inet:ip_address()
161 or inet:hostname()) and port-number.
162 connect(Socket, Addr, Port, Opts) ->
164 {ok, #sctp_assoc_change{state = comm_up}} |
165 {error, #sctp_assoc_change{state = cant_assoc}} |
166 {error, inet:posix()}
167 Types:
169 Socket = sctp_socket()
171 Addr = inet:ip_address() | inet:hostname()
172 Port = inet:port_number()
173 Opts = [Opt :: option()]
174 Same as connect(Socket, Addr, Port, Opts, infinity).
176 connect(Socket, Addr, Port, Opts, Timeout) ->
178 {ok, #sctp_assoc_change{state = comm_up}} |
179 {error, #sctp_assoc_change{state = cant_assoc}} |
180 {error, inet:posix()}
181 Types:
183 Socket = sctp_socket()
185 Addr = inet:ip_address() | inet:hostname()
186 Port = inet:port_number()
187 Opts = [Opt :: option()]
188 Timeout = timeout()
189 Establishes a new association for socket Socket, with the peer
191 (SCTP server socket) specified by Addr and Port. Timeout, is ex‐
192 pressed in milliseconds. A socket can be associated with multi‐
193 ple peers.
194 Warning:
196 Using a value of Timeout less than the maximum time taken by the
197 OS to establish an association (around 4.5 minutes if the de‐
198 fault values from RFC 4960 are used), can result in inconsistent
199 or incorrect return values. This is especially relevant for as‐
200 sociations sharing the same Socket (that is, source address and
201 port), as the controlling process blocks until connect/* re‐
202 turns. connect_init/* provides an alternative without this limi‐
203 tation.
204 The result of connect/* is an #sctp_assoc_change{} event that
207 contains, in particular, the new Association ID:
208 #sctp_assoc_change{
210 state = atom(),
211 error = integer(),
212 outbound_streams = integer(),
213 inbound_streams = integer(),
214 assoc_id = assoc_id()
215 }
216 The number of outbound and inbound streams can be set by giving
218 an sctp_initmsg option to connect as in:
219 connect(Socket, Ip, Port>,
221 [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
222 max_instreams=MaxInStreams}}])
223 All options Opt are set on the socket before the association is
225 attempted. If an option record has undefined field values, the
226 options record is first read from the socket for those values.
227 In effect, Opt option records only define field values to change
228 before connecting.
229 The returned outbound_streams and inbound_streams are the stream
231 numbers on the socket. These can be different from the requested
232 values (OutStreams and MaxInStreams, respectively) if the peer
233 requires lower values.
234 state can have the following values:
236 comm_up:
238 Association is successfully established. This indicates a
239 successful completion of connect.
240 cant_assoc:
242 The association cannot be established (connect/* failure).
243 Other states do not normally occur in the output from connect/*.
245 Rather, they can occur in #sctp_assoc_change{} events received
246 instead of data in recv/* calls. All of them indicate losing the
247 association because of various error conditions, and are listed
248 here for the sake of completeness:
249 comm_lost:
251 restart:
254 shutdown_comp:
257 Field error can provide more detailed diagnostics. The error
260 field value can be converted into a string using error_string/1.
261 connect_init(Socket, SockAddr, Opts) -> ok | {error, inet:posix()}
263 Types:
265 Socket = sctp_socket()
267 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
268 Opts = [option()]
269 Same as connect_init(Socket, SockAddr, Opts, infinity).
271 connect_init(Socket, SockAddr, Opts, Timeout) ->
273 ok | {error, inet:posix()}
274 Types:
276 Socket = sctp_socket()
278 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
279 Opts = [option()]
280 Timeout = timeout()
281 This is conceptually the same as connect_init/5, only with the
283 difference that we use a socket address, socket:sockaddr_in() or
284 socket:sockaddr_in6() instead of an address (inet:ip_address()
285 or inet:hostname()) and port-number.
286 connect_init(Socket, Addr, Port, Opts) ->
288 ok | {error, inet:posix()}
289 Types:
291 Socket = sctp_socket()
293 Addr = inet:ip_address() | inet:hostname()
294 Port = inet:port_number()
295 Opts = [option()]
296 Same as connect_init(Socket, Addr, Port, Opts, infinity).
298 connect_init(Socket, Addr, Port, Opts, Timeout) ->
300 ok | {error, inet:posix()}
301 Types:
303 Socket = sctp_socket()
305 Addr = inet:ip_address() | inet:hostname()
306 Port = inet:port_number()
307 Opts = [option()]
308 Timeout = timeout()
309 Initiates a new association for socket Socket, with the peer
311 (SCTP server socket) specified by Addr and Port.
312 The fundamental difference between this API and connect/* is
314 that the return value is that of the underlying OS connect(2)
315 system call. If ok is returned, the result of the association
316 establishment is received by the calling process as an #sctp_as‐
317 soc_change{} event. The calling process must be prepared to re‐
318 ceive this, or poll for it using recv/*, depending on the value
319 of the active option.
320 The parameters are as described in connect/*, except the Timeout
322 value.
323 The timer associated with Timeout only supervises IP resolution
325 of Addr.
326 controlling_process(Socket, Pid) -> ok | {error, Reason}
328 Types:
330 Socket = sctp_socket()
332 Pid = pid()
333 Reason = closed | not_owner | badarg | inet:posix()
334 Assigns a new controlling process Pid to Socket. Same implemen‐
336 tation as gen_udp:controlling_process/2.
337 eof(Socket, Assoc) -> ok | {error, Reason}
339 Types:
341 Socket = sctp_socket()
343 Assoc = #sctp_assoc_change{}
344 Reason = term()
345 Gracefully terminates the association specified by Assoc, with
347 flushing of all unsent data. The socket itself remains open.
348 Other associations opened on this socket are still valid. The
349 socket can be used in new associations.
350 error_string(ErrorNumber) -> ok | string() | unknown_error
352 Types:
354 ErrorNumber = integer()
356 Translates an SCTP error number from, for example, #sctp_re‐
358 mote_error{} or #sctp_send_failed{} into an explanatory string,
359 or one of the atoms ok for no error or undefined for an unrecog‐
360 nized error.
361 listen(Socket, IsServer) -> ok | {error, Reason}
363 listen(Socket, Backlog) -> ok | {error, Reason}
365 Types:
367 Socket = sctp_socket()
369 Backlog = integer()
370 Reason = term()
371 Sets up a socket to listen on the IP address and port number it
373 is bound to.
374 For type seqpacket, sockets (the default) IsServer must be true
376 or false. In contrast to TCP, there is no listening queue length
377 in SCTP. If IsServer is true, the socket accepts new associa‐
378 tions, that is, it becomes an SCTP server socket.
379 For type stream, sockets Backlog define the backlog queue length
381 just like in TCP.
382 open() -> {ok, Socket} | {error, inet:posix()}
384 open(Port) -> {ok, Socket} | {error, inet:posix()}
386 open(Opts) -> {ok, Socket} | {error, inet:posix()}
388 open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
390 Types:
392 Opts = [Opt]
394 Opt =
395 {ifaddr, IP | SockAddr} |
396 {ip, IP} |
397 {port, Port} |
398 inet:address_family() |
399 {type, SockType} |
400 {netns, file:filename_all()} |
401 {bind_to_device, binary()} |
402 option()
403 IP = inet:ip_address() | any | loopback
404 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
405 Port = inet:port_number()
406 SockType = seqpacket | stream
407 Socket = sctp_socket()
408 Creates an SCTP socket and binds it to the local addresses spec‐
410 ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
411 feature is called SCTP multi-homing). The default IP and Port
412 are any and 0, meaning bind to all local addresses on any free
413 port.
414 It is also possible to use {ifaddr, SockAddr}, in which case it
416 takes precedence over the ip and port options. These options can
417 however be used to update the address and port of ifaddr (if
418 they occur after ifaddr in the options list), although this is
419 not recommended.
420 Other options:
422 inet6:
424 Sets up the socket for IPv6.
425 inet:
427 Sets up the socket for IPv4. This is the default.
428 A default set of socket options is used. In particular, the
430 socket is opened in binary and passive mode, with SockType seq‐
431 packet, and with reasonably large kernel and driver buffers.
432 If the socket is in passive mode data can be received through
434 the recv/1,2 calls.
435 If the socket is in active mode data received data is delivered
437 to the controlling process as messages:
438 {sctp, Socket, FromIP, FromPort, {AncData, Data}}
440 See recv/1,2 for a description of the message fields.
443 Note:
445 This message format unfortunately differs slightly from the
446 gen_udp message format with ancillary data, and from the
447 recv/1,2 return tuple format.
448 peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
451 Types:
453 Socket = sctp_socket()
455 Assoc = #sctp_assoc_change{} | assoc_id()
456 NewSocket = sctp_socket()
457 Reason = term()
458 Branches off an existing association Assoc in a socket Socket of
460 type seqpacket (one-to-many style) into a new socket NewSocket
461 of type stream (one-to-one style).
462 The existing association argument Assoc can be either a
464 #sctp_assoc_change{} record as returned from, for example,
465 recv/*, connect/*, or from a listening socket in active mode. It
466 can also be just the field assoc_id integer from such a record.
467 recv(Socket) ->
469 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
470 recv(Socket, Timeout) ->
472 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
473 Types:
475 Socket = sctp_socket()
477 Timeout = timeout()
478 FromIP = inet:ip_address()
479 FromPort = inet:port_number()
480 AncData = [#sctp_sndrcvinfo{} | inet:ancillary_data()]
481 Data =
482 binary() |
483 string() |
484 #sctp_sndrcvinfo{} |
485 #sctp_assoc_change{} |
486 #sctp_paddr_change{} |
487 #sctp_adaptation_event{}
488 Reason =
489 inet:posix() |
490 #sctp_send_failed{} |
491 #sctp_paddr_change{} |
492 #sctp_pdapi_event{} |
493 #sctp_remote_error{} |
494 #sctp_shutdown_event{}
495 Receives the Data message from any association of the socket. If
497 the receive times out, {error,timeout} is returned. The default
498 time-out is infinity. FromIP and FromPort indicate the address
499 of the sender.
500 AncData is a list of ancillary data items that can be received
502 along with the main Data. This list can be empty, or contain a
503 single #sctp_sndrcvinfo{} record if receiving of such ancillary
504 data is enabled (see option sctp_events). It is enabled by de‐
505 fault, as such ancillary data provides an easy way of determin‐
506 ing the association and stream over which the message is re‐
507 ceived. (An alternative way is to get the association ID from
508 FromIP and FromPort using socket option sctp_get_peer_addr_info,
509 but this does still not produce the stream number).
510 AncData may also contain ancillary data from the socket op‐
512 tions recvtos, recvtclass or recvttl, if that is supported by
513 the platform for the socket.
514 The Data received can be a binary() or a list() of bytes (inte‐
516 gers in the range 0 through 255) depending on the socket mode,
517 or an SCTP event.
518 Possible SCTP events:
520 * #sctp_sndrcvinfo{}
522 * #sctp_assoc_change{}
524 *
526 #sctp_paddr_change{
529 addr = {ip_address(),port()},
530 state = atom(),
531 error = integer(),
532 assoc_id = assoc_id()
533 }
534 Indicates change of the status of the IP address of the peer
536 specified by addr within association assoc_id. Possible val‐
537 ues of state (mostly self-explanatory) include:
538 addr_unreachable:
540 addr_available:
543 addr_removed:
546 addr_added:
549 addr_made_prim:
552 addr_confirmed:
555 In case of an error (for example, addr_unreachable), field
558 error provides more diagnostics. In such cases, event
559 #sctp_paddr_change{} is automatically converted into an er‐
560 ror term returned by recv. The error field value can be con‐
561 verted into a string using error_string/1.
562 *
564 #sctp_send_failed{
567 flags = true | false,
568 error = integer(),
569 info = #sctp_sndrcvinfo{},
570 assoc_id = assoc_id()
571 data = binary()
572 }
573 The sender can receive this event if a send operation fails.
575 flags:
577 A Boolean specifying if the data has been transmitted over
578 the wire.
579 error:
581 Provides extended diagnostics, use error_string/1.
582 info:
584 The original #sctp_sndrcvinfo{} record used in the failed
585 send/*.
586 data:
588 The whole original data chunk attempted to be sent.
589 In the current implementation of the Erlang/SCTP binding,
591 this event is internally converted into an error term re‐
592 turned by recv/*.
593 *
595 #sctp_adaptation_event{
598 adaptation_ind = integer(),
599 assoc_id = assoc_id()
600 }
601 Delivered when a peer sends an adaptation layer indication
603 parameter (configured through option sctp_adaptation_layer).
604 Notice that with the current implementation of the Er‐
605 lang/SCTP binding, this event is disabled by default.
606 *
608 #sctp_pdapi_event{
611 indication = sctp_partial_delivery_aborted,
612 assoc_id = assoc_id()
613 }
614 A partial delivery failure. In the current implementation of
616 the Erlang/SCTP binding, this event is internally converted
617 into an error term returned by recv/*.
618 send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
620 Types:
622 Socket = sctp_socket()
624 SndRcvInfo = #sctp_sndrcvinfo{}
625 Data = binary() | iolist()
626 Reason = term()
627 Sends the Data message with all sending parameters from a
629 #sctp_sndrcvinfo{} record. This way, the user can specify the
630 PPID (passed to the remote end) and context (passed to the local
631 SCTP layer), which can be used, for example, for error identifi‐
632 cation. However, such a fine level of user control is rarely re‐
633 quired. The function send/4 is sufficient for most applications.
634 send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
636 Types:
638 Socket = sctp_socket()
640 Assoc = #sctp_assoc_change{} | assoc_id()
641 Stream = integer()
642 Data = binary() | iolist()
643 Reason = term()
644 Sends a Data message over an existing association and specified
646 stream.
647
649 The set of admissible SCTP socket options is by construction orthogonal
650 to the sets of TCP, UDP, and generic inet options. Only options listed
651 here are allowed for SCTP sockets. Options can be set on the socket us‐
652 ing open/1,2 or inet:setopts/2, retrieved using inet:getopts/2. Options
653 can be changed when calling connect/4,5.
654 {mode, list|binary} or just list or binary:
656 Determines the type of data returned from recv/1,2.
657 {active, true|false|once|N}:
659 * If false (passive mode, the default), the caller must do an ex‐
662 plicit recv call to retrieve the available data from the socket.
663 * If true|once|N (active modes) received data or events are sent to
665 the owning process. See open/0..2 for the message format.
666 * If true (full active mode) there is no flow control.
668 Note:
670 Note that this can cause the message queue to overflow causing for
671 example the virtual machine to run out of memory and crash.
672 * If once, only one message is automatically placed in the message
675 queue, and after that the mode is automatically reset to passive.
676 This provides flow control and the possibility for the receiver
677 to listen for its incoming SCTP data interleaved with other in‐
678 ter-process messages.
679 * If active is specified as an integer N in the range -32768 to
681 32767 (inclusive), that number is added to the socket's counting
682 of data messages to be delivered to the controlling process. If
683 the result of the addition is negative, the count is set to 0.
684 Once the count reaches 0, either through the delivery of messages
685 or by being explicitly set with inet:setopts/2, the socket mode
686 is automatically reset to passive ({active, false}). When a
687 socket in this active mode transitions to passive mode, the mes‐
688 sage {sctp_passive, Socket} is sent to the controlling process to
689 notify it that if it wants to receive more data messages from the
690 socket, it must call inet:setopts/2 to set the socket back into
691 an active mode.
692 {tos, integer()}:
694 Sets the Type-Of-Service field on the IP datagrams that are sent,
695 to the specified value. This effectively determines a prioritiza‐
696 tion policy for the outbound packets. The acceptable values are
697 system-dependent.
698 {priority, integer()}:
700 A protocol-independent equivalent of tos above. Setting priority
701 implies setting tos as well.
702 {dontroute, true|false}:
704 Defaults to false. If true, the kernel does not send packets
705 through any gateway, only sends them to directly connected hosts.
706 {reuseaddr, true|false}:
708 Defaults to false. If true, the local binding address {IP,Port} of
709 the socket can be reused immediately. No waiting in state
710 CLOSE_WAIT is performed (can be required for high-throughput
711 servers).
712 {sndbuf, integer()}:
714 The size, in bytes, of the OS kernel send buffer for this socket.
715 Sending errors would occur for datagrams larger than val(sndbuf).
716 Setting this option also adjusts the size of the driver buffer (see
717 buffer above).
718 {recbuf, integer()}:
720 The size, in bytes, of the OS kernel receive buffer for this
721 socket. Sending errors would occur for datagrams larger than
722 val(recbuf). Setting this option also adjusts the size of the
723 driver buffer (see buffer above).
724 {sctp_module, module()}:
726 Overrides which callback module is used. Defaults to inet_sctp for
727 IPv4 and inet6_sctp for IPv6.
728 {sctp_rtoinfo, #sctp_rtoinfo{}}:
730 #sctp_rtoinfo{
733 assoc_id = assoc_id(),
734 initial = integer(),
735 max = integer(),
736 min = integer()
737 }
738 Determines retransmission time-out parameters, in milliseconds, for
740 the association(s) specified by assoc_id.
741 assoc_id = 0 (default) indicates the whole endpoint. See RFC 2960
743 and Sockets API Extensions for SCTP for the exact semantics of the
744 field values.
745 {sctp_associnfo, #sctp_assocparams{}}:
747 #sctp_assocparams{
750 assoc_id = assoc_id(),
751 asocmaxrxt = integer(),
752 number_peer_destinations = integer(),
753 peer_rwnd = integer(),
754 local_rwnd = integer(),
755 cookie_life = integer()
756 }
757 Determines association parameters for the association(s) specified
759 by assoc_id.
760 assoc_id = 0 (default) indicates the whole endpoint. See Sockets
762 API Extensions for SCTP for the discussion of their semantics.
763 Rarely used.
764 {sctp_initmsg, #sctp_initmsg{}}:
766 #sctp_initmsg{
769 num_ostreams = integer(),
770 max_instreams = integer(),
771 max_attempts = integer(),
772 max_init_timeo = integer()
773 }
774 Determines the default parameters that this socket tries to negoti‐
776 ate with its peer while establishing an association with it. Is to
777 be set after open/* but before the first connect/*. #sctp_initmsg{}
778 can also be used as ancillary data with the first call of send/* to
779 a new peer (when a new association is created).
780 num_ostreams:
782 Number of outbound streams
783 max_instreams:
785 Maximum number of inbound streams
786 max_attempts:
788 Maximum retransmissions while establishing an association
789 max_init_timeo:
791 Time-out, in milliseconds, for establishing an association
792 {sctp_autoclose, integer() >= 0}:
794 Determines the time, in seconds, after which an idle association is
795 automatically closed. 0 means that the association is never auto‐
796 matically closed.
797 {sctp_nodelay, true|false}:
799 Turns on|off the Nagle algorithm for merging small packets into
800 larger ones. This improves throughput at the expense of latency.
801 {sctp_disable_fragments, true|false}:
803 If true, induces an error on an attempt to send a message larger
804 than the current PMTU size (which would require fragmentation/re‐
805 assembling). Notice that message fragmentation does not affect the
806 logical atomicity of its delivery; this option is provided for per‐
807 formance reasons only.
808 {sctp_i_want_mapped_v4_addr, true|false}:
810 Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
811 the socket address family is AF_INET6).
812 {sctp_maxseg, integer()}:
814 Determines the maximum chunk size if message fragmentation is used.
815 If 0, the chunk size is limited by the Path MTU only.
816 {sctp_primary_addr, #sctp_prim{}}:
818 #sctp_prim{
821 assoc_id = assoc_id(),
822 addr = {IP, Port}
823 }
824 IP = ip_address()
825 Port = port_number()
826 For the association specified by assoc_id, {IP,Port} must be one of
828 the peer addresses. This option determines that the specified ad‐
829 dress is treated by the local SCTP stack as the primary address of
830 the peer.
831 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
833 #sctp_setpeerprim{
836 assoc_id = assoc_id(),
837 addr = {IP, Port}
838 }
839 IP = ip_address()
840 Port = port_number()
841 When set, informs the peer to use {IP, Port} as the primary address
843 of the local endpoint for the association specified by assoc_id.
844 {sctp_adaptation_layer, #sctp_setadaptation{}}:
846 #sctp_setadaptation{
849 adaptation_ind = integer()
850 }
851 When set, requests that the local endpoint uses the value specified
853 by adaptation_ind as the Adaptation Indication parameter for estab‐
854 lishing new associations. For details, see RFC 2960 and Sockets API
855 Extenstions for SCTP.
856 {sctp_peer_addr_params, #sctp_paddrparams{}}:
858 #sctp_paddrparams{
861 assoc_id = assoc_id(),
862 address = {IP, Port},
863 hbinterval = integer(),
864 pathmaxrxt = integer(),
865 pathmtu = integer(),
866 sackdelay = integer(),
867 flags = list()
868 }
869 IP = ip_address()
870 Port = port_number()
871 Determines various per-address parameters for the association spec‐
873 ified by assoc_id and the peer address address (the SCTP protocol
874 supports multi-homing, so more than one address can correspond to a
875 specified association).
876 hbinterval:
878 Heartbeat interval, in milliseconds
879 pathmaxrxt:
881 Maximum number of retransmissions before this address is consid‐
882 ered unreachable (and an alternative address is selected)
883 pathmtu:
885 Fixed Path MTU, if automatic discovery is disabled (see flags be‐
886 low)
887 sackdelay:
889 Delay, in milliseconds, for SAC messages (if the delay is en‐
890 abled, see flags below)
891 flags:
893 The following flags are available:
894 hb_enable:
896 Enables heartbeat
897 hb_disable:
899 Disables heartbeat
900 hb_demand:
902 Initiates heartbeat immediately
903 pmtud_enable:
905 Enables automatic Path MTU discovery
906 pmtud_disable:
908 Disables automatic Path MTU discovery
909 sackdelay_enable:
911 Enables SAC delay
912 sackdelay_disable:
914 Disables SAC delay
915 {sctp_default_send_param, #sctp_sndrcvinfo{}}:
917 #sctp_sndrcvinfo{
920 stream = integer(),
921 ssn = integer(),
922 flags = list(),
923 ppid = integer(),
924 context = integer(),
925 timetolive = integer(),
926 tsn = integer(),
927 cumtsn = integer(),
928 assoc_id = assoc_id()
929 }
930 #sctp_sndrcvinfo{} is used both in this socket option, and as an‐
932 cillary data while sending or receiving SCTP messages. When set as
933 an option, it provides default values for subsequent send calls on
934 the association specified by assoc_id.
935 assoc_id = 0 (default) indicates the whole endpoint.
937 The following fields typically must be specified by the sender:
939 sinfo_stream:
941 Stream number (0-base) within the association to send the mes‐
942 sages through;
943 sinfo_flags:
945 The following flags are recognised:
946 unordered:
948 The message is to be sent unordered
949 addr_over:
951 The address specified in send overwrites the primary peer ad‐
952 dress
953 abort:
955 Aborts the current association without flushing any unsent data
956 eof:
958 Gracefully shuts down the current association, with flushing of
959 unsent data
960 Other fields are rarely used. For complete information, see RFC
962 2960 and Sockets API Extensions for SCTP.
963 {sctp_events, #sctp_event_subscribe{}}:
965 #sctp_event_subscribe{
968 data_io_event = true | false,
969 association_event = true | false,
970 address_event = true | false,
971 send_failure_event = true | false,
972 peer_error_event = true | false,
973 shutdown_event = true | false,
974 partial_delivery_event = true | false,
975 adaptation_layer_event = true | false
976 }
977 This option determines which SCTP Events are to be received
979 (through recv/*) along with the data. The only exception is
980 data_io_event, which enables or disables receiving of #sctp_sndrcv‐
981 info{} ancillary data, not events. By default, all flags except
982 adaptation_layer_event are enabled, although sctp_data_io_event and
983 association_event are used by the driver itself and not exported to
984 the user level.
985 {sctp_delayed_ack_time, #sctp_assoc_value{}}:
987 #sctp_assoc_value{
990 assoc_id = assoc_id(),
991 assoc_value = integer()
992 }
993 Rarely used. Determines the ACK time (specified by assoc_value, in
995 milliseconds) for the specified association or the whole endpoint
996 if assoc_value = 0 (default).
997 {sctp_status, #sctp_status{}}:
999 #sctp_status{
1002 assoc_id = assoc_id(),
1003 state = atom(),
1004 rwnd = integer(),
1005 unackdata = integer(),
1006 penddata = integer(),
1007 instrms = integer(),
1008 outstrms = integer(),
1009 fragmentation_point = integer(),
1010 primary = #sctp_paddrinfo{}
1011 }
1012 This option is read-only. It determines the status of the SCTP as‐
1014 sociation specified by assoc_id. The following are the possible
1015 values of state (the state designations are mostly self-explana‐
1016 tory):
1017 sctp_state_empty:
1019 Default. Means that no other state is active.
1020 sctp_state_closed:
1022 sctp_state_cookie_wait:
1025 sctp_state_cookie_echoed:
1028 sctp_state_established:
1031 sctp_state_shutdown_pending:
1034 sctp_state_shutdown_sent:
1037 sctp_state_shutdown_received:
1040 sctp_state_shutdown_ack_sent:
1043 Semantics of the other fields:
1046 sstat_rwnd:
1048 Current receiver window size of the association
1049 sstat_unackdata:
1051 Number of unacked data chunks
1052 sstat_penddata:
1054 Number of data chunks pending receipt
1055 sstat_instrms:
1057 Number of inbound streams
1058 sstat_outstrms:
1060 Number of outbound streams
1061 sstat_fragmentation_point:
1063 Message size at which SCTP fragmentation occurs
1064 sstat_primary:
1066 Information on the current primary peer address (see below for
1067 the format of #sctp_paddrinfo{})
1068 {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1070 #sctp_paddrinfo{
1073 assoc_id = assoc_id(),
1074 address = {IP, Port},
1075 state = inactive | active | unconfirmed,
1076 cwnd = integer(),
1077 srtt = integer(),
1078 rto = integer(),
1079 mtu = integer()
1080 }
1081 IP = ip_address()
1082 Port = port_number()
1083 This option is read-only. It determines the parameters specific to
1085 the peer address specified by address within the association speci‐
1086 fied by assoc_id. Field address fmust be set by the caller; all
1087 other fields are filled in on return. If assoc_id = 0 (default),
1088 the address is automatically translated into the corresponding as‐
1089 sociation ID. This option is rarely used. For the semantics of all
1090 fields, see RFC 2960 and Sockets API Extensions for SCTP.
1091
1093 Example of an Erlang SCTP server that receives SCTP messages and prints
1094 them on the standard output:
1095 -module(sctp_server).
1097 -export([server/0,server/1,server/2]).
1099 -include_lib("kernel/include/inet.hrl").
1100 -include_lib("kernel/include/inet_sctp.hrl").
1101 server() ->
1103 server(any, 2006).
1104 server([Host,Port]) when is_list(Host), is_list(Port) ->
1106 {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1107 io:format("~w -> ~w~n", [Host, IP]),
1108 server([IP, list_to_integer(Port)]).
1109 server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1111 is_integer(Port) ->
1112 {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1113 io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1114 ok = gen_sctp:listen(S, true),
1115 server_loop(S).
1116 server_loop(S) ->
1118 case gen_sctp:recv(S) of
1119 {error, Error} ->
1120 io:format("SCTP RECV ERROR: ~p~n", [Error]);
1121 Data ->
1122 io:format("Received: ~p~n", [Data])
1123 end,
1124 server_loop(S).
1125 Example of an Erlang SCTP client interacting with the above server. No‐
1127 tice that in this example the client creates an association with the
1128 server with 5 outbound streams. Therefore, sending of "Test 0" over
1129 stream 0 succeeds, but sending of "Test 5" over stream 5 fails. The
1130 client then aborts the association, which results in that the corre‐
1131 sponding event is received on the server side.
1132 -module(sctp_client).
1134 -export([client/0, client/1, client/2]).
1136 -include_lib("kernel/include/inet.hrl").
1137 -include_lib("kernel/include/inet_sctp.hrl").
1138 client() ->
1140 client([localhost]).
1141 client([Host]) ->
1143 client(Host, 2006);
1144 client([Host, Port]) when is_list(Host), is_list(Port) ->
1146 client(Host,list_to_integer(Port)),
1147 init:stop().
1148 client(Host, Port) when is_integer(Port) ->
1150 {ok,S} = gen_sctp:open(),
1151 {ok,Assoc} = gen_sctp:connect
1152 (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1153 io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1154 io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1156 io:nl(),
1157 timer:sleep(10000),
1158 io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1159 io:nl(),
1160 timer:sleep(10000),
1161 io:write(gen_sctp:abort(S, Assoc)),
1162 io:nl(),
1163 timer:sleep(1000),
1165 gen_sctp:close(S).
1166 A simple Erlang SCTP client that uses the connect_init API:
1168 -module(ex3).
1170 -export([client/4]).
1172 -include_lib("kernel/include/inet.hrl").
1173 -include_lib("kernel/include/inet_sctp.hrl").
1174 client(Peer1, Port1, Peer2, Port2)
1176 when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1177 {ok,S} = gen_sctp:open(),
1178 SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1179 ActiveOpt = {active, true},
1180 Opts = [SctpInitMsgOpt, ActiveOpt],
1181 ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1182 ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1183 io:format("Connections initiated~n", []),
1184 client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1185 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1187 receive
1188 {sctp, S, Peer1, Port1, {_Anc, SAC}}
1189 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1190 io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1191 [SAC#sctp_assoc_change.state,
1192 SAC#sctp_assoc_change.assoc_id]),
1193 client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1194 Peer2, Port2, AssocId2);
1195 {sctp, S, Peer2, Port2, {_Anc, SAC}}
1197 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1198 io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1199 [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1200 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1201 SAC#sctp_assoc_change.assoc_id);
1202 {sctp, S, Peer1, Port1, Data} ->
1204 io:format("Association 1: received ~p~n", [Data]),
1205 client_loop(S, Peer1, Port1, AssocId1,
1206 Peer2, Port2, AssocId2);
1207 {sctp, S, Peer2, Port2, Data} ->
1209 io:format("Association 2: received ~p~n", [Data]),
1210 client_loop(S, Peer1, Port1, AssocId1,
1211 Peer2, Port2, AssocId2);
1212 Other ->
1214 io:format("Other ~p~n", [Other]),
1215 client_loop(S, Peer1, Port1, AssocId1,
1216 Peer2, Port2, AssocId2)
1217 after 5000 ->
1219 ok
1220 end.
1221
1223 gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control Transmission
1224 Protocol), Sockets API Extensions for SCTP
1225Ericsson AB kernel 8.3.2 gen_sctp(3)