Linux Programer’s Mnaual – RECV(2)
NAME
recv, recvfrom, recvmsg - receive a message from a socket
SYNOPSIS
#include
#include
ssize_t recv(int sockfd, void *buf, size_t len, int flags);
ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags,
struct sockaddr *src_addr, socklen_t *addrlen);
ssize_t recvmsg(int sockfd, struct msghdr *msg, int flags);
DESCRIPTION
The recvfrom() and 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.
在从一个套接口上接收消息时, 调用recvfrom()和recvmsg(), 无论这个套接口是否面向连接.
If src_addr is not NULL, and the underlying protocol provides the source address, this source address is filled in. When src_addr is NULL, nothing is filled in; in this case, addrlen is not used, and should also be NULL. The argument addrlen is a value-result argument, which the caller should initialize before the call to the size of the buffer associated with 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, addrlen will return a value greater than was supplied to the call.
如果src_addr不为NULL, 并且底层协议支持源地址(如UDP), 则这个源地址被填充, 当src_addr为NULL, 则不被填充. 这种情况下addrlen是无用的, 且应该被设置为0, addrlen是个值结果参数, 在调用方调用前应对addrlen初始化, 在调用之后, 返回指定实际源地址的大小. 如果提供的缓冲太小, 返回的地址可能被截短. 这时addrlen会返回一个比调用时提供的值更大的值.
The recv() call is normally used only on a connected socket (see ) and is identical to recvfrom() with a NULL src_addr argument.
系统调用recv()通常只用于一个已连接的套接口(参见), 并且与recvfrom()的src_addr参数为NULL的情况完全相同.
All three routines 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.
这三个调用都返回实际接收消息的长度, 如果接收到的消息太长, 超出了提供的缓冲(buf)的长度(len), 那么超出的部分可能丢弃, 这依赖于套接口接收消息的类型.
If no messages are available at the socket, the receive calls wait for a message to arrive, unless the socket is nonblocking (see ), in which case the value -1 is returned and the external variable errno is set to 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.
如果在套接口上没有可接受的消息, 则接口调用等待消息到达(阻塞), 除非该套接口被设置为阻塞(参阅), 这时, 返回-1, 并设置errno为EAGAIN or EWOULDBLOCK. 接收调用通常返回请求的数据, 而不是等待全部的数据.
The or call may be used to determine when more data arrives.
当要确定是否有更多数据到达时, 可能调用或者.
The flags argument to a recv() call is formed by OR'ing one or more of the following values:
flags参数是由下面数值用”|”组成
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 SCM_RIGHTS operation (described in ). This flag is useful for the same reasons as the O_CLOEXEC flag of .
使用SCM_RIGHTS操作(参阅)为一个Unix域协议接收描述符, 设置”执行时关闭”选项. 该选项与设置open(2) O_CLOEXEC的选项原因相同.
MSG_DONTWAIT (since Linux 2.2)
Enables nonblocking operation; if the operation would block, the call fails with the error EAGAIN or EWOULDBLOCK (this can also be enabled using the O_NONBLOCK flag with the F_SETFL ).
使能非阻塞操作. 如果操作阻塞, 将返回EAGAIN或EWOULDBLOCK错误(也可以使用 F_SETFL的O_NONBLOCK选项).
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 IP_RECVERR). The user should supply a buffer of sufficient size. See and for more information. The payload of the original packet that caused the error is passed as normal data via msg_iovec. The original destination address of the datagram that caused the error is supplied via msg_name.
该标记列举应从套接口错误队列接收的派对错误. 该错误传递依赖于某种特定协议的辅助消息(对于IPv4, 为IP_RECVERR). 用户应该足够大的缓冲空间. 参见和获取更多信息. 原始数据包中引起错误的负载数据, 通过msg_iovec被作为正常数据传递. 数据包中引起错误的原始目的地址通过msg_name提供.
For local errors, no address is passed (this can be checked with the cmsg_len member of the cmsghdr). For error receives, the MSG_ERRQUEUE is set in the 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.
对于本地错误, 没有地址被传递(这个可以通过cmsghdr中的cmsg_len成员检查). 对于接收错误, MSG_ERRQUEUE被设置在msghdr中. 在一个错误被传递后, 未发生的套接口错误将在下一个排队错误中出现, 并在下一个套接口操作中被传递.
The error is supplied in a sock_extended_err structure:
该错误在结构sock_extended_err中提供
#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_errno contains the errno number of the queued error. ee_origin is the origin code of where the error originated. The other fields are protocol-specific. The macro 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 sa_family member of the sockaddr contains AF_UNSPEC and the other fields of the sockaddr are undefined. The payload of the packet that caused the error is passed as normal data.
ee_errno中包含被排序错误的errno, ee_origin是错误发生源的原始代码. 其他字段由协议指定. 宏定义SOCK_EE_OFFENDER返回一个指针. 这个指针指向发生错误的网络结构的地址, 提供了一个指向辅助信息的指针. 如果该地址是未知的, sockaddr中的sa_family成员为AF_UNSPEC, 并且该结构的其他字段未指定. 引起错误的报文负载作为正常的数据被传送.
For local errors, no address is passed (this can be checked with the cmsg_len member of the cmsghdr). For error receives, the MSG_ERRQUEUE is set in the 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.
对于本地错误, 没有地址被传递(这个可以通过cmsghdr中的cmsg_len成员检查). 对于接收错误, MSG_ERRQUEUE被设置在msghdr中. 在一个错误被传递后, 未发生的套接口错误将在下一个排队错误中出现, 并在下一个套接口操作中被传递.
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.
该标记请求接正常数据流之外的收外带数据, 一些协议将快速数据置于正常数据队列的起始, 并因此这个标记不能用于这类型的协议.
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.
这个标记导致接收操作返回接收队列开始部分是数据, 而不将这部分数据从队列中移除. 也就是说随后接收到的数据是相同的.
MSG_TRUNC (since Linux 2.2)
For raw (AF_PACKET), Internet datagram (since Linux 2.4.27/2.6.8), and netlink (since Linux 2.6.22) sockets: return the real length of the packet or datagram, even when it was longer than the passed buffer. Not implemented for UNIX domain () sockets.
对于raw(AF_PACKET)套接口, Internet数据包(Linux2.4.27~2.6.8)套接口, 和netlink(从2.6.22)套接口: 返回报文或数据包的实际长度, 即使其长度长于接收的缓冲区长度. 这个标记在Unix协议域((7))套接口中没有实现.
For use with Internet stream sockets, see .
使用Internet Stream 套接口, 参阅
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.
这个标记要求操作阻塞, 知道全部的请求被满足. 然而, 当扑捉到一个信号, 错误或连接中断, 或接下来的数据是不同类型的数据时, 调用仍然会返回比请求的长度短的数据.
The recvmsg() call uses a msghdr structure to minimize the number of directly supplied arguments. This structure is defined as follows in :
recvmsg()使用msghdr结构减少提供参数的个数. 这个结构定义在中:
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 */
};
Here msg_name and msg_namelen specify the source address if the socket is unconnected; msg_name may be given as a null pointer if no names are desired or required. The fields msg_iov and msg_iovlen describe scatter-gather locations, as discussed in . The field msg_control, which has length msg_controllen, points to a buffer for other protocol control-related messages or miscellaneous ancillary data. When recvmsg() is called, msg_controllen should contain the length of the available buffer in msg_control; upon return from a successful call it will contain the length of the control message sequence.
如果套几口源地址未连接, msg_name和msg_namelen指定源地址. 如果不要求源地址, msg_name给定为NULL. msg_iov和msg_iovlen描述分散集中的位置, 如中的描述. msg_control指定其他协议控制相关的消息或其他辅助数据的缓冲区的指针. msg_controllen为该结构的长度. 当recvmsg()被调用, msg_controllen应包含msg_control中可用缓冲的长度. 当调用成功返回, msg_controllen应包消息序列的长度.
The messages are of the form:
消息的组成如下:
struct cmsghdr {
socklen_t cmsg_len; /* data byte count, including hdr */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by unsigned char cmsg_data[]; */
};
Ancillary data should only be accessed by the macros defined in .
辅助数据应只被中的宏定义访问.
As an example, Linux uses this ancillary data mechanism to pass extended errors, IP options, or file descriptors over UNIX domain sockets.
Linux使用这些辅助数据机制传递扩充的错误, ip选项, 或用于UNIX协议域套接字的文件描述符.
The msg_flags field in the msghdr is set on return of recvmsg(). It can contain several flags:
msghdr中的msg_flags为recvmsg()调用的返回, 可以包含以下标记.
MSG_EOR
indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET).
指定记录的结束; 返回完成的记录(通常使用SOCK_SEQPACKET标记)
MSG_TRUNC
indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied.
指定因数据包长于缓冲长度而被截去的数据.
MSG_CTRUNC
indicates that some control data were discarded due to lack of space in the buffer for ancillary data.
指定由于辅助数据缓冲空间限制而别截去的数据.
MSG_OOB
is returned to indicate that expedited or out-of-band data were received.
返回接收到的快速数据或外带数据
MSG_ERRQUEUE
indicates that no data was received but an extended error from the socket error queue.
说明只收来自socket错误队列的附加错误
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.
这些调用返回接收到的字节数, 或者返回-1, 代表错误发生. 当对端正常关闭返回0.
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.
在套接字协议层产生的标准错误, 附加的错误可能产生并返回给底层协议模块, 参阅他们的手册页
EAGAIN or EWOULDBLOCK
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-2001 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.
当套接口被标记为非阻塞, 或者接收操作阻塞, 且接收时限已经超过设置的超时时间. 这种情况下, POSIX.1-2001这两种错误代码都允许被返回, 且不要求这两个常量有相同的值, 所以一个可移植程序应该检查这两种可能性.
EBADF The argument sockfd is an invalid descriptor.
参数sockfd是一个无效的描述符
ECONNREFUSED
A remote host refused to allow the network connection (typically because it is not running the requested service).
远程主机拒绝网络连接(通常是因为没有运行接收请求的服务).
EFAULT The receive buffer pointer(s) point outside the process's address space.
接收缓冲指针, 超出了进程地址空间.
EINTR The receive was interrupted by delivery of a signal before any data were available; see .
在没有得到任何可用数据之前, 接收被交付信号中断. 参见.
EINVAL Invalid argument passed.
无效参数
ENOMEM Could not allocate memory for recvmsg().
不能为recvmsg()分配空间
ENOTCONN
The socket is associated with a connection-oriented protocol and has not been connected (see and ).
套接口与一个面向连接的协议(TCP, 或者其他面向连接的协议)关联, 但还未连接, 参见 和
ENOTSOCK
The argument sockfd does not refer to a socket.
sockfd不是一个有效的套接口.
CONFORMING TO
4.4BSD (these function calls first appeared in 4.2BSD), POSIX.1-2001. POSIX.1-2001 only describes the MSG_OOB, MSG_PEEK, and MSG_WAITALL flags.
NOTES
The prototypes given above follow glibc2. The Single UNIX Specification agrees, except that it has return values of type ssize_t (while 4.x BSD and libc4 and libc5 all have int). The flags argument is int in 4.x BSD, but unsigned int in libc4 and libc5. The len argument is int in 4.x BSD, but size_t in libc4 and libc5. The addrlen argument is int * in 4.x BSD, libc4 and libc5. The present socklen_t * was invented by POSIX. See also .
According to POSIX.1-2001, the msg_controllen field of the msghdr structure should be typed as socklen_t, but glibc currently types it as size_t.
EXAMPLE
An example of the use of recvfrom() is shown in .
recvfrom()的例子, 参见
SEE ALSO
, , , , , , , ,
COLOPHON
This page is part of release 3.32 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at .
