WAND Trace processing  4.0.5
libtrace_format_t Struct Reference

A libtrace capture format module. More...

Collaboration diagram for libtrace_format_t:

Data Fields

const char * name
 The name of this module, used in the libtrace URI to identify the capture format. More...
 
const char * version
 The version of this module. More...
 
enum base_format_t type
 The RT protocol type of this module. More...
 
int(* probe_filename )(const char *fname)
 Given a filename, return if this is the most likely capture format (used for devices). More...
 
int(* probe_magic )(io_t *io)
 Given a file, looks at the start of the file to determine if this is the capture format. More...
 
int(* init_input )(libtrace_t *libtrace)
 Initialises an input trace using the capture format. More...
 
int(* config_input )(libtrace_t *libtrace, trace_option_t option, void *value)
 Applies a configuration option to an input trace. More...
 
int(* start_input )(libtrace_t *libtrace)
 Starts or unpauses an input trace - note that this function is often the one that opens the file or device for reading. More...
 
int(* pause_input )(libtrace_t *libtrace)
 Pauses an input trace - this function should close or detach the file or device that is being read from. More...
 
int(* init_output )(libtrace_out_t *libtrace)
 Initialises an output trace using the capture format. More...
 
int(* config_output )(libtrace_out_t *libtrace, trace_option_output_t option, void *value)
 Applies a configuration option to an output trace. More...
 
int(* start_output )(libtrace_out_t *libtrace)
 Starts an output trace - note that this function is often the one that opens the file or device for writing. More...
 
int(* fin_input )(libtrace_t *libtrace)
 Concludes an input trace and cleans up the capture format data. More...
 
int(* fin_output )(libtrace_out_t *libtrace)
 Concludes an output trace and cleans up the capture format data. More...
 
int(* read_packet )(libtrace_t *libtrace, libtrace_packet_t *packet)
 Reads the next packet from an input trace into the provided packet structure. More...
 
int(* prepare_packet )(libtrace_t *libtrace, libtrace_packet_t *packet, void *buffer, libtrace_rt_types_t rt_type, uint32_t flags)
 Converts a buffer containing a packet record into a libtrace packet. More...
 
void(* fin_packet )(libtrace_packet_t *packet)
 Frees any resources allocated by the capture format module for a libtrace packet. More...
 
int(* write_packet )(libtrace_out_t *libtrace, libtrace_packet_t *packet)
 Write a libtrace packet to an output trace. More...
 
int(* flush_output )(libtrace_out_t *libtrace)
 Flush any buffered output for an output trace. More...
 
libtrace_linktype_t(* get_link_type )(const libtrace_packet_t *packet)
 Returns the libtrace link type for a packet. More...
 
libtrace_direction_t(* get_direction )(const libtrace_packet_t *packet)
 Returns the direction of a packet. More...
 
libtrace_direction_t(* set_direction )(libtrace_packet_t *packet, libtrace_direction_t direction)
 Sets the direction of a packet. More...
 
uint64_t(* get_erf_timestamp )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in the ERF timestamp format. More...
 
struct timeval(* get_timeval )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in the timeval format. More...
 
struct timespec(* get_timespec )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in the timespec format. More...
 
double(* get_seconds )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in floating point seconds. More...
 
int(* seek_erf )(libtrace_t *trace, uint64_t timestamp)
 Moves the read pointer to a certain ERF timestamp within an input trace file. More...
 
int(* seek_timeval )(libtrace_t *trace, struct timeval tv)
 Moves the read pointer to a certain timestamp represented using a timeval within an input trace file. More...
 
int(* seek_seconds )(libtrace_t *trace, double seconds)
 Moves the read pointer to a certain timestamp represented using floating point seconds within an input trace file. More...
 
int(* get_capture_length )(const libtrace_packet_t *packet)
 Returns the payload length of the captured packet record. More...
 
int(* get_wire_length )(const libtrace_packet_t *packet)
 Returns the original length of the packet as it was on the wire. More...
 
int(* get_framing_length )(const libtrace_packet_t *packet)
 Returns the length of the capture format framing header. More...
 
size_t(* set_capture_length )(struct libtrace_packet_t *packet, size_t size)
 Sets the capture length for a packet. More...
 
