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 2017-09-15 "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 .PP
  52 .BI "ssize_t recv(int " sockfd ", void *" buf ", size_t " len ", int " flags );
  53 .PP
  54 .BI "ssize_t recvfrom(int " sockfd ", void *" buf ", size_t " len ", int " flags ,
  55 .BI "                 struct sockaddr *" src_addr ", socklen_t *" addrlen );
  56 .PP
  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 The only difference between
  72 .BR recv ()
  73 and
  74 .BR read (2)
  75 is the presence of
  76 .IR flags .
  77 With a zero
  78 .I flags
  79 argument,
  80 .BR recv ()
  81 is generally equivalent to
  82 .BR read (2)
  83 (but see NOTES).
  84 Also, the following call
  85 .PP
  86     recv(sockfd, buf, len, flags);
  87 .PP
  88 is equivalent to
  89 .PP
  90     recvfrom(sockfd, buf, len, flags, NULL, NULL);
  91 .PP
  92 All three calls return the length of the message on successful
  93 completion.
  94 If a message is too long to fit in the supplied buffer, excess
  95 bytes may be discarded depending on the type of socket the message is
  96 received from.
  97 .PP
  98 If no messages are available at the socket, the receive calls wait for a
  99 message to arrive, unless the socket is nonblocking (see
 100 .BR fcntl (2)),
 101 in which case the value \-1 is returned and the external variable
 102 .I errno
 103 is set to
 104 .BR EAGAIN " or " EWOULDBLOCK .
 105 The receive calls normally return any data available, up to the requested
 106 amount, rather than waiting for receipt of the full amount requested.
 107 .PP
 108 An application can use
 109 .BR select (2),
 110 .BR poll (2),
 111 or
 112 .BR epoll (7)
 113 to determine when more data arrives on a socket.
 114 .SS The flags argument
 115 The
 116 .I flags
 117 argument is formed by ORing one or more of the following values:
 118 .TP
 119 .BR MSG_CMSG_CLOEXEC " (" recvmsg "() only; since Linux 2.6.23)"
 120 Set the close-on-exec flag for the file descriptor received
 121 via a UNIX domain file descriptor using the
 122 .B SCM_RIGHTS
 123 operation (described in
 124 .BR unix (7)).
 125 This flag is useful for the same reasons as the
 126 .B O_CLOEXEC
 127 flag of
 128 .BR open (2).
 129 .TP
 130 .BR MSG_DONTWAIT " (since Linux 2.2)"
 131 Enables nonblocking operation; if the operation would block,
 132 the call fails with the error
 133 .BR EAGAIN " or " EWOULDBLOCK .
 134 This provides similar behavior to setting the
 135 .B O_NONBLOCK
 136 flag (via the
 137 .BR fcntl (2)
 138 .B F_SETFL
 139 operation), but differs in that
 140 .B MSG_DONTWAIT
 141 is a per-call option, whereas
 142 .B O_NONBLOCK
 143 is a setting on the open file description (see
 144 .BR open (2)),
 145 which will affect all threads in the calling process
 146 and as well as other processes that hold file descriptors
 147 referring to the same open file description.
 148 .TP
 149 .BR MSG_ERRQUEUE " (since Linux 2.2)"
 150 This flag
 151 specifies that queued errors should be received from the socket error queue.
 152 The error is passed in
 153 an ancillary message with a type dependent on the protocol (for IPv4
 154 .BR IP_RECVERR ).
 155 The user should supply a buffer of sufficient size.
 156 See
 157 .BR cmsg (3)
 158 and
 159 .BR ip (7)
 160 for more information.
 161 The payload of the original packet that caused the error
 162 is passed as normal data via
 163 .IR msg_iovec .
 164 The original destination address of the datagram that caused the error
 165 is supplied via
 166 .IR msg_name .
 167 .IP
 168 The error is supplied in a
 169 .I sock_extended_err
 170 structure:
 171 .IP
 172 .in +4n
 173 .EX
 174 #define SO_EE_ORIGIN_NONE    0
 175 #define SO_EE_ORIGIN_LOCAL   1
 176 #define SO_EE_ORIGIN_ICMP    2
 177 #define SO_EE_ORIGIN_ICMP6   3
 178
 179 struct sock_extended_err
 180 {
 181     uint32_t ee_errno;   /* Error number */
 182     uint8_t  ee_origin;  /* Where the error originated */
 183     uint8_t  ee_type;    /* Type */
 184     uint8_t  ee_code;    /* Code */
 185     uint8_t  ee_pad;     /* Padding */
 186     uint32_t ee_info;    /* Additional information */
 187     uint32_t ee_data;    /* Other data */
 188     /* More data may follow */
 189 };
 190
 191 struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
 192 .EE
 193 .in
 194 .IP
 195 .I ee_errno
 196 contains the
 197 .I errno
 198 number of the queued error.
 199 .I ee_origin
 200 is the origin code of where the error originated.
 201 The other fields are protocol-specific.
 202 The macro
 203 .B SOCK_EE_OFFENDER
 204 returns a pointer to the address of the network object
 205 where the error originated from given a pointer to the ancillary message.
 206 If this address is not known, the
 207 .I sa_family
 208 member of the
 209 .I sockaddr
 210 contains
 211 .B AF_UNSPEC
 212 and the other fields of the
 213 .I sockaddr
 214 are undefined.
 215 The payload of the packet that caused the error is passed as normal data.
 216 .IP
 217 For local errors, no address is passed (this
 218 can be checked with the
 219 .I cmsg_len
 220 member of the
 221 .IR cmsghdr ).
 222 For error receives,
 223 the
 224 .B MSG_ERRQUEUE
 225 flag is set in the
 226 .IR msghdr .
 227 After an error has been passed, the pending socket error
 228 is regenerated based on the next queued error and will be passed
 229 on the next socket operation.
 230 .TP
 231 .B MSG_OOB
 232 This flag requests receipt of out-of-band data that would not be received
 233 in the normal data stream.
 234 Some protocols place expedited data
 235 at the head of the normal data queue, and thus this flag cannot
 236 be used with such protocols.
 237 .TP
 238 .B MSG_PEEK
 239 This flag causes the receive operation to
 240 return data from the beginning of the
 241 receive queue without removing that data from the queue.
 242 Thus, a
 243 subsequent receive call will return the same data.
 244 .TP
 245 .BR MSG_TRUNC " (since Linux 2.2)"
 246 For raw
 247 .RB ( AF_PACKET ),
 248 Internet datagram (since Linux 2.4.27/2.6.8),
 249 netlink (since Linux 2.6.22), and UNIX datagram
 250 .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
 251 (since Linux 3.4) sockets:
 252 return the real length of the packet or datagram,
 253 even when it was longer than the passed buffer.
 254 .IP
 255 For use with Internet stream sockets, see
 256 .BR tcp (7).
 257 .TP
 258 .BR MSG_WAITALL " (since Linux 2.2)"
 259 This flag requests that the operation block until the full request is
 260 satisfied.
 261 However, the call may still return less data than requested if
 262 a signal is caught, an error or disconnect occurs, or the next data to be
 263 received is of a different type than that returned.
 264 This flag has no effect for datagram sockets.
 265 .\"
 266 .SS recvfrom()
 267 .BR recvfrom ()
 268 places the received message into the buffer
 269 .IR buf .
 270 The caller must specify the size of the buffer in
 271 .IR len .
 272 .PP
 273 If
 274 .I src_addr
 275 is not NULL,
 276 and the underlying protocol provides the source address of the message,
 277 that source address is placed in the buffer pointed to by
 278 .IR src_addr .
 279 .\" (Note: for datagram sockets in both the UNIX and Internet domains,
 280 .\" .I src_addr
 281 .\" is filled in.
 282 .\" .I src_addr
 283 .\" is also filled in for stream sockets in the UNIX domain, but is not
 284 .\" filled in for stream sockets in the Internet domain.)
 285 .\" [The above notes on AF_UNIX and AF_INET sockets apply as at
 286 .\" Kernel 2.4.18. (MTK, 22 Jul 02)]
 287 In this case,
 288 .I addrlen
 289 is a value-result argument.
 290 Before the call,
 291 it should be initialized to the size of the buffer associated with
 292 .IR src_addr .
 293 Upon return,
 294 .I addrlen
 295 is updated to contain the actual size of the source address.
 296 The returned address is truncated if the buffer provided is too small;
 297 in this case,
 298 .I addrlen
 299 will return a value greater than was supplied to the call.
 300 .PP
 301 If the caller is not interested in the source address,
 302 .I src_addr
 303 and
 304 .I addrlen
 305 should be specified as NULL.
 306 .\"
 307 .SS recv()
 308 The
 309 .BR recv ()
 310 call is normally used only on a
 311 .I connected
 312 socket (see
 313 .BR connect (2)).
 314 It is equivalent to the call:
 315 .PP
 316     recvfrom(fd, buf, len, flags, NULL, 0);
 317 .\"
 318 .SS recvmsg()
 319 The
 320 .BR recvmsg ()
 321 call uses a
 322 .I msghdr
 323 structure to minimize the number of directly supplied arguments.
 324 This structure is defined as follows in
 325 .IR <sys/socket.h> :
 326 .PP
 327 .in +4n
 328 .EX
 329 struct iovec {                    /* Scatter/gather array items */
 330     void  *iov_base;              /* Starting address */
 331     size_t iov_len;               /* Number of bytes to transfer */
 332 };
 333
 334 struct msghdr {
 335     void         *msg_name;       /* Optional address */
 336     socklen_t     msg_namelen;    /* Size of address */
 337     struct iovec *msg_iov;        /* Scatter/gather array */
 338     size_t        msg_iovlen;     /* # elements in msg_iov */
 339     void         *msg_control;    /* Ancillary data, see below */
 340     size_t        msg_controllen; /* Ancillary data buffer len */
 341     int           msg_flags;      /* Flags on received message */
 342 };
 343 .EE
 344 .in
 345 .PP
 346 The
 347 .I msg_name
 348 field points to a caller-allocated buffer that is used to
 349 return the source address if the socket is unconnected.
 350 The caller should set
 351 .I msg_namelen
 352 to the size of this buffer before this call;
 353 upon return from a successful call,
 354 .I msg_namelen
 355 will contain the length of the returned address.
 356 If the application does not need to know the source address,
 357 .I msg_name
 358 can be specified as NULL.
 359 .PP
 360 The fields
 361 .I msg_iov
 362 and
 363 .I msg_iovlen
 364 describe scatter-gather locations, as discussed in
 365 .BR readv (2).
 366 .PP
 367 The field
 368 .IR msg_control ,
 369 which has length
 370 .IR msg_controllen ,
 371 points to a buffer for other protocol control-related messages or
 372 miscellaneous ancillary data.
 373 When
 374 .BR recvmsg ()
 375 is called,
 376 .I msg_controllen
 377 should contain the length of the available buffer in
 378 .IR msg_control ;
 379 upon return from a successful call it will contain the length
 380 of the control message sequence.
 381 .PP
 382 The messages are of the form:
 383 .PP
 384 .in +4n
 385 .EX
 386 struct cmsghdr {
 387     size_t cmsg_len;    /* Data byte count, including header
 388                            (type is socklen_t in POSIX) */
 389     int    cmsg_level;  /* Originating protocol */
 390     int    cmsg_type;   /* Protocol-specific type */
 391 /* followed by
 392     unsigned char cmsg_data[]; */
 393 };
 394 .EE
 395 .in
 396 .PP
 397 Ancillary data should be accessed only by the macros defined in
 398 .BR cmsg (3).
 399 .PP
 400 As an example, Linux uses this ancillary data mechanism to pass extended
 401 errors, IP options, or file descriptors over UNIX domain sockets.
 402 .PP
 403 The
 404 .I msg_flags
 405 field in the
 406 .I msghdr
 407 is set on return of
 408 .BR recvmsg ().
 409 It can contain several flags:
 410 .TP
 411 .B MSG_EOR
 412 indicates end-of-record; the data returned completed a record (generally
 413 used with sockets of type
 414 .BR SOCK_SEQPACKET ).
 415 .TP
 416 .B MSG_TRUNC
 417 indicates that the trailing portion of a datagram was discarded because the
 418 datagram was larger than the buffer supplied.
 419 .TP
 420 .B MSG_CTRUNC
 421 indicates that some control data was discarded due to lack of space in the
 422 buffer for ancillary data.
 423 .TP
 424 .B MSG_OOB
 425 is returned to indicate that expedited or out-of-band data was received.
 426 .TP
 427 .B MSG_ERRQUEUE
 428 indicates that no data was received but an extended error from the socket
 429 error queue.
 430 .SH RETURN VALUE
 431 These calls return the number of bytes received, or \-1
 432 if an error occurred.
 433 In the event of an error,
 434 .I errno
 435 is set to indicate the error.
 436 .PP
 437 When a stream socket peer has performed an orderly shutdown,
 438 the return value will be 0 (the traditional "end-of-file" return).
 439 .PP
 440 Datagram sockets in various domains (e.g., the UNIX and Internet domains)
 441 permit zero-length datagrams.
 442 When such a datagram is received, the return value is 0.
 443 .PP
 444 The value 0 may also be returned if the requested number of bytes
 445 to receive from a stream socket was 0.
 446 .SH ERRORS
 447 These are some standard errors generated by the socket layer.
 448 Additional errors
 449 may be generated and returned from the underlying protocol modules;
 450 see their manual pages.
 451 .TP
 452 .BR EAGAIN " or " EWOULDBLOCK
 453 .\" Actually EAGAIN on Linux
 454 The socket is marked nonblocking and the receive operation
 455 would block, or a receive timeout had been set and the timeout expired
 456 before data was received.
 457 POSIX.1 allows either error to be returned for this case,
 458 and does not require these constants to have the same value,
 459 so a portable application should check for both possibilities.
 460 .TP
 461 .B EBADF
 462 The argument
 463 .I sockfd
 464 is an invalid file descriptor.
 465 .TP
 466 .B ECONNREFUSED
 467 A remote host refused to allow the network connection (typically
 468 because it is not running the requested service).
 469 .TP
 470 .B EFAULT
 471 The receive buffer pointer(s) point outside the process's
 472 address space.
 473 .TP
 474 .B EINTR
 475 The receive was interrupted by delivery of a signal before
 476 any data was available; see
 477 .BR signal (7).
 478 .TP
 479 .B EINVAL
 480 Invalid argument passed.
 481 .\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom()
 482 .TP
 483 .B ENOMEM
 484 Could not allocate memory for
 485 .BR recvmsg ().
 486 .TP
 487 .B ENOTCONN
 488 The socket is associated with a connection-oriented protocol
 489 and has not been connected (see
 490 .BR connect (2)
 491 and
 492 .BR accept (2)).
 493 .TP
 494 .B ENOTSOCK
 495 The file descriptor
 496 .I sockfd
 497 does not refer to a socket.
 498 .SH CONFORMING TO
 499 POSIX.1-2001, POSIX.1-2008,
 500 4.4BSD (these interfaces first appeared in 4.2BSD).
 501 .PP
 502 POSIX.1 describes only the
 503 .BR MSG_OOB ,
 504 .BR MSG_PEEK ,
 505 and
 506 .B MSG_WAITALL
 507 flags.
 508 .SH NOTES
 509 If a zero-length datagram is pending,
 510 .BR read (2)
 511 and
 512 .BR recv ()
 513 with a
 514 .I flags
 515 argument of zero provide different behavior.
 516 In this circumstance,
 517 .BR read (2)
 518 has no effect (the datagram remains pending), while
 519 .BR recv ()
 520 consumes the pending datagram.
 521 .PP
 522 The
 523 .I socklen_t
 524 type was invented by POSIX.
 525 See also
 526 .BR accept (2).
 527 .PP
 528 According to POSIX.1,
 529 .\" POSIX.1-2001, POSIX.1-2008
 530 the
 531 .I msg_controllen
 532 field of the
 533 .I msghdr
 534 structure should be typed as
 535 .IR socklen_t ,
 536 but glibc currently types it as
 537 .IR size_t .
 538 .\" glibc bug raised 12 Mar 2006
 539 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
 540 .\" The problem is an underlying kernel issue: the size of the
 541 .\" __kernel_size_t type used to type this field varies
 542 .\" across architectures, but socklen_t is always 32 bits.
 543 .PP
 544 See
 545 .BR recvmmsg (2)
 546 for information about a Linux-specific system call
 547 that can be used to receive multiple datagrams in a single call.
 548 .SH EXAMPLE
 549 An example of the use of
 550 .BR recvfrom ()
 551 is shown in
 552 .BR getaddrinfo (3).
 553 .SH SEE ALSO
 554 .BR fcntl (2),
 555 .BR getsockopt (2),
 556 .BR read (2),
 557 .BR recvmmsg (2),
 558 .BR select (2),
 559 .BR shutdown (2),
 560 .BR socket (2),
 561 .BR cmsg (3),
 562 .BR sockatmark (3),
 563 .BR ip (7),
 564 .BR ipv6 (7),
 565 .BR socket (7),
 566 .BR tcp (7),
 567 .BR udp (7),
 568 .BR unix (7)