1.\" $NetBSD: recv.2,v 1.36 2013/07/14 14:29:09 njoly Exp $ 2.\" 3.\" Copyright (c) 1983, 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)recv.2 8.3 (Berkeley) 2/21/94 31.\" 32.Dd June 22, 2012 33.Dt RECV 2 34.Os 35.Sh NAME 36.Nm recv , 37.Nm recvfrom , 38.Nm recvmsg , 39.Nm recvmmsg 40.Nd receive a message from a socket 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In sys/socket.h 45.Ft ssize_t 46.Fn recv "int s" "void *buf" "size_t len" "int flags" 47.Ft ssize_t 48.Fn recvfrom "int s" "void * restrict buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen" 49.Ft ssize_t 50.Fn recvmsg "int s" "struct msghdr *msg" "int flags" 51.Ft int 52.Fn recvmmsg "int s" "struct mmsghdr *mmsg" "unsigned int vlen" "unsigned int flags" "struct timespec *timeout" 53.Sh DESCRIPTION 54.Fn recvfrom , 55.Fn recvmsg 56and 57.Fn recvmmsg 58are used to receive messages from a socket, 59and may be used to receive data on a socket whether or not 60it is connection-oriented. 61.Pp 62If 63.Fa from 64is non-nil, and the socket is not connection-oriented, 65the source address of the message is filled in. 66.Fa fromlen 67is a value-result parameter, initialized to the size of 68the buffer associated with 69.Fa from , 70and modified on return to indicate the actual size of the 71address stored there. 72.Pp 73The 74.Fn recvmmsg 75call be used to receive multiple messages in the same call using an array of 76.Fa mmsghdr 77elements with the following form, as defined in 78.Ao Pa sys/socket.h Ac : 79.Pp 80.Bd -literal 81struct mmsghdr { 82 struct msghdr msg_hdr; /* the message to be sent */ 83 unsigned int msg_len; /* number of bytes received */ 84}; 85.Ed 86.Pp 87The 88.Fa msg_len 89member contains the number of bytes received for each 90.Fa msg_hdr 91member. 92The array has 93.Fa vlen 94elements, which is limited to 95.Dv 1024 . 96If there is an error, a number fewer than 97.Fa vlen 98may be returned, and the error may be retrieved using 99.Xr getsockopt 2 100with 101.Dv SO_ERROR . 102If the flag 103.Dv MSG_WAITFORONE 104is set in 105.Fa flags 106then the 107.Fn recvmmsg 108call will wait for one message, and set 109.Dv MSG_DONTWAIT 110for the rest. 111If the 112.Fa timeout 113parameter is not 114.Dv NULL , 115then 116.Fn recvmmsg 117will return if that time is exceeded. 118.Pp 119The 120.Fn recv 121call is normally used only on a 122.Em connected 123socket (see 124.Xr connect 2 ) 125and is identical to 126.Fn recvfrom 127with a nil 128.Fa from 129parameter. 130As it is redundant, it may not be supported in future releases. 131.Pp 132.Fn recv , 133.Fn recvfrom 134and 135.Fn recvmsg 136routines return the length of the message on successful 137completion. 138.Fn recvmmsg 139returns the number of messages received. 140If a message is too long to fit in the supplied buffer, 141excess bytes may be discarded depending on the type of socket 142the message is received from (see 143.Xr socket 2 ) . 144.Pp 145If no messages are available at the socket, the 146receive call waits for a message to arrive, unless 147the socket is nonblocking (see 148.Xr fcntl 2 ) 149in which case the value 150\-1 is returned and the external variable 151.Va errno 152set to 153.Er EAGAIN . 154If no data is available and the remote peer was shut down, 1550 is returned. 156The receive calls normally return any data available, 157up to the requested amount, 158rather than waiting for receipt of the full amount requested; 159this behavior is affected by the socket-level options 160.Dv SO_RCVLOWAT 161and 162.Dv SO_RCVTIMEO 163described in 164.Xr getsockopt 2 . 165.Pp 166The 167.Xr select 2 168or 169.Xr poll 2 170call may be used to determine when more data arrive. 171.Pp 172The 173.Fa flags 174argument to a recv call is formed by 175.Em or Ap ing 176one or more of the values: 177.Bl -column MSG_CMSG_CLOEXEC -offset indent 178.It Dv MSG_CMSG_CLOEXEC Ta set the close on exec property for passed file descriptors 179.It Dv MSG_OOB Ta process out-of-band data 180.It Dv MSG_PEEK Ta peek at incoming message 181.It Dv MSG_WAITALL Ta wait for full request or error 182.El 183The 184.Dv MSG_OOB 185flag requests receipt of out-of-band data 186that would not be received in the normal data stream. 187Some protocols place expedited data at the head of the normal 188data queue, and thus this flag cannot be used with such protocols. 189The 190.Dv MSG_PEEK 191flag causes the receive operation to return data 192from the beginning of the receive queue without removing that 193data from the queue. 194Thus, a subsequent receive call will return the same data. 195The 196.Dv MSG_WAITALL 197flag requests that the operation block until 198the full request is satisfied. 199However, the call may still return less data than requested 200if a signal is caught, an error or disconnect occurs, 201or the next data to be received is of a different type than that returned. 202.Pp 203The 204.Fn recvmsg 205call uses a 206.Fa msghdr 207structure to minimize the number of directly supplied parameters. 208This structure has the following form, as defined in 209.Ao Pa sys/socket.h Ac : 210.Pp 211.Bd -literal 212struct msghdr { 213 void *msg_name; /* optional address */ 214 socklen_t msg_namelen; /* size of address */ 215 struct iovec *msg_iov; /* scatter/gather array */ 216 int msg_iovlen; /* # elements in msg_iov */ 217 void *msg_control; /* ancillary data, see below */ 218 socklen_t msg_controllen; /* ancillary data buffer len */ 219 int msg_flags; /* flags on received message */ 220}; 221.Ed 222.Pp 223Here 224.Fa msg_name 225and 226.Fa msg_namelen 227specify the source address if the socket is unconnected; 228.Fa msg_name 229may be given as a null pointer if no names are desired or required. 230If the socket is connected, 231.Fa msg_name 232and 233.Fa msg_namelen 234are ignored. 235.Fa msg_iov 236and 237.Fa msg_iovlen 238describe scatter gather locations, as discussed in 239.Xr read 2 . 240.Fa msg_control , 241which has length 242.Fa msg_controllen , 243points to a buffer for other protocol control related messages 244or other miscellaneous ancillary data. 245The messages are of the form: 246.Bd -literal 247struct cmsghdr { 248 socklen_t cmsg_len; /* data byte count, including hdr */ 249 int cmsg_level; /* originating protocol */ 250 int cmsg_type; /* protocol-specific type */ 251/* followed by 252 u_char cmsg_data[]; */ 253}; 254.Ed 255As an example, one could use this to learn of changes in the data-stream 256in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting 257a recvmsg with no data buffer provided immediately after an 258.Fn accept 259call. 260.Pp 261Open file descriptors are now passed as ancillary data for 262.Dv AF_LOCAL 263domain sockets, with 264.Fa cmsg_level 265set to 266.Dv SOL_SOCKET 267and 268.Fa cmsg_type 269set to 270.Dv SCM_RIGHTS . 271.Pp 272The 273.Fa msg_flags 274field is set on return according to the message received. 275.Dv MSG_EOR 276indicates end-of-record; 277the data returned completed a record (generally used with sockets of type 278.Dv SOCK_SEQPACKET ) . 279.Dv MSG_TRUNC 280indicates that 281the trailing portion of a datagram was discarded because the datagram 282was larger than the buffer supplied. 283.Dv MSG_CTRUNC 284indicates that some 285control data were discarded due to lack of space in the buffer 286for ancillary data. 287.Dv MSG_OOB 288is returned to indicate that expedited or out-of-band data were received. 289.Sh RETURN VALUES 290The 291.Fn recv , 292.Fn recvfrom 293and 294.Fn recvmsg 295calls return the number of bytes received, or \-1 296if an error occurred. 297For connected sockets whose remote peer was shut down, 2980 is returned when no more data is available. 299The 300.Fn recvmmsg 301calls return the number of messages received, or \-1 302if an error occurred. 303.Sh ERRORS 304The calls fail if: 305.Bl -tag -width Er 306.It Bq Er EAGAIN 307The socket is marked non-blocking, and the receive operation 308would block, or 309a receive timeout had been set, 310and the timeout expired before data were received. 311.It Bq Er EBADF 312The argument 313.Fa s 314is an invalid descriptor. 315.It Bq Er EFAULT 316The receive buffer pointer(s) point outside the process's 317address space. 318.It Bq Er EINTR 319The receive was interrupted by delivery of a signal before 320any data were available. 321.It Bq Er EINVAL 322The total length of the I/O is more than can be expressed by the ssize_t 323return value. 324.It Bq Er ENOTCONN 325The socket is associated with a connection-oriented protocol 326and has not been connected (see 327.Xr connect 2 328and 329.Xr accept 2 ) . 330.It Bq Er ENOTSOCK 331The argument 332.Fa s 333does not refer to a socket. 334.El 335.Pp 336.Fn recvmsg 337will also fail if: 338.Bl -tag -width Er 339.It Bq Er EMSGSIZE 340The 341.Fa msg_iovlen 342member of the 343.Fa msg 344structure is less than or equal to 0 345or is greater than 346.Brq Dv IOV_MAX . 347.El 348.Sh SEE ALSO 349.Xr fcntl 2 , 350.Xr getsockopt 2 , 351.Xr poll 2 , 352.Xr read 2 , 353.Xr select 2 , 354.Xr socket 2 355.Sh HISTORY 356The 357.Fn recv 358function call appeared in 359.Bx 4.2 . 360The 361.Fn recvmmsg 362function call appeared in 363.Tn Linux 2.6.32 364and 365.Nx 7.0 . 366