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