uint64_t(* get_received_packets )(libtrace_t *trace)
 Returns the number of packets observed by an input trace. More...
 
uint64_t(* get_filtered_packets )(libtrace_t *trace)
 Returns the number of packets filtered by an input trace. More...
 
uint64_t(* get_dropped_packets )(libtrace_t *trace)
 Returns the number of packets dropped by an input trace. More...
 
void(* get_statistics )(libtrace_t *trace, libtrace_stat_t *stat)
 Returns statistics about a trace. More...
 
int(* get_fd )(const libtrace_t *trace)
 Returns the file descriptor used by the input trace. More...
 
struct libtrace_eventobj_t(* trace_event )(libtrace_t *trace, libtrace_packet_t *packet)
 Returns the next libtrace event for the input trace. More...
 
void(* help )(void)
 Prints some useful help information to standard output. More...
 
struct libtrace_format_tnext
 Next pointer, should always be NULL - used by the format module manager. More...
 
struct libtrace_info_t info
 Holds information about the trace format. More...
 
int(* pstart_input )(libtrace_t *trace)
 Starts or unpauses an input trace in parallel mode - note that this function is often the one that opens the file or device for reading. More...
 
int(* pread_packets )(libtrace_t *trace, libtrace_thread_t *t, libtrace_packet_t **packets, size_t nb_packets)
 Read a batch of packets from the input stream related to thread. More...
 
int(* ppause_input )(libtrace_t *trace)
 Pause a parallel trace. More...
 
int(* pfin_input )(libtrace_t *trace)
 Called after all threads have been paused, Finish (close) a parallel trace. More...
 
int(* pregister_thread )(libtrace_t *libtrace, libtrace_thread_t *t, bool reader)
 Register a thread for use with the format or using the packets produced by it. More...
 
void(* punregister_thread )(libtrace_t *libtrace, libtrace_thread_t *t)
 If needed any memory allocated with pregister_thread can be released in this function. More...
 
void(* get_thread_statistics )(libtrace_t *libtrace, libtrace_thread_t *t, libtrace_stat_t *stat)
 Returns statistics for a single thread. More...
 

Detailed Description

A libtrace capture format module.

Field Documentation

int(* libtrace_format_t::config_input)(libtrace_t *libtrace, trace_option_t option, void *value)

Applies a configuration option to an input trace.

Parameters
libtraceThe input trace to apply the option to
optionThe option that is being configured
valueA pointer to the value that the option is to be set to
Returns
0 if successful, -1 if the option is unsupported or an error occurs

Referenced by trace_config(), and trace_set_hasher().

int(* libtrace_format_t::config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value)

Applies a configuration option to an output trace.

Parameters
libtraceThe output trace to apply the option to
optionThe option that is being configured
valueA pointer to the value that the option is to be set to
Returns
0 if successful, -1 if the option is unsupported or an error occurs

Referenced by trace_config_output().

int(* libtrace_format_t::fin_input)(libtrace_t *libtrace)

Concludes an input trace and cleans up the capture format data.

Parameters
libtraceThe input trace to be concluded
Returns
0 if successful, -1 if an error occurs

Libtrace will call the pause_input function if the input trace is currently active prior to calling this function.

Referenced by trace_destroy().

int(* libtrace_format_t::fin_output)(libtrace_out_t *libtrace)

Concludes an output trace and cleans up the capture format data.

Parameters
libtraceThe output trace to be concluded
Returns
0 if successful, -1 if an error occurs

Referenced by trace_destroy_output().

void(* libtrace_format_t::fin_packet)(libtrace_packet_t *packet)

Frees any resources allocated by the capture format module for a libtrace packet.

Parameters
Thepacket to be finalised

Referenced by trace_destroy_packet(), and trace_fin_packet().

int(* libtrace_format_t::flush_output)(libtrace_out_t *libtrace)

Flush any buffered output for an output trace.

Parameters
libtraceThe output trace to be flushed

Referenced by trace_flush_output().

int(* libtrace_format_t::get_capture_length)(const libtrace_packet_t *packet)

Returns the payload length of the captured packet record.

Parameters
packetThe packet to get the capture length from
Returns
The capture length for the packet, or -1 if an error occurs

