1.\" $OpenBSD: recv.2,v 1.37 2011/07/19 18:24:40 mikeb 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: July 19 2011 $ 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.Fd #include <sys/types.h> 43.Fd #include <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.Sh DESCRIPTION 51.Fn recvfrom 52and 53.Fn recvmsg 54are used to receive messages from a socket, 55.Fa s , 56and may be used to receive 57data on a socket whether or not it is connection-oriented. 58.Pp 59If 60.Fa from 61is non-null and the socket is not connection-oriented, 62the source address of the message is filled in. 63.Fa fromlen 64is a value-result parameter, initialized to the size of 65the buffer associated with 66.Fa from , 67and modified on return to indicate the actual size of the 68address stored there. 69.Pp 70The 71.Fn recv 72call is normally used only on a 73.Em connected 74socket (see 75.Xr connect 2 ) 76and is identical to 77.Fn recvfrom 78with a null 79.Fa from 80parameter. 81As it is redundant, it may not be supported in future releases. 82.Pp 83On successful completion, all three routines return the number of 84message bytes read. 85If a message is too long to fit in the supplied 86buffer, excess bytes may be discarded depending on the type of socket 87the message is received from (see 88.Xr socket 2 ) . 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 to a recv call is formed by 118.Tn OR Ns ing 119one or more of the values: 120.Pp 121.Bl -tag -width "MSG_DONTWAITXX" -offset indent -compact 122.It Dv MSG_OOB 123process out-of-band data 124.It Dv MSG_PEEK 125peek at incoming message 126.It Dv MSG_WAITALL 127wait for full request or error 128.It Dv MSG_DONTWAIT 129don't block 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. 159.Pp 160The 161.Fn recvmsg 162call uses a 163.Fa msghdr 164structure to minimize the number of directly supplied parameters. 165This structure has the following form, as defined in 166.Aq Pa sys/socket.h : 167.Bd -literal 168struct msghdr { 169 void *msg_name; /* optional address */ 170 socklen_t msg_namelen; /* size of address */ 171 struct iovec *msg_iov; /* scatter/gather array */ 172 unsigned int msg_iovlen; /* # elements in msg_iov */ 173 void *msg_control; /* ancillary data, see below */ 174 socklen_t msg_controllen; /* ancillary data buffer len */ 175 int msg_flags; /* flags on received message */ 176}; 177.Ed 178.Pp 179Here 180.Fa msg_name 181and 182.Fa msg_namelen 183specify the source address if the socket is unconnected; 184.Fa msg_name 185may be given as a null pointer if no names are desired or required. 186.Fa msg_iov 187and 188.Fa msg_iovlen 189describe scatter gather locations, as discussed in 190.Xr read 2 . 191.Fa msg_control , 192which has length 193.Fa msg_controllen , 194points to a buffer for other protocol control related messages 195or other miscellaneous ancillary data. 196The messages are of the form: 197.Bd -literal 198struct cmsghdr { 199 socklen_t cmsg_len; /* data byte count, including hdr */ 200 int cmsg_level; /* originating protocol */ 201 int cmsg_type; /* protocol-specific type */ 202/* followed by u_char cmsg_data[]; */ 203}; 204.Ed 205.Pp 206See 207.Xr CMSG_DATA 3 208for how these messages are constructed and decomposed. 209.Pp 210Open file descriptors are now passed as ancillary data for 211.Dv AF_UNIX 212domain and 213.Xr socketpair 2 214sockets, with 215.Fa cmsg_level 216set to 217.Dv SOL_SOCKET 218and 219.Fa cmsg_type 220set to 221.Dv SCM_RIGHTS . 222.Pp 223The 224.Fa msg_flags 225field is set on return according to the message received. 226It will contain zero or more of the following values: 227.Pp 228.Bl -tag -width MSG_CTRUNC -offset indent -compact 229.It Dv MSG_OOB 230Returned to indicate that expedited or out-of-band data was received. 231.It Dv MSG_EOR 232Indicates end-of-record; 233the data returned completed a record (generally used with sockets of type 234.Dv SOCK_SEQPACKET ) . 235.It Dv MSG_TRUNC 236Indicates that 237the trailing portion of a datagram was discarded because the datagram 238was larger than the buffer supplied. 239.It Dv MSG_CTRUNC 240Indicates that some 241control data were discarded due to lack of space in the buffer 242for ancillary data. 243.It Dv MSG_BCAST 244Indicates that the packet was received as broadcast. 245.It Dv MSG_MCAST 246Indicates that the packet was received as multicast. 247.El 248.Sh RETURN VALUES 249These calls return the number of bytes received, or \-1 if an error occurred. 250.Sh ERRORS 251.Fn recv , 252.Fn recvfrom , 253and 254.Fn recvmsg 255fail if: 256.Bl -tag -width "[EHOSTUNREACH]" 257.It Bq Er EBADF 258The argument 259.Fa s 260is an invalid descriptor. 261.It Bq Er ENOTCONN 262The socket is associated with a connection-oriented protocol 263and has not been connected (see 264.Xr connect 2 265and 266.Xr accept 2 ) . 267.It Bq Er ENOTSOCK 268The argument 269.Fa s 270does not refer to a socket. 271.It Bq Er EAGAIN 272The socket is marked non-blocking, and the receive operation 273would block, or 274a receive timeout had been set, 275and the timeout expired before data were received. 276.It Bq Er EINTR 277The receive was interrupted by delivery of a signal before 278any data were available. 279.It Bq Er EFAULT 280The receive buffer pointer(s) point outside the process's 281address space. 282.It Bq Er EHOSTUNREACH 283A socket operation was attempted to an unreachable host. 284.It Bq Er EHOSTDOWN 285A socket operation failed 286because the destination host was down. 287.It Bq Er ENETDOWN 288A socket operation encountered a dead network. 289.El 290.Pp 291In addition, 292.Fn recv 293and 294.Fn recvfrom 295may return the following error: 296.Bl -tag -width Er 297.It Bq Er EINVAL 298.Fa len 299was larger than 300.Dv SSIZE_MAX . 301.El 302.Pp 303Also, 304.Fn recv 305may return the following error: 306.Bl -tag -width "[ECONNREFUSED]" 307.It Bq Er ECONNREFUSED 308The socket is associated with a connection-oriented protocol 309and the connection was forcefully rejected (see 310.Xr connect 2 ) . 311.El 312.Pp 313And 314.Fn recvmsg 315may return one of the following errors: 316.Bl -tag -width Er 317.It Bq Er EINVAL 318The sum of the 319.Fa iov_len 320values in the 321.Fa msg_iov 322array overflowed an 323.Em ssize_t . 324.It Bq Er EMSGSIZE 325The 326.Fa msg_iovlen 327member of 328.Fa msg 329was less than 0 or larger than 330.Dv IOV_MAX . 331.It Bq Er EMSGSIZE 332The receiving program did not have sufficient 333free file descriptor slots. 334The descriptors are closed 335and any pending data can be returned 336by another call to 337.Fn recvmsg . 338.El 339.Sh SEE ALSO 340.Xr connect 2 , 341.Xr fcntl 2 , 342.Xr getsockopt 2 , 343.Xr poll 2 , 344.Xr read 2 , 345.Xr select 2 , 346.Xr socket 2 , 347.Xr socketpair 2 , 348.Xr CMSG_DATA 3 349.Sh HISTORY 350The 351.Fn recv 352function call appeared in 353.Bx 4.2 . 354