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.5 2006/05/26 19:39:37 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.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 191.Pp 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_UNIX 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 209Process credentials can also be passed as ancillary data for 210.Dv AF_UNIX 211domain sockets using a 212.Fa cmsg_type 213of 214.Dv SCM_CREDS . 215In this case, 216.Fa cmsg_data 217should be a structure of type 218.Fa cmsgcred , 219which is defined in 220.In sys/socket.h 221as follows: 222.Pp 223.Bd -literal 224struct cmsgcred { 225 pid_t cmcred_pid; /* PID of sending process */ 226 uid_t cmcred_uid; /* real UID of sending process */ 227 uid_t cmcred_euid; /* effective UID of sending process */ 228 gid_t cmcred_gid; /* real GID of sending process */ 229 short cmcred_ngroups; /* number or groups */ 230 gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ 231}; 232.Ed 233.Pp 234The kernel will fill in the credential information of the sending process 235and deliver it to the receiver. 236.Pp 237The 238.Fa msg_flags 239field is set on return according to the message received. 240.Dv MSG_EOR 241indicates end-of-record; 242the data returned completed a record (generally used with sockets of type 243.Dv SOCK_SEQPACKET ) . 244.Dv MSG_TRUNC 245indicates that 246the trailing portion of a datagram was discarded because the datagram 247was larger than the buffer supplied. 248.Dv MSG_CTRUNC 249indicates that some 250control data were discarded due to lack of space in the buffer 251for ancillary data. 252.Dv MSG_OOB 253is returned to indicate that expedited or out-of-band data were received. 254.Sh RETURN VALUES 255Upon successful completion the number of bytes which were received is 256returned. Otherwise -1 is returned and the global variable errno is 257set to indicate the error. 258.Sh ERRORS 259The calls fail if: 260.Bl -tag -width Er 261.It Bq Er EBADF 262The argument 263.Fa s 264is an invalid descriptor. 265.It Bq Er ENOTCONN 266The socket is associated with a connection-oriented protocol 267and has not been connected (see 268.Xr connect 2 269and 270.Xr accept 2 ) . 271.It Bq Er ENOTSOCK 272The argument 273.Fa s 274does not refer to a socket. 275.It Bq Er EAGAIN 276The socket is marked non-blocking, and the receive operation 277would block, or 278a receive timeout had been set, 279and the timeout expired before data were received. 280.It Bq Er EINTR 281The receive was interrupted by delivery of a signal before 282any data were available. 283.It Bq Er EFAULT 284The receive buffer pointer(s) point outside the process's 285address space. 286.El 287.Sh SEE ALSO 288.Xr fcntl 2 , 289.Xr getsockopt 2 , 290.Xr read 2 , 291.Xr select 2 , 292.Xr socket 2 293.Sh HISTORY 294The 295.Fn recv 296function call appeared in 297.Bx 4.2 . 298