Main Page | Data Structures | Directories | File List | Data Fields | Globals | Related Pages
lib

libtrace.h File Reference

Trace file processing library header. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Wireless trace support

Functions to access wireless information from packets that have wireless monitoring headers such as Radiotap or Prism.

The trace_get_wireless_* functions provide an abstract interface for retrieving information from wireless traces. They take a pointer to the wireless monitoring header (usually found with trace_get_link(packet)) and the linktype of the header passed in.

All of the trace_get_wireless_* functions return false if the requested information was unavailable, or true if it was. The actual data is stored in an output variable supplied by the caller. Values returned into the output variable will always be returned in host byte order.

#define ARPHRD_80211_RADIOTAP   803
DLLEXPORT bool trace_get_wireless_tsft (void *linkptr, libtrace_linktype_t linktype, uint64_t *tsft)
 Get the wireless Timer Syncronisation Function.
DLLEXPORT bool trace_get_wireless_rate (void *linkptr, libtrace_linktype_t linktype, uint8_t *rate)
 Get the wireless rate.
DLLEXPORT bool trace_get_wireless_freq (void *linkptr, libtrace_linktype_t linktype, uint16_t *freq)
 Get the wireless channel frequency.
DLLEXPORT bool trace_get_wireless_signal_strength_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *strength)
 Get the wireless signal strength in dBm.
DLLEXPORT bool trace_get_wireless_noise_strength_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *strength)
 Get the wireless noise strength in dBm.
DLLEXPORT bool trace_get_wireless_signal_strength_db (void *linkptr, libtrace_linktype_t linktype, uint8_t *strength)
 Get the wireless signal strength in dB.
DLLEXPORT bool trace_get_wireless_noise_strength_db (void *linkptr, libtrace_linktype_t linktype, uint8_t *strength)
 Get the wireless noise strength in dB.
DLLEXPORT bool trace_get_wireless_tx_attenuation (void *linkptr, libtrace_linktype_t linktype, uint16_t *attenuation)
 Get the wireless transmit attenuation.
DLLEXPORT bool trace_get_wireless_tx_attenuation_db (void *linkptr, libtrace_linktype_t linktype, uint16_t *attenuation)
 Get the wireless transmit attenuation in dB.
DLLEXPORT bool trace_get_wireless_tx_power_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *txpower)
 Get the wireless transmit power in dBm.
DLLEXPORT bool trace_get_wireless_antenna (void *linkptr, libtrace_linktype_t linktype, uint8_t *antenna)
 Get the wireless antenna.

Protocol structures

These convenience structures are here as they are portable ways of dealing with various protocols.

typedef libtrace_ip libtrace_ip_t
 Generic IP header structure.
typedef libtrace_ip6_ext libtrace_ip6_ext_t
 IPv6 header extension structure.
typedef libtrace_ip6 libtrace_ip6_t
 Generic IPv6 header structure.
typedef libtrace_tcp libtrace_tcp_t
 Generic TCP header structure.
typedef libtrace_udp libtrace_udp_t
 Generic UDP header structure.
typedef libtrace_icmp libtrace_icmp_t
 Generic ICMP header structure.
typedef libtrace_llcsnap libtrace_llcsnap_t
 Generic LLC/SNAP header structure.
typedef libtrace_ether libtrace_ether_t
 802.3 frame
typedef libtrace_8021q libtrace_8021q_t
 802.1Q frame
typedef libtrace_atm_cell libtrace_atm_cell_t
 ATM User Network Interface (UNI) Cell.
typedef libtrace_atm_nni_cell libtrace_atm_nni_cell_t
 ATM Network Node/Network Interface (NNI) Cell.
typedef libtrace_atm_capture_cell libtrace_atm_capture_cell_t
 Captured UNI cell.
typedef libtrace_atm_nni_capture_cell libtrace_atm_nni_capture_cell_t
 Captured NNI cell.
typedef libtrace_pps libtrace_ppp_t
 PPP header.
typedef libtrace_80211_t libtrace_80211_t
 802.11 header
typedef libtrace_radiotap_t libtrace_radiotap_t
 The Radiotap header pre-amble.

Reading/Writing packets

These members deal with creating, reading and writing packets

typedef libtrace_eventobj_t libtrace_eventobj_t
 Structure returned by libtrace_event explaining what the current event is.
enum  libtrace_event_t { TRACE_EVENT_IOWAIT, TRACE_EVENT_SLEEP, TRACE_EVENT_PACKET, TRACE_EVENT_TERMINATE }
 Event types see libtrace_eventobj_t and trace_event. More...
DLLEXPORT libtrace_packet_t * trace_create_packet (void)
 Create a new packet object.
DLLEXPORT libtrace_packet_t * trace_copy_packet (const libtrace_packet_t *packet)
 Copy a packet.
DLLEXPORT void trace_destroy_packet (libtrace_packet_t *packet)
 Destroy a packet object.
DLLEXPORT int trace_read_packet (libtrace_t *trace, libtrace_packet_t *packet)
 Read one packet from the trace.
DLLEXPORT libtrace_eventobj_t trace_event (libtrace_t *trace, libtrace_packet_t *packet)
 Processes the next libtrace event.
DLLEXPORT int trace_write_packet (libtrace_out_t *trace, libtrace_packet_t *packet)
 Write one packet out to the output trace.

