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