Capture length is the current size of the packet record itself, following any truncation that may have occurred during the capture process. This length does not include the capture format framing header.

Referenced by trace_get_capture_length().

libtrace_direction_t(* libtrace_format_t::get_direction)(const libtrace_packet_t *packet)

Returns the direction of a packet.

Parameters
packetThe packet to get the direction for
Returns
The direction of the packet, or -1 if no direction tag is present or an error occurs

Referenced by trace_get_direction().

uint64_t(* libtrace_format_t::get_dropped_packets)(libtrace_t *trace)

Returns the number of packets dropped by an input trace.

Parameters
traceThe input trace to get the dropped count for
Returns
The number of packets dropped by the input trace, or UINT64_MAX if the number is unknown

Referenced by trace_get_dropped_packets().

uint64_t(* libtrace_format_t::get_erf_timestamp)(const libtrace_packet_t *packet)

Returns the timestamp for a packet in the ERF timestamp format.

Parameters
packetThe packet to get the timestamp from
Returns
The 64-bit ERF timestamp
Note
Each format must implement at least one of the four "get timestamp" functions.

If not implemented, libtrace will convert the result of one of the other timestamp functions into the appropriate format instead. This means each capture format only needs to implement the most sensible of the four and let libtrace handle any conversions.

Referenced by register_format(), trace_get_erf_timestamp(), and trace_get_seconds().

int(* libtrace_format_t::get_fd)(const libtrace_t *trace)

Returns the file descriptor used by the input trace.

Parameters
traceThe input trace to get the file descriptor for
Returns
The file descriptor used by the input trace to read packets

Referenced by register_format().

uint64_t(* libtrace_format_t::get_filtered_packets)(libtrace_t *trace)

Returns the number of packets filtered by an input trace.

Parameters
traceThe input trace to get the filtered count for
Returns
The number of packets filtered by the input trace, or UINT64_MAX if the number is unknown

Referenced by trace_get_filtered_packets().

int(* libtrace_format_t::get_framing_length)(const libtrace_packet_t *packet)

Returns the length of the capture format framing header.

Parameters
packetThe packet to get the framing length from
Returns
The length of the framing header, or -1 if an error occurs

The framing header is the extra metadata that the capture process records about a packet. The framing length does not include any of the packet payload itself. The total size of the packet record can be calculated be adding this value with the capture length.

Referenced by trace_get_framing_length().

libtrace_linktype_t(* libtrace_format_t::get_link_type)(const libtrace_packet_t *packet)

Returns the libtrace link type for a packet.

Parameters
packetThe packet to get the link type for
Returns
The libtrace link type, or -1 if this link type is unknown

Referenced by trace_get_link_type().

uint64_t(* libtrace_format_t::get_received_packets)(libtrace_t *trace)

Returns the number of packets observed by an input trace.

Parameters
traceThe input trace to get the packet count for
Returns
The number of packets observed by an input trace, or UINT64_MAX if the number is unknown

This count includes packets that have been filtered and dropped.

Referenced by trace_get_received_packets().

double(* libtrace_format_t::get_seconds)(const libtrace_packet_t *packet)

Returns the timestamp for a packet in floating point seconds.

Parameters
packetThe packet to get the timestamp from
Returns
The timestamp from the packet as a floating point number of seconds since 1970-01-01 00:00:00 UTC
Note
Each format must implement at least one of the four "get timestamp" functions.

If not implemented, libtrace will convert the result of one of the other timestamp functions into the appropriate format instead. This means each capture format only needs to implement the most sensible of the four and let libtrace handle any conversions.

Referenced by register_format(), trace_get_erf_timestamp(), and trace_get_seconds().

void(* libtrace_format_t::get_statistics)(libtrace_t *trace, libtrace_stat_t *stat)

Returns statistics about a trace.

Parameters
traceThe libtrace object
stat[in,out] A statistics structure ready to be filled

The filtered and accepted statistics will be set to the values stored in the library. All other statistics are not set.

Note
If filtering of packets is performed by a trace and the number of filtered packets is unknown this should be marked as invalid by the format.

