tfSocketScatteredSendTo

Table of Contents >> Programmer's Reference

#include <trsocket.h>

int tfSocketScatteredSendTo	(
	int socketDescriptor,
	ttUserBlockPtr userBlockPtr,
	int userBlockCount,
	ttUserFreeFuncPtr userFreeFunction,
	int flags,
	cons struct sockaddr TM_FAR * toAddressPtr,
	int toAddressLength
	);

Function Description

This function allows the user to send data on a non-TCP socket directly from user owned scattered data buffers. The user passes a pointer to an array of user block data of type ttUserBlock, and the number of elements in the array. Each ttUserBlock element contains a pointer to a user buffer, a pointer to the beginning of the user data in the user buffer, and the user data length in the user buffer. Upon return from this routine, the user can reuse the array of ttUserBlock, but the Treck stack owns the user buffers that were pointed to by the ttUserBlock elements. 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 buffers and should try to resend the same buffers later on. The userFreeFunction will be called by the Treck stack for each user buffer 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. An example of tfSocketScatteredSendTo() usage is shown in the loopback test module txscatlp.c.

Note:

If the user uses a preemptive kernel, i.e. TM_TRECK_PREEMPTIVE_KERNEL is defined in <trsystem.h>, it is the user's responsibility to ensure that the user free function is re-entrant, as it could potentially be called from different threads.

Parameters

• socketDescriptor

  As returned by socket().

• userBlockPtr

  Pointer to the first element of the user array that contains information about the user scattered data.

• userBlockCount

  Number of elements in the above array.

• userFreeFunction

  Pointer to the user free function that will be called for each user buffer when the data in the user buffer no longer needs to be accessed. This function is called by the Treck stack with the pointer to the user buffer as a parameter.

• flags

  MSG_DONTWAIT: The call is non-blocking regardless of the blocking mode of the socket.

  0: The call is blocking if the socket is in blocking mode, otherwise it is non-blocking.

• toAddressPtr

  The address to send the data to. If the user had called connect() on the socket then toAddressPtr should be null.

• toAddressLength

  The length of the address.

ttUserBlock

 
#define trsocket.h
 
/*
 * Data type to convey information about scattered send user buffers,
 * in the tfSocketScatteredSendTo() API, and tfIpScatteredSend() API.
 */
typedef struct tsUserBlock
{
/* Pointer to buffer (passed to the free routine) */
    char TM_FAR * userBufferPtr;
/* Pointer to beginning of data */
    char TM_FAR * userDataPtr;
/* Data length */
    int           userDataLength;
} ttUserBlock;
typedef ttUserBlock TM_FAR * ttUserBlockPtr;
 

userFreeFuncPtr

 
int userFreeFunc (char TM_FAR * bufferPtr);
 

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

  Not enough room to queue the data in the socket send queue. User still owns the data user buffers, and is responsible for resending them later on.

• TM_EINVAL

  One of the following:

• userBlockPtr is null
• userBlockCount is less than or equal to 0
• userFreeFunction is null
• socket is a TCP socket with toAddressPtr being non-zero
• flags is something besides 0 or MSG_DONTWAIT.

• TM_ENOBUFS

  Not enough memory to allocate the Treck headers.

• TM_EBADF

  The socket descriptor is invalid.

• TM_EMSGSIZE

  The data length was bigger than the send queue, or the data length caused the IP datagram to be bigger than the IP MTU, and IP fragmentation is not allowed.

• TM_EPROTOTYPE

  Attempt to send on a connected TCP socket.

• TM_EHOSTUNREACH

  No route to host.

• 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.

• TM_ENOENT

  No interface could be found to send the packet out (limited broadcast destination IP address).

• TM_ENXIO

  Outgoing interface is closed.

• TM_EIO

  Interface transmit queue if full (only if interface transmit queue is used).

• (Other)

  Error value passed through from the device driver send function.

Table of Contents >> Programmer's Reference