Data Structures | Defines | Typedefs | Enumerations | Functions | Variables

libtrace_int.h File Reference

Header file containing definitions for structures and functions that are internal. More...

Go to the source code of this file.

Data Structures

struct  libtrace_event_status_t
 Data about the most recent event from a trace file. More...
struct  libtrace_t
 A libtrace input trace. More...
struct  libtrace_out_t
 A libtrace output trace. More...
struct  libtrace_pflog_header_t
 A local definition of a PFLOG header. More...
struct  libtrace_format_t
 A libtrace capture format module. More...
struct  libtrace_filter_t
 BPF not supported by this system, but we still need to define a structure for the filter. More...
struct  libtrace_pcapfile_pkt_hdr_t
 Local definition of a PCAP header. More...

Defines

#define PF_RULESET_NAME_SIZE   16
#define IFNAMSIZ   16
#define TRACE_RADIOTAP_F_FCS   0x10
Byte ordering

Macros that define how to convert a value into a particular byte-order

#define bswap_host_to_be64(num)   ((uint64_t)(num))
#define bswap_host_to_le64(num)   byteswap64(num)
#define bswap_host_to_be32(num)   ((uint32_t)(num))
#define bswap_host_to_le32(num)   byteswap32(num)
#define bswap_host_to_be16(num)   ((uint16_t)(num))
#define bswap_host_to_le16(num)   byteswap16(num)
#define bswap_be_to_host64(num)   ((uint64_t)(num))
#define bswap_le_to_host64(num)   byteswap64(num)
#define bswap_be_to_host32(num)   ((uint32_t)(num))
#define bswap_le_to_host32(num)   byteswap32(num)
#define bswap_be_to_host16(num)   ((uint16_t)(num))
#define bswap_le_to_host16(num)   byteswap16(num)

Typedefs

typedef struct
libtrace_pflog_header_t 
libtrace_pflog_header_t
 A local definition of a PFLOG header.
typedef struct
libtrace_pcapfile_pkt_hdr_t 
libtrace_pcapfile_pkt_hdr_t
 Local definition of a PCAP header.

Enumerations

enum  { TRACE_PREP_OWN_BUFFER = 1, TRACE_PREP_DO_NOT_OWN_BUFFER = 0 }
 

Flags for prepare_packet functions.

More...

Functions

char * strndup (const char *s, size_t size)
int strncasecmp (const char *str1, const char *str2, size_t n)
 A local implementation of strncasecmp (as some systems do not have it).
int snprintf (char *str, size_t size, const char *format,...)
 A local implementation of snprintf (as some systems do not have it).
