Jump to: navigation, search

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


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


#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;


int userFreeFunc (char TM_FAR * bufferPtr);


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

    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.
    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.
    Not enough memory to allocate the Treck headers.
    The socket descriptor is invalid.
    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.
    Attempt to send on a connected TCP socket.
    No route to host.
    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.
    No interface could be found to send the packet out (limited broadcast destination IP address).
    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