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