1 files changed, 188 insertions, 12 deletions
diff --git a/lib/libc/net/sctp_recvmsg.3 b/lib/libc/net/sctp_recvmsg.3
index a8b073418657..7bcdcc74f7a1 100644
--- a/lib/libc/net/sctp_recvmsg.3
+++ b/lib/libc/net/sctp_recvmsg.3
@@ -25,13 +25,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD$
-.\"
-.Dd April 23, 2015
+.Dd May 2, 2024
 .Dt SCTP_RECVMSG 3
 .Os
 .Sh NAME
-.Nm sctp_recvmsg
+.Nm sctp_recvmsg ,
+.Nm sctp_recvv
 .Nd receive a message from an SCTP socket
 .Sh LIBRARY
 .Lb libc
@@ -41,18 +40,22 @@
 .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"
+.Fa "int s" "void *msg" "size_t len" "struct sockaddr *from"
+.Fa "socklen_t *fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags"
+.Fc
+.Ft ssize_t
+.Fo sctp_recvv
+.Fa "int s" "const struct iovec *iov" "int iovlen" "struct sockaddr *from"
+.Fa "socklen_t *fromlen" "void *info" "socklen_t *infolen"
+.Fa "unsigned int *infotype" "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
+and
+.Fn sctp_recvv
+functions are used to receive a message from another SCTP endpoint.
+They are used by one-to-one (SOCK_STREAM) type sockets after a successful
 .Fn connect
 call or after the application has performed a
 .Fn listen
@@ -60,6 +63,8 @@ followed by a successful
 .Fn accept .
 For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
 .Fn sctp_recvmsg
+or
+.Fn sctp_recvv
 after having implicitly started an association via one
 of the send calls including
 .Fn sctp_sendmsg ,
@@ -233,6 +238,159 @@ The
 .Fa sinfo->info_timetolive
 field is not used by
 .Fn sctp_recvmsg .
+.Pp
+The
+.Fn sctp_recvv
+function works as
+.Fn sctp_recvmsg
+with two differences.
+Firstly, the receive buffer is passed as an array containing
+.Vt iocnt
+objects of type
+.Vt struct iovec ,
+where the received data will be scattered in the same manner as
+.Xr readv 2 .
+Secondly, the
+.Fa sinfo
+argument is replaced by the tuple
+.Fa info ,
+.Fa infolen ,
+and
+.Fa infotype ,
+which allow different information to be received based on the socket options.
+.Pp
+To receive an
+.Vt sctp_rcvinfo
+structure, set the
+.Va SCTP_RECVRCVINFO
+socket option, and pass a pointer to a
+.Vt struct sctp_rcvinfo
+structure in
+.Fa info .
+The
+.Vt sctp_rcvinfo
+structure has the following format:
+.Bd -literal
+struct sctp_rcvinfo {
+	uint16_t rcv_sid;		/* Stream arriving on */
+	uint16_t rcv_ssn;		/* Stream Sequence Number */
+	uint16_t rcv_flags;		/* Flags on the incoming message */
+	uint32_t rcv_ppid;		/* The ppid field */
+	uint32_t rcv_tsn;		/* The transport sequence number */
+	uint32_t rcv_cumtsn;		/* The cumulative TSN */
+	uint32_t rcv_context;		/* Opaque context field */
+	sctp_assoc_t rcv_assoc_id;	/* Peer association id */
+};
+.Ed
+.Pp
+These fields have the same meaning as the equivalent fields in
+.Vt struct sctp_sndrcvinfo ,
+defined above.
+.Pp
+To receive an
+.Vt sctp_nxtinfo
+structure, set the
+.Va SCTP_RECVNXTINFO
+socket option, and pass a pointer to a
+.Vt struct sctp_nxtinfo
+structure in
+.Fa info .
+The
+.Vt struct sctp_nxtinfo
+structure has the following format:
+.Bd -literal
+struct sctp_nxtinfo {
+	uint16_t nxt_sid;		/* Next message's stream number */
+	uint16_t nxt_flags;		/* Flags (see below) */
+	uint32_t nxt_ppid;		/* The ppid field */
+	uint32_t nxt_length;		/* Length of next message */
+	sctp_assoc_t nxt_assoc_id;	/* Peer association id */
+};
+.Ed
+.Pp
+The fields
+.Va nxt_sid ,
+.Va nxt_ppid ,
+and
+.Va nxt_assoc_id
+have the same meaning as in
+.Vt struct sctp_rcvinfo ,
+except they refer to the next message rather than the message that was
+received.
+The field
+.Va nxt_length
+contains the length of the part of the next message currently available in
+the socket buffer.
+This may not represent the length of the entire message unless the
+.Va SCTP_COMPLETE
+flag is set in
+.Va nxt_flags .
+.Pp
+The
+.Va nxt_flags
+field is a bitmask which may contain any of the following values:
+.Bl -bullet
+.It
+.Va SCTP_UNORDERED :
+The next message was sent unordered.
+.It
+.Va SCTP_COMPLETE :
+The entirety of the next message has been received in the socket buffer.
+In this case, the
+.Va nxt_length
+field contains the length of the entire message.
+.It
+.Va SCTP_NOTIFICATION :
+The next message is a notification, not a user message.
+.El
+.Pp
+If both the
+.Va SCTP_RECVRCVINFO
+and
+.Va SCTP_RECVNXTINFO
+socket options are set, then pass a pointer to a
+.Vt struct sctp_recvv_rn
+structure in
+.Fa info .
+This struct has the following format:
+.Bd -literal
+struct sctp_recvv_rn {
+	struct sctp_rcvinfo recvv_rcvinfo;
+	struct sctp_nxtinfo recvv_nxtinfo;
+};
+.Ed
+.Pp
+The value pointed to by
+.Fa infolen
+should initially contain the length of the structure to which
+.Fa info
+points.
+When the function returns, it will be set to the length of the
+returned structure.
+Additionally,
+.Fa *infotype
+will be set to one of the following values depending on what type of info
+was returned:
+.Bl -bullet
+.It
+.Va SCTP_RECVV_NOINFO :
+no information was returned.
+.It
+.Va SCTP_RECVV_RCVINFO :
+.Fa *info
+contains an object of type
+.Vt struct sctp_rcvinfo .
+.It
+.Va SCTP_RECVV_NXTINFO :
+.Fa *info
+contains an object of type
+.Vt struct sctp_nxtinfo .
+.It
+.Va SCTP_RECVV_RN :
+.Fa *info
+contains an object of type
+.Vt struct sctp_recvv_rn .
+.El
 .Sh RETURN VALUES
 The call returns the number of bytes received, or -1
 if an error occurred.
@@ -281,6 +439,12 @@ 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 NOTES
+The
+.Fn sctp_recvmsg
+function is deprecated.
+New applications should use
+.Fn sctp_recvv .
 .Sh SEE ALSO
 .Xr getsockopt 2 ,
 .Xr recv 2 ,
@@ -292,3 +456,15 @@ is not connected and is a one-to-one style socket.
 .Xr sctp_send 3 ,
 .Xr sctp_sendmsg 3 ,
 .Xr sctp 4
+.Rs
+.%A R. Stewart
+.%A M. Tuexen
+.%A K. Poon
+.%A P. Lei
+.%A V. Yasevich
+.%T Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)
+.%R RFC 6458
+.%D December 2011
+.Re
+.Sh STANDARDS
+The functions described in this document conform to RFC 6458.