Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SCTP(4)		       FreeBSD Kernel Interfaces Manual		       SCTP(4)

NAME
     sctp -- Internet Stream Control Transmission Protocol

SYNOPSIS
     #include <sys/types.h>
     #include <sys/socket.h>
     #include <netinet/sctp.h>

     int
     socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP);

     int
     socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);

DESCRIPTION
     The SCTP protocol provides	reliable, flow-controlled, two-way transmis-
     sion of data.  It is a message oriented protocol and can support the
     SOCK_STREAM and SOCK_SEQPACKET abstractions.  SCTP	uses the standard
     Internet address format and, in addition, provides	a per-host collection
     of	``port addresses''.  Thus, each	address	is composed of an Internet
     address specifying	the host and network, with a specific SCTP port	on the
     host identifying the peer entity.

     There are two models of programming in SCTP.  The first uses the
     SOCK_STREAM abstraction.  In this abstraction sockets utilizing the SCTP
     protocol are either ``active'' or ``passive''.  Active sockets initiate
     connections to passive sockets.  By default, SCTP sockets are created
     active; to	create a passive socket, the listen(2) system call must	be
     used after	binding	the socket with	the bind(2) or sctp_bindx(3) system
     calls.  Only passive sockets may use the accept(2)	call to	accept incom-
     ing connections.  Only active sockets may use the connect(2) call to ini-
     tiate connections.

     The other abstraction SOCK_SEQPACKET provides a ``connectionless''	mode
     of	operation in that the user may send to an address (using any of	the
     valid send	calls that carry a socket address) and an association will be
     setup implicitly by the underlying	SCTP transport stack.  This abstrac-
     tion is the only one capable of sending data on the third leg of the
     four-way handshake.  A user must still call listen(2) to allow the	socket
     to	accept connections.  Calling listen(2) however does not	restrict the
     user from still initiating	implicit connections to	other peers.

     The SCTP protocol directly	supports multi-homing.	So when	binding	a
     socket with the ``wildcard'' address INADDR_ANY, the SCTP stack will
     inform the	peer about all of the local addresses that are deemed in scope
     of	the peer.  The peer will then possibly have multiple paths to reach
     the local host.

     The SCTP transport	protocol is also multi-streamed.  Multi-streaming
     refers to the ability to send sub-ordered flows of	messages.  A user per-
     forms this	by specifying a	specific stream	in one of the extended send
     calls such	as the sctp_send(3) function call.  Sending messages on	dif-
     ferent streams will allow parallel	delivery of data i.e., a message loss
     in	stream 1 will not block	the delivery of	messages sent in stream	2.

     The SCTP transport	protocol also provides a unordered service as well.
     The unordered service allows a message to be sent and delivered with no
     regard to the ordering of any other message.

   Extensions
     The FreeBSD implementation	of SCTP	also supports the following exten-
     sions:

     sctp partial reliability This extension allows one	to have	message	be
	     skipped and not delivered based on	some user specified parame-
	     ters.

     sctp dynamic addressing
	      This extension allows addresses to be added and deleted dynammi-
	     cally from	an existing association.

     sctp authentication This extension	allows the user	to authenticate	spe-
	     cific peer	chunks (including data)	to validate that the peer who
	     sent the message is in fact the peer who setup the	association.
	     A shared key option is also provided for so that two stacks can
	     pre-share keys.

     packet drop
	      Some routers support a special satellite protocol	that will
	     report losses due to corruption.  This allows retransmissions
	     without subsequent	loss in	bandwidth utilization.

     stream reset This extension allows	a user on either side to reset the
	     stream sequence numbers used by any or all	streams.

     SCTP supports a number of socket options which can	be set with
     setsockopt(2) and tested with getsockopt(2) or sctp_opt_info(2):

     SCTP_NODELAY		 Under most circumstances, SCTP	sends data
				 when it is presented; when outstanding	data
				 has not yet been acknowledged,	it gathers
				 small amounts of output to be sent in a sin-
				 gle packet once an acknowledgement is
				 received.  For	some clients, such as window
				 systems that send a stream of mouse events
				 which receive no replies, this	packetization
				 may cause significant delays.	The boolean
				 option	SCTP_NODELAY defeats this algorithm.

     SCTP_RTOINFO		 This option returns specific information
				 about an associations ``Retransmission	Time
				 Out''.	 It can	also be	used to	change the
				 default values.

     SCTP_ASSOCINFO		 This option returns specific information
				 about the requested association.

     SCTP_INITMSG		 This option allows you	to get or set the
				 default sending parameters when an associa-
				 tion is implicitly setup.  It allows you to
				 change	such things as the maxium number of
				 streams allowed inbound and the number	of
				 streams requested of the peer.

     SCTP_AUTOCLOSE		 For the one-to-many model (SOCK_SEQPACKET)
				 associations are setup	implicitly.  This
				 option	allows the user	to specify a default
				 number	of idle	seconds	to allow the associa-
				 tion be maintained.  After the	idle timer
				 (where	no user	message	have been sent or have
				 been received from the	peer) the association
				 will be gracefully closed.  The default for
				 this value is 0, or unlimited (i.e., no auto-
				 matic close).

     SCTP_SET_PEER_PRIMARY_ADDR	 The dynamic address extension allows a	peer
				 to also request a particular address of its
				 be made into the primary address.  This
				 option	allows the caller to make such a
				 request to a peer.  Note that if the peer
				 does not also support the dynamic address
				 extension, this call will fail.  Note the
				 caller	must provide a valid local address
				 that the peer has been	told about during
				 association setup or dynamically.

     SCTP_PRIMARY_ADDR		 This option allows the	setting	of the primary
				 address that the caller wishes	to send	to.
				 The caller provides the address of a peer
				 that is to be made primary.

     SCTP_ADAPTATION_LAYER	 The dynamic address extension also allows a
				 user to pass a	32 bit opaque value upon asso-
				 ciation setup.	 This option allows a user to
				 set or	get this value.

     SCTP_DISABLE_FRAGMENTS	 By default SCTP will fragment user messages
				 into multiple pieces that will	fit on the
				 network and then later, upon reception,
				 reassemble the	pieces into a single user mes-
				 sage.	If this	option is enabled instead, any
				 send that exceeds the path maximum transfer
				 unit (P-MTU) will fail	and the	message	will
				 NOT be	sent.

     SCTP_PEER_ADDR_PARAMS	 This option will allow	a user to set or get
				 specific peer address parameters.

     SCTP_DEFAULT_SEND_PARAM	 When a	user does not use one of the extended
				 send calls (e.g., sctp_sendmsg(3)) a set of
				 default values	apply to each send.  These
				 values	include	things like the	stream number
				 to send to as well as the per-protocol	id.
				 This option lets a caller both	get and	set
				 these values.	If the user changes these
				 default values, then these new	values will be
				 used as the default whenever no information
				 is provided by	the sender (i.e., the non-
				 extended API is used).

     SCTP_EVENTS		 SCTP has non-data events that it can communi-
				 cate to its application.  By default these
				 are all disabled since	they arrive in the
				 data path with	a special flag
				 MSG_NOTIFICATION set upon the received	mes-
				 sage.	This option lets a caller both get
				 what events are current being received	as
				 well as set different events that they	may be
				 interested in receiving.

     SCTP_I_WANT_MAPPED_V4_ADDR	 SCTP supports both IPV4 and IPV6.  An associ-
				 ation may span	both IPV4 and IPV6 addresses
				 since SCTP is multi-homed.  By	default, when
				 opening an IPV6 socket, when data arrives on
				 the socket from a peer's V4 address the V4
				 address  will be presented with an address
				 family	of AF_INET.  If	this is	undesireable,
				 then this option can be enabled which will
				 then convert all V4 addresses into mapped V6
				 representations.

     SCTP_MAXSEG		 By default SCTP chooses its message fragmen-
				 tation	point based upon the smallest P-MTU of
				 the peer.  This option	lets the caller	set it
				 to a smaller value.  Note that	while the user
				 can change this value,	if the P-MTU is
				 smaller than the value	set by the user, then
				 the P-MTU value will override any user	set-
				 ting.

     SCTP_DELAYED_ACK_TIME	 This option lets the user both	set and	get
				 the delayed ack time (in milliseconds)	that
				 SCTP is using.	 The default is	200 millisec-
				 onds.

     SCTP_PARTIAL_DELIVERY_POINT
				 SCTP at times may need	to start delivery of a
				 very large message before the entire message
				 has arrived.  By default SCTP waits until the
				 incoming message is larger than one fourth of
				 the receive buffer.  This option allows the
				 stacks	value to be overridden with a smaller
				 value.

     SCTP_FRAGMENT_INTERLEAVE	 SCTP at times will start partial delivery (as
				 mentioned above).  In the normal case succes-
				 sive reads will continue to return the	rest
				 of the	message, blocking if needed, until all
				 of that message is read.  However this	means
				 other messages	may have arrived and be	ready
				 for delivery and be blocked behind the	mes-
				 sage being partially delivered.  If this
				 option	is enabled, when a partial delivery
				 message has no	more data to be	received, then
				 a subsequent read may return a	different mes-
				 sage that is ready for	delivery.  By default
				 this option is	off since the user must	be
				 using the extended API's to be	able to	tell
				 the difference	between	messages (via the
				 stream	and stream sequence number).

     SCTP_AUTH_CHUNK		 By default only the dynamic addressing	chunks
				 are authenticated.  This option lets a	user
				 request an additional chunk be	authenticated
				 as well.  Note	that successive	calls to this
				 option	will work and continue to add more
				 chunks	that require authentication.  Note
				 that this option only effects future associa-
				 tions and not existing	ones.

     SCTP_AUTH_KEY		 This option allows a user to specify a	shared
				 key that can be later used to authenticate a
				 peer.

     SCTP_HMAC_IDENT		 This option will let you get or set the list
				 of HMAC algorithms used to authenticate
				 peers.	 Note that the HMAC values are in pri-
				 ority order where the first HMAC identifier
				 is the	most prefered and the last is the
				 least prefered.

     SCTP_AUTH_ACTIVE_KEY	 This option allows you	to make	a key active
				 for the generation of authentication informa-
				 tion.	Note that the peer must	have the same
				 key or	else the data will be discarded.

     SCTP_AUTH_DELETE_KEY	 This option allows you	to delete an old key.

     SCTP_USE_EXT_RECVINFO	 The sockets api document allows an extended
				 send/receive information structure to be
				 used.	The extended structure includes	addi-
				 tional	fields related to the next message to
				 be received (after the	current	receive	com-
				 pletes) if such information is	known.	By
				 default the system will not pass this infor-
				 mation.  This option allows the user to
				 request this information.

     SCTP_AUTO_ASCONF		 By default when bound to all address and the
				 system	administrator has enables automatic
				 dynamic addresses, the	SCTP stack will	auto-
				 matically generate address changes into add
				 and delete requests to	any peers by setting
				 this option to	true.  This option allows an
				 endpoint to disable that behavior.

     SCTP_MAXBURST		 By default SCTP implements micro-burst	con-
				 trol so that as the congestion	window opens
				 up no large burst of packets can be gener-
				 ated.	The default burst limit	is four.  This
				 option	lets the user change this value.

     SCTP_CONTEXT		 Many sctp extended calls have a context
				 field.	 The context field is a	32 bit opaque
				 value that will be returned in	send failures.
				 This option lets the caller set the default
				 context value to use when none	is provided by
				 the user.

     SCTP_EXPLICIT_EOR		 By default, a single send is a	complete mes-
				 sage.	SCTP generates an implied record
				 boundary.  If this option is enabled, then
				 all sends are part of the same	message	until
				 the user indicates an end of record with the
				 special flag SCTP_EOR passed in the
				 sctp_sndrcvinfo flags field.  This effec-
				 tively	makes all sends	part of	the same mes-
				 sage until the	user specifices	differently.
				 This means that a caller must NOT change the
				 stream	number until after the SCTP_EOR	is
				 passed	to SCTP	else an	error will be
				 returned.

     SCTP_STATUS		 This option is	a read only option that
				 returns various status	information about the
				 specified association.

     SCTP_GET_PEER_ADDR_INFO	 This read only	option returns information
				 about a peer address.

     SCTP_PEER_AUTH_CHUNKS	 This read only	option returns a list of the
				 chunks	the peer requires to be	authenticated.

     SCTP_LOCAL_AUTH_CHUNKS	 This read only	option returns a list of the
				 locally required chunks that must be authen-
				 ticated.

     SCTP_RESET_STREAMS		 This socket option is used to cause a stream
				 sequence number or all	stream sequence	num-
				 bers to be reset.  Note that the peer SCTP
				 endpoint must also support the	stream reset
				 extension as well.

SEE ALSO
     accept(2),	bind(2), connect(2), listen(2),	sctp_bindx(3),
     sctp_connectx(3), sctp_opt_info(3), sctp_recvmsg(3), sctp_sendmsg(3)

FreeBSD	9.2		       December	15, 2006		   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=sctp&sektion=4&manpath=FreeBSD+7.2-RELEASE>

home | help