| .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $ |
| .\" |
| .\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 1998,1999 by Andi Kleen |
| .\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin |
| .\" |
| .TH RECV 2 2016-03-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| recv, recvfrom, recvmsg \- receive a message from a socket |
| .SH SYNOPSIS |
| .\" .B #include <sys/uio.h> |
| .\" .br |
| .nf |
| .B #include <sys/types.h> |
| .br |
| .B #include <sys/socket.h> |
| .sp |
| .BI "ssize_t recv(int " sockfd ", void *" buf ", size_t " len ", int " flags ); |
| .sp |
| .BI "ssize_t recvfrom(int " sockfd ", void *" buf ", size_t " len ", int " flags , |
| .BI " struct sockaddr *" src_addr ", socklen_t *" addrlen ); |
| .sp |
| .BI "ssize_t recvmsg(int " sockfd ", struct msghdr *" msg ", int " flags ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR recv (), |
| .BR recvfrom (), |
| and |
| .BR recvmsg () |
| calls are used to receive messages from a socket. |
| They may be used |
| to receive data on both connectionless and connection-oriented sockets. |
| This page first describes common features of all three system calls, |
| and then describes the differences between the calls. |
| .PP |
| The only difference between |
| .BR recv () |
| and |
| .BR read (2) |
| is the presence of |
| .IR flags . |
| With a zero |
| .I flags |
| argument, |
| .BR recv () |
| is equivalent to |
| .BR read (2). |
| Also, the following call |
| |
| recv(sockfd, buf, len, flags); |
| |
| is equivalent to |
| |
| recvfrom(sockfd, buf, len, flags, NULL, NULL); |
| .PP |
| All three calls return the length of the message on successful |
| completion. |
| If a message is too long to fit in the supplied buffer, excess |
| bytes may be discarded depending on the type of socket the message is |
| received from. |
| .PP |
| If no messages are available at the socket, the receive calls wait for a |
| message to arrive, unless the socket is nonblocking (see |
| .BR fcntl (2)), |
| in which case the value \-1 is returned and the external variable |
| .I errno |
| is set to |
| .BR EAGAIN " or " EWOULDBLOCK . |
| The receive calls normally return any data available, up to the requested |
| amount, rather than waiting for receipt of the full amount requested. |
| .PP |
| An application can use |
| .BR select (2), |
| .BR poll (2), |
| or |
| .BR epoll (7) |
| to determine when more data arrives on a socket. |
| .SS The flags argument |
| The |
| .I flags |
| argument is formed by ORing one or more of the following values: |
| .TP |
| .BR MSG_CMSG_CLOEXEC " (" recvmsg "() only; since Linux 2.6.23)" |
| Set the close-on-exec flag for the file descriptor received |
| via a UNIX domain file descriptor using the |
| .B SCM_RIGHTS |
| operation (described in |
| .BR unix (7)). |
| This flag is useful for the same reasons as the |
| .B O_CLOEXEC |
| flag of |
| .BR open (2). |
| .TP |
| .BR MSG_DONTWAIT " (since Linux 2.2)" |
| Enables nonblocking operation; if the operation would block, |
| the call fails with the error |
| .BR EAGAIN " or " EWOULDBLOCK . |
| This provides similar behavior to setting the |
| .B O_NONBLOCK |
| flag (via the |
| .BR fcntl (2) |
| .B F_SETFL |
| operation), but differs in that |
| .B MSG_DONTWAIT |
| is a per-call option, whereas |
| .B O_NONBLOCK |
| is a setting on the open file description (see |
| .BR open (2)), |
| which will affect all threads in the calling process |
| and as well as other processes that hold file descriptors |
| referring to the same open file description. |
| .TP |
| .BR MSG_ERRQUEUE " (since Linux 2.2)" |
| This flag |
| specifies that queued errors should be received from the socket error queue. |
| The error is passed in |
| an ancillary message with a type dependent on the protocol (for IPv4 |
| .BR IP_RECVERR ). |
| The user should supply a buffer of sufficient size. |
| See |
| .BR cmsg (3) |
| and |
| .BR ip (7) |
| for more information. |
| The payload of the original packet that caused the error |
| is passed as normal data via |
| .IR msg_iovec . |
| The original destination address of the datagram that caused the error |
| is supplied via |
| .IR msg_name . |
| .IP |
| For local errors, no address is passed (this can be checked with the |
| .I cmsg_len |
| member of the |
| .IR cmsghdr ). |
| For error receives, the |
| .B MSG_ERRQUEUE |
| is set in the |
| .IR msghdr . |
| After an error has been passed, the pending socket error |
| is regenerated based on the next queued error and will be passed |
| on the next socket operation. |
| |
| The error is supplied in a |
| .I sock_extended_err |
| structure: |
| .in +4n |
| .nf |
| |
| #define SO_EE_ORIGIN_NONE 0 |
| #define SO_EE_ORIGIN_LOCAL 1 |
| #define SO_EE_ORIGIN_ICMP 2 |
| #define SO_EE_ORIGIN_ICMP6 3 |
| |
| struct sock_extended_err |
| { |
| uint32_t ee_errno; /* error number */ |
| uint8_t ee_origin; /* where the error originated */ |
| uint8_t ee_type; /* type */ |
| uint8_t ee_code; /* code */ |
| uint8_t ee_pad; /* padding */ |
| uint32_t ee_info; /* additional information */ |
| uint32_t ee_data; /* other data */ |
| /* More data may follow */ |
| }; |
| |
| struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); |
| .fi |
| .in |
| .IP |
| .I ee_errno |
| contains the |
| .I errno |
| number of the queued error. |
| .I ee_origin |
| is the origin code of where the error originated. |
| The other fields are protocol-specific. |
| The macro |
| .B SOCK_EE_OFFENDER |
| returns a pointer to the address of the network object |
| where the error originated from given a pointer to the ancillary message. |
| If this address is not known, the |
| .I sa_family |
| member of the |
| .I sockaddr |
| contains |
| .B AF_UNSPEC |
| and the other fields of the |
| .I sockaddr |
| are undefined. |
| The payload of the packet that caused the error is passed as normal data. |
| .IP |
| For local errors, no address is passed (this |
| can be checked with the |
| .I cmsg_len |
| member of the |
| .IR cmsghdr ). |
| For error receives, |
| the |
| .B MSG_ERRQUEUE |
| is set in the |
| .IR msghdr . |
| After an error has been passed, the pending socket error |
| is regenerated based on the next queued error and will be passed |
| on the next socket operation. |
| .TP |
| .B MSG_OOB |
| This flag requests receipt of out-of-band data that would not be received |
| in the normal data stream. |
| Some protocols place expedited data |
| at the head of the normal data queue, and thus this flag cannot |
| be used with such protocols. |
| .TP |
| .B MSG_PEEK |
| This flag causes the receive operation to |
| return data from the beginning of the |
| receive queue without removing that data from the queue. |
| Thus, a |
| subsequent receive call will return the same data. |
| .TP |
| .BR MSG_TRUNC " (since Linux 2.2)" |
| For raw |
| .RB ( AF_PACKET ), |
| Internet datagram (since Linux 2.4.27/2.6.8), |
| netlink (since Linux 2.6.22), and UNIX datagram (since Linux 3.4) sockets: |
| return the real length of the packet or datagram, |
| even when it was longer than the passed buffer. |
| |
| For use with Internet stream sockets, see |
| .BR tcp (7). |
| .TP |
| .BR MSG_WAITALL " (since Linux 2.2)" |
| This flag requests that the operation block until the full request is |
| satisfied. |
| However, the call may still return less data than requested if |
| a signal is caught, an error or disconnect occurs, or the next data to be |
| received is of a different type than that returned. |
| This flag has no effect for datagram sockets. |
| .\" |
| .SS recvfrom() |
| .BR recvfrom () |
| places the received message into the buffer |
| .IR buf . |
| The caller must specify the size of the buffer in |
| .IR len . |
| |
| If |
| .I src_addr |
| is not NULL, |
| and the underlying protocol provides the source address of the message, |
| that source address is placed in the buffer pointed to by |
| .IR src_addr . |
| .\" (Note: for datagram sockets in both the UNIX and Internet domains, |
| .\" .I src_addr |
| .\" is filled in. |
| .\" .I src_addr |
| .\" is also filled in for stream sockets in the UNIX domain, but is not |
| .\" filled in for stream sockets in the Internet domain.) |
| .\" [The above notes on AF_UNIX and AF_INET sockets apply as at |
| .\" Kernel 2.4.18. (MTK, 22 Jul 02)] |
| In this case, |
| .I addrlen |
| is a value-result argument. |
| Before the call, |
| it should be initialized to the size of the buffer associated with |
| .IR src_addr . |
| Upon return, |
| .I addrlen |
| is updated to contain the actual size of the source address. |
| The returned address is truncated if the buffer provided is too small; |
| in this case, |
| .I addrlen |
| will return a value greater than was supplied to the call. |
| |
| If the caller is not interested in the source address, |
| .I src_addr |
| and |
| .I addrlen |
| should be specified as NULL. |
| .\" |
| .SS recv() |
| The |
| .BR recv () |
| call is normally used only on a |
| .I connected |
| socket (see |
| .BR connect (2)). |
| It is equivalent to the call: |
| |
| recvfrom(fd, buf, len, flags, NULL, 0)); |
| .\" |
| .SS recvmsg() |
| The |
| .BR recvmsg () |
| call uses a |
| .I msghdr |
| structure to minimize the number of directly supplied arguments. |
| This structure is defined as follows in |
| .IR <sys/socket.h> : |
| .in +4n |
| .nf |
| |
| struct iovec { /* Scatter/gather array items */ |
| void *iov_base; /* Starting address */ |
| size_t iov_len; /* Number of bytes to transfer */ |
| }; |
| |
| struct msghdr { |
| void *msg_name; /* optional address */ |
| socklen_t msg_namelen; /* size of address */ |
| struct iovec *msg_iov; /* scatter/gather array */ |
| size_t msg_iovlen; /* # elements in msg_iov */ |
| void *msg_control; /* ancillary data, see below */ |
| size_t msg_controllen; /* ancillary data buffer len */ |
| int msg_flags; /* flags on received message */ |
| }; |
| .fi |
| .in |
| .PP |
| The |
| .I msg_name |
| field points to a caller-allocated buffer that is used to |
| return the source address if the socket is unconnected. |
| The caller should set |
| .I msg_namelen |
| to the size of this buffer before this call; |
| upon return from a successful call, |
| .I msg_namelen |
| will contain the length of the returned address. |
| If the application does not need to know the source address, |
| .I msg_name |
| can be specified as NULL. |
| |
| The fields |
| .I msg_iov |
| and |
| .I msg_iovlen |
| describe scatter-gather locations, as discussed in |
| .BR readv (2). |
| |
| The field |
| .IR msg_control , |
| which has length |
| .IR msg_controllen , |
| points to a buffer for other protocol control-related messages or |
| miscellaneous ancillary data. |
| When |
| .BR recvmsg () |
| is called, |
| .I msg_controllen |
| should contain the length of the available buffer in |
| .IR msg_control ; |
| upon return from a successful call it will contain the length |
| of the control message sequence. |
| .PP |
| The messages are of the form: |
| .in +4n |
| .nf |
| |
| struct cmsghdr { |
| size_t cmsg_len; /* Data byte count, including header |
| (type is socklen_t in POSIX) */ |
| int cmsg_level; /* Originating protocol */ |
| int cmsg_type; /* Protocol-specific type */ |
| /* followed by |
| unsigned char cmsg_data[]; */ |
| }; |
| .fi |
| .in |
| .PP |
| Ancillary data should be accessed only by the macros defined in |
| .BR cmsg (3). |
| .PP |
| As an example, Linux uses this ancillary data mechanism to pass extended |
| errors, IP options, or file descriptors over UNIX domain sockets. |
| .PP |
| The |
| .I msg_flags |
| field in the |
| .I msghdr |
| is set on return of |
| .BR recvmsg (). |
| It can contain several flags: |
| .TP |
| .B MSG_EOR |
| indicates end-of-record; the data returned completed a record (generally |
| used with sockets of type |
| .BR SOCK_SEQPACKET ). |
| .TP |
| .B MSG_TRUNC |
| indicates that the trailing portion of a datagram was discarded because the |
| datagram was larger than the buffer supplied. |
| .TP |
| .B MSG_CTRUNC |
| indicates that some control data were discarded due to lack of space in the |
| buffer for ancillary data. |
| .TP |
| .B MSG_OOB |
| is returned to indicate that expedited or out-of-band data were received. |
| .TP |
| .B MSG_ERRQUEUE |
| indicates that no data was received but an extended error from the socket |
| error queue. |
| .SH RETURN VALUE |
| These calls return the number of bytes received, or \-1 |
| if an error occurred. |
| In the event of an error, |
| .I errno |
| is set to indicate the error. |
| |
| When a stream socket peer has performed an orderly shutdown, |
| the return value will be 0 (the traditional "end-of-file" return). |
| |
| Datagram sockets in various domains (e.g., the UNIX and Internet domains) |
| permit zero-length datagrams. |
| When such a datagram is received, the return value is 0. |
| |
| The value 0 may also be returned if the requested number of bytes |
| to receive from a stream socket was 0. |
| .SH ERRORS |
| These are some standard errors generated by the socket layer. |
| Additional errors |
| may be generated and returned from the underlying protocol modules; |
| see their manual pages. |
| .TP |
| .BR EAGAIN " or " EWOULDBLOCK |
| .\" Actually EAGAIN on Linux |
| The socket is marked nonblocking and the receive operation |
| would block, or a receive timeout had been set and the timeout expired |
| before data was received. |
| POSIX.1 allows either error to be returned for this case, |
| and does not require these constants to have the same value, |
| so a portable application should check for both possibilities. |
| .TP |
| .B EBADF |
| The argument |
| .I sockfd |
| is an invalid file descriptor. |
| .TP |
| .B ECONNREFUSED |
| A remote host refused to allow the network connection (typically |
| because it is not running the requested service). |
| .TP |
| .B EFAULT |
| The receive buffer pointer(s) point outside the process's |
| address space. |
| .TP |
| .B EINTR |
| The receive was interrupted by delivery of a signal before |
| any data were available; see |
| .BR signal (7). |
| .TP |
| .B EINVAL |
| Invalid argument passed. |
| .\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom() |
| .TP |
| .B ENOMEM |
| Could not allocate memory for |
| .BR recvmsg (). |
| .TP |
| .B ENOTCONN |
| The socket is associated with a connection-oriented protocol |
| and has not been connected (see |
| .BR connect (2) |
| and |
| .BR accept (2)). |
| .TP |
| .B ENOTSOCK |
| The file descriptor |
| .I sockfd |
| does not refer to a socket. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, |
| 4.4BSD (these interfaces first appeared in 4.2BSD). |
| .LP |
| POSIX.1 describes only the |
| .BR MSG_OOB , |
| .BR MSG_PEEK , |
| and |
| .B MSG_WAITALL |
| flags. |
| .SH NOTES |
| The |
| .I socklen_t |
| type was invented by POSIX. |
| See also |
| .BR accept (2). |
| |
| According to POSIX.1, |
| .\" POSIX.1-2001, POSIX.1-2008 |
| the |
| .I msg_controllen |
| field of the |
| .I msghdr |
| structure should be typed as |
| .IR socklen_t , |
| but glibc currently types it as |
| .IR size_t . |
| .\" glibc bug raised 12 Mar 2006 |
| .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 |
| .\" The problem is an underlying kernel issue: the size of the |
| .\" __kernel_size_t type used to type this field varies |
| .\" across architectures, but socklen_t is always 32 bits. |
| |
| See |
| .BR recvmmsg (2) |
| for information about a Linux-specific system call |
| that can be used to receive multiple datagrams in a single call. |
| .SH EXAMPLE |
| An example of the use of |
| .BR recvfrom () |
| is shown in |
| .BR getaddrinfo (3). |
| .SH SEE ALSO |
| .BR fcntl (2), |
| .BR getsockopt (2), |
| .BR read (2), |
| .BR recvmmsg (2), |
| .BR select (2), |
| .BR shutdown (2), |
| .BR socket (2), |
| .BR cmsg (3), |
| .BR sockatmark (3), |
| .BR socket (7) |