1.\" $OpenBSD: recv.2,v 1.51 2023/08/17 05:45:51 jmc Exp $ 2.\" $NetBSD: recv.2,v 1.6 1995/02/27 12:36:08 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)recv.2 8.3 (Berkeley) 2/21/94 32.\" 33.Dd $Mdocdate: August 17 2023 $ 34.Dt RECV 2 35.Os 36.Sh NAME 37.Nm recv , 38.Nm recvfrom , 39.Nm recvmsg , 40.Nm recvmmsg 41.Nd receive a message from a socket 42.Sh SYNOPSIS 43.In sys/socket.h 44.Ft ssize_t 45.Fn recv "int s" "void *buf" "size_t len" "int flags" 46.Ft ssize_t 47.Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr *from" "socklen_t *fromlen" 48.Ft ssize_t 49.Fn recvmsg "int s" "struct msghdr *msg" "int flags" 50.Ft int 51.Fn recvmmsg "int s" "struct mmsghdr *mmsg" "unsigned int vlen" "int flags" "struct timespec *timeout" 52.Sh DESCRIPTION 53.Fn recv , 54.Fn recvfrom , 55.Fn recvmsg , 56and 57.Fn recvmmsg 58are used to receive messages from a socket, 59.Fa s . 60.Fn recv 61is normally used only on a 62.Em connected 63socket (see 64.Xr connect 2 ) . 65.Fn recvfrom , 66.Fn recvmsg , 67and 68.Fn recvmmsg 69may be used to receive 70data on a socket whether or not it is connection-oriented. 71.Pp 72.Fn recv 73is identical to 74.Fn recvfrom 75with a null 76.Fa from 77parameter. 78.Pp 79If 80.Fa from 81is non-null and the socket is not connection-oriented, 82the source address of the message is filled in. 83.Fa fromlen 84is a value-result parameter, initialized to the size of 85the buffer associated with 86.Fa from , 87and modified on return to indicate the actual size of the 88address stored there. 89.Pp 90If no messages are available at the socket, the 91receive call waits for a message to arrive, unless 92the socket is nonblocking (see 93.Xr fcntl 2 ) 94in which case the value 95\-1 is returned and the external variable 96.Va errno 97set to 98.Er EAGAIN . 99The receive calls normally return any data available, 100up to the requested amount, 101rather than waiting for receipt of the full amount requested; 102this behavior is affected by the socket-level options 103.Dv SO_RCVLOWAT 104and 105.Dv SO_RCVTIMEO 106described in 107.Xr getsockopt 2 . 108.Pp 109The 110.Xr select 2 111or 112.Xr poll 2 113system calls may be used to determine when more data arrive. 114.Pp 115The 116.Fa flags 117argument is the bitwise OR of zero or more of the following values: 118.Pp 119.Bl -tag -width "MSG_CMSG_CLOEXECXX" -offset indent -compact 120.It Dv MSG_OOB 121process out-of-band data 122.It Dv MSG_PEEK 123peek at incoming message 124.It Dv MSG_WAITALL 125wait for full request or error 126.It Dv MSG_DONTWAIT 127don't block 128.It Dv MSG_CMSG_CLOEXEC 129set the close-on-exec flag on received file descriptors 130.El 131.Pp 132The 133.Dv MSG_OOB 134flag requests receipt of out-of-band data 135that would not be received in the normal data stream. 136Some protocols place expedited data at the head of the normal 137data queue, and thus this flag cannot be used with such protocols. 138The 139.Dv MSG_PEEK 140flag causes the receive operation to return data 141from the beginning of the receive queue without removing that 142data from the queue. 143Thus, a subsequent receive call will return the same data. 144The 145.Dv MSG_WAITALL 146flag requests that the operation block until 147the full request is satisfied. 148However, the call may still return less data than requested 149if a signal is caught, an error or disconnect occurs, 150or the next data to be received is of a different type than that returned. 151The 152.Dv MSG_DONTWAIT 153flag requests the call to return when it would block otherwise. 154If no data is available, 155.Va errno 156is set to 157.Er EAGAIN . 158This flag is not available in strict ANSI or C99 compilation mode. 159The 160.Dv MSG_CMSG_CLOEXEC 161requests that any file descriptors received as ancillary data with 162.Fn recvmsg 163and 164.Fn recvmmsg 165(see below) 166have their close-on-exec flag set. 167.Pp 168The 169.Fn recvmsg 170call uses a 171.Fa msghdr 172structure to minimize the number of directly supplied parameters. 173This structure has the following form, as defined in 174.In sys/socket.h : 175.Bd -literal 176struct msghdr { 177 void *msg_name; /* optional address */ 178 socklen_t msg_namelen; /* size of address */ 179 struct iovec *msg_iov; /* scatter/gather array */ 180 unsigned int msg_iovlen; /* # elements in msg_iov */ 181 void *msg_control; /* ancillary data, see below */ 182 socklen_t msg_controllen; /* ancillary data buffer len */ 183 int msg_flags; /* flags on received message */ 184}; 185.Ed 186.Pp 187Here 188.Fa msg_name 189and 190.Fa msg_namelen 191specify the source address if the socket is unconnected; 192.Fa msg_name 193may be given as a null pointer if no names are desired or required. 194.Fa msg_iov 195and 196.Fa msg_iovlen 197describe scatter gather locations, as discussed in 198.Xr read 2 . 199.Fa msg_control , 200which has length 201.Fa msg_controllen , 202points to a buffer for other protocol control related messages 203or other miscellaneous ancillary data. 204The messages are of the form: 205.Bd -literal 206struct cmsghdr { 207 socklen_t cmsg_len; /* data byte count, including hdr */ 208 int cmsg_level; /* originating protocol */ 209 int cmsg_type; /* protocol-specific type */ 210/* followed by u_char cmsg_data[]; */ 211}; 212.Ed 213.Pp 214See 215.Xr CMSG_DATA 3 216for how these messages are constructed and decomposed. 217.Pp 218Open file descriptors are now passed as ancillary data for 219.Dv AF_UNIX 220domain and 221.Xr socketpair 2 222sockets, with 223.Fa cmsg_level 224set to 225.Dv SOL_SOCKET 226and 227.Fa cmsg_type 228set to 229.Dv SCM_RIGHTS . 230.Pp 231The 232.Fa msg_flags 233field is set on return according to the message received. 234It will contain zero or more of the following values: 235.Pp 236.Bl -tag -width MSG_CTRUNC -offset indent -compact 237.It Dv MSG_OOB 238Returned to indicate that expedited or out-of-band data was received. 239.It Dv MSG_EOR 240Indicates end-of-record; 241the data returned completed a record (generally used with sockets of type 242.Dv SOCK_SEQPACKET ) . 243.It Dv MSG_TRUNC 244Indicates that 245the trailing portion of a datagram was discarded because the datagram 246was larger than the buffer supplied. 247.It Dv MSG_CTRUNC 248Indicates that some 249control data were discarded due to lack of space in the buffer 250for ancillary data. 251.It Dv MSG_BCAST 252Indicates that the packet was received as broadcast. 253.It Dv MSG_MCAST 254Indicates that the packet was received as multicast. 255.El 256.Pp 257The 258.Fn recvmmsg 259call uses an array of the 260.Fa mmsghdr 261structure of length 262.Fa vlen 263to group multiple 264.Fa msghdr 265structures into a single system call. 266.Fa vlen 267is capped at maximum 268.Dv 1024 269messages that are received in a single call. 270The 271.Fa flags 272field allows setting 273.Dv MSG_WAITFORONE 274to wait for one 275.Fa msghdr , 276and set 277.Dv MSG_DONTWAIT 278for all subsequent messages. 279A provided 280.Fa timeout 281limits the time spent in the function but it does not limit the 282time spent in lower parts of the kernel. 283.Pp 284The 285.Fa mmsghdr 286structure has the following form, as defined in 287.In sys/socket.h : 288.Bd -literal 289struct mmsghdr { 290 struct msghdr msg_hdr; 291 unsigned int msg_len; 292}; 293.Ed 294.Pp 295Here 296.Fa msg_len 297indicated the number of bytes received for each 298.Fa msg_hdr 299member. 300.Sh RETURN VALUES 301The 302.Fn recv , 303.Fn recvfrom , 304and 305.Fn recvmsg 306calls return the number of bytes received, or \-1 if an error occurred. 307The 308.Fn recvmmsg 309call returns the number of messages received, or \-1 310if an error occurred before the first message has been received. 311.Sh ERRORS 312.Fn recv , 313.Fn recvfrom , 314.Fn recvmsg , 315and 316.Fn recvmmsg 317fail if: 318.Bl -tag -width "[EHOSTUNREACH]" 319.It Bq Er EBADF 320The argument 321.Fa s 322is an invalid descriptor. 323.It Bq Er ENOTCONN 324The socket is associated with a connection-oriented protocol 325and has not been connected (see 326.Xr connect 2 327and 328.Xr accept 2 ) . 329.It Bq Er ENOTSOCK 330The argument 331.Fa s 332does not refer to a socket. 333.It Bq Er EAGAIN 334The socket is marked non-blocking, and the receive operation 335would block, or 336a receive timeout had been set, 337and the timeout expired before data were received. 338.It Bq Er EINTR 339The receive was interrupted by delivery of a signal before 340any data were available. 341.It Bq Er EFAULT 342The receive buffer pointer(s) point outside the process's 343address space. 344.It Bq Er EHOSTUNREACH 345A socket operation was attempted to an unreachable host. 346.It Bq Er EHOSTDOWN 347A socket operation failed 348because the destination host was down. 349.It Bq Er ENETDOWN 350A socket operation encountered a dead network. 351.It Bq Er ECONNREFUSED 352The socket is associated with a connection-oriented protocol 353and the connection was forcefully rejected (see 354.Xr connect 2 ) . 355.El 356.Pp 357In addition, 358.Fn recv 359and 360.Fn recvfrom 361may return the following error: 362.Bl -tag -width Er 363.It Bq Er EINVAL 364.Fa len 365was larger than 366.Dv SSIZE_MAX . 367.El 368.Pp 369And 370.Fn recvmsg 371and 372.Fn recvmmsg 373may return one of the following errors: 374.Bl -tag -width Er 375.It Bq Er EINVAL 376The sum of the 377.Fa iov_len 378values in the 379.Fa msg_iov 380array overflowed an 381.Em ssize_t . 382.It Bq Er EMSGSIZE 383The 384.Fa msg_iovlen 385member of 386.Fa msg 387was less than 0 or larger than 388.Dv IOV_MAX . 389.It Bq Er EMSGSIZE 390The receiving program did not have sufficient 391free file descriptor slots. 392The descriptors are closed 393and any pending data can be returned 394by another call to 395.Fn recvmsg . 396.El 397.Sh SEE ALSO 398.Xr connect 2 , 399.Xr fcntl 2 , 400.Xr getsockopt 2 , 401.Xr poll 2 , 402.Xr read 2 , 403.Xr select 2 , 404.Xr socket 2 , 405.Xr socketpair 2 , 406.Xr CMSG_DATA 3 , 407.Xr sockatmark 3 408.Sh STANDARDS 409The 410.Fn recv , 411.Fn recvfrom , 412and 413.Fn recvmsg 414functions conform to 415.St -p1003.1-2008 . 416The 417.Dv MSG_DONTWAIT , 418.Dv MSG_BCAST , 419and 420.Dv MSG_MCAST 421flags are extensions to that specification. 422.Sh HISTORY 423The 424.Fn recv 425function call appeared in 426.Bx 4.1c . 427The 428.Fn recvmmsg 429syscall first appeared in Linux 2.6.33 and was added to 430.Ox 7.2 . 431.Sh CAVEATS 432Calling 433.Fn recvmsg 434with a control message having no or an empty scatter/gather array 435exposes variations in implementations. 436To avoid these, always use an 437.Fa iovec 438with at least a one-byte buffer and set 439.Fa msg_iov 440and an 441.Fa msg_iovlen 442to use this vector. 443