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