void trace_set_err (libtrace_t *trace, int errcode, const char *msg,...) PRINTF(3
 Sets the error status on an input trace.
void void trace_set_err_out (libtrace_out_t *trace, int errcode, const char *msg,...) PRINTF(3
 Sets the error status on an output trace.
void void void trace_clear_cache (libtrace_packet_t *packet)
 Clears the cached values for a libtrace packet.
int trace_prepare_packet (libtrace_t *trace, libtrace_packet_t *packet, void *buffer, libtrace_rt_types_t rt_type, uint32_t flags)
 Converts the data provided in buffer into a valid libtrace packet.
void register_format (struct libtrace_format_t *format)
 Registers a new capture format module.
libtrace_linktype_t pcap_linktype_to_libtrace (libtrace_dlt_t linktype)
 Converts a PCAP DLT into a libtrace link type.
libtrace_rt_types_t pcap_linktype_to_rt (libtrace_dlt_t linktype)
 Converts a PCAP DLT into an RT protocol type.
libtrace_dlt_t libtrace_to_pcap_linktype (libtrace_linktype_t type)
 Converts a libtrace link type into a PCAP linktype.
libtrace_dlt_t libtrace_to_pcap_dlt (libtrace_linktype_t type)
 Converts a libtrace link type into a PCAP DLT.
libtrace_dlt_t rt_to_pcap_linktype (libtrace_rt_types_t rt_type)
 Converts an RT protocol type into a PCAP DLT.
libtrace_linktype_t erf_type_to_libtrace (uint8_t erf)
 Converts an ERF type into a libtrace link type.
uint8_t libtrace_to_erf_type (libtrace_linktype_t linktype)
 Converts a libtrace link type into an ERF type.
libtrace_linktype_t arphrd_type_to_libtrace (unsigned int arphrd)
 Converts an ARPHRD type into a libtrace link type.
unsigned int libtrace_to_arphrd_type (libtrace_linktype_t type)
 Converts a libtrace link type into an ARPHRD type.
void promote_packet (libtrace_packet_t *packet)
 Converts a libtrace packet to the Linux SLL type.
bool demote_packet (libtrace_packet_t *packet)
 Attempts to demote a packet by removing the first header.
void * trace_get_payload_from_linux_sll (const void *link, uint16_t *arphrd_type, uint16_t *next_header, uint32_t *remaining)
 Returns a pointer to the header following a Linux SLL header.
DLLEXPORT void * trace_get_payload_from_atm (void *link, uint8_t *type, uint32_t *remaining)
 Returns a pointer to the header following an ATM header.
uint64_t byteswap64 (uint64_t num)
 Byteswaps a 64-bit value.
uint32_t byteswap32 (uint32_t num)
 Byteswaps a 32-bit value.
uint16_t byteswap16 (uint16_t num)
 Byteswaps a 16-bit value.
void erf_constructor (void)
 Constructor for the ERF format module.
void tsh_constructor (void)
 Constructor for the TSH format module.
void legacy_constructor (void)
 Constructor for the Legacy DAG format module.
void linuxnative_constructor (void)
 Constructor for the Linux Native format module.
void pcap_constructor (void)
 Constructor for the PCAP format module.
void pcapfile_constructor (void)
 Constructor for the PCAP File format module.
void rt_constructor (void)
 Constructor for the RT format module.
void duck_constructor (void)
 Constructor for the DUCK format module.
void atmhdr_constructor (void)
 Constructor for the ATM Header format module.
bool trace_get_wireless_flags (void *link, libtrace_linktype_t linktype, uint8_t *flags)
 Extracts the RadioTap flags from a wireless link header.

Variables

int libtrace_halt
 The list of registered capture formats.

Detailed Description

Header file containing definitions for structures and functions that are internal.

Author:
Daniel Lawson
Perry Lorier
Shane Alcock
Version:
Id:
libtrace_int.h 1759 2012-03-14 01:59:44Z salcock

All of the structures and functions defined in this header file are intended for internal use within Libtrace only. They should not be exported as part of the library API as we don't want users accessing things like the contents of the libtrace packet structure directly!


Typedef Documentation

Local definition of a PCAP header.

A local definition of a PFLOG header.


Enumeration Type Documentation

anonymous enum

Flags for prepare_packet functions.

Enumerator:
TRACE_PREP_OWN_BUFFER 

The buffer memory has been allocated by libtrace and should be freed when the packet is destroyed.

TRACE_PREP_DO_NOT_OWN_BUFFER 

The buffer memory is externally-owned and must not be freed by libtrace when the packet is destroyed.


Function Documentation

libtrace_linktype_t arphrd_type_to_libtrace ( unsigned int  arphrd  ) 
void atmhdr_constructor ( void   ) 

Constructor for the ATM Header format module.

References register_format().

uint16_t byteswap16 ( uint16_t  num  ) 

Byteswaps a 16-bit value.

Parameters:
num The value to be byteswapped.
Returns:
The byteswapped 16-bit number
uint32_t byteswap32 ( uint32_t  num  ) 

Byteswaps a 32-bit value.

Parameters:
num The value to be byteswapped.
Returns:
The byteswapped 32-bit number
uint64_t byteswap64 ( uint64_t  num  ) 

Byteswaps a 64-bit value.

Parameters:
num The value to be byteswapped.
Returns:
The byteswapped 64-bit number
bool demote_packet ( libtrace_packet_t packet  ) 

Attempts to demote a packet by removing the first header.

Parameters:
packet The packet to be demoted
Returns:
True if the packet was demoted, false otherwise.

Essentially the opposite of promote_packet, except that it will also remove an ATM header as well as Linux SLL.

References libtrace_packet_t::buf_control, libtrace_packet_t::buffer, demote_packet(), libtrace_packet_t::header, libtrace_packet_t::payload, pcap_linktype_to_rt(), libtrace_packet_t::trace, trace_clear_cache(), trace_create_dead(), TRACE_CTRL_EXTERNAL, TRACE_DLT_RAW, trace_get_capture_length(), trace_get_link_type(), trace_get_payload_from_atm(), trace_get_timeval(), trace_get_wire_length(), trace_set_capture_length(), TRACE_TYPE_ATM, TRACE_TYPE_LINUX_SLL, and libtrace_packet_t::type.

Referenced by demote_packet(), and trace_apply_filter().

void duck_constructor ( void   ) 

Constructor for the DUCK format module.

References register_format().

void erf_constructor ( void   ) 

Constructor for the ERF format module.

References register_format().

libtrace_linktype_t erf_type_to_libtrace ( uint8_t  erf  ) 

Converts an ERF type into a libtrace link type.

Parameters:
erf The ERF type to be converted
Returns:
The libtrace link type that is equivalent to the provided ERF type, or -1 if the ERF type is unknown

References erf_type_to_libtrace(), TYPE_AAL5, TYPE_ATM, TYPE_DSM_COLOR_ETH, TYPE_ETH, and TYPE_HDLC_POS.

Referenced by erf_type_to_libtrace().

void legacy_constructor ( void   ) 

Constructor for the Legacy DAG format module.

References register_format().

unsigned int libtrace_to_arphrd_type ( libtrace_linktype_t  type  ) 

Converts a libtrace link type into an ARPHRD type.

Parameters:
type The libtrace link type to be converted
Returns:
The ARPHRD type that is equivalent to the provided libtrace link type, or -1 if the link type cannot be matched to an ARPHRD type

References libtrace_to_arphrd_type(), TRACE_TYPE_80211, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_ETH.

Referenced by libtrace_to_arphrd_type().

uint8_t libtrace_to_erf_type ( libtrace_linktype_t  linktype  ) 

Converts a libtrace link type into an ERF type.

Parameters:
linktype The libtrace link type to be converted
Returns:
The ERF type that is equivalent to the provided libtrace link type, or -1 if the link type cannot be matched to an ERF type.

References libtrace_to_erf_type(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, and TRACE_TYPE_PPP.

Referenced by libtrace_to_erf_type().

libtrace_dlt_t libtrace_to_pcap_dlt ( libtrace_linktype_t  type  ) 

Converts a libtrace link type into a PCAP DLT.

Parameters:
type The libtrace link type to be converted
Returns:
The PCAP DLT that is equivalent to the provided libtrace link type, or -1 if the link type is unknown

References libtrace_to_pcap_dlt(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, and TRACE_TYPE_PPP.

Referenced by libtrace_to_pcap_dlt(), libtrace_to_pcap_linktype(), and trace_apply_filter().

libtrace_dlt_t libtrace_to_pcap_linktype ( libtrace_linktype_t  type  ) 

Converts a libtrace link type into a PCAP linktype.

Parameters:
type The libtrace link type to be converted
Returns:
The PCAP linktype that is equivalent to the provided libtrace link type, or -1 if the link type is unknown

References libtrace_to_pcap_dlt(), and libtrace_to_pcap_linktype().

Referenced by libtrace_to_pcap_linktype(), and trace_construct_packet().

void linuxnative_constructor ( void   ) 

Constructor for the Linux Native format module.

References register_format().

void pcap_constructor ( void   ) 

Constructor for the PCAP format module.

libtrace_linktype_t pcap_linktype_to_libtrace ( libtrace_dlt_t  linktype  ) 

Converts a PCAP DLT into a libtrace link type.

Parameters:
linktype The PCAP DLT to be converted
Returns:
The libtrace link type that is equivalent to the provided DLT, or -1 if the DLT is unknown

References pcap_linktype_to_libtrace(), TRACE_DLT_IEEE802_11_RADIO, TRACE_DLT_LINKTYPE_RAW, TRACE_DLT_NULL, and TRACE_DLT_RAW.

Referenced by pcap_linktype_to_libtrace(), and promote_packet().

libtrace_rt_types_t pcap_linktype_to_rt ( libtrace_dlt_t  linktype  ) 

Converts a PCAP DLT into an RT protocol type.

Parameters:
linktype The PCAP DLT to be converted
Returns:
The RT type that is equivalent to the provided DLT

References pcap_linktype_to_rt().

Referenced by demote_packet(), pcap_linktype_to_rt(), promote_packet(), and trace_construct_packet().

void pcapfile_constructor ( void   ) 

Constructor for the PCAP File format module.

References register_format().

void promote_packet ( libtrace_packet_t packet  ) 

Converts a libtrace packet to the Linux SLL type.

Parameters:
packet The packet to be promoted
Note:
This will involve memcpy() so use sparingly.

This function prepends a Linux SLL header to a packet so that we can store direction tagging information.

Converts a libtrace packet to the Linux SLL type.

Packets that don't support direction tagging are annoying, especially when we have direction tagging information! So this converts the packet to TRACE_TYPE_LINUX_SLL which does support direction tagging. This is a pcap style packet for the reason that it means it works with bpf filters.

Note:
this will copy the packet, so use sparingly if possible.

References libtrace_packet_t::buf_control, libtrace_packet_t::buffer, libtrace_t::format, libtrace_sll_header_t::halen, libtrace_sll_header_t::hatype, libtrace_packet_t::header, libtrace_packet_t::payload, pcap_linktype_to_libtrace(), pcap_linktype_to_rt(), libtrace_sll_header_t::pkttype, promote_packet(), libtrace_sll_header_t::protocol, rt_to_pcap_linktype(), libtrace_packet_t::trace, trace_clear_cache(), TRACE_CTRL_EXTERNAL, TRACE_FORMAT_PCAP, trace_get_capture_length(), trace_get_framing_length(), trace_get_layer3(), TRACE_TYPE_ETH, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_NONE, libtrace_packet_t::type, and libtrace_format_t::type.

Referenced by promote_packet().

void register_format ( struct libtrace_format_t format  ) 
void rt_constructor ( void   ) 

Constructor for the RT format module.

References register_format().

libtrace_dlt_t rt_to_pcap_linktype ( libtrace_rt_types_t  rt_type  ) 

Converts an RT protocol type into a PCAP DLT.

Parameters:
rt_type The RT type to be converted
Returns:
The PCAP DLT that is equivalent to the provided RT protocol

References rt_to_pcap_linktype(), and TRACE_RT_DATA_DLT.

Referenced by promote_packet(), and rt_to_pcap_linktype().

int snprintf ( char *  str,
size_t  size,
const char *  format,
  ... 
)

A local implementation of snprintf (as some systems do not have it).

Referenced by trace_ether_ntoa().

int strncasecmp ( const char *  str1,
const char *  str2,
size_t  n 
)

A local implementation of strncasecmp (as some systems do not have it).

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

void void void trace_clear_cache ( libtrace_packet_t packet  ) 
DLLEXPORT void* trace_get_payload_from_atm ( void *  link,
uint8_t *  type,
uint32_t *  remaining 
)

Returns a pointer to the header following an ATM header.

Parameters:
link A pointer to the ATM header to be skipped
[out] type The ethertype of the next header
[in,out] remaining Updated with the number of captured bytes remaining
Returns:
A pointer to the header following the ATM header, or NULL if no subsequent header is present.

Remaining must point to the number of bytes captured from the ATM header and beyond. It will be decremented by the number of bytes skipped to find the payload.

If the ATM header is complete but there are zero bytes of payload after the end of the header, a pointer to where the payload would be is returned and remaining will be set to zero. If the ATM header is incomplete (truncated), then NULL is returned and remaining will be set to 0. Therefore, it is very important to check the value of remaining after calling this function.

References libtrace_atm_capture_cell::pt, and trace_get_payload_from_atm().

Referenced by demote_packet(), trace_get_payload_from_atm(), and trace_get_payload_from_layer2().

void* trace_get_payload_from_linux_sll ( const void *  link,
uint16_t *  arphrd_type,
uint16_t *  next_header,
uint32_t *  remaining 
)

Returns a pointer to the header following a Linux SLL header.

Parameters:
link A pointer to the Linux SLL header to be skipped
[out] arphrd_type The arp hardware type of the packet
[out] next_header The ethertype of the next header
[in,out] remaining Updated with the number of captured bytes remaining
Returns:
A pointer to the header following the Linux SLL header, or NULL if no subsequent header is present.

Remaining must point to the number of bytes captured from the Linux SLL header and beyond. It will be decremented by the number of bytes skipped to find the payload.

If the Linux SLL header is complete but there are zero bytes of payload after the end of the header, a pointer to where the payload would be is returned and remaining will be set to zero. If the Linux SLL header is incomplete (truncated), then NULL is returned and remaining will be set to 0. Therefore, it is very important to check the value of remaining after calling this function.

References libtrace_sll_header_t::hatype, libtrace_sll_header_t::protocol, and trace_get_payload_from_linux_sll().

Referenced by trace_get_payload_from_linux_sll(), trace_get_payload_from_meta(), trace_get_wireless_antenna(), trace_get_wireless_flags(), trace_get_wireless_freq(), trace_get_wireless_noise_strength_db(), trace_get_wireless_noise_strength_dbm(), trace_get_wireless_rate(), trace_get_wireless_signal_strength_db(), trace_get_wireless_signal_strength_dbm(), trace_get_wireless_tsft(), trace_get_wireless_tx_attenuation(), trace_get_wireless_tx_attenuation_db(), and trace_get_wireless_tx_power_dbm().

bool trace_get_wireless_flags ( void *  link,
libtrace_linktype_t  linktype,
uint8_t *  flags 
)

Extracts the RadioTap flags from a wireless link header.

Parameters:
link A pointer to the wireless link header
linktype The link type of the wireless header
[out] flags Space to store the extracted flags
Returns:
True if libtrace was able to extract flags from the link header, false otherwise.

This function has been left internal because it is not portable across drivers.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), trace_get_wireless_flags(), TRACE_RADIOTAP_FLAGS, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_flags().

int trace_prepare_packet ( libtrace_t trace,
libtrace_packet_t packet,
void *  buffer,
libtrace_rt_types_t  rt_type,
uint32_t  flags 
)

Converts the data provided in buffer into a valid libtrace packet.

Parameters:
trace An input trace of the same format as the "packet" contained in the buffer
packet The libtrace packet to prepare
buffer A buffer containing the packet data, including the capture format header
rt_type The RT type for the packet that is being prepared
flags Used to specify options for the preparation function, e.g. who owns the packet buffer
Returns:
-1 if an error occurs, 0 otherwise

Packet preparation is a tricky concept - the idea is to take the data pointed to by 'buffer' and treat it as a packet record of the same capture format as that used by the input trace. The provided libtrace packet then has its internal pointers and values set to describe the packet record in the buffer.

The primary use of this function is to allow the RT packet reader to easily and safely convert packets from the RT format back into the format that they were originally captured with., essentially removing the RT encapsulation.

We've decided not to make this function available via the exported API because there are several issues that can arise if it is not used very carefully and it is not very useful outside of internal contexts anyway.

References libtrace_packet_t::buf_control, libtrace_t::format, libtrace_format_t::prepare_packet, libtrace_packet_t::trace, trace_clear_cache(), TRACE_CTRL_EXTERNAL, TRACE_CTRL_PACKET, TRACE_ERR_BAD_STATE, TRACE_ERR_UNSUPPORTED, trace_prepare_packet(), and trace_set_err().

Referenced by trace_prepare_packet().

void trace_set_err ( libtrace_t trace,
int  errcode,
const char *  msg,
  ... 
)

Sets the error status on an input trace.

Parameters:
trace The input trace to set the error status for
errcode The code for the error - can be a libtrace error code or a regular errno value
msg A message to print when reporting the error

Referenced by trace_apply_filter(), trace_config(), trace_create(), trace_create_dead(), trace_open_file(), trace_pause(), trace_prepare_packet(), trace_read_packet(), trace_seek_erf_timestamp(), trace_seek_seconds(), and trace_seek_timeval().

void void trace_set_err_out ( libtrace_out_t trace,
int  errcode,
const char *  msg,
  ... 
)

Sets the error status on an output trace.

Parameters:
trace The output trace to set the error status for
errcode The code for the error - can be a libtrace error code or a regular errno value
msg A message to print when reporting the error

Referenced by trace_create_output(), and trace_write_packet().

void tsh_constructor ( void   ) 

Constructor for the TSH format module.

References register_format().


Variable Documentation

The list of registered capture formats.

Specifies whether any blocking packet readers should cease reading immediately

Referenced by trace_interrupt().