Referenced by trace_get_dropped_packets(), trace_get_filtered_packets(), trace_get_received_packets(), and trace_get_statistics().

void(* libtrace_format_t::get_thread_statistics)(libtrace_t *libtrace, libtrace_thread_t *t, libtrace_stat_t *stat)

Returns statistics for a single thread.

Parameters
traceThe libtrace object
tThe thread to return statistics for
stat[in,out] A statistics structure ready to be filled

The filtered and accepted statistics will be set to the values stored in the library. All other statistics are not set.

Note
If filtering of packets is performed by a trace and the number of filtered packets is unknown this should be marked as invalid by the format.

Referenced by trace_get_thread_statistics().

struct timespec(* libtrace_format_t::get_timespec)(const libtrace_packet_t *packet)

Returns the timestamp for a packet in the timespec format.

Parameters
packetThe packet to get the timestamp from
Returns
The timestamp from the packet as a timespec
Note
Each format must implement at least one of the four "get timestamp" functions.

If not implemented, libtrace will convert the result of one of the other timestamp functions into the appropriate format instead. This means each capture format only needs to implement the most sensible of the four and let libtrace handle any conversions.

Referenced by trace_get_erf_timestamp(), and trace_get_seconds().

struct timeval(* libtrace_format_t::get_timeval)(const libtrace_packet_t *packet)

Returns the timestamp for a packet in the timeval format.

Parameters
packetThe packet to get the timestamp from
Returns
The timestamp from the packet as a timeval
Note
Each format must implement at least one of the four "get timestamp" functions.

If not implemented, libtrace will convert the result of one of the other timestamp functions into the appropriate format instead. This means each capture format only needs to implement the most sensible of the four and let libtrace handle any conversions.

Referenced by register_format(), trace_get_erf_timestamp(), and trace_get_seconds().

int(* libtrace_format_t::get_wire_length)(const libtrace_packet_t *packet)

Returns the original length of the packet as it was on the wire.

Parameters
packetThe packet to get the wire length from
Returns
The length of the packet on the wire at the time of capture, or -1 if an error occurs

Wire length is the original size of the packet prior to any truncation that may have occurred as part of the capture process. This length does not include the capture format framing header.

Referenced by trace_get_wire_length().

void(* libtrace_format_t::help)(void)

Prints some useful help information to standard output.

Referenced by trace_help().

struct libtrace_info_t libtrace_format_t::info

Holds information about the trace format.

Referenced by trace_get_information(), and trace_pstart().

int(* libtrace_format_t::init_input)(libtrace_t *libtrace)

Initialises an input trace using the capture format.

Parameters
libtraceThe input trace to be initialised
Returns
0 if successful, -1 in the event of error

Referenced by register_format(), and trace_create().

int(* libtrace_format_t::init_output)(libtrace_out_t *libtrace)

Initialises an output trace using the capture format.

Parameters
libtraceThe output trace to be initialised
Returns
0 if successful, -1 in the event of error

Referenced by register_format(), and trace_create_output().

const char* libtrace_format_t::name

The name of this module, used in the libtrace URI to identify the capture format.

Referenced by register_format(), trace_create(), trace_create_dead(), trace_create_output(), and trace_write_packet().

struct libtrace_format_t* libtrace_format_t::next

Next pointer, should always be NULL - used by the format module manager.

Referenced by register_format(), trace_create(), trace_create_dead(), trace_create_output(), and trace_help().

int(* libtrace_format_t::pause_input)(libtrace_t *libtrace)

Pauses an input trace - this function should close or detach the file or device that is being read from.

Parameters
libtraceThe input trace to be paused
Returns
0 if successful, -1 in the event of error

Referenced by trace_destroy(), trace_pause(), and trace_pstart().

int(* libtrace_format_t::pfin_input)(libtrace_t *trace)

Called after all threads have been paused, Finish (close) a parallel trace.

Parameters
libtraceThe input trace to be stopped
int(* libtrace_format_t::ppause_input)(libtrace_t *trace)

Pause a parallel trace.

Parameters
libtraceThe input trace to be paused

Referenced by trace_ppause(), and trace_pstart().

int(* libtrace_format_t::pread_packets)(libtrace_t *trace, libtrace_thread_t *t, libtrace_packet_t **packets, size_t nb_packets)

