Add man page for sctp(4).
This commit is contained in:
parent
d7f036be09
commit
c4abcf4909
|
@ -1,4 +1,4 @@
|
|||
# $NetBSD: mi,v 1.1603 2018/07/31 16:44:29 khorben Exp $
|
||||
# $NetBSD: mi,v 1.1604 2018/07/31 19:30:18 rjs Exp $
|
||||
#
|
||||
# Note: don't delete entries from here - mark them as "obsolete" instead.
|
||||
#
|
||||
|
@ -4724,6 +4724,7 @@
|
|||
./usr/share/man/html4/schide.html man-sys-htmlman html
|
||||
./usr/share/man/html4/scsi.html man-sys-htmlman html
|
||||
./usr/share/man/html4/scsibus.html man-sys-htmlman html
|
||||
./usr/share/man/html4/sctp.html man-sys-htmlman html
|
||||
./usr/share/man/html4/sd.html man-sys-htmlman html
|
||||
./usr/share/man/html4/sdhc.html man-sys-htmlman html
|
||||
./usr/share/man/html4/sdmmc.html man-sys-htmlman html
|
||||
|
@ -7712,6 +7713,7 @@
|
|||
./usr/share/man/man4/schide.4 man-sys-man .man
|
||||
./usr/share/man/man4/scsi.4 man-sys-man .man
|
||||
./usr/share/man/man4/scsibus.4 man-sys-man .man
|
||||
./usr/share/man/man4/sctp.4 man-sys-man .man
|
||||
./usr/share/man/man4/sd.4 man-sys-man .man
|
||||
./usr/share/man/man4/sdhc.4 man-sys-man .man
|
||||
./usr/share/man/man4/sdmmc.4 man-sys-man .man
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
# $NetBSD: Makefile,v 1.661 2018/07/31 16:44:29 khorben Exp $
|
||||
# $NetBSD: Makefile,v 1.662 2018/07/31 19:30:19 rjs Exp $
|
||||
# @(#)Makefile 8.1 (Berkeley) 6/18/93
|
||||
|
||||
MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
|
||||
|
@ -55,7 +55,7 @@ MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
|
|||
raid.4 ral.4 ray.4 rcons.4 rdcphy.4 re.4 rgephy.4 rlphy.4 \
|
||||
rnd.4 route.4 rs5c372rtc.4 rtk.4 rtsx.4 rtw.4 rtwn.4 rum.4 run.4 \
|
||||
s390rtc.4 satalink.4 sbus.4 schide.4 \
|
||||
scsi.4 sd.4 se.4 seeprom.4 sem.4 \
|
||||
scsi.4 sctp.4 sd.4 se.4 seeprom.4 sem.4 \
|
||||
ses.4 sf.4 sfb.4 sgsmix.4 shb.4 shmif.4 shpcic.4 si70xxtemp.4 \
|
||||
siisata.4 siop.4 sip.4 siside.4 sk.4 sl.4 slide.4 \
|
||||
sm.4 smsh.4 sn.4 sony.4 spc.4 speaker.4 spif.4 sqphy.4 ss.4 \
|
||||
|
|
|
@ -0,0 +1,436 @@
|
|||
.\" $NetBSD: sctp.4,v 1.1 2018/07/31 19:30:19 rjs Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2006, Randall Stewart.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd July 31, 2018
|
||||
.Dt SCTP 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm sctp
|
||||
.Nd Internet Stream Control Transmission Protocol
|
||||
.Sh SYNOPSIS
|
||||
.In sys/types.h
|
||||
.In sys/socket.h
|
||||
.In netinet/sctp.h
|
||||
.Ft int
|
||||
.Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP
|
||||
.Ft int
|
||||
.Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Tn SCTP
|
||||
protocol provides reliable, flow-controlled, two-way
|
||||
transmission of data.
|
||||
It is a message oriented protocol and can
|
||||
support the
|
||||
.Dv SOCK_STREAM
|
||||
and
|
||||
.Dv SOCK_SEQPACKET
|
||||
abstractions.
|
||||
.Tn SCTP
|
||||
uses the standard
|
||||
Internet address format and, in addition, provides a per-host
|
||||
collection of
|
||||
.Dq "port addresses" .
|
||||
Thus, each address is composed of an Internet address specifying
|
||||
the host and network, with a specific
|
||||
.Tn SCTP
|
||||
port on the host identifying the peer entity.
|
||||
.Pp
|
||||
There are two models of programming in SCTP.
|
||||
The first uses the
|
||||
.Dv SOCK_STREAM
|
||||
abstraction.
|
||||
In this abstraction sockets utilizing the
|
||||
.Tn SCTP
|
||||
protocol are either
|
||||
.Dq active
|
||||
or
|
||||
.Dq passive .
|
||||
Active sockets initiate connections to passive
|
||||
sockets.
|
||||
By default,
|
||||
.Tn SCTP
|
||||
sockets are created active; to create a
|
||||
passive socket, the
|
||||
.Xr listen 2
|
||||
system call must be used after binding the socket with the
|
||||
.Xr bind 2
|
||||
or
|
||||
.Xr sctp_bindx 3
|
||||
system calls.
|
||||
Only passive sockets may use the
|
||||
.Xr accept 2
|
||||
call to accept incoming connections.
|
||||
Only active sockets may use the
|
||||
.Xr connect 2
|
||||
call to initiate connections.
|
||||
.Pp
|
||||
The other abstraction
|
||||
.Dv SOCK_SEQPACKET
|
||||
provides a
|
||||
.Dq 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
|
||||
.Tn SCTP
|
||||
transport stack.
|
||||
This abstraction is the only one capable of sending data on the
|
||||
third leg of the four-way handshake.
|
||||
A user must still call
|
||||
.Xr listen 2
|
||||
to allow the socket to accept connections.
|
||||
Calling
|
||||
.Xr listen 2
|
||||
however does not restrict the user from still initiating
|
||||
implicit connections to other peers.
|
||||
.Pp
|
||||
The
|
||||
.Tn SCTP
|
||||
protocol directly supports multi-homing.
|
||||
So when binding a socket with the
|
||||
.Dq wildcard
|
||||
address
|
||||
.Dv INADDR_ANY ,
|
||||
the
|
||||
.Tn 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.
|
||||
.Pp
|
||||
The
|
||||
.Tn SCTP
|
||||
transport protocol is also multi-streamed.
|
||||
Multi-streaming refers to the ability to send sub-ordered flows of
|
||||
messages.
|
||||
A user performs this by specifying a specific stream in one of the
|
||||
extended send calls such as the
|
||||
.Xr sctp_send 3
|
||||
function call.
|
||||
Sending messages on different 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.
|
||||
.Pp
|
||||
The
|
||||
.Tn 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.
|
||||
.Ss Extensions
|
||||
The NetBSD implementation of
|
||||
.Tn SCTP
|
||||
also supports the following extensions:
|
||||
.Bl -hang -width indent
|
||||
.It "sctp partial reliability"
|
||||
This extension allows one to have message be skipped and
|
||||
not delivered based on some user specified parameters.
|
||||
.It "sctp dynamic addressing"
|
||||
This extension allows addresses to be added and deleted
|
||||
dynamically from an existing association.
|
||||
.It "sctp authentication"
|
||||
This extension allows the user to authenticate specific
|
||||
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.
|
||||
.It "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.
|
||||
.It "stream reset"
|
||||
This extension allows a user on either side to reset the
|
||||
stream sequence numbers used by any or all streams.
|
||||
.El
|
||||
.Pp
|
||||
.Tn SCTP
|
||||
supports a number of socket options which can be set with
|
||||
.Xr setsockopt 2
|
||||
and tested with
|
||||
.Xr getsockopt 2
|
||||
or
|
||||
.Xr sctp_opt_info 3 :
|
||||
.Bl -tag -width ".Dv SCTP_SET_PEER_PRIMARY_ADDR"
|
||||
.It Dv SCTP_NODELAY
|
||||
Under most circumstances,
|
||||
.Tn 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 single 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
|
||||
.Dv SCTP_NODELAY
|
||||
defeats this algorithm.
|
||||
.It Dv SCTP_RTOINFO
|
||||
This option returns specific information about an associations
|
||||
.Dq "Retransmission Time Out" .
|
||||
It can also be used to change the default values.
|
||||
.It Dv SCTP_ASSOCINFO
|
||||
This option returns specific information about the requested
|
||||
association.
|
||||
.It Dv SCTP_INITMSG
|
||||
This option allows you to get or set the default sending
|
||||
parameters when an association is implicitly setup.
|
||||
It allows you to change such things as the maximum number of
|
||||
streams allowed inbound and the number of streams requested
|
||||
of the peer.
|
||||
.It Dv SCTP_AUTOCLOSE
|
||||
For the one-to-many model
|
||||
.Dv ( SOCK_SEQPACKET )
|
||||
associations are setup implicitly.
|
||||
This option allows the user to specify a default number of idle
|
||||
seconds to allow the association 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 automatic
|
||||
close).
|
||||
.It Dv 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.
|
||||
.It Dv 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.
|
||||
.It Dv SCTP_ADAPTATION_LAYER
|
||||
The dynamic address extension also allows a user to
|
||||
pass a 32 bit opaque value upon association setup.
|
||||
This option allows a user to set or get this value.
|
||||
.It Dv SCTP_DISABLE_FRAGMENTS
|
||||
By default
|
||||
.Tn 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 message.
|
||||
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.
|
||||
.It Dv SCTP_PEER_ADDR_PARAMS
|
||||
This option will allow a user to set or get specific
|
||||
peer address parameters.
|
||||
.It Dv SCTP_DEFAULT_SEND_PARAM
|
||||
When a user does not use one of the extended send
|
||||
calls (e.g.,
|
||||
.Xr 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).
|
||||
.It Dv SCTP_EVENTS
|
||||
.Tn SCTP
|
||||
has non-data events that it can communicate
|
||||
to its application.
|
||||
By default these are all disabled since they arrive in the data path
|
||||
with a special flag
|
||||
.Dv MSG_NOTIFICATION
|
||||
set upon the received message.
|
||||
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.
|
||||
.It Dv SCTP_I_WANT_MAPPED_V4_ADDR
|
||||
.Tn SCTP
|
||||
supports both IPV4 and IPV6.
|
||||
An association may span both IPV4 and IPV6 addresses since
|
||||
.Tn 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 undesirable, then this option
|
||||
can be enabled which will then convert all V4 addresses
|
||||
into mapped V6 representations.
|
||||
.It Dv SCTP_MAXSEG
|
||||
By default
|
||||
.Tn SCTP
|
||||
chooses its message fragmentation 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 setting.
|
||||
.It Dv SCTP_DELAYED_ACK_TIME
|
||||
This option lets the user both set and get the
|
||||
delayed ack time (in milliseconds) that
|
||||
.Tn SCTP
|
||||
is using.
|
||||
The default is 200 milliseconds.
|
||||
.It Dv SCTP_PARTIAL_DELIVERY_POINT
|
||||
.Tn 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.
|
||||
.It Dv SCTP_FRAGMENT_INTERLEAVE
|
||||
.Tn SCTP
|
||||
at times will start partial delivery (as mentioned above).
|
||||
In the normal case successive 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 message 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 message 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).
|
||||
.It Dv 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 associations and
|
||||
not existing ones.
|
||||
.It Dv SCTP_AUTH_KEY
|
||||
This option allows a user to specify a shared
|
||||
key that can be later used to authenticate
|
||||
a peer.
|
||||
.It Dv 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 priority order where
|
||||
the first HMAC identifier is the most preferred
|
||||
and the last is the least preferred.
|
||||
.It Dv SCTP_AUTH_ACTIVE_KEY
|
||||
This option allows you to make a key active for
|
||||
the generation of authentication information.
|
||||
Note that the peer must have the same key or else the
|
||||
data will be discarded.
|
||||
.It Dv SCTP_AUTH_DELETE_KEY
|
||||
This option allows you to delete an old key.
|
||||
.It Dv SCTP_USE_EXT_RECVINFO
|
||||
The sockets api document allows an extended
|
||||
send/receive information structure to be used.
|
||||
The extended structure includes additional fields
|
||||
related to the next message to be received (after the
|
||||
current receive completes) if such information is known.
|
||||
By default the system will not pass this information.
|
||||
This option allows the user to request this information.
|
||||
.It Dv SCTP_AUTO_ASCONF
|
||||
By default when bound to all address and the system administrator has
|
||||
enables automatic dynamic addresses, the
|
||||
.Tn SCTP
|
||||
stack will automatically 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.
|
||||
.It Dv SCTP_MAXBURST
|
||||
By default
|
||||
.Tn SCTP
|
||||
implements micro-burst control so that as the congestion window
|
||||
opens up no large burst of packets can be generated.
|
||||
The default burst limit is four.
|
||||
This option lets the user change this value.
|
||||
.It Dv 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.
|
||||
.It Dv SCTP_EXPLICIT_EOR
|
||||
By default, a single send is a complete message.
|
||||
.Tn 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
|
||||
.Dv SCTP_EOR
|
||||
passed in the sctp_sndrcvinfo flags field.
|
||||
This effectively makes all sends part of the same message
|
||||
until the user specifies differently.
|
||||
This means that a caller must NOT change the stream number until
|
||||
after the
|
||||
.Dv SCTP_EOR
|
||||
is passed to
|
||||
.Tn SCTP
|
||||
else an error will be returned.
|
||||
.It Dv SCTP_STATUS
|
||||
This option is a read only option that returns
|
||||
various status information about the specified association.
|
||||
.It Dv SCTP_GET_PEER_ADDR_INFO
|
||||
This read only option returns information about a peer
|
||||
address.
|
||||
.It Dv SCTP_PEER_AUTH_CHUNKS
|
||||
This read only option returns a list of the chunks
|
||||
the peer requires to be authenticated.
|
||||
.It Dv SCTP_LOCAL_AUTH_CHUNKS
|
||||
This read only option returns a list of the locally
|
||||
required chunks that must be authenticated.
|
||||
.It Dv SCTP_RESET_STREAMS
|
||||
This socket option is used to cause a stream sequence
|
||||
number or all stream sequence numbers to be reset.
|
||||
Note that the peer
|
||||
.Tn SCTP
|
||||
endpoint must also support the stream reset extension
|
||||
as well.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr accept 2 ,
|
||||
.Xr bind 2 ,
|
||||
.Xr connect 2 ,
|
||||
.Xr listen 2 ,
|
||||
.Xr sctp_bindx 3 ,
|
||||
.Xr sctp_connectx 3 ,
|
||||
.Xr sctp_opt_info 3 ,
|
||||
.Xr sctp_recvmsg 3 ,
|
||||
.Xr sctp_sendmsg 3
|
||||
.Rs
|
||||
.%R RFC
|
||||
.%N 4960
|
||||
.%T "Stream Control Transmission Protocol"
|
||||
.%D September 2007
|
||||
.Re
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm
|
||||
protocol appeared in
|
||||
.Nx 8.0 .
|
Loading…
Reference in New Issue