send Subroutine

Edit online

Purpose

Sends messages from a connected socket.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/socketvar.h>
#include <sys/socket.h>
int send (Socket,
Message, Length, Flags)
int  Socket;
const void * Message;
size_t  Length;
int  Flags;

Description

The send subroutine sends a message only when the socket is connected. This subroutine on a socket is not thread safe. The sendto and sendmsg subroutines can be used with unconnected or connected sockets.

To broadcast on a socket, first issue a setsockopt subroutine using the SO_BROADCAST option to gain broadcast permissions.

Specify the length of the message with the Length parameter. If the message is too long to pass through the underlying protocol, the system returns an error and does not transmit the message.

No indication of failure to deliver is implied in a send subroutine. A return value of -1 indicates some locally detected errors.

If no space for messages is available at the sending socket to hold the message to be transmitted, the send subroutine blocks unless the socket is in a nonblocking I/O mode. Use the select subroutine to determine when it is possible to send more data.

The socket applications can be compiled with COMPAT_43 defined. This will make the sockaddr structure BSD 4.3 compatible. For more details refer to socket.h.

Parameters

Item Description
Socket Specifies the unique name for the socket.
Message Points to the address of the message to send.
Length Specifies the length of the message in bytes.
Flags Allows the sender to control the transmission of the message. The Flags parameter used to send a call is formed by logically ORing one or both of the values shown in the following list:
MSG_OOB
Processes out-of-band data on sockets that support SOCK_STREAM communication.
MSG_DONTROUTE
Sends without using routing tables.
MSG_MPEG2
Indicates that this block is a MPEG2 block. This flag is valid SOCK_CONN_DGRAM types of sockets only.

Return Values

Upon successful completion, the send subroutine returns the number of characters sent.

If the send subroutine is unsuccessful, the subroutine handler performs the following functions:

  • Returns a value of -1 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable.

Error Codes

The subroutine is unsuccessful if any of the following errors occurs:

Error Description
EACCES Write access to the named socket is denied, or the socket trying to send a broadcast packet does not have broadcast capability.
EADDRNOTAVAIL The specified address is not a valid address.
EAFNOSUPPORT The specified address is not a valid address for the address family of this socket.
EBADF The Socket parameter is not valid.
ECONNRESET A connection was forcibly closed by a peer.
EDESTADDRREQ The socket is not in connection-mode and no peer address is set.
EFAULT The Address parameter is not in a writable part of the user address space.
EHOSTUNREACH The destination host cannot be reached.
EINTR A signal interrupted send before any data was transmitted.
EINVAL The Length parameter is invalid.
EISCONN A SOCK_DGRAM socket is already connected.
EMSGSIZE The message is too large to be sent all at once, as the socket requires.
ENETUNREACH The destination network is not reachable.
ENOBUFS Insufficient resources were available in the system to perform the operation.
ENOENT The path name does not name an existing file, or the path name is an empty string.
ENOMEM The available data space in memory is not large enough to hold group/ACL information.
ENOTSOCK The Socket parameter refers to a file, not 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 An attempt was made to send on a socket that was connected, but the connection has been shut down either by the remote peer or by this side of the connection. If the socket is of type SOCK_STREAM, the SIGPIPE signal is generated to the calling process.
EWOULDBLOCK The socket is marked nonblocking, and no connections are present to be accepted.