1.\" $NetBSD: recv.2,v 1.39 2019/08/04 01:22:49 uwe 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. 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 ".Dv 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 182.Pp 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.In sys/socket.h : 210.Bd -literal 211struct msghdr { 212 void *msg_name; /* optional address */ 213 socklen_t msg_namelen; /* size of address */ 214 struct iovec *msg_iov; /* scatter/gather array */ 215 int msg_iovlen; /* # elements in msg_iov */ 216 void *msg_control; /* ancillary data, see below */ 217 socklen_t msg_controllen; /* ancillary data buffer len */ 218 int msg_flags; /* flags on received message */ 219}; 220.Ed 221.Pp 222Here 223.Fa msg_name 224and 225.Fa msg_namelen 226specify the source address if the socket is unconnected; 227.Fa msg_name 228may be given as a null pointer if no names are desired or required. 229If the socket is connected, 230.Fa msg_name 231and 232.Fa msg_namelen 233are ignored. 234.Fa msg_iov 235and 236.Fa msg_iovlen 237describe scatter gather locations, as discussed in 238.Xr read 2 . 239.Fa msg_control , 240which has length 241.Fa msg_controllen , 242points to a buffer for other protocol control related messages 243or other miscellaneous ancillary data. 244The messages are of the form: 245.Bd -literal 246struct cmsghdr { 247 socklen_t cmsg_len; /* data byte count, including hdr */ 248 int cmsg_level; /* originating protocol */ 249 int cmsg_type; /* protocol-specific type */ 250/* followed by 251 u_char cmsg_data[]; */ 252}; 253.Ed 254As an example, one could use this to learn of changes in the data-stream 255in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting 256a recvmsg with no data buffer provided immediately after an 257.Xr accept 2 258call. 259.Pp 260Open file descriptors are now passed as ancillary data for 261.Dv AF_LOCAL 262domain sockets, with 263.Fa cmsg_level 264set to 265.Dv SOL_SOCKET 266and 267.Fa cmsg_type 268set to 269.Dv SCM_RIGHTS . 270.Pp 271The 272.Fa msg_flags 273field is set on return according to the message received. 274.Dv MSG_EOR 275indicates end-of-record; 276the data returned completed a record (generally used with sockets of type 277.Dv SOCK_SEQPACKET ) . 278.Dv MSG_TRUNC 279indicates that 280the trailing portion of a datagram was discarded because the datagram 281was larger than the buffer supplied. 282.Dv MSG_CTRUNC 283indicates that some 284control data were discarded due to lack of space in the buffer 285for ancillary data. 286.Dv MSG_OOB 287is returned to indicate that expedited or out-of-band data were received. 288.Sh RETURN VALUES 289The 290.Fn recv , 291.Fn recvfrom 292and 293.Fn recvmsg 294calls return the number of bytes received, or \-1 295if an error occurred. 296For connected sockets whose remote peer was shut down, 2970 is returned when no more data is available. 298The 299.Fn recvmmsg 300call returns the number of messages received, or \-1 301if an error occurred. 302.Sh ERRORS 303The calls fail if: 304.Bl -tag -width Er 305.It Bq Er EAGAIN 306The socket is marked non-blocking, and the receive operation 307would block, or 308a receive timeout had been set, 309and the timeout expired before data were received. 310.It Bq Er EBADF 311The argument 312.Fa s 313is an invalid descriptor. 314.It Bq Er EFAULT 315The receive buffer pointer(s) point outside the process's 316address space. 317.It Bq Er EINTR 318The receive was interrupted by delivery of a signal before 319any data were available. 320.It Bq Er EINVAL 321The total length of the I/O is more than can be expressed by the 322.Vt ssize_t 323return value. 324.It Bq Er ENOBUFS 325A message was not delivered because it would have overflowed the buffer. 326.It Bq Er ENOTCONN 327The socket is associated with a connection-oriented protocol 328and has not been connected (see 329.Xr connect 2 330and 331.Xr accept 2 ) . 332.It Bq Er ENOTSOCK 333The argument 334.Fa s 335does not refer to a socket. 336.El 337.Pp 338.Fn recvmsg 339will also fail if: 340.Bl -tag -width Er 341.It Bq Er EMSGSIZE 342The 343.Fa msg_iovlen 344member of the 345.Fa msg 346structure is less than or equal to 0, 347or is greater than 348.Brq Dv IOV_MAX . 349.El 350.Sh SEE ALSO 351.Xr fcntl 2 , 352.Xr getsockopt 2 , 353.Xr poll 2 , 354.Xr read 2 , 355.Xr select 2 , 356.Xr socket 2 357.Sh HISTORY 358The 359.Fn recv 360function call appeared in 361.Bx 4.2 . 362The 363.Fn recvmmsg 364function call appeared in 365.Tn Linux 2.6.32 366and 367.Nx 7.0 . 368