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