diff options
Diffstat (limited to 'man/man2/recv.2')
| -rw-r--r-- | man/man2/recv.2 | 563 |
1 files changed, 563 insertions, 0 deletions
diff --git a/man/man2/recv.2 b/man/man2/recv.2 new file mode 100644 index 000000000..294eca384 --- /dev/null +++ b/man/man2/recv.2 @@ -0,0 +1,563 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" $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 (date) "Linux man-pages (unreleased)" +.SH NAME +recv, recvfrom, recvmsg \- receive a message from a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.P +.BI "ssize_t recv(int " sockfd ", void " buf [. len "], size_t " len , +.BI " int " flags ); +.BI "ssize_t recvfrom(int " sockfd ", void " buf "[restrict ." len "], size_t " len , +.BI " int " flags , +.BI " struct sockaddr *_Nullable restrict " src_addr , +.BI " socklen_t *_Nullable restrict " addrlen ); +.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. +.P +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 generally equivalent to +.BR read (2) +(but see NOTES). +Also, the following call +.P +.in +4n +.EX +recv(sockfd, buf, len, flags); +.EE +.in +.P +is equivalent to +.P +.in +4n +.EX +recvfrom(sockfd, buf, len, flags, NULL, NULL); +.EE +.in +.P +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. +.P +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 +.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. +.P +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 +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 +The error is supplied in a +.I sock_extended_err +structure: +.IP +.in +4n +.EX +#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 *); +.EE +.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 SO_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 +flag 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 as well as sequenced-packet +.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f +(since Linux 3.4) sockets: +return the real length of the packet or datagram, +even when it was longer than the passed buffer. +.IP +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 . +.P +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. +.P +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: +.P +.in +4n +.EX +recvfrom(fd, buf, len, flags, NULL, 0); +.EE +.in +.\" +.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> : +.P +.in +4n +.EX +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 */ +}; +.EE +.in +.P +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. +.P +The fields +.I msg_iov +and +.I msg_iovlen +describe scatter-gather locations, as discussed in +.BR readv (2). +.P +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. +.P +The messages are of the form: +.P +.in +4n +.EX +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[]; */ +}; +.EE +.in +.P +Ancillary data should be accessed only by the macros defined in +.BR cmsg (3). +.P +As an example, Linux uses this ancillary data mechanism to pass extended +errors, IP options, or file descriptors over UNIX domain sockets. +For further information on the use of ancillary data in various +socket domains, see +.BR unix (7) +and +.BR ip (7). +.P +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 was 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 was received. +.TP +.B MSG_ERRQUEUE +indicates that no data was received but an extended error from the socket +error queue. +.TP +.BR MSG_CMSG_CLOEXEC " (since Linux 2.6.23)" +.\" commit 4a19542e5f694cd408a32c3d9dc593ba9366e2d7 +indicates that +.B MSG_CMSG_CLOEXEC +was specified in the +.I flags +argument of +.BR recvmsg (). +.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. +.P +When a stream socket peer has performed an orderly shutdown, +the return value will be 0 (the traditional "end-of-file" return). +.P +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. +.P +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 was 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 VERSIONS +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 , +and the +.I msg_iovlen +field should be typed as +.IR int , +but glibc currently types both as +.IR size_t . +.\" glibc bug for msg_controllen 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 these fields varies +.\" across architectures, but socklen_t is always 32 bits, +.\" as (at least with GCC) is int. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +4.4BSD (first appeared in 4.2BSD). +.P +POSIX.1 describes only the +.BR MSG_OOB , +.BR MSG_PEEK , +and +.B MSG_WAITALL +flags. +.SH NOTES +If a zero-length datagram is pending, +.BR read (2) +and +.BR recv () +with a +.I flags +argument of zero provide different behavior. +In this circumstance, +.BR read (2) +has no effect (the datagram remains pending), while +.BR recv () +consumes the pending datagram. +.P +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 EXAMPLES +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 ip (7), +.BR ipv6 (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) |