HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |VERSIONS |STANDARDS |HISTORY |NOTES |BUGS |EXAMPLES |SEE ALSO |COLOPHON | |
send(2) System Calls Manualsend(2)send, sendto, sendmsg - send a message on a socket
Standard C library (libc,-lc)
#include <sys/socket.h>ssize_t send(size_t size;intsockfd, const voidbuf[size], size_tsize, intflags);ssize_t sendto(size_t size;intsockfd, const voidbuf[size], size_tsize, intflags,const struct sockaddr *dest_addr, socklen_taddrlen);ssize_t sendmsg(intsockfd, const struct msghdr *msg, intflags);
The system callssend(),sendto(), andsendmsg() are used to transmit a message to another socket. Thesend() call may be used only when the socket is in aconnected state (so that the intended recipient is known). The only difference betweensend() andwrite(2) is the presence offlags. With a zeroflags argument,send() is equivalent towrite(2). Also, the following call send(sockfd, buf, size, flags); is equivalent to sendto(sockfd, buf, size, flags, NULL, 0); The argumentsockfd is the file descriptor of the sending socket. Ifsendto() is used on a connection-mode (SOCK_STREAM,SOCK_SEQPACKET) socket, the argumentsdest_addr andaddrlen are ignored (and the errorEISCONNmay be returned when they are not NULL and 0), and the errorENOTCONNis returned when the socket was not actually connected. Otherwise, the address of the target is given bydest_addr withaddrlen specifying its size. Forsendmsg(), the address of the target is given bymsg.msg_name, withmsg.msg_namelen specifying its size. Forsend() andsendto(), the message is found inbuf and has sizesize. Forsendmsg(), the message is pointed to by the elements of the arraymsg.msg_iov. Thesendmsg() call also allows sending ancillary data (also known as control information). If the message is too long to pass atomically through the underlying protocol, the errorEMSGSIZEis returned, and the message is not transmitted. No indication of failure to deliver is implicit in asend(). Locally detected errors are indicated by a return value of -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 errorEAGAINorEWOULDBLOCKin this case. Theselect(2) call may be used to determine when it is possible to send more data.The flags argument Theflags argument is the bitwise OR of zero or more of the following flags.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 onSOCK_DGRAMandSOCK_RAWsockets and currently implemented only for IPv4 and IPv6. Seearp(7) for details.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.MSG_DONTWAIT(since Linux 2.2) Enables nonblocking operation; if the operation would block,EAGAINorEWOULDBLOCKis returned. This provides similar behavior to setting theO_NONBLOCKflag (via thefcntl(2)F_SETFLoperation), but differs in thatMSG_DONTWAITis a per-call option, whereasO_NONBLOCKis a setting on the open file description (seeopen(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.MSG_EOR(since Linux 2.2) Terminates a record (when this notion is supported, as for sockets of typeSOCK_SEQPACKET).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 theTCP_CORK socket option (seetcp(7)), with the difference that this flag can be set on a per-call basis. 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 theUDP_CORKsocket option described inudp(7).)MSG_NOSIGNAL(since Linux 2.2) Don't generate aSIGPIPEsignal if the peer on a stream- oriented socket has closed the connection. TheEPIPEerror is still returned. This provides similar behavior to usingsigaction(2) to ignoreSIGPIPE, but, whereasMSG_NOSIGNAL is a per-call feature, ignoringSIGPIPEsets a process attribute that affects all threads in the process.MSG_OOB Sendsout-of-band data on sockets that support this notion (e.g., of typeSOCK_STREAM); the underlying protocol must also supportout-of-band data.MSG_FASTOPEN(since Linux 3.7) Attempts TCP Fast Open (RFC7413) and sends data in the SYN like a combination ofconnect(2) andwrite(2), by performing an implicitconnect(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 returnsEINPROGRESS, 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 sameerrno asconnect(2) if the handshake fails. This flag requires enabling TCP Fast Open client support on sysctlnet.ipv4.tcp_fastopen. Refer toTCP_FASTOPEN_CONNECTsocket option intcp(7) for an alternative approach.sendmsg() The definition of themsghdr structure employed bysendmsg() is as follows: 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 size */ int msg_flags; /* Flags (unused) */ }; Themsg_name field is used on an unconnected socket to specify the target address for a datagram. It points to a buffer containing the address; themsg_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. Themsg_iov andmsg_iovlen fields specify scatter-gather locations, as forwritev(2). You may send control information (ancillary data) using themsg_control andmsg_controllen members. The maximum control buffer size the kernel can process is limited per socket by the value in/proc/sys/net/core/optmem_max; seesocket(7). For further information on the use of ancillary data in various socket domains, seeunix(7) andip(7). Themsg_flags field is ignored.On success, these calls return the number of bytes sent. On error, -1 is returned, anderrno is set to indicate the error.
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.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. (Seepath_resolution(7).) (For UDP sockets) An attempt was made to send to a network/broadcast address as though it was a unicast address.EAGAINorEWOULDBLOCK 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.EAGAIN(Internet domain datagram sockets) The socket referred to bysockfd 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/proc/sys/net/ipv4/ip_local_port_range inip(7).EALREADY Another Fast Open is in progress.EBADFsockfd is not a valid open file descriptor.ECONNRESET Connection reset by peer.EDESTADDRREQ The socket is not connection-mode, and no peer address is set.EFAULTAn invalid user space address was specified for an argument.EINTRA signal occurred before any data was transmitted; seesignal(7).EINVALInvalid 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.)EMSGSIZE The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible.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.)ENOMEMNo memory available.ENOTCONN The socket is not connected, and no target has been given.ENOTSOCK The file descriptorsockfd does not refer to a socket.EOPNOTSUPP Some bit in theflags argument is inappropriate for the socket type.EPIPEThe local end has been shut down on a connection oriented socket. In this case, the process will also receive aSIGPIPEunlessMSG_NOSIGNALis set.
According to POSIX.1-2001, themsg_controllen field of themsghdr structure should be typed assocklen_t, and themsg_iovlen field should be typed asint, but glibc currently types both assize_t.
POSIX.1-2008.MSG_CONFIRMis a Linux extension.
4.4BSD, SVr4, POSIX.1-2001. (first appeared in 4.2BSD). POSIX.1-2001 describes only theMSG_OOBandMSG_EORflags. POSIX.1-2008 adds a specification ofMSG_NOSIGNAL.
Seesendmmsg(2) for information about a Linux-specific system call that can be used to transmit multiple datagrams in a single call.
Linux may returnEPIPEinstead ofENOTCONN.
An example of the use ofsendto() is shown ingetaddrinfo(3).
fcntl(2),getsockopt(2),recv(2),select(2),sendfile(2),sendmmsg(2),shutdown(2),socket(2),write(2),cmsg(3),ip(7),ipv6(7),socket(7),tcp(7),udp(7),unix(7)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-06-28send(2)Pages that refer to this page:getrlimit(2), io_uring_enter2(2), io_uring_enter(2), recvmmsg(2), select(2), select_tut(2), sendmmsg(2), socket(2), socketcall(2), splice(2), syscalls(2), audit_request_features(3), cmsg(3), getaddrinfo(3), getifaddrs(3), if_nameindex(3), io_uring_prep_send(3), io_uring_prep_send_bundle(3), io_uring_prep_sendmsg(3), io_uring_prep_sendmsg_zc(3), io_uring_prep_send_set_addr(3), io_uring_prep_sendto(3), io_uring_prep_send_zc(3), io_uring_prep_send_zc_fixed(3), rtime(3), size_t(3type), sockaddr(3type), sockatmark(3), arp(7), bpf-helpers(7), ddp(7), ip(7), ipv6(7), landlock(7), mctp(7), netlink(7), packet(7), raw(7), sctp(7), signal(7), signal-safety(7), socket(7), tcp(7), udp(7), unix(7), vsock(7), trafgen(8)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |