original/man2/recv.2

   1 .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $
  35 .\"
  36 .\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith <faith@cs.unc.edu>
  37 .\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond <esr@thyrsus.com>
  38 .\" Modified 1998,1999 by Andi Kleen
  39 .\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin
  40 .\"
  41 .TH RECV 2 2014-02-11 "Linux" "Linux Programmer's Manual"
  42 .SH NAME
  43 recv, recvfrom, recvmsg \- receive a message from a socket
  44 .SH SYNOPSIS
  45 .\" .B #include <sys/uio.h>
  46 .\" .br
  47 .nf
  48 .B #include <sys/types.h>
  49 .br
  50 .B #include <sys/socket.h>
  51 .sp
  52 .BI "ssize_t recv(int " sockfd ", void *" buf ", size_t " len ", int " flags );
  53 .sp
  54 .BI "ssize_t recvfrom(int " sockfd ", void *" buf ", size_t " len ", int " flags ,
  55 .BI "                 struct sockaddr *" src_addr ", socklen_t *" addrlen );
  56 .sp
  57 .BI "ssize_t recvmsg(int " sockfd ", struct msghdr *" msg ", int " flags );
  58 .fi
  59 .SH DESCRIPTION
  60 The
  61 .BR recv (),
  62 .BR recvfrom (),
  63 and
  64 .BR recvmsg ()
  65 calls are used to receive messages from a socket.
  66 They may be used
  67 to receive data on both connectionless and connection-oriented sockets.
  68 This page first describes common features of all three system calls,
  69 and then describes the differences between the calls.
  70 .PP
  71 All three calls return the length of the message on successful
  72 completion.
  73 If a message is too long to fit in the supplied buffer, excess
  74 bytes may be discarded depending on the type of socket the message is
  75 received from.
  76 .PP
  77 If no messages are available at the socket, the receive calls wait for a
  78 message to arrive, unless the socket is nonblocking (see
  79 .BR fcntl (2)),
  80 in which case the value \-1 is returned and the external variable
  81 .I errno
  82 is set to
  83 .BR EAGAIN " or " EWOULDBLOCK .
  84 The receive calls normally return any data available, up to the requested
  85 amount, rather than waiting for receipt of the full amount requested.
  86 .PP
  87 An application can used
  88 .BR select (2),
  89 .BR poll (2),
  90 or
  91 .BR epoll (7)
  92 to determine when more data arrives on a socket.
  93 .SS The flags argument
  94 The
  95 .I flags
  96 argument is formed by ORing one or more of the following values:
  97 .TP
  98 .BR MSG_CMSG_CLOEXEC " (" recvmsg "() only; since Linux 2.6.23)"
  99 Set the close-on-exec flag for the file descriptor received
 100 via a UNIX domain file descriptor using the
 101 .B SCM_RIGHTS
 102 operation (described in
 103 .BR unix (7)).
 104 This flag is useful for the same reasons as the
 105 .B O_CLOEXEC
 106 flag of
 107 .BR open (2).
 108 .TP
 109 .BR MSG_DONTWAIT " (since Linux 2.2)"
 110 Enables nonblocking operation; if the operation would block,
 111 the call fails with the error
 112 .BR EAGAIN " or " EWOULDBLOCK
 113 (this can also be enabled using the
 114 .B O_NONBLOCK
 115 flag with the
 116 .B F_SETFL
 117 .BR fcntl (2)).
 118 .TP
 119 .BR MSG_ERRQUEUE " (since Linux 2.2)"
 120 This flag
 121 specifies that queued errors should be received from the socket error queue.
 122 The error is passed in
 123 an ancillary message with a type dependent on the protocol (for IPv4
 124 .BR IP_RECVERR ).
 125 The user should supply a buffer of sufficient size.
 126 See
 127 .BR cmsg (3)
 128 and
 129 .BR ip (7)
 130 for more information.
 131 The payload of the original packet that caused the error
 132 is passed as normal data via
 133 .IR msg_iovec .
 134 The original destination address of the datagram that caused the error
 135 is supplied via
 136 .IR msg_name .
 137 .IP
 138 For local errors, no address is passed (this can be checked with the
 139 .I cmsg_len
 140 member of the
 141 .IR cmsghdr ).
 142 For error receives, the
 143 .B MSG_ERRQUEUE
 144 is set in the
 145 .IR msghdr .
 146 After an error has been passed, the pending socket error
 147 is regenerated based on the next queued error and will be passed
 148 on the next socket operation.
 149
 150 The error is supplied in a
 151 .I sock_extended_err
 152 structure:
 153 .in +4n
 154 .nf
 155
 156 #define SO_EE_ORIGIN_NONE    0
 157 #define SO_EE_ORIGIN_LOCAL   1
 158 #define SO_EE_ORIGIN_ICMP    2
 159 #define SO_EE_ORIGIN_ICMP6   3
 160
 161 struct sock_extended_err
 162 {
 163     uint32_t ee_errno;   /* error number */
 164     uint8_t  ee_origin;  /* where the error originated */
 165     uint8_t  ee_type;    /* type */
 166     uint8_t  ee_code;    /* code */
 167     uint8_t  ee_pad;     /* padding */
 168     uint32_t ee_info;    /* additional information */
 169     uint32_t ee_data;    /* other data */
 170     /* More data may follow */
 171 };
 172
 173 struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
 174 .fi
 175 .in
 176 .IP
 177 .I ee_errno
 178 contains the
 179 .I errno
 180 number of the queued error.
 181 .I ee_origin
 182 is the origin code of where the error originated.
 183 The other fields are protocol-specific.
 184 The macro
 185 .B SOCK_EE_OFFENDER
 186 returns a pointer to the address of the network object
 187 where the error originated from given a pointer to the ancillary message.
 188 If this address is not known, the
 189 .I sa_family
 190 member of the
 191 .I sockaddr
 192 contains
 193 .B AF_UNSPEC
 194 and the other fields of the
 195 .I sockaddr
 196 are undefined.
 197 The payload of the packet that caused the error is passed as normal data.
 198 .IP
 199 For local errors, no address is passed (this
 200 can be checked with the
 201 .I cmsg_len
 202 member of the
 203 .IR cmsghdr ).
 204 For error receives,
 205 the
 206 .B MSG_ERRQUEUE
 207 is set in the
 208 .IR msghdr .
 209 After an error has been passed, the pending socket error
 210 is regenerated based on the next queued error and will be passed
 211 on the next socket operation.
 212 .TP
 213 .B MSG_OOB
 214 This flag requests receipt of out-of-band data that would not be received
 215 in the normal data stream.
 216 Some protocols place expedited data
 217 at the head of the normal data queue, and thus this flag cannot
 218 be used with such protocols.
 219 .TP
 220 .B MSG_PEEK
 221 This flag causes the receive operation to
 222 return data from the beginning of the
 223 receive queue without removing that data from the queue.
 224 Thus, a
 225 subsequent receive call will return the same data.
 226 .TP
 227 .BR MSG_TRUNC " (since Linux 2.2)"
 228 For raw
 229 .RB ( AF_PACKET ),
 230 Internet datagram (since Linux 2.4.27/2.6.8),
 231 netlink (since Linux 2.6.22), and UNIX datagram (since Linux 3.4) sockets:
 232 return the real length of the packet or datagram,
 233 even when it was longer than the passed buffer.
 234
 235 For use with Internet stream sockets, see
 236 .BR tcp (7).
 237 .TP
 238 .BR MSG_WAITALL " (since Linux 2.2)"
 239 This flag requests that the operation block until the full request is
 240 satisfied.
 241 However, the call may still return less data than requested if
 242 a signal is caught, an error or disconnect occurs, or the next data to be
 243 received is of a different type than that returned.
 244 .\"
 245 .SS recvfrom()
 246 .BR recvfrom ()
 247 places the received message into the buffer
 248 .IR buf .
 249 The caller must specify the size of the buffer in
 250 .IR len .
 251
 252 If
 253 .I src_addr
 254 is not NULL,
 255 and the underlying protocol provides the source address of the message,
 256 that source address is placed in the buffer pointed to by
 257 .IR src_addr .
 258 .\" (Note: for datagram sockets in both the UNIX and Internet domains,
 259 .\" .I src_addr
 260 .\" is filled in.
 261 .\" .I src_addr
 262 .\" is also filled in for stream sockets in the UNIX domain, but is not
 263 .\" filled in for stream sockets in the Internet domain.)
 264 .\" [The above notes on AF_UNIX and AF_INET sockets apply as at
 265 .\" Kernel 2.4.18. (MTK, 22 Jul 02)]
 266 In this case,
 267 .I addrlen
 268 is a value-result argument.
 269 Before the call,
 270 it should be initialized to the size of the buffer associated with
 271 .IR src_addr .
 272 Upon return,
 273 .I addrlen
 274 is updated to contain the actual size of the source address.
 275 The returned address is truncated if the buffer provided is too small;
 276 in this case,
 277 .I addrlen
 278 will return a value greater than was supplied to the call.
 279
 280 If the caller is not interested in the source address,
 281 .I src_addr
 282 should be specified as NULL and
 283 .I addrlen
 284 should be specified as 0.
 285 .\"
 286 .SS recv()
 287 The
 288 .BR recv ()
 289 call is normally used only on a
 290 .I connected
 291 socket (see
 292 .BR connect (2)).
 293 It is equivalent to the call:
 294
 295     recvfrom(fd, buf, len, flags, NULL, 0));
 296 .\"
 297 .SS recvmsg()
 298 The
 299 .BR recvmsg ()
 300 call uses a
 301 .I msghdr
 302 structure to minimize the number of directly supplied arguments.
 303 This structure is defined as follows in
 304 .IR <sys/socket.h> :
 305 .in +4n
 306 .nf
 307
 308 struct iovec {                    /* Scatter/gather array items */
 309     void  *iov_base;              /* Starting address */
 310     size_t iov_len;               /* Number of bytes to transfer */
 311 };
 312
 313 struct msghdr {
 314     void         *msg_name;       /* optional address */
 315     socklen_t     msg_namelen;    /* size of address */
 316     struct iovec *msg_iov;        /* scatter/gather array */
 317     size_t        msg_iovlen;     /* # elements in msg_iov */
 318     void         *msg_control;    /* ancillary data, see below */
 319     size_t        msg_controllen; /* ancillary data buffer len */
 320     int           msg_flags;      /* flags on received message */
 321 };
 322 .fi
 323 .in
 324 .PP
 325 Here
 326 .I msg_name
 327 and
 328 .I msg_namelen
 329 specify the source address if the socket is unconnected;
 330 .I msg_name
 331 may be given as a null pointer if no names are desired or required.
 332 The fields
 333 .I msg_iov
 334 and
 335 .I msg_iovlen
 336 describe scatter-gather locations, as discussed in
 337 .BR readv (2).
 338 The field
 339 .IR msg_control ,
 340 which has length
 341 .IR msg_controllen ,
 342 points to a buffer for other protocol control-related messages or
 343 miscellaneous ancillary data.
 344 When
 345 .BR recvmsg ()
 346 is called,
 347 .I msg_controllen
 348 should contain the length of the available buffer in
 349 .IR msg_control ;
 350 upon return from a successful call it will contain the length
 351 of the control message sequence.
 352 .PP
 353 The messages are of the form:
 354 .in +4n
 355 .nf
 356
 357 struct cmsghdr {
 358     socklen_t     cmsg_len;     /* data byte count, including hdr */
 359     int           cmsg_level;   /* originating protocol */
 360     int           cmsg_type;    /* protocol-specific type */
 361 /* followed by
 362     unsigned char cmsg_data[]; */
 363 };
 364 .fi
 365 .in
 366 .PP
 367 Ancillary data should be accessed only by the macros defined in
 368 .BR cmsg (3).
 369 .PP
 370 As an example, Linux uses this ancillary data mechanism to pass extended
 371 errors, IP options, or file descriptors over UNIX domain sockets.
 372 .PP
 373 The
 374 .I msg_flags
 375 field in the
 376 .I msghdr
 377 is set on return of
 378 .BR recvmsg ().
 379 It can contain several flags:
 380 .TP
 381 .B MSG_EOR
 382 indicates end-of-record; the data returned completed a record (generally
 383 used with sockets of type
 384 .BR SOCK_SEQPACKET ).
 385 .TP
 386 .B MSG_TRUNC
 387 indicates that the trailing portion of a datagram was discarded because the
 388 datagram was larger than the buffer supplied.
 389 .TP
 390 .B MSG_CTRUNC
 391 indicates that some control data were discarded due to lack of space in the
 392 buffer for ancillary data.
 393 .TP
 394 .B MSG_OOB
 395 is returned to indicate that expedited or out-of-band data were received.
 396 .TP
 397 .B MSG_ERRQUEUE
 398 indicates that no data was received but an extended error from the socket
 399 error queue.
 400 .SH RETURN VALUE
 401 These calls return the number of bytes received, or \-1
 402 if an error occurred.
 403 In the event of an error,
 404 .I errno
 405 is set to indicate the error.
 406
 407 When a stream socket peer has performed an orderly shutdown,
 408 the return value will be 0 (the traditional "end-of-file" return).
 409
 410 Datagram sockets in various domains (e.g., the UNIX and Internet domains)
 411 permit zero-length datagrams.
 412 When such a datagram is received, the return value is 0.
 413
 414 The value 0 may also be returned if the requested number of bytes
 415 to receive from a stream socket was 0.
 416 .SH ERRORS
 417 These are some standard errors generated by the socket layer.
 418 Additional errors
 419 may be generated and returned from the underlying protocol modules;
 420 see their manual pages.
 421 .TP
 422 .BR EAGAIN " or " EWOULDBLOCK
 423 .\" Actually EAGAIN on Linux
 424 The socket is marked nonblocking and the receive operation
 425 would block, or a receive timeout had been set and the timeout expired
 426 before data was received.
 427 POSIX.1-2001 allows either error to be returned for this case,
 428 and does not require these constants to have the same value,
 429 so a portable application should check for both possibilities.
 430 .TP
 431 .B EBADF
 432 The argument
 433 .I sockfd
 434 is an invalid descriptor.
 435 .TP
 436 .B ECONNREFUSED
 437 A remote host refused to allow the network connection (typically
 438 because it is not running the requested service).
 439 .TP
 440 .B EFAULT
 441 The receive buffer pointer(s) point outside the process's
 442 address space.
 443 .TP
 444 .B EINTR
 445 The receive was interrupted by delivery of a signal before
 446 any data were available; see
 447 .BR signal (7).
 448 .TP
 449 .B EINVAL
 450 Invalid argument passed.
 451 .\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom()
 452 .TP
 453 .B ENOMEM
 454 Could not allocate memory for
 455 .BR recvmsg ().
 456 .TP
 457 .B ENOTCONN
 458 The socket is associated with a connection-oriented protocol
 459 and has not been connected (see
 460 .BR connect (2)
 461 and
 462 .BR accept (2)).
 463 .TP
 464 .B ENOTSOCK
 465 The argument
 466 .I sockfd
 467 does not refer to a socket.
 468 .SH CONFORMING TO
 469 4.4BSD (these function calls first appeared in 4.2BSD),
 470 POSIX.1-2001.
 471 .LP
 472 POSIX.1-2001 describes only the
 473 .BR MSG_OOB ,
 474 .BR MSG_PEEK ,
 475 and
 476 .B MSG_WAITALL
 477 flags.
 478 .SH NOTES
 479 The prototypes given above follow glibc2.
 480 The Single UNIX Specification agrees, except that it has return values
 481 of type \fIssize_t\fP (while 4.x BSD and libc4 and libc5 all have \fIint\fP).
 482 The
 483 .I flags
 484 argument is \fIint\fP in 4.x BSD, but \fIunsigned int\fP in libc4 and libc5.
 485 The
 486 .I len
 487 argument is \fIint\fP in 4.x BSD, but \fIsize_t\fP in libc4 and libc5.
 488 The
 489 .I addrlen
 490 argument is \fIint\ *\fP in 4.x BSD, libc4 and libc5.
 491 The present  \fIsocklen_t\ *\fP was invented by POSIX.
 492 See also
 493 .BR accept (2).
 494
 495 According to POSIX.1-2001, the
 496 .I msg_controllen
 497 field of the
 498 .I msghdr
 499 structure should be typed as
 500 .IR socklen_t ,
 501 but glibc currently types it as
 502 .IR size_t .
 503 .\" glibc bug raised 12 Mar 2006
 504 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 505 .\" The problem is an underlying kernel issue: the size of the
 506 .\" __kernel_size_t type used to type this field varies
 507 .\" across architectures, but socklen_t is always 32 bits.
 508
 509 See
 510 .BR recvmmsg (2)
 511 for information about a Linux-specific system call
 512 that can be used to receive multiple datagrams in a single call.
 513 .SH EXAMPLE
 514 An example of the use of
 515 .BR recvfrom ()
 516 is shown in
 517 .BR getaddrinfo (3).
 518 .SH SEE ALSO
 519 .BR fcntl (2),
 520 .BR getsockopt (2),
 521 .BR read (2),
 522 .BR recvmmsg (2),
 523 .BR select (2),
 524 .BR shutdown (2),
 525 .BR socket (2),
 526 .BR cmsg (3),
 527 .BR sockatmark (3),
 528 .BR socket (7)
 529 .SH COLOPHON
 530 This page is part of release 3.65 of the Linux
 531 .I man-pages
 532 project.
 533 A description of the project,
 534 and information about reporting bugs,
 535 can be found at
 536 \%http://www.kernel.org/doc/man\-pages/.