1.\" $OpenBSD: recv.2,v 1.36 2008/07/29 20:15:53 gilles 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 29 2008 $ 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 210As an example, one could use this to learn of changes in the data-stream 211in XNS/SPP. 212.Pp 213Open file descriptors are now passed as ancillary data for 214.Dv AF_UNIX 215domain and 216.Xr socketpair 2 217sockets, with 218.Fa cmsg_level 219set to 220.Dv SOL_SOCKET 221and 222.Fa cmsg_type 223set to 224.Dv SCM_RIGHTS . 225.Pp 226The 227.Fa msg_flags 228field is set on return according to the message received. 229It will contain zero or more of the following values: 230.Pp 231.Bl -tag -width MSG_CTRUNC -offset indent -compact 232.It Dv MSG_OOB 233Returned to indicate that expedited or out-of-band data was received. 234.It Dv MSG_EOR 235Indicates end-of-record; 236the data returned completed a record (generally used with sockets of type 237.Dv SOCK_SEQPACKET ) . 238.It Dv MSG_TRUNC 239Indicates that 240the trailing portion of a datagram was discarded because the datagram 241was larger than the buffer supplied. 242.It Dv MSG_CTRUNC 243Indicates that some 244control data were discarded due to lack of space in the buffer 245for ancillary data. 246.It Dv MSG_BCAST 247Indicates that the packet was received as broadcast. 248.It Dv MSG_MCAST 249Indicates that the packet was received as multicast. 250.El 251.Sh RETURN VALUES 252These calls return the number of bytes received, or \-1 if an error occurred. 253.Sh ERRORS 254.Fn recv , 255.Fn recvfrom , 256and 257.Fn recvmsg 258fail if: 259.Bl -tag -width "[EHOSTUNREACH]" 260.It Bq Er EBADF 261The argument 262.Fa s 263is an invalid descriptor. 264.It Bq Er ENOTCONN 265The socket is associated with a connection-oriented protocol 266and has not been connected (see 267.Xr connect 2 268and 269.Xr accept 2 ) . 270.It Bq Er ENOTSOCK 271The argument 272.Fa s 273does not refer to a socket. 274.It Bq Er EAGAIN 275The socket is marked non-blocking, and the receive operation 276would block, or 277a receive timeout had been set, 278and the timeout expired before data were received. 279.It Bq Er EINTR 280The receive was interrupted by delivery of a signal before 281any data were available. 282.It Bq Er EFAULT 283The receive buffer pointer(s) point outside the process's 284address space. 285.It Bq Er EHOSTUNREACH 286A socket operation was attempted to an unreachable host. 287.It Bq Er EHOSTDOWN 288A socket operation failed 289because the destination host was down. 290.It Bq Er ENETDOWN 291A socket operation encountered a dead network. 292.El 293.Pp 294In addition, 295.Fn recv 296and 297.Fn recvfrom 298may return the following error: 299.Bl -tag -width Er 300.It Bq Er EINVAL 301.Fa len 302was larger than 303.Dv SSIZE_MAX . 304.El 305.Pp 306Also, 307.Fn recv 308may return the following error: 309.Bl -tag -width "[ECONNREFUSED]" 310.It Bq Er ECONNREFUSED 311The socket is associated with a connection-oriented protocol 312and the connection was forcefully rejected (see 313.Xr connect 2 ) . 314.El 315.Pp 316And 317.Fn recvmsg 318may return one of the following errors: 319.Bl -tag -width Er 320.It Bq Er EINVAL 321The sum of the 322.Fa iov_len 323values in the 324.Fa msg_iov 325array overflowed an 326.Em ssize_t . 327.It Bq Er EMSGSIZE 328The 329.Fa msg_iovlen 330member of 331.Fa msg 332was less than 0 or larger than 333.Dv IOV_MAX . 334.It Bq Er EMSGSIZE 335The receiving program did not have sufficient 336free file descriptor slots. 337The descriptors are closed 338and any pending data can be returned 339by another call to 340.Fn recvmsg . 341.El 342.Sh SEE ALSO 343.Xr connect 2 , 344.Xr fcntl 2 , 345.Xr getsockopt 2 , 346.Xr poll 2 , 347.Xr read 2 , 348.Xr select 2 , 349.Xr socket 2 , 350.Xr socketpair 2 , 351.Xr CMSG_DATA 3 352.Sh HISTORY 353The 354.Fn recv 355function call appeared in 356.Bx 4.2 . 357