1.\" $OpenBSD: recv.2,v 1.40 2014/02/13 07:30:39 guenther 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: February 13 2014 $ 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 is the bitwise OR of zero or more of the following values: 118.Pp 119.Bl -tag -width "MSG_DONTWAITXX" -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.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. 157.Pp 158The 159.Fn recvmsg 160call uses a 161.Fa msghdr 162structure to minimize the number of directly supplied parameters. 163This structure has the following form, as defined in 164.In sys/socket.h : 165.Bd -literal 166struct msghdr { 167 void *msg_name; /* optional address */ 168 socklen_t msg_namelen; /* size of address */ 169 struct iovec *msg_iov; /* scatter/gather array */ 170 unsigned int msg_iovlen; /* # elements in msg_iov */ 171 void *msg_control; /* ancillary data, see below */ 172 socklen_t msg_controllen; /* ancillary data buffer len */ 173 int msg_flags; /* flags on received message */ 174}; 175.Ed 176.Pp 177Here 178.Fa msg_name 179and 180.Fa msg_namelen 181specify the source address if the socket is unconnected; 182.Fa msg_name 183may be given as a null pointer if no names are desired or required. 184.Fa msg_iov 185and 186.Fa msg_iovlen 187describe scatter gather locations, as discussed in 188.Xr read 2 . 189.Fa msg_control , 190which has length 191.Fa msg_controllen , 192points to a buffer for other protocol control related messages 193or other miscellaneous ancillary data. 194The messages are of the form: 195.Bd -literal 196struct cmsghdr { 197 socklen_t cmsg_len; /* data byte count, including hdr */ 198 int cmsg_level; /* originating protocol */ 199 int cmsg_type; /* protocol-specific type */ 200/* followed by u_char cmsg_data[]; */ 201}; 202.Ed 203.Pp 204See 205.Xr CMSG_DATA 3 206for how these messages are constructed and decomposed. 207.Pp 208Open file descriptors are now passed as ancillary data for 209.Dv AF_UNIX 210domain and 211.Xr socketpair 2 212sockets, with 213.Fa cmsg_level 214set to 215.Dv SOL_SOCKET 216and 217.Fa cmsg_type 218set to 219.Dv SCM_RIGHTS . 220.Pp 221The 222.Fa msg_flags 223field is set on return according to the message received. 224It will contain zero or more of the following values: 225.Pp 226.Bl -tag -width MSG_CTRUNC -offset indent -compact 227.It Dv MSG_OOB 228Returned to indicate that expedited or out-of-band data was received. 229.It Dv MSG_EOR 230Indicates end-of-record; 231the data returned completed a record (generally used with sockets of type 232.Dv SOCK_SEQPACKET ) . 233.It Dv MSG_TRUNC 234Indicates that 235the trailing portion of a datagram was discarded because the datagram 236was larger than the buffer supplied. 237.It Dv MSG_CTRUNC 238Indicates that some 239control data were discarded due to lack of space in the buffer 240for ancillary data. 241.It Dv MSG_BCAST 242Indicates that the packet was received as broadcast. 243.It Dv MSG_MCAST 244Indicates that the packet was received as multicast. 245.El 246.Sh RETURN VALUES 247These calls return the number of bytes received, or \-1 if an error occurred. 248.Sh ERRORS 249.Fn recv , 250.Fn recvfrom , 251and 252.Fn recvmsg 253fail if: 254.Bl -tag -width "[EHOSTUNREACH]" 255.It Bq Er EBADF 256The argument 257.Fa s 258is an invalid descriptor. 259.It Bq Er ENOTCONN 260The socket is associated with a connection-oriented protocol 261and has not been connected (see 262.Xr connect 2 263and 264.Xr accept 2 ) . 265.It Bq Er ENOTSOCK 266The argument 267.Fa s 268does not refer to a socket. 269.It Bq Er EAGAIN 270The socket is marked non-blocking, and the receive operation 271would block, or 272a receive timeout had been set, 273and the timeout expired before data were received. 274.It Bq Er EINTR 275The receive was interrupted by delivery of a signal before 276any data were available. 277.It Bq Er EFAULT 278The receive buffer pointer(s) point outside the process's 279address space. 280.It Bq Er EHOSTUNREACH 281A socket operation was attempted to an unreachable host. 282.It Bq Er EHOSTDOWN 283A socket operation failed 284because the destination host was down. 285.It Bq Er ENETDOWN 286A socket operation encountered a dead network. 287.El 288.Pp 289In addition, 290.Fn recv 291and 292.Fn recvfrom 293may return the following error: 294.Bl -tag -width Er 295.It Bq Er EINVAL 296.Fa len 297was larger than 298.Dv SSIZE_MAX . 299.El 300.Pp 301Also, 302.Fn recv 303may return the following error: 304.Bl -tag -width "[ECONNREFUSED]" 305.It Bq Er ECONNREFUSED 306The socket is associated with a connection-oriented protocol 307and the connection was forcefully rejected (see 308.Xr connect 2 ) . 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.Sh HISTORY 348The 349.Fn recv 350function call appeared in 351.Bx 4.2 . 352