Linux socket send(2) (翻译 man 2)

SEND(2)                       Linux Programmer's Manual                       SEND(2)

NAME

       send, sendto, sendmsg - send a message on a socket

//向socket发送信息

SYNOPSIS

       #include <sys/types.h>

       #include <sys/socket.h>

       ssize_t send(int sockfd, const void *buf, size_t len, int flags);

       ssize_t sendto(int sockfd, const void *buf, size_t len, int flags,
                      const struct sockaddr *dest_addr, socklen_t addrlen);

       ssize_t sendmsg(int sockfd, const struct msghdr *msg, int flags);

DESCRIPTION

       The system calls send(), sendto(), and sendmsg() are used to transmit a
       message to another socket.

//这些协调调用向另一个socket发送信息.

       The send() call may be used only when the socket is in a connected state (so

       that the intended recipient is known).  The only difference between send() and

       write(2) is the presence of flags.  With a zero flags argument, send() is

       equivalent to write(2).  Also, the following call

           send(sockfd, buf, len, flags);

       is equivalent to

           sendto(sockfd, buf, len, flags, NULL, 0);

//send()调用应该仅仅用在当socket是连接状态的时候(这样预期的接收就是已知的).send()和 write(2)唯一不同就是标志位.

//当send()的标志位为0的时候,send()等同于write(2).同样的,上述是send()等效于sendto().

       The argument sockfd is the file descriptor of the sending socket.

//参数sockfd是发送socket的fd

       If sendto() is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET) socket,

       the arguments dest_addr and addrlen are ignored (and the error EISCONN may be

       returned when they are not NULL and 0), and the error ENOTCONN is returned

       when the socket was not actually connected.  Otherwise, the address of the

       target is given by dest_addr with addrlen specifying its size.  For sendmsg(),

       the address of the target is given by msg.msg_name, with msg.msg_namelen

       specifying its size.

//如果 sendto() 用在连接模式的(SOCK_STREAM, SOCK_SEQPACKET) socket的话,dest_addr 和 addrlen 参数就会忽略(如果

//它们不是NULL和0的话, EISCONN错误就会返回),如果socket不是实际连接的话 ENOTCONN的错误就会返回.

//另外,目的地址由 dest_addr 同时 addrlen 给出了地址的大小.对 sendmsg()来说,目标地址

是由 msg.msg_name 给出的,msg_msg_namelen给出了地址的大小.

       For send() and sendto(), the message is found in buf and has length len.  For

       sendmsg(), the message is pointed to by the elements of the array msg.msg_iov.

       The sendmsg() call also allows sending ancillary data (also known as control

       information).

//对send()和sendto(),在buf中的信息的长度是len.对sendmsg(),信息是由数组 msg.msg.msg_iov的元素指向的.

//sendmsg()调用也允许发送额外的信息(也作为控制信息).

       If the message is too long to pass atomically through the underlying protocol,

       the error EMSGSIZE is returned, and the message is not transmitted.

//如果信息通过以下的协议自动发送的时候过长的话,那么 EMSGSIZE 错误就会返回,信息就不会发送.

       No indication of failure to deliver is implicit in a send().  Locally detected

       errors are indicated by a return value of -1.

//在send()中没有失败的发送是隐含的.本地检测到错误由返回值表示为-1来标识.

       When the message does not fit into the send buffer of the socket, send()

       normally blocks, unless the socket has been placed in nonblocking I/O mode.

       In nonblocking mode it would fail with the error EAGAIN or EWOULDBLOCK in this

       case.  The select(2) call may be used to determine when it is possible to send

       more data.

//在socket中信息不能正好放入发送缓存的时候,send()一般会阻塞,直到socket被置为非阻塞的I/O模式.

//在非阻塞模式这种情况会失败返回 EAGAIN 或者 EWOULDBLOCK.select(2)调用可以用来决定什么时候可以发送更多的数据.

       The flags argument is the bitwise OR of zero or more of the following flags.

//flags 参数可以设置为用OR 0个或者多个以下的标志位:

       MSG_CONFIRM (Since Linux 2.3.15)

              Tell the link layer that forward progress happened: you got a

              successful reply from the other side.  If the link layer doesn't get

              this it will regularly reprobe the neighbor (e.g., via a unicast ARP).

              Only valid on SOCK_DGRAM and SOCK_RAW sockets and currently only

              implemented for IPv4 and IPv6.  See arp(7) for details.

//MSG_CONFIRM (从 Linux 2.3.15 之后开始支持) 

//告诉连接层之前的处理发生了:你已经从别处获得了成功的应答.如果连接层如果没从别处获得成功的应答,那么连接层就会定期的再次探测它的邻居

