A libtrace capture format module. More...
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_t * | next |
Next pointer, should always be NULL - used by the format module manager. |
A libtrace capture format module.
int(* libtrace_format_t::config_input)(libtrace_t *libtrace, trace_option_t option, void *value) |
Applies a configuration option to an input trace.
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 |
Referenced by trace_config().
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.
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 |
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.
libtrace | The input trace to be concluded |
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.
libtrace | The output trace to be concluded |
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.
The | packet to be finalised |
Referenced by trace_read_packet().
int(* libtrace_format_t::get_capture_length)(const libtrace_packet_t *packet) |
Returns the payload length of the captured packet record.
packet | The packet to get the capture length from |
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().
uint64_t(* libtrace_format_t::get_captured_packets)(libtrace_t *trace) |
Returns the number of packets captured and returned by an input trace.
trace | The input trace to get the capture count for |
This is the number of packets that have been successfully returned to the libtrace user via the read_packet() function.
libtrace_direction_t(* libtrace_format_t::get_direction)(const libtrace_packet_t *packet) |
Returns the direction of a packet.
packet | The packet to get the direction for |
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.
trace | The input trace to get the dropped count for |
Referenced by trace_get_dropped_packets(), and trace_get_filtered_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.
packet | The packet to get the timestamp from |
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.
trace | The input trace to get the file descriptor for |
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.
trace | The input trace to get the filtered count for |
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.
packet | The packet to get the framing length from |
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.
packet | The packet to get the link type for |
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.
trace | The input trace to get the packet count for |
This count includes packets that have been filtered and dropped.
Referenced by trace_get_filtered_packets(), and 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.
packet | The packet to get the timestamp from |
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.
packet | The packet to get the timestamp from |
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.
packet | The packet to get the timestamp from |
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.
packet | The packet to get the wire length from |
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().
int(* libtrace_format_t::init_input)(libtrace_t *libtrace) |
Initialises an input trace using the capture format.
libtrace | The input trace to be initialised |
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.
libtrace | The output trace to be initialised |
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(), 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().
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.
libtrace | The input trace to be paused |
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.
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 |
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.
fname | The name of the device or file to examine |
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.
io | An open libtrace IO reader for the file to check |
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.
libtrace | The input trace to read from | |
packet | The libtrace packet to read into |
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.
trace | The input trace to seek within | |
timestamp | The timestamp to seek to, as an ERF timestamp |
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.
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.
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 |
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.
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.
trace | The input trace to seek within | |
timestamp | The timestamp to seek to, as a timeval |
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.
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.
packet | The packet to adjust the capture length for. | |
size | The new capture length |
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.
packet | The packet to set the direction for | |
direction | The direction to assign to the packet |
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.
libtrace | The input trace to be started or unpaused |
Referenced by 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.
libtrace | The output trace to be started |
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) [read] |
Returns the next libtrace event for the input trace.
trace | The input trace to get the next event from | |
packet | A libtrace packet to read a packet into |
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().
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.
libtrace | The output trace to write the packet to | |
packet | The packet to be written out |
Referenced by trace_write_packet().