1SCTP(7)                    Linux Programmer's Manual                   SCTP(7)
2
3
4

NAME

6       sctp - SCTP protocol.
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <netinet/in.h>
11       #include <netinet/sctp.h>
12
13       sctp_socket = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
14       sctp_socket = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
15

DESCRIPTION

17       This  is  an  implementation of the SCTP protocol as defined in RFC2960
18       and RFC3309. It is a message oriented, reliable transport protocol with
19       direct  support for multihoming that runs on top of ip(7), and supports
20       both v4 and v6 versions.
21
22       Like TCP, SCTP provides reliable,  connection  oriented  data  delivery
23       with  congestion control. Unlike TCP, SCTP also provides message bound‐
24       ary preservation, ordered and unordered message delivery, multi-stream‐
25       ing  and  multi-homing.  Detection of data corruption, loss of data and
26       duplication of data is achieved by using checksums  and  sequence  num‐
27       bers.  A  selective retransmission mechanism is applied to correct loss
28       or corruption of data.
29
30       This implementation supports a mapping of  SCTP  into  sockets  API  as
31       defined  in  the  draft-ietf-tsvwg-sctpsocket-10.txt(Sockets API exten‐
32       sions for SCTP).  Two styles of interfaces are supported.
33
34       A one-to-many style interface  with  1  to  MANY  relationship  between
35       socket  and  associations  where  the  outbound  association  setup  is
36       implicit. The syntax of a one-to-many style socket() call is
37
38       sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
39
40       A typical server in this style  uses  the  following  socket  calls  in
41       sequence to prepare an endpoint for servicing requests.
42
43            1. socket()
44            2. bind()
45            3. listen()
46            4. recvmsg()
47            5. sendmsg()
48            6. close()
49
50       A typical client uses the following calls in sequence to setup an asso‐
51       ciation with a server to request services.
52
53            1. socket()
54            2. sendmsg()
55            3. recvmsg()
56            4. close()
57
58       A one-to-one style interface with a 1 to 1 relationship between  socket
59       and association which enables existing TCP applications to be ported to
60       SCTP with very little effort. The syntax of a one-to-one style socket()
61       call is
62
63       sd = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
64
65       A  typical  server  in  one-to-one style uses the following system call
66       sequence to prepare an SCTP endpoint for servicing requests:
67
68            1. socket()
69            2. bind()
70            3. listen()
71            4. accept()
72
73       The accept() call blocks until a new association is set up. It  returns
74       with  a  new  socket  descriptor.  The  server then uses the new socket
75       descriptor to communicate with the  client,  using  recv()  and  send()
76       calls to get requests and send back responses. Then it calls
77
78            5. close()
79
80       to  terminate the association. A typical client uses the following sys‐
81       tem call sequence to setup an association with a server to request ser‐
82       vices:
83
84            1. socket()
85            2. connect()
86
87       After returning from connect(), the client uses send() and recv() calls
88       to send out requests and receive responses from the server. The  client
89       calls
90
91            3. close()
92
93       to terminate this association when done.
94

ADDRESS FORMATS

96       SCTP is built on top of IP (see ip(7)).  The address formats defined by
97       ip(7) apply to SCTP.  SCTP only supports point-to-point  communication;
98       broadcasting and multicasting are not supported.
99

SYSCTLS

