1.\" $OpenBSD: recv.2,v 1.47 2019/01/11 06:10:13 jsg 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: January 11 2019 $ 34.Dt RECV 2 35.Os 36.Sh NAME 37.Nm recv , 38.Nm recvfrom , 39.Nm recvmsg 40.Nd receive a message from a socket 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 *from" "socklen_t *fromlen" 47.Ft ssize_t 48.Fn recvmsg "int s" "struct msghdr *msg" "int flags" 49.Sh DESCRIPTION 50.Fn recvfrom 51and 52.Fn recvmsg 53are used to receive messages from a socket, 54.Fa s , 55and may be used to receive 56data on a socket whether or not it is connection-oriented. 57.Pp 58If 59.Fa from 60is non-null and the socket is not connection-oriented, 61the source address of the message is filled in. 62.Fa fromlen 63is a value-result parameter, initialized to the size of 64the buffer associated with 65.Fa from , 66and modified on return to indicate the actual size of the 67address stored there. 68.Pp 69The 70.Fn recv 71call is normally used only on a 72.Em connected 73socket (see 74.Xr connect 2 ) 75and is identical to 76.Fn recvfrom 77with a null 78.Fa from 79parameter. 80.Pp 81On successful completion, all three routines return the number of 82message bytes read. 83If a message is too long to fit in the supplied 84buffer, excess bytes may be discarded depending on the type of socket 85the message is received from (see 86.Xr socket 2 ) . 87.Pp 88If no messages are available at the socket, the 89receive call waits for a message to arrive, unless 90the socket is nonblocking (see 91.Xr fcntl 2 ) 92in which case the value 93\-1 is returned and the external variable 94.Va errno 95set to 96.Er EAGAIN . 97The receive calls normally return any data available, 98up to the requested amount, 99rather than waiting for receipt of the full amount requested; 100this behavior is affected by the socket-level options 101.Dv SO_RCVLOWAT 102and 103.Dv SO_RCVTIMEO 104described in 105.Xr getsockopt 2 . 106.Pp 107The 108.Xr select 2 109or 110.Xr poll 2 111system calls may be used to determine when more data arrive. 112.Pp 113The 114.Fa flags 115argument is the bitwise OR of zero or more of the following values: 116.Pp 117.Bl -tag -width "MSG_CMSG_CLOEXECXX" -offset indent -compact 118.It Dv MSG_OOB 119process out-of-band data 120.It Dv MSG_PEEK 121peek at incoming message 122.It Dv MSG_WAITALL 123wait for full request or error 124.It Dv MSG_DONTWAIT 125don't block 126.It Dv MSG_CMSG_CLOEXEC 127set the close-on-exec flag on received file descriptors 128.El 129.Pp 130The 131.Dv MSG_OOB 132flag requests receipt of out-of-band data 133that would not be received in the normal data stream. 134Some protocols place expedited data at the head of the normal 135data queue, and thus this flag cannot be used with such protocols. 136The 137.Dv MSG_PEEK 138flag causes the receive operation to return data 139from the beginning of the receive queue without removing that 140data from the queue. 141Thus, a subsequent receive call will return the same data. 142The 143.Dv MSG_WAITALL 144flag requests that the operation block until 145the full request is satisfied. 146However, the call may still return less data than requested 147if a signal is caught, an error or disconnect occurs, 148or the next data to be received is of a different type than that returned. 149The 150.Dv MSG_DONTWAIT 151flag requests the call to return when it would block otherwise. 152If no data is available, 153.Va errno 154is set to 155.Er EAGAIN . 156This flag is not available in strict ANSI or C99 compilation mode. 157The 158.Dv MSG_CMSG_CLOEXEC 159requests that any file descriptors received as ancillary data with 160.Fn recvmsg 161(see below) 162have their close-on-exec flag set. 163.Pp 164The 165.Fn recvmsg 166call uses a 167.Fa msghdr 168structure to minimize the number of directly supplied parameters. 169This structure has the following form, as defined in 170.In sys/socket.h : 171.Bd -literal 172struct msghdr { 173 void *msg_name; /* optional address */ 174 socklen_t msg_namelen; /* size of address */ 175 struct iovec *msg_iov; /* scatter/gather array */ 176 unsigned int msg_iovlen; /* # elements in msg_iov */ 177 void *msg_control; /* ancillary data, see below */ 178 socklen_t msg_controllen; /* ancillary data buffer len */ 179 int msg_flags; /* flags on received message */ 180}; 181.Ed 182.Pp 183Here 184.Fa msg_name 185and 186.Fa msg_namelen 187specify the source address if the socket is unconnected; 188.Fa msg_name 189may be given as a null pointer if no names are desired or required. 190.Fa msg_iov 191and 192.Fa msg_iovlen 193describe scatter gather locations, as discussed in 194.Xr read 2 . 195.Fa msg_control , 196which has length 197.Fa msg_controllen , 198points to a buffer for other protocol control related messages 199or other miscellaneous ancillary data. 200The messages are of the form: 201.Bd -literal 202struct cmsghdr { 203 socklen_t cmsg_len; /* data byte count, including hdr */ 204 int cmsg_level; /* originating protocol */ 205 int cmsg_type; /* protocol-specific type */ 206/* followed by u_char cmsg_data[]; */ 207}; 208.Ed 209.Pp 210See 211.Xr CMSG_DATA 3 212for how these messages are constructed and decomposed. 213.Pp 214Open file descriptors are now passed as ancillary data for 215.Dv AF_UNIX 216domain and 217.Xr socketpair 2 218sockets, with 219.Fa cmsg_level 220set to 221.Dv SOL_SOCKET 222and 223.Fa cmsg_type 224set to 225.Dv SCM_RIGHTS . 226.Pp 227The 228.Fa msg_flags 229field is set on return according to the message received. 230It will contain zero or more of the following values: 231.Pp 232.Bl -tag -width MSG_CTRUNC -offset indent -compact 233.It Dv MSG_OOB 234Returned to indicate that expedited or out-of-band data was received. 235.It Dv MSG_EOR 236Indicates end-of-record; 237the data returned completed a record (generally used with sockets of type 238.Dv SOCK_SEQPACKET ) . 239.It Dv MSG_TRUNC 240Indicates that 241the trailing portion of a datagram was discarded because the datagram 242was larger than the buffer supplied. 243.It Dv MSG_CTRUNC 244Indicates that some 245control data were discarded due to lack of space in the buffer 246for ancillary data. 247.It Dv MSG_BCAST 248Indicates that the packet was received as broadcast. 249.It Dv MSG_MCAST 250Indicates that the packet was received as multicast. 251.El 252.Sh RETURN VALUES 253These calls return the number of bytes received, or \-1 if an error occurred. 254.Sh ERRORS 255.Fn recv , 256.Fn recvfrom , 257and 258.Fn recvmsg 259fail if: 260.Bl -tag -width "[EHOSTUNREACH]" 261.It Bq Er EBADF 262The argument 263.Fa s 264is an invalid descriptor. 265.It Bq Er ENOTCONN 266The socket is associated with a connection-oriented protocol 267and has not been connected (see 268.Xr connect 2 269and 270.Xr accept 2 ) . 271.It Bq Er ENOTSOCK 272The argument 273.Fa s 274does not refer to a socket. 275.It Bq Er EAGAIN 276The socket is marked non-blocking, and the receive operation 277would block, or 278a receive timeout had been set, 279and the timeout expired before data were received. 280.It Bq Er EINTR 281The receive was interrupted by delivery of a signal before 282any data were available. 283.It Bq Er EFAULT 284The receive buffer pointer(s) point outside the process's 285address space. 286.It Bq Er EHOSTUNREACH 287A socket operation was attempted to an unreachable host. 288.It Bq Er EHOSTDOWN 289A socket operation failed 290because the destination host was down. 291.It Bq Er ENETDOWN 292A socket operation encountered a dead network. 293.It Bq Er ECONNREFUSED 294The socket is associated with a connection-oriented protocol 295and the connection was forcefully rejected (see 296.Xr connect 2 ) . 297.El 298.Pp 299In addition, 300.Fn recv 301and 302.Fn recvfrom 303may return the following error: 304.Bl -tag -width Er 305.It Bq Er EINVAL 306.Fa len 307was larger than 308.Dv SSIZE_MAX . 309.El 310.Pp 311And 312.Fn recvmsg 313may return one of the following errors: 314.Bl -tag -width Er 315.It Bq Er EINVAL 316The sum of the 317.Fa iov_len 318values in the 319.Fa msg_iov 320array overflowed an 321.Em ssize_t . 322.It Bq Er EMSGSIZE 323The 324.Fa msg_iovlen 325member of 326.Fa msg 327was less than 0 or larger than 328.Dv IOV_MAX . 329.It Bq Er EMSGSIZE 330The receiving program did not have sufficient 331free file descriptor slots. 332The descriptors are closed 333and any pending data can be returned 334by another call to 335.Fn recvmsg . 336.El 337.Sh SEE ALSO 338.Xr connect 2 , 339.Xr fcntl 2 , 340.Xr getsockopt 2 , 341.Xr poll 2 , 342.Xr read 2 , 343.Xr select 2 , 344.Xr socket 2 , 345.Xr socketpair 2 , 346.Xr CMSG_DATA 3 , 347.Xr sockatmark 3 348.Sh STANDARDS 349The 350.Fn recv , 351.Fn recvfrom , 352and 353.Fn recvmsg 354functions conform to 355.St -p1003.1-2008 . 356The 357.Dv MSG_DONTWAIT , 358.Dv MSG_BCAST , 359and 360.Dv MSG_MCAST 361flags are extensions to that specification. 362.Sh HISTORY 363The 364.Fn recv 365function call appeared in 366.Bx 4.1c . 367.Sh CAVEATS 368Calling 369.Fn recvmsg 370with a control message having no or an empty scatter/gather array 371exposes variations in implementations. 372To avoid these, always use an 373.Fa iovec 374with at least a one-byte buffer and set 375.Fa msg_iov 376and an 377.Fa msg_iovlen 378to use this vector. 379