tfZeroCopySend

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int tfZeroCopySend (
int socketDescriptor,
ttUserMessage bufferHandle,
int bufferLength,
int flags
);


Function Description

This function is used to send a zero copy message. It operates identically to send with the exception that it takes a zero copy buffer handle as a parameter, and with the exception that it sends either the whole buffer or nothing.


Note Note: Once tfZeroCopySend() is called, the caller does NOT own the buffer and it is freed by the TCP/IP stack, except when if fails with a TM_EWOULDBLOCK error code, in which case the user can either try and send the buffer at a later time, or free the zero copy buffer using tfFreeZeroCopyBuffer().


Parameters

  • socketDescriptor
    The socket descriptor to send data to.
  • bufferHandle
    The zero copy buffer that contains the message.
  • bufferLength
    The length of the message to send.
  • flags
    See below for possible flags parameters that can be OR'ed together.


Flags

Value Meaning
MSG_DONTWAIT Don't wait for data, 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 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.
MSG_SCATTERED (Non TCP sockets). Set this flag when sending a scattered zero copy recv buffer received with tfZeroCopyRecv(). (See tfZeroCopyRecv().)

Note that to send a user scattered buffer (not obtained via a call to tfZeroCopyRecv()), then tfSocketScatteredSendTo() can be used.


Returns

  • >= 0
    The number of bytes sent.
  • 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_ENOBUFS
    Insufficient memory to complete the operation.
  • TM_EHOSTUNREACH
    Non-TCP socket only. No route to destination.
  • 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 non-TCP sockets.)
  • TM_EMSGSIZE
    The socket is marked as non-blocking and the buffer length exceeds the socket send queue size or the socket requires that the message be sent atomically and the message was too long.
  • TM_EWOULDBLOCK
    The socket is marked as non-blocking, the buffer length is less than or equal to the send queue size and the buffer length exceeds the available space remaining in the socket's send queue.
  • TM_ENOTCONN
    The socket is not connected.
  • TM_ESHUTDOWN
    The user has issued a write shutdown() or a tfClose() call (TCP socket only).
  • TM_EFAULT
    'bufferHandle' does not correspond to a zero copy buffer.
  • TM_EINVAL
    One of the following:
  • bufferLength is less than or equal to 0.
  • flags is something besides what is listed above.


Table of Contents >> Programmer's Reference