1.\" $OpenBSD: recv.2,v 1.24 2000/10/18 05:12:11 aaron 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. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)recv.2 8.3 (Berkeley) 2/21/94 36.\" 37.Dd February 15, 1999 38.Dt RECV 2 39.Os 40.Sh NAME 41.Nm recv , 42.Nm recvfrom , 43.Nm recvmsg 44.Nd receive a message from a socket 45.Sh SYNOPSIS 46.Fd #include <sys/types.h> 47.Fd #include <sys/socket.h> 48.Ft ssize_t 49.Fn recv "int s" "void *buf" "size_t len" "int flags" 50.Ft ssize_t 51.Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr *from" "socklen_t *fromlen" 52.Ft ssize_t 53.Fn recvmsg "int s" "struct msghdr *msg" "int flags" 54.Sh DESCRIPTION 55.Fn recvfrom 56and 57.Fn recvmsg 58are used to receive messages from a socket, and may be used to receive 59data on a socket whether or not it is connection-oriented. 60.Pp 61If 62.Fa from 63is non-null and the socket is not connection-oriented, 64the source address of the message is filled in. 65.Fa fromlen 66is a value-result parameter, initialized to the size of 67the buffer associated with 68.Fa from , 69and modified on return to indicate the actual size of the 70address stored there. 71.Pp 72The 73.Fn recv 74call is normally used only on a 75.Em connected 76socket (see 77.Xr connect 2 ) 78and is identical to 79.Fn recvfrom 80with a null 81.Fa from 82parameter. 83As it is redundant, it may not be supported in future releases. 84.Pp 85On successful completion, all three routines return the number of 86message bytes read. 87If a message is too long to fit in the supplied 88buffer, excess bytes may be discarded depending on the type of socket 89the message is received from (see 90.Xr socket 2 ) . 91.Pp 92If no messages are available at the socket, the 93receive call waits for a message to arrive, unless 94the socket is nonblocking (see 95.Xr fcntl 2 ) 96in which case the value 97\-1 is returned and the external variable 98.Va errno 99set to 100.Er EAGAIN . 101The receive calls normally return any data available, 102up to the requested amount, 103rather than waiting for receipt of the full amount requested; 104this behavior is affected by the socket-level options 105.Dv SO_RCVLOWAT 106and 107.Dv SO_RCVTIMEO 108described in 109.Xr getsockopt 2 . 110.Pp 111The 112.Xr select 2 113or 114.Xr poll 2 115system calls may be used to determine when more data arrive. 116.Pp 117The 118.Fa flags 119argument to a recv call is formed by 120.Tn OR Ns ing 121one or more of the values: 122.Bl -column MSG_WAITALL -offset indent 123.It Dv MSG_OOB Ta process out-of-band data 124.It Dv MSG_PEEK Ta peek at incoming message 125.It Dv MSG_WAITALL Ta wait for full request or error 126.El 127.Pp 128The 129.Dv MSG_OOB 130flag requests receipt of out-of-band data 131that would not be received in the normal data stream. 132Some protocols place expedited data at the head of the normal 133data queue, and thus this flag cannot be used with such protocols. 134The 135.Dv MSG_PEEK 136flag causes the receive operation to return data 137from the beginning of the receive queue without removing that 138data from the queue. 139Thus, a subsequent receive call will return the same data. 140The 141.Dv MSG_WAITALL 142flag requests that the operation block until 143the full request is satisfied. 144However, the call may still return less data than requested 145if a signal is caught, an error or disconnect occurs, 146or the next data to be received is of a different type than that returned. 147.Pp 148The 149.Fn recvmsg 150call uses a 151.Fa msghdr 152structure to minimize the number of directly supplied parameters. 153This structure has the following form, as defined in 154.Ao Pa sys/socket.h Ac : 155.Pp 156.Bd -literal 157struct msghdr { 158 caddr_t msg_name; /* optional address */ 159 socklen_t msg_namelen; /* size of address */ 160 struct iovec *msg_iov; /* scatter/gather array */ 161 u_int msg_iovlen; /* # elements in msg_iov */ 162 caddr_t msg_control; /* ancillary data, see below */ 163 socklen_t msg_controllen; /* ancillary data buffer len */ 164 int msg_flags; /* flags on received message */ 165}; 166.Ed 167.Pp 168Here 169.Fa msg_name 170and 171.Fa msg_namelen 172specify the source address if the socket is unconnected; 173.Fa msg_name 174may be given as a null pointer if no names are desired or required. 175.Fa msg_iov 176and 177.Fa msg_iovlen 178describe scatter gather locations, as discussed in 179.Xr read 2 . 180.Fa msg_control , 181which has length 182.Fa msg_controllen , 183points to a buffer for other protocol control related messages 184or other miscellaneous ancillary data. 185The messages are of the form: 186.Bd -literal 187struct cmsghdr { 188 socklen_t cmsg_len; /* data byte count, including hdr */ 189 int cmsg_level; /* originating protocol */ 190 int cmsg_type; /* protocol-specific type */ 191/* followed by u_char cmsg_data[]; */ 192}; 193.Ed 194.Pp 195As an example, one could use this to learn of changes in the data-stream 196in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting 197a recvmsg with no data buffer provided immediately after an 198.Fn accept 199call. 200.Pp 201Open file descriptors are now passed as ancillary data for 202.Dv AF_UNIX 203domain sockets, with 204.Fa cmsg_level 205set to 206.Dv SOL_SOCKET 207and 208.Fa cmsg_type 209set to 210.Dv SCM_RIGHTS . 211.Pp 212The 213.Fa msg_flags 214field is set on return according to the message received. 215It will contain zero or more of the following values: 216.Bl -column MSG_CTRUNC -offset indent 217.It Dv MSG_EOR Ta 218Indicates end-of-record; 219the data returned completed a record (generally used with sockets of type 220.Dv SOCK_SEQPACKET ) . 221.It Dv MSG_TRUNC Ta 222Indicates that 223the trailing portion of a datagram was discarded because the datagram 224was larger than the buffer supplied. 225.It Dv MSG_CTRUNC Ta 226Indicates that some 227control data were discarded due to lack of space in the buffer 228for ancillary data. 229.It Dv MSG_OOB Ta 230Returned to indicate that expedited or out-of-band data was received. 231.It Dv MSG_BCAST Ta 232Indicates that the packet was received as broadcast. 233.It Dv MSG_MCAST Ta 234Indicates that the packet was received as multicast. 235.El 236.Sh RETURN VALUES 237These calls return the number of bytes received, or \-1 if an error occurred. 238.Sh ERRORS 239.Fn recv , 240.Fn recvfrom , 241and 242.Fn recvmsg 243fail if: 244.Bl -tag -width Er 245.It Bq Er EBADF 246The argument 247.Fa s 248is an invalid descriptor. 249.It Bq Er ENOTCONN 250The socket is associated with a connection-oriented protocol 251and has not been connected (see 252.Xr connect 2 253and 254.Xr accept 2 ) . 255.It Bq Er ENOTSOCK 256The argument 257.Fa s 258does not refer to a socket. 259.It Bq Er EAGAIN 260The socket is marked non-blocking, and the receive operation 261would block, or 262a receive timeout had been set, 263and the timeout expired before data were received. 264.It Bq Er EINTR 265The receive was interrupted by delivery of a signal before 266any data were available. 267.It Bq Er EFAULT 268The receive buffer pointer(s) point outside the process's 269address space. 270.El 271.Pp 272In addition, 273.Fn recv 274and 275.Fn recvfrom 276may return the following error: 277.Bl -tag -width Er 278.It Bq Er EINVAL 279.Fa len 280was larger than 281.Dv SSIZE_MAX . 282.El 283.Pp 284Also, 285.Fn recvmsg 286may return one of the following errors: 287.Bl -tag -width Er 288.It Bq Er EINVAL 289The sum of the 290.Fa iov_len 291values in the 292.Fa msg_iov 293array overflowed an 294.Em ssize_t . 295.It Bq Er EMSGSIZE 296The 297.Fa msg_iovlen 298member of 299.Fa msg 300was less than 0 or larger than 301.Dv IOV_MAX . 302.El 303.Sh SEE ALSO 304.Xr fcntl 2 , 305.Xr getsockopt 2 , 306.Xr poll 2 , 307.Xr read 2 , 308.Xr select 2 , 309.Xr poll 2 , 310.Xr socket 2 311.Sh HISTORY 312The 313.Fn recv 314function call appeared in 315.Bx 4.2 . 316