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$ 30.\" 31.Dd December 28, 2006 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 * restrict 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_DONTWAIT" -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.El 130.Pp 131The 132.Dv MSG_OOB 133flag requests receipt of out-of-band data 134that would not be received in the normal data stream. 135Some protocols place expedited data at the head of the normal 136data queue, and thus this flag cannot be used with such protocols. 137The 138.Dv MSG_PEEK 139flag causes the receive operation to return data 140from the beginning of the receive queue without removing that 141data from the queue. 142Thus, a subsequent receive call will return the same data. 143The 144.Dv MSG_WAITALL 145flag requests that the operation block until 146the full request is satisfied. 147However, the call may still return less data than requested 148if a signal is caught, an error or disconnect occurs, 149or the next data to be received is of a different type than that returned. 150The 151.Dv MSG_DONTWAIT 152flag requests the call to return when it would block otherwise. 153If no data is available, 154.Va errno 155is set to 156.Er EAGAIN . 157This flag is not available in strict 158.Tn ANSI 159or C99 compilation mode. 160.Pp 161The 162.Fn recvmsg 163system call uses a 164.Fa msghdr 165structure to minimize the number of directly supplied arguments. 166This structure has the following form, as defined in 167.In sys/socket.h : 168.Bd -literal 169struct msghdr { 170 void *msg_name; /* optional address */ 171 socklen_t msg_namelen; /* size of address */ 172 struct iovec *msg_iov; /* scatter/gather array */ 173 int msg_iovlen; /* # elements in msg_iov */ 174 void *msg_control; /* ancillary data, see below */ 175 socklen_t msg_controllen;/* ancillary data buffer len */ 176 int msg_flags; /* flags on received message */ 177}; 178.Ed 179.Pp 180Here 181.Fa msg_name 182and 183.Fa msg_namelen 184specify the destination address if the socket is unconnected; 185.Fa msg_name 186may be given as a null pointer if no names are desired or required. 187The 188.Fa msg_iov 189and 190.Fa msg_iovlen 191arguments 192describe scatter gather locations, as discussed in 193.Xr read 2 . 194The 195.Fa msg_control 196argument, 197which has length 198.Fa msg_controllen , 199points to a buffer for other protocol control related messages 200or other miscellaneous ancillary data. 201The messages are of the form: 202.Bd -literal 203struct cmsghdr { 204 socklen_t cmsg_len; /* data byte count, including hdr */ 205 int cmsg_level; /* originating protocol */ 206 int cmsg_type; /* protocol-specific type */ 207/* followed by 208 u_char cmsg_data[]; */ 209}; 210.Ed 211.Pp 212As an example, one could use this to learn of changes in the data-stream 213in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting 214a 215.Fn recvmsg 216with no data buffer provided immediately after an 217.Fn accept 218system call. 219.Pp 220Open file descriptors are now passed as ancillary data for 221.Dv AF_UNIX 222domain sockets, with 223.Fa cmsg_level 224set to 225.Dv SOL_SOCKET 226and 227.Fa cmsg_type 228set to 229.Dv SCM_RIGHTS . 230.Pp 231Process credentials can also be passed as ancillary data for 232.Dv AF_UNIX 233domain sockets using a 234.Fa cmsg_type 235of 236.Dv SCM_CREDS . 237In this case, 238.Fa cmsg_data 239should be a structure of type 240.Fa cmsgcred , 241which is defined in 242.In sys/socket.h 243as follows: 244.Bd -literal 245struct cmsgcred { 246 pid_t cmcred_pid; /* PID of sending process */ 247 uid_t cmcred_uid; /* real UID of sending process */ 248 uid_t cmcred_euid; /* effective UID of sending process */ 249 gid_t cmcred_gid; /* real GID of sending process */ 250 short cmcred_ngroups; /* number or groups */ 251 gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ 252}; 253.Ed 254.Pp 255The kernel will fill in the credential information of the sending process 256and deliver it to the receiver. 257.Pp 258The 259.Fa msg_flags 260field is set on return according to the message received. 261.Dv MSG_EOR 262indicates end-of-record; 263the data returned completed a record (generally used with sockets of type 264.Dv SOCK_SEQPACKET ) . 265.Dv MSG_TRUNC 266indicates that 267the trailing portion of a datagram was discarded because the datagram 268was larger than the buffer supplied. 269.Dv MSG_CTRUNC 270indicates that some 271control data were discarded due to lack of space in the buffer 272for ancillary data. 273.Dv MSG_OOB 274is returned to indicate that expedited or out-of-band data were received. 275.Sh RETURN VALUES 276These calls return the number of bytes received, or -1 277if an error occurred. 278.Sh ERRORS 279The calls fail if: 280.Bl -tag -width Er 281.It Bq Er EBADF 282The argument 283.Fa s 284is an invalid descriptor. 285.It Bq Er ECONNRESET 286The remote socket end is forcibly closed. 287.It Bq Er ENOTCONN 288The socket is associated with a connection-oriented protocol 289and has not been connected (see 290.Xr connect 2 291and 292.Xr accept 2 ) . 293.It Bq Er ENOTSOCK 294The argument 295.Fa s 296does not refer to a socket. 297.It Bq Er EMSGSIZE 298The 299.Fn recvmsg 300system call 301was used to receive rights (file descriptors) that were in flight on the 302connection. 303However, the receiving program did not have enough free file 304descriptor slots to accept them. 305In this case the descriptors are 306closed, any pending data can be returned by another call to 307.Fn recvmsg . 308.It Bq Er EAGAIN 309The socket is marked non-blocking, and the receive operation 310would block, or 311a receive timeout had been set, 312and the timeout expired before data were received. 313.It Bq Er EINTR 314The receive was interrupted by delivery of a signal before 315any data were available. 316.It Bq Er EFAULT 317The receive buffer pointer(s) point outside the process's 318address space. 319.El 320.Sh SEE ALSO 321.Xr fcntl 2 , 322.Xr getsockopt 2 , 323.Xr read 2 , 324.Xr select 2 , 325.Xr socket 2 326.Sh HISTORY 327The 328.Fn recv 329function appeared in 330.Bx 4.2 . 331