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