diff options
Diffstat (limited to 'man2/send.2')
| -rw-r--r-- | man2/send.2 | 506 |
1 files changed, 0 insertions, 506 deletions
diff --git a/man2/send.2 b/man2/send.2 deleted file mode 100644 index 79abcc7..0000000 --- a/man2/send.2 +++ /dev/null @@ -1,506 +0,0 @@ -.\" Copyright (c) 1983, 1991 The Regents of the University of California. -.\" All rights reserved. -.\" -.\" SPDX-License-Identifier: BSD-4-Clause-UC -.\" -.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> -.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> -.\" Modified Oct 1998 by Andi Kleen -.\" Modified Oct 2003 by aeb -.\" Modified 2004-07-01 by mtk -.\" -.TH send 2 2024-02-18 "Linux man-pages 6.7" -.SH NAME -send, sendto, sendmsg \- send a message on a socket -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/socket.h> -.P -.BI "ssize_t send(int " sockfd ", const void " buf [. len "], size_t " len \ -", int " flags ); -.BI "ssize_t sendto(int " sockfd ", const void " buf [. len "], size_t " len \ -", int " flags , -.BI " const struct sockaddr *" dest_addr ", socklen_t " addrlen ); -.BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \ -", int " flags ); -.fi -.SH DESCRIPTION -The system calls -.BR send (), -.BR sendto (), -and -.BR sendmsg () -are used to transmit a message to another socket. -.P -The -.BR send () -call may be used only when the socket is in a -.I connected -state (so that the intended recipient is known). -The only difference between -.BR send () -and -.BR write (2) -is the presence of -.IR flags . -With a zero -.I flags -argument, -.BR send () -is equivalent to -.BR write (2). -Also, the following call -.P -.in +4n -.EX -send(sockfd, buf, len, flags); -.EE -.in -.P -is equivalent to -.P -.in +4n -.EX -sendto(sockfd, buf, len, flags, NULL, 0); -.EE -.in -.P -The argument -.I sockfd -is the file descriptor of the sending socket. -.P -If -.BR sendto () -is used on a connection-mode -.RB ( SOCK_STREAM , -.BR SOCK_SEQPACKET ) -socket, the arguments -.I dest_addr -and -.I addrlen -are ignored (and the error -.B EISCONN -may be returned when they are -not NULL and 0), and the error -.B ENOTCONN -is returned when the socket was not actually connected. -Otherwise, the address of the target is given by -.I dest_addr -with -.I addrlen -specifying its size. -For -.BR sendmsg (), -the address of the target is given by -.IR msg.msg_name , -with -.I msg.msg_namelen -specifying its size. -.P -For -.BR send () -and -.BR sendto (), -the message is found in -.I buf -and has length -.IR len . -For -.BR sendmsg (), -the message is pointed to by the elements of the array -.IR msg.msg_iov . -The -.BR sendmsg () -call also allows sending ancillary data (also known as control information). -.P -If the message is too long to pass atomically through the -underlying protocol, the error -.B EMSGSIZE -is returned, and the message is not transmitted. -.P -No indication of failure to deliver is implicit in a -.BR send (). -Locally detected errors are indicated by a return value of \-1. -.P -When the message does not fit into the send buffer of the socket, -.BR send () -normally blocks, unless the socket has been placed in nonblocking I/O -mode. -In nonblocking mode it would fail with the error -.B EAGAIN -or -.B EWOULDBLOCK -in this case. -The -.BR select (2) -call may be used to determine when it is possible to send more data. -.SS The flags argument -The -.I flags -argument is the bitwise OR -of zero or more of the following flags. -.\" FIXME . ? document MSG_PROXY (which went away in Linux 2.3.15) -.TP -.BR 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). -Valid only on -.B SOCK_DGRAM -and -.B SOCK_RAW -sockets and currently implemented only for IPv4 and IPv6. -See -.BR arp (7) -for details. -.TP -.B MSG_DONTROUTE -Don't use a gateway to send out the packet, send to hosts only on -directly connected networks. -This is usually used only -by diagnostic or routing programs. -This is defined only for protocol -families that route; packet sockets don't. -.TP -.BR MSG_DONTWAIT " (since Linux 2.2)" -Enables nonblocking operation; if the operation would block, -.B EAGAIN -or -.B EWOULDBLOCK -is returned. -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_EOR " (since Linux 2.2)" -Terminates a record (when this notion is supported, as for sockets of type -.BR SOCK_SEQPACKET ). -.TP -.BR 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 -.B TCP_CORK -socket option (see -.BR tcp (7)), -with the difference that this flag can be set on a per-call basis. -.IP -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 transmitted only when a call is performed -that does not specify this flag. -(See also the -.B UDP_CORK -socket option described in -.BR udp (7).) -.TP -.BR MSG_NOSIGNAL " (since Linux 2.2)" -Don't generate a -.B SIGPIPE -signal if the peer on a stream-oriented socket has closed the connection. -The -.B EPIPE -error is still returned. -This provides similar behavior to using -.BR sigaction (2) -to ignore -.BR SIGPIPE , -but, whereas -.B MSG_NOSIGNAL -is a per-call feature, -ignoring -.B SIGPIPE -sets a process attribute that affects all threads in the process. -.TP -.B MSG_OOB -Sends -.I out-of-band -data on sockets that support this notion (e.g., of type -.BR SOCK_STREAM ); -the underlying protocol must also support -.I out-of-band -data. -.TP -.BR MSG_FASTOPEN " (since Linux 3.7)" -Attempts TCP Fast Open (RFC7413) and sends data in the SYN like a -combination of -.BR connect (2) -and -.BR write (2), -by performing an implicit -.BR connect (2) -operation. -It blocks until the data is buffered and the handshake has completed. -For a non-blocking socket, -it returns the number of bytes buffered and sent in the SYN packet. -If the cookie is not available locally, -it returns -.BR EINPROGRESS , -and sends a SYN with a Fast Open cookie request automatically. -The caller needs to write the data again when the socket is connected. -On errors, -it sets the same -.I errno -as -.BR connect (2) -if the handshake fails. -This flag requires enabling TCP Fast Open client support on sysctl -.IR net.ipv4.tcp_fastopen . -.IP -Refer to -.B TCP_FASTOPEN_CONNECT -socket option in -.BR tcp (7) -for an alternative approach. -.SS sendmsg() -The definition of the -.I msghdr -structure employed by -.BR sendmsg () -is as follows: -.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 (unused) */ -}; -.EE -.in -.P -The -.I msg_name -field is used on an unconnected socket to specify the target -address for a datagram. -It points to a buffer containing the address; the -.I msg_namelen -field should be set to the size of the address. -For a connected socket, these fields should be specified as NULL and 0, -respectively. -.P -The -.I msg_iov -and -.I msg_iovlen -fields specify scatter-gather locations, as for -.BR writev (2). -.P -You may send control information (ancillary data) using the -.I msg_control -and -.I msg_controllen -members. -The maximum control buffer length the kernel can process is limited -per socket by the value in -.IR /proc/sys/net/core/optmem_max ; -see -.BR socket (7). -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 is ignored. -.\" Still to be documented: -.\" Send file descriptors and user credentials using the -.\" msg_control* fields. -.SH RETURN VALUE -On success, these calls return the number of bytes sent. -On error, \-1 is returned, and -.I errno -is set to indicate the error. -.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 respective manual pages. -.TP -.B 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 -.BR path_resolution (7).) -.IP -(For UDP sockets) An attempt was made to send to a -network/broadcast address as though it was a unicast address. -.TP -.BR EAGAIN " or " EWOULDBLOCK -.\" Actually EAGAIN on Linux -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. -.TP -.B EAGAIN -(Internet domain datagram sockets) -The socket referred to by -.I sockfd -had not previously been bound to an address and, -upon attempting to bind it to an ephemeral port, -it was determined that all port numbers in the ephemeral port range -are currently in use. -See the discussion of -.I /proc/sys/net/ipv4/ip_local_port_range -in -.BR ip (7). -.TP -.B EALREADY -Another Fast Open is in progress. -.TP -.B EBADF -.I sockfd -is not a valid open file descriptor. -.TP -.B ECONNRESET -Connection reset by peer. -.TP -.B EDESTADDRREQ -The socket is not connection-mode, and no peer address is set. -.TP -.B EFAULT -An invalid user space address was specified for an argument. -.TP -.B EINTR -A signal occurred before any data was transmitted; see -.BR signal (7). -.TP -.B EINVAL -Invalid argument passed. -.TP -.B 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.) -.TP -.B EMSGSIZE -The socket type -.\" (e.g., SOCK_DGRAM ) -requires that message be sent atomically, and the size -of the message to be sent made this impossible. -.TP -.B 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.) -.TP -.B ENOMEM -No memory available. -.TP -.B ENOTCONN -The socket is not connected, and no target has been given. -.TP -.B ENOTSOCK -The file descriptor -.I sockfd -does not refer to a socket. -.TP -.B EOPNOTSUPP -Some bit in the -.I flags -argument is inappropriate for the socket type. -.TP -.B EPIPE -The local end has been shut down on a connection oriented socket. -In this case, the process -will also receive a -.B SIGPIPE -unless -.B MSG_NOSIGNAL -is set. -.SH VERSIONS -According to POSIX.1-2001, 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. -.P -.B MSG_CONFIRM -is a Linux extension. -.SH HISTORY -4.4BSD, SVr4, POSIX.1-2001. -(first appeared in 4.2BSD). -.P -POSIX.1-2001 describes only the -.B MSG_OOB -and -.B MSG_EOR -flags. -POSIX.1-2008 adds a specification of -.BR MSG_NOSIGNAL . -.SH NOTES -See -.BR sendmmsg (2) -for information about a Linux-specific system call -that can be used to transmit multiple datagrams in a single call. -.SH BUGS -Linux may return -.B EPIPE -instead of -.BR ENOTCONN . -.SH EXAMPLES -An example of the use of -.BR sendto () -is shown in -.BR getaddrinfo (3). -.SH SEE ALSO -.BR fcntl (2), -.BR getsockopt (2), -.BR recv (2), -.BR select (2), -.BR sendfile (2), -.BR sendmmsg (2), -.BR shutdown (2), -.BR socket (2), -.BR write (2), -.BR cmsg (3), -.BR ip (7), -.BR ipv6 (7), -.BR socket (7), -.BR tcp (7), -.BR udp (7), -.BR unix (7) |