[src/trunk]: src/lib/libc/net Add missing SCTP manpage.

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

details:   https://anonhg.NetBSD.org/src/rev/003b453dd480
branches:  trunk
changeset: 365141:003b453dd480
user:      rjs <rjs%NetBSD.org@localhost>
date:      Thu Aug 02 10:18:19 2018 +0000

description:
Add missing SCTP manpage.

diffstat:

 lib/libc/net/sctp_recvmsg.3 |  303 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 303 insertions(+), 0 deletions(-)

diffs (truncated from 307 to 300 lines):

diff -r 255fe9eb28bc -r 003b453dd480 lib/libc/net/sctp_recvmsg.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/net/sctp_recvmsg.3       Thu Aug 02 10:18:19 2018 +0000
@@ -0,0 +1,303 @@
+.\"    $NetBSD: sctp_recvmsg.3,v 1.1 2018/08/02 10:18:19 rjs Exp $
+.\"
+.\" Copyright (c) 1983, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.
+.\"
+.\" 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. 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 August 1, 2018
+.Dt SCTP_RECVMSG 3
+.Os
+.Sh NAME
+.Nm sctp_recvmsg
+.Nd receive a message from an SCTP socket
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/socket.h
+.In netinet/sctp.h
+.Ft ssize_t
+.Fo sctp_recvmsg
+.Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from"
+.Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn sctp_recvmsg
+system call
+is used to receive a message from another SCTP endpoint.
+The
+.Fn sctp_recvmsg
+call is used by one-to-one (SOCK_STREAM) type sockets after a
+successful
+.Fn connect
+call or after the application has performed a
+.Fn listen
+followed by a successful
+.Fn accept .
+For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
+.Fn sctp_recvmsg
+after having implicitly started an association via one
+of the send calls including
+.Fn sctp_sendmsg ,
+.Fn sendto
+and
+.Fn sendmsg .
+Or, an application may also receive a message after having
+called
+.Fn listen
+with a positive backlog to enable the reception of new associations.
+.Pp
+The address of the sender is held in the
+.Fa from
+argument with
+.Fa fromlen
+specifying its size.
+At the completion of a successful
+.Fn sctp_recvmsg
+call
+.Fa from
+will hold the address of the peer and
+.Fa fromlen
+will hold the length of that address.
+Note that
+the address is bounded by the initial value of
+.Fa fromlen
+which is used as an in/out variable.
+.Pp
+The length of the message
+.Fa msg
+to be received is bounded by
+.Fa len .
+If the message is too long to fit in the users
+receive buffer, then the
+.Fa flags
+argument will
+.Em not
+have the
+.Dv MSG_EOF
+flag applied.
+If the message is a complete message then
+the
+.Fa flags
+argument will have
+.Dv MSG_EOF
+set.
+Locally detected errors are
+indicated by a return value of -1 with
+.Va errno
+set accordingly.
+The
+.Fa flags
+argument may also hold the value
+.Dv MSG_NOTIFICATION .
+When this
+occurs it indicates that the message received is
+.Em not
+from
+the peer endpoint, but instead is a notification from the
+SCTP stack (see
+.Xr sctp 4
+for more details).
+Note that no notifications are ever
+given unless the user subscribes to such notifications using
+the
+.Dv SCTP_EVENTS
+socket option.
+.Pp
+If no messages are available at the socket then
+.Fn sctp_recvmsg
+normally blocks on the reception of a message or NOTIFICATION, unless the
+socket has been placed in non-blocking I/O mode.
+The
+.Xr select 2
+system call may be used to determine when it is possible to
+receive a message.
+.Pp
+The
+.Fa sinfo
+argument is defined as follows.
+.Bd -literal
+struct sctp_sndrcvinfo {
+       uint16_t sinfo_stream;  /* Stream arriving on */
+       uint16_t sinfo_ssn;     /* Stream Sequence Number */
+       uint16_t sinfo_flags;   /* Flags on the incoming message */
+       uint32_t sinfo_ppid;    /* The ppid field */
+       uint32_t sinfo_context; /* context field */
+       uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */
+       uint32_t sinfo_tsn;        /* The transport sequence number */
+       uint32_t sinfo_cumtsn;     /* The cumulative acknowledgment point  */
+       sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */
+};
+.Ed
+.Pp
+The
+.Fa sinfo->sinfo_ppid
+field is an opaque 32 bit value that is passed transparently
+through the stack from the peer endpoint.
+Note that the stack passes this value without regard to byte
+order.
+.Pp
+The
+.Fa sinfo->sinfo_flags
+field may include the following:
+.Bd -literal
+#define SCTP_UNORDERED           0x0400        /* Message is un-ordered */
+.Ed
+.Pp
+The
+.Dv SCTP_UNORDERED
+flag is used to specify that the message arrived with no
+specific order and was delivered to the peer application
+as soon as possible.
+When this flag is absent the message
+was delivered in order within the stream it was received.
+.Pp
+The
+.Fa sinfo->sinfo_stream
+field is the SCTP stream that the message was received on.
+Streams in SCTP are reliable (or partially reliable) flows of ordered
+messages.
+.Pp
+The
+.Fa sinfo->sinfo_context
+field is used only if the local application set an association level
+context with the
+.Dv SCTP_CONTEXT
+socket option.
+Optionally a user process can use this value to index some application
+specific data structure for all data coming from a specific
+association.
+.Pp
+The
+.Fa sinfo->sinfo_ssn
+field will hold the stream sequence number assigned
+by the peer endpoint if the message is
+.Em not
+unordered.
+For unordered messages this field holds an undefined value.
+.Pp
+The
+.Fa sinfo->sinfo_tsn
+field holds a transport sequence number (TSN) that was assigned
+to this message by the peer endpoint.
+For messages that fit in or less
+than the path MTU this will be the only TSN assigned.
+Note that for messages that span multiple TSNs this
+value will be one of the TSNs that was used on the
+message.
+.Pp
+The
+.Fa sinfo->sinfo_cumtsn
+field holds the current cumulative acknowledgment point of
+the transport association.
+Note that this may be larger
+or smaller than the TSN assigned to the message itself.
+.Pp
+The
+.Fa sinfo->sinfo_assoc_id
+is the unique association identification that was assigned
+to the association.
+For one-to-many (SOCK_SEQPACKET) type
+sockets this value can be used to send data to the peer without
+the use of an address field.
+It is also quite useful in
+setting various socket options on the specific association
+(see
+.Xr sctp 4 ) .
+.Pp
+The
+.Fa sinfo->info_timetolive
+field is not used by
+.Fn sctp_recvmsg .
+.Sh RETURN VALUES
+The call returns the number of bytes received, or -1
+if an error occurred.
+.Sh ERRORS
+The
+.Fn sctp_recvmsg
+system call
+fails if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+An invalid descriptor was specified.
+.It Bq Er ENOTSOCK
+The argument
+.Fa s
+is not a socket.
+.It Bq Er EFAULT
+An invalid user space address was specified for an argument.
+.It Bq Er EMSGSIZE
+The socket requires that message be sent atomically,
+and the size of the message to be sent made this impossible.
+.It Bq Er EAGAIN
+The socket is marked non-blocking and the requested operation
+would block.
+.It Bq Er ENOBUFS
+The system was unable to allocate an internal buffer.
+The operation may succeed when buffers become available.
+.It Bq Er ENOBUFS
+The output queue for a network interface was full.
+This generally indicates that the interface has stopped sending,
+but may be caused by transient congestion.
+.It Bq Er EHOSTUNREACH
+The remote host was unreachable.
+.It Bq Er ENOTCONN
+On a one-to-one style socket no association exists.
+.It Bq Er ECONNRESET
+An abort was received by the stack while the user was
+attempting to send data to the peer.
+.It Bq Er ENOENT
+On a one to many style socket no address is specified
+so that the association cannot be located or the
+SCTP_ABORT flag was specified on a non-existing association.
+.It Bq Er EPIPE
+The socket is unable to send anymore data
+.Dv ( SBS_CANTSENDMORE
+has been set on the socket).
+This typically means that the socket
+is not connected and is a one-to-one style socket.
+.El
+.Sh SEE ALSO
+.Xr recv 2 ,
+.Xr select 2 ,
+.Xr socket 2 ,
+.Xr write 2 ,
+.Xr getsockopt 2 ,
+.Xr setsockopt 2 ,
+.Xr sctp_send 3 ,
+.Xr sctp_sendmsg 3 ,
+.Xr sendmsg 2 ,
+.Xr sctp 4
+.Rs
+.%R RFC