1.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)recv.2 6.9 (Berkeley) 03/10/91 7.\" 8.Dd 9.Dt RECV 2 10.Os BSD 4.2 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 int 20.Fn recv "int s" "char *buf" "int len" "int flags" 21.Ft int 22.Fn recvfrom "int s" "char *buf" "int len" "int flags" "struct sockaddr *from" "int *fromlen" 23.Ft int 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 31it is in a connected state or not. 32.Pp 33If 34.Fa from 35is non-nil, the source address of the message is filled in. 36.Fa Fromlen 37is a value-result parameter, initialized to the size of 38the buffer associated with 39.Fa from , 40and modified on return to indicate the actual size of the 41address stored there. 42.Pp 43The 44.Fn recv 45call is normally used only on a 46.Em connected 47socket (see 48.Xr connect 2 ) 49and is identical to 50.Fn recvfrom 51with a nil 52.Fa from 53parameter. 54As it is redundant, it may not be supported in future releases. 55.Pp 56All three routines return the length of the message on successful 57completion. 58If a message is too long to fit in the supplied buffer, 59excess bytes may be discarded depending on the type of socket 60the message is received from (see 61.Xr socket 2 ) . 62.Pp 63If no messages are available at the socket, the 64receive call waits for a message to arrive, unless 65the socket is nonblocking (see 66.Xr ioctl 2 ) 67in which case the value 68-1 is returned and the external variable 69.Va errno 70set to 71.Er EWOULDBLOCK. 72.Pp 73The 74.Xr select 2 75call may be used to determine when more data arrives. 76.Pp 77The 78.Fa flags 79argument to a recv call is formed by 80.Em or Ap ing 81one or more of the values: 82.Bd -literal 83#define MSG_OOB 0x1 /* process out-of-band data */ 84#define MSG_PEEK 0x2 /* peek at incoming message */ 85#define MSG_DONTROUTE 0x4 /* send without using routing tables */ 86#define MSG_EOR 0x8 /* data completes record */ 87#define MSG_TRUNC 0x10 /* data discarded before delivery */ 88#define MSG_CTRUNC 0x20 /* control data lost before delivery */ 89.Ed 90.Pp 91The 92.Fn recvmsg 93call uses a 94.Fa msghdr 95structure to minimize the number of directly supplied parameters. 96This structure has the following form, as defined in 97.Ao Pa sys/socket.h Ac : 98.Pp 99.Bd -literal 100struct msghdr { 101 caddr_t msg_name; /* optional address */ 102 u_int msg_namelen; /* size of address */ 103 struct iovec *msg_iov; /* scatter/gather array */ 104 u_int msg_iovlen; /* # elements in msg_iov */ 105 caddr_t msg_control; /* ancillary data, see below */ 106 u_int msg_controllen; /* ancillary data buffer len */ 107 int msg_flags; /* flags on received message */ 108}; 109.Ed 110.Pp 111Here 112.Fa msg_name 113and 114.Fa msg_namelen 115specify the destination address if the socket is unconnected; 116.Fa msg_name 117may be given as a null pointer if no names are desired or required. 118.Fa Msg_iov 119and 120.Fa msg_iovlen 121describe scatter gather locations, as discussed in 122.Xr read 2 . 123.Fa Msg_control , 124which has length 125.Fa msg_controllen , 126points to a buffer for other protocol control related messages 127or other miscellaneous ancillary data. 128The messages are of the form: 129.Bd -literal 130struct cmsghdr { 131 u_int cmsg_len; /* data byte count, including hdr */ 132 int cmsg_level; /* originating protocol */ 133 int cmsg_type; /* protocol-specific type */ 134/* followed by 135 u_char cmsg_data[]; */ 136}; 137.Ed 138As an example, one could use this to learn of changes in the data-stream 139in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting 140a recvmsg with no uio provided immediately after an 141.Fn accept , 142thought of here in the sense of get-next-connection-request without 143an implicit connection confirmation. 144.Pp 145Open file descriptors are now passed as ancillary data for 146.Dv AF_UNIX 147domain sockets, with 148.Fa cmsg_level 149being 150.Dv SOL_SOCKET 151and 152.Fa cmsg_type 153being 154.Dv SCM_RIGHTS . 155.Pp 156.Fa Msg_flags 157is set on return according to the message received. 158.Dv MSG_EOR 159indicates end-of-record, 160.Dv MSG_TRUNC 161indicates that 162some trailing datagram data was discarded, 163.Dv MSG_CTRUNC 164indicates that some 165control data was discarded due to lack of space, 166.Dv MSG_OOB 167is returned to indicate that expedited data was received. 168.Pp 169.Sh RETURN VALUES 170These calls return the number of bytes received, or -1 171if an error occurred. 172.Sh ERRORS 173The calls fail if: 174.Bl -tag -width EWOULDBLOCKAA 175.It Bq Er EBADF 176The argument 177.Fa s 178is an invalid descriptor. 179.It Bq Er ENOTSOCK 180The argument 181.Fa s 182is not a socket. 183.It Bq Er EWOULDBLOCK 184The socket is marked non-blocking and the receive operation 185would block. 186.It Bq Er EINTR 187The receive was interrupted by delivery of a signal before 188any data was available. 189.It Bq Er EFAULT 190The receive buffer pointer(s) point outside the process's 191address space. 192.El 193.Sh SEE ALSO 194.Xr fcntl 2 , 195.Xr read 2 , 196.Xr send 2 , 197.Xr select 2 , 198.Xr getsockopt 2 , 199.Xr socket 2 200.Sh HISTORY 201The 202.Nm 203function call appeared in 204.Bx 4.2 . 205