dag_rx_stream_next_inline(3)

NAME
dag_rx_stream_next_inline - receive (inline) a single ERF record from an Endace DAG card

SYNOPSIS
#include "dagapi.h "

uint8_t*
dag_rx_stream_next_inline(int dagfd, int rx_stream_num, int tx_stream_num);

DESCRIPTION
dag_rx_stream_next_inline can only be used with a DAG that is capable of transmitting packets and configured with the overlap option to set up the memory buffers for inline operation:

For DAG 3 class cards:
    dagthree -d dagN default overlap

For DAG 4 class series:
    dagfour -d dagN default overlap

The dagfwddemo(1) program included in the tools directory of the DAG software release demonstrates the inline capabilities of a DAG card and serves as a fully-functional example for programmers. dagfwddemo(1) applies a user-defined BSD Packet Filter (BPF) expression to each packet received and only retransmits the packets that pass the filter. Two streams are attached and started before this routine is used, one stream for receive and the other for transmit.

The main loop of an inline packet processing application using dag_rx_stream_next_record will look similar to the code in the EXAMPLE section below.

RETURN VALUE
On success dag_rx_stream_next_inline returns a pointer to a single ERF record, otherwise it returns NULL with errno set appropriately.

ERRORS

EBADF
    dagfd is an invalid file descriptor.

EINVAL
    rx_stream_num or tx_stream_num refers to a stream that has not been attached.

EIO the next ERF record has an invalid ERF type. This is usually a fatal error requiring the capture session to be restarted.

ENOTTY
    rx_stream_num or tx_stream_num refers to an invalid stream.

NOTES
The ERF header contains an record length field that specifies the size of the record, so the record length is not returned with the routine call.

EXAMPLE

    while (keep_processing())
    {
    	const char* record = (const char*) dag_rx_stream_next_inline(dagfd, RX_STREAM, TX_STREAM);
    	uint32_t length = ntohs(((dag_record_t*) record)->rlen);
    	process_packet(record, length);

    	dag_tx_stream_commit_bytes(dagfd, TX_STREAM, length);
    }

The user-provided packet processing routine, process(), has up to three functions to perform:

1.  Make application-specific decision about whether the packet is to be dropped or retransmitted.

2.  If the packet is to be dropped then the rx error bit in the ERF header flags byte must be set to 1.

3.  If the packet is to be transmitted out the opposite interface from which it arrived, then the iface field in the ERF header flags must be adjusted.

Some Endace DAG card firmware has the capability to automatically rewrite the interface field in the ERF header so that packets received on interface 0 are transmitted via interface 1 and vice versa. If the DAG card has been configured to rewrite the interface field then the software does not need to perform Step 3 above.

SEE ALSO
dag_advance_stream(3), dag_attach_stream(3), dag_detach_stream(3), dag_get_stream_buffer_level(3), dag_get_stream_buffer_size(3), dag_get_stream_poll(3), dag_rx_get_stream_count(3), dag_rx_stream_next_record(3), dag_set_stream_poll(3), dag_start_stream(3), dag_stop_stream(3).

BUGS
Report bugs to <support@endace.com>.

LAST UPDATED
$Author: koryn $
$Revision: 2481 $
$Date: 2005-11-10 14:52:13 +1300 (Thu, 10 Nov 2005) $

COPYRIGHT
(c) 2004-2005 Endace Technology, Hamilton, New Zealand. All Rights Reserved.