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.\" 3. 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: src/lib/libc/sys/recv.2,v 1.8.2.8 2001/12/14 18:34:01 ru Exp $ 30.\" 31.Dd November 1, 2015 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 *from" "socklen_t *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 221Open file descriptors are now passed as ancillary data for 222.Dv AF_UNIX 223domain sockets, with 224.Fa cmsg_level 225set to 226.Dv SOL_SOCKET 227and 228.Fa cmsg_type 229set to 230.Dv SCM_RIGHTS . 231The close-on-exec flag on received descriptors is set according to the 232.Dv MSG_CMSG_CLOEXEC 233flag passed to 234.Fn recvmsg . 235.Pp 236Process credentials can also be passed as ancillary data for 237.Dv AF_UNIX 238domain sockets using a 239.Fa cmsg_type 240of 241.Dv SCM_CREDS . 242In this case, 243.Fa cmsg_data 244should be a structure of type 245.Fa cmsgcred , 246which is defined in 247.In sys/socket.h 248as follows: 249.Bd -literal 250struct cmsgcred { 251 pid_t cmcred_pid; /* PID of sending process */ 252 uid_t cmcred_uid; /* real UID of sending process */ 253 uid_t cmcred_euid; /* effective UID of sending process */ 254 gid_t cmcred_gid; /* real GID of sending process */ 255 short cmcred_ngroups; /* number or groups */ 256 gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ 257}; 258.Ed 259.Pp 260The kernel will fill in the credential information of the sending process 261and deliver it to the receiver. 262.Pp 263The 264.Fa msg_flags 265field is set on return according to the message received. 266.Dv MSG_EOR 267indicates end-of-record; 268the data returned completed a record (generally used with sockets of type 269.Dv SOCK_SEQPACKET ) . 270.Dv MSG_TRUNC 271indicates that 272the trailing portion of a datagram was discarded because the datagram 273was larger than the buffer supplied. 274.Dv MSG_CTRUNC 275indicates that some 276control data were discarded due to lack of space in the buffer 277for ancillary data. 278.Dv MSG_OOB 279is returned to indicate that expedited or out-of-band data were received. 280.Sh RETURN VALUES 281Upon successful completion the number of bytes which were received is 282returned. Otherwise -1 is returned and the global variable 283.Va errno 284is set to indicate the error. 285.Sh ERRORS 286The calls fail if: 287.Bl -tag -width Er 288.It Bq Er EBADF 289The argument 290.Fa s 291is an invalid descriptor. 292.It Bq Er ENOTCONN 293The socket is associated with a connection-oriented protocol 294and has not been connected (see 295.Xr connect 2 296and 297.Xr accept 2 ) . 298.It Bq Er ENOTSOCK 299The argument 300.Fa s 301does not refer to a socket. 302.It Bq Er EAGAIN 303The socket is marked non-blocking and the receive operation 304would block, or 305a receive timeout had been set 306and the timeout expired before data were received. 307.It Bq Er EINTR 308The receive was interrupted by delivery of a signal before 309any data were available. 310.It Bq Er EFAULT 311The receive buffer pointer(s) point outside the process's 312address space. 313.El 314.Sh SEE ALSO 315.Xr fcntl 2 , 316.Xr getsockopt 2 , 317.Xr read 2 , 318.Xr select 2 , 319.Xr socket 2 , 320.Xr unix 4 321.Sh HISTORY 322The 323.Fn recv 324function appeared in 325.Bx 4.2 . 326