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 Exported data types
46 assoc_id()
47 An opaque term returned in, for example, #sctp_paddr_change{},
49 which identifies an association for an SCTP socket. The term is
50 opaque except for the special value 0, which has a meaning such
51 as "the whole endpoint" or "all future associations".
52 option() = elementary_option() | record_option()
54 One of the SCTP Socket Options used to set an option.
56 option_name() =
58 elementary_option_name() | record_option() | ro_option()
59 An option name or one of the SCTP Socket Options used to get an
61 option.
62 option_value() =
64 elementary_option() | record_option() | ro_option()
65 One of the SCTP Socket Options as returned when getting an op‐
67 tion.
68 sctp_socket()
70 Socket identifier returned from open/*.
72
74 Internal data types
75 elementary_option() =
76 {active, true | false | once | -32768..32767} |
77 {buffer, integer() >= 0} |
78 {debug, boolean()} |
79 {dontroute, boolean()} |
80 {exclusiveaddruse, boolean()} |
81 {high_msgq_watermark, integer() >= 1} |
82 {linger, {boolean(), integer() >= 0}} |
83 {low_msgq_watermark, integer() >= 1} |
84 {mode, list | binary} |
85 list | binary |
86 {priority, integer() >= 0} |
87 {recbuf, integer() >= 0} |
88 {reuseaddr, boolean()} |
89 {reuseport, boolean()} |
90 {reuseport_lb, boolean()} |
91 {ipv6_v6only, boolean()} |
92 {sndbuf, integer() >= 0} |
93 {sctp_autoclose, integer() >= 0} |
94 {sctp_disable_fragments, boolean()} |
95 {sctp_i_want_mapped_v4_addr, boolean()} |
96 {sctp_maxseg, integer() >= 0} |
97 {sctp_nodelay, boolean()} |
98 {tos, integer() >= 0} |
99 {tclass, integer() >= 0} |
100 {ttl, integer() >= 0} |
101 {recvtos, boolean()} |
102 {recvtclass, boolean()} |
103 {recvttl, boolean()}
104 elementary_option_name() =
106 active | buffer | debug | dontroute | exclusiveaddruse |
107 high_msgq_watermark | linger | low_msgq_watermark | mode |
108 priority | recbuf | reuseaddr | reuseport | reuseport_lb |
109 ipv6_v6only | sctp_autoclose | sctp_disable_fragments |
110 sctp_i_want_mapped_v4_addr | sctp_maxseg | sctp_nodelay |
111 sndbuf | tos | tclass | ttl | recvtos | recvtclass | recvttl
112 record_option() =
114 {sctp_adaptation_layer, #sctp_setadaptation{}} |
115 {sctp_associnfo, #sctp_assocparams{}} |
116 {sctp_default_send_param, #sctp_sndrcvinfo{}} |
117 {sctp_delayed_ack_time, #sctp_assoc_value{}} |
118 {sctp_events, #sctp_event_subscribe{}} |
119 {sctp_initmsg, #sctp_initmsg{}} |
120 {sctp_peer_addr_params, #sctp_paddrparams{}} |
121 {sctp_primary_addr, #sctp_prim{}} |
122 {sctp_rtoinfo, #sctp_rtoinfo{}} |
123 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}
124 ro_option() =
126 {sctp_get_peer_addr_info, #sctp_paddrinfo{}} |
127 {sctp_status, #sctp_status{}}
128
130 abort(Socket, Assoc) -> ok | {error, inet:posix()}
131 Types:
133 Socket = sctp_socket()
135 Assoc = #sctp_assoc_change{}
136 Abnormally terminates the association specified by Assoc, with‐
138 out flushing of unsent data. The socket itself remains open.
139 Other associations opened on this socket are still valid, and
140 the socket can be used in new associations.
141 close(Socket) -> ok | {error, inet:posix()}
143 Types:
145 Socket = sctp_socket()
147 Closes the socket and all associations on it. The unsent data is
149 flushed as in eof/2. The close/1 call is blocking or otherwise
150 depending of the value of the linger socket option. If close
151 does not linger or linger time-out expires, the call returns and
152 the data is flushed in the background.
153 connect(Socket, SockAddr, Opts) ->
155 {ok, #sctp_assoc_change{state = comm_up}} |
156 {error, #sctp_assoc_change{state = cant_assoc}} |
157 {error, inet:posix()}
158 Types:
160 Socket = sctp_socket()
162 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
163 Opts = [Opt :: option()]
164 Same as connect(Socket, SockAddr, Opts, infinity).
166 connect(Socket, SockAddr, Opts, Timeout) ->
168 {ok, #sctp_assoc_change{state = comm_up}} |
169 {error, #sctp_assoc_change{state = cant_assoc}} |
170 {error, inet:posix()}
171 Types:
173 Socket = sctp_socket()
175 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
176 Opts = [Opt :: option()]
177 Timeout = timeout()
178 This is conceptually the same as connect/5, only with the dif‐
180 ference that we use a socket address, socket:sockaddr_in() or
181 socket:sockaddr_in6() instead of an address (inet:ip_address()
182 or inet:hostname()) and port-number.
183 connect(Socket, Addr, Port, Opts) ->
185 {ok, #sctp_assoc_change{state = comm_up}} |
186 {error, #sctp_assoc_change{state = cant_assoc}} |
187 {error, inet:posix()}
188 Types:
190 Socket = sctp_socket()
192 Addr = inet:ip_address() | inet:hostname()
193 Port = inet:port_number()
194 Opts = [Opt :: option()]
195 Same as connect(Socket, Addr, Port, Opts, infinity).
197 connect(Socket, Addr, Port, Opts, Timeout) ->
199 {ok, #sctp_assoc_change{state = comm_up}} |
200 {error, #sctp_assoc_change{state = cant_assoc}} |
201 {error, inet:posix()}
202 Types:
204 Socket = sctp_socket()
206 Addr = inet:ip_address() | inet:hostname()
207 Port = inet:port_number()
208 Opts = [Opt :: option()]
209 Timeout = timeout()
210 Establishes a new association for socket Socket, with the peer
212 (SCTP server socket) specified by Addr and Port. Timeout, is ex‐
213 pressed in milliseconds. A socket can be associated with multi‐
214 ple peers.
215 Warning:
217 Using a value of Timeout less than the maximum time taken by the
218 OS to establish an association (around 4.5 minutes if the de‐
219 fault values from RFC 4960 are used), can result in inconsistent
220 or incorrect return values. This is especially relevant for as‐
221 sociations sharing the same Socket (that is, source address and
222 port), as the controlling process blocks until connect/* re‐
223 turns. connect_init/* provides an alternative without this limi‐
224 tation.
225 The result of connect/* is an #sctp_assoc_change{} event that
228 contains, in particular, the new Association ID:
229 #sctp_assoc_change{
231 state = atom(),
232 error = integer(),
233 outbound_streams = integer(),
234 inbound_streams = integer(),
235 assoc_id = assoc_id()
236 }
237 The number of outbound and inbound streams can be set by giving
239 an sctp_initmsg option to connect as in:
240 connect(Socket, Ip, Port>,
242 [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
243 max_instreams=MaxInStreams}}])
244 All options Opt are set on the socket before the association is
246 attempted. If an option record has undefined field values, the
247 options record is first read from the socket for those values.
248 In effect, Opt option records only define field values to change
249 before connecting.
250 The returned outbound_streams and inbound_streams are the stream
252 numbers on the socket. These can be different from the requested
253 values (OutStreams and MaxInStreams, respectively) if the peer
254 requires lower values.
255 state can have the following values:
257 comm_up:
259 Association is successfully established. This indicates a
260 successful completion of connect.
261 cant_assoc:
263 The association cannot be established (connect/* failure).
264 Other states do not normally occur in the output from connect/*.
266 Rather, they can occur in #sctp_assoc_change{} events received
267 instead of data in recv/* calls. All of them indicate losing the
268 association because of various error conditions, and are listed
269 here for the sake of completeness:
270 comm_lost:
272 restart:
275 shutdown_comp:
278 Field error can provide more detailed diagnostics. The error
281 field value can be converted into a string using error_string/1.
282 connect_init(Socket, SockAddr, Opts) -> ok | {error, inet:posix()}
284 Types:
286 Socket = sctp_socket()
288 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
289 Opts = [option()]
290 Same as connect_init(Socket, SockAddr, Opts, infinity).
292 connect_init(Socket, SockAddr, Opts, Timeout) ->
294 ok | {error, inet:posix()}
295 Types:
297 Socket = sctp_socket()
299 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
300 Opts = [option()]
301 Timeout = timeout()
302 This is conceptually the same as connect_init/5, only with the
304 difference that we use a socket address, socket:sockaddr_in() or
305 socket:sockaddr_in6() instead of an address (inet:ip_address()
306 or inet:hostname()) and port-number.
307 connect_init(Socket, Addr, Port, Opts) ->
309 ok | {error, inet:posix()}
310 Types:
312 Socket = sctp_socket()
314 Addr = inet:ip_address() | inet:hostname()
315 Port = inet:port_number()
316 Opts = [option()]
317 Same as connect_init(Socket, Addr, Port, Opts, infinity).
319 connect_init(Socket, Addr, Port, Opts, Timeout) ->
321 ok | {error, inet:posix()}
322 Types:
324 Socket = sctp_socket()
326 Addr = inet:ip_address() | inet:hostname()
327 Port = inet:port_number()
328 Opts = [option()]
329 Timeout = timeout()
330 Initiates a new association for socket Socket, with the peer
332 (SCTP server socket) specified by Addr and Port.
333 The fundamental difference between this API and connect/* is
335 that the return value is that of the underlying OS connect(2)
336 system call. If ok is returned, the result of the association
337 establishment is received by the calling process as an #sctp_as‐
338 soc_change{} event. The calling process must be prepared to re‐
339 ceive this, or poll for it using recv/*, depending on the value
340 of the active option.
341 The parameters are as described in connect/*, except the Timeout
343 value.
344 The timer associated with Timeout only supervises IP resolution
346 of Addr.
347 connectx_init(Socket, SockAddrs, Opts) ->
349 {ok, assoc_id()} | {error, inet:posix()}
350 Types:
352 Socket = sctp_socket()
354 SockAddrs =
355 [{inet:ip_address(), inet:port_number()} |
356 inet:family_address() |
357 socket:sockaddr_in() |
358 socket:sockaddr_in6()]
359 Opts = [option()]
360 Similar to connectx_init/5 except using socket addresses, and
362 not having a Timeout. Since the addresses do not need lookup and
363 the connect is non-blocking this call returns immediately.
364 The value of each socket address port must be the same or zero.
366 At least one socket address must have a non-zero port
367 connectx_init(Socket, Addrs, Port, Opts) ->
369 {ok, assoc_id()} | {error, inet:posix()}
370 Types:
372 Socket = sctp_socket()
374 Addrs = [inet:ip_address() | inet:hostname()]
375 Port = inet:port_number() | atom()
376 Opts = [option()]
377 Same as connectx_init(Socket, Addrs, Port, Opts, infinity).
379 connectx_init(Socket, Addrs, Port, Opts, Timeout) ->
381 {ok, assoc_id()} | {error, inet:posix()}
382 Types:
384 Socket = sctp_socket()
386 Addrs = [inet:ip_address() | inet:hostname()]
387 Port = inet:port_number() | atom()
388 Opts = [option()]
389 Timeout = timeout()
390 Initiates a new association for socket Socket, with the peer
392 (SCTP server socket) specified by Addrs and Port.
393 This API is similar to connect_init/* except the underlying OS
395 sctp_connectx(3) system call is used.
396 If successful, the association ID is returned which will be re‐
398 ceived in a subsequent #sctp_assoc_change{} event.
399 The parameters are as described in connect_init/5
401 NOTE: This API allows the OS to use all Addrs when establishing
403 an association, but does not guarantee it will. Therefore, if
404 the connection fails the user may want to rotate the order of
405 addresses for a subsequent call.
406 controlling_process(Socket, Pid) -> ok | {error, Reason}
408 Types:
410 Socket = sctp_socket()
412 Pid = pid()
413 Reason = closed | not_owner | badarg | inet:posix()
414 Assigns a new controlling process Pid to Socket. Same implemen‐
416 tation as gen_udp:controlling_process/2.
417 eof(Socket, Assoc) -> ok | {error, Reason}
419 Types:
421 Socket = sctp_socket()
423 Assoc = #sctp_assoc_change{}
424 Reason = term()
425 Gracefully terminates the association specified by Assoc, with
427 flushing of all unsent data. The socket itself remains open.
428 Other associations opened on this socket are still valid. The
429 socket can be used in new associations.
430 error_string(ErrorNumber) -> ok | string() | unknown_error
432 Types:
434 ErrorNumber = integer()
436 Translates an SCTP error number from, for example, #sctp_re‐
438 mote_error{} or #sctp_send_failed{} into an explanatory string,
439 or one of the atoms ok for no error or undefined for an unrecog‐
440 nized error.
441 listen(Socket, IsServer) -> ok | {error, Reason}
443 listen(Socket, Backlog) -> ok | {error, Reason}
445 Types:
447 Socket = sctp_socket()
449 Backlog = integer()
450 Reason = term()
451 Sets up a socket to listen on the IP address and port number it
453 is bound to.
454 For type seqpacket, sockets (the default) IsServer must be true
456 or false. In contrast to TCP, there is no listening queue length
457 in SCTP. If IsServer is true, the socket accepts new associa‐
458 tions, that is, it becomes an SCTP server socket.
459 For type stream, sockets Backlog define the backlog queue length
461 just like in TCP.
462 open() -> {ok, Socket} | {error, inet:posix()}
464 open(Port) -> {ok, Socket} | {error, inet:posix()}
466 open(Opts) -> {ok, Socket} | {error, inet:posix()}
468 open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
470 Types:
472 Opts = [Opt]
474 Opt =
475 {ifaddr, IP | SockAddr} |
476 {ip, IP} |
477 {port, Port} |
478 inet:address_family() |
479 {type, SockType} |
480 {netns, file:filename_all()} |
481 {bind_to_device, binary()} |
482 option()
483 IP = inet:ip_address() | any | loopback
484 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
485 Port = inet:port_number()
486 SockType = seqpacket | stream
487 Socket = sctp_socket()
488 Creates an SCTP socket and binds it to the local addresses spec‐
490 ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
491 feature is called SCTP multi-homing). The default IP and Port
492 are any and 0, meaning bind to all local addresses on any free
493 port.
494 It is also possible to use {ifaddr, SockAddr}, in which case it
496 takes precedence over the ip and port options. These options can
497 however be used to update the address and port of ifaddr (if
498 they occur after ifaddr in the options list), although this is
499 not recommended.
500 Other options:
502 inet6:
504 Sets up the socket for IPv6.
505 inet:
507 Sets up the socket for IPv4. This is the default.
508 A default set of socket options is used. In particular, the
510 socket is opened in binary and passive mode, with SockType seq‐
511 packet, and with reasonably large kernel and driver buffers.
512 If the socket is in passive mode data can be received through
514 the recv/1,2 calls.
515 If the socket is in active mode data received data is delivered
517 to the controlling process as messages:
518 {sctp, Socket, FromIP, FromPort, {AncData, Data}}
520 See recv/1,2 for a description of the message fields.
523 Note:
525 This message format unfortunately differs slightly from the
526 gen_udp message format with ancillary data, and from the
527 recv/1,2 return tuple format.
528 peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
531 Types:
533 Socket = sctp_socket()
535 Assoc = #sctp_assoc_change{} | assoc_id()
536 NewSocket = sctp_socket()
537 Reason = term()
538 Branches off an existing association Assoc in a socket Socket of
540 type seqpacket (one-to-many style) into a new socket NewSocket
541 of type stream (one-to-one style).
542 The existing association argument Assoc can be either a
544 #sctp_assoc_change{} record as returned from, for example,
545 recv/*, connect/*, or from a listening socket in active mode. It
546 can also be just the field assoc_id integer from such a record.
547 recv(Socket) ->
549 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
550 recv(Socket, Timeout) ->
552 {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
553 Types:
555 Socket = sctp_socket()
557 Timeout = timeout()
558 FromIP = inet:ip_address()
559 FromPort = inet:port_number()
560 AncData = [#sctp_sndrcvinfo{} | inet:ancillary_data()]
561 Data =
562 binary() |
563 string() |
564 #sctp_sndrcvinfo{} |
565 #sctp_assoc_change{} |
566 #sctp_paddr_change{} |
567 #sctp_adaptation_event{}
568 Reason =
569 inet:posix() |
570 #sctp_send_failed{} |
571 #sctp_paddr_change{} |
572 #sctp_pdapi_event{} |
573 #sctp_remote_error{} |
574 #sctp_shutdown_event{}
575 Receives the Data message from any association of the socket. If
577 the receive times out, {error,timeout} is returned. The default
578 time-out is infinity. FromIP and FromPort indicate the address
579 of the sender.
580 AncData is a list of ancillary data items that can be received
582 along with the main Data. This list can be empty, or contain a
583 single #sctp_sndrcvinfo{} record if receiving of such ancillary
584 data is enabled (see option sctp_events). It is enabled by de‐
585 fault, as such ancillary data provides an easy way of determin‐
586 ing the association and stream over which the message is re‐
587 ceived. (An alternative way is to get the association ID from
588 FromIP and FromPort using socket option sctp_get_peer_addr_info,
589 but this does still not produce the stream number).
590 AncData may also contain ancillary data from the socket op‐
592 tions recvtos, recvtclass or recvttl, if that is supported by
593 the platform for the socket.
594 The Data received can be a binary() or a list() of bytes (inte‐
596 gers in the range 0 through 255) depending on the socket mode,
597 or an SCTP event.
598 Possible SCTP events:
600 * #sctp_sndrcvinfo{}
602 * #sctp_assoc_change{}
604 *
606 #sctp_paddr_change{
609 addr = {ip_address(),port()},
610 state = atom(),
611 error = integer(),
612 assoc_id = assoc_id()
613 }
614 Indicates change of the status of the IP address of the peer
616 specified by addr within association assoc_id. Possible val‐
617 ues of state (mostly self-explanatory) include:
618 addr_unreachable:
620 addr_available:
623 addr_removed:
626 addr_added:
629 addr_made_prim:
632 addr_confirmed:
635 In case of an error (for example, addr_unreachable), field
638 error provides more diagnostics. In such cases, event
639 #sctp_paddr_change{} is automatically converted into an er‐
640 ror term returned by recv. The error field value can be con‐
641 verted into a string using error_string/1.
642 *
644 #sctp_send_failed{
647 flags = true | false,
648 error = integer(),
649 info = #sctp_sndrcvinfo{},
650 assoc_id = assoc_id()
651 data = binary()
652 }
653 The sender can receive this event if a send operation fails.
655 flags:
657 A Boolean specifying if the data has been transmitted over
658 the wire.
659 error:
661 Provides extended diagnostics, use error_string/1.
662 info:
664 The original #sctp_sndrcvinfo{} record used in the failed
665 send/*.
666 data:
668 The whole original data chunk attempted to be sent.
669 In the current implementation of the Erlang/SCTP binding,
671 this event is internally converted into an error term re‐
672 turned by recv/*.
673 *
675 #sctp_adaptation_event{
678 adaptation_ind = integer(),
679 assoc_id = assoc_id()
680 }
681 Delivered when a peer sends an adaptation layer indication
683 parameter (configured through option sctp_adaptation_layer).
684 Notice that with the current implementation of the Er‐
685 lang/SCTP binding, this event is disabled by default.
686 *
688 #sctp_pdapi_event{
691 indication = sctp_partial_delivery_aborted,
692 assoc_id = assoc_id()
693 }
694 A partial delivery failure. In the current implementation of
696 the Erlang/SCTP binding, this event is internally converted
697 into an error term returned by recv/*.
698 send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
700 Types:
702 Socket = sctp_socket()
704 SndRcvInfo = #sctp_sndrcvinfo{}
705 Data = binary() | iolist()
706 Reason = term()
707 Sends the Data message with all sending parameters from a
709 #sctp_sndrcvinfo{} record. This way, the user can specify the
710 PPID (passed to the remote end) and context (passed to the local
711 SCTP layer), which can be used, for example, for error identifi‐
712 cation. However, such a fine level of user control is rarely re‐
713 quired. The function send/4 is sufficient for most applications.
714 send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
716 Types:
718 Socket = sctp_socket()
720 Assoc = #sctp_assoc_change{} | assoc_id()
721 Stream = integer()
722 Data = binary() | iolist()
723 Reason = term()
724 Sends a Data message over an existing association and specified
726 stream.
727
729 The set of admissible SCTP socket options is by construction orthogonal
730 to the sets of TCP, UDP, and generic inet options. Only options listed
731 here are allowed for SCTP sockets. Options can be set on the socket us‐
732 ing open/1,2 or inet:setopts/2, retrieved using inet:getopts/2. Options
733 can be changed when calling connect/4,5.
734 {mode, list|binary} or just list or binary:
736 Determines the type of data returned from recv/1,2.
737 {active, true|false|once|N}:
739 * If false (passive mode, the default), the caller must do an ex‐
742 plicit recv call to retrieve the available data from the socket.
743 * If true|once|N (active modes) received data or events are sent to
745 the owning process. See open/0..2 for the message format.
746 * If true (full active mode) there is no flow control.
748 Note:
750 Note that this can cause the message queue to overflow causing for
751 example the virtual machine to run out of memory and crash.
752 * If once, only one message is automatically placed in the message
755 queue, and after that the mode is automatically reset to passive.
756 This provides flow control and the possibility for the receiver
757 to listen for its incoming SCTP data interleaved with other in‐
758 ter-process messages.
759 * If active is specified as an integer N in the range -32768 to
761 32767 (inclusive), that number is added to the socket's counting
762 of data messages to be delivered to the controlling process. If
763 the result of the addition is negative, the count is set to 0.
764 Once the count reaches 0, either through the delivery of messages
765 or by being explicitly set with inet:setopts/2, the socket mode
766 is automatically reset to passive ({active, false}). When a
767 socket in this active mode transitions to passive mode, the mes‐
768 sage {sctp_passive, Socket} is sent to the controlling process to
769 notify it that if it wants to receive more data messages from the
770 socket, it must call inet:setopts/2 to set the socket back into
771 an active mode.
772 {tos, integer()}:
774 Sets the Type-Of-Service field on the IP datagrams that are sent,
775 to the specified value. This effectively determines a prioritiza‐
776 tion policy for the outbound packets. The acceptable values are
777 system-dependent.
778 {priority, integer()}:
780 A protocol-independent equivalent of tos above. Setting priority
781 implies setting tos as well.
782 {dontroute, true|false}:
784 Defaults to false. If true, the kernel does not send packets
785 through any gateway, only sends them to directly connected hosts.
786 {reuseaddr, true|false}:
788 Defaults to false. If true, the local binding address {IP,Port} of
789 the socket can be reused immediately. No waiting in state
790 CLOSE_WAIT is performed (can be required for high-throughput
791 servers).
792 {sndbuf, integer()}:
794 The size, in bytes, of the OS kernel send buffer for this socket.
795 Sending errors would occur for datagrams larger than val(sndbuf).
796 Setting this option also adjusts the size of the driver buffer (see
797 buffer above).
798 {recbuf, integer()}:
800 The size, in bytes, of the OS kernel receive buffer for this
801 socket. Sending errors would occur for datagrams larger than
802 val(recbuf). Setting this option also adjusts the size of the
803 driver buffer (see buffer above).
804 {sctp_module, module()}:
806 Overrides which callback module is used. Defaults to inet_sctp for
807 IPv4 and inet6_sctp for IPv6.
808 {sctp_rtoinfo, #sctp_rtoinfo{}}:
810 #sctp_rtoinfo{
813 assoc_id = assoc_id(),
814 initial = integer(),
815 max = integer(),
816 min = integer()
817 }
818 Determines retransmission time-out parameters, in milliseconds, for
820 the association(s) specified by assoc_id.
821 assoc_id = 0 (default) indicates the whole endpoint. See RFC 2960
823 and Sockets API Extensions for SCTP for the exact semantics of the
824 field values.
825 {sctp_associnfo, #sctp_assocparams{}}:
827 #sctp_assocparams{
830 assoc_id = assoc_id(),
831 asocmaxrxt = integer(),
832 number_peer_destinations = integer(),
833 peer_rwnd = integer(),
834 local_rwnd = integer(),
835 cookie_life = integer()
836 }
837 Determines association parameters for the association(s) specified
839 by assoc_id.
840 assoc_id = 0 (default) indicates the whole endpoint. See Sockets
842 API Extensions for SCTP for the discussion of their semantics.
843 Rarely used.
844 {sctp_initmsg, #sctp_initmsg{}}:
846 #sctp_initmsg{
849 num_ostreams = integer(),
850 max_instreams = integer(),
851 max_attempts = integer(),
852 max_init_timeo = integer()
853 }
854 Determines the default parameters that this socket tries to negoti‐
856 ate with its peer while establishing an association with it. Is to
857 be set after open/* but before the first connect/*. #sctp_initmsg{}
858 can also be used as ancillary data with the first call of send/* to
859 a new peer (when a new association is created).
860 num_ostreams:
862 Number of outbound streams
863 max_instreams:
865 Maximum number of inbound streams
866 max_attempts:
868 Maximum retransmissions while establishing an association
869 max_init_timeo:
871 Time-out, in milliseconds, for establishing an association
872 {sctp_autoclose, integer() >= 0}:
874 Determines the time, in seconds, after which an idle association is
875 automatically closed. 0 means that the association is never auto‐
876 matically closed.
877 {sctp_nodelay, true|false}:
879 Turns on|off the Nagle algorithm for merging small packets into
880 larger ones. This improves throughput at the expense of latency.
881 {sctp_disable_fragments, true|false}:
883 If true, induces an error on an attempt to send a message larger
884 than the current PMTU size (which would require fragmentation/re‐
885 assembling). Notice that message fragmentation does not affect the
886 logical atomicity of its delivery; this option is provided for per‐
887 formance reasons only.
888 {sctp_i_want_mapped_v4_addr, true|false}:
890 Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
891 the socket address family is AF_INET6).
892 {sctp_maxseg, integer()}:
894 Determines the maximum chunk size if message fragmentation is used.
895 If 0, the chunk size is limited by the Path MTU only.
896 {sctp_primary_addr, #sctp_prim{}}:
898 #sctp_prim{
901 assoc_id = assoc_id(),
902 addr = {IP, Port}
903 }
904 IP = ip_address()
905 Port = port_number()
906 For the association specified by assoc_id, {IP,Port} must be one of
908 the peer addresses. This option determines that the specified ad‐
909 dress is treated by the local SCTP stack as the primary address of
910 the peer.
911 {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
913 #sctp_setpeerprim{
916 assoc_id = assoc_id(),
917 addr = {IP, Port}
918 }
919 IP = ip_address()
920 Port = port_number()
921 When set, informs the peer to use {IP, Port} as the primary address
923 of the local endpoint for the association specified by assoc_id.
924 {sctp_adaptation_layer, #sctp_setadaptation{}}:
926 #sctp_setadaptation{
929 adaptation_ind = integer()
930 }
931 When set, requests that the local endpoint uses the value specified
933 by adaptation_ind as the Adaptation Indication parameter for estab‐
934 lishing new associations. For details, see RFC 2960 and Sockets API
935 Extensions for SCTP.
936 {sctp_peer_addr_params, #sctp_paddrparams{}}:
938 #sctp_paddrparams{
941 assoc_id = assoc_id(),
942 address = {IP, Port},
943 hbinterval = integer(),
944 pathmaxrxt = integer(),
945 pathmtu = integer(),
946 sackdelay = integer(),
947 flags = list()
948 }
949 IP = ip_address()
950 Port = port_number()
951 Determines various per-address parameters for the association spec‐
953 ified by assoc_id and the peer address address (the SCTP protocol
954 supports multi-homing, so more than one address can correspond to a
955 specified association).
956 hbinterval:
958 Heartbeat interval, in milliseconds
959 pathmaxrxt:
961 Maximum number of retransmissions before this address is consid‐
962 ered unreachable (and an alternative address is selected)
963 pathmtu:
965 Fixed Path MTU, if automatic discovery is disabled (see flags be‐
966 low)
967 sackdelay:
969 Delay, in milliseconds, for SAC messages (if the delay is en‐
970 abled, see flags below)
971 flags:
973 The following flags are available:
974 hb_enable:
976 Enables heartbeat
977 hb_disable:
979 Disables heartbeat
980 hb_demand:
982 Initiates heartbeat immediately
983 pmtud_enable:
985 Enables automatic Path MTU discovery
986 pmtud_disable:
988 Disables automatic Path MTU discovery
989 sackdelay_enable:
991 Enables SAC delay
992 sackdelay_disable:
994 Disables SAC delay
995 {sctp_default_send_param, #sctp_sndrcvinfo{}}:
997 #sctp_sndrcvinfo{
1000 stream = integer(),
1001 ssn = integer(),
1002 flags = list(),
1003 ppid = integer(),
1004 context = integer(),
1005 timetolive = integer(),
1006 tsn = integer(),
1007 cumtsn = integer(),
1008 assoc_id = assoc_id()
1009 }
1010 #sctp_sndrcvinfo{} is used both in this socket option, and as an‐
1012 cillary data while sending or receiving SCTP messages. When set as
1013 an option, it provides default values for subsequent send calls on
1014 the association specified by assoc_id.
1015 assoc_id = 0 (default) indicates the whole endpoint.
1017 The following fields typically must be specified by the sender:
1019 sinfo_stream:
1021 Stream number (0-base) within the association to send the mes‐
1022 sages through;
1023 sinfo_flags:
1025 The following flags are recognised:
1026 unordered:
1028 The message is to be sent unordered
1029 addr_over:
1031 The address specified in send overwrites the primary peer ad‐
1032 dress
1033 abort:
1035 Aborts the current association without flushing any unsent data
1036 eof:
1038 Gracefully shuts down the current association, with flushing of
1039 unsent data
1040 Other fields are rarely used. For complete information, see RFC
1042 2960 and Sockets API Extensions for SCTP.
1043 {sctp_events, #sctp_event_subscribe{}}:
1045 #sctp_event_subscribe{
1048 data_io_event = true | false,
1049 association_event = true | false,
1050 address_event = true | false,
1051 send_failure_event = true | false,
1052 peer_error_event = true | false,
1053 shutdown_event = true | false,
1054 partial_delivery_event = true | false,
1055 adaptation_layer_event = true | false
1056 }
1057 This option determines which SCTP Events are to be received
1059 (through recv/*) along with the data. The only exception is
1060 data_io_event, which enables or disables receiving of #sctp_sndrcv‐
1061 info{} ancillary data, not events. By default, all flags except
1062 adaptation_layer_event are enabled, although sctp_data_io_event and
1063 association_event are used by the driver itself and not exported to
1064 the user level.
1065 {sctp_delayed_ack_time, #sctp_assoc_value{}}:
1067 #sctp_assoc_value{
1070 assoc_id = assoc_id(),
1071 assoc_value = integer()
1072 }
1073 Rarely used. Determines the ACK time (specified by assoc_value, in
1075 milliseconds) for the specified association or the whole endpoint
1076 if assoc_value = 0 (default).
1077 {sctp_status, #sctp_status{}}:
1079 #sctp_status{
1082 assoc_id = assoc_id(),
1083 state = atom(),
1084 rwnd = integer(),
1085 unackdata = integer(),
1086 penddata = integer(),
1087 instrms = integer(),
1088 outstrms = integer(),
1089 fragmentation_point = integer(),
1090 primary = #sctp_paddrinfo{}
1091 }
1092 This option is read-only. It determines the status of the SCTP as‐
1094 sociation specified by assoc_id. The following are the possible
1095 values of state (the state designations are mostly self-explana‐
1096 tory):
1097 sctp_state_empty:
1099 Default. Means that no other state is active.
1100 sctp_state_closed:
1102 sctp_state_cookie_wait:
1105 sctp_state_cookie_echoed:
1108 sctp_state_established:
1111 sctp_state_shutdown_pending:
1114 sctp_state_shutdown_sent:
1117 sctp_state_shutdown_received:
1120 sctp_state_shutdown_ack_sent:
1123 Semantics of the other fields:
1126 sstat_rwnd:
1128 Current receiver window size of the association
1129 sstat_unackdata:
1131 Number of unacked data chunks
1132 sstat_penddata:
1134 Number of data chunks pending receipt
1135 sstat_instrms:
1137 Number of inbound streams
1138 sstat_outstrms:
1140 Number of outbound streams
1141 sstat_fragmentation_point:
1143 Message size at which SCTP fragmentation occurs
1144 sstat_primary:
1146 Information on the current primary peer address (see below for
1147 the format of #sctp_paddrinfo{})
1148 {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1150 #sctp_paddrinfo{
1153 assoc_id = assoc_id(),
1154 address = {IP, Port},
1155 state = inactive | active | unconfirmed,
1156 cwnd = integer(),
1157 srtt = integer(),
1158 rto = integer(),
1159 mtu = integer()
1160 }
1161 IP = ip_address()
1162 Port = port_number()
1163 This option is read-only. It determines the parameters specific to
1165 the peer address specified by address within the association speci‐
1166 fied by assoc_id. Field address fmust be set by the caller; all
1167 other fields are filled in on return. If assoc_id = 0 (default),
1168 the address is automatically translated into the corresponding as‐
1169 sociation ID. This option is rarely used. For the semantics of all
1170 fields, see RFC 2960 and Sockets API Extensions for SCTP.
1171
1173 Example of an Erlang SCTP server that receives SCTP messages and prints
1174 them on the standard output:
1175 -module(sctp_server).
1177 -export([server/0,server/1,server/2]).
1179 -include_lib("kernel/include/inet.hrl").
1180 -include_lib("kernel/include/inet_sctp.hrl").
1181 server() ->
1183 server(any, 2006).
1184 server([Host,Port]) when is_list(Host), is_list(Port) ->
1186 {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1187 io:format("~w -> ~w~n", [Host, IP]),
1188 server([IP, list_to_integer(Port)]).
1189 server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1191 is_integer(Port) ->
1192 {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1193 io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1194 ok = gen_sctp:listen(S, true),
1195 server_loop(S).
1196 server_loop(S) ->
1198 case gen_sctp:recv(S) of
1199 {error, Error} ->
1200 io:format("SCTP RECV ERROR: ~p~n", [Error]);
1201 Data ->
1202 io:format("Received: ~p~n", [Data])
1203 end,
1204 server_loop(S).
1205 Example of an Erlang SCTP client interacting with the above server. No‐
1207 tice that in this example the client creates an association with the
1208 server with 5 outbound streams. Therefore, sending of "Test 0" over
1209 stream 0 succeeds, but sending of "Test 5" over stream 5 fails. The
1210 client then aborts the association, which results in that the corre‐
1211 sponding event is received on the server side.
1212 -module(sctp_client).
1214 -export([client/0, client/1, client/2]).
1216 -include_lib("kernel/include/inet.hrl").
1217 -include_lib("kernel/include/inet_sctp.hrl").
1218 client() ->
1220 client([localhost]).
1221 client([Host]) ->
1223 client(Host, 2006);
1224 client([Host, Port]) when is_list(Host), is_list(Port) ->
1226 client(Host,list_to_integer(Port)),
1227 init:stop().
1228 client(Host, Port) when is_integer(Port) ->
1230 {ok,S} = gen_sctp:open(),
1231 {ok,Assoc} = gen_sctp:connect
1232 (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1233 io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1234 io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1236 io:nl(),
1237 timer:sleep(10000),
1238 io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1239 io:nl(),
1240 timer:sleep(10000),
1241 io:write(gen_sctp:abort(S, Assoc)),
1242 io:nl(),
1243 timer:sleep(1000),
1245 gen_sctp:close(S).
1246 A simple Erlang SCTP client that uses the connect_init API:
1248 -module(ex3).
1250 -export([client/4]).
1252 -include_lib("kernel/include/inet.hrl").
1253 -include_lib("kernel/include/inet_sctp.hrl").
1254 client(Peer1, Port1, Peer2, Port2)
1256 when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1257 {ok,S} = gen_sctp:open(),
1258 SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1259 ActiveOpt = {active, true},
1260 Opts = [SctpInitMsgOpt, ActiveOpt],
1261 ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1262 ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1263 io:format("Connections initiated~n", []),
1264 client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1265 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1267 receive
1268 {sctp, S, Peer1, Port1, {_Anc, SAC}}
1269 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1270 io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1271 [SAC#sctp_assoc_change.state,
1272 SAC#sctp_assoc_change.assoc_id]),
1273 client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1274 Peer2, Port2, AssocId2);
1275 {sctp, S, Peer2, Port2, {_Anc, SAC}}
1277 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1278 io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1279 [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1280 client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1281 SAC#sctp_assoc_change.assoc_id);
1282 {sctp, S, Peer1, Port1, Data} ->
1284 io:format("Association 1: received ~p~n", [Data]),
1285 client_loop(S, Peer1, Port1, AssocId1,
1286 Peer2, Port2, AssocId2);
1287 {sctp, S, Peer2, Port2, Data} ->
1289 io:format("Association 2: received ~p~n", [Data]),
1290 client_loop(S, Peer1, Port1, AssocId1,
1291 Peer2, Port2, AssocId2);
1292 Other ->
1294 io:format("Other ~p~n", [Other]),
1295 client_loop(S, Peer1, Port1, AssocId1,
1296 Peer2, Port2, AssocId2)
1297 after 5000 ->
1299 ok
1300 end.
1301
1303 gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control Transmission
1304 Protocol), Sockets API Extensions for SCTP
1305Ericsson AB kernel 9.1 gen_sctp(3)