Trace management

These members deal with creating, configuring, starting, pausing and cleaning up a trace object

enum  trace_option_t {
  TRACE_OPTION_SNAPLEN, TRACE_OPTION_PROMISC, TRACE_OPTION_FILTER, TRACE_OPTION_META_FREQ,
  TRACE_OPTION_EVENT_REALTIME
}
 Valid trace capture options. More...
enum  trace_option_output_t { TRACE_OPTION_OUTPUT_FILEFLAGS, TRACE_OPTION_OUTPUT_COMPRESS }
DLLEXPORT libtrace_t * trace_create (const char *uri)
 Create a trace file from a URI.
DLLEXPORT libtrace_t * trace_create_dead (const char *uri)
 Creates a "dummy" trace file that has only the format type set.
DLLEXPORT libtrace_out_t * trace_create_output (const char *uri)
 Creates a trace output file from a URI.
DLLEXPORT int trace_start (libtrace_t *libtrace)
 Start the capture.
DLLEXPORT int trace_pause (libtrace_t *libtrace)
 Pause the capture.
DLLEXPORT int trace_start_output (libtrace_out_t *libtrace)
 Start an output trace.
DLLEXPORT int trace_config (libtrace_t *libtrace, trace_option_t option, void *value)
 Sets an input config option.
DLLEXPORT int trace_config_output (libtrace_out_t *libtrace, trace_option_output_t option, void *value)
 Sets an output config option.
DLLEXPORT void trace_destroy (libtrace_t *trace)
 Close a trace file, freeing up any resources it may have been using.
DLLEXPORT void trace_destroy_dead (libtrace_t *trace)
 Close a trace file, freeing up any resources it may have been using.
DLLEXPORT void trace_destroy_output (libtrace_out_t *trace)
 Close a trace output file, freeing up any resources it may have been using.
DLLEXPORT libtrace_err_t trace_get_err (libtrace_t *trace)
 Check (and clear) the current error state of an input trace.
DLLEXPORT bool trace_is_err (libtrace_t *trace)
 Return if there is an error.