//(如通过ARP的单播).只有在 SOCK_DRAM 和 SOCK_RAW 的socket上有效,当前只有 IPv4 IPv6上实现了.参见 arp(7)的细节.

       MSG_DONTROUTE

              Don't use a gateway to send out the packet, only send to hosts on

              directly connected networks.  This is usually used only by diagnostic

              or routing programs.  This is only defined for protocol families that

              route; packet sockets don't.

//不要用网关发出数据包,仅仅通过直接连接的网络向主机发送.这经常用在诊断或者路由程序中.这仅仅是为了路由协议族定义的,socket的包不使用.

       MSG_DONTWAIT (since Linux 2.2)

              Enables nonblocking operation; if the operation would block, EAGAIN or

              EWOULDBLOCK is returned (this can also be enabled using the O_NONBLOCK

              flag with the F_SETFL fcntl(2)).

//MSG_DONTWAIT (从 Linux 2.2 之后开始支持) 

//使能非阻塞操作,如果操作阻塞的话,会返回 EAGAIN 或者 EWOULDBLOCK(也可以使用o_NONBLOCK在fcntl(2)的F_SETFL打开).

       MSG_EOR (since Linux 2.2)

              Terminates a record (when this notion is supported, as for sockets of

              type SOCK_SEQPACKET).

//MSG_EOR (从 Linux 2.2 之后开始支持) 

//终结一个记录(当支持这个想法的时候,就和SOCK_SEQPACKET的socket类型一样了)

       MSG_MORE (Since Linux 2.4.4)

              The caller has more data to send.  This flag is used with TCP sockets

              to obtain the same effect as the TCP_CORK socket option (see tcp(7)),

              with the difference that this flag can be set on a per-call basis.

//MSG_MORE(从 Linux 2.4.4 之后开始支持) 

//调用者还有更多的数据要发送.这个标志位是在TCP的socket上用来获得TCP_CORK socket一样的效果的(参见(tcp(7)),

//唯一的不同是这个标志位可以在预先调用的基础上设置.

              Since Linux 2.6, this flag is also supported for UDP sockets, and

              informs the kernel to package all of the data sent in calls with this

              flag set into a single datagram which is only transmitted when a call

              is performed that does not specify this flag.  (See also the UDP_CORK

              socket option described in udp(7).)

//在Linux 2.6之前,这个标志位也被UDP支持,并通知内核将在调用中所有设置这个标志位的数据

打包为一个单独的数据报,这个数据报仅仅当调用生效的时候而

//没有设置这个标志位的时候才会发送.(参见UDP-CORK 在udp(7)的选项中有描述).

       MSG_NOSIGNAL (since Linux 2.2)

              Requests not to send SIGPIPE on errors on stream oriented sockets when

              the other end breaks the connection.  The EPIPE error is still

              returned.

//MSG_NOSIGNAL (从 Linux 2.2 之后开始支持) 

//要求在面向流的socket上当错误发生的时候不发送SIGPIPE这个信号,当别的终端破坏这个连接的时候.EPIPE错误仍然会返回.

       MSG_OOB

              Sends out-of-band data on sockets that support this notion (e.g., of

              type SOCK_STREAM); the underlying protocol must also support out-of-

              band data.

//支持这种情况的话会在socket上发送越界数据(如 SOCK_STREAM);与之对应的是协议也要支持越界数据.

       The definition of the msghdr structure follows.  See recv(2) and below for an

       exact description of its fields.

//msghdr 结构体的定义如下.在recv(2)中看这些域的额外描述.

           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 */

           };

       You may send control information using the msg_control and msg_controllen

       members.  The maximum control buffer length the kernel can process is limited

       per socket by the value in /proc/sys/net/core/optmem_max; see socket(7).

//你可以使用 msg_control 和 msg_cintrollen发送控制信息.对每个socket而言在内核中控制缓存的最大值是由这个值限制的,

//是 /proc/sys/net/core/optmem_max ; 参见 socket(7)

RETURN VALUE

       On success, these calls return the number of characters sent.  On error, -1 is

       returned, and errno is set appropriately.

//成功的话这些调用返回发送的字符数.错误的话返回-1并且自动设定errno.

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 respective manual pages.

//这些是在socket层产生的标准错误,额外的错误也会产生并且从对应的协议模型返回,见协议的各自的手册.

       EACCES (For UNIX domain sockets, which are identified by pathname) Write

              permission is denied on the destination socket file, or search

              permission is denied for one of the directories the path prefix.  (See

              path_resolution(7).)

