1.\" Copyright (c) 1983, 1990, 1991, 1993 2.\" The Regents of the University of California. 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.\" @(#)recv.2 8.3 (Berkeley) 2/21/94 33.\" $FreeBSD: src/lib/libc/sys/recv.2,v 1.8.2.8 2001/12/14 18:34:01 ru Exp $ 34.\" $DragonFly: src/lib/libc/sys/recv.2,v 1.7 2008/05/02 02:05:04 swildner Exp $ 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.In sys/types.h 48.In 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 115call may be used to determine when more data arrive. 116.Pp 117The 118.Fa flags 119argument to a recv call is formed by 120.Em or Ap ing 121one or more of the values: 122.Bl -column MSG_WAITALL -offset indent 123.It Dv MSG_OOB Ta process out-of-band data 124.It Dv MSG_PEEK Ta peek at incoming message 125.It Dv MSG_WAITALL Ta wait for full request or error 126.El 127.Pp 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.In sys/socket.h : 151.Bd -literal 152struct msghdr { 153 caddr_t msg_name; /* optional address */ 154 u_int msg_namelen; /* size of address */ 155 struct iovec *msg_iov; /* scatter/gather array */ 156 u_int msg_iovlen; /* # elements in msg_iov */ 157 caddr_t msg_control; /* ancillary data, see below */ 158 u_int msg_controllen; /* ancillary data buffer len */ 159 int msg_flags; /* flags on received message */ 160}; 161.Ed 162.Pp 163Here 164.Fa msg_name 165and 166.Fa msg_namelen 167specify the destination address if the socket is unconnected; 168.Fa msg_name 169may be given as a null pointer if no names are desired or required. 170.Fa Msg_iov 171and 172.Fa msg_iovlen 173describe scatter gather locations, as discussed in 174.Xr read 2 . 175.Fa Msg_control , 176which has length 177.Fa msg_controllen , 178points to a buffer for other protocol control related messages 179or other miscellaneous ancillary data. 180The messages are of the form: 181.Bd -literal 182struct cmsghdr { 183 u_int cmsg_len; /* data byte count, including hdr */ 184 int cmsg_level; /* originating protocol */ 185 int cmsg_type; /* protocol-specific type */ 186/* followed by 187 u_char cmsg_data[]; */ 188}; 189.Ed 190.Pp 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_UNIX 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 208Process credentials can also be passed as ancillary data for 209.Dv AF_UNIX 210domain sockets using a 211.Fa cmsg_type 212of 213.Dv SCM_CREDS . 214In this case, 215.Fa cmsg_data 216should be a structure of type 217.Fa cmsgcred , 218which is defined in 219.In sys/socket.h 220as follows: 221.Bd -literal 222struct cmsgcred { 223 pid_t cmcred_pid; /* PID of sending process */ 224 uid_t cmcred_uid; /* real UID of sending process */ 225 uid_t cmcred_euid; /* effective UID of sending process */ 226 gid_t cmcred_gid; /* real GID of sending process */ 227 short cmcred_ngroups; /* number or groups */ 228 gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ 229}; 230.Ed 231.Pp 232The kernel will fill in the credential information of the sending process 233and deliver it to the receiver. 234.Pp 235The 236.Fa msg_flags 237field is set on return according to the message received. 238.Dv MSG_EOR 239indicates end-of-record; 240the data returned completed a record (generally used with sockets of type 241.Dv SOCK_SEQPACKET ) . 242.Dv MSG_TRUNC 243indicates that 244the trailing portion of a datagram was discarded because the datagram 245was larger than the buffer supplied. 246.Dv MSG_CTRUNC 247indicates that some 248control data were discarded due to lack of space in the buffer 249for ancillary data. 250.Dv MSG_OOB 251is returned to indicate that expedited or out-of-band data were received. 252.Sh RETURN VALUES 253Upon successful completion the number of bytes which were received is 254returned. Otherwise -1 is returned and the global variable 255.Va errno 256is set to indicate the error. 257.Sh ERRORS 258The calls fail if: 259.Bl -tag -width Er 260.It Bq Er EBADF 261The argument 262.Fa s 263is an invalid descriptor. 264.It Bq Er ENOTCONN 265The socket is associated with a connection-oriented protocol 266and has not been connected (see 267.Xr connect 2 268and 269.Xr accept 2 ) . 270.It Bq Er ENOTSOCK 271The argument 272.Fa s 273does not refer to a socket. 274.It Bq Er EAGAIN 275The socket is marked non-blocking, and the receive operation 276would block, or 277a receive timeout had been set, 278and the timeout expired before data were received. 279.It Bq Er EINTR 280The receive was interrupted by delivery of a signal before 281any data were available. 282.It Bq Er EFAULT 283The receive buffer pointer(s) point outside the process's 284address space. 285.El 286.Sh SEE ALSO 287.Xr fcntl 2 , 288.Xr getsockopt 2 , 289.Xr read 2 , 290.Xr select 2 , 291.Xr socket 2 292.Sh HISTORY 293The 294.Fn recv 295function call appeared in 296.Bx 4.2 . 297