DLLEXPORT void trace_perror (libtrace_t *trace, const char *msg,...) PRINTF(2
 Output an error message to stderr and clear the error status.
DLLEXPORT void DLLEXPORT libtrace_err_t trace_get_err_output (libtrace_out_t *trace)
 Check (and clear) the current error state of an output trace.
DLLEXPORT bool trace_is_err_output (libtrace_out_t *trace)
 Return if there is an error.
DLLEXPORT void trace_perror_output (libtrace_out_t *trace, const char *msg,...) PRINTF(2
 Output an error message to stderr and clear the error status.
DLLEXPORT void uint64_t trace_get_received_packets (libtrace_t *trace)
 Return the number of captured packets Includes the number of packets counted as early as possible, before filtering, and includes dropped packets.
uint64_t trace_get_filtered_packets (libtrace_t *trace)
 Return the number of filtered packets Returns the number of packets that were captured, but discarded for not matching a trace filter.
uint64_t trace_get_dropped_packets (libtrace_t *trace)
 Return the number of packets that have been dropped for lack of packets.
uint64_t trace_get_accepted_packets (libtrace_t *trace)
 Return the number of packets that have been returned to library user.

Protocol decodes

These functions locate and return a pointer to various headers inside a packet

DLLEXPORT void * trace_get_packet_buffer (const libtrace_packet_t *packet, libtrace_linktype_t *linktype, uint32_t *remaining)
 Gets a pointer to the first byte of the packet as it was captured and returns its corresponding linktype and capture length.
DLLEXPORT SIMPLE_FUNCTION
DEPRECATED void * 		trace_get_link (const libtrace_packet_t *packet)
 get a pointer to the link layer
DLLEXPORT SIMPLE_FUNCTION
libtrace_ip_t * 		trace_get_ip (libtrace_packet_t *packet)
 get a pointer to the IPv4 header (if any)
DLLEXPORT SIMPLE_FUNCTION
libtrace_ip6_t * 		trace_get_ip6 (libtrace_packet_t *packet)
 get a pointer to the IPv6 header (if any)
DLLEXPORT void * trace_get_packet_meta (const libtrace_packet_t *packet, libtrace_linktype_t *linktype, uint32_t *remaining)
 Return a pointer to the first metadata header in a packet, if present.
DLLEXPORT void * trace_get_payload_from_meta (const void *meta, libtrace_linktype_t *linktype, uint32_t *remaining)
 Returns the payload of a metadata header.
DLLEXPORT void * trace_get_layer2 (const libtrace_packet_t *packet, libtrace_linktype_t *linktype, uint32_t *remaining)
 Get a pointer to the layer 2 header.
DLLEXPORT void * trace_get_payload_from_layer2 (void *l2, libtrace_linktype_t linktype, uint16_t *ethertype, uint32_t *remaining)
 Gets a pointer to the next header given a pointer to a layer2 header.
DLLEXPORT void * trace_get_layer3 (const libtrace_packet_t *packet, uint16_t *ethertype, uint32_t *remaining)
 Get a pointer to the layer 3 header.
DLLEXPORT void * trace_get_transport (const libtrace_packet_t *packet, uint8_t *proto, uint32_t *remaining)
 Gets a pointer to the transport layer header (if any).
DLLEXPORT void * trace_get_payload_from_ip (libtrace_ip_t *ip, uint8_t *proto, uint32_t *remaining)
 Gets a pointer to the payload given a pointer to the IP header.
DLLEXPORT void * trace_get_payload_from_ip6 (libtrace_ip6_t *ipptr, uint8_t *prot, uint32_t *remaining)
 Gets a pointer to the payload given a pointer to the IPv6 header.
DLLEXPORT void * trace_get_payload_from_link (void *linkptr, libtrace_linktype_t linktype, uint16_t *type, uint32_t *remaining)
 Gets a pointer to the payload given a pointer to the link header.
DLLEXPORT void * trace_get_vlan_payload_from_ethernet_payload (void *ethernet_payload, uint16_t *type, uint32_t *remaining)
 Skips over any 802.1q headers, if present.
DLLEXPORT void * trace_get_payload_from_tcp (libtrace_tcp_t *tcp, uint32_t *remaining)
 Gets a pointer to the payload given a pointer to a tcp header.
DLLEXPORT void * trace_get_payload_from_udp (libtrace_udp_t *udp, uint32_t *remaining)
 Gets a pointer to the payload given a pointer to a udp header.
DLLEXPORT void * trace_get_payload_from_icmp (libtrace_icmp_t *icmp, uint32_t *remaining)
 Gets a pointer to the payload given a pointer to a icmp header.
DLLEXPORT SIMPLE_FUNCTION
libtrace_tcp_t * 		trace_get_tcp (libtrace_packet_t *packet)
 get a pointer to the TCP header (if any)
DLLEXPORT SIMPLE_FUNCTION
libtrace_tcp_t * 		trace_get_tcp_from_ip (libtrace_ip_t *ip, uint32_t *remaining)
 get a pointer to the TCP header (if any) given a pointer to the IP header
DLLEXPORT SIMPLE_FUNCTION
libtrace_udp_t * 		trace_get_udp (libtrace_packet_t *packet)
 get a pointer to the UDP header (if any)
DLLEXPORT SIMPLE_FUNCTION
libtrace_udp_t * 		trace_get_udp_from_ip (libtrace_ip_t *ip, uint32_t *remaining)
 get a pointer to the UDP header (if any) given a pointer to the IP header
DLLEXPORT SIMPLE_FUNCTION
libtrace_icmp_t * 		trace_get_icmp (libtrace_packet_t *packet)
 get a pointer to the ICMP header (if any)
DLLEXPORT SIMPLE_FUNCTION
libtrace_icmp_t * 		trace_get_icmp_from_ip (libtrace_ip_t *ip, uint32_t *remaining)
 get a pointer to the ICMP header (if any) given a pointer to the IP header
DLLEXPORT SIMPLE_FUNCTION
uint8_t * 		trace_get_destination_mac (libtrace_packet_t *packet)
 Get the destination MAC address.
DLLEXPORT SIMPLE_FUNCTION
uint8_t * 		trace_get_source_mac (libtrace_packet_t *packet)
 Get the source MAC address.
DLLEXPORT SIMPLE_FUNCTION
struct sockaddr * 		trace_get_source_address (const libtrace_packet_t *packet, struct sockaddr *addr)
 Get the source IP address.
DLLEXPORT SIMPLE_FUNCTION
struct sockaddr * 		trace_get_destination_address (const libtrace_packet_t *packet, struct sockaddr *addr)
 Get the destination IP address.

Time

These functions deal with time that a packet arrived and return it in various formats

DLLEXPORT SIMPLE_FUNCTION
uint64_t 		trace_get_erf_timestamp (const libtrace_packet_t *packet)
 Get the current time in DAG time format.
DLLEXPORT SIMPLE_FUNCTION
struct timeval 		trace_get_timeval (const libtrace_packet_t *packet)
 Get the current time in struct timeval.
DLLEXPORT SIMPLE_FUNCTION
double 		trace_get_seconds (const libtrace_packet_t *packet)
 Get the current time in floating point seconds.
DLLEXPORT int trace_seek_seconds (libtrace_t *trace, double seconds)
 Seek within a trace.
DLLEXPORT int trace_seek_timeval (libtrace_t *trace, struct timeval tv)
 Seek within a trace.
DLLEXPORT int trace_seek_erf_timestamp (libtrace_t *trace, uint64_t ts)
 Seek within a trace.

Sizes

This section deals with finding or setting the various different lengths a packet can have

DLLEXPORT SIMPLE_FUNCTION
size_t 		trace_get_capture_length (const libtrace_packet_t *packet)
 Get the size of the packet in the trace (in bytes).
DLLEXPORT SIMPLE_FUNCTION
size_t 		trace_get_wire_length (const libtrace_packet_t *packet)
 Get the size of the packet as it was seen on the wire (in bytes).
DLLEXPORT SIMPLE_FUNCTION
size_t 		trace_get_framing_length (const libtrace_packet_t *packet)
 Get the length of the capture framing headers (in bytes).
DLLEXPORT size_t trace_set_capture_length (libtrace_packet_t *packet, size_t size)
 Truncate ("snap") the packet at the suggested length.

BPF

This section deals with using Berkley Packet Filters

DLLEXPORT SIMPLE_FUNCTION
libtrace_filter_t * 		trace_create_filter (const char *filterstring)
 setup a BPF filter
DLLEXPORT libtrace_filter_t * trace_create_filter_from_bytecode (void *bf_insns, unsigned int bf_len)
 Setup a BPF filter based on pre-compiled byte-code.
DLLEXPORT int trace_apply_filter (libtrace_filter_t *filter, const libtrace_packet_t *packet)
 Apply a BPF filter to a packet.
DLLEXPORT void trace_destroy_filter (libtrace_filter_t *filter)
 Destroy a BPF filter.

Portability

This section has functions that causes annoyances to portability for one reason or another.

DLLEXPORT char * trace_ether_ntoa (const uint8_t *addr, char *buf)
 Convert an ethernet address to a string.
DLLEXPORT uint8_t * trace_ether_aton (const char *buf, uint8_t *addr)
 Convert a string to an ethernet address.

Defines

#define DLLEXPORT
#define DLLLOCAL
#define LT_BITFIELD8   unsigned int
#define LT_BITFIELD16   unsigned int
#define LT_BITFIELD32   unsigned int
#define LT_BITFIELD64   unsigned int
#define LIBTRACE_API_VERSION   ((3<<16)|(0<<8)|(3))
 API version as 2 byte hex digits, eg 0xXXYYZZ.
#define LIBTRACE_SVN_REVISION   0
#define DAG_DRIVER_V   ""
#define DEPRECATED
#define SIMPLE_FUNCTION
#define UNUSED
#define PACKED
#define PRINTF(formatpos, argpos)
#define LIBTRACE_PACKET_BUFSIZE   65536
 The size of a packet's buffer when managed by libtrace.

Typedefs

typedef libtrace_out_t libtrace_out_t
 Opaque structure holding information about an output trace.
typedef libtrace_t libtrace_t
 Opaque structure holding information about a trace.
typedef libtrace_filter_t libtrace_filter_t
 Opaque structure holding information about a bpf filter.
typedef trace_err_t libtrace_err_t
 libtrace error information
typedef libtrace_packet_t libtrace_packet_t
 The libtrace packet structure, applications shouldn't be meddling around in here.

Enumerations

enum  buf_control_t { TRACE_CTRL_PACKET = 'p', TRACE_CTRL_EXTERNAL = 'e' }
 If a packet has memory allocated If the packet has allocated it's own memory it's buffer_control should be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be free()'d. More...
enum  {
  TRACE_ERR_NOERROR = 0, TRACE_ERR_BAD_FORMAT = -1, TRACE_ERR_INIT_FAILED = -2, TRACE_ERR_UNKNOWN_OPTION = -3,
  TRACE_ERR_NO_CONVERSION = -4, TRACE_ERR_BAD_PACKET = -5, TRACE_ERR_OPTION_UNAVAIL = -6, TRACE_ERR_UNSUPPORTED = -7,
  TRACE_ERR_BAD_STATE = -8
}
 Enumeration of error codes. More...
enum  libtrace_dlt_t {
  TRACE_DLT_NULL = 0, TRACE_DLT_EN10MB = 1, TRACE_DLT_PPP = 9, TRACE_DLT_ATM_RFC1483 = 11,
  TRACE_DLT_RAW = 12, TRACE_DLT_LINKTYPE_RAW = 101, TRACE_DLT_C_HDLC = 104, TRACE_DLT_IEEE802_11 = 105,
  TRACE_DLT_LINUX_SLL = 113, TRACE_DLT_PFLOG = 117, TRACE_DLT_IEEE802_11_RADIO = 127
}
 Enumeration of DLT supported by libtrace. More...
enum  libtrace_linktype_t {
  TRACE_TYPE_HDLC_POS = 1, TRACE_TYPE_ETH = 2, TRACE_TYPE_ATM = 3, TRACE_TYPE_80211 = 4,
  TRACE_TYPE_NONE = 5, TRACE_TYPE_LINUX_SLL = 6, TRACE_TYPE_PFLOG = 7, TRACE_TYPE_POS = 9,
  TRACE_TYPE_80211_PRISM = 12, TRACE_TYPE_AAL5 = 13, TRACE_TYPE_DUCK = 14, TRACE_TYPE_80211_RADIO = 15,
  TRACE_TYPE_LLCSNAP = 16, TRACE_TYPE_PPP = 17, TRACE_TYPE_METADATA = 18
}
 Enumeration of link layer types supported by libtrace. More...
enum  base_format_t {
  TRACE_FORMAT_ERF = 1, TRACE_FORMAT_PCAP = 2, TRACE_FORMAT_PCAPFILE = 3, TRACE_FORMAT_WAG = 4,
  TRACE_FORMAT_RT = 5, TRACE_FORMAT_LEGACY_ATM = 6, TRACE_FORMAT_LEGACY_POS = 7, TRACE_FORMAT_LEGACY_ETH = 8,
  TRACE_FORMAT_LINUX_NATIVE = 9, TRACE_FORMAT_DUCK = 10, TRACE_FORMAT_BPF = 11, TRACE_FORMAT_TSH = 12,
  TRACE_FORMAT_ATMHDR = 13, TRACE_FORMAT_LEGACY_NZIX = 14
}
 RT protocol base format identifiers This is used to say what kind of packet is being sent over the rt protocol. More...
enum  libtrace_rt_types_t {
  TRACE_RT_HELLO = 1, TRACE_RT_START = 2, TRACE_RT_ACK = 3, TRACE_RT_STATUS = 4,
  TRACE_RT_DUCK = 5, TRACE_RT_END_DATA = 6, TRACE_RT_CLOSE = 7, TRACE_RT_DENY_CONN = 8,
  TRACE_RT_PAUSE = 9, TRACE_RT_PAUSE_ACK = 10, TRACE_RT_OPTION = 11, TRACE_RT_KEYCHANGE = 12,
  TRACE_RT_DUCK_2_4 = 13, TRACE_RT_DUCK_2_5 = 14, TRACE_RT_LOSTCONN = 15, TRACE_RT_SERVERSTART = 16,
  TRACE_RT_CLIENTDROP = 17, TRACE_RT_METADATA = 18, TRACE_RT_DATA_SIMPLE = 1000, TRACE_RT_DATA_ERF = TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_ERF,
  TRACE_RT_DATA_WAG = TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_WAG, TRACE_RT_DATA_LEGACY_ATM = TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ATM, TRACE_RT_DATA_LEGACY_POS = TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_POS, TRACE_RT_DATA_LEGACY_ETH = TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ETH,
  TRACE_RT_DATA_LINUX_NATIVE = TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_NATIVE, TRACE_RT_DATA_TSH = TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_TSH, TRACE_RT_DATA_ATMHDR = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_ATMHDR, TRACE_RT_DATA_LEGACY_NZIX = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_LEGACY_NZIX,
  TRACE_RT_DATA_DLT = 2000, TRACE_RT_DLT_NULL = TRACE_RT_DATA_DLT+TRACE_DLT_NULL, TRACE_RT_DLT_EN10MB = TRACE_RT_DATA_DLT+TRACE_DLT_EN10MB, TRACE_RT_DLT_IEEE802_11 = TRACE_RT_DATA_DLT+TRACE_DLT_IEEE802_11,
  TRACE_RT_DLT_LINUX_SLL = TRACE_RT_DATA_DLT+TRACE_DLT_LINUX_SLL, TRACE_RT_DLT_PFLOG = TRACE_RT_DATA_DLT+TRACE_DLT_PFLOG, TRACE_RT_DLT_ATM_RFC1483 = TRACE_RT_DATA_DLT+TRACE_DLT_ATM_RFC1483, TRACE_RT_DATA_DLT_END = 2999,
  TRACE_RT_LAST = (2<<31)
}
enum  libtrace_direction_t { TRACE_DIR_OUTGOING = 0, TRACE_DIR_INCOMING = 1, TRACE_DIR_OTHER = 2 }
 Trace directions Note that these are the directions used by convention, more directions are possible, not just these 3, and that they may not conform to this convention. More...
enum  libtrace_radiotap_field_t {
  TRACE_RADIOTAP_TSFT = 0, TRACE_RADIOTAP_FLAGS = 1, TRACE_RADIOTAP_RATE = 2, TRACE_RADIOTAP_CHANNEL = 3,
  TRACE_RADIOTAP_FHSS = 4, TRACE_RADIOTAP_DBM_ANTSIGNAL = 5, TRACE_RADIOTAP_DBM_ANTNOISE = 6, TRACE_RADIOTAP_LOCK_QUALITY = 7,
  TRACE_RADIOTAP_TX_ATTENUATION = 8, TRACE_RADIOTAP_DB_TX_ATTENUATION = 9, TRACE_RADIOTAP_DBM_TX_POWER = 10, TRACE_RADIOTAP_ANTENNA = 11,
  TRACE_RADIOTAP_DB_ANTSIGNAL = 12, TRACE_RADIOTAP_DB_ANTNOISE = 13, TRACE_RADIOTAP_RX_FLAGS = 14, TRACE_RADIOTAP_TX_FLAGS = 15,
  TRACE_RADIOTAP_RTS_RETRIES = 16, TRACE_RADIOTAP_DATA_RETRIES = 17, TRACE_RADIOTAP_EXT = 31
}
 Enumeration of Radiotap fields. More...
enum  serverport_t { USE_DEST, USE_SOURCE }
 Which port is the server port. More...

Functions

DLLEXPORT void trace_help (void)
 Prints help information for libtrace.
DLLEXPORT int trace_get_next_option (unsigned char **ptr, int *len, unsigned char *type, unsigned char *optlen, unsigned char **data)
 parse an ip or tcp option
DLLEXPORT SIMPLE_FUNCTION
libtrace_linktype_t 		trace_get_link_type (const libtrace_packet_t *packet)
 Get the type of the link layer.
DLLEXPORT libtrace_direction_t trace_set_direction (libtrace_packet_t *packet, libtrace_direction_t direction)
 Set the direction flag, if it has one.
DLLEXPORT SIMPLE_FUNCTION
libtrace_direction_t 		trace_get_direction (const libtrace_packet_t *packet)
 Get the direction flag, if it has one.
DLLEXPORT SIMPLE_FUNCTION
uint16_t 		trace_get_source_port (const libtrace_packet_t *packet)
 Get the source port.
DLLEXPORT SIMPLE_FUNCTION
uint16_t 		trace_get_destination_port (const libtrace_packet_t *packet)
 Get the destination port.
DLLEXPORT SIMPLE_FUNCTION
int8_t 		trace_get_server_port (uint8_t protocol, uint16_t source, uint16_t dest)
 hint at the server port in specified protocol
DLLEXPORT const char * trace_parse_uri (const char *uri, char **format)
 Takes a uri and splits it into a format and uridata component.
DLLEXPORT enum base_format_t trace_get_format (struct libtrace_packet_t *packet)
 Gets the format type for a given packet.
DLLEXPORT void trace_construct_packet (libtrace_packet_t *packet, libtrace_linktype_t linktype, const void *data, uint16_t len)
 Construct a packet from a buffer.

Detailed Description

Trace file processing library header.

Author:
Daniel Lawson

Perry Lorier

Version:
Id
libtrace.h 773 2006-05-01 12:58:09Z perry
This library provides a per packet interface into a trace file, or a live captures. It supports ERF, DAG cards, WAG cards, WAG's event format, pcap etc.

Usage
See the example/ directory in the source distribution for some simple examples
Linking
To use this library you need to link against libtrace by passing -ltrace to your linker. You may also need to link against a version of libpcap and of zlib which are compiled for largefile support (if you wish to access traces larger than 2 GB). This is left as an exercise for the reader. Debian Woody, at least, does not support large file offsets.

Define Documentation

#define LIBTRACE_API_VERSION   ((3<<16)|(0<<8)|(3))
 

API version as 2 byte hex digits, eg 0xXXYYZZ.

#define LIBTRACE_PACKET_BUFSIZE   65536
 

The size of a packet's buffer when managed by libtrace.

Typedef Documentation

typedef struct libtrace_80211_t libtrace_80211_t
 

802.11 header

typedef struct libtrace_8021q libtrace_8021q_t
 

802.1Q frame

typedef struct libtrace_atm_capture_cell libtrace_atm_capture_cell_t
 

Captured UNI cell.

Endance don't capture the HEC, presumably to keep alignment. This version of the libtrace_atm_cell is used when dealing with dag captures of uni cells.

typedef struct libtrace_atm_cell libtrace_atm_cell_t
 

ATM User Network Interface (UNI) Cell.

typedef struct libtrace_atm_nni_capture_cell libtrace_atm_nni_capture_cell_t
 

Captured NNI cell.

Endance don't capture the HEC, presumably to keep alignment. This version of the libtrace_atm_nni_cell is used when dealing with dag captures of nni cells.

typedef struct libtrace_atm_nni_cell libtrace_atm_nni_cell_t
 

ATM Network Node/Network Interface (NNI) Cell.

typedef struct trace_err_t libtrace_err_t
 

libtrace error information

typedef struct libtrace_ether libtrace_ether_t
 

802.3 frame

typedef struct libtrace_eventobj_t libtrace_eventobj_t
 

Structure returned by libtrace_event explaining what the current event is.

typedef struct libtrace_filter_t libtrace_filter_t
 

Opaque structure holding information about a bpf filter.

typedef struct libtrace_icmp libtrace_icmp_t
 

Generic ICMP header structure.

typedef struct libtrace_ip6_ext libtrace_ip6_ext_t
 

IPv6 header extension structure.

typedef struct libtrace_ip6 libtrace_ip6_t
 

Generic IPv6 header structure.

typedef struct libtrace_ip libtrace_ip_t
 

Generic IP header structure.

typedef struct libtrace_llcsnap libtrace_llcsnap_t
 

Generic LLC/SNAP header structure.

typedef struct libtrace_out_t libtrace_out_t
 

Opaque structure holding information about an output trace.

typedef struct libtrace_packet_t libtrace_packet_t
 

The libtrace packet structure, applications shouldn't be meddling around in here.

typedef struct libtrace_pps libtrace_ppp_t
 

PPP header.

typedef struct libtrace_radiotap_t libtrace_radiotap_t
 

The Radiotap header pre-amble.

All Radiotap headers start with this pre-amble, followed by the fields specified in the it_present bitmask. If bit 31 of it_present is set, then another bitmask follows.

Note:
All of the radiotap data fields are in little-endian byte-order.

typedef struct libtrace_t libtrace_t
 

Opaque structure holding information about a trace.

typedef struct libtrace_tcp libtrace_tcp_t
 

Generic TCP header structure.

typedef struct libtrace_udp libtrace_udp_t
 

Generic UDP header structure.

Enumeration Type Documentation

anonymous enum
 

Enumeration of error codes.

Enumeration values:
TRACE_ERR_NOERROR  No Error has occured.

... yet.

TRACE_ERR_BAD_FORMAT  The URI passed to trace_create() is unsupported, or badly formed.
TRACE_ERR_INIT_FAILED  The trace failed to initialise.
TRACE_ERR_UNKNOWN_OPTION  Unknown config option.
TRACE_ERR_NO_CONVERSION  This output uri cannot write packets of this type.
TRACE_ERR_BAD_PACKET  This packet is corrupt, or unusable for the action required.
TRACE_ERR_OPTION_UNAVAIL  Option known, but unsupported by this format.
TRACE_ERR_UNSUPPORTED  This feature is unsupported.
TRACE_ERR_BAD_STATE  Illegal use of the API.

enum base_format_t
 

RT protocol base format identifiers This is used to say what kind of packet is being sent over the rt protocol.

enum buf_control_t
 

If a packet has memory allocated If the packet has allocated it's own memory it's buffer_control should be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be free()'d.

If it's doing zerocopy out of memory owned by something else it should be TRACE_CTRL_EXTERNAL.

Note:
the letters p and e are magic numbers used to detect if the packet wasn't created properly

enum libtrace_direction_t
 

Trace directions Note that these are the directions used by convention, more directions are possible, not just these 3, and that they may not conform to this convention.

Enumeration values:
TRACE_DIR_OUTGOING  Packets originating "inside".
TRACE_DIR_INCOMING  Packets originating "outside".
TRACE_DIR_OTHER  Packets with an unknown direction, or one that's unknown.

enum libtrace_dlt_t
 

Enumeration of DLT supported by libtrace.

Enumeration values:
TRACE_DLT_IEEE802_11_RADIO  Radiotap.

enum libtrace_event_t
 

Event types see libtrace_eventobj_t and trace_event.

Enumeration values:
TRACE_EVENT_IOWAIT  Need to block on fd.
TRACE_EVENT_SLEEP  Sleep for some time.
TRACE_EVENT_PACKET  packet has arrived
TRACE_EVENT_TERMINATE  End of trace.

enum libtrace_linktype_t
 

Enumeration of link layer types supported by libtrace.

Enumeration values:
TRACE_TYPE_ETH  802.3 style Ethernet
TRACE_TYPE_ATM  ATM frame.
TRACE_TYPE_80211  802.11 frames
TRACE_TYPE_NONE  Raw IP frames.
TRACE_TYPE_LINUX_SLL  Linux "null" framing.
TRACE_TYPE_PFLOG  FreeBSD's PFlug.
TRACE_TYPE_DUCK  Pseudo link layer for DUCK packets.
TRACE_TYPE_80211_RADIO  Radiotap + 802.11.
TRACE_TYPE_LLCSNAP  Raw LLC/SNAP.
TRACE_TYPE_PPP  PPP frames.
TRACE_TYPE_METADATA  WDCAP-style meta-data.

enum libtrace_radiotap_field_t
 

Enumeration of Radiotap fields.

Enumeration values:
TRACE_RADIOTAP_TSFT  Timer synchronisation function, in microseconds (uint64).
TRACE_RADIOTAP_FLAGS  Wireless flags (uint8).
TRACE_RADIOTAP_RATE  Bitrate in units of 500kbps (uint8).
TRACE_RADIOTAP_CHANNEL  Frequency in MHz (uint16) and channel flags (uint16).
TRACE_RADIOTAP_FHSS  FHSS hop set (uint8) and hopping pattern (uint8).
TRACE_RADIOTAP_DBM_ANTSIGNAL  Signal power in dBm (int8).
TRACE_RADIOTAP_DBM_ANTNOISE  Noise power in dBm (int8).
TRACE_RADIOTAP_LOCK_QUALITY  Barker Code lock quality (uint16).
TRACE_RADIOTAP_TX_ATTENUATION  TX attenuation as unitless distance from max power (uint16).
TRACE_RADIOTAP_DB_TX_ATTENUATION  TX attenutation as dB from max power (uint16).
TRACE_RADIOTAP_DBM_TX_POWER  TX Power in dBm (int8).
TRACE_RADIOTAP_ANTENNA  Antenna frame was rx'd or tx'd on (uint8).
TRACE_RADIOTAP_DB_ANTSIGNAL  Signal power in dB from a fixed reference (uint8).
TRACE_RADIOTAP_DB_ANTNOISE  Noise power in dB from a fixed reference (uint8).
TRACE_RADIOTAP_TX_FLAGS  Properties of received frame (uint16).
TRACE_RADIOTAP_RTS_RETRIES  Properties of transmitted frame (uint16).
TRACE_RADIOTAP_DATA_RETRIES  Number of rts retries frame used (uint8).
TRACE_RADIOTAP_EXT  Number of unicast retries a transmitted frame used (uint8).

enum libtrace_rt_types_t
 

Enumeration values:
TRACE_RT_HELLO  Connection accepted.
TRACE_RT_START  Request for data transmission to begin.
TRACE_RT_ACK  Data acknowledgement.
TRACE_RT_STATUS  Fifo status packet.
TRACE_RT_DUCK  Dag duck info packet.
TRACE_RT_END_DATA  Server is exiting message.
TRACE_RT_CLOSE  Client is exiting message.
TRACE_RT_DENY_CONN  Connection has been denied.
TRACE_RT_PAUSE  Request server to suspend sending data.
TRACE_RT_PAUSE_ACK  Server is paused message.
TRACE_RT_OPTION  Option request.
TRACE_RT_KEYCHANGE  Anonymisation key has changed.
TRACE_RT_DUCK_2_4  Dag 2.4 Duck.
TRACE_RT_DUCK_2_5  Dag 2.5 Duck.
TRACE_RT_LOSTCONN  Lost connection to server.
TRACE_RT_SERVERSTART  Reliable server has been restarted.
TRACE_RT_CLIENTDROP  Reliable client was lost.
TRACE_RT_METADATA  Packet contains server meta-data.
TRACE_RT_DATA_SIMPLE  Trace types that know their link type.
TRACE_RT_DATA_DLT  Pcap doesn't store the linktype per packet, and thus we have to store it in here.

sigh.

enum serverport_t
 

Which port is the server port.

Enumeration values:
USE_DEST  Destination port is the server port.
USE_SOURCE  Source port is the server port.

enum trace_option_output_t
 

Enumeration values:
TRACE_OPTION_OUTPUT_FILEFLAGS  File flags to open the trace file with.

eg O_APPEND

TRACE_OPTION_OUTPUT_COMPRESS  Compression level, eg 6.

enum trace_option_t
 

Valid trace capture options.

Enumeration values:
TRACE_OPTION_SNAPLEN  Number of bytes captured.
TRACE_OPTION_PROMISC  Capture packets to other hosts.
TRACE_OPTION_FILTER  Apply this filter to all packets.
TRACE_OPTION_META_FREQ  Frequency of meta-data information, e.g.

DUCK packets

TRACE_OPTION_EVENT_REALTIME  trace_event ignores gaps between packets when reading traces off disk

Function Documentation

DLLEXPORT int trace_apply_filter (  libtrace_filter_t *  filter,
const libtrace_packet_t *  packet
) 
 

Apply a BPF filter to a packet.

Parameters:
filter the filter opaque pointer
packet the packet opaque pointer
Returns:
>0 if the filter matches, 0 if it doesn't, -1 on error.
Note:
Due to the way BPF filters are built, the filter is not actually compiled until the first time trace_create_filter is called. If your filter is incorrect, it will generate an error message and assert, exiting the program. This behaviour may change to more graceful handling of this error in the future.

DLLEXPORT int trace_config (  libtrace_t *  libtrace,
trace_option_t  option,
void *  value
) 
 

Sets an input config option.

Parameters:
libtrace the trace object to apply the option to
option the option to set
value the value to set the option to
Returns:
-1 if option configuration failed, 0 otherwise This should be called after trace_create, and before trace_start

DLLEXPORT int trace_config_output (  libtrace_out_t *  libtrace,
trace_option_output_t  option,
void *  value
) 
 

Sets an output config option.

Parameters:
libtrace the output trace object to apply the option to
option the option to set
value the value to set the option to
Returns:
-1 if option configuration failed, 0 otherwise This should be called after trace_create_output, and before trace_start_output

DLLEXPORT void trace_construct_packet (  libtrace_packet_t *  packet,
libtrace_linktype_t  linktype,
const void *  data,
uint16_t  len
) 
 

Construct a packet from a buffer.

Parameters:
packet[in,out] Libtrace Packet object to update with the new data.
linktype The linktype of the packet.
[in] data The packet data (including linklayer)
len Length of packet data

DLLEXPORT libtrace_packet_t* trace_copy_packet (  const libtrace_packet_t *  packet  ) 
 

Copy a packet.

Parameters:
packet the source packet to copy
Returns:
a new packet which has the same content as the source packet
Note:
This always involves a copy, which can be slow. Use of this function should be avoided where possible.
The reason you would want to use this function is that a zerocopied
packet from a device is using the devices memory which may be a limited resource. Copying the packet will cause it to be copied into the systems memory.

DLLEXPORT libtrace_t* trace_create (  const char *  uri  ) 
 

Create a trace file from a URI.

Parameters:
uri containing a valid libtrace URI
Returns:
an opaque pointer to a libtrace_t
Valid URI's are:
  • erf:/path/to/erf/file
  • erf:- (stdin)
  • dag:/dev/dagcard
  • pcapint:pcapinterface (eg: pcap:eth0)
  • pcap:/path/to/pcap/file
  • pcap:-
  • rt:hostname
  • rt:hostname:port
  • rtclient:hostname (deprecated)
  • rtclient:hostname:port (deprecated)

If an error occured when attempting to open the trace file, an error trace is returned and trace_get_error should be called to find out if an error occured, and what that error was. The trace is created in the configuration state, you must call trace_start to start the capture.

DLLEXPORT libtrace_t* trace_create_dead (  const char *  uri  ) 
 

Creates a "dummy" trace file that has only the format type set.

Returns:
an opaque pointer to a (sparsely initialised) libtrace_t
IMPORTANT: Do not attempt to call trace_read_packet or other such functions with the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's that are not associated with a libtrace_t structure.

DLLEXPORT SIMPLE_FUNCTION libtrace_filter_t* trace_create_filter (  const char *  filterstring  ) 
 

setup a BPF filter

Parameters:
filterstring a char * containing the bpf filter string
Returns:
opaque pointer pointer to a libtrace_filter_t object
Note:
The filter is not actually compiled at this point, so no correctness tests are performed here. trace_create_filter will always return ok, but if the filter is poorly constructed an error will be generated when the filter is actually used

DLLEXPORT libtrace_filter_t* trace_create_filter_from_bytecode (  void *  bf_insns,
unsigned int  bf_len
) 
 

Setup a BPF filter based on pre-compiled byte-code.

Parameters:
bf_insns A pointer to the start of the byte-code
bf_len The number of BPF instructions
Returns:
an opaque pointer to a libtrace_filter_t object
Note:
The supplied byte-code is not checked for correctness.
Author:
Scott Raynel

DLLEXPORT libtrace_out_t* trace_create_output (  const char *  uri  ) 
 

Creates a trace output file from a URI.