1.\" $NetBSD: recv.2,v 1.40 2025/04/03 10:27:54 riastradh 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.In sys/socket.h : 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. 129.Pp 130.Fn recv , 131.Fn recvfrom 132and 133.Fn recvmsg 134routines return the length of the message on successful 135completion. 136.Fn recvmmsg 137returns the number of messages received. 138If a message is too long to fit in the supplied buffer, 139excess bytes may be discarded depending on the type of socket 140the message is received from (see 141.Xr socket 2 ) . 142.Pp 143If no messages are available at the socket, the 144receive call waits for a message to arrive, unless 145the socket is nonblocking (see 146.Xr fcntl 2 ) 147in which case the value 148\-1 is returned and the external variable 149.Va errno 150set to 151.Er EAGAIN . 152If no data is available and the remote peer was shut down, 1530 is returned. 154The receive calls normally return any data available, 155up to the requested amount, 156rather than waiting for receipt of the full amount requested; 157this behavior is affected by the socket-level options 158.Dv SO_RCVLOWAT 159and 160.Dv SO_RCVTIMEO 161described in 162.Xr getsockopt 2 . 163.Pp 164The 165.Xr select 2 166or 167.Xr poll 2 168call may be used to determine when more data arrives. 169.Pp 170The 171.Fa flags 172argument to a recv call is formed by 173.Em or Ap ing 174one or more of the values: 175.Bl -column ".Dv MSG_CMSG_CLOEXEC" -offset indent 176.It Dv MSG_CMSG_CLOEXEC Ta set the close on exec property for passed file descriptors 177.It Dv MSG_OOB Ta process out-of-band data 178.It Dv MSG_PEEK Ta peek at incoming message 179.It Dv MSG_WAITALL Ta wait for full request or error 180.El 181.Pp 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.In sys/socket.h : 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.Xr accept 2 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 321.Vt ssize_t 322return value. 323.It Bq Er ENOBUFS 324A message was not delivered because it would have overflowed the buffer. 325.It Bq Er ENOTCONN 326The socket is associated with a connection-oriented protocol 327and has not been connected (see 328.Xr connect 2 329and 330.Xr accept 2 ) . 331.It Bq Er ENOTSOCK 332The argument 333.Fa s 334does not refer to a socket. 335.El 336.Pp 337.Fn recvmsg 338will also fail if: 339.Bl -tag -width Er 340.It Bq Er EMSGSIZE 341The 342.Fa msg_iovlen 343member of the 344.Fa msg 345structure is less than or equal to 0, 346or is greater than 347.Brq Dv IOV_MAX . 348.El 349.Sh SEE ALSO 350.Xr fcntl 2 , 351.Xr getsockopt 2 , 352.Xr poll 2 , 353.Xr read 2 , 354.Xr select 2 , 355.Xr socket 2 356.Sh HISTORY 357The 358.Fn recv 359function call appeared in 360.Bx 4.2 . 361The 362.Fn recvmmsg 363function call appeared in 364.Tn Linux 2.6.32 365and 366.Nx 7.0 . 367