1.\" Copyright (c) 1983, 1990, 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.\" @(#)recv.2 8.3 (Berkeley) 2/21/94 29.\" 30.Dd July 30, 2022 31.Dt RECV 2 32.Os 33.Sh NAME 34.Nm recv , 35.Nm recvfrom , 36.Nm recvmsg , 37.Nm recvmmsg 38.Nd receive message(s) from a socket 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/socket.h 43.Ft ssize_t 44.Fn recv "int s" "void *buf" "size_t len" "int flags" 45.Ft ssize_t 46.Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen" 47.Ft ssize_t 48.Fn recvmsg "int s" "struct msghdr *msg" "int flags" 49.Ft ssize_t 50.Fn recvmmsg "int s" "struct mmsghdr * restrict msgvec" "size_t vlen" "int flags" "const struct timespec * restrict timeout" 51.Sh DESCRIPTION 52The 53.Fn recvfrom , 54.Fn recvmsg , 55and 56.Fn recvmmsg 57system calls 58are used to receive messages from a socket, 59and may be used to receive data on a socket whether or not 60it is connection-oriented. 61.Pp 62If 63.Fa from 64is not a null pointer 65and the socket is not connection-oriented, 66the source address of the message is filled in. 67The 68.Fa fromlen 69argument 70is a value-result argument, initialized to the size of 71the buffer associated with 72.Fa from , 73and modified on return to indicate the actual size of the 74address stored there. 75.Pp 76The 77.Fn recv 78function is normally used only on a 79.Em connected 80socket (see 81.Xr connect 2 ) 82and is identical to 83.Fn recvfrom 84with a 85null pointer passed as its 86.Fa from 87argument. 88.Pp 89The 90.Fn recvmmsg 91function is used to receive multiple 92messages at a call. 93Their number is supplied by 94.Fa vlen . 95The messages are placed in the buffers described by 96.Fa msgvec 97vector, after reception. 98The size of each received message is placed in the 99.Fa msg_len 100field of each element of the vector. 101If 102.Fa timeout 103is NULL the call blocks until the data is available for each 104supplied message buffer. 105Otherwise it waits for data for the specified amount of time. 106If the timeout expired and there is no data received, 107a value 0 is returned. 108The 109.Xr ppoll 2 110system call is used to implement the timeout mechanism, 111before first receive is performed. 112.Pp 113The 114.Fn recv , 115.Fn recvfrom 116and 117.Fn recvmsg 118return the length of the message on successful 119completion, whereas 120.Fn recvmmsg 121returns the number of received messages. 122If a message is too long to fit in the supplied buffer, 123excess bytes may be discarded depending on the type of socket 124the message is received from (see 125.Xr socket 2 ) . 126.Pp 127If no messages are available at the socket, the 128receive call waits for a message to arrive, unless 129the socket is non-blocking (see 130.Xr fcntl 2 ) 131in which case the value 132\-1 is returned and the global variable 133.Va errno 134is set to 135.Er EAGAIN . 136The receive calls except 137.Fn recvmmsg 138normally return any data available, 139up to the requested amount, 140rather than waiting for receipt of the full amount requested; 141this behavior is affected by the socket-level options 142.Dv SO_RCVLOWAT 143and 144.Dv SO_RCVTIMEO 145described in 146.Xr getsockopt 2 . 147The 148.Fn recvmmsg 149function implements this behaviour for each message in the vector. 150.Pp 151The 152.Xr select 2 153system call may be used to determine when more data arrives. 154.Pp 155The 156.Fa flags 157argument to a 158.Fn recv 159function is formed by 160.Em or Ap ing 161one or more of the values: 162.Bl -column ".Dv MSG_CMSG_CLOEXEC" -offset indent 163.It Dv MSG_OOB Ta process out-of-band data 164.It Dv MSG_PEEK Ta peek at incoming message 165.It Dv MSG_TRUNC Ta return real packet or datagram length 166.It Dv MSG_WAITALL Ta wait for full request or error 167.It Dv MSG_DONTWAIT Ta do not block 168.It Dv MSG_CMSG_CLOEXEC Ta set received fds close-on-exec 169.It Dv MSG_WAITFORONE Ta do not block after receiving the first message 170(only for 171.Fn recvmmsg 172) 173.El 174.Pp 175The 176.Dv MSG_OOB 177flag requests receipt of out-of-band data 178that would not be received in the normal data stream. 179Some protocols place expedited data at the head of the normal 180data queue, and thus this flag cannot be used with such protocols. 181The 182.Dv MSG_PEEK 183flag causes the receive operation to return data 184from the beginning of the receive queue without removing that 185data from the queue. 186Thus, a subsequent receive call will return the same data. 187The 188.Dv MSG_TRUNC 189flag causes the receive operation to return the full length of the packet 190or datagram even if larger than provided buffer. The flag is supported 191on SOCK_DGRAM sockets for 192.Dv AF_INET 193, 194.Dv AF_INET6 195and 196.Dv AF_UNIX 197families. 198The 199.Dv MSG_WAITALL 200flag requests that the operation block until 201the full request is satisfied. 202However, the call may still return less data than requested 203if a signal is caught, an error or disconnect occurs, 204or the next data to be received is of a different type than that returned. 205The 206.Dv MSG_DONTWAIT 207flag requests the call to return when it would block otherwise. 208If no data is available, 209.Va errno 210is set to 211.Er EAGAIN . 212This flag is not available in 213.St -ansiC 214or 215.St -isoC-99 216compilation mode. 217The 218.Dv MSG_WAITFORONE 219flag sets MSG_DONTWAIT after the first message has been received. 220This flag is only relevant for 221.Fn recvmmsg . 222.Pp 223The 224.Fn recvmsg 225system call uses a 226.Fa msghdr 227structure to minimize the number of directly supplied arguments. 228This structure has the following form, as defined in 229.In sys/socket.h : 230.Bd -literal 231struct msghdr { 232 void *msg_name; /* optional address */ 233 socklen_t msg_namelen; /* size of address */ 234 struct iovec *msg_iov; /* scatter/gather array */ 235 int msg_iovlen; /* # elements in msg_iov */ 236 void *msg_control; /* ancillary data, see below */ 237 socklen_t msg_controllen;/* ancillary data buffer len */ 238 int msg_flags; /* flags on received message */ 239}; 240.Ed 241.Pp 242Here 243.Fa msg_name 244and 245.Fa msg_namelen 246specify the source address if the socket is unconnected; 247.Fa msg_name 248may be given as a null pointer if no names are desired or required. 249The 250.Fa msg_iov 251and 252.Fa msg_iovlen 253arguments 254describe scatter gather locations, as discussed in 255.Xr read 2 . 256The 257.Fa msg_control 258argument, 259which has length 260.Fa msg_controllen , 261points to a buffer for other protocol control related messages 262or other miscellaneous ancillary data. 263The messages are of the form: 264.Bd -literal 265struct cmsghdr { 266 socklen_t cmsg_len; /* data byte count, including hdr */ 267 int cmsg_level; /* originating protocol */ 268 int cmsg_type; /* protocol-specific type */ 269/* followed by 270 u_char cmsg_data[]; */ 271}; 272.Ed 273.Pp 274As an example, the SO_TIMESTAMP socket option returns a reception 275timestamp for UDP packets. 276.Pp 277With 278.Dv AF_UNIX 279domain sockets, ancillary data can be used to pass file descriptors and 280process credentials. 281See 282.Xr unix 4 283for details. 284.Pp 285The 286.Fa msg_flags 287field is set on return according to the message received. 288.Dv MSG_EOR 289indicates end-of-record; 290the data returned completed a record (generally used with sockets of type 291.Dv SOCK_SEQPACKET ) . 292.Dv MSG_TRUNC 293indicates that 294the trailing portion of a datagram was discarded because the datagram 295was larger than the buffer supplied. 296.Dv MSG_CTRUNC 297indicates that some 298control data were discarded due to lack of space in the buffer 299for ancillary data. 300.Dv MSG_OOB 301is returned to indicate that expedited or out-of-band data were received. 302.Pp 303The 304.Fn recvmmsg 305system call uses the 306.Fa mmsghdr 307structure, defined as follows in the 308.In sys/socket.h 309header: 310.Bd -literal 311struct mmsghdr { 312 struct msghdr msg_hdr; /* message header */ 313 ssize_t msg_len; /* message length */ 314}; 315.Ed 316.Pp 317On data reception the 318.Fa msg_len 319field is updated to the length of the received message. 320.Sh RETURN VALUES 321These calls except 322.Fn recvmmsg 323return the number of bytes received. 324.Fn recvmmsg 325returns the number of messages received. 326A value of -1 is returned if an error occurred. 327.Sh ERRORS 328The calls fail if: 329.Bl -tag -width Er 330.It Bq Er EBADF 331The argument 332.Fa s 333is an invalid descriptor. 334.It Bq Er ECONNRESET 335The remote socket end is forcibly closed. 336.It Bq Er ENOTCONN 337The socket is associated with a connection-oriented protocol 338and has not been connected (see 339.Xr connect 2 340and 341.Xr accept 2 ) . 342.It Bq Er ENOTSOCK 343The argument 344.Fa s 345does not refer to a socket. 346.It Bq Er EMFILE 347The 348.Fn recvmsg 349system call 350was used to receive rights (file descriptors) that were in flight on the 351connection. 352However, the receiving program did not have enough free file 353descriptor slots to accept them. 354In this case the descriptors are closed, with pending data either discarded 355in the case of the unreliable datagram protocol or preserved in the case of a 356reliable protocol. 357The pending data can be retrieved with another call to 358.Fn recvmsg . 359.It Bq Er EMSGSIZE 360The 361.Fa msg_iovlen 362member of the 363.Fa msghdr 364structure pointed to by 365.Fa msg 366is less than or equal to 0, or is greater than 367.Va IOV_MAX . 368.It Bq Er EAGAIN 369The socket is marked non-blocking and the receive operation 370would block, or 371a receive timeout had been set 372and the timeout expired before data were received. 373.It Bq Er EINTR 374The receive was interrupted by delivery of a signal before 375any data were available. 376.It Bq Er EFAULT 377The receive buffer pointer(s) point outside the process's 378address space. 379.El 380.Sh SEE ALSO 381.Xr fcntl 2 , 382.Xr getsockopt 2 , 383.Xr read 2 , 384.Xr select 2 , 385.Xr socket 2 , 386.Xr CMSG_DATA 3 , 387.Xr unix 4 388.Sh HISTORY 389The 390.Fn recv 391function appeared in 392.Bx 4.2 . 393The 394.Fn recvmmsg 395function appeared in 396.Fx 11.0 . 397