1.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. 2.\" 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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" from: @(#)recv.2 6.11 (Berkeley) 5/1/91 33.\" $Id: recv.2,v 1.5 1994/01/10 23:54:25 jtc Exp $ 34.\" 35.Dd May 1, 1991 36.Dt RECV 2 37.Os BSD 4.3r 38.Sh NAME 39.Nm recv , 40.Nm recvfrom , 41.Nm recvmsg 42.Nd receive a message from a socket 43.Sh SYNOPSIS 44.Fd #include <sys/types.h> 45.Fd #include <sys/socket.h> 46.Ft int 47.Fn recv "int s" "void *buf" "int len" "int flags" 48.Ft int 49.Fn recvfrom "int s" "void *buf" "int len" "int flags" "struct sockaddr *from" "int *fromlen" 50.Ft int 51.Fn recvmsg "int s" "struct msghdr *msg" "int flags" 52.Sh DESCRIPTION 53.Fn Recvfrom 54and 55.Fn recvmsg 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 non-nil, and the socket is not connection-oriented, 63the source address of the message is filled in. 64.Fa Fromlen 65is a value-result parameter, initialized to the size of 66the buffer associated with 67.Fa from , 68and modified on return to indicate the actual size of the 69address stored there. 70.Pp 71The 72.Fn recv 73call is normally used only on a 74.Em connected 75socket (see 76.Xr connect 2 ) 77and is identical to 78.Fn recvfrom 79with a nil 80.Fa from 81parameter. 82As it is redundant, it may not be supported in future releases. 83.Pp 84All three routines return the length of the message on successful 85completion. 86If a message is too long to fit in the supplied buffer, 87excess bytes may be discarded depending on the type of socket 88the message is received from (see 89.Xr socket 2 ) . 90.Pp 91If no messages are available at the socket, the 92receive call waits for a message to arrive, unless 93the socket is nonblocking (see 94.Xr fcntl 2 ) 95in which case the value 96-1 is returned and the external variable 97.Va errno 98set to 99.Er EWOULDBLOCK. 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 112call may be used to determine when more data arrive. 113.Pp 114The 115.Fa flags 116argument to a recv call is formed by 117.Em or Ap ing 118one or more of the values: 119.Bl -column MSG_WAITALL -offset indent 120.It Dv MSG_OOB Ta process out-of-band data 121.It Dv MSG_PEEK Ta peek at incoming message 122.It Dv MSG_WAITALL Ta wait for full request or error 123.El 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.Ao Pa sys/socket.h Ac : 147.Pp 148.Bd -literal 149struct msghdr { 150 caddr_t msg_name; /* optional address */ 151 u_int msg_namelen; /* size of address */ 152 struct iovec *msg_iov; /* scatter/gather array */ 153 u_int msg_iovlen; /* # elements in msg_iov */ 154 caddr_t msg_control; /* ancillary data, see below */ 155 u_int msg_controllen; /* ancillary data buffer len */ 156 int msg_flags; /* flags on received message */ 157}; 158.Ed 159.Pp 160Here 161.Fa msg_name 162and 163.Fa msg_namelen 164specify the destination address if the socket is unconnected; 165.Fa msg_name 166may be given as a null pointer if no names are desired or required. 167.Fa Msg_iov 168and 169.Fa msg_iovlen 170describe scatter gather locations, as discussed in 171.Xr read 2 . 172.Fa Msg_control , 173which has length 174.Fa msg_controllen , 175points to a buffer for other protocol control related messages 176or other miscellaneous ancillary data. 177The messages are of the form: 178.Bd -literal 179struct cmsghdr { 180 u_int cmsg_len; /* data byte count, including hdr */ 181 int cmsg_level; /* originating protocol */ 182 int cmsg_type; /* protocol-specific type */ 183/* followed by 184 u_char cmsg_data[]; */ 185}; 186.Ed 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 204The 205.Fa msg_flags 206field is set on return according to the message received. 207.Dv MSG_EOR 208indicates end-of-record; 209the data returned completed a record (generally used with sockets of type 210.Dv SOCK_SEQPACKET ) . 211.Dv MSG_TRUNC 212indicates that 213the trailing portion of a datagram was discarded because the datagram 214was larger than the buffer supplied. 215.Dv MSG_CTRUNC 216indicates that some 217control data were discarded due to lack of space in the buffer 218for ancillary data. 219.Dv MSG_OOB 220is returned to indicate that expedited or out-of-band data were received. 221.Pp 222.Sh RETURN VALUES 223These calls return the number of bytes received, or -1 224if an error occurred. 225.Sh ERRORS 226The calls fail if: 227.Bl -tag -width Er 228.It Bq Er EBADF 229The argument 230.Fa s 231is an invalid descriptor. 232.It Bq Er ENOTCONN 233The socket is associated with a connection-oriented protocol 234and has not been connected (see 235.Xr connect 2 236and 237.Xr accept 2 ). 238.It Bq Er ENOTSOCK 239The argument 240.Fa s 241does not refer to a socket. 242.It Bq Er EWOULDBLOCK 243The socket is marked non-blocking, and the receive operation 244would block, or 245a receive timeout had been set, 246and the timeout expired before data were received. 247.It Bq Er EINTR 248The receive was interrupted by delivery of a signal before 249any data were available. 250.It Bq Er EFAULT 251The receive buffer pointer(s) point outside the process's 252address space. 253.El 254.Sh SEE ALSO 255.Xr fcntl 2 , 256.Xr read 2 , 257.Xr select 2 , 258.Xr getsockopt 2 , 259.Xr socket 2 260.Sh HISTORY 261The 262.Fn recv 263function call appeared in 264.Bx 4.2 . 265