tfZeroCopyUserBufferSend

Table of Contents >> Programmer's Reference

#include <trsocket.h>

int tfZeroCopyUserBufferSend	(
	int socketDescriptor,
	char TM_FAR * userBufferPtr,
	char TM_FAR * userDataPtr,
	int userDataLength,
	ttUserFreeFuncPtr userFreeFunction,
	int flags
	);

Function Description

Data Socket Send. 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 the buffer and should try and re-send the same buffer later on. The user-defined ttUserFreeFunc() function (pointed to by userFreeFunction) 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. An example of tfZeroCopyUserBufferSend() usage is shown in the loopback test module txscatlp.c.

Parameters

• socketDescriptor

  The socket descriptor to send data to.

• userBufferPtr

  A pointer Treck will use to free the user buffer. This pointer will be passed to the userFreeFunction. It may be identical to userDataPtr.

• userDataPtr

  A pointer to the user data.

• userDataLength

  The size of the user data.

• userFreeFunction

  A pointer to the user-defined ttUserFreeFunc() function called by the stack when the buffer is no longer needed.

• flags

  One of the following:

• 0
• MSG_DONTWAIT
• MSG_DONTROUTE
• MSG_WAITALL
• MSG_OOB

Returns

• >= 0

  The number of bytes transmitted/queued. Treck will free the user buffers.

• TM_SOCKET_ERROR

  Failure.

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