git: 5590bacaafd8 - main - sctp: update manpages
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 03 Feb 2024 01:36:24 UTC
The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=5590bacaafd8687bf522bb0413178c177c43f952 commit 5590bacaafd8687bf522bb0413178c177c43f952 Author: Lexi Winter <lexi@le-fay.org> AuthorDate: 2024-02-03 00:20:57 +0000 Commit: Warner Losh <imp@FreeBSD.org> CommitDate: 2024-02-03 01:35:00 +0000 sctp: update manpages Add missing documentation for sctp_sendv(3) and sctp_recvv(3). Add a note that sctp_send(3), sctp_sendx(3) and sctp_recvmsg(3) are deprecated by RFC 6458. Add a STANDARDS section to all functions specified in RFC 6458 to indicate their standards conformance. MFC after: 2 weeks Reviewed by: imp, bcr, kp, tuexen Pull Request: https://github.com/freebsd/freebsd-src/pull/965 --- lib/libc/net/Makefile.inc | 10 ++- lib/libc/net/sctp_bindx.3 | 16 +++- lib/libc/net/sctp_connectx.3 | 16 +++- lib/libc/net/sctp_freepaddrs.3 | 18 +++- lib/libc/net/sctp_getpaddrs.3 | 18 +++- lib/libc/net/sctp_recvmsg.3 | 194 +++++++++++++++++++++++++++++++++++++++-- lib/libc/net/sctp_send.3 | 192 +++++++++++++++++++++++++++++++++++++++- lib/libc/net/sctp_sendmsg.3 | 6 +- lib/libc/sys/sctp_peeloff.2 | 6 +- 9 files changed, 454 insertions(+), 22 deletions(-) diff --git a/lib/libc/net/Makefile.inc b/lib/libc/net/Makefile.inc index 35d88edb3a95..d75d42fb0679 100644 --- a/lib/libc/net/Makefile.inc +++ b/lib/libc/net/Makefile.inc @@ -110,10 +110,12 @@ MLINKS+=inet.3 addr.3 \ inet.3 inet_pton.3 \ inet.3 network.3 \ inet.3 ntoa.3 -MLINKS+= sctp_send.3 sctp_sendx.3 -MLINKS+= sctp_sendmsg.3 sctp_sendmsgx.3 -MLINKS+= sctp_freepaddrs.3 sctp_freeladdrs.3 -MLINKS+= sctp_getpaddrs.3 sctp_getladdrs.3 +MLINKS+=sctp_freepaddrs.3 sctp_freeladdrs.3 +MLINKS+=sctp_getpaddrs.3 sctp_getladdrs.3 +MLINKS+=sctp_recvmsg.3 sctp_recvv.3 +MLINKS+=sctp_sendmsg.3 sctp_sendmsgx.3 +MLINKS+=sctp_send.3 sctp_sendx.3 \ + sctp_send.3 sctp_sendv.3 MLINKS+=inet_net.3 inet_net_ntop.3 \ inet_net.3 inet_net_pton.3 MLINKS+=inet6_opt_init.3 inet6_opt_append.3 \ diff --git a/lib/libc/net/sctp_bindx.3 b/lib/libc/net/sctp_bindx.3 index d233a6fa37ce..93a9857ddc86 100644 --- a/lib/libc/net/sctp_bindx.3 +++ b/lib/libc/net/sctp_bindx.3 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd June 14, 2015 +.Dd February 2, 2024 .Dt SCTP_BINDX 3 .Os .Sh NAME @@ -105,3 +105,17 @@ is not a socket. .Sh SEE ALSO .Xr bind 2 , .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 +.Fn sctp_bindx +function conforms to RFC 6458. diff --git a/lib/libc/net/sctp_connectx.3 b/lib/libc/net/sctp_connectx.3 index cd903ddd01ce..c6cbca14006d 100644 --- a/lib/libc/net/sctp_connectx.3 +++ b/lib/libc/net/sctp_connectx.3 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd June 19, 2007 +.Dd February 2, 2024 .Dt SCTP_CONNECTX 3 .Os .Sh NAME @@ -98,3 +98,17 @@ is not a socket. .Sh SEE ALSO .Xr connect 2 , .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 +.Fn sctp_connectx +function conforms to RFC 6458. diff --git a/lib/libc/net/sctp_freepaddrs.3 b/lib/libc/net/sctp_freepaddrs.3 index fb85cae089c8..07d486920125 100644 --- a/lib/libc/net/sctp_freepaddrs.3 +++ b/lib/libc/net/sctp_freepaddrs.3 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 15, 2006 +.Dd February 2, 2024 .Dt SCTP_FREEPADDRS 3 .Os .Sh NAME @@ -59,3 +59,19 @@ none. .Xr sctp_getladdrs 3 , .Xr sctp_getpaddrs 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 +.Fn sctp_freepaddrs +and +.Fn sctp_freeladdrs +functions conform to RFC 6458. diff --git a/lib/libc/net/sctp_getpaddrs.3 b/lib/libc/net/sctp_getpaddrs.3 index efcf3f47efea..0e80e72bbaf6 100644 --- a/lib/libc/net/sctp_getpaddrs.3 +++ b/lib/libc/net/sctp_getpaddrs.3 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 15, 2006 +.Dd February 2, 2024 .Dt SCTP_GETPADDRS 3 .Os .Sh NAME @@ -91,3 +91,19 @@ is not a socket. .Xr sctp_freeladdrs 3 , .Xr sctp_freepaddrs 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 +.Fn sctp_getpaddrs +and +.Fn sctp_getladdrs +functions conform to RFC 6458. diff --git a/lib/libc/net/sctp_recvmsg.3 b/lib/libc/net/sctp_recvmsg.3 index a5f794743f53..53aae5dd2527 100644 --- a/lib/libc/net/sctp_recvmsg.3 +++ b/lib/libc/net/sctp_recvmsg.3 @@ -25,11 +25,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 23, 2015 +.Dd February 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 @@ -42,15 +43,19 @@ .Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" .Fa "socklen_t * restrict 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 @@ -58,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 , @@ -231,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. @@ -279,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 , @@ -290,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. diff --git a/lib/libc/net/sctp_send.3 b/lib/libc/net/sctp_send.3 index 32319ac8493c..ce34a2554576 100644 --- a/lib/libc/net/sctp_send.3 +++ b/lib/libc/net/sctp_send.3 @@ -25,12 +25,13 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 15, 2006 +.Dd February 2, 2024 .Dt SCTP_SEND 3 .Os .Sh NAME .Nm sctp_send , -.Nm sctp_sendx +.Nm sctp_sendx , +.Nm sctp_sendv .Nd send a message from an SCTP socket .Sh LIBRARY .Lb libc @@ -48,11 +49,27 @@ .Fa "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs" .Fa "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags" .Fc +.Ft ssize_t +.Fo sctp_sendv +.Fa "int sd" "const struct iovec *iov" "int iocnt" "struct sockaddr *addrs" +.Fa "int addrcnt" "void *info" "socklen_t infolen" "unsigned int infotype" +.Fa "int flags" +.Fc .Sh DESCRIPTION The .Fn sctp_send system call is used to transmit a message to another SCTP endpoint. +The +.Fn sctp_sendx +function is used to specify multiple peer addresses when creating an implicit +association, as in +.Xr sctp_connectx 3 . +The +.Fn sctp_sendv +function is used to transmit a message whose data is gathered from the +provided I/O buffers. +.Pp .Fn sctp_send may be used to send data to an existing association for both one-to-many (SOCK_SEQPACKET) and one-to-one (SOCK_STREAM) socket types. @@ -253,6 +270,7 @@ and .Fa sinfo->sinfo_cumtsn are used only when receiving messages and are thus ignored by .Fn sctp_send . +.Pp The function .Fn sctp_sendx has the same properties as @@ -281,6 +299,156 @@ the association in place of the association id. If both an address and an association id are specified, the association id has priority. +.Pp +The function +.Fn sctp_sendv +works as +.Fn sctp_sendx , +with two differences. +Firstly, the data to be written is passed as an array containing +.Vt iocnt +objects of type +.Vt struct iovec , +which will be gathered for sending in the same manner as +.Xr writev 2 . +Secondly, the +.Fa info +argument is replaced by the tuple +.Fa sinfo , +.Fa infolen , +.Fa infotype , +where +.Fa sinfo +is a pointer to a struct of size +.Fa infolen +whose type is indicated by the +.Fa infotype +argument. +.Pp +If no information is passed, set +.Fa infotype +to +.Va SCTP_SENDV_NOINFO . +.Fa sinfo +may be a null pointer. +.Pp +If +.Fa sinfo +points to a +.Vt struct sctp_sndinfo , +set +.Fa infotype +to +.Va SCTP_SENDV_SNDINFO . +The +.Vt sctp_sndinfo +structure has the following format: +.Bd -literal +struct sctp_sndinfo { + uint16_t snd_sid; /* stream identifier */ + uint16_t snd_flags; /* Flags */ + uint32_t snd_ppid; /* ppid field */ + uint32_t snd_context; /* context field */ + sctp_assoc_t snd_assoc_id; /* association id */ +}; +.Ed +.Pp +The meaning of these fields is the same as in +.Vt struct sctp_sndrcvinfo , +described above. +.Pp +If +.Fa sinfo +points to a +.Vt struct sctp_authinfo , +set +.Fa infotype +to +.Va SCTP_SENDV_AUTHINFO . +The +.Vt sctp_authinfo +struct has the following format: +.Bd -literal +struct sctp_authinfo { + uint16_t auth_keynumber; /* Shared key identifier */ +}; +.Ed +.Pp +The +.Va auth_keynumber +field specifies the shared key identifier that will be used for sending the +message. +.Pp +If +.Fa sinfo +points to a +.Vt struct sctp_prinfo , +set +.Fa infotype +to +.Va SCTP_SENDV_PRINFO . +The +.Vt sctp_prinfo +structure has the following format: +.Bd -literal +struct sctp_prinfo { + uint16_t pr_policy; /* PR-SCTP policy */ + uint32_t pr_value; /* PR-SCTP Policy option */ +}; +.Ed +.Pp +The +.Va pr_policy +field should be set to either +.Va SCTP_PR_SCTP_NONE +to use reliable transmission (in which case the field +.Va pr_value +is ignored), or +.Va SCTP_PR_SCTP_TTL +to use RFC 3758 timed reliability, in which case the field +.Va pr_value +contains the lifetime in milliseconds. +.Pp +To pass two or more types in +.Fa sinfo , +set +.Fa infotype +to +.Va SCTP_SENDV_SPA +and pass a pointer to a +.Vt struct sctp_sendv_spa +in +.Fa sinfo . +The +.Ft sctp_sendv_spa +structure has the following format: +.Bd -literal +struct sctp_sendv_spa { + uint32_t sendv_flags; + struct sctp_sndinfo sendv_sndinfo; + struct sctp_prinfo sendv_prinfo; + struct sctp_authinfo sendv_authinfo; +}; +.Ed +.Pp +The +.Va sendv_flags +member should be set to the bitwise OR of the flags +.Va SCTP_SEND_SNDINFO_VALID , +.Va SCTP_SEND_PRINFO_VALID , +and +.Va SCTP_SEND_AUTHINFO_VALID +to indicate which fields of the struct contain valid data. +.Pp +If +.Fa infotype +is set to SCTP_SENDV_NOINFO, the +.Fa infolen +argument should be set to zero. +Otherwise, +.Fa infolen +should be set to the length of the data structure pointed to by +.Fa info . .Sh RETURN VALUES The call returns the number of characters sent, or -1 if an error occurred. @@ -329,6 +497,14 @@ 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 functions +.Fn sctp_send +and +.Fn sctp_sendx +are deprecated. +New applications should use +.Fn sctp_sendv . .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , @@ -340,6 +516,18 @@ is not connected and is a one-to-one style socket. .Xr sctp_recvmsg 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. .Sh BUGS Because .Fn sctp_send diff --git a/lib/libc/net/sctp_sendmsg.3 b/lib/libc/net/sctp_sendmsg.3 index dedfc3324cd3..47a7c7db2d8b 100644 --- a/lib/libc/net/sctp_sendmsg.3 +++ b/lib/libc/net/sctp_sendmsg.3 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 15, 2006 +.Dd February 2, 2024 .Dt SCTP_SENDMSG 3 .Os .Sh NAME @@ -96,13 +96,13 @@ is set to the message is not transmitted. .Pp No indication of failure to deliver is implicit in a -.Xr sctp_sendmsg 3 +.Fn sctp_sendmsg call. Locally detected errors are indicated by a return value of -1. .Pp If no space is available at the socket to hold the message to be transmitted, then -.Xr sctp_sendmsg 3 +.Fn sctp_sendmsg normally blocks, unless the socket has been placed in non-blocking I/O mode. The diff --git a/lib/libc/sys/sctp_peeloff.2 b/lib/libc/sys/sctp_peeloff.2 index 5aa246cfa49f..f31282e555db 100644 --- a/lib/libc/sys/sctp_peeloff.2 +++ b/lib/libc/sys/sctp_peeloff.2 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 30, 2007 +.Dd February 2, 2024 .Dt SCTP_PEELOFF 2 .Os .Sh NAME @@ -72,3 +72,7 @@ is not a socket. .El .Sh SEE ALSO .Xr sctp 4 +.Sh STANDARDS +The +.Fn sctp_peeloff +function conforms to RFC 6458.