101       These  variables  can  be accessed by the /proc/sys/net/sctp/* files or
102       with the sysctl(2) interface.  In addition, most IP sysctls also  apply
103       to SCTP. See ip(7).
104
105       Please  check  kernel documentation for this, at Documentation/network‐
106       ing/ip-sysctl.txt.
107

STATISTICS

109       These variables can be accessed by the /proc/net/sctp/* files.
110
111       assocs Displays the following information  about  the  active  associa‐
112              tions.   assoc ptr, sock ptr, socket style, sock state, associa‐
113              tion state, hash  bucket,  association  id,  bytes  in  transmit
114              queue,  bytes  in  receive  queue,  user  id, inode, local port,
115              remote port, local addresses and remote addresses.
116
117       eps    Displays the following information about the  active  endpoints.
118              endpoint  ptr,  sock ptr, socket style, sock state, hash bucket,
119              local port, user id, inode and local addresses.
120
121       snmp   Displays the following statistics related to SCTP states,  pack‐
122              ets and chunks.
123
124
125       SctpCurrEstab
126              The number of associations for which the current state is
127              either ESTABLISHED, SHUTDOWN-RECEIVED  or  SHUTDOWN-PEND‐
128              ING.
129
130       SctpActiveEstabs
131              The  number of times that associations have made a direct
132              transition to the  ESTABLISHED  state  from  the  COOKIE-
133              ECHOED  state.  The upper layer initiated the association
134              attempt.
135
136       SctpPassiveEstabs
137              The number of times that associations have made a  direct
138              transition  to  the  ESTABLISHED  state  from  the CLOSED
139              state. The  remote  endpoint  initiated  the  association
140              attempt.
141
142       SctpAborteds
143              The  number of times that associations have made a direct
144              transition to the CLOSED state from any state  using  the
145              primitive 'ABORT'. Ungraceful termination of the associa‐
146              tion.
147
148       SctpShutdowns
149              The number of times that associations have made a  direct
150              transition  to the CLOSED state from either the SHUTDOWN-
151              SENT state or the SHUTDOWN-ACK-SENT state. Graceful  ter‐
152              mination of the association.
153
154       SctpOutOfBlues
155              The  number  of  out  of the blue packets received by the
156              host. An out of the blue packet is an  SCTP  packet  cor‐
157              rectly  formed,  including  the  proper checksum, but for
158              which the receiver was unable to identify an  appropriate
159              association.
160
161       SctpChecksumErrors
162              The  number  of  SCTP  packets  received  with an invalid
163              checksum.
164
165       SctpOutCtrlChunks
166              The number of SCTP control chunks  sent  (retransmissions
167              are  not included).  Control chunks are those chunks dif‐
168              ferent from DATA.
169
170       SctpOutOrderChunks
171              The number of SCTP ordered data chunks sent  (retransmis‐
172              sions are not included).
173
174       SctpOutUnorderChunks
175              The  number of SCTP unordered chunks(data chunks in which
176              the U bit is set to  1)  sent  (retransmissions  are  not
177              included).
178
179       SctpInCtrlChunks
180              The  number of SCTP control chunks received (no duplicate
181              chunks included).
182
183       SctpInOrderChunks
184              The number of  SCTP  ordered  data  chunks  received  (no
185              duplicate chunks included).
186
187       SctpInUnorderChunks
188              The  number of SCTP unordered chunks(data chunks in which
189              the U bit is set to  1)  received  (no  duplicate  chunks
190              included).
191
192       SctpFragUsrMsgs
193              The  number  of  user messages that have to be fragmented
194              because of the MTU.
195
196       SctpReasmUsrMsgs
197              The number of user messages reassembled, after conversion
198              into DATA chunks.
199
200       SctpOutSCTPPacks
201              The  number  of  SCTP  packets  sent.  Retransmitted DATA
202              chunks are included.
203
204       SctpInSCTPPacks
205              The number  of  SCTP  packets  received.  Duplicates  are
206              included.
207

SOCKET OPTIONS

209       To  set  or get a SCTP socket option, call getsockopt(2) to read
210       or setsockopt(2) to write the option with the option level argu‐
211       ment set to SOL_SCTP.
212
213       SCTP_RTOINFO.
214              This option is used to get or set the protocol parameters
215              used to initialize and bound retransmission  timout(RTO).
216              The      structure      sctp_rtoinfo      defined      in
217              /usr/include/netinet/sctp.h is used to access and  modify
218              these parameters.
219
220       SCTP_ASSOCINFO
221              This option is used to both examine and set various asso‐
222              ciation   and   endpoint   parameters.   The    sturcture
223              sctp_assocparams  defined  in /usr/include/netinet/sctp.h
224              is used to access and modify these parameters.
225
226       SCTP_INITMSG
227              This option is used to get or set the protocol parameters
228              for the default association initialization. The structure
229              sctp_initmsg defined  in  /usr/include/netinet/sctp.h  is
230              used to access and modify these parameters.
231
232              Setting initialization parameters is effective only on an
233              unconnected socket (for one-to-many  style  sockets  only
234              future  associations  are  effected  by the change). With
235              one-to-one style sockets, this  option  is  inherited  by
236              sockets derived from a listener socket.
237
238       SCTP_NODELAY
239              Turn  on/off  any  Nagle-like  algorithm. This means that
240              packets are generally sent as soon  as  possible  and  no
241              unnecessary  delays  are  introduced, at the cost of more
242              packets in the network.  Expects an integer boolean flag.
243
244       SCTP_AUTOCLOSE
245              This socket option is applicable to the one-to-many style
246              socket only. When set it will cause associations that are
247              idle for more than the specified  number  of  seconds  to
248              automatically close. An association being idle is defined
249              an association that has NOT sent or received  user  data.
250              The  special value of 0 indicates that no automatic close
251              of any  associations  should  be  performed.  The  option
252              expects an integer defining the number of seconds of idle
253              time before an association is closed.
254
255       SCTP_SET_PEER_PRIMARY_ADDR
256              Requests that the peer mark the enclosed address  as  the
257              association  primary. The enclosed address must be one of
258              the association's locally bound addresses. The  structure
259              sctp_setpeerprim  defined  in /usr/include/netinet/sctp.h
260              is used to make a set peer primary request.
261
262       SCTP_PRIMARY_ADDR
263              Requests that the local SCTP stack use the enclosed  peer
264              address  as the association primary. The enclosed address
265              must be one of  the  association  peer's  addresses.  The
266              structure          sctp_prim          defined          in
267              /usr/include/netinet/sctp.h is used  to  make  a  get/set
268              primary request.
269
270       SCTP_DISABLE_FRAGMENTS
271              This  option  is  a  on/off flag and is passed an integer
272              where a non-zero is on and a zero is off. If  enabled  no
273              SCTP message fragmentation will be performed.  Instead if
274              a message being sent exceeds the current PMTU  size,  the
275              message  will  NOT be sent and an error will be indicated
276              to the user.
277
278       SCTP_PEER_ADDR_PARAMS
279              Using this option, applications  can  enable  or  disable
280              heartbeats for any peer address of an association, modify
281              an address's heartbeat interval, force a heartbeat to  be
282              sent immediately, and adjust the address's maximum number
283              of retransmissions sent before an address  is  considered
284              unreachable.  The  structure  sctp_paddrparams defined in
285              /usr/include/netinet/sctp.h is used to access and  modify
286              an address's parameters.
287
288       SCTP_DEFAULT_SEND_PARAM
289              Applications  that  wish  to use the sendto() system call
290              may wish to specify a  default  set  of  parameters  that
291              would  normally  be  supplied  through  the  inclusion of
292              ancillary data. This socket option allows such an  appli‐
293              cation  to set the default sctp_sndrcvinfo structure. The
294              application that wishes to use this socket option  simply
295              passes  in  to  this  call  the sctp_sndrcvinfo structure
296              defined in /usr/include/netinet/sctp.h. The input parame‐
297              ters   accepted   by   this  call  include  sinfo_stream,
298              sinfo_flags, sinfo_ppid, sinfo_context, sinfo_timetolive.
299              The  user  must  set the sinfo_assoc_id field to identify
300              the
301               association to affect if the caller is using the one-to-
302              many style.
303
304       SCTP_EVENTS
305              This  socket  option is used to specify various notifica‐
306              tions and ancillary data the user wishes to receive.  The
307              structure       sctp_event_subscribe      defined      in
308              /usr/include/netinet/sctp.h is used to access  or  modify
309              the events of interest to the user.
310
311       SCTP_I_WANT_MAPPED_V4_ADDR
312              This  socket  option  is a boolean flag which turns on or
313              off mapped V4 addresses. If this option is turned on  and
314              the  socket is type PF_INET6, then IPv4 addresses will be
315              mapped to V6 representation. If  this  option  is  turned
316              off,  then  no mapping will be done of V4 addresses and a
317              user  will  receive  both  PF_INET6  and   PF_INET   type
318              addresses on the socket.
319
320              By  default this option is turned on and expects an inte‐
321              ger to be passed where non-zero turns on the  option  and
322              zero turns off the option.
323
324       SCTP_MAXSEG
325              This  socket  option specifies the maximum size to put in
326              any outgoing SCTP DATA chunk. If a message is larger than
327              this  size  it will be fragmented by SCTP into the speci‐
328              fied size. Note that the underlying  SCTP  implementation
329              may  fragment  into smaller sized chunks when the PMTU of
330              the underlying association is smaller than the value  set
331              by the user. The option expects an integer.
332
333              The  default  value  for this option is 0 which indicates
334              the user is NOT limiting fragmentation and only the  PMTU
335              will effect SCTP's choice of DATA chunk size.
336
337       SCTP_STATUS
338              Applications  can  retrieve  current  status  information
339              about an association, including association  state,  peer
340              receiver  window size, number of unacked data chunks, and
341              number of data chunks pending receipt.  This  information
342              is  read-only.   The  structure  sctp_status  defined  in
343              /usr/include/netinet/sctp.h is used to access this infor‐
344              mation.
345
346       SCTP_GET_PEER_ADDR_INFO
347              Applications  can  retrieve  information about a specific
348              peer address of an association, including its  reachabil‐
349              ity  state,  congestion  window, and retransmission timer
350              values.  This information  is  read-only.  The  structure
351              sctp_paddr_info defined in /usr/include/netinet/sctp.h is
352              used to access this information.
353
354       SCTP_GET_ASSOC_STATS
355              Applications can retrieve  current  statistics  about  an
356              association,  including  SACKs  sent  and  received, SCTP
357              packets sent and received. The complete list can be found
358              in       /usr/include/netinet/sctp.h       in      struct
359              sctp_assoc_stats.
360

AUTHORS

362       Sridhar Samudrala <sri@us.ibm.com>
363

SEE ALSO

365       socket(7), socket(2), ip(7), bind(2), listen(2), accept(2), con‐
366       nect(2),   sendmsg(2),   recvmsg(2),  sysctl(2),  getsockopt(2),
367       sctp_bindx(3), sctp_connectx(3), sctp_sendmsg(3), sctp_sendv(3),
368       sctp_send(3),  sctp_recvmsg(3),  sctp_recvv(3), sctp_peeloff(3),
369       sctp_getladdrs(3), sctp_getpaddrs(3), sctp_opt_info(3).
370
371       RFC2960, RFC3309 for the SCTP specification.
372
373
374
375Linux Man Page                    2005-10-25                           SCTP(7)
Impressum