Data Fields

libtrace_format_t Struct Reference

A libtrace capture format module. More...

Collaboration diagram for libtrace_format_t:
Collaboration graph
[legend]

Data Fields

const char * name
 The name of this module, used in the libtrace URI to identify the capture format.
const char * version
 The version of this module.
enum base_format_t type
 The RT protocol type of this module.
int(* probe_filename )(const char *fname)
 Given a filename, return if this is the most likely capture format (used for devices).
int(* probe_magic )(io_t *io)
 Given a file, looks at the start of the file to determine if this is the capture format.
int(* init_input )(libtrace_t *libtrace)
 Initialises an input trace using the capture format.
int(* config_input )(libtrace_t *libtrace, trace_option_t option, void *value)
 Applies a configuration option to an input trace.
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.
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.
int(* init_output )(libtrace_out_t *libtrace)
 Initialises an output trace using the capture format.
int(* config_output )(libtrace_out_t *libtrace, trace_option_output_t option, void *value)
 Applies a configuration option to an output trace.
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.
int(* fin_input )(libtrace_t *libtrace)
 Concludes an input trace and cleans up the capture format data.
int(* fin_output )(libtrace_out_t *libtrace)
 Concludes an output trace and cleans up the capture format data.
int(* read_packet )(libtrace_t *libtrace, libtrace_packet_t *packet)
 Reads the next packet from an input trace into the provided packet structure.
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.
void(* fin_packet )(libtrace_packet_t *packet)
 Frees any resources allocated by the capture format module for a libtrace packet.
int(* write_packet )(libtrace_out_t *libtrace, libtrace_packet_t *packet)
 Write a libtrace packet to an output trace.
libtrace_linktype_t(* get_link_type )(const libtrace_packet_t *packet)
 Returns the libtrace link type for a packet.
libtrace_direction_t(* get_direction )(const libtrace_packet_t *packet)
 Returns the direction of a packet.
libtrace_direction_t(* set_direction )(libtrace_packet_t *packet, libtrace_direction_t direction)
 Sets the direction of a packet.
uint64_t(* get_erf_timestamp )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in the ERF timestamp format.
struct timeval(* get_timeval )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in the timeval format.
struct timespec(* get_timespec )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in the timespec format.
double(* get_seconds )(const libtrace_packet_t *packet)
 Returns the timestamp for a packet in floating point seconds.
int(* seek_erf )(libtrace_t *trace, uint64_t timestamp)
 Moves the read pointer to a certain ERF timestamp within an input trace file.
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.
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.
int(* get_capture_length )(const libtrace_packet_t *packet)
 Returns the payload length of the captured packet record.
int(* get_wire_length )(const libtrace_packet_t *packet)
 Returns the original length of the packet as it was on the wire.
int(* get_framing_length )(const libtrace_packet_t *packet)
 Returns the length of the capture format framing header.
size_t(* set_capture_length )(struct libtrace_packet_t *packet, size_t size)
 Sets the capture length for a packet.
uint64_t(* get_received_packets )(libtrace_t *trace)
 Returns the number of packets observed by an input trace.
uint64_t(* get_filtered_packets )(libtrace_t *trace)
 Returns the number of packets filtered by an input trace.
uint64_t(* get_dropped_packets )(libtrace_t *trace)
 Returns the number of packets dropped by an input trace.
uint64_t(* get_captured_packets )(libtrace_t *trace)
 Returns the number of packets captured and returned by an input trace.
int(* get_fd )(const libtrace_t *trace)
 Returns the file descriptor used by the input trace.
struct libtrace_eventobj_t(* trace_event )(libtrace_t *trace, libtrace_packet_t *packet)
 Returns the next libtrace event for the input trace.
void(* help )(void)
 Prints some useful help information to standard output.
struct libtrace_format_tnext
 Next pointer, should always be NULL - used by the format module manager.

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:
libtrace The input trace to apply the option to
option The option that is being configured
value A 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().

Applies a configuration option to an output trace.

Parameters:
libtrace The output trace to apply the option to
option The option that is being configured
value A 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().

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

Parameters:
libtrace The 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().

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

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

Referenced by trace_destroy_output().

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

Parameters:
The packet to be finalised

Referenced by trace_read_packet().

Returns the payload length of the captured packet record.

Parameters:
packet The 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().

Returns the number of packets captured and returned by an input trace.

Parameters:
trace The input trace to get the capture count for
Returns:
The number of packets returned to the libtrace user, or UINT64_MAX if the number is unknown

This is the number of packets that have been successfully returned to the libtrace user via the read_packet() function.

Returns the direction of a packet.

Parameters:
packet The 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().

Returns the number of packets dropped by an input trace.

Parameters:
trace The 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(), and trace_get_filtered_packets().

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

Parameters:
packet The 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:
trace The input trace to get the file descriptor for
Returns:
The file descriptor used by the input trace to read packets

Referenced by register_format().

Returns the number of packets filtered by an input trace.

Parameters:
trace The 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().

Returns the length of the capture format framing header.

Parameters:
packet The 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().

Returns the libtrace link type for a packet.

Parameters:
packet The 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().

Returns the number of packets observed by an input trace.

Parameters:
trace The 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_filtered_packets(), and trace_get_received_packets().

Returns the timestamp for a packet in floating point seconds.

Parameters:
packet The 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().

struct timespec(* libtrace_format_t::get_timespec)(const libtrace_packet_t *packet) [read]

Returns the timestamp for a packet in the timespec format.

Parameters:
packet The 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) [read]

Returns the timestamp for a packet in the timeval format.

Parameters:
packet The 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().

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

Parameters:
packet The 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().

Initialises an input trace using the capture format.

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

Referenced by register_format(), and trace_create().

Initialises an output trace using the capture format.

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

Referenced by register_format(), and trace_create_output().

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

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

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

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

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

Referenced by trace_destroy(), and trace_pause().

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:
libtrace An input trace in the capture format for the packet
packet A libtrace packet to put the prepared packet into
buffer The buffer containing the packet record (including the capture format header)
rt_type The RT type for the packet
flags Flags 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:
fname The name of the device or file to examine
Returns:
1 if the name matches the capture format, 0 otherwise

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:
io An open libtrace IO reader for the file to check
Returns:
1 if the file matches the capture format, 0 otherwise

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

Parameters:
libtrace The input trace to read from
packet The 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.

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:
trace The input trace to seek within
timestamp The 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:
trace The input trace to seek within
timestamp The 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:
trace The input trace to seek within
timestamp The 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:
packet The packet to adjust the capture length for.
size The 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().

Sets the direction of a packet.

Parameters:
packet The packet to set the direction for
direction The 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().

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

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

Referenced by trace_start().

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

Parameters:
libtrace The 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().

Returns the next libtrace event for the input trace.

Parameters:
trace The input trace to get the next event from
packet A 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().

The RT protocol type of this module.

Referenced by promote_packet(), and trace_get_format().

The version of this module.

Write a libtrace packet to an output trace.

Parameters:
libtrace The output trace to write the packet to
packet The 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: