[src/trunk]: src Add man page for sctp(4).

[rjs <rjs%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/bbb01f97b6a7
branches:  trunk
changeset: 365089:bbb01f97b6a7
user:      rjs <rjs%NetBSD.org@localhost>
date:      Tue Jul 31 19:30:18 2018 +0000

description:
Add man page for sctp(4).

diffstat:

 distrib/sets/lists/man/mi |    4 +-
 share/man/man4/Makefile   |    4 +-
 share/man/man4/sctp.4     |  436 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 441 insertions(+), 3 deletions(-)

diffs (truncated from 483 to 300 lines):

diff -r 9ef51cd2ff16 -r bbb01f97b6a7 distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Tue Jul 31 16:44:28 2018 +0000
+++ b/distrib/sets/lists/man/mi Tue Jul 31 19:30:18 2018 +0000
@@ -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
diff -r 9ef51cd2ff16 -r bbb01f97b6a7 share/man/man4/Makefile
--- a/share/man/man4/Makefile   Tue Jul 31 16:44:28 2018 +0000
+++ b/share/man/man4/Makefile   Tue Jul 31 19:30:18 2018 +0000
@@ -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 @@
        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 \
diff -r 9ef51cd2ff16 -r bbb01f97b6a7 share/man/man4/sctp.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/sctp.4     Tue Jul 31 19:30:18 2018 +0000
@@ -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