1gen_sctp(3)                Erlang Module Definition                gen_sctp(3)
2
3
4

NAME

6       gen_sctp - Functions for communicating with sockets using the SCTP
7           protocol.
8

DESCRIPTION

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
14       During development, this implementation was tested on:
15
16         * Linux Fedora Core 5.0 (kernel 2.6.15-2054 or later is needed)
17
18         * Solaris 10, 11
19
20       During OTP adaptation it was tested on:
21
22         * SUSE  Linux Enterprise Server 10 (x86_64) kernel 2.6.16.27-0.6-smp,
23           with lksctp-tools-1.0.6
24
25         * Briefly on Solaris 10
26
27         * 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
30         * FreeBSD 8.2
31
32       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
36       Record definitions for this module can be found using:
37
38       -include_lib("kernel/include/inet_sctp.hrl").
39
40       These  record  definitions use the "new" spelling 'adaptation', not the
41       deprecated 'adaption', regardless of which spelling  the  underlying  C
42       API uses.
43

DATA TYPES

45       assoc_id()
46
47              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
52       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
90              One of the SCTP Socket Options.
91
92       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
104       sctp_socket()
105
106              Socket identifier returned from open/*.
107

EXPORTS

109       abort(Socket, Assoc) -> ok | {error, inet:posix()}
110
111              Types:
112
113                 Socket = sctp_socket()
114                 Assoc = #sctp_assoc_change{}
115
116              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
121       close(Socket) -> ok | {error, inet:posix()}
122
123              Types:
124
125                 Socket = sctp_socket()
126
127              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
133       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
138              Types:
139
140                 Socket = sctp_socket()
141                 Addr = inet:ip_address() | inet:hostname()
142                 Port = inet:port_number()
143                 Opts = [Opt :: option()]
144
145              Same as connect(Socket, Addr, Port, Opts, infinity).
146
147       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
152              Types:
153
154                 Socket = sctp_socket()
155                 Addr = inet:ip_address() | inet:hostname()
156                 Port = inet:port_number()
157                 Opts = [Opt :: option()]
158                 Timeout = timeout()
159
160              Establishes  a  new association for socket Socket, with the peer
161              (SCTP server socket) specified by Addr and Port. Timeout, is ex‐
162              pressed  in milliseconds. A socket can be associated with multi‐
163              ple peers.
164
165          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 de‐
168              fault values from RFC 4960 are used), can result in inconsistent
169              or  incorrect return values. This is especially relevant for as‐
170              sociations sharing the same Socket (that is, source address  and
171              port),  as  the  controlling  process blocks until connect/* re‐
172              turns. connect_init/* provides an alternative without this limi‐
173              tation.
174
175
176              The  result  of  connect/* is an #sctp_assoc_change{} event that
177              contains, in particular, the new Association ID:
178
179              #sctp_assoc_change{
180                    state             = atom(),
181                    error             = integer(),
182                    outbound_streams  = integer(),
183                    inbound_streams   = integer(),
184                    assoc_id          = assoc_id()
185              }
186
187              The number of outbound and inbound streams can be set by  giving
188              an sctp_initmsg option to connect as in:
189
190              connect(Socket, Ip, Port>,
191                    [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
192                                                 max_instreams=MaxInStreams}}])
193
194              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
200              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
205              state can have the following values:
206
207                comm_up:
208                  Association is successfully established.  This  indicates  a
209                  successful completion of connect.
210
211                cant_assoc:
212                  The association cannot be established (connect/* failure).
213
214              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
220                comm_lost:
221
222
223                restart:
224
225
226                shutdown_comp:
227
228
229              Field  error  can  provide  more detailed diagnostics. The error
230              field value can be converted into a string using error_string/1.
231
232       connect_init(Socket, Addr, Port, Opts) ->
233                       ok | {error, inet:posix()}
234
235              Types:
236
237                 Socket = sctp_socket()
238                 Addr = inet:ip_address() | inet:hostname()
239                 Port = inet:port_number()
240                 Opts = [option()]
241
242              Same as connect_init(Socket, Addr, Port, Opts, infinity).
243
244       connect_init(Socket, Addr, Port, Opts, Timeout) ->
245                       ok | {error, inet:posix()}
246
247              Types:
248
249                 Socket = sctp_socket()
250                 Addr = inet:ip_address() | inet:hostname()
251                 Port = inet:port_number()
252                 Opts = [option()]
253                 Timeout = timeout()
254
255              Initiates a new association for socket  Socket,  with  the  peer
256              (SCTP server socket) specified by Addr and Port.
257
258              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 #sctp_as‐
262              soc_change{}  event. The calling process must be prepared to re‐
263              ceive this, or poll for it using recv/*, depending on the  value
264              of the active option.
265
266              The parameters are as described in connect/*, except the Timeout
267              value.
268
269              The timer associated with Timeout only supervises IP  resolution
270              of Addr.
271
272       controlling_process(Socket, Pid) -> ok | {error, Reason}
273
274              Types:
275
276                 Socket = sctp_socket()
277                 Pid = pid()
278                 Reason = closed | not_owner | badarg | inet:posix()
279
280              Assigns  a new controlling process Pid to Socket. Same implemen‐
281              tation as gen_udp:controlling_process/2.
282
283       eof(Socket, Assoc) -> ok | {error, Reason}
284
285              Types:
286
287                 Socket = sctp_socket()
288                 Assoc = #sctp_assoc_change{}
289                 Reason = term()
290
291              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
296       error_string(ErrorNumber) -> ok | string() | unknown_error
297
298              Types:
299
300                 ErrorNumber = integer()
301
302              Translates  an  SCTP  error  number from, for example, #sctp_re‐
303              mote_error{} or #sctp_send_failed{} into an explanatory  string,
304              or one of the atoms ok for no error or undefined for an unrecog‐
305              nized error.
306
307       listen(Socket, IsServer) -> ok | {error, Reason}
308
309       listen(Socket, Backlog) -> ok | {error, Reason}
310
311              Types:
312
313                 Socket = sctp_socket()
314                 Backlog = integer()
315                 Reason = term()
316
317              Sets up a socket to listen on the IP address and port number  it
318              is bound to.
319
320              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
325              For type stream, sockets Backlog define the backlog queue length
326              just like in TCP.
327
328       open() -> {ok, Socket} | {error, inet:posix()}
329
330       open(Port) -> {ok, Socket} | {error, inet:posix()}
331
332       open(Opts) -> {ok, Socket} | {error, inet:posix()}
333
334       open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
335
336              Types:
337
338                 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
351              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
357              Other options:
358
359                inet6:
360                  Sets up the socket for IPv6.
361
362                inet:
363                  Sets up the socket for IPv4. This is the default.
364
365              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
369              If  the  socket  is in passive mode data can be received through
370              the recv/1,2 calls.
371
372              If the socket is in active mode data received data is  delivered
373              to the controlling process as messages:
374
375              {sctp, Socket, FromIP, FromPort, {AncData, Data}}
376
377
378              See recv/1,2 for a description of the message fields.
379
380          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
385
386       peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
387
388              Types:
389
390                 Socket = sctp_socket()
391                 Assoc = #sctp_assoc_change{} | assoc_id()
392                 NewSocket = sctp_socket()
393                 Reason = term()
394
395              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
399              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
404       recv(Socket) ->
405               {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
406
407       recv(Socket, Timeout) ->
408               {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
409
410              Types:
411
412                 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
432              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
437              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  de‐
441              fault,  as such ancillary data provides an easy way of determin‐
442              ing the association and stream over which  the  message  is  re‐
443              ceived.  (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
447              AncData  may  also  contain  ancillary data  from the socket op‐
448              tions recvtos, recvtclass or recvttl, if that  is  supported  by
449              the platform for the socket.
450
451              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
455              Possible SCTP events:
456
457                * #sctp_sndrcvinfo{}
458
459                * #sctp_assoc_change{}
460
461                *
462
463
464                #sctp_paddr_change{
465                      addr      = {ip_address(),port()},
466                      state     = atom(),
467                      error     = integer(),
468                      assoc_id  = assoc_id()
469                }
470
471                  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
475                  addr_unreachable:
476
477
478                  addr_available:
479
480
481                  addr_removed:
482
483
484                  addr_added:
485
486
487                  addr_made_prim:
488
489
490                  addr_confirmed:
491
492
493                  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 er‐
496                  ror term returned by recv. The error field value can be con‐
497                  verted into a string using error_string/1.
498
499                *
500
501
502                #sctp_send_failed{
503                      flags     = true | false,
504                      error     = integer(),
505                      info      = #sctp_sndrcvinfo{},
506                      assoc_id  = assoc_id()
507                      data      = binary()
508                }
509
510                  The sender can receive this event if a send operation fails.
511
512                  flags:
513                    A Boolean specifying if the data has been transmitted over
514                    the wire.
515
516                  error:
517                    Provides extended diagnostics, use error_string/1.
518
519                  info:
520                    The original #sctp_sndrcvinfo{} record used in the  failed
521                    send/*.
522
523                  data:
524                    The whole original data chunk attempted to be sent.
525
526                  In  the  current  implementation of the Erlang/SCTP binding,
527                  this event is internally converted into an  error  term  re‐
528                  turned by recv/*.
529
530                *
531
532
533                #sctp_adaptation_event{
534                      adaptation_ind = integer(),
535                      assoc_id       = assoc_id()
536                }
537
538                  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 Er‐
541                  lang/SCTP binding, this event is disabled by default.
542
543                *
544
545
546                #sctp_pdapi_event{
547                      indication = sctp_partial_delivery_aborted,
548                      assoc_id   = assoc_id()
549                }
550
551                  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
555       send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
556
557              Types:
558
559                 Socket = sctp_socket()
560                 SndRcvInfo = #sctp_sndrcvinfo{}
561                 Data = binary() | iolist()
562                 Reason = term()
563
564              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 re‐
569              quired. The function send/4 is sufficient for most applications.
570
571       send(Socket, Assoc, Stream, Data) -> ok | {error, Reason}
572
573              Types:
574
575                 Socket = sctp_socket()
576                 Assoc = #sctp_assoc_change{} | assoc_id()
577                 Stream = integer()
578                 Data = binary() | iolist()
579                 Reason = term()
580
581              Sends  a Data message over an existing association and specified
582              stream.
583

SCTP SOCKET OPTIONS

585       The set of admissible SCTP socket options is by construction orthogonal
586       to  the sets of TCP, UDP, and generic inet options. Only options listed
587       here are allowed for SCTP sockets. Options can be set on the socket us‐
588       ing open/1,2 or inet:setopts/2, retrieved using inet:getopts/2. Options
589       can be changed when calling connect/4,5.
590
591         {mode, list|binary} or just list or binary:
592           Determines the type of data returned from recv/1,2.
593
594         {active, true|false|once|N}:
595
596
597           * If false (passive mode, the default), the caller must do  an  ex‐
598             plicit recv call to retrieve the available data from the socket.
599
600           * If true|once|N (active modes) received data or events are sent to
601             the owning process. See open/0..2 for the message format.
602
603           * If true (full active mode) there is no flow control.
604
605       Note:
606           Note that this can cause the message queue to overflow causing  for
607           example the virtual machine to run out of memory and crash.
608
609
610           * If  once, only one message is automatically placed in the message
611             queue, and after that the mode is automatically reset to passive.
612             This  provides  flow control and the possibility for the receiver
613             to listen for its incoming SCTP data interleaved with  other  in‐
614             ter-process messages.
615
616           * If  active  is  specified  as an integer N in the range -32768 to
617             32767 (inclusive), that number is added to the socket's  counting
618             of  data  messages to be delivered to the controlling process. If
619             the result of the addition is negative, the count is  set  to  0.
620             Once the count reaches 0, either through the delivery of messages
621             or by being explicitly set with inet:setopts/2, the  socket  mode
622             is  automatically  reset  to  passive  ({active,  false}). When a
623             socket in this active mode transitions to passive mode, the  mes‐
624             sage {sctp_passive, Socket} is sent to the controlling process to
625             notify it that if it wants to receive more data messages from the
626             socket,  it  must call inet:setopts/2 to set the socket back into
627             an active mode.
628
629         {tos, integer()}:
630           Sets the Type-Of-Service field on the IP datagrams that  are  sent,
631           to  the  specified value. This effectively determines a prioritiza‐
632           tion policy for the outbound packets.  The  acceptable  values  are
633           system-dependent.
634
635         {priority, integer()}:
636           A  protocol-independent  equivalent  of tos above. Setting priority
637           implies setting tos as well.
638
639         {dontroute, true|false}:
640           Defaults to false. If  true,  the  kernel  does  not  send  packets
641           through any gateway, only sends them to directly connected hosts.
642
643         {reuseaddr, true|false}:
644           Defaults  to false. If true, the local binding address {IP,Port} of
645           the  socket  can  be  reused  immediately.  No  waiting  in   state
646           CLOSE_WAIT  is  performed  (can  be  required  for  high-throughput
647           servers).
648
649         {sndbuf, integer()}:
650           The size, in bytes, of the OS kernel send buffer for  this  socket.
651           Sending  errors  would occur for datagrams larger than val(sndbuf).
652           Setting this option also adjusts the size of the driver buffer (see
653           buffer above).
654
655         {recbuf, integer()}:
656           The  size,  in  bytes,  of  the  OS  kernel receive buffer for this
657           socket. Sending  errors  would  occur  for  datagrams  larger  than
658           val(recbuf).  Setting  this  option  also  adjusts  the size of the
659           driver buffer (see buffer above).
660
661         {sctp_module, module()}:
662           Overrides which callback module is used. Defaults to inet_sctp  for
663           IPv4 and inet6_sctp for IPv6.
664
665         {sctp_rtoinfo, #sctp_rtoinfo{}}:
666
667
668         #sctp_rtoinfo{
669               assoc_id = assoc_id(),
670               initial  = integer(),
671               max      = integer(),
672               min      = integer()
673         }
674
675           Determines retransmission time-out parameters, in milliseconds, for
676           the association(s) specified by assoc_id.
677
678           assoc_id = 0 (default) indicates the whole endpoint. See  RFC  2960
679           and  Sockets API Extensions for SCTP for the exact semantics of the
680           field values.
681
682         {sctp_associnfo, #sctp_assocparams{}}:
683
684
685         #sctp_assocparams{
686               assoc_id                 = assoc_id(),
687               asocmaxrxt               = integer(),
688               number_peer_destinations = integer(),
689               peer_rwnd                = integer(),
690               local_rwnd               = integer(),
691               cookie_life              = integer()
692         }
693
694           Determines association parameters for the association(s)  specified
695           by assoc_id.
696
697           assoc_id  =  0  (default) indicates the whole endpoint. See Sockets
698           API Extensions for SCTP for  the  discussion  of  their  semantics.
699           Rarely used.
700
701         {sctp_initmsg, #sctp_initmsg{}}:
702
703
704         #sctp_initmsg{
705              num_ostreams   = integer(),
706              max_instreams  = integer(),
707              max_attempts   = integer(),
708              max_init_timeo = integer()
709         }
710
711           Determines the default parameters that this socket tries to negoti‐
712           ate with its peer while establishing an association with it. Is  to
713           be set after open/* but before the first connect/*. #sctp_initmsg{}
714           can also be used as ancillary data with the first call of send/* to
715           a new peer (when a new association is created).
716
717           num_ostreams:
718             Number of outbound streams
719
720           max_instreams:
721             Maximum number of inbound streams
722
723           max_attempts:
724             Maximum retransmissions while establishing an association
725
726           max_init_timeo:
727             Time-out, in milliseconds, for establishing an association
728
729         {sctp_autoclose, integer() >= 0}:
730           Determines the time, in seconds, after which an idle association is
731           automatically closed. 0 means that the association is  never  auto‐
732           matically closed.
733
734         {sctp_nodelay, true|false}:
735           Turns  on|off  the  Nagle  algorithm for merging small packets into
736           larger ones. This improves throughput at the expense of latency.
737
738         {sctp_disable_fragments, true|false}:
739           If true, induces an error on an attempt to send  a  message  larger
740           than  the  current PMTU size (which would require fragmentation/re‐
741           assembling). Notice that message fragmentation does not affect  the
742           logical atomicity of its delivery; this option is provided for per‐
743           formance reasons only.
744
745         {sctp_i_want_mapped_v4_addr, true|false}:
746           Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
747           the socket address family is AF_INET6).
748
749         {sctp_maxseg, integer()}:
750           Determines the maximum chunk size if message fragmentation is used.
751           If 0, the chunk size is limited by the Path MTU only.
752
753         {sctp_primary_addr, #sctp_prim{}}:
754
755
756         #sctp_prim{
757               assoc_id = assoc_id(),
758               addr     = {IP, Port}
759         }
760          IP = ip_address()
761          Port = port_number()
762
763           For the association specified by assoc_id, {IP,Port} must be one of
764           the  peer  addresses. This option determines that the specified ad‐
765           dress is treated by the local SCTP stack as the primary address  of
766           the peer.
767
768         {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
769
770
771         #sctp_setpeerprim{
772               assoc_id = assoc_id(),
773               addr     = {IP, Port}
774         }
775          IP = ip_address()
776          Port = port_number()
777
778           When set, informs the peer to use {IP, Port} as the primary address
779           of the local endpoint for the association specified by assoc_id.
780
781         {sctp_adaptation_layer, #sctp_setadaptation{}}:
782
783
784         #sctp_setadaptation{
785               adaptation_ind = integer()
786         }
787
788           When set, requests that the local endpoint uses the value specified
789           by adaptation_ind as the Adaptation Indication parameter for estab‐
790           lishing new associations. For details, see RFC 2960 and Sockets API
791           Extenstions for SCTP.
792
793         {sctp_peer_addr_params, #sctp_paddrparams{}}:
794
795
796         #sctp_paddrparams{
797               assoc_id   = assoc_id(),
798               address    = {IP, Port},
799               hbinterval = integer(),
800               pathmaxrxt = integer(),
801               pathmtu    = integer(),
802               sackdelay  = integer(),
803               flags      = list()
804         }
805         IP = ip_address()
806         Port = port_number()
807
808           Determines various per-address parameters for the association spec‐
809           ified by assoc_id and the peer address address (the  SCTP  protocol
810           supports multi-homing, so more than one address can correspond to a
811           specified association).
812
813           hbinterval:
814             Heartbeat interval, in milliseconds
815
816           pathmaxrxt:
817             Maximum number of retransmissions before this address is  consid‐
818             ered unreachable (and an alternative address is selected)
819
820           pathmtu:
821             Fixed Path MTU, if automatic discovery is disabled (see flags be‐
822             low)
823
824           sackdelay:
825             Delay, in milliseconds, for SAC messages (if  the  delay  is  en‐
826             abled, see flags below)
827
828           flags:
829             The following flags are available:
830
831             hb_enable:
832               Enables heartbeat
833
834             hb_disable:
835               Disables heartbeat
836
837             hb_demand:
838               Initiates heartbeat immediately
839
840             pmtud_enable:
841               Enables automatic Path MTU discovery
842
843             pmtud_disable:
844               Disables automatic Path MTU discovery
845
846             sackdelay_enable:
847               Enables SAC delay
848
849             sackdelay_disable:
850               Disables SAC delay
851
852         {sctp_default_send_param, #sctp_sndrcvinfo{}}:
853
854
855         #sctp_sndrcvinfo{
856               stream     = integer(),
857               ssn        = integer(),
858               flags      = list(),
859               ppid       = integer(),
860               context    = integer(),
861               timetolive = integer(),
862               tsn        = integer(),
863               cumtsn     = integer(),
864               assoc_id   = assoc_id()
865         }
866
867           #sctp_sndrcvinfo{}  is  used both in this socket option, and as an‐
868           cillary data while sending or receiving SCTP messages. When set  as
869           an  option, it provides default values for subsequent send calls on
870           the association specified by assoc_id.
871
872           assoc_id = 0 (default) indicates the whole endpoint.
873
874           The following fields typically must be specified by the sender:
875
876           sinfo_stream:
877             Stream number (0-base) within the association to  send  the  mes‐
878             sages through;
879
880           sinfo_flags:
881             The following flags are recognised:
882
883             unordered:
884               The message is to be sent unordered
885
886             addr_over:
887               The  address  specified in send overwrites the primary peer ad‐
888               dress
889
890             abort:
891               Aborts the current association without flushing any unsent data
892
893             eof:
894               Gracefully shuts down the current association, with flushing of
895               unsent data
896
897             Other  fields  are rarely used. For complete information, see RFC
898             2960 and Sockets API Extensions for SCTP.
899
900         {sctp_events, #sctp_event_subscribe{}}:
901
902
903         #sctp_event_subscribe{
904                 data_io_event          = true | false,
905                 association_event      = true | false,
906                 address_event          = true | false,
907                 send_failure_event     = true | false,
908                 peer_error_event       = true | false,
909                 shutdown_event         = true | false,
910                 partial_delivery_event = true | false,
911                 adaptation_layer_event = true | false
912         }
913
914           This option  determines  which  SCTP  Events  are  to  be  received
915           (through  recv/*)  along  with  the  data.  The  only  exception is
916           data_io_event, which enables or disables receiving of #sctp_sndrcv‐
917           info{}  ancillary  data,  not  events. By default, all flags except
918           adaptation_layer_event are enabled, although sctp_data_io_event and
919           association_event are used by the driver itself and not exported to
920           the user level.
921
922         {sctp_delayed_ack_time, #sctp_assoc_value{}}:
923
924
925         #sctp_assoc_value{
926               assoc_id    = assoc_id(),
927               assoc_value = integer()
928         }
929
930           Rarely used. Determines the ACK time (specified by assoc_value,  in
931           milliseconds)  for  the specified association or the whole endpoint
932           if assoc_value = 0 (default).
933
934         {sctp_status, #sctp_status{}}:
935
936
937         #sctp_status{
938               assoc_id            = assoc_id(),
939               state               = atom(),
940               rwnd                = integer(),
941               unackdata           = integer(),
942               penddata            = integer(),
943               instrms             = integer(),
944               outstrms            = integer(),
945               fragmentation_point = integer(),
946               primary             = #sctp_paddrinfo{}
947         }
948
949           This option is read-only. It determines the status of the SCTP  as‐
950           sociation  specified  by  assoc_id.  The following are the possible
951           values of state (the state designations  are  mostly  self-explana‐
952           tory):
953
954           sctp_state_empty:
955             Default. Means that no other state is active.
956
957           sctp_state_closed:
958
959
960           sctp_state_cookie_wait:
961
962
963           sctp_state_cookie_echoed:
964
965
966           sctp_state_established:
967
968
969           sctp_state_shutdown_pending:
970
971
972           sctp_state_shutdown_sent:
973
974
975           sctp_state_shutdown_received:
976
977
978           sctp_state_shutdown_ack_sent:
979
980
981           Semantics of the other fields:
982
983           sstat_rwnd:
984             Current receiver window size of the association
985
986           sstat_unackdata:
987             Number of unacked data chunks
988
989           sstat_penddata:
990             Number of data chunks pending receipt
991
992           sstat_instrms:
993             Number of inbound streams
994
995           sstat_outstrms:
996             Number of outbound streams
997
998           sstat_fragmentation_point:
999             Message size at which SCTP fragmentation occurs
1000
1001           sstat_primary:
1002             Information  on  the  current primary peer address (see below for
1003             the format of #sctp_paddrinfo{})
1004
1005         {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1006
1007
1008         #sctp_paddrinfo{
1009               assoc_id  = assoc_id(),
1010               address   = {IP, Port},
1011               state     = inactive | active | unconfirmed,
1012               cwnd      = integer(),
1013               srtt      = integer(),
1014               rto       = integer(),
1015               mtu       = integer()
1016         }
1017         IP = ip_address()
1018         Port = port_number()
1019
1020           This option is read-only. It determines the parameters specific  to
1021           the peer address specified by address within the association speci‐
1022           fied by assoc_id. Field address fmust be set  by  the  caller;  all
1023           other  fields  are  filled in on return. If assoc_id = 0 (default),
1024           the address is automatically translated into the corresponding  as‐
1025           sociation  ID. This option is rarely used. For the semantics of all
1026           fields, see RFC 2960 and Sockets API Extensions for SCTP.
1027

SCTP EXAMPLES

1029       Example of an Erlang SCTP server that receives SCTP messages and prints
1030       them on the standard output:
1031
1032       -module(sctp_server).
1033
1034       -export([server/0,server/1,server/2]).
1035       -include_lib("kernel/include/inet.hrl").
1036       -include_lib("kernel/include/inet_sctp.hrl").
1037
1038       server() ->
1039           server(any, 2006).
1040
1041       server([Host,Port]) when is_list(Host), is_list(Port) ->
1042           {ok, #hostent{h_addr_list = [IP|_]}} = inet:gethostbyname(Host),
1043           io:format("~w -> ~w~n", [Host, IP]),
1044           server([IP, list_to_integer(Port)]).
1045
1046       server(IP, Port) when is_tuple(IP) orelse IP == any orelse IP == loopback,
1047                             is_integer(Port) ->
1048           {ok,S} = gen_sctp:open(Port, [{recbuf,65536}, {ip,IP}]),
1049           io:format("Listening on ~w:~w. ~w~n", [IP,Port,S]),
1050           ok     = gen_sctp:listen(S, true),
1051           server_loop(S).
1052
1053       server_loop(S) ->
1054           case gen_sctp:recv(S) of
1055           {error, Error} ->
1056               io:format("SCTP RECV ERROR: ~p~n", [Error]);
1057           Data ->
1058               io:format("Received: ~p~n", [Data])
1059           end,
1060           server_loop(S).
1061
1062       Example of an Erlang SCTP client interacting with the above server. No‐
1063       tice that in this example the client creates an  association  with  the
1064       server  with  5  outbound  streams. Therefore, sending of "Test 0" over
1065       stream 0 succeeds, but sending of "Test 5" over  stream  5  fails.  The
1066       client  then  aborts  the association, which results in that the corre‐
1067       sponding event is received on the server side.
1068
1069       -module(sctp_client).
1070
1071       -export([client/0, client/1, client/2]).
1072       -include_lib("kernel/include/inet.hrl").
1073       -include_lib("kernel/include/inet_sctp.hrl").
1074
1075       client() ->
1076           client([localhost]).
1077
1078       client([Host]) ->
1079           client(Host, 2006);
1080
1081       client([Host, Port]) when is_list(Host), is_list(Port) ->
1082           client(Host,list_to_integer(Port)),
1083           init:stop().
1084
1085       client(Host, Port) when is_integer(Port) ->
1086           {ok,S}     = gen_sctp:open(),
1087           {ok,Assoc} = gen_sctp:connect
1088               (S, Host, Port, [{sctp_initmsg,#sctp_initmsg{num_ostreams=5}}]),
1089           io:format("Connection Successful, Assoc=~p~n", [Assoc]),
1090
1091           io:write(gen_sctp:send(S, Assoc, 0, <<"Test 0">>)),
1092           io:nl(),
1093           timer:sleep(10000),
1094           io:write(gen_sctp:send(S, Assoc, 5, <<"Test 5">>)),
1095           io:nl(),
1096           timer:sleep(10000),
1097           io:write(gen_sctp:abort(S, Assoc)),
1098           io:nl(),
1099
1100           timer:sleep(1000),
1101           gen_sctp:close(S).
1102
1103       A simple Erlang SCTP client that uses the connect_init API:
1104
1105       -module(ex3).
1106
1107       -export([client/4]).
1108       -include_lib("kernel/include/inet.hrl").
1109       -include_lib("kernel/include/inet_sctp.hrl").
1110
1111       client(Peer1, Port1, Peer2, Port2)
1112         when is_tuple(Peer1), is_integer(Port1), is_tuple(Peer2), is_integer(Port2) ->
1113           {ok,S}     = gen_sctp:open(),
1114           SctpInitMsgOpt = {sctp_initmsg,#sctp_initmsg{num_ostreams=5}},
1115           ActiveOpt = {active, true},
1116           Opts = [SctpInitMsgOpt, ActiveOpt],
1117           ok = gen_sctp:connect(S, Peer1, Port1, Opts),
1118           ok = gen_sctp:connect(S, Peer2, Port2, Opts),
1119           io:format("Connections initiated~n", []),
1120           client_loop(S, Peer1, Port1, undefined, Peer2, Port2, undefined).
1121
1122       client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2, AssocId2) ->
1123           receive
1124               {sctp, S, Peer1, Port1, {_Anc, SAC}}
1125                 when is_record(SAC, sctp_assoc_change), AssocId1 == undefined ->
1126                   io:format("Association 1 connect result: ~p. AssocId: ~p~n",
1127                             [SAC#sctp_assoc_change.state,
1128                              SAC#sctp_assoc_change.assoc_id]),
1129                   client_loop(S, Peer1, Port1, SAC#sctp_assoc_change.assoc_id,
1130                               Peer2, Port2, AssocId2);
1131
1132               {sctp, S, Peer2, Port2, {_Anc, SAC}}
1133                 when is_record(SAC, sctp_assoc_change), AssocId2 == undefined ->
1134                   io:format("Association 2 connect result: ~p. AssocId: ~p~n",
1135                             [SAC#sctp_assoc_change.state, SAC#sctp_assoc_change.assoc_id]),
1136                   client_loop(S, Peer1, Port1, AssocId1, Peer2, Port2,
1137                              SAC#sctp_assoc_change.assoc_id);
1138
1139               {sctp, S, Peer1, Port1, Data} ->
1140                   io:format("Association 1: received ~p~n", [Data]),
1141                   client_loop(S, Peer1, Port1, AssocId1,
1142                               Peer2, Port2, AssocId2);
1143
1144               {sctp, S, Peer2, Port2, Data} ->
1145                   io:format("Association 2: received ~p~n", [Data]),
1146                   client_loop(S, Peer1, Port1, AssocId1,
1147                               Peer2, Port2, AssocId2);
1148
1149               Other ->
1150                   io:format("Other ~p~n", [Other]),
1151                   client_loop(S, Peer1, Port1, AssocId1,
1152                               Peer2, Port2, AssocId2)
1153
1154           after 5000 ->
1155                   ok
1156           end.
1157

SEE ALSO

1159       gen_tcp(3), gen_udp(3), inet(3), RFC 2960 (Stream Control  Transmission
1160       Protocol), Sockets API Extensions for SCTP
1161
1162
1163
1164Ericsson AB                      kernel 8.1.3                      gen_sctp(3)
Impressum