Jump to: navigation, search

Table of Contents >> Programmer's Reference

#include <trsocket.h>

int tfZeroCopyUserBufferSendTo (
int socketDescriptor,
char TM_FAR * userBufferPtr,
char TM_FAR * userDataPtr,
int userDataLength,
ttUserFreeFuncPtr userFreeFunction,
int flags,
cont struct sockaddr TM_FAR * toAddressPtr,
int toAddressLength

Function Description

Allows the user to send data on a socket directly from user owned data buffers without having to copy the data. Upon return from this routine, the user no longer owns its buffer.The only exception is when TM_SOCKET_ERROR is returned and the errorCode retrieved with tfGetSocketError() is TM_EWOULDBLOCK. In that case the user still owns its buffer and should try and re-send the same buffer later on. The userFreeFunction (type ttUserFreeFunc) will be called by the Treck stack for each user buffer if an error other than TM_EWOULDBLOCK occurs, or when the data has been sent out on the network, and the device driver no longer needs to access the data in the user buffer. It is the user's responsibility to ensure that the userFreeFunction is re-entrant as it could potentially be called from different threads, unless the user uses a different free function per user application thread and the user does not use a Treck transmit task and does not use a Treck send (complete) task.

Note Note: An example of tfZeroCopyUserBufferSendTo() usage is shown in the loopback test module txscatlp.c.


  • socketDescriptor
    The socket descriptor to send data to.
  • userBufferPtr
    A pointer to the user buffer to be used when calling the userFreeFunction.
  • userDataPtr
    A pointer to the user data.
  • userDataLength
    The size of the user data.
  • userFreeFunction
    The function (type ttUserFreeFunc) called by the stack when the buffer is no longer needed.
  • flags
    One of the following:
  • 0
  • toAddressPtr
    The address to send the data to.
  • toAddressLength
    The length of the destination address.


  • >= 0
    The number of bytes transmitted/queued. Treck will free the user buffers.

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

    There is not enough room in the socket's send queue to queue the data. The user still owns the user buffer and is responsible for re-sending later on.
    One of the following:
  • userBufferPtr is 0.
  • userDataPtr is 0.
  • userDataLength is 0 or -1.
  • userFreeFunction is 0.
  • flags is something besides what is listed above.
    Not enough memory to allocate the Treck headers.
    The socket descriptor is invalid.
    The data length was larger than the socket's send queue.
    No route to destination.
    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.

Table of Contents >> Programmer's Reference