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