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
162              expressed  in milliseconds. A socket can be associated with mul‐
163              tiple 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
168              default values from RFC 4960 are used), can result in  inconsis‐
169              tent or incorrect return values. This is especially relevant for
170              associations sharing the same Socket (that  is,  source  address
171              and  port),  as  the  controlling process blocks until connect/*
172              returns. connect_init/* provides  an  alternative  without  this
173              limitation.
174
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             = atom(),
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.
230
231       connect_init(Socket, Addr, Port, Opts) ->
232                       ok | {error, inet:posix()}
233
234              Types:
235
236                 Socket = sctp_socket()
237                 Addr = inet:ip_address() | inet:hostname()
238                 Port = inet:port_number()
239                 Opts = [option()]
240
241              Same as connect_init(Socket, Addr, Port, Opts, infinity).
242
243       connect_init(Socket, Addr, Port, Opts, Timeout) ->
244                       ok | {error, inet:posix()}
245
246              Types:
247
248                 Socket = sctp_socket()
249                 Addr = inet:ip_address() | inet:hostname()
250                 Port = inet:port_number()
251                 Opts = [option()]
252                 Timeout = timeout()
253
254              Initiates  a  new  association  for socket Socket, with the peer
255              (SCTP server socket) specified by Addr and Port.
256
257              The fundamental difference between this  API  and  connect/*  is
258              that  the  return  value is that of the underlying OS connect(2)
259              system call. If ok is returned, the result  of  the  association
260              establishment   is   received  by  the  calling  process  as  an
261              #sctp_assoc_change{} event. The calling process must be prepared
262              to  receive  this, or poll for it using recv/*, depending on the
263              value of the active option.
264
265              The parameters are as described in connect/*, except the Timeout
266              value.
267
268              The  timer associated with Timeout only supervises IP resolution
269              of Addr.
270
271       controlling_process(Socket, Pid) -> ok | {error, Reason}
272
273              Types:
274
275                 Socket = sctp_socket()
276                 Pid = pid()
277                 Reason = closed | not_owner | badarg | inet:posix()
278
279              Assigns a new controlling process Pid to Socket. Same  implemen‐
280              tation as gen_udp:controlling_process/2.
281
282       eof(Socket, Assoc) -> ok | {error, Reason}
283
284              Types:
285
286                 Socket = sctp_socket()
287                 Assoc = #sctp_assoc_change{}
288                 Reason = term()
289
290              Gracefully  terminates  the association specified by Assoc, with
291              flushing of all unsent data. The  socket  itself  remains  open.
292              Other  associations  opened  on this socket are still valid. The
293              socket can be used in new associations.
294
295       error_string(ErrorNumber) -> ok | string() | unknown_error
296
297              Types:
298
299                 ErrorNumber = integer()
300
301              Translates   an   SCTP   error   number   from,   for   example,
302              #sctp_remote_error{}  or #sctp_send_failed{} into an explanatory
303              string, or one of the atoms ok for no error or undefined for  an
304              unrecognized error.
305
306       listen(Socket, IsServer) -> ok | {error, Reason}
307
308       listen(Socket, Backlog) -> ok | {error, Reason}
309
310              Types:
311
312                 Socket = sctp_socket()
313                 Backlog = integer()
314                 Reason = term()
315
316              Sets  up a socket to listen on the IP address and port number it
317              is bound to.
318
319              For type seqpacket, sockets (the default) IsServer must be  true
320              or false. In contrast to TCP, there is no listening queue length
321              in SCTP. If IsServer is true, the socket  accepts  new  associa‐
322              tions, that is, it becomes an SCTP server socket.
323
324              For type stream, sockets Backlog define the backlog queue length
325              just like in TCP.
326
327       open() -> {ok, Socket} | {error, inet:posix()}
328
329       open(Port) -> {ok, Socket} | {error, inet:posix()}
330
331       open(Opts) -> {ok, Socket} | {error, inet:posix()}
332
333       open(Port, Opts) -> {ok, Socket} | {error, inet:posix()}
334
335              Types:
336
337                 Opts = [Opt]
338                 Opt =
339                     {ip, IP} |
340                     {ifaddr, IP} |
341                     inet:address_family() |
342                     {port, Port} |
343                     {type, SockType} |
344                     option()
345                 IP = inet:ip_address() | any | loopback
346                 Port = inet:port_number()
347                 SockType = seqpacket | stream
348                 Socket = sctp_socket()
349
350              Creates an SCTP socket and binds it to the local addresses spec‐
351              ified by all {ip,IP} (or synonymously {ifaddr,IP}) options (this
352              feature is called SCTP multi-homing). The default  IP  and  Port
353              are  any  and 0, meaning bind to all local addresses on any free
354              port.
355
356              Other options:
357
358                inet6:
359                  Sets up the socket for IPv6.
360
361                inet:
362                  Sets up the socket for IPv4. This is the default.
363
364              A default set of socket options  is  used.  In  particular,  the
365              socket  is opened in binary and passive mode, with SockType seq‐
366              packet, and with reasonably large kernel and driver buffers.
367
368              If the socket is in passive mode data can  be  received  through
369              the recv/1,2 calls.
370
371              If  the socket is in active mode data received data is delivered
372              to the controlling process as messages:
373
374              {sctp, Socket, FromIP, FromPort, {AncData, Data}}
375
376
377              See recv/1,2 for a description of the message fields.
378
379          Note:
380              This message format  unfortunately  differs  slightly  from  the
381              gen_udp  message  format  with  ancillary  data,  and  from  the
382              recv/1,2 return tuple format.
383
384
385       peeloff(Socket, Assoc) -> {ok, NewSocket} | {error, Reason}
386
387              Types:
388
389                 Socket = sctp_socket()
390                 Assoc = #sctp_assoc_change{} | assoc_id()
391                 NewSocket = sctp_socket()
392                 Reason = term()
393
394              Branches off an existing association Assoc in a socket Socket of
395              type  seqpacket  (one-to-many style) into a new socket NewSocket
396              of type stream (one-to-one style).
397
398              The  existing  association  argument  Assoc  can  be  either   a
399              #sctp_assoc_change{}  record  as  returned  from,  for  example,
400              recv/*, connect/*, or from a listening socket in active mode. It
401              can also be just the field assoc_id integer from such a record.
402
403       recv(Socket) ->
404               {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
405
406       recv(Socket, Timeout) ->
407               {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}
408
409              Types:
410
411                 Socket = sctp_socket()
412                 Timeout = timeout()
413                 FromIP = inet:ip_address()
414                 FromPort = inet:port_number()
415                 AncData = [#sctp_sndrcvinfo{} | inet:ancillary_data()]
416                 Data =
417                     binary() |
418                     string() |
419                     #sctp_sndrcvinfo{} |
420                     #sctp_assoc_change{} |
421                     #sctp_paddr_change{} |
422                     #sctp_adaptation_event{}
423                 Reason =
424                     inet:posix() |
425                     #sctp_send_failed{} |
426                     #sctp_paddr_change{} |
427                     #sctp_pdapi_event{} |
428                     #sctp_remote_error{} |
429                     #sctp_shutdown_event{}
430
431              Receives the Data message from any association of the socket. If
432              the receive times out, {error,timeout} is returned. The  default
433              time-out  is  infinity. FromIP and FromPort indicate the address
434              of the sender.
435
436              AncData is a list of ancillary data items that can  be  received
437              along  with  the main Data. This list can be empty, or contain a
438              single #sctp_sndrcvinfo{} record if receiving of such  ancillary
439              data  is  enabled  (see  option  sctp_events).  It is enabled by
440              default, as such ancillary data provides an easy way  of  deter‐
441              mining  the  association  and  stream  over which the message is
442              received. (An alternative way is to get the association ID  from
443              FromIP and FromPort using socket option sctp_get_peer_addr_info,
444              but this does still not produce the stream number).
445
446              AncData may also  contain   ancillary  data    from  the  socket
447              options  recvtos, recvtclass or recvttl, if that is supported by
448              the platform for the socket.
449
450              The Data received can be a binary() or a list() of bytes  (inte‐
451              gers  in  the range 0 through 255) depending on the socket mode,
452              or an SCTP event.
453
454              Possible SCTP events:
455
456                * #sctp_sndrcvinfo{}
457
458                * #sctp_assoc_change{}
459
460                *
461
462
463                #sctp_paddr_change{
464                      addr      = {ip_address(),port()},
465                      state     = atom(),
466                      error     = integer(),
467                      assoc_id  = assoc_id()
468                }
469
470                  Indicates change of the status of the IP address of the peer
471                  specified by addr within association assoc_id. Possible val‐
472                  ues of state (mostly self-explanatory) include:
473
474                  addr_unreachable:
475
476
477                  addr_available:
478
479
480                  addr_removed:
481
482
483                  addr_added:
484
485
486                  addr_made_prim:
487
488
489                  addr_confirmed:
490
491
492                  In case of an error (for example,  addr_unreachable),  field
493                  error  provides  more  diagnostics.  In  such  cases,  event
494                  #sctp_paddr_change{}  is  automatically  converted  into  an
495                  error  term  returned  by recv. The error field value can be
496                  converted into a string using error_string/1.
497
498                *
499
500
501                #sctp_send_failed{
502                      flags     = true | false,
503                      error     = integer(),
504                      info      = #sctp_sndrcvinfo{},
505                      assoc_id  = assoc_id()
506                      data      = binary()
507                }
508
509                  The sender can receive this event if a send operation fails.
510
511                  flags:
512                    A Boolean specifying if the data has been transmitted over
513                    the wire.
514
515                  error:
516                    Provides extended diagnostics, use error_string/1.
517
518                  info:
519                    The  original #sctp_sndrcvinfo{} record used in the failed
520                    send/*.
521
522                  data:
523                    The whole original data chunk attempted to be sent.
524
525                  In the current implementation of  the  Erlang/SCTP  binding,
526                  this  event  is  internally  converted  into  an  error term
527                  returned by recv/*.
528
529                *
530
531
532                #sctp_adaptation_event{
533                      adaptation_ind = integer(),
534                      assoc_id       = assoc_id()
535                }
536
537                  Delivered when a peer sends an adaptation  layer  indication
538                  parameter (configured through option sctp_adaptation_layer).
539                  Notice  that  with  the  current   implementation   of   the
540                  Erlang/SCTP binding, this event is disabled by default.
541
542                *
543
544
545                #sctp_pdapi_event{
546                      indication = sctp_partial_delivery_aborted,
547                      assoc_id   = assoc_id()
548                }
549
550                  A partial delivery failure. In the current implementation of
551                  the Erlang/SCTP binding, this event is internally  converted
552                  into an error term returned by recv/*.
553
554       send(Socket, SndRcvInfo, Data) -> ok | {error, Reason}
555
556              Types:
557
558                 Socket = sctp_socket()
559                 SndRcvInfo = #sctp_sndrcvinfo{}
560                 Data = binary() | iolist()
561                 Reason = term()
562
563              Sends  the  Data  message  with  all  sending  parameters from a
564              #sctp_sndrcvinfo{} record. This way, the user  can  specify  the
565              PPID (passed to the remote end) and context (passed to the local
566              SCTP layer), which can be used, for example, for error identifi‐
567              cation.  However,  such  a  fine level of user control is rarely
568              required. The function send/4 is sufficient  for  most  applica‐
569              tions.
570
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
588       using  open/1,2  or  inet:setopts/2,  retrieved  using  inet:getopts/2.
589       Options can be changed when calling connect/4,5.
590
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
598             explicit  recv  call  to  retrieve  the  available  data from the
599             socket.
600
601           * If true|once|N (active modes) received data or events are sent to
602             the owning process. See open/0..2 for the message format.
603
604           * If true (full active mode) there is no flow control.
605
606       Note:
607           Note  that this can cause the message queue to overflow causing for
608           example the virtual machine to run out of memory and crash.
609
610
611           * If once, only one message is automatically placed in the  message
612             queue, and after that the mode is automatically reset to passive.
613             This provides flow control and the possibility for  the  receiver
614             to  listen  for  its  incoming  SCTP  data interleaved with other
615             inter-process messages.
616
617           * If active is specified as an integer N in  the  range  -32768  to
618             32767  (inclusive), that number is added to the socket's counting
619             of data messages to be delivered to the controlling  process.  If
620             the  result  of  the addition is negative, the count is set to 0.
621             Once the count reaches 0, either through the delivery of messages
622             or  by  being explicitly set with inet:setopts/2, the socket mode
623             is automatically reset  to  passive  ({active,  false}).  When  a
624             socket  in this active mode transitions to passive mode, the mes‐
625             sage {sctp_passive, Socket} is sent to the controlling process to
626             notify it that if it wants to receive more data messages from the
627             socket, it must call inet:setopts/2 to set the socket  back  into
628             an active mode.
629
630         {tos, integer()}:
631           Sets  the  Type-Of-Service field on the IP datagrams that are sent,
632           to the specified value. This effectively determines  a  prioritiza‐
633           tion  policy  for  the  outbound packets. The acceptable values are
634           system-dependent.
635
636         {priority, integer()}:
637           A protocol-independent equivalent of tos  above.  Setting  priority
638           implies setting tos as well.
639
640         {dontroute, true|false}:
641           Defaults  to  false.  If  true,  the  kernel  does not send packets
642           through any gateway, only sends them to directly connected hosts.
643
644         {reuseaddr, true|false}:
645           Defaults to false. If true, the local binding address {IP,Port}  of
646           the   socket  can  be  reused  immediately.  No  waiting  in  state
647           CLOSE_WAIT  is  performed  (can  be  required  for  high-throughput
648           servers).
649
650         {sndbuf, integer()}:
651           The  size,  in bytes, of the OS kernel send buffer for this socket.
652           Sending errors would occur for datagrams larger  than  val(sndbuf).
653           Setting this option also adjusts the size of the driver buffer (see
654           buffer above).
655
656         {recbuf, integer()}:
657           The size, in bytes, of  the  OS  kernel  receive  buffer  for  this
658           socket.  Sending  errors  would  occur  for  datagrams  larger than
659           val(recbuf). Setting this option  also  adjusts  the  size  of  the
660           driver buffer (see buffer above).
661
662         {sctp_module, module()}:
663           Overrides  which callback module is used. Defaults to inet_sctp for
664           IPv4 and inet6_sctp for IPv6.
665
666         {sctp_rtoinfo, #sctp_rtoinfo{}}:
667
668
669         #sctp_rtoinfo{
670               assoc_id = assoc_id(),
671               initial  = integer(),
672               max      = integer(),
673               min      = integer()
674         }
675
676           Determines retransmission time-out parameters, in milliseconds, for
677           the association(s) specified by assoc_id.
678
679           assoc_id  =  0 (default) indicates the whole endpoint. See RFC 2960
680           and Sockets API Extensions for SCTP for the exact semantics of  the
681           field values.
682
683         {sctp_associnfo, #sctp_assocparams{}}:
684
685
686         #sctp_assocparams{
687               assoc_id                 = assoc_id(),
688               asocmaxrxt               = integer(),
689               number_peer_destinations = integer(),
690               peer_rwnd                = integer(),
691               local_rwnd               = integer(),
692               cookie_life              = integer()
693         }
694
695           Determines  association parameters for the association(s) specified
696           by assoc_id.
697
698           assoc_id = 0 (default) indicates the whole  endpoint.  See  Sockets
699           API  Extensions  for  SCTP  for  the discussion of their semantics.
700           Rarely used.
701
702         {sctp_initmsg, #sctp_initmsg{}}:
703
704
705         #sctp_initmsg{
706              num_ostreams   = integer(),
707              max_instreams  = integer(),
708              max_attempts   = integer(),
709              max_init_timeo = integer()
710         }
711
712           Determines the default parameters that this socket tries to negoti‐
713           ate  with its peer while establishing an association with it. Is to
714           be set after open/* but before the first connect/*. #sctp_initmsg{}
715           can also be used as ancillary data with the first call of send/* to
716           a new peer (when a new association is created).
717
718           num_ostreams:
719             Number of outbound streams
720
721           max_instreams:
722             Maximum number of inbound streams
723
724           max_attempts:
725             Maximum retransmissions while establishing an association
726
727           max_init_timeo:
728             Time-out, in milliseconds, for establishing an association
729
730         {sctp_autoclose, integer() >= 0}:
731           Determines the time, in seconds, after which an idle association is
732           automatically  closed.  0 means that the association is never auto‐
733           matically closed.
734
735         {sctp_nodelay, true|false}:
736           Turns on|off the Nagle algorithm for  merging  small  packets  into
737           larger ones. This improves throughput at the expense of latency.
738
739         {sctp_disable_fragments, true|false}:
740           If  true,  induces  an error on an attempt to send a message larger
741           than  the  current  PMTU  size  (which  would  require   fragmenta‐
742           tion/reassembling).  Notice  that  message  fragmentation  does not
743           affect the logical atomicity of its delivery; this option  is  pro‐
744           vided for performance reasons only.
745
746         {sctp_i_want_mapped_v4_addr, true|false}:
747           Turns on|off automatic mapping of IPv4 addresses into IPv6 ones (if
748           the socket address family is AF_INET6).
749
750         {sctp_maxseg, integer()}:
751           Determines the maximum chunk size if message fragmentation is used.
752           If 0, the chunk size is limited by the Path MTU only.
753
754         {sctp_primary_addr, #sctp_prim{}}:
755
756
757         #sctp_prim{
758               assoc_id = assoc_id(),
759               addr     = {IP, Port}
760         }
761          IP = ip_address()
762          Port = port_number()
763
764           For the association specified by assoc_id, {IP,Port} must be one of
765           the peer addresses.  This  option  determines  that  the  specified
766           address  is  treated by the local SCTP stack as the primary address
767           of the peer.
768
769         {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}:
770
771
772         #sctp_setpeerprim{
773               assoc_id = assoc_id(),
774               addr     = {IP, Port}
775         }
776          IP = ip_address()
777          Port = port_number()
778
779           When set, informs the peer to use {IP, Port} as the primary address
780           of the local endpoint for the association specified by assoc_id.
781
782         {sctp_adaptation_layer, #sctp_setadaptation{}}:
783
784
785         #sctp_setadaptation{
786               adaptation_ind = integer()
787         }
788
789           When set, requests that the local endpoint uses the value specified
790           by adaptation_ind as the Adaptation Indication parameter for estab‐
791           lishing new associations. For details, see RFC 2960 and Sockets API
792           Extenstions for SCTP.
793
794         {sctp_peer_addr_params, #sctp_paddrparams{}}:
795
796
797         #sctp_paddrparams{
798               assoc_id   = assoc_id(),
799               address    = {IP, Port},
800               hbinterval = integer(),
801               pathmaxrxt = integer(),
802               pathmtu    = integer(),
803               sackdelay  = integer(),
804               flags      = list()
805         }
806         IP = ip_address()
807         Port = port_number()
808
809           Determines various per-address parameters for the association spec‐
810           ified  by  assoc_id and the peer address address (the SCTP protocol
811           supports multi-homing, so more than one address can correspond to a
812           specified association).
813
814           hbinterval:
815             Heartbeat interval, in milliseconds
816
817           pathmaxrxt:
818             Maximum  number of retransmissions before this address is consid‐
819             ered unreachable (and an alternative address is selected)
820
821           pathmtu:
822             Fixed Path MTU, if automatic discovery  is  disabled  (see  flags
823             below)
824
825           sackdelay:
826             Delay,  in  milliseconds,  for  SAC  messages  (if  the  delay is
827             enabled, see flags below)
828
829           flags:
830             The following flags are available:
831
832             hb_enable:
833               Enables heartbeat
834
835             hb_disable:
836               Disables heartbeat
837
838             hb_demand:
839               Initiates heartbeat immediately
840
841             pmtud_enable:
842               Enables automatic Path MTU discovery
843
844             pmtud_disable:
845               Disables automatic Path MTU discovery
846
847             sackdelay_enable:
848               Enables SAC delay
849
850             sackdelay_disable:
851               Disables SAC delay
852
853         {sctp_default_send_param, #sctp_sndrcvinfo{}}:
854
855
856         #sctp_sndrcvinfo{
857               stream     = integer(),
858               ssn        = integer(),
859               flags      = list(),
860               ppid       = integer(),
861               context    = integer(),
862               timetolive = integer(),
863               tsn        = integer(),
864               cumtsn     = integer(),
865               assoc_id   = assoc_id()
866         }
867
868           #sctp_sndrcvinfo{} is used both  in  this  socket  option,  and  as
869           ancillary  data  while sending or receiving SCTP messages. When set
870           as an option, it provides default values for subsequent send  calls
871           on the association specified by assoc_id.
872
873           assoc_id = 0 (default) indicates the whole endpoint.
874
875           The following fields typically must be specified by the sender:
876
877           sinfo_stream:
878             Stream  number  (0-base)  within the association to send the mes‐
879             sages through;
880
881           sinfo_flags:
882             The following flags are recognised:
883
884             unordered:
885               The message is to be sent unordered
886
887             addr_over:
888               The address specified  in  send  overwrites  the  primary  peer
889               address
890
891             abort:
892               Aborts the current association without flushing any unsent data
893
894             eof:
895               Gracefully shuts down the current association, with flushing of
896               unsent data
897
898             Other fields are rarely used. For complete information,  see  RFC
899             2960 and Sockets API Extensions for SCTP.
900
901         {sctp_events, #sctp_event_subscribe{}}:
902
903
904         #sctp_event_subscribe{
905                 data_io_event          = true | false,
906                 association_event      = true | false,
907                 address_event          = true | false,
908                 send_failure_event     = true | false,
909                 peer_error_event       = true | false,
910                 shutdown_event         = true | false,
911                 partial_delivery_event = true | false,
912                 adaptation_layer_event = true | false
913         }
914
915           This  option  determines  which  SCTP  Events  are  to  be received
916           (through recv/*)  along  with  the  data.  The  only  exception  is
917           data_io_event, which enables or disables receiving of #sctp_sndrcv‐
918           info{} ancillary data, not events. By  default,  all  flags  except
919           adaptation_layer_event are enabled, although sctp_data_io_event and
920           association_event are used by the driver itself and not exported to
921           the user level.
922
923         {sctp_delayed_ack_time, #sctp_assoc_value{}}:
924
925
926         #sctp_assoc_value{
927               assoc_id    = assoc_id(),
928               assoc_value = integer()
929         }
930
931           Rarely  used. Determines the ACK time (specified by assoc_value, in
932           milliseconds) for the specified association or the  whole  endpoint
933           if assoc_value = 0 (default).
934
935         {sctp_status, #sctp_status{}}:
936
937
938         #sctp_status{
939               assoc_id            = assoc_id(),
940               state               = atom(),
941               rwnd                = integer(),
942               unackdata           = integer(),
943               penddata            = integer(),
944               instrms             = integer(),
945               outstrms            = integer(),
946               fragmentation_point = integer(),
947               primary             = #sctp_paddrinfo{}
948         }
949
950           This  option  is  read-only.  It  determines the status of the SCTP
951           association specified by assoc_id. The following are  the  possible
952           values  of  state  (the state designations are mostly self-explana‐
953           tory):
954
955           sctp_state_empty:
956             Default. Means that no other state is active.
957
958           sctp_state_closed:
959
960
961           sctp_state_cookie_wait:
962
963
964           sctp_state_cookie_echoed:
965
966
967           sctp_state_established:
968
969
970           sctp_state_shutdown_pending:
971
972
973           sctp_state_shutdown_sent:
974
975
976           sctp_state_shutdown_received:
977
978
979           sctp_state_shutdown_ack_sent:
980
981
982           Semantics of the other fields:
983
984           sstat_rwnd:
985             Current receiver window size of the association
986
987           sstat_unackdata:
988             Number of unacked data chunks
989
990           sstat_penddata:
991             Number of data chunks pending receipt
992
993           sstat_instrms:
994             Number of inbound streams
995
996           sstat_outstrms:
997             Number of outbound streams
998
999           sstat_fragmentation_point:
1000             Message size at which SCTP fragmentation occurs
1001
1002           sstat_primary:
1003             Information on the current primary peer address  (see  below  for
1004             the format of #sctp_paddrinfo{})
1005
1006         {sctp_get_peer_addr_info, #sctp_paddrinfo{}}:
1007
1008
1009         #sctp_paddrinfo{
1010               assoc_id  = assoc_id(),
1011               address   = {IP, Port},
1012               state     = inactive | active | unconfirmed,
1013               cwnd      = integer(),
1014               srtt      = integer(),
1015               rto       = integer(),
1016               mtu       = integer()
1017         }
1018         IP = ip_address()
1019         Port = port_number()
1020
1021           This  option is read-only. It determines the parameters specific to
1022           the peer address specified by address within the association speci‐
1023           fied  by  assoc_id.  Field  address fmust be set by the caller; all
1024           other fields are filled in on return. If assoc_id  =  0  (default),
1025           the  address  is  automatically  translated  into the corresponding
1026           association ID. This option is rarely used. For  the  semantics  of
1027           all fields, see RFC 2960 and Sockets API Extensions for SCTP.
1028

SCTP EXAMPLES

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

SEE ALSO

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