diff options
Diffstat (limited to 'man2/recv.2')
| -rw-r--r-- | man2/recv.2 | 563 |
1 files changed, 0 insertions, 563 deletions
diff --git a/man2/recv.2 b/man2/recv.2 deleted file mode 100644 index 916cca3..0000000 --- a/man2/recv.2 +++ /dev/null @@ -1,563 +0,0 @@ -.\" 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 2024-02-18 "Linux man-pages 6.7" -.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) |