tfZeroCopyUserBufferSendTo

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.


Parameters

  • 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
  • MSG_DONTWAIT
  • MSG_DONTROUTE
  • MSG_OOB
  • toAddressPtr
    The address to send the data to.
  • toAddressLength
    The length of the destination address.


Returns

  • >= 0
    The number of bytes transmitted/queued. Treck will free the user buffers.
  • 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_EWOULDBLOCK
    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.
  • TM_EINVAL
    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.
  • TM_ENOBUFS
    Not enough memory to allocate the Treck headers.
  • TM_EBADF
    The socket descriptor is invalid.
  • TM_EMSGSIZE
    The data length was larger than the socket's send queue.
  • TM_EHOSTUNREACH
    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.


Table of Contents >> Programmer's Reference