send() — Send data on a socket
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2
Single UNIX Specification, Version 3 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>
ssize_t send(int socket, const void *buffer, size_t length, int flags);
#define _OE_SOCKETS
#include <sys/socket.h>
int send(int socket, char *buffer, int length, int flags);
General description
- Parameter
- Description
- socket
- The socket descriptor.
- msg
- The pointer to the buffer containing the message to transmit.
- length
- The length of the message pointed to by the msg parameter.
- flags
- The flags parameter is set by If more
than one flag is specified, the logical OR operator (|) must be used
to separate them.
- MSG_OOB
-
Sends out-of-band data on sockets that support this notion. Only SOCK_STREAM sockets support out-of-band data. The out-of-band data is a single byte.
Before out-of-band data can be sent between two programs, there must be some coordination of effort. If the data is intended to not be read inline, the recipient of the out-of-band data must specify the recipient of the SIGURG signal that is generated when the out-of-band data is sent. If no recipient is set, no signal is sent. The recipient is set up by using F_SETOWN operand of the fcntl command, specifying either a pid or gid. For more information on this operand, refer to the fcntl command.
The recipient of the data determines whether to receive out-of-band data inline or not inline by the setting of the SO_OOBINLINE option of setsockopt(). For more information on receiving out-of-band data, refer to the setsockopt(), recv(), recvfrom() and recvmsg() commands.
- MSG_DONTROUTE
- The SO_DONTROUTE option is turned on for the duration of the operation. This is usually used only by diagnostic or routing programs.
If there is not enough available buffer space to hold the socket data to be transmitted, and the socket is in blocking mode, send() blocks the caller until additional buffer space becomes available. If the socket is in nonblocking mode, send() returns -1 and sets the error code to EWOULDBLOCK. See fcntl() — Control open file descriptors or ioctl() — Control device for a description of how to set nonblocking mode.
For datagram sockets, this call sends the entire datagram, provided that the datagram fits into the TCP/IP buffers. Stream sockets act like streams of information with no boundaries separating data. For example, if an application wishes to send 1000 bytes, each call to this function can send 1 byte, or 10 bytes, or the entire 1000 bytes. Therefore, applications using stream sockets should place this call in a loop, calling this function until all data has been sent.
Special behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Returned value
If successful, send() returns 0 or greater indicating the number of bytes sent. However, this does not assure that data delivery was complete. A connection can be dropped by a peer socket and a SIGPIPE signal generated at a later time if data delivery is not complete.
- Error Code
- Description
- EBADF
- socket is not a valid socket descriptor.
- ECONNRESET
- A connection was forcibly closed by a peer.
- EDESTADDRREQ
- The socket is not connection-oriented and no peer address is set.
- EFAULT
- Using the msg and length parameters would result in an attempt to access storage outside the caller's address space.
- EINTR
- A signal interrupted send() before any data was transmitted.
- EIO
- There has been a network or transport failure.
- EMSGSIZE
- The message was too big to be sent as a single datagram.
- ENOBUFS
- Buffer space is not available to send the message.
- ENOTCONN
- The socket is not connected.
- ENOTSOCK
- The descriptor is for a file, not for a socket.
- EOPNOTSUPP
- The socket argument is associated with a socket that does not support one or more of the values set in flags.
- EPIPE
- For a connected stream socket the connection to the peer socket has been lost. A SIGPIPE signal is sent to the calling process.
- EWOULDBLOCK
- socket is in nonblocking mode and no data buffers are available or the SO_SNDTIMEO timeout value was reached before buffers became available.
Related information
- sys/socket.h — Sockets definitions
- connect() — Connect a socket
- fcntl() — Control open file descriptors
- getsockopt() — Get the options associated with a socket
- ioctl() — Control device
- read() — Read from a file or socket
- readv() — Read data on a file or socket and store in a set of buffers
- recv() — Receive data on a socket
- recvfrom() — Receive messages on a socket
- recvmsg() — Receive messages on a socket and store in an array of message headers
- select(), pselect() — Monitor activity on files or sockets and message queues
- selectex() — Monitor activity on files or sockets and message queues
- sendmsg() — Send messages on a socket
- sendto() — Send data on a socket
- socket() — Create a socket
- write() — Write data on a file or socket
- writev() — Write data on a file or socket from an array