send

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int send (
int socketDescriptor,
char * bufferPtr,
int bufferLength,
int flags
);


Function Description

send() is used to transmit a message to another transport end-point. send() may be used only when the socket is in a connected state. socketDescriptor is a socket created with socket(). If the message is too long to pass atomically through the underlying protocol (non-TCP protocol), then the error TM_EMSGSIZE is returned and the message is not transmitted. A return value of TM_SOCKET_ERROR indicates locally detected errors only. A positive return value does not implicitly mean the message was delivered, but rather that it was sent.

Blocking socket send()

If the socket does not have enough buffer space available to hold the message being sent, send blocks.

Non-blocking stream (TCP or SCTP) socket send()

If the socket does not have enough buffer space available to hold the message being sent, the send call does not block. It can send as much data from the message as can fit in the socket send buffer and returns the length of the data sent. If none of the message data fits, then TM_SOCKET_ERROR is returned with socket error being set to TM_EWOULDBLOCK.

Non-blocking datagram socket send()

If the socket does not have enough buffer space available to hold the message being sent, no data is being sent and TM_SOCKET_ERROR is returned with socket error being set to TM_EWOULDBLOCK. The select() call may be used to determine when it is possible to send more data.


Sending Out-of-Band Data

For example, if you have remote login application, and you want to interrupt with a ^C keystroke, at the socket level you want to be able to send the ^C flagged as special data (also called out-of-band data). You also want the TCP protocol to let the peer (or remote) TCP know as soon as possible that a special character is coming, and you want the peer (or remote) TCP to notify the peer (or remote) application as soon as possible.

At the TCP level, this mechanism is called TCP urgent data. At the socket level, the mechanism is called out-of-band data. Out-of-band data generated by the socket layer, is implemented at the TCP layer with the urgent data mechanism. The user application can send one or several out-of-band data bytes. With TCP you cannot send the out-of-band data ahead of the data that has already been buffered in the TCP send buffer, but you can let the other side know (with the urgent flag, i.e. the term urgent data) that out-of-band data is coming, and you can let the peer TCP know the offset of the current data to the last byte of out-of-band data.

So with TCP, the out-of-band data byte(s) are not sent ahead of the data stream, but the TCP protocol can notify the remote TCP ahead of time that some out-of-band data byte(s) exist. What TCP does, is mark the byte stream where urgent data ends, and set the Urgent flag bit in the TCP header flag field, as long as it is sending data before, or up to, the last byte of out-of-band data.

In your application, you can send out-of-band data, by calling the send function with the MSG_OOB flag. All the bytes of data sent that way (using send() with the MSG_OOB flag) are out-of-band data bytes. Note that if you call send() several times with out-of-band data, TCP will always keep track of where the last out-of-band byte of data is in the byte data stream, and flag this byte as the last byte of urgent data. To receive out-of-band data, please see the recv() section of this manual.


Parameters

  • socketDescriptor
    The socket descriptor to use to send the data.
  • bufferPtr
    A pointer to the buffer to send.
  • bufferLength
    The length of the buffer to send.
  • flags
    See below for possible flags parameters that can be OR'ed together.


Flags

Value Meaning
MSG_DONTWAIT Don't wait for the data send to complete, but rather return immediately.
MSG_OOB Send "out-of-band" data on sockets that support this notion. The underlying protocol must also support "out-of-band" data. Only TCP SOCK_STREAM sockets created in the AF_INET address family support out-of-band data.
MSG_DONTROUTE The SO_DONTROUTE option is turned on for the duration of the operation. Only diagnostic or routing programs use it.


Return Values

  • >= 0
    Number of bytes actually sent on the socket.
  • TM_SOCKET_ERROR
    Failure.


Note Note: TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself.

To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).


Possible socket errors

  • TM_EBADF
    The socket descriptor is invalid.
  • TM_EINVAL
    One of the following:
  • bufferPtr is 0.
  • bufferLength is less than or equal to 0.
  • flags is something besides what is listed above.
  • TM_ENOBUFS
    Insufficient memory to complete the operation.
  • TM_EHOSTUNREACH
    No route to destination. (For sockets other than TCP or SCTP.)
  • TM_ECONNREFUSED
    The socket received an ICMP destination unreachable message from the remote host. This typically means that the receiver is not listening on the remote port. (For sockets other than TCP or SCTP.)
  • TM_EMSGSIZE
    The socket requires that the message be sent atomically and the message was too long.
  • TM_EWOULDBLOCK
    The socket is marked as non-blocking and the send() operation would block.
  • TM_ENOTCONN
    The socket is not connected.
  • TM_ESHUTDOWN
    The user has issued a write shutdown() or a tfClose() call (TCP or SCTP socket only).
  • TM_ETIMEDOUT
    The TCP connection has timed out.


Table of Contents >> Programmer's Reference