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-05-10 "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 use
  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 The
 326 .I msg_name
 327 field points to a caller-allocated buffer that is used to
 328 return the source address if the socket is unconnected.
 329 The caller should set
 330 .I msg_namelen
 331 to the size of this buffer before this call;
 332 upon return from a successful call,
 333 .I msg_name
 334 will contain the length of the returned address.
 335 If the application does not need to know the source address,
 336 .I msg_name
 337 can be specified as NULL.
 338
 339 The fields
 340 .I msg_iov
 341 and
 342 .I msg_iovlen
 343 describe scatter-gather locations, as discussed in
 344 .BR readv (2).
 345
 346 The field
 347 .IR msg_control ,
 348 which has length
 349 .IR msg_controllen ,
 350 points to a buffer for other protocol control-related messages or
 351 miscellaneous ancillary data.
 352 When
 353 .BR recvmsg ()
 354 is called,
 355 .I msg_controllen
 356 should contain the length of the available buffer in
 357 .IR msg_control ;
 358 upon return from a successful call it will contain the length
 359 of the control message sequence.
 360 .PP
 361 The messages are of the form:
 362 .in +4n
 363 .nf
 364
 365 struct cmsghdr {
 366     socklen_t     cmsg_len;     /* data byte count, including hdr */
 367     int           cmsg_level;   /* originating protocol */
 368     int           cmsg_type;    /* protocol-specific type */
 369 /* followed by
 370     unsigned char cmsg_data[]; */
 371 };
 372 .fi
 373 .in
 374 .PP
 375 Ancillary data should be accessed only by the macros defined in
 376 .BR cmsg (3).
 377 .PP
 378 As an example, Linux uses this ancillary data mechanism to pass extended
 379 errors, IP options, or file descriptors over UNIX domain sockets.
 380 .PP
 381 The
 382 .I msg_flags
 383 field in the
 384 .I msghdr
 385 is set on return of
 386 .BR recvmsg ().
 387 It can contain several flags:
 388 .TP
 389 .B MSG_EOR
 390 indicates end-of-record; the data returned completed a record (generally
 391 used with sockets of type
 392 .BR SOCK_SEQPACKET ).
 393 .TP
 394 .B MSG_TRUNC
 395 indicates that the trailing portion of a datagram was discarded because the
 396 datagram was larger than the buffer supplied.
 397 .TP
 398 .B MSG_CTRUNC
 399 indicates that some control data were discarded due to lack of space in the
 400 buffer for ancillary data.
 401 .TP
 402 .B MSG_OOB
 403 is returned to indicate that expedited or out-of-band data were received.
 404 .TP
 405 .B MSG_ERRQUEUE
 406 indicates that no data was received but an extended error from the socket
 407 error queue.
 408 .SH RETURN VALUE
 409 These calls return the number of bytes received, or \-1
 410 if an error occurred.
 411 In the event of an error,
 412 .I errno
 413 is set to indicate the error.
 414
 415 When a stream socket peer has performed an orderly shutdown,
 416 the return value will be 0 (the traditional "end-of-file" return).
 417
 418 Datagram sockets in various domains (e.g., the UNIX and Internet domains)
 419 permit zero-length datagrams.
 420 When such a datagram is received, the return value is 0.
 421
 422 The value 0 may also be returned if the requested number of bytes
 423 to receive from a stream socket was 0.
 424 .SH ERRORS
 425 These are some standard errors generated by the socket layer.
 426 Additional errors
 427 may be generated and returned from the underlying protocol modules;
 428 see their manual pages.
 429 .TP
 430 .BR EAGAIN " or " EWOULDBLOCK
 431 .\" Actually EAGAIN on Linux
 432 The socket is marked nonblocking and the receive operation
 433 would block, or a receive timeout had been set and the timeout expired
 434 before data was received.
 435 POSIX.1-2001 allows either error to be returned for this case,
 436 and does not require these constants to have the same value,
 437 so a portable application should check for both possibilities.
 438 .TP
 439 .B EBADF
 440 The argument
 441 .I sockfd
 442 is an invalid descriptor.
 443 .TP
 444 .B ECONNREFUSED
 445 A remote host refused to allow the network connection (typically
 446 because it is not running the requested service).
 447 .TP
 448 .B EFAULT
 449 The receive buffer pointer(s) point outside the process's
 450 address space.
 451 .TP
 452 .B EINTR
 453 The receive was interrupted by delivery of a signal before
 454 any data were available; see
 455 .BR signal (7).
 456 .TP
 457 .B EINVAL
 458 Invalid argument passed.
 459 .\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom()
 460 .TP
 461 .B ENOMEM
 462 Could not allocate memory for
 463 .BR recvmsg ().
 464 .TP
 465 .B ENOTCONN
 466 The socket is associated with a connection-oriented protocol
 467 and has not been connected (see
 468 .BR connect (2)
 469 and
 470 .BR accept (2)).
 471 .TP
 472 .B ENOTSOCK
 473 The argument
 474 .I sockfd
 475 does not refer to a socket.
 476 .SH CONFORMING TO
 477 4.4BSD (these function calls first appeared in 4.2BSD),
 478 POSIX.1-2001.
 479 .LP
 480 POSIX.1-2001 describes only the
 481 .BR MSG_OOB ,
 482 .BR MSG_PEEK ,
 483 and
 484 .B MSG_WAITALL
 485 flags.
 486 .SH NOTES
 487 The prototypes given above follow glibc2.
 488 The Single UNIX Specification agrees, except that it has return values
 489 of type \fIssize_t\fP (while 4.x BSD and libc4 and libc5 all have \fIint\fP).
 490 The
 491 .I flags
 492 argument is \fIint\fP in 4.x BSD, but \fIunsigned int\fP in libc4 and libc5.
 493 The
 494 .I len
 495 argument is \fIint\fP in 4.x BSD, but \fIsize_t\fP in libc4 and libc5.
 496 The
 497 .I addrlen
 498 argument is \fIint\ *\fP in 4.x BSD, libc4 and libc5.
 499 The present  \fIsocklen_t\ *\fP was invented by POSIX.
 500 See also
 501 .BR accept (2).
 502
 503 According to POSIX.1-2001, the
 504 .I msg_controllen
 505 field of the
 506 .I msghdr
 507 structure should be typed as
 508 .IR socklen_t ,
 509 but glibc currently types it as
 510 .IR size_t .
 511 .\" glibc bug raised 12 Mar 2006
 512 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 513 .\" The problem is an underlying kernel issue: the size of the
 514 .\" __kernel_size_t type used to type this field varies
 515 .\" across architectures, but socklen_t is always 32 bits.
 516
 517 See
 518 .BR recvmmsg (2)
 519 for information about a Linux-specific system call
 520 that can be used to receive multiple datagrams in a single call.
 521 .SH EXAMPLE
 522 An example of the use of
 523 .BR recvfrom ()
 524 is shown in
 525 .BR getaddrinfo (3).
 526 .SH SEE ALSO
 527 .BR fcntl (2),
 528 .BR getsockopt (2),
 529 .BR read (2),
 530 .BR recvmmsg (2),
 531 .BR select (2),
 532 .BR shutdown (2),
 533 .BR socket (2),
 534 .BR cmsg (3),
 535 .BR sockatmark (3),
 536 .BR socket (7)
 537 .SH COLOPHON
 538 This page is part of release 3.68 of the Linux
 539 .I man-pages
 540 project.
 541 A description of the project,
 542 information about reporting bugs,
 543 and the latest version of this page,
 544 can be found at
 545 \%http://www.kernel.org/doc/man\-pages/.