lib/libc/recv.2

   1 .\"     $OpenBSD: recv.2,v 1.43 2015/02/16 16:20:15 tedu Exp $
   2 .\"     $NetBSD: recv.2,v 1.6 1995/02/27 12:36:08 cgd Exp $
   3 .\"
   4 .\" Copyright (c) 1983, 1990, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)recv.2      8.3 (Berkeley) 2/21/94
  32 .\"
  33 .Dd October 25, 2016
  34 .Dt RECV 2
  35 .Os
  36 .Sh NAME
  37 .Nm recv ,
  38 .Nm recvfrom ,
  39 .Nm recvmsg
  40 .Nd receive a message from a socket
  41 .Sh SYNOPSIS
  42 .In sys/socket.h
  43 .Ft ssize_t
  44 .Fn recv "int s" "void *buf" "size_t len" "int flags"
  45 .Ft ssize_t
  46 .Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr *from" "socklen_t *fromlen"
  47 .Ft ssize_t
  48 .Fn recvmsg "int s" "struct msghdr *msg" "int flags"
  49 .Sh DESCRIPTION
  50 .Fn recvfrom
  51 and
  52 .Fn recvmsg
  53 are used to receive messages from a socket,
  54 .Fa s ,
  55 and may be used to receive
  56 data on a socket whether or not it is connection-oriented.
  57 .Pp
  58 If
  59 .Fa from
  60 is non-null and the socket is not connection-oriented,
  61 the source address of the message is filled in.
  62 .Fa fromlen
  63 is a value-result parameter, initialized to the size of
  64 the buffer associated with
  65 .Fa from ,
  66 and modified on return to indicate the actual size of the
  67 address stored there.
  68 .Pp
  69 The
  70 .Fn recv
  71 call is normally used only on a
  72 .Em connected
  73 socket (see
  74 .Xr connect 2 )
  75 and is identical to
  76 .Fn recvfrom
  77 with a null
  78 .Fa from
  79 parameter.
  80 .Pp
  81 On successful completion, all three routines return the number of
  82 message bytes read.
  83 If a message is too long to fit in the supplied
  84 buffer, excess bytes may be discarded depending on the type of socket
  85 the message is received from (see
  86 .Xr socket 2 ) .
  87 .Pp
  88 If no messages are available at the socket, the
  89 receive call waits for a message to arrive, unless
  90 the socket is nonblocking (see
  91 .Xr fcntl 2 )
  92 in which case the value
  93 \-1 is returned and the external variable
  94 .Va errno
  95 set to
  96 .Er EAGAIN .
  97 The receive calls normally return any data available,
  98 up to the requested amount,
  99 rather than waiting for receipt of the full amount requested;
 100 this behavior is affected by the socket-level options
 101 .Dv SO_RCVLOWAT
 102 and
 103 .Dv SO_RCVTIMEO
 104 described in
 105 .Xr getsockopt 2 .
 106 .Pp
 107 The
 108 .Xr select 2
 109 or
 110 .Xr poll 2
 111 system calls may be used to determine when more data arrive.
 112 .Pp
 113 The
 114 .Fa flags
 115 argument is the bitwise OR of zero or more of the following values:
 116 .Pp
 117 .Bl -tag -width "MSG_DONTWAITXX" -offset indent -compact
 118 .It Dv MSG_OOB
 119 process out-of-band data
 120 .It Dv MSG_PEEK
 121 peek at incoming message
 122 .It Dv MSG_WAITALL
 123 wait for full request or error
 124 .It Dv MSG_DONTWAIT
 125 don't block
 126 .El
 127 .Pp
 128 The
 129 .Dv MSG_OOB
 130 flag requests receipt of out-of-band data
 131 that would not be received in the normal data stream.
 132 Some protocols place expedited data at the head of the normal
 133 data queue, and thus this flag cannot be used with such protocols.
 134 The
 135 .Dv MSG_PEEK
 136 flag causes the receive operation to return data
 137 from the beginning of the receive queue without removing that
 138 data from the queue.
 139 Thus, a subsequent receive call will return the same data.
 140 The
 141 .Dv MSG_WAITALL
 142 flag requests that the operation block until
 143 the full request is satisfied.
 144 However, the call may still return less data than requested
 145 if a signal is caught, an error or disconnect occurs,
 146 or the next data to be received is of a different type than that returned.
 147 The
 148 .Dv MSG_DONTWAIT
 149 flag requests the call to return when it would block otherwise.
 150 If no data is available,
 151 .Va errno
 152 is set to
 153 .Er EAGAIN .
 154 .Pp
 155 The
 156 .Fn recvmsg
 157 call uses a
 158 .Fa msghdr
 159 structure to minimize the number of directly supplied parameters.
 160 This structure has the following form, as defined in
 161 .In sys/socket.h :
 162 .Bd -literal
 163 struct msghdr {
 164         void            *msg_name;      /* optional address */
 165         socklen_t       msg_namelen;    /* size of address */
 166         struct          iovec *msg_iov; /* scatter/gather array */
 167         int             msg_iovlen;     /* # elements in msg_iov */
 168         void            *msg_control;   /* ancillary data, see below */
 169         socklen_t       msg_controllen; /* ancillary data buffer len */
 170         int             msg_flags;      /* flags on received message */
 171 };
 172 .Ed
 173 .Pp
 174 Here
 175 .Fa msg_name
 176 and
 177 .Fa msg_namelen
 178 specify the source address if the socket is unconnected;
 179 .Fa msg_name
 180 may be given as a null pointer if no names are desired or required.
 181 .Fa msg_iov
 182 and
 183 .Fa msg_iovlen
 184 describe scatter gather locations, as discussed in
 185 .Xr read 2 .
 186 .Fa msg_control ,
 187 which has length
 188 .Fa msg_controllen ,
 189 points to a buffer for other protocol control related messages
 190 or other miscellaneous ancillary data.
 191 The messages are of the form:
 192 .Bd -literal
 193 struct cmsghdr {
 194         socklen_t       cmsg_len;   /* data byte count, including hdr */
 195         int             cmsg_level; /* originating protocol */
 196         int             cmsg_type;  /* protocol-specific type */
 197 /* followed by u_char   cmsg_data[]; */
 198 };
 199 .Ed
 200 .Pp
 201 See
 202 .Xr CMSG_DATA 3
 203 for how these messages are constructed and decomposed.
 204 .Pp
 205 Open file descriptors are now passed as ancillary data for
 206 .Dv AF_UNIX
 207 domain and
 208 .Xr socketpair 2
 209 sockets, with
 210 .Fa cmsg_level
 211 set to
 212 .Dv SOL_SOCKET
 213 and
 214 .Fa cmsg_type
 215 set to
 216 .Dv SCM_RIGHTS .
 217 .Pp
 218 The
 219 .Fa msg_flags
 220 field is set on return according to the message received.
 221 It will contain zero or more of the following values:
 222 .Pp
 223 .Bl -tag -width MSG_CTRUNC -offset indent -compact
 224 .It Dv MSG_OOB
 225 Returned to indicate that expedited or out-of-band data was received.
 226 .It Dv MSG_EOR
 227 Indicates end-of-record;
 228 the data returned completed a record (generally used with sockets of type
 229 .Dv SOCK_SEQPACKET ) .
 230 .It Dv MSG_TRUNC
 231 Indicates that
 232 the trailing portion of a datagram was discarded because the datagram
 233 was larger than the buffer supplied.
 234 .It Dv MSG_CTRUNC
 235 Indicates that some
 236 control data were discarded due to lack of space in the buffer
 237 for ancillary data.
 238 .El
 239 .Sh RETURN VALUES
 240 These calls return the number of bytes received, or \-1 if an error occurred.
 241 .Sh ERRORS
 242 .Fn recv ,
 243 .Fn recvfrom ,
 244 and
 245 .Fn recvmsg
 246 fail if:
 247 .Bl -tag -width "[EHOSTUNREACH]"
 248 .It Bq Er EBADF
 249 The argument
 250 .Fa s
 251 is an invalid descriptor.
 252 .It Bq Er ENOTCONN
 253 The socket is associated with a connection-oriented protocol
 254 and has not been connected (see
 255 .Xr connect 2
 256 and
 257 .Xr accept 2 ) .
 258 .It Bq Er ENOTSOCK
 259 The argument
 260 .Fa s
 261 does not refer to a socket.
 262 .It Bq Er EAGAIN
 263 The socket is marked non-blocking, and the receive operation
 264 would block, or
 265 a receive timeout had been set,
 266 and the timeout expired before data were received.
 267 .It Bq Er EINTR
 268 The receive was interrupted by delivery of a signal before
 269 any data were available.
 270 .It Bq Er EFAULT
 271 The receive buffer pointer(s) point outside the process's
 272 address space.
 273 .It Bq Er ECONNREFUSED
 274 The socket is associated with a connection-oriented protocol
 275 and the connection was forcefully rejected (see
 276 .Xr connect 2 ) .
 277 .It Bq Er ECONNRESET
 278 The socket is associated with a connection-oriented protocol
 279 and the connection was forcefully closed by the peer.
 280 .El
 281 .Pp
 282 In addition,
 283 .Fn recv
 284 and
 285 .Fn recvfrom
 286 may return the following error:
 287 .Bl -tag -width Er
 288 .It Bq Er EINVAL
 289 .Fa len
 290 was larger than
 291 .Dv SSIZE_MAX .
 292 .El
 293 .Pp
 294 And
 295 .Fn recvmsg
 296 may return one of the following errors:
 297 .Bl -tag -width Er
 298 .It Bq Er EINVAL
 299 The sum of the
 300 .Fa iov_len
 301 values in the
 302 .Fa msg_iov
 303 array overflowed an
 304 .Em ssize_t .
 305 .It Bq Er EMSGSIZE
 306 The
 307 .Fa msg_iovlen
 308 member of
 309 .Fa msg
 310 was less than 0 or larger than
 311 .Dv IOV_MAX .
 312 .El
 313 .Sh SEE ALSO
 314 .Xr connect 2 ,
 315 .Xr fcntl 2 ,
 316 .Xr getsockopt 2 ,
 317 .Xr poll 2 ,
 318 .Xr read 2 ,
 319 .Xr select 2 ,
 320 .Xr socket 2 ,
 321 .Xr socketpair 2 ,
 322 .Xr CMSG_DATA 3 ,
 323 .Xr sockatmark 3
 324 .Sh STANDARDS
 325 The
 326 .Fn recv ,
 327 .Fn recvfrom ,
 328 and
 329 .Fn recvmsg
 330 functions conform to
 331 .St -p1003.1-2008 .
 332 The
 333 .Dv MSG_DONTWAIT
 334 flag is an extension to that specification.
 335 .Sh HISTORY
 336 The
 337 .Fn recv
 338 function call appeared in
 339 .Bx 4.2 .