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.\" $DragonFly: src/lib/libc/sys/recv.2,v 1.7 2008/05/02 02:05:04 swildner Exp $ 31.\" 32.Dd February 21, 1994 33.Dt RECV 2 34.Os 35.Sh NAME 36.Nm recv , 37.Nm recvfrom , 38.Nm recvmsg 39.Nd receive a message from a socket 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 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 *buf" "size_t len" "int flags" "struct sockaddr *from" "socklen_t *fromlen" 49.Ft ssize_t 50.Fn recvmsg "int s" "struct msghdr *msg" "int flags" 51.Sh DESCRIPTION 52.Fn Recvfrom 53and 54.Fn recvmsg 55are used to receive messages from a socket, 56and may be used to receive data on a socket whether or not 57it is connection-oriented. 58.Pp 59If 60.Fa from 61is non-nil, and the socket is not connection-oriented, 62the source address of the message is filled in. 63.Fa Fromlen 64is a value-result parameter, initialized to the size of 65the buffer associated with 66.Fa from , 67and modified on return to indicate the actual size of the 68address stored there. 69.Pp 70The 71.Fn recv 72call is normally used only on a 73.Em connected 74socket (see 75.Xr connect 2 ) 76and is identical to 77.Fn recvfrom 78with a nil 79.Fa from 80parameter. 81As it is redundant, it may not be supported in future releases. 82.Pp 83All three routines return the length of the message on successful 84completion. 85If a message is too long to fit in the supplied buffer, 86excess bytes may be discarded depending on the type of socket 87the message is received from (see 88.Xr socket 2 ) . 89.Pp 90If no messages are available at the socket, the 91receive call waits for a message to arrive, unless 92the socket is nonblocking (see 93.Xr fcntl 2 ) 94in which case the value 95-1 is returned and the external variable 96.Va errno 97set to 98.Er EAGAIN . 99The receive calls normally return any data available, 100up to the requested amount, 101rather than waiting for receipt of the full amount requested; 102this behavior is affected by the socket-level options 103.Dv SO_RCVLOWAT 104and 105.Dv SO_RCVTIMEO 106described in 107.Xr getsockopt 2 . 108.Pp 109The 110.Xr select 2 111call may be used to determine when more data arrive. 112.Pp 113The 114.Fa flags 115argument to a recv call is formed by 116.Em or Ap ing 117one or more of the values: 118.Bl -column MSG_WAITALL -offset indent 119.It Dv MSG_OOB Ta process out-of-band data 120.It Dv MSG_PEEK Ta peek at incoming message 121.It Dv MSG_WAITALL Ta wait for full request or error 122.El 123.Pp 124The 125.Dv MSG_OOB 126flag requests receipt of out-of-band data 127that would not be received in the normal data stream. 128Some protocols place expedited data at the head of the normal 129data queue, and thus this flag cannot be used with such protocols. 130The MSG_PEEK flag causes the receive operation to return data 131from the beginning of the receive queue without removing that 132data from the queue. 133Thus, a subsequent receive call will return the same data. 134The MSG_WAITALL flag requests that the operation block until 135the full request is satisfied. 136However, the call may still return less data than requested 137if a signal is caught, an error or disconnect occurs, 138or the next data to be received is of a different type than that returned. 139.Pp 140The 141.Fn recvmsg 142call uses a 143.Fa msghdr 144structure to minimize the number of directly supplied parameters. 145This structure has the following form, as defined in 146.In sys/socket.h : 147.Bd -literal 148struct msghdr { 149 caddr_t msg_name; /* optional address */ 150 u_int msg_namelen; /* size of address */ 151 struct iovec *msg_iov; /* scatter/gather array */ 152 u_int msg_iovlen; /* # elements in msg_iov */ 153 caddr_t msg_control; /* ancillary data, see below */ 154 u_int msg_controllen; /* ancillary data buffer len */ 155 int msg_flags; /* flags on received message */ 156}; 157.Ed 158.Pp 159Here 160.Fa msg_name 161and 162.Fa msg_namelen 163specify the destination address if the socket is unconnected; 164.Fa msg_name 165may be given as a null pointer if no names are desired or required. 166.Fa Msg_iov 167and 168.Fa msg_iovlen 169describe scatter gather locations, as discussed in 170.Xr read 2 . 171.Fa Msg_control , 172which has length 173.Fa msg_controllen , 174points to a buffer for other protocol control related messages 175or other miscellaneous ancillary data. 176The messages are of the form: 177.Bd -literal 178struct cmsghdr { 179 u_int cmsg_len; /* data byte count, including hdr */ 180 int cmsg_level; /* originating protocol */ 181 int cmsg_type; /* protocol-specific type */ 182/* followed by 183 u_char cmsg_data[]; */ 184}; 185.Ed 186.Pp 187As an example, one could use this to learn of changes in the data-stream 188in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting 189a recvmsg with no data buffer provided immediately after an 190.Fn accept 191call. 192.Pp 193Open file descriptors are now passed as ancillary data for 194.Dv AF_UNIX 195domain sockets, with 196.Fa cmsg_level 197set to 198.Dv SOL_SOCKET 199and 200.Fa cmsg_type 201set to 202.Dv SCM_RIGHTS . 203.Pp 204Process credentials can also be passed as ancillary data for 205.Dv AF_UNIX 206domain sockets using a 207.Fa cmsg_type 208of 209.Dv SCM_CREDS . 210In this case, 211.Fa cmsg_data 212should be a structure of type 213.Fa cmsgcred , 214which is defined in 215.In sys/socket.h 216as follows: 217.Bd -literal 218struct cmsgcred { 219 pid_t cmcred_pid; /* PID of sending process */ 220 uid_t cmcred_uid; /* real UID of sending process */ 221 uid_t cmcred_euid; /* effective UID of sending process */ 222 gid_t cmcred_gid; /* real GID of sending process */ 223 short cmcred_ngroups; /* number or groups */ 224 gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ 225}; 226.Ed 227.Pp 228The kernel will fill in the credential information of the sending process 229and deliver it to the receiver. 230.Pp 231The 232.Fa msg_flags 233field is set on return according to the message received. 234.Dv MSG_EOR 235indicates end-of-record; 236the data returned completed a record (generally used with sockets of type 237.Dv SOCK_SEQPACKET ) . 238.Dv MSG_TRUNC 239indicates that 240the trailing portion of a datagram was discarded because the datagram 241was larger than the buffer supplied. 242.Dv MSG_CTRUNC 243indicates that some 244control data were discarded due to lack of space in the buffer 245for ancillary data. 246.Dv MSG_OOB 247is returned to indicate that expedited or out-of-band data were received. 248.Sh RETURN VALUES 249Upon successful completion the number of bytes which were received is 250returned. Otherwise -1 is returned and the global variable 251.Va errno 252is set to indicate the error. 253.Sh ERRORS 254The calls fail if: 255.Bl -tag -width Er 256.It Bq Er EBADF 257The argument 258.Fa s 259is an invalid descriptor. 260.It Bq Er ENOTCONN 261The socket is associated with a connection-oriented protocol 262and has not been connected (see 263.Xr connect 2 264and 265.Xr accept 2 ) . 266.It Bq Er ENOTSOCK 267The argument 268.Fa s 269does not refer to a socket. 270.It Bq Er EAGAIN 271The socket is marked non-blocking, and the receive operation 272would block, or 273a receive timeout had been set, 274and the timeout expired before data were received. 275.It Bq Er EINTR 276The receive was interrupted by delivery of a signal before 277any data were available. 278.It Bq Er EFAULT 279The receive buffer pointer(s) point outside the process's 280address space. 281.El 282.Sh SEE ALSO 283.Xr fcntl 2 , 284.Xr getsockopt 2 , 285.Xr read 2 , 286.Xr select 2 , 287.Xr socket 2 288.Sh HISTORY 289The 290.Fn recv 291function call appeared in 292.Bx 4.2 . 293