Read a batch of packets from the input stream related to thread.

At most read nb_packets, however should return with less if packets are not waiting. However still must return at least 1, 0 still indicates EOF.

Parameters
libtraceThe input trace
tThe thread
packetsAn array of packets
nb_packetsThe number of packets in the array (the maximum to read)
Returns
The number of packets read, or 0 in the case of EOF or -1 in error or -2 to represent interrupted due to message waiting before packets had been read.
int(* libtrace_format_t::pregister_thread)(libtrace_t *libtrace, libtrace_thread_t *t, bool reader)

Register a thread for use with the format or using the packets produced by it.

This is NOT only used for threads reading packets in fact all threads use this.

The libtrace lock is not held by this format but can be aquired by the format.

Some use cases include setting up any thread local storage required for to read packets and free packets. For DPDK we require any thread that may release or read a packet to have have an internal number associated with it.

The thread type can be used to see if this thread is going to be used to read packets or otherwise.

Returns
0 if successful, -1 if the option is unsupported or an error occurs (such as a maximum of threads being reached)
int(* libtrace_format_t::prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet, void *buffer, libtrace_rt_types_t rt_type, uint32_t flags)

Converts a buffer containing a packet record into a libtrace packet.

Parameters
libtraceAn input trace in the capture format for the packet
packetA libtrace packet to put the prepared packet into
bufferThe buffer containing the packet record (including the capture format header)
rt_typeThe RT type for the packet
flagsFlags describing properties that should be applied to the new packet
Returns
0 if successful, -1 if an error occurs.

Updates internal trace and packet details, such as payload pointers, loss counters and packet types to match the packet record provided in the buffer. This is a zero-copy function.

Intended (at this stage) only for internal use, particularly by RT which needs to decapsulate RT packets

Referenced by trace_prepare_packet().

int(* libtrace_format_t::probe_filename)(const char *fname)

Given a filename, return if this is the most likely capture format (used for devices).

Used to "guess" the capture format when the URI is not fully specified.

Parameters
fnameThe name of the device or file to examine
Returns
1 if the name matches the capture format, 0 otherwise
int(* libtrace_format_t::probe_magic)(io_t *io)

Given a file, looks at the start of the file to determine if this is the capture format.

Used to "guess" the capture format when the URI is not fully specified.

Parameters
ioAn open libtrace IO reader for the file to check
Returns
1 if the file matches the capture format, 0 otherwise
int(* libtrace_format_t::pstart_input)(libtrace_t *trace)

Starts or unpauses an input trace in parallel mode - note that this function is often the one that opens the file or device for reading.

Parameters
libtraceThe input trace to be started or unpaused
Returns
0 upon success. Otherwise in event of an error -1 is returned.

Referenced by trace_pstart().

void(* libtrace_format_t::punregister_thread)(libtrace_t *libtrace, libtrace_thread_t *t)

If needed any memory allocated with pregister_thread can be released in this function.

The thread will be destroyed directly after this function is called.

int(* libtrace_format_t::read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet)

Reads the next packet from an input trace into the provided packet structure.

Parameters
libtraceThe input trace to read from
packetThe libtrace packet to read into
Returns
The size of the packet read (in bytes) including the capture framing header, or -1 if an error occurs. 0 is returned in the event of an EOF or -2 in the case of interrupting the parallel API.

If no packets are available for reading, this function should block until one appears or return 0 if the end of a trace file has been reached.

Referenced by trace_read_packet().

int(* libtrace_format_t::seek_erf)(libtrace_t *trace, uint64_t timestamp)

Moves the read pointer to a certain ERF timestamp within an input trace file.

Parameters
traceThe input trace to seek within
timestampThe timestamp to seek to, as an ERF timestamp
Returns
0 on success, -1 on failure.

The next packet read from this trace will now be the first packet to have a timestamp equal to or greater than the provided timestamp.

Note
Each format that supports seeking must implement at least one of the seek functions.

If not implemented, libtrace will convert the timestamp into the appropriate format to use a seek function that has been implemented. This means each capture format only needs to implement the seek function that matches the native timestamp format for that capture.

