.\" 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:
.\" 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 1998,1999 by Andi Kleen
.\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin
.\"
-.TH RECV 2 2009-03-10 "Linux" "Linux Programmer's Manual"
+.TH RECV 2 2014-05-10 "Linux" "Linux Programmer's Manual"
.SH NAME
recv, recvfrom, recvmsg \- receive a message from a socket
.SH SYNOPSIS
.fi
.SH DESCRIPTION
The
-.BR recvfrom ()
+.BR recv (),
+.BR recvfrom (),
and
.BR recvmsg ()
-calls are used to receive messages from a socket, and may be used
-to receive data on a socket whether or not it is connection-oriented.
-.PP
-If
-.I src_addr
-is not NULL, and the underlying protocol provides the source address,
-this source address is filled in.
-When
-.I src_addr
-is NULL, nothing is filled in; in this case,
-.I addrlen
-is not used, and should also be NULL.
-.\" (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)]
-The argument
-.I addrlen
-is a value-result argument,
-which the caller should initialize before the call to
-the size of the buffer associated with
-.IR src_addr ,
-and modified on return to indicate 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.
-.PP
-The
-.BR recv ()
-call is normally used only on a
-.I connected
-socket (see
-.BR connect (2))
-and is identical to
-.BR recvfrom ()
-with a NULL
-.I src_addr
-argument.
+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
-All three routines return the length of the message on successful
+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
The receive calls normally return any data available, up to the requested
amount, rather than waiting for receipt of the full amount requested.
.PP
-The
-.BR select (2)
+An application can use
+.BR select (2),
+.BR poll (2),
or
-.BR poll (2)
-call may be used to determine when more data arrives.
-.PP
+.BR epoll (7)
+to determine when more data arrives on a socket.
+.SS The flags argument
The
.I flags
-argument to a
-.BR recv ()
-call is formed by
-.IR OR 'ing
-one or more of the following values:
+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
+via a UNIX domain file descriptor using the
.B SCM_RIGHTS
operation (described in
.BR unix (7)).
For raw
.RB ( AF_PACKET ),
Internet datagram (since Linux 2.4.27/2.6.8),
-and netlink (since Linux 2.6.22) sockets:
+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.
-Not implemented for Unix domain
-.RB ( unix (7))
-sockets.
For use with Internet stream sockets, see
.BR tcp (7).
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.
-.PP
+.\"
+.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
+should be specified as NULL and
+.I addrlen
+should be specified as 0.
+.\"
+.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
struct iovec *msg_iov; /* scatter/gather array */
size_t msg_iovlen; /* # elements in msg_iov */
void *msg_control; /* ancillary data, see below */
- socklen_t msg_controllen; /* ancillary data buffer len */
+ size_t msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
};
.fi
.in
.PP
-Here
+The
.I msg_name
-and
+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
-specify the source address if the socket is unconnected;
+to the size of this buffer before this call;
+upon return from a successful call,
+.I msg_name
+will contain the length of the returned address.
+If the application does not need to know the source address,
.I msg_name
-may be given as a null pointer if no names are desired or required.
+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
.fi
.in
.PP
-Ancillary data should only be accessed by the macros defined in
+Ancillary data should be accessed only by the macros defined in
.BR cmsg (3).
.PP
-As an example, Linux uses this auxiliary data mechanism to pass extended
-errors, IP options or file descriptors over Unix sockets.
+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 msghdr is set on return of
+field in the
+.I msghdr
+is set on return of
.BR recvmsg ().
It can contain several flags:
.TP
.B MSG_ERRQUEUE
indicates that no data was received but an extended error from the socket
error queue.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
These calls return the number of bytes received, or \-1
if an error occurred.
-The return value will be 0 when the
-peer has performed an orderly shutdown.
+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
The argument
.I sockfd
does not refer to a socket.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
4.4BSD (these function calls first appeared in 4.2BSD),
POSIX.1-2001.
.LP
-POSIX.1-2001 only describes the
+POSIX.1-2001 describes only the
.BR MSG_OOB ,
.BR MSG_PEEK ,
and
flags.
.SH NOTES
The prototypes given above follow glibc2.
-The Single Unix Specification agrees, except that it has return values
+The Single UNIX Specification agrees, except that it has return values
of type \fIssize_t\fP (while 4.x BSD and libc4 and libc5 all have \fIint\fP).
The
.I flags
.I msghdr
structure should be typed as
.IR socklen_t ,
-but glibc currently (2.4) types it as
+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"
+.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)
+.SH COLOPHON
+This page is part of release 3.67 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
