1.\" $NetBSD: recv.2,v 1.38 2018/03/19 16:26:26 roy 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 March 19, 2018 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 can 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.Bd -literal 80struct mmsghdr { 81 struct msghdr msg_hdr; /* the message to be sent */ 82 unsigned int msg_len; /* number of bytes received */ 83}; 84.Ed 85.Pp 86The 87.Fa msg_len 88member contains the number of bytes received for each 89.Fa msg_hdr 90member. 91The array has 92.Fa vlen 93elements, which is limited to 94.Dv 1024 . 95If there is an error, a number fewer than 96.Fa vlen 97may be returned, and the error may be retrieved using 98.Xr getsockopt 2 99with 100.Dv SO_ERROR . 101If the flag 102.Dv MSG_WAITFORONE 103is set in 104.Fa flags 105then the 106.Fn recvmmsg 107call will wait for one message, and set 108.Dv MSG_DONTWAIT 109for the rest. 110If the 111.Fa timeout 112parameter is not 113.Dv NULL , 114then 115.Fn recvmmsg 116will return if that time is exceeded. 117.Pp 118The 119.Fn recv 120call is normally used only on a 121.Em connected 122socket (see 123.Xr connect 2 ) 124and is identical to 125.Fn recvfrom 126with a nil 127.Fa from 128parameter. 129As it is redundant, it may not be supported in future releases. 130.Pp 131.Fn recv , 132.Fn recvfrom 133and 134.Fn recvmsg 135routines return the length of the message on successful 136completion. 137.Fn recvmmsg 138returns the number of messages received. 139If a message is too long to fit in the supplied buffer, 140excess bytes may be discarded depending on the type of socket 141the message is received from (see 142.Xr socket 2 ) . 143.Pp 144If no messages are available at the socket, the 145receive call waits for a message to arrive, unless 146the socket is nonblocking (see 147.Xr fcntl 2 ) 148in which case the value 149\-1 is returned and the external variable 150.Va errno 151set to 152.Er EAGAIN . 153If no data is available and the remote peer was shut down, 1540 is returned. 155The receive calls normally return any data available, 156up to the requested amount, 157rather than waiting for receipt of the full amount requested; 158this behavior is affected by the socket-level options 159.Dv SO_RCVLOWAT 160and 161.Dv SO_RCVTIMEO 162described in 163.Xr getsockopt 2 . 164.Pp 165The 166.Xr select 2 167or 168.Xr poll 2 169call may be used to determine when more data arrives. 170.Pp 171The 172.Fa flags 173argument to a recv call is formed by 174.Em or Ap ing 175one or more of the values: 176.Bl -column MSG_CMSG_CLOEXEC -offset indent 177.It Dv MSG_CMSG_CLOEXEC Ta set the close on exec property for passed file descriptors 178.It Dv MSG_OOB Ta process out-of-band data 179.It Dv MSG_PEEK Ta peek at incoming message 180.It Dv MSG_WAITALL Ta wait for full request or error 181.El 182The 183.Dv MSG_OOB 184flag requests receipt of out-of-band data 185that would not be received in the normal data stream. 186Some protocols place expedited data at the head of the normal 187data queue, and thus this flag cannot be used with such protocols. 188The 189.Dv MSG_PEEK 190flag causes the receive operation to return data 191from the beginning of the receive queue without removing that 192data from the queue. 193Thus, a subsequent receive call will return the same data. 194The 195.Dv MSG_WAITALL 196flag requests that the operation block until 197the full request is satisfied. 198However, the call may still return less data than requested 199if a signal is caught, an error or disconnect occurs, 200or the next data to be received is of a different type than that returned. 201.Pp 202The 203.Fn recvmsg 204call uses a 205.Fa msghdr 206structure to minimize the number of directly supplied parameters. 207This structure has the following form, as defined in 208.Ao Pa sys/socket.h Ac : 209.Bd -literal 210struct msghdr { 211 void *msg_name; /* optional address */ 212 socklen_t msg_namelen; /* size of address */ 213 struct iovec *msg_iov; /* scatter/gather array */ 214 int msg_iovlen; /* # elements in msg_iov */ 215 void *msg_control; /* ancillary data, see below */ 216 socklen_t msg_controllen; /* ancillary data buffer len */ 217 int msg_flags; /* flags on received message */ 218}; 219.Ed 220.Pp 221Here 222.Fa msg_name 223and 224.Fa msg_namelen 225specify the source address if the socket is unconnected; 226.Fa msg_name 227may be given as a null pointer if no names are desired or required. 228If the socket is connected, 229.Fa msg_name 230and 231.Fa msg_namelen 232are ignored. 233.Fa msg_iov 234and 235.Fa msg_iovlen 236describe scatter gather locations, as discussed in 237.Xr read 2 . 238.Fa msg_control , 239which has length 240.Fa msg_controllen , 241points to a buffer for other protocol control related messages 242or other miscellaneous ancillary data. 243The messages are of the form: 244.Bd -literal 245struct cmsghdr { 246 socklen_t cmsg_len; /* data byte count, including hdr */ 247 int cmsg_level; /* originating protocol */ 248 int cmsg_type; /* protocol-specific type */ 249/* followed by 250 u_char cmsg_data[]; */ 251}; 252.Ed 253As an example, one could use this to learn of changes in the data-stream 254in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting 255a recvmsg with no data buffer provided immediately after an 256.Fn accept 257call. 258.Pp 259Open file descriptors are now passed as ancillary data for 260.Dv AF_LOCAL 261domain sockets, with 262.Fa cmsg_level 263set to 264.Dv SOL_SOCKET 265and 266.Fa cmsg_type 267set to 268.Dv SCM_RIGHTS . 269.Pp 270The 271.Fa msg_flags 272field is set on return according to the message received. 273.Dv MSG_EOR 274indicates end-of-record; 275the data returned completed a record (generally used with sockets of type 276.Dv SOCK_SEQPACKET ) . 277.Dv MSG_TRUNC 278indicates that 279the trailing portion of a datagram was discarded because the datagram 280was larger than the buffer supplied. 281.Dv MSG_CTRUNC 282indicates that some 283control data were discarded due to lack of space in the buffer 284for ancillary data. 285.Dv MSG_OOB 286is returned to indicate that expedited or out-of-band data were received. 287.Sh RETURN VALUES 288The 289.Fn recv , 290.Fn recvfrom 291and 292.Fn recvmsg 293calls return the number of bytes received, or \-1 294if an error occurred. 295For connected sockets whose remote peer was shut down, 2960 is returned when no more data is available. 297The 298.Fn recvmmsg 299call returns the number of messages received, or \-1 300if an error occurred. 301.Sh ERRORS 302The calls fail if: 303.Bl -tag -width Er 304.It Bq Er EAGAIN 305The socket is marked non-blocking, and the receive operation 306would block, or 307a receive timeout had been set, 308and the timeout expired before data were received. 309.It Bq Er EBADF 310The argument 311.Fa s 312is an invalid descriptor. 313.It Bq Er EFAULT 314The receive buffer pointer(s) point outside the process's 315address space. 316.It Bq Er EINTR 317The receive was interrupted by delivery of a signal before 318any data were available. 319.It Bq Er EINVAL 320The total length of the I/O is more than can be expressed by the ssize_t 321return value. 322.It Bq Er ENOBUFS 323A message was not delivered because it would have overflowed the buffer. 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