Referenced by trace_seek_erf_timestamp(), trace_seek_seconds(), and trace_seek_timeval().

int(* libtrace_format_t::seek_seconds)(libtrace_t *trace, double seconds)

Moves the read pointer to a certain timestamp represented using floating point seconds within an input trace file.

Parameters
traceThe input trace to seek within
timestampThe timestamp to seek to, as floating point seconds since 1970-01-01 00:00:00 UTC
Returns
0 on success, -1 on failure.

The next packet read from this trace will now be the first packet to have a timestamp equal to or greater than the provided timestamp.

Note
Each format that supports seeking must implement at least one of the seek functions.

If not implemented, libtrace will convert the timestamp into the appropriate format to use a seek function that has been implemented. This means each capture format only needs to implement the seek function that matches the native timestamp format for that capture.

Referenced by trace_seek_erf_timestamp(), trace_seek_seconds(), and trace_seek_timeval().

int(* libtrace_format_t::seek_timeval)(libtrace_t *trace, struct timeval tv)

Moves the read pointer to a certain timestamp represented using a timeval within an input trace file.

Parameters
traceThe input trace to seek within
timestampThe timestamp to seek to, as a timeval
Returns
0 on success, -1 on failure.

The next packet read from this trace will now be the first packet to have a timestamp equal to or greater than the provided timestamp.

Note
Each format that supports seeking must implement at least one of the seek functions.

If not implemented, libtrace will convert the timestamp into the appropriate format to use a seek function that has been implemented. This means each capture format only needs to implement the seek function that matches the native timestamp format for that capture.

Referenced by trace_seek_erf_timestamp(), trace_seek_seconds(), and trace_seek_timeval().

size_t(* libtrace_format_t::set_capture_length)(struct libtrace_packet_t *packet, size_t size)

Sets the capture length for a packet.

Parameters
packetThe packet to adjust the capture length for.
sizeThe new capture length
Returns
The new capture length of the packet, or -1 if an error occurs
Note
This function should only reduce the capture length. If the provided length is larger than the current capture length, -1 should be returned.

Referenced by trace_set_capture_length().

libtrace_direction_t(* libtrace_format_t::set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction)

Sets the direction of a packet.

Parameters
packetThe packet to set the direction for
directionThe direction to assign to the packet
Returns
The updated direction for the packet, or -1 if an error occurs
Note
Some capture formats do not feature direction tagging, so it will not make sense to implement a set_direction function for them.

Referenced by trace_set_direction().

int(* libtrace_format_t::start_input)(libtrace_t *libtrace)

Starts or unpauses an input trace - note that this function is often the one that opens the file or device for reading.

Parameters
libtraceThe input trace to be started or unpaused
Returns
0 if successful, -1 in the event of error

Referenced by trace_pstart(), and trace_start().

int(* libtrace_format_t::start_output)(libtrace_out_t *libtrace)

Starts an output trace - note that this function is often the one that opens the file or device for writing.

Parameters
libtraceThe output trace to be started
Returns
0 if successful, -1 if an error occurs

There is no pause for output traces, as writing is not performed asynchronously.

Referenced by trace_start_output().

struct libtrace_eventobj_t(* libtrace_format_t::trace_event)(libtrace_t *trace, libtrace_packet_t *packet)

Returns the next libtrace event for the input trace.

Parameters
traceThe input trace to get the next event from
packetA libtrace packet to read a packet into
Returns
A libtrace event describing the event that occured

The event API allows for non-blocking reading of packets from an input trace. If a packet is available and ready to be read, a packet event should be returned. Otherwise a sleep or fd event should be returned to indicate that the caller needs to wait. If the input trace has an error or reaches EOF, a terminate event should be returned.

Referenced by register_format(), and trace_event().

enum base_format_t libtrace_format_t::type

The RT protocol type of this module.

Referenced by promote_packet(), and trace_get_format().

const char* libtrace_format_t::version

The version of this module.

int(* libtrace_format_t::write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet)

Write a libtrace packet to an output trace.

Parameters
libtraceThe output trace to write the packet to
packetThe packet to be written out
Returns
The number of bytes written, or -1 if an error occurs

Referenced by trace_write_packet().


The documentation for this struct was generated from the following file: