1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd February 2, 2024 29.Dt SCTP_RECVMSG 3 30.Os 31.Sh NAME 32.Nm sctp_recvmsg , 33.Nm sctp_recvv 34.Nd receive a message from an SCTP socket 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/socket.h 40.In netinet/sctp.h 41.Ft ssize_t 42.Fo sctp_recvmsg 43.Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" 44.Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags" 45.Fc 46.Ft ssize_t 47.Fo sctp_recvv 48.Fa "int s" "const struct iovec *iov" "int iovlen" "struct sockaddr *from" 49.Fa "socklen_t *fromlen" "void *info" "socklen_t *infolen" 50.Fa "unsigned int *infotype" "int *flags" 51.Fc 52.Sh DESCRIPTION 53The 54.Fn sctp_recvmsg 55and 56.Fn sctp_recvv 57functions are used to receive a message from another SCTP endpoint. 58They are used by one-to-one (SOCK_STREAM) type sockets after a successful 59.Fn connect 60call or after the application has performed a 61.Fn listen 62followed by a successful 63.Fn accept . 64For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call 65.Fn sctp_recvmsg 66or 67.Fn sctp_recvv 68after having implicitly started an association via one 69of the send calls including 70.Fn sctp_sendmsg , 71.Fn sendto 72and 73.Fn sendmsg . 74Or, an application may also receive a message after having 75called 76.Fn listen 77with a positive backlog to enable the reception of new associations. 78.Pp 79The address of the sender is held in the 80.Fa from 81argument with 82.Fa fromlen 83specifying its size. 84At the completion of a successful 85.Fn sctp_recvmsg 86call 87.Fa from 88will hold the address of the peer and 89.Fa fromlen 90will hold the length of that address. 91Note that 92the address is bounded by the initial value of 93.Fa fromlen 94which is used as an in/out variable. 95.Pp 96The length of the message 97.Fa msg 98to be received is bounded by 99.Fa len . 100If the message is too long to fit in the users 101receive buffer, then the 102.Fa flags 103argument will 104.Em not 105have the 106.Dv MSG_EOR 107flag applied. 108If the message is a complete message then 109the 110.Fa flags 111argument will have 112.Dv MSG_EOR 113set. 114Locally detected errors are 115indicated by a return value of -1 with 116.Va errno 117set accordingly. 118The 119.Fa flags 120argument may also hold the value 121.Dv MSG_NOTIFICATION . 122When this 123occurs it indicates that the message received is 124.Em not 125from 126the peer endpoint, but instead is a notification from the 127SCTP stack (see 128.Xr sctp 4 129for more details). 130Note that no notifications are ever 131given unless the user subscribes to such notifications using 132the 133.Dv SCTP_EVENTS 134socket option. 135.Pp 136If no messages are available at the socket then 137.Fn sctp_recvmsg 138normally blocks on the reception of a message or NOTIFICATION, unless the 139socket has been placed in non-blocking I/O mode. 140The 141.Xr select 2 142system call may be used to determine when it is possible to 143receive a message. 144.Pp 145The 146.Fa sinfo 147argument is defined as follows. 148.Bd -literal 149struct sctp_sndrcvinfo { 150 uint16_t sinfo_stream; /* Stream arriving on */ 151 uint16_t sinfo_ssn; /* Stream Sequence Number */ 152 uint16_t sinfo_flags; /* Flags on the incoming message */ 153 uint32_t sinfo_ppid; /* The ppid field */ 154 uint32_t sinfo_context; /* context field */ 155 uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */ 156 uint32_t sinfo_tsn; /* The transport sequence number */ 157 uint32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ 158 sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ 159}; 160.Ed 161.Pp 162The 163.Fa sinfo->sinfo_ppid 164field is an opaque 32 bit value that is passed transparently 165through the stack from the peer endpoint. 166Note that the stack passes this value without regard to byte 167order. 168.Pp 169The 170.Fa sinfo->sinfo_flags 171field may include the following: 172.Bd -literal 173#define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ 174.Ed 175.Pp 176The 177.Dv SCTP_UNORDERED 178flag is used to specify that the message arrived with no 179specific order and was delivered to the peer application 180as soon as possible. 181When this flag is absent the message 182was delivered in order within the stream it was received. 183.Pp 184The 185.Fa sinfo->sinfo_stream 186field is the SCTP stream that the message was received on. 187Streams in SCTP are reliable (or partially reliable) flows of ordered 188messages. 189.Pp 190The 191.Fa sinfo->sinfo_context 192field is used only if the local application set an association level 193context with the 194.Dv SCTP_CONTEXT 195socket option. 196Optionally a user process can use this value to index some application 197specific data structure for all data coming from a specific 198association. 199.Pp 200The 201.Fa sinfo->sinfo_ssn 202field will hold the stream sequence number assigned 203by the peer endpoint if the message is 204.Em not 205unordered. 206For unordered messages this field holds an undefined value. 207.Pp 208The 209.Fa sinfo->sinfo_tsn 210field holds a transport sequence number (TSN) that was assigned 211to this message by the peer endpoint. 212For messages that fit in or less 213than the path MTU this will be the only TSN assigned. 214Note that for messages that span multiple TSNs this 215value will be one of the TSNs that was used on the 216message. 217.Pp 218The 219.Fa sinfo->sinfo_cumtsn 220field holds the current cumulative acknowledgment point of 221the transport association. 222Note that this may be larger 223or smaller than the TSN assigned to the message itself. 224.Pp 225The 226.Fa sinfo->sinfo_assoc_id 227is the unique association identification that was assigned 228to the association. 229For one-to-many (SOCK_SEQPACKET) type 230sockets this value can be used to send data to the peer without 231the use of an address field. 232It is also quite useful in 233setting various socket options on the specific association 234(see 235.Xr sctp 4 ) . 236.Pp 237The 238.Fa sinfo->info_timetolive 239field is not used by 240.Fn sctp_recvmsg . 241.Pp 242The 243.Fn sctp_recvv 244function works as 245.Fn sctp_recvmsg 246with two differences. 247Firstly, the receive buffer is passed as an array containing 248.Vt iocnt 249objects of type 250.Vt struct iovec , 251where the received data will be scattered in the same manner as 252.Xr readv 2 . 253Secondly, the 254.Fa sinfo 255argument is replaced by the tuple 256.Fa info , 257.Fa infolen , 258and 259.Fa infotype , 260which allow different information to be received based on the socket options. 261.Pp 262To receive an 263.Vt sctp_rcvinfo 264structure, set the 265.Va SCTP_RECVRCVINFO 266socket option, and pass a pointer to a 267.Vt struct sctp_rcvinfo 268structure in 269.Fa info . 270The 271.Vt sctp_rcvinfo 272structure has the following format: 273.Bd -literal 274struct sctp_rcvinfo { 275 uint16_t rcv_sid; /* Stream arriving on */ 276 uint16_t rcv_ssn; /* Stream Sequence Number */ 277 uint16_t rcv_flags; /* Flags on the incoming message */ 278 uint32_t rcv_ppid; /* The ppid field */ 279 uint32_t rcv_tsn; /* The transport sequence number */ 280 uint32_t rcv_cumtsn; /* The cumulative TSN */ 281 uint32_t rcv_context; /* Opaque context field */ 282 sctp_assoc_t rcv_assoc_id; /* Peer association id */ 283}; 284.Ed 285.Pp 286These fields have the same meaning as the equivalent fields in 287.Vt struct sctp_sndrcvinfo , 288defined above. 289.Pp 290To receive an 291.Vt sctp_nxtinfo 292structure, set the 293.Va SCTP_RECVNXTINFO 294socket option, and pass a pointer to a 295.Vt struct sctp_nxtinfo 296structure in 297.Fa info . 298The 299.Vt struct sctp_nxtinfo 300structure has the following format: 301.Bd -literal 302struct sctp_nxtinfo { 303 uint16_t nxt_sid; /* Next message's stream number */ 304 uint16_t nxt_flags; /* Flags (see below) */ 305 uint32_t nxt_ppid; /* The ppid field */ 306 uint32_t nxt_length; /* Length of next message */ 307 sctp_assoc_t nxt_assoc_id; /* Peer association id */ 308}; 309.Ed 310.Pp 311The fields 312.Va nxt_sid , 313.Va nxt_ppid , 314and 315.Va nxt_assoc_id 316have the same meaning as in 317.Vt struct sctp_rcvinfo , 318except they refer to the next message rather than the message that was 319received. 320The field 321.Va nxt_length 322contains the length of the part of the next message currently available in 323the socket buffer. 324This may not represent the length of the entire message unless the 325.Va SCTP_COMPLETE 326flag is set in 327.Va nxt_flags . 328.Pp 329The 330.Va nxt_flags 331field is a bitmask which may contain any of the following values: 332.Bl -bullet 333.It 334.Va SCTP_UNORDERED : 335The next message was sent unordered. 336.It 337.Va SCTP_COMPLETE : 338The entirety of the next message has been received in the socket buffer. 339In this case, the 340.Va nxt_length 341field contains the length of the entire message. 342.It 343.Va SCTP_NOTIFICATION : 344The next message is a notification, not a user message. 345.El 346.Pp 347If both the 348.Va SCTP_RECVRCVINFO 349and 350.Va SCTP_RECVNXTINFO 351socket options are set, then pass a pointer to a 352.Vt struct sctp_recvv_rn 353structure in 354.Fa info . 355This struct has the following format: 356.Bd -literal 357struct sctp_recvv_rn { 358 struct sctp_rcvinfo recvv_rcvinfo; 359 struct sctp_nxtinfo recvv_nxtinfo; 360}; 361.Ed 362.Pp 363The value pointed to by 364.Fa infolen 365should initially contain the length of the structure to which 366.Fa info 367points. 368When the function returns, it will be set to the length of the 369returned structure. 370Additionally, 371.Fa *infotype 372will be set to one of the following values depending on what type of info 373was returned: 374.Bl -bullet 375.It 376.Va SCTP_RECVV_NOINFO : 377no information was returned. 378.It 379.Va SCTP_RECVV_RCVINFO : 380.Fa *info 381contains an object of type 382.Vt struct sctp_rcvinfo . 383.It 384.Va SCTP_RECVV_NXTINFO : 385.Fa *info 386contains an object of type 387.Vt struct sctp_nxtinfo . 388.It 389.Va SCTP_RECVV_RN : 390.Fa *info 391contains an object of type 392.Vt struct sctp_recvv_rn . 393.El 394.Sh RETURN VALUES 395The call returns the number of bytes received, or -1 396if an error occurred. 397.Sh ERRORS 398The 399.Fn sctp_recvmsg 400system call 401fails if: 402.Bl -tag -width Er 403.It Bq Er EBADF 404An invalid descriptor was specified. 405.It Bq Er ENOTSOCK 406The argument 407.Fa s 408is not a socket. 409.It Bq Er EFAULT 410An invalid user space address was specified for an argument. 411.It Bq Er EMSGSIZE 412The socket requires that message be sent atomically, 413and the size of the message to be sent made this impossible. 414.It Bq Er EAGAIN 415The socket is marked non-blocking and the requested operation 416would block. 417.It Bq Er ENOBUFS 418The system was unable to allocate an internal buffer. 419The operation may succeed when buffers become available. 420.It Bq Er ENOBUFS 421The output queue for a network interface was full. 422This generally indicates that the interface has stopped sending, 423but may be caused by transient congestion. 424.It Bq Er EHOSTUNREACH 425The remote host was unreachable. 426.It Bq Er ENOTCONN 427On a one-to-one style socket no association exists. 428.It Bq Er ECONNRESET 429An abort was received by the stack while the user was 430attempting to send data to the peer. 431.It Bq Er ENOENT 432On a one to many style socket no address is specified 433so that the association cannot be located or the 434SCTP_ABORT flag was specified on a non-existing association. 435.It Bq Er EPIPE 436The socket is unable to send anymore data 437.Dv ( SBS_CANTSENDMORE 438has been set on the socket). 439This typically means that the socket 440is not connected and is a one-to-one style socket. 441.El 442.Sh NOTES 443The 444.Fn sctp_recvmsg 445function is deprecated. 446New applications should use 447.Fn sctp_recvv . 448.Sh SEE ALSO 449.Xr getsockopt 2 , 450.Xr recv 2 , 451.Xr select 2 , 452.Xr sendmsg 2 , 453.Xr setsockopt 2 , 454.Xr socket 2 , 455.Xr write 2 , 456.Xr sctp_send 3 , 457.Xr sctp_sendmsg 3 , 458.Xr sctp 4 459.Rs 460.%A R. Stewart 461.%A M. Tuexen 462.%A K. Poon 463.%A P. Lei 464.%A V. Yasevich 465.%T Sockets API Extensions for the Stream Control Transmission Protocol (SCTP) 466.%R RFC 6458 467.%D December 2011 468.Re 469.Sh STANDARDS 470The functions described in this document conform to RFC 6458. 471