//(在UNIX下通过路径定义的socket域)在目的地址的socket写权限是禁止的,或者是在路径的目录前缀搜索权限是禁止的(参见 path_resolution(7)).

       EAGAIN or EWOULDBLOCK

              The socket is marked nonblocking and the requested operation would

              block.  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.

//socket标记为非阻塞但是要求的操作阻塞了它.POSIX.1-2001 在这种情况下允许返回这2者中的任何一个,并不需要2者有相同的值,

//所以一个可移植的程序应该对这2种可能性都进行检查.

       EBADF  An invalid descriptor was specified.

//无效的描述符

       ECONNRESET

              Connection reset by peer.

//对方重置了连接.

//译者注:比较容易出现这种情况的原因:

//①：服务器的并发连接数超过了其承载量，服务器会将其中一些连接Down掉；

//②：客户关掉了浏览器，而服务器还在给客户端发送数据；(在关闭IE的时候,设备的发送端确实会返回这个错误)

       EDESTADDRREQ

              The socket is not connection-mode, and no peer address is set.

//socket不是连接模式,同时没有设置对方的地址

       EFAULT An invalid user space address was specified for an argument.

//对参数指定了无效的用户空间地址

       EINTR  A signal occurred before any data was transmitted; see signal(7).

//在数据传输之前信号产生了;参见signal(7);

       EINVAL Invalid argument passed.

//传递了无效的参数

       EISCONN

              The connection-mode socket was connected already but a recipient was

              specified.  (Now either this error is returned, or the recipient

              specification is ignored.)

//已经连接了一个连接模式的socket但是指定了容器.(现在或者是返回这个错误,要么忽略指定容器).

       EMSGSIZE

              The socket type requires that message be sent atomically, and the size

              of the message to be sent made this impossible.

//需要的socket类型已经被信息自动设定了,然而发送信息的大小使得这种模式成为不可能的.

       ENOBUFS

              The output queue for a network interface was full.  This generally

              indicates that the interface has stopped sending, but may be caused by

              transient congestion.  (Normally, this does not occur in Linux.

              Packets are just silently dropped when a device queue overflows.)

//对网络接口的输出队列已满.这一般表示接口停止发送,可能是由于传输拥挤造成的.(一般的,在Linux下不会发生,

//当设备队列溢出的话,数据报会默默的被丢弃掉).

       ENOMEM No memory available.

//没有可用的内存了

       ENOTCONN

              The socket is not connected, and no target has been given.

//socket没有连接,也没有给出发送的目标.

       ENOTSOCK

              The argument sockfd is not a socket.

//参数 sockfd 不是一个 socket

       EOPNOTSUPP

              Some bit in the flags argument is inappropriate for the socket type.

//flags 参数的一些标志位和 socket的类型不合适

       EPIPE  The local end has been shut down on a connection oriented socket.  In

              this case the process will also receive a SIGPIPE unless MSG_NOSIGNAL

              is set.

//在一个基于连接的socket上本地端已经关闭.在这种情况下,进程会收到 SIGPIEP除非MSG_NOSIGNAL设置的话.

CONFORMING TO

       4.4BSD, SVr4, POSIX.1-2001.  These function calls appeared in 4.2BSD.

       POSIX.1-2001 only describes the MSG_OOB and MSG_EOR flags.  The MSG_CONFIRM

       flag is a Linux extension.

NOTES

       The prototypes given above follow the Single UNIX Specification, as glibc2

       also does; the flags argument was int in 4.x BSD, but unsigned int in libc4

       and libc5; the len argument was int in 4.x BSD and libc4, but size_t in libc5;

       the addrlen argument was int in 4.x BSD and libc4 and libc5.  See also

       accept(2).

//上面给出的协议类型是单独的UNIX规格的,glibc2也可以. 

//flags参数在4.x BSD中是int,但是在libc4 中是unsigned int;

//len 参数在4.x BSD 和 libc4 中是int,但是在libc5 中是 size_t;

//addrlen 参数 在4.x BSD 和 libc4 ,libc5 中都是int.

//参见accept(2)中的描述

       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.

//根据POSIX.1-2001, msghdr 结构体的 msg_controllen 域应该是 socklen_t 的,但是当前 glibc 中是 size_t.

BUGS

       Linux may return EPIPE instead of ENOTCONN.

//在Linux中可能返回 EPIPE 来取代 ENOTCONN

EXAMPLE

       An example of the use of sendto() is shown in getaddrinfo(3).

SEE ALSO

       fcntl(2), getsockopt(2), recv(2), select(2), sendfile(2), shutdown(2),

       socket(2), write(2), cmsg(3), ip(7), socket(7), tcp(7), udp(7)

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 http://www.kernel.org/doc/man-pages/.