man2/recv.2

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