WAND Trace processing  4.0.5
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.

Data Structures

struct  trace_err_t
 Libtrace error information. More...
 
struct  libtrace_packet_t
 The libtrace packet structure. More...
 
struct  libtrace_ip
 Generic IP header structure. More...
 
struct  libtrace_ip6_ext
 IPv6 header extension structure. More...
 
struct  libtrace_ip6_frag
 IPv6 fragmentation header. More...
 
struct  libtrace_ip6
 Generic IPv6 header structure. More...
 
struct  libtrace_tcp
 Generic TCP header structure. More...
 
struct  libtrace_udp
 Generic UDP header structure. More...
 
struct  libtrace_icmp
 Generic ICMP header structure. More...
 
struct  libtrace_icmp6
 Generic ICMPv6 header structure. More...
 
struct  libtrace_llcsnap
 Generic LLC/SNAP header structure. More...
 
struct  libtrace_ether
 802.3 frame More...
 
struct  libtrace_8021q
 802.1Q frame More...
 
struct  libtrace_atm_cell
 ATM User Network Interface (UNI) Cell. More...
 
struct  libtrace_atm_nni_cell
 ATM Network Node/Network Interface (NNI) Cell. More...
 
struct  libtrace_atm_capture_cell
 Captured UNI cell. More...
 
struct  libtrace_atm_nni_capture_cell
 Captured NNI cell. More...
 
struct  libtrace_ppp
 PPP header. More...
 
struct  libtrace_pppoe
 PPPoE header. More...
 
struct  libtrace_gre_t
 Libtrace local definition of GRE (Generalised Routing Protocol) header RFC2890. More...
 
struct  libtrace_vxlan_t
 Libtrace local definition of VXLAN Header (draft-mahalingam-dutt-dcops-vxlan) More...
 
struct  libtrace_80211_t
 802.11 header More...
 
struct  libtrace_radiotap_t
 The Radiotap header pre-amble. More...
 
struct  libtrace_ospf_v2_t
 OSPF header. More...
 
struct  libtrace_ospf_options_t
 Options Field present in some OSPFv2 packets. More...
 
struct  libtrace_ospf_lsa_v2_t
 LSA Header for OSPFv2. More...
 
struct  libtrace_ospf_hello_v2_t
 OSPFv2 Hello Packet. More...
 
struct  libtrace_ospf_db_desc_v2_t
 OSPFv2 Database Description packet. More...
 
struct  libtrace_ospf_ls_req_t
 OSPF Link State Request Packet. More...
 
struct  libtrace_ospf_ls_update_t
 OSPF Link State Update Packet. More...
 
struct  libtrace_ospf_as_external_lsa_t
 OSPFv2 AS External LSA Body. More...
 
struct  libtrace_ospf_summary_lsa
 OSPFv2 Summary LSA Body. More...
 
struct  libtrace_ospf_network_lsa_t
 OSPFv2 Network LSA Body. More...
 
struct  libtrace_ospf_link_t
 OSPFv2 Router Link structure. More...
 
struct  libtrace_ospf_router_lsa_t
 OSPFv2 Router LSA. More...
 
struct  libtrace_sll_header_t
 A local definition of an SLL header. More...
 
struct  libtrace_stat_t
 Statistic counters are cumulative from the time the trace is started. More...
 
struct  libtrace_eventobj_t
 Structure returned by libtrace_event explaining what the current event is. More...
 

Macros

#define ct_assert(e)   extern char (*ct_assert(void)) [sizeof(char[1 - 2*!(e)])]
 
#define LIBTRACE_API_VERSION   ((4<<16)|(0<<8)|(5))
 API version as 2 byte hex digits, eg 0xXXYYZZ. More...
 
#define LIBTRACE_SVN_REVISION   LIBTRACE_API_VERSION
 This used to be replaced with the current SVN revision number when 'make dist' was invoked to create a distributable tarball. More...
 
#define DAG_DRIVER_V   ""
 DAG driver version installed on the current system. More...
 
#define ASSERT_RET(run, cond)   assert(run cond)
 A version of assert that always runs the first argument even when not debugging, however only asserts the condition if debugging Intended for use mainly with pthread locks etc. More...
 
#define LT_BITFIELD8   unsigned int
 
#define LT_BITFIELD16   unsigned int
 
#define LT_BITFIELD32   unsigned int
 
#define LT_BITFIELD64   unsigned int
 
#define LT_USE_PACKED   1
 
#define LT_USE_UNUSED   1
 
#define LT_USE_DEPRECATED   1
 
#define LT_USE_PURE   1
 
#define LT_USE_PRINTF   1
 
#define LT_USE_VISIBILITY   1
 
#define PACKED   __attribute__((packed))
 
#define UNUSED   __attribute__((unused))
 
#define DEPRECATED   __attribute__((deprecated))
 
#define SIMPLE_FUNCTION   __attribute__((pure))
 
#define PRINTF(formatpos, argpos)   __attribute__((format(printf,formatpos, argpos)))
 
#define CACHE_LINE_SIZE   64
 
#define ALIGN_STRUCT(x)   __attribute__((aligned(x)))
 
#define DLLEXPORT
 
#define DLLLOCAL
 
#define LIBTRACE_PACKET_BUFSIZE   65536
 The size of a packet's buffer when managed by libtrace. More...
 
#define IS_LIBTRACE_META_PACKET(packet)   (packet->type < TRACE_RT_DATA_SIMPLE)
 
#define X(name)   LT_BITFIELD64 name ##_valid : 1;
 

Typedefs

typedef struct libtrace_out_t libtrace_out_t
 Opaque structure holding information about an output trace. More...
 
typedef struct libtrace_t libtrace_t
 Opaque structure holding information about a trace. More...
 
typedef struct libtrace_filter_t libtrace_filter_t
 Opaque structure holding information about a bpf filter. More...
 
typedef struct libtrace_thread_t libtrace_thread_t
 Opaque structure holding information about libtrace thread. More...
 
typedef struct callback_set libtrace_callback_set_t
 Opaque structure holding callback functions for libtrace threads. More...
 
typedef struct trace_err_t libtrace_err_t
 Libtrace error information. More...
 
typedef struct libtrace_packet_t libtrace_packet_t
 The libtrace packet structure. More...
 

Enumerations

enum  buf_control_t { TRACE_CTRL_PACKET ='p', TRACE_CTRL_EXTERNAL ='e' }
 If the packet has allocated its own memory the buffer_control should be set to TRACE_CTRL_PACKET, so that the memory will be freed when the packet is destroyed. 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, TRACE_ERR_BAD_FILTER = -9, TRACE_ERR_RT_FAILURE = -10, TRACE_ERR_UNSUPPORTED_COMPRESS = -11,
  TRACE_ERR_WANDIO_FAILED = -12
}
 Enumeration of error codes. More...
 
enum  libtrace_dlt_t {
  TRACE_DLT_ERROR = -1, TRACE_DLT_NULL = 0, TRACE_DLT_EN10MB = 1, TRACE_DLT_PPP = 9,
  TRACE_DLT_ATM_RFC1483 = 11, TRACE_DLT_RAW = 12, TRACE_DLT_OPENBSD_LOOP = 108, TRACE_DLT_PPP_SERIAL = 50,
  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 DLTs supported by libtrace. More...
 
enum  libtrace_linktype_t {
  TRACE_TYPE_CONTENT_INVALID = -2, TRACE_TYPE_UNKNOWN = -1, 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, TRACE_TYPE_NONDATA = 19, TRACE_TYPE_OPENBSD_LOOP = 20, TRACE_TYPE_ERF_META = 21,
  TRACE_TYPE_ETSILI = 22
}
 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, TRACE_FORMAT_LINUX_RING =15, TRACE_FORMAT_RAWERF =16,
  TRACE_FORMAT_DPDK =17, TRACE_FORMAT_PCAPNG =18, TRACE_FORMAT_NDAG =19, TRACE_FORMAT_DPDK_NDAG =20,
  TRACE_FORMAT_ETSILIVE =21
}
 RT protocol base format identifiers. 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_DUCK_5_0 =19, TRACE_RT_PCAPNG_META =20,
  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_LINUX_RING =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_RING, TRACE_RT_DATA_DPDK =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_DPDK,
  TRACE_RT_DATA_ETSILI = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_ETSILIVE, 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_DATA_BPF = 3000, TRACE_RT_BPF_NULL = TRACE_RT_DATA_BPF+TRACE_DLT_NULL, TRACE_RT_BPF_EN10MB = TRACE_RT_DATA_BPF+TRACE_DLT_EN10MB,
  TRACE_RT_BPF_IEEE802_11 = TRACE_RT_DATA_BPF+TRACE_DLT_IEEE802_11, TRACE_RT_BPF_PFLOG =TRACE_RT_DATA_BPF+TRACE_DLT_PFLOG, TRACE_RT_BPF_ATM_RFC1483 =TRACE_RT_DATA_BPF+TRACE_DLT_ATM_RFC1483, TRACE_RT_DATA_BPF_END = 3999,
  TRACE_RT_DATA_PCAPNG = 4000, TRACE_RT_DATA_PCAPNG_END = 4499, TRACE_RT_LAST = 4500
}
 RT protocol packet types. More...
 
enum  libtrace_ipproto_t {
  TRACE_IPPROTO_IP = 0, TRACE_IPPROTO_ICMP = 1, TRACE_IPPROTO_IGMP = 2, TRACE_IPPROTO_IPIP = 4,
  TRACE_IPPROTO_TCP = 6, TRACE_IPPROTO_UDP = 17, TRACE_IPPROTO_IPV6 = 41, TRACE_IPPROTO_ROUTING = 43,
  TRACE_IPPROTO_FRAGMENT = 44, TRACE_IPPROTO_RSVP = 46, TRACE_IPPROTO_GRE = 47, TRACE_IPPROTO_ESP = 50,
  TRACE_IPPROTO_AH = 51, TRACE_IPPROTO_ICMPV6 = 58, TRACE_IPPROTO_NONE = 59, TRACE_IPPROTO_DSTOPTS = 60,
  TRACE_IPPROTO_OSPF = 89, TRACE_IPPROTO_PIM = 103, TRACE_IPPROTO_SCTP = 132
}
 IP Protocol values. More...
 
enum  libtrace_ethertype_t {
  TRACE_ETHERTYPE_LOOPBACK = 0x0060, TRACE_ETHERTYPE_IP = 0x0800, TRACE_ETHERTYPE_ARP = 0x0806, TRACE_ETHERTYPE_RARP = 0x8035,
  TRACE_ETHERTYPE_8021Q = 0x8100, TRACE_ETHERTYPE_IPV6 = 0x86DD, TRACE_ETHERTYPE_MPLS = 0x8847, TRACE_ETHERTYPE_MPLS_MC = 0x8848,
  TRACE_ETHERTYPE_PPP_DISC = 0x8863, TRACE_ETHERTYPE_PPP_SES = 0x8864
}
 Ethertypes supported by Libtrace. More...
 
enum  libtrace_direction_t { TRACE_DIR_OUTGOING = 0, TRACE_DIR_INCOMING = 1, TRACE_DIR_OTHER = 2, TRACE_DIR_UNKNOWN = -1 }
 Trace directions. 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...
 

Functions

DLLEXPORT void trace_help (void)
 Prints help information for libtrace. More...
 
DLLEXPORT void trace_interrupt (void)
 Causes a libtrace reader to stop blocking whilst waiting on new packets and immediately return EOF. More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_linktype_t 
trace_get_link_type (const libtrace_packet_t *packet)
 Gets the link layer type for a packet. More...
 
DLLEXPORT libtrace_direction_t trace_set_direction (libtrace_packet_t *packet, libtrace_direction_t direction)
 Set the direction flag for a packet, if the capture format supports direction tagging. More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_direction_t 
trace_get_direction (const libtrace_packet_t *packet)
 Get the direction flag for a packet, if it has one. More...
 
Protocol decodes

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

A packet is divided up into several "layers.":

  • Framing header – This is the header provided by the capture format itself rather than anything that was sent over the network. This provides basic details about the packet record including capture lengths, wire lengths, timestamps, direction information and any other metadata that is part of the capture format.
  • Metadata header (optional) – A header containing metadata about a packet that was captured, but the metadata was not transmitted over the wire. Some examples include RadioTap and Linux_sll headers. This can be retrieved by trace_get_packet_meta(), or skipped using trace_get_payload_from_meta(). There may be multiple "metadata" headers on a packet.
  • Layer 5/transport – These are protocols carried in IPv4/IPv6 frames. These can be retrieved using trace_get_transport().
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. More...
 
DLLEXPORT SIMPLE_FUNCTION
DEPRECATED void * 
trace_get_link (const libtrace_packet_t *packet)
 Get a pointer to the link layer for a given packet. More...
 
DLLEXPORT libtrace_packet_ttrace_strip_packet (libtrace_packet_t *packet)
 Strips layer 2.5 headers from a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_ip_t
trace_get_ip (libtrace_packet_t *packet)
 Get a pointer to the IPv4 header (if any) for a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_ip6_t
trace_get_ip6 (libtrace_packet_t *packet)
 get a pointer to the IPv6 header (if any) More...
 
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. More...
 
DLLEXPORT void * trace_get_payload_from_meta (const void *meta, libtrace_linktype_t *linktype, uint32_t *remaining)
 Returns the payload of a metadata header. More...
 
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. More...
 
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 following a layer 2 header. More...
 
DLLEXPORT void * trace_get_layer3 (const libtrace_packet_t *packet, uint16_t *ethertype, uint32_t *remaining)
 Get a pointer to the layer 3 (e.g. More...
 
DLLEXPORT uint16_t * trace_checksum_layer3 (libtrace_packet_t *packet, uint16_t *csum)
 Calculates the expected IP checksum for a packet. More...
 
DLLEXPORT uint16_t * trace_checksum_transport (libtrace_packet_t *packet, uint16_t *csum)
 Calculates the expected checksum for the transport header in a packet. More...
 
DLLEXPORT uint16_t trace_get_fragment_offset (const libtrace_packet_t *packet, uint8_t *more)
 Calculates the fragment offset in bytes for an IP packet. More...
 
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) More...
 
DLLEXPORT void * trace_get_payload_from_ip (libtrace_ip_t *ip, uint8_t *proto, uint32_t *remaining)
 Gets a pointer to the payload following an IPv4 header. More...
 
DLLEXPORT void * trace_get_payload_from_ip6 (libtrace_ip6_t *ipptr, uint8_t *proto, uint32_t *remaining)
 Gets a pointer to the payload following an IPv6 header. More...
 
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 following a link header. More...
 
DLLEXPORT void * trace_get_payload_from_vlan (void *vlan, uint16_t *type, uint32_t *remaining)
 Gets a pointer to the payload following an 802.1q (VLAN) header. More...
 
DLLEXPORT void * trace_get_payload_from_mpls (void *mpls, uint16_t *type, uint32_t *remaining)
 Gets a pointer to the payload following an MPLS header. More...
 
DLLEXPORT void * trace_get_payload_from_pppoe (void *pppoe, uint16_t *type, uint32_t *remaining)
 Gets a pointer to the payload following a PPPoE header. More...
 
DLLEXPORT void * trace_get_payload_from_tcp (libtrace_tcp_t *tcp, uint32_t *remaining)
 Gets a pointer to the payload following a TCP header. More...
 
DLLEXPORT void * trace_get_payload_from_udp (libtrace_udp_t *udp, uint32_t *remaining)
 Gets a pointer to the payload following a UDP header. More...
 
DLLEXPORT void * trace_get_payload_from_icmp (libtrace_icmp_t *icmp, uint32_t *remaining)
 Gets a pointer to the payload following a ICMP header. More...
 
DLLEXPORT void * trace_get_payload_from_icmp6 (libtrace_icmp6_t *icmp, uint32_t *remaining)
 Gets a pointer to the payload following a ICMPv6 header. More...
 
DLLEXPORT void * trace_get_payload_from_gre (libtrace_gre_t *gre, uint32_t *remaining)
 Gets a pointer to the payload following a GRE header. More...
 
DLLEXPORT libtrace_vxlan_ttrace_get_vxlan_from_udp (libtrace_udp_t *udp, uint32_t *remaining)
 Gets a pointer to the payload following a VXLAN header. More...
 
DLLEXPORT void * trace_get_payload_from_vxlan (libtrace_vxlan_t *vxlan, uint32_t *remaining)
 Gets a pointer to the payload following a VXLAN header. More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_tcp_t
trace_get_tcp (libtrace_packet_t *packet)
 Get a pointer to the TCP header (if present) More...
 
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 following an IPv4 header (if present) More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_udp_t
trace_get_udp (libtrace_packet_t *packet)
 Get a pointer to the UDP header (if present) More...
 
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 following an IPv4 header (if present) More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_icmp_t
trace_get_icmp (libtrace_packet_t *packet)
 Get a pointer to the ICMP header (if present) More...
 
DLLEXPORT SIMPLE_FUNCTION
libtrace_icmp6_t
trace_get_icmp6 (libtrace_packet_t *packet)
 Get a pointer to the ICMPv6 header (if present) More...
 
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 following an IPv4 header (if present) More...
 
DLLEXPORT SIMPLE_FUNCTION void * trace_get_ospf_header (libtrace_packet_t *packet, uint8_t *version, uint32_t *remaining)
 Get a pointer to the OSPF header (if present) More...
 
DLLEXPORT SIMPLE_FUNCTION void * trace_get_ospf_contents_v2 (libtrace_ospf_v2_t *header, uint8_t *ospf_type, uint32_t *remaining)
 Get a pointer to the contents of the OSPF packet after the OSPF header. More...
 
DLLEXPORT SIMPLE_FUNCTION
unsigned char * 
trace_get_first_ospf_lsa_from_update_v2 (libtrace_ospf_ls_update_t *ls_update, uint32_t *remaining)
 Get a pointer to the start of the first LSA contained within an LS Update packet. More...
 
DLLEXPORT SIMPLE_FUNCTION
unsigned char * 
trace_get_first_ospf_lsa_from_db_desc_v2 (libtrace_ospf_db_desc_v2_t *db_desc, uint32_t *remaining)
 Get a pointer to the start of the first LSA contained within an Database Description packet. More...
 
DLLEXPORT SIMPLE_FUNCTION
unsigned char * 
trace_get_first_ospf_link_from_router_lsa_v2 (libtrace_ospf_router_lsa_v2_t *lsa, uint32_t *remaining)
 Get a pointer to the start of the first link contained within a Router LSA. More...
 
DLLEXPORT SIMPLE_FUNCTION int trace_get_next_ospf_link_v2 (unsigned char **current, libtrace_ospf_link_v2_t **link, uint32_t *remaining, uint32_t *link_len)
 Parses an OSPF Router LSA Link and finds the next Link (if there is one) More...
 
DLLEXPORT SIMPLE_FUNCTION int trace_get_next_ospf_lsa_v2 (unsigned char **current, libtrace_ospf_lsa_v2_t **lsa_hdr, unsigned char **lsa_body, uint32_t *remaining, uint8_t *lsa_type, uint16_t *lsa_length)
 Parses an OSPF LSA and finds the next LSA (if there is one) More...
 
DLLEXPORT SIMPLE_FUNCTION int trace_get_next_ospf_lsa_header_v2 (unsigned char **current, libtrace_ospf_lsa_v2_t **lsa_hdr, uint32_t *remaining, uint8_t *lsa_type, uint16_t *lsa_length)
 Parses an OSPF LSA header and finds the next LSA (if there is one) More...
 
DLLEXPORT SIMPLE_FUNCTION uint32_t trace_get_ospf_metric_from_as_external_lsa_v2 (libtrace_ospf_as_external_lsa_v2_t *as_lsa)
 Extracts the metric field from an AS External LSA packet. More...
 
DLLEXPORT SIMPLE_FUNCTION uint32_t trace_get_ospf_metric_from_summary_lsa_v2 (libtrace_ospf_summary_lsa_v2_t *sum_lsa)
 Extracts the metric field from a Summary LSA packet. More...
 
DLLEXPORT SIMPLE_FUNCTION uint8_t * trace_get_destination_mac (libtrace_packet_t *packet)
 Gets the destination MAC address for a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION uint8_t * trace_get_source_mac (libtrace_packet_t *packet)
 Gets the source MAC address for a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION
struct sockaddr * 
trace_get_source_address (const libtrace_packet_t *packet, struct sockaddr *addr)
 Get the source IP address for a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION char * trace_get_source_address_string (const libtrace_packet_t *packet, char *space, int spacelen)
 Get the source IP address for a packet and convert it into a string. More...
 
DLLEXPORT SIMPLE_FUNCTION
struct sockaddr * 
trace_get_destination_address (const libtrace_packet_t *packet, struct sockaddr *addr)
 Get the destination IP address for a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION char * trace_get_destination_address_string (const libtrace_packet_t *packet, char *space, int spacelen)
 Get the destination IP address for a packet and convert it into a string. More...
 
DLLEXPORT int trace_get_next_option (unsigned char **ptr, int *len, unsigned char *type, unsigned char *optlen, unsigned char **data)
 Parses an IP or TCP option. More...
 
Time

These functions deal with the timestamp describing when a packet was captured and can convert it into various formats

DLLEXPORT SIMPLE_FUNCTION uint64_t trace_get_erf_timestamp (const libtrace_packet_t *packet)
 Get the packet timestamp in the DAG time format. More...
 
DLLEXPORT SIMPLE_FUNCTION
struct timeval 
trace_get_timeval (const libtrace_packet_t *packet)
 Get the packet timestamp as a struct timeval. More...
 
DLLEXPORT SIMPLE_FUNCTION
struct timespec 
trace_get_timespec (const libtrace_packet_t *packet)
 Get the packet timestamp as a struct timespec. More...
 
DLLEXPORT SIMPLE_FUNCTION double trace_get_seconds (const libtrace_packet_t *packet)
 Get the packet timestamp in floating point seconds. More...
 
DLLEXPORT int trace_seek_seconds (libtrace_t *trace, double seconds)
 Seek within an input trace to a time specified in floating point seconds. More...
 
DLLEXPORT int trace_seek_timeval (libtrace_t *trace, struct timeval tv)
 Seek within an input trace to a time specified as a timeval. More...
 
DLLEXPORT int trace_seek_erf_timestamp (libtrace_t *trace, uint64_t ts)
 Seek within an input trace to a time specified as an ERF timestamp. More...
 
Sizes

This section deals with finding or setting the various different lengths that a packet can have, e.g.

capture lengths, wire lengths, etc.

DLLEXPORT SIMPLE_FUNCTION size_t trace_get_capture_length (const libtrace_packet_t *packet)
 Get the current size of the packet (in bytes), taking into account any truncation or snapping that may have previously been performed. More...
 
DLLEXPORT SIMPLE_FUNCTION size_t trace_get_wire_length (const libtrace_packet_t *packet)
 Get the size of the packet as it was originally seen on the wire (in bytes). More...
 
DLLEXPORT SIMPLE_FUNCTION size_t trace_get_framing_length (const libtrace_packet_t *packet)
 Get the length of the capture framing headers (in bytes). More...
 
DLLEXPORT SIMPLE_FUNCTION size_t trace_get_payload_length (const libtrace_packet_t *packet)
 Get the length of the original payload content of the packet (in bytes). More...
 
DLLEXPORT size_t trace_set_capture_length (libtrace_packet_t *packet, size_t size)
 Truncate ("snap") the packet to the suggested length. More...
 
BPF

This section deals with using Berkley Packet Filters to filter input traces

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

This section contains functions that deal with portability issues, e.g.

byte ordering.

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

Protocol structures

These convenience structures provide portable versions of the headers for a variety of protocols.

#define LIBTRACE_GRE_FLAG_CHECKSUM   0x8000
 
#define LIBTRACE_GRE_FLAG_KEY   0x2000
 
#define LIBTRACE_GRE_FLAG_SEQ   0x1000
 
#define LIBTRACE_GRE_FLAG_VERMASK   0x0007
 
#define LIBTRACE_GRE_FLAG_ACK   0x0080
 
#define LIBTRACE_GRE_PPTP_VERSION   0x0001
 
#define TRACE_SLL_HOST   0
 Packet was addressed for the local host. More...
 
#define TRACE_SLL_BROADCAST   1
 Packet was addressed for a broadcast address. More...
 
#define TRACE_SLL_MULTICAST   2
 Packet was addressed for a multicast address. More...
 
#define TRACE_SLL_OTHERHOST   3
 Packet was addressed for another host but was captured by a promiscuous device. More...
 
#define TRACE_SLL_OUTGOING   4
 Packet originated from the local host. More...
 
enum  libtrace_ospf_types_t {
  TRACE_OSPF_HELLO = 1, TRACE_OSPF_DATADESC = 2, TRACE_OSPF_LSREQ = 3, TRACE_OSPF_LSUPDATE = 4,
  TRACE_OSPF_LSACK = 5
}
 OSPF message types. More...
 
enum  libtrace_ospf_ls_types_t {
  TRACE_OSPF_LS_ROUTER = 1, TRACE_OSPF_LS_NETWORK = 2, TRACE_OSPF_LS_SUMMARY = 3, TRACE_OSPF_LS_ASBR_SUMMARY = 4,
  TRACE_OSPF_LS_EXTERNAL = 5
}
 OSPF link state acknowledgement types. More...
 
typedef struct libtrace_ip libtrace_ip_t
 Generic IP header structure. More...
 
typedef struct libtrace_ip6_ext libtrace_ip6_ext_t
 IPv6 header extension structure. More...
 
typedef struct libtrace_ip6_frag libtrace_ip6_frag_t
 IPv6 fragmentation header. More...
 
typedef struct libtrace_ip6 libtrace_ip6_t
 Generic IPv6 header structure. More...
 
typedef struct libtrace_tcp libtrace_tcp_t
 Generic TCP header structure. More...
 
typedef struct libtrace_udp libtrace_udp_t
 Generic UDP header structure. More...
 
typedef struct libtrace_icmp libtrace_icmp_t
 Generic ICMP header structure. More...
 
typedef struct libtrace_icmp6 libtrace_icmp6_t
 Generic ICMPv6 header structure. More...
 
typedef struct libtrace_llcsnap libtrace_llcsnap_t
 Generic LLC/SNAP header structure. More...
 
typedef struct libtrace_ether libtrace_ether_t
 802.3 frame More...
 
typedef struct libtrace_8021q libtrace_8021q_t
 802.1Q frame More...
 
typedef struct libtrace_atm_cell libtrace_atm_cell_t
 ATM User Network Interface (UNI) Cell. More...
 
typedef struct
libtrace_atm_nni_cell 
libtrace_atm_nni_cell_t
 ATM Network Node/Network Interface (NNI) Cell. More...
 
typedef struct
libtrace_atm_capture_cell 
libtrace_atm_capture_cell_t
 Captured UNI cell. More...
 
typedef struct
libtrace_atm_nni_capture_cell 
libtrace_atm_nni_capture_cell_t
 Captured NNI cell. More...
 
typedef struct libtrace_ppp libtrace_ppp_t
 PPP header. More...
 
typedef struct libtrace_pppoe libtrace_pppoe_t
 PPPoE header. More...
 
typedef struct libtrace_gre_t libtrace_gre_t
 Libtrace local definition of GRE (Generalised Routing Protocol) header RFC2890. More...
 
typedef struct libtrace_vxlan_t libtrace_vxlan_t
 Libtrace local definition of VXLAN Header (draft-mahalingam-dutt-dcops-vxlan) More...
 
typedef struct libtrace_80211_t libtrace_80211_t
 802.11 header More...
 
typedef struct libtrace_radiotap_t libtrace_radiotap_t
 The Radiotap header pre-amble. More...
 
typedef struct libtrace_ospf_v2_t libtrace_ospf_v2_t
 OSPF header. More...
 
typedef struct
libtrace_ospf_options_t 
libtrace_ospf_options_t
 Options Field present in some OSPFv2 packets. More...
 
typedef struct
libtrace_ospf_lsa_v2_t 
libtrace_ospf_lsa_v2_t
 LSA Header for OSPFv2. More...
 
typedef struct
libtrace_ospf_hello_v2_t 
libtrace_ospf_hello_v2_t
 OSPFv2 Hello Packet. More...
 
typedef struct
libtrace_ospf_db_desc_v2_t 
libtrace_ospf_db_desc_v2_t
 OSPFv2 Database Description packet. More...
 
typedef struct
libtrace_ospf_ls_req_t 
libtrace_ospf_ls_req_t
 OSPF Link State Request Packet. More...
 
typedef struct
libtrace_ospf_ls_update_t 
libtrace_ospf_ls_update_t
 OSPF Link State Update Packet. More...
 
typedef struct
libtrace_ospf_as_external_lsa_t 
libtrace_ospf_as_external_lsa_v2_t
 OSPFv2 AS External LSA Body. More...
 
typedef struct
libtrace_ospf_summary_lsa 
libtrace_ospf_summary_lsa_v2_t
 OSPFv2 Summary LSA Body. More...
 
typedef struct
libtrace_ospf_network_lsa_t 
libtrace_ospf_network_lsa_v2_t
 OSPFv2 Network LSA Body. More...
 
typedef struct libtrace_ospf_link_t libtrace_ospf_link_v2_t
 OSPFv2 Router Link structure. More...
 
typedef struct
libtrace_ospf_router_lsa_t 
libtrace_ospf_router_lsa_v2_t
 OSPFv2 Router LSA. More...
 
typedef struct
libtrace_sll_header_t 
libtrace_sll_header_t
 A local definition of an SLL header. More...
 

Trace management

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

#define LIBTRACE_STAT_FIELDS
 An X Macro set for libtrace stat fields. More...
 
enum  trace_option_t {
  TRACE_OPTION_SNAPLEN, TRACE_OPTION_PROMISC, TRACE_OPTION_FILTER, TRACE_OPTION_META_FREQ,
  TRACE_OPTION_EVENT_REALTIME, TRACE_OPTION_HASHER, TRACE_OPTION_REPLAY_SPEEDUP
}
 Valid configuration options for input traces. More...
 
enum  trace_option_compresstype_t {
  TRACE_OPTION_COMPRESSTYPE_NONE = 0, TRACE_OPTION_COMPRESSTYPE_ZLIB = 1, TRACE_OPTION_COMPRESSTYPE_BZ2 = 2, TRACE_OPTION_COMPRESSTYPE_LZO = 3,
  TRACE_OPTION_COMPRESSTYPE_LZMA = 4, TRACE_OPTION_COMPRESSTYPE_LAST
}
 Valid compression types Note, this must be kept in sync with WANDIO_COMPRESS_* numbers in wandio.h. More...
 
enum  trace_option_output_t { TRACE_OPTION_OUTPUT_FILEFLAGS, TRACE_OPTION_OUTPUT_COMPRESS, TRACE_OPTION_OUTPUT_COMPRESSTYPE }
 Valid configuration options for output traces. More...
 
typedef struct libtrace_stat_t libtrace_stat_t
 Statistic counters are cumulative from the time the trace is started. More...
 
DLLEXPORT const char * trace_parse_uri (const char *uri, char **format)
 Takes a uri and splits it into a format and uridata component. More...
 
DLLEXPORT libtrace_ttrace_create (const char *uri)
 Create an input trace from a URI. More...
 
DLLEXPORT libtrace_ttrace_create_dead (const char *uri)
 Creates a "dummy" trace file that has only the format type set. More...
 
DLLEXPORT libtrace_out_ttrace_create_output (const char *uri)
 Creates a trace output file from a URI. More...
 
DLLEXPORT int trace_start (libtrace_t *libtrace)
 Start an input trace. More...
 
DLLEXPORT int trace_pause (libtrace_t *libtrace)
 Pauses an input trace. More...
 
DLLEXPORT int trace_start_output (libtrace_out_t *libtrace)
 Start an output trace. More...
 
DLLEXPORT int trace_config (libtrace_t *libtrace, trace_option_t option, void *value)
 Sets an input config option. More...
 
DLLEXPORT int trace_set_snaplen (libtrace_t *trace, int snaplen)
 Maximum number of bytes to be captured for any given packet. More...
 
DLLEXPORT int trace_set_promisc (libtrace_t *trace, bool promisc)
 If enabled, places a live capture interface into promiscuous mode. More...
 
DLLEXPORT int trace_set_filter (libtrace_t *trace, libtrace_filter_t *filter)
 Apply this filter to all packets read from this trace. More...
 
DLLEXPORT int trace_set_meta_freq (libtrace_t *trace, int freq)
 Defines the frequency of meta-data reporting, e.g. More...
 
DLLEXPORT int trace_set_event_realtime (libtrace_t *trace, bool realtime)
 If enabled, the libtrace event API will ignore time gaps between packets when reading from a trace file. More...
 
 ct_assert (offsetof(libtrace_stat_t, accepted)==8)
 
DLLEXPORT int trace_config_output (libtrace_out_t *libtrace, trace_option_output_t option, void *value)
 Sets an output config option. More...
 
DLLEXPORT void trace_destroy (libtrace_t *trace)
 Close an input trace, freeing up any resources it may have been using. More...
 
DLLEXPORT void trace_destroy_dead (libtrace_t *trace)
 Close a dummy trace file, freeing up any resources it may have been using. More...
 
DLLEXPORT void trace_destroy_output (libtrace_out_t *trace)
 Close an output trace, freeing up any resources it may have been using. More...
 
DLLEXPORT int trace_flush_output (libtrace_out_t *libtrace)
 Flush an output trace, forcing any buffered packets to be written. More...
 
DLLEXPORT libtrace_err_t trace_get_err (libtrace_t *trace)
 Check (and clear) the current error state of an input trace. More...
 
DLLEXPORT bool trace_is_err (libtrace_t *trace)
 Indicate if there has been an error on an input trace. More...
 
DLLEXPORT void trace_perror (libtrace_t *trace, const char *msg,...) PRINTF(2
 Outputs the error message for an input trace to stderr and clear the error status. More...
 
DLLEXPORT void DLLEXPORT
libtrace_err_t 
trace_get_err_output (libtrace_out_t *trace)
 Checks (and clears) the current error state for an output trace. More...
 
DLLEXPORT bool trace_is_err_output (libtrace_out_t *trace)
 Indicates if there is an error on an output trace. More...
 
DLLEXPORT void trace_perror_output (libtrace_out_t *trace, const char *msg,...) PRINTF(2
 Outputs the error message for an output trace to stderr and clear the error status. More...
 
DLLEXPORT void DLLEXPORT
DEPRECATED uint64_t 
trace_get_received_packets (libtrace_t *trace)
 Returns the number of packets observed on an input trace. More...
 
DLLEXPORT DEPRECATED uint64_t trace_get_filtered_packets (libtrace_t *trace)
 Returns the number of packets that were captured, but discarded for not matching a provided filter. More...
 
DLLEXPORT DEPRECATED uint64_t trace_get_dropped_packets (libtrace_t *trace)
 Returns the number of packets that have been dropped on an input trace due to lack of buffer space on the capturing device. More...
 
DLLEXPORT DEPRECATED uint64_t trace_get_accepted_packets (libtrace_t *trace)
 Returns the number of packets that have been read from the input trace using trace_read_packet(). More...
 
DLLEXPORT libtrace_stat_ttrace_get_statistics (libtrace_t *trace, libtrace_stat_t *stats)
 Returns statistic counters for a trace, for a parallel trace this is a combined total. More...
 
DLLEXPORT void trace_get_thread_statistics (libtrace_t *trace, libtrace_thread_t *t, libtrace_stat_t *stats)
 Returns statistic counters for a single thread of a trace. More...
 
DLLEXPORT libtrace_stat_ttrace_create_statistics (void)
 Creates and returns a zeroed libtrace_stat_t structure. More...
 
DLLEXPORT void trace_clear_statistics (libtrace_stat_t *s)
 Clear all fields of given statistic. More...
 
DLLEXPORT void trace_subtract_statistics (const libtrace_stat_t *a, const libtrace_stat_t *b, libtrace_stat_t *c)
 Performs the operation c=a-b accounting for valid fields. More...
 
DLLEXPORT void trace_add_statistics (const libtrace_stat_t *a, const libtrace_stat_t *b, libtrace_stat_t *c)
 Performs operation c=a+b accounting for valid fields. More...
 
DLLEXPORT int trace_print_statistics (const libtrace_stat_t *s, FILE *f, const char *format)
 Prints all valid stats to a file stream, (which could be stdout/err). More...
 

Reading / Writing packets

These members deal with creating, reading and writing packets

enum  { TRACE_PREP_OWN_BUFFER =1, TRACE_PREP_DO_NOT_OWN_BUFFER =0 }
 Flags for prepare_packet functions. More...
 
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...
 
typedef struct libtrace_eventobj_t libtrace_eventobj_t
 Structure returned by libtrace_event explaining what the current event is. More...
 
DLLEXPORT libtrace_packet_ttrace_create_packet (void)
 Create a new packet object. More...
 
DLLEXPORT libtrace_packet_ttrace_copy_packet (const libtrace_packet_t *packet)
 Copy a packet object. More...
 
DLLEXPORT void trace_destroy_packet (libtrace_packet_t *packet)
 Destroy a packet object. More...
 
DLLEXPORT int trace_read_packet (libtrace_t *trace, libtrace_packet_t *packet)
 Read the next packet from an input trace. More...
 
DLLEXPORT 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. More...
 
DLLEXPORT libtrace_eventobj_t trace_event (libtrace_t *trace, libtrace_packet_t *packet)
 Processes the next libtrace event from an input trace. More...
 
DLLEXPORT int trace_write_packet (libtrace_out_t *trace, libtrace_packet_t *packet)
 Write one packet out to the output trace. More...
 
DLLEXPORT enum base_format_t trace_get_format (struct libtrace_packet_t *packet)
 Gets the capture format for a given packet. More...
 
DLLEXPORT void trace_construct_packet (libtrace_packet_t *packet, libtrace_linktype_t linktype, const void *data, uint16_t len)
 Construct a libtrace packet from a buffer containing the packet payload. More...
 

Ports

This section contains functions for dealing with port numbers at the transport layer.

enum  serverport_t { USE_DEST, USE_SOURCE }
 An indication of which port is the "server" port for a given port pair. More...
 
DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_source_port (const libtrace_packet_t *packet)
 Gets the source port for a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_destination_port (const libtrace_packet_t *packet)
 Gets the destination port for a given packet. More...
 
DLLEXPORT SIMPLE_FUNCTION int8_t trace_get_server_port (uint8_t protocol, uint16_t source, uint16_t dest)
 Hint at which of the two provided ports is the server port. More...
 

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_packet_meta()) 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
 libc doesn't define this yet, so we have to do so ourselves More...
 
DLLEXPORT bool trace_get_wireless_tsft (void *linkptr, libtrace_linktype_t linktype, uint64_t *tsft)
 Get the wireless Timer Synchronisation Function. More...
 
DLLEXPORT bool trace_get_wireless_rate (void *linkptr, libtrace_linktype_t linktype, uint8_t *rate)
 Get the wireless data rate. More...
 
DLLEXPORT bool trace_get_wireless_freq (void *linkptr, libtrace_linktype_t linktype, uint16_t *freq)
 Get the wireless channel frequency. More...
 
DLLEXPORT bool trace_get_wireless_signal_strength_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *strength)
 Get the wireless signal strength in dBm. More...
 
DLLEXPORT bool trace_get_wireless_noise_strength_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *strength)
 Get the wireless noise strength in dBm. More...
 
DLLEXPORT bool trace_get_wireless_signal_strength_db (void *linkptr, libtrace_linktype_t linktype, uint8_t *strength)
 Get the wireless signal strength in dB. More...
 
DLLEXPORT bool trace_get_wireless_noise_strength_db (void *linkptr, libtrace_linktype_t linktype, uint8_t *strength)
 Get the wireless noise strength in dB. More...
 
DLLEXPORT bool trace_get_wireless_tx_attenuation (void *linkptr, libtrace_linktype_t linktype, uint16_t *attenuation)
 Get the wireless transmit attenuation. More...
 
DLLEXPORT bool trace_get_wireless_tx_attenuation_db (void *linkptr, libtrace_linktype_t linktype, uint16_t *attenuation)
 Get the wireless transmit attenuation in dB. More...
 
DLLEXPORT bool trace_get_wireless_tx_power_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *txpower)
 Get the wireless transmit power in dBm. More...
 
DLLEXPORT bool trace_get_wireless_antenna (void *linkptr, libtrace_linktype_t linktype, uint8_t *antenna)
 Get the wireless antenna. More...
 

Detailed Description

Trace file processing library header.

Author
Daniel Lawson
Perry Lorier
Shane Alcock
Richard Sanger
Version
$Id$

This library provides a per packet interface into a trace file, or a live captures. It supports ERF, DAG cards, PCAP, Linux and BSD native sockets, legacy ERF formats 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.

See libtrace_parallel.h for a description of the parallel API that allows programmers to spread packet processing across multiple threads.

Macro Definition Documentation

#define ARPHRD_80211_RADIOTAP   803

libc doesn't define this yet, so we have to do so ourselves

#define ASSERT_RET (   run,
  cond 
)    assert(run cond)

A version of assert that always runs the first argument even when not debugging, however only asserts the condition if debugging Intended for use mainly with pthread locks etc.

which have error returns but should never actually fail.

Referenced by store_first_packet(), trace_apply_filter(), trace_create(), trace_create_dead(), trace_destroy(), trace_destroy_dead(), trace_get_first_packet(), trace_join(), trace_ppause(), and trace_pstart().

#define DAG_DRIVER_V   ""

DAG driver version installed on the current system.

#define LIBTRACE_API_VERSION   ((4<<16)|(0<<8)|(5))

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.

Referenced by trace_config(), trace_construct_packet(), trace_get_capture_length(), and trace_get_wire_length().

#define LIBTRACE_STAT_FIELDS
Value:
X(accepted) \
X(filtered) \
X(received) \
X(dropped) \
X(captured) \
X(missing) \
X(errors)

An X Macro set for libtrace stat fields.

Referenced by trace_add_statistics(), trace_get_statistics(), trace_get_thread_statistics(), trace_print_statistics(), and trace_subtract_statistics().

#define LIBTRACE_SVN_REVISION   LIBTRACE_API_VERSION

This used to be replaced with the current SVN revision number when 'make dist' was invoked to create a distributable tarball.

We don't use SVN anymore and there probably isn't any need to know the exact revision number either these days.

#define TRACE_SLL_BROADCAST   1

Packet was addressed for a broadcast address.

#define TRACE_SLL_HOST   0

Packet was addressed for the local host.

#define TRACE_SLL_MULTICAST   2

Packet was addressed for a multicast address.

#define TRACE_SLL_OTHERHOST   3

Packet was addressed for another host but was captured by a promiscuous device.

#define TRACE_SLL_OUTGOING   4

Packet originated from the local host.

Referenced by promote_packet().

Typedef Documentation

802.11 header

802.1Q frame

Captured UNI cell.

Endace 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.

ATM User Network Interface (UNI) Cell.

Captured NNI cell.

Endace 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.

ATM Network Node/Network Interface (NNI) Cell.

Opaque structure holding callback functions for libtrace threads.

typedef struct trace_err_t libtrace_err_t

Libtrace error information.

802.3 frame

Structure returned by libtrace_event explaining what the current event is.

Opaque structure holding information about a bpf filter.

Libtrace local definition of GRE (Generalised Routing Protocol) header RFC2890.

Generic ICMPv6 header structure.

Generic ICMP header structure.

IPv6 header extension structure.

IPv6 fragmentation header.

typedef struct libtrace_ip6 libtrace_ip6_t

Generic IPv6 header structure.

Note
The flow label field also includes the Version and Traffic Class fields, because we haven't figured out a nice way to deal with fields crossing byte boundaries on both Big and Little Endian machines
typedef struct libtrace_ip libtrace_ip_t

Generic IP header structure.

Generic LLC/SNAP header structure.

OSPFv2 AS External LSA Body.

OSPFv2 Database Description packet.

OSPFv2 Hello Packet.

OSPFv2 Router Link structure.

OSPF Link State Request Packet.

OSPF Link State Update Packet.

LSA Header for OSPFv2.

OSPFv2 Network LSA Body.

Options Field present in some OSPFv2 packets.

OSPFv2 Router LSA.

OSPFv2 Summary LSA Body.

OSPF header.

Opaque structure holding information about an output trace.

The libtrace packet structure.

Applications shouldn't be meddling around in here

typedef struct libtrace_ppp libtrace_ppp_t

PPP header.

PPPoE header.

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.

A local definition of an SLL header.

Statistic counters are cumulative from the time the trace is started.

Trace pause will reset the counters, to zero. Always check {field}_valid is set before attempting to read the stored value.

Note
Always allocate this structure using trace_create_statistics(). This allows us to extend the structure in the future.
typedef struct libtrace_t libtrace_t

Opaque structure holding information about a trace.

typedef struct libtrace_tcp libtrace_tcp_t

Generic TCP header structure.

Opaque structure holding information about libtrace thread.

typedef struct libtrace_udp libtrace_udp_t

Generic UDP header structure.

Libtrace local definition of VXLAN Header (draft-mahalingam-dutt-dcops-vxlan)

Enumeration Type Documentation

anonymous enum

Enumeration of error codes.

Enumerator
TRACE_ERR_NOERROR 

No Error has occurred....

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.

TRACE_ERR_BAD_FILTER 

Failed to compile a BPF filter.

TRACE_ERR_RT_FAILURE 

RT communication breakdown.

TRACE_ERR_UNSUPPORTED_COMPRESS 

Compression format unsupported.

TRACE_ERR_WANDIO_FAILED 

Wandio has returned an error.

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.

RT protocol base format identifiers.

This is used to describe the capture format of the packet is being sent using the RT protocol.

Enumerator
TRACE_FORMAT_ERF 

ERF (DAG capture format)

TRACE_FORMAT_PCAP 

Live PCAP capture.

TRACE_FORMAT_PCAPFILE 

PCAP trace file.

TRACE_FORMAT_WAG 

WAG live capture (Obsolete)

TRACE_FORMAT_RT 

RT network protocol.

TRACE_FORMAT_LEGACY_ATM 

Legacy ERF for ATM capture.

TRACE_FORMAT_LEGACY_POS 

Legacy ERF for POS capture.

TRACE_FORMAT_LEGACY_ETH 

Legacy ERF for ETH capture.

TRACE_FORMAT_LINUX_NATIVE 

Linux native interface capture.

TRACE_FORMAT_DUCK 

DAG Clock information.

TRACE_FORMAT_BPF 

BSD native interface capture.

TRACE_FORMAT_TSH 

TSH trace format.

TRACE_FORMAT_ATMHDR 

Legacy ATM header capture.

TRACE_FORMAT_LEGACY_NZIX 

Legacy format used for NZIX traces.

TRACE_FORMAT_LINUX_RING 

Linux native interface capture PACKET_MMAP.

TRACE_FORMAT_RAWERF 

Special format for reading uncompressed ERF traces without checking for compression.

TRACE_FORMAT_DPDK 

The Intel Data Plane Development Kit format.

TRACE_FORMAT_PCAPNG 

PCAP-NG trace file.

TRACE_FORMAT_NDAG 

DAG multicast over a network.

TRACE_FORMAT_DPDK_NDAG 

DAG multicast over a network, received via DPDK.

TRACE_FORMAT_ETSILIVE 

ETSI LI over a network.

If the packet has allocated its own memory the buffer_control should be set to TRACE_CTRL_PACKET, so that the memory will be freed when the packet is destroyed.

If the packet has been zero-copied out of memory owned by something else, e.g. a DAG card, 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.
Enumerator
TRACE_CTRL_PACKET 

Buffer memory is owned by the packet.

TRACE_CTRL_EXTERNAL 

Buffer memory is owned by an external source.

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.

Enumerator
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.

TRACE_DIR_UNKNOWN 

No direction information available.

Enumeration of DLTs supported by libtrace.

Enumerator
TRACE_DLT_NULL 

pcap documents this as having the Address Family value in host byte order as the framing.

Ugly? Yes.

TRACE_DLT_RAW 

Ok, so OpenBSD has a different value for DLT_RAW as the rest of the planet, so detect this.

When reading to/from files we should be using TRACE_DLT_LINKTYPE_RAW instead. When talking about DLT's inside libtrace tho, we should be using /these/ DLT's.

TRACE_DLT_LINKTYPE_RAW 

See TRACE_DLT_RAW for explanations of pain.

TRACE_DLT_IEEE802_11_RADIO 

Radiotap.

Ethertypes supported by Libtrace.

Enumerator
TRACE_ETHERTYPE_LOOPBACK 

Ethernet Loopback.

TRACE_ETHERTYPE_IP 

IPv4.

TRACE_ETHERTYPE_ARP 

Address resolution protocol.

TRACE_ETHERTYPE_RARP 

Reverse ARP.

TRACE_ETHERTYPE_8021Q 

802.1q VLAN Extended Header

TRACE_ETHERTYPE_IPV6 

IPv6.

TRACE_ETHERTYPE_MPLS 

MPLS Unicast traffic.

TRACE_ETHERTYPE_MPLS_MC 

MPLS Multicast traffic.

TRACE_ETHERTYPE_PPP_DISC 

PPPoE Service Discovery.

TRACE_ETHERTYPE_PPP_SES 

PPPoE Session Messages.

Event types see libtrace_eventobj_t and trace_event.

Enumerator
TRACE_EVENT_IOWAIT 

Wait on the given file descriptor.

TRACE_EVENT_SLEEP 

Sleep for the given amount of time.

TRACE_EVENT_PACKET 

Packet has been read from input trace.

TRACE_EVENT_TERMINATE 

End of input trace.

IP Protocol values.

Enumerator
TRACE_IPPROTO_IP 

IP pseudo protocol number.

TRACE_IPPROTO_ICMP 

Internet Control Message protocol.

TRACE_IPPROTO_IGMP 

Internet Group Management Protocol.

TRACE_IPPROTO_IPIP 

IP encapsulated in IP.

TRACE_IPPROTO_TCP 

Transmission Control Protocol.

TRACE_IPPROTO_UDP 

User Datagram Protocol.

TRACE_IPPROTO_IPV6 

IPv6 over IPv4.

TRACE_IPPROTO_ROUTING 

IPv6 Routing header.

TRACE_IPPROTO_FRAGMENT 

IPv6 Fragmentation header.

TRACE_IPPROTO_RSVP 

Resource Reservation Protocol.

TRACE_IPPROTO_GRE 

General Routing Encapsulation.

TRACE_IPPROTO_ESP 

Encapsulated Security Payload [RFC2406].

TRACE_IPPROTO_AH 

Authentication Header [RFC2402].

TRACE_IPPROTO_ICMPV6 

ICMPv6.

TRACE_IPPROTO_NONE 

IPv6 no next header.

TRACE_IPPROTO_DSTOPTS 

IPv6 destination options.

TRACE_IPPROTO_OSPF 

Open Shortest Path First routing protocol.

TRACE_IPPROTO_PIM 

Protocol Independant Multicast.

TRACE_IPPROTO_SCTP 

Stream Control Transmission Protocol.

Enumeration of link layer types supported by libtrace.

Enumerator
TRACE_TYPE_CONTENT_INVALID 

Packet contents are not valid.

TRACE_TYPE_UNKNOWN 

Unable to determine link type.

TRACE_TYPE_HDLC_POS 

HDLC over POS.

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 PFlog.

TRACE_TYPE_POS 

Packet-over-SONET.

TRACE_TYPE_80211_PRISM 

802.11 Prism frames

TRACE_TYPE_AAL5 

ATM Adaptation Layer 5 frames.

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.

TRACE_TYPE_NONDATA 

Not a data packet.

TRACE_TYPE_OPENBSD_LOOP 

OpenBSD loopback.

TRACE_TYPE_ERF_META 

ERF Provenance metadata record.

TRACE_TYPE_ETSILI 

ETSI Lawful Intercept.

OSPF link state acknowledgement types.

Enumerator
TRACE_OSPF_LS_ROUTER 

OSPF Router LSA.

TRACE_OSPF_LS_NETWORK 

OSPF Network LSA.

TRACE_OSPF_LS_SUMMARY 

OSPF Summary LSA.

TRACE_OSPF_LS_ASBR_SUMMARY 

OSPF Summary LSA (ASBR)

TRACE_OSPF_LS_EXTERNAL 

OSPF AS External LSA.

OSPF message types.

Enumerator
TRACE_OSPF_HELLO 

OSPF Hello.

TRACE_OSPF_DATADESC 

OSPF Database Description.

TRACE_OSPF_LSREQ 

OSPF Link State Request.

TRACE_OSPF_LSUPDATE 

OSPF Link State Update.

TRACE_OSPF_LSACK 

OSPF Link State Acknowledgement.

Enumeration of Radiotap fields.

Enumerator
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 attenuation 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)

RT protocol packet types.

Enumerator
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_DUCK_5_0 

Dag 5.0 Duck.

TRACE_RT_PCAPNG_META 

Metadata for a PCAP NG input source.

TRACE_RT_DATA_SIMPLE 

Not actually used - all DATA types begin from this value.

TRACE_RT_DATA_ERF 

RT is encapsulating an ERF capture record.

TRACE_RT_DATA_WAG 

RT is encapsulating a WAG capture record.

TRACE_RT_DATA_LEGACY_ATM 

RT is encapsulating a Legacy ATM capture record.

TRACE_RT_DATA_LEGACY_POS 

RT is encapsulating a Legacy POS capture record.

TRACE_RT_DATA_LEGACY_ETH 

RT is encapsulating a Legacy ETH capture record.

TRACE_RT_DATA_LINUX_NATIVE 

RT is encapsulating a Linux native capture record.

TRACE_RT_DATA_TSH 

RT is encapsulating a BSD native capture record.

RT is encapsulating a TSH capture record

TRACE_RT_DATA_ATMHDR 

RT is encapsulating an ATM header capture record.

TRACE_RT_DATA_LEGACY_NZIX 

RT is encapsulating a Legacy NZIX capture record.

TRACE_RT_DATA_LINUX_RING 

RT is encapsulating a Linux native PACKET_MMAP capture record.

TRACE_RT_DATA_DPDK 

RT is encapsulating a Intel DPDK capture record.

TRACE_RT_DATA_DLT 

As PCAP does not store the linktype with the packet, we need to create a separate RT type for each supported DLT, starting from this value.

TRACE_RT_DLT_NULL 

RT is encapsulating a PCAP capture record with a NULL linktype.

TRACE_RT_DLT_EN10MB 

RT is encapsulating a PCAP capture record with an Ethernet linktype.

TRACE_RT_DLT_IEEE802_11 

RT is encapsulating a PCAP capture record with an 802.11 linktype.

TRACE_RT_DLT_LINUX_SLL 

RT is encapsulating a PCAP capture record with a Linux SLL linktype.

TRACE_RT_DLT_PFLOG 

RT is encapsulating a PCAP capture record with a PFlog linktype.

TRACE_RT_DLT_ATM_RFC1483 

RT is encapsulating a PCAP capture record with an AAL5 linktype.

TRACE_RT_DATA_DLT_END 

Unused value marking the end of the valid range for PCAP RT encapsulation.

TRACE_RT_DATA_BPF 

BPF does not store the linktype with the packet, so we need a separate RT type for each supported DLT.

This value represents the starting point

TRACE_RT_LAST 

Unused value marking the end of the valid range for all RT packet types.

An indication of which port is the "server" port for a given port pair.

Enumerator
USE_DEST 

Destination port is the server port.

USE_SOURCE 

Source port is the server port.

Valid compression types Note, this must be kept in sync with WANDIO_COMPRESS_* numbers in wandio.h.

Enumerator
TRACE_OPTION_COMPRESSTYPE_NONE 

No compression.

TRACE_OPTION_COMPRESSTYPE_ZLIB 

GZip Compression.

TRACE_OPTION_COMPRESSTYPE_BZ2 

BZip2 Compression.

TRACE_OPTION_COMPRESSTYPE_LZO 

LZO Compression.

TRACE_OPTION_COMPRESSTYPE_LZMA 

LZO Compression.

Valid configuration options for output traces.

Enumerator
TRACE_OPTION_OUTPUT_FILEFLAGS 

File flags to use when opening an output file, e.g.

O_APPEND

TRACE_OPTION_OUTPUT_COMPRESS 

Compression level: 0 = no compression, 1 = faster compression, 9 = better compression.

TRACE_OPTION_OUTPUT_COMPRESSTYPE 

Compression type, see trace_option_compresstype_t.

Valid configuration options for input traces.

Enumerator
TRACE_OPTION_SNAPLEN 

Maximum number of bytes to be captured for any given packet.

TRACE_OPTION_PROMISC 

If enabled, places a live capture interface into promiscuous mode.

TRACE_OPTION_FILTER 

Apply this filter to all packets read from this trace.

TRACE_OPTION_META_FREQ 

Defines the frequency of meta-data reporting, e.g.

DUCK packets

TRACE_OPTION_EVENT_REALTIME 

If enabled, the libtrace event API will ignore time gaps between packets when reading from a trace file.

TRACE_OPTION_HASHER 

The hasher function for a parallel libtrace.

It is recommended to access this option via trace_set_hasher().

TRACE_OPTION_REPLAY_SPEEDUP 

Speed up trace file replays (via trace_event()) by this factor.

Function Documentation

DLLEXPORT void trace_add_statistics ( const libtrace_stat_t a,
const libtrace_stat_t b,
libtrace_stat_t c 
)

Performs operation c=a+b accounting for valid fields.

c is allowed to be a or b.

Parameters
aThe first operand
bThe second operand
cThe result

References LIBTRACE_STAT_FIELDS, and libtrace_stat_t::magic.

DLLEXPORT int trace_apply_filter ( libtrace_filter_t filter,
const libtrace_packet_t packet 
)

Apply a BPF filter to a packet.

Parameters
filterThe filter to be applied
packetThe packet to be matched against the filter
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 a more graceful handling of this error in the future.

References ASSERT_RET, demote_packet(), libtrace_to_pcap_dlt(), libtrace_packet_t::trace, trace_copy_packet(), trace_destroy_packet(), TRACE_ERR_NO_CONVERSION, trace_get_link_type(), trace_get_packet_buffer(), trace_set_err(), TRACE_TYPE_ERF_META, and TRACE_TYPE_NONDATA.

Referenced by trace_read_packet().

DLLEXPORT uint16_t* trace_checksum_layer3 ( libtrace_packet_t packet,
uint16_t *  csum 
)

Calculates the expected IP checksum for a packet.

Parameters
packetThe libtrace packet to calculate the checksum for
[out]csumThe checksum that is calculated by this function. This may not be NULL.
Returns
A pointer to the original checksum field within the IP header. If the checksum field is not present in the packet, NULL is returned.
Note
The return value points to the checksum that exists within the current packet. The value in csum is the value that the checksum should be, given the current packet contents.
This function involves the use of a memcpy, so be careful about calling it excessively if performance is a concern for you.

New in libtrace 3.0.17

References libtrace_ip::ip_hl, libtrace_ip::ip_sum, TRACE_ETHERTYPE_IP, and trace_get_layer3().

DLLEXPORT uint16_t* trace_checksum_transport ( libtrace_packet_t packet,
uint16_t *  csum 
)

Calculates the expected checksum for the transport header in a packet.

Parameters
packetThe libtrace packet to calculate the checksum for
[out]csumThe checksum that is calculated by this function. This may not be NULL.
Returns
A pointer to the original checksum field within the transport header. If the checksum field is not present in the packet, NULL is returned.
Note
The return value points to the checksum that exists within the current packet. The value in csum is the value that the checksum should be, given the current packet contents.
This function involves the use of a memcpy, so be careful about calling it excessively if performance is a concern for you.
Because transport checksums are calculated across the entire payload, truncated packets will result in NULL being returned.

This function will determine the appropriate checksum for whatever transport layer header is present in the provided packet. At this stage, this only currently works for TCP, UDP and ICMP packets.

Be wary of TCP checksum offloading if you are examining the checksum of packets captured on the same host that generated them!

New in libtrace 3.0.17

References libtrace_tcp::check, libtrace_udp::check, libtrace_icmp::checksum, libtrace_tcp::doff, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_icmp(), trace_get_payload_from_tcp(), trace_get_payload_from_udp(), trace_get_payload_length(), trace_get_transport(), TRACE_IPPROTO_ICMP, TRACE_IPPROTO_TCP, and TRACE_IPPROTO_UDP.

DLLEXPORT void trace_clear_statistics ( libtrace_stat_t s)

Clear all fields of given statistic.

This api doesn't verify the magic field unlike other stat apis.

Parameters
sThe statistic structure to clear

References libtrace_stat_t::magic.

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

Sets an input config option.

Parameters
libtraceThe trace object to apply the option to
optionThe option to set
valueThe 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()

Note
Please consider using the newer trace_set_X() functions to access this function.

References libtrace_format_t::config_input, libtrace_t::filter, libtrace_t::format, LIBTRACE_PACKET_BUFSIZE, libtrace_t::replayspeedup, libtrace_t::snaplen, TRACE_ERR_BAD_STATE, TRACE_ERR_OPTION_UNAVAIL, TRACE_ERR_UNKNOWN_OPTION, trace_get_err(), trace_is_err(), TRACE_OPTION_EVENT_REALTIME, TRACE_OPTION_FILTER, TRACE_OPTION_HASHER, TRACE_OPTION_META_FREQ, TRACE_OPTION_PROMISC, TRACE_OPTION_REPLAY_SPEEDUP, TRACE_OPTION_SNAPLEN, trace_set_err(), and trace_set_hasher().

Referenced by trace_set_event_realtime(), trace_set_filter(), trace_set_meta_freq(), trace_set_promisc(), and trace_set_snaplen().

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

Sets an output config option.

Parameters
libtraceThe output trace object to apply the option to
optionThe option to set
valueThe 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

References libtrace_format_t::config_output, and libtrace_out_t::format.

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

Construct a libtrace packet from a buffer containing the packet payload.

Parameters
[in,out]packetLibtrace Packet object to update with the new data.
linktypeThe linktype of the packet data.
[in]dataThe packet data (including linklayer).
lenLength of packet data provided in the buffer.
Note
The constructed packet will be in the PCAP format.
To be useful, the provided buffer must start with the layer 2 header (or a metadata header, if desired).

References libtrace_packet_t::buf_control, libtrace_packet_t::buffer, libtrace_packet_t::header, LIBTRACE_PACKET_BUFSIZE, libtrace_to_pcap_linktype(), libtrace_packet_t::payload, pcap_linktype_to_rt(), libtrace_packet_t::trace, trace_clear_cache(), trace_create_dead(), TRACE_CTRL_PACKET, and libtrace_packet_t::type.

DLLEXPORT libtrace_packet_t* trace_copy_packet ( const libtrace_packet_t packet)

Copy a packet object.

Parameters
packetThe 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 zero-copied
packet from a device will be stored using memory owned by the device which may be a limited resource. Copying the packet will ensure that the packet is now stored in memory owned and managed by libtrace.

References libtrace_packet_t::buf_control, libtrace_packet_t::buffer, libtrace_packet_t::error, libtrace_packet_t::hash, libtrace_packet_t::header, libtrace_packet_t::order, libtrace_packet_t::payload, libtrace_t::startcount, libtrace_packet_t::trace, trace_clear_cache(), TRACE_CTRL_PACKET, trace_get_capture_length(), trace_get_framing_length(), libtrace_packet_t::type, and libtrace_packet_t::which_trace_start.

Referenced by libtrace_make_packet_safe(), store_first_packet(), and trace_apply_filter().

DLLEXPORT libtrace_t* trace_create ( const char *  uri)

Create an input trace from a URI.

Parameters
uriA valid libtrace URI to be opened
Returns
An opaque pointer to a libtrace_t

Some 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

If an error occurred when attempting to open the trace file, a trace is still returned so trace_is_err() should be called to find out if an error occurred. The trace is created in the configuration state, you must call trace_start before attempting to read packets from the trace.

References libtrace_t::accepted_packets, ASSERT_RET, libtrace_t::err, trace_err_t::err_num, libtrace_t::event, libtrace_t::filter, libtrace_t::filtered_packets, libtrace_t::format, libtrace_t::global_blob, libtrace_t::hasher, libtrace_format_t::init_input, libtrace_t::io, libtrace_t::last_packet, libtrace_t::libtrace_lock, libtrace_format_t::name, libtrace_format_t::next, libtrace_event_status_t::packet, libtrace_t::packet_freelist, libtrace_t::perpkt_cond, libtrace_t::perpkt_queue_full, libtrace_t::pread, trace_err_t::problem, libtrace_event_status_t::psize, libtrace_t::read_packet_lock, libtrace_t::replayspeedup, libtrace_t::sequence_number, libtrace_t::snaplen, libtrace_t::startcount, libtrace_t::started, libtrace_t::state, strncasecmp(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_NOERROR, TRACE_ERR_UNSUPPORTED, trace_parse_uri(), trace_set_err(), libtrace_t::uridata, and libtrace_event_status_t::waiting.

DLLEXPORT libtrace_t* trace_create_dead ( const char *  uri)

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

Parameters
uriA valid (but fake) URI indicating the format of the dummy trace that is to be created.
Returns
An opaque pointer to a (sparsely initialised) libtrace_t

Only the format portion of the uri parameter matters - the 'file' being opened does not have to exist.

Note
IMPORTANT: Do not attempt to call trace_read_packet or other such functions with the dummy trace. Its intended purpose is to provide access to the format functions where the original trace may no longer exist or is not the correct format, e.g. reading ERF packets from an RT input.

References libtrace_t::accepted_packets, ASSERT_RET, libtrace_t::err, trace_err_t::err_num, libtrace_t::event, libtrace_t::filter, libtrace_t::filtered_packets, libtrace_t::format, libtrace_t::format_data, libtrace_t::global_blob, libtrace_t::hasher, libtrace_t::io, libtrace_t::last_packet, libtrace_t::libtrace_lock, libtrace_format_t::name, libtrace_format_t::next, libtrace_event_status_t::packet, libtrace_t::packet_freelist, libtrace_t::perpkt_cond, libtrace_t::perpkt_queue_full, libtrace_t::pread, libtrace_event_status_t::psize, libtrace_t::read_packet_lock, libtrace_t::sequence_number, libtrace_t::snaplen, libtrace_t::started, libtrace_t::state, strncasecmp(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_NOERROR, trace_set_err(), and libtrace_t::uridata.

Referenced by demote_packet(), and trace_construct_packet().

DLLEXPORT SIMPLE_FUNCTION libtrace_filter_t* trace_create_filter ( const char *  filterstring)

Creates a BPF filter.

Parameters
filterstringThe filter string describing the BPF filter to create
Returns
An opaque 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 
)

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

Parameters
bf_insnsA pointer to the start of the byte-code
bf_lenThe number of BPF instructions
Returns
An opaque pointer to a libtrace_filter_t object
Note
The supplied byte-code is not checked for correctness. Instead, incorrect byte-code will generate an error once the filter is actually used.
Author
Scott Raynel

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

Parameters
bf_insnsA pointer to the start of the byte-code
bf_lenThe 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.

Parameters
uriThe uri string describing the output format and destination
Returns
An opaque pointer to a libtrace_output_t

Valid URIs include:

  • erf:/path/to/erf/file
  • pcap:/path/to/pcap/file

If an error occurred when attempting to open the output trace, a trace is still returned but trace_errno will be set. Use trace_is_err_out() and trace_perror_output() to get more information.

References libtrace_out_t::err, trace_err_t::err_num, libtrace_out_t::format, libtrace_format_t::init_output, libtrace_format_t::name, libtrace_format_t::next, trace_err_t::problem, libtrace_out_t::started, strncasecmp(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_NOERROR, TRACE_ERR_UNSUPPORTED, trace_parse_uri(), trace_set_err_out(), and libtrace_out_t::uridata.

DLLEXPORT libtrace_packet_t* trace_create_packet ( void  )

Create a new packet object.

Returns
A pointer to an initialised libtrace_packet_t object, or NULL if libtrace is unable to allocate space for a new packet.

References libtrace_packet_t::buf_control, libtrace_packet_t::ref_lock, trace_clear_cache(), TRACE_CTRL_PACKET, and libtrace_packet_t::which_trace_start.

Referenced by trace_event_trace(), and trace_pstart().

DLLEXPORT libtrace_stat_t* trace_create_statistics ( void  )

Creates and returns a zeroed libtrace_stat_t structure.

This allows us to add extra fields increasing the size of the structure without breaking existing libtrace applications.

This structure should be free'd using free().

Returns
A valid pointer to a libtrace_stat_t struct otherwise NULL if memory was not available.

References libtrace_stat_t::magic.

Referenced by trace_get_statistics(), and trace_ppause().

DLLEXPORT void trace_destroy_dead ( libtrace_t trace)

Close a dummy trace file, freeing up any resources it may have been using.

Parameters
traceThe dummy trace to be destroyed

References ASSERT_RET, libtrace_t::format_data, libtrace_t::libtrace_lock, libtrace_t::perpkt_cond, and libtrace_t::read_packet_lock.

DLLEXPORT void trace_destroy_filter ( libtrace_filter_t filter)

Destroy a BPF filter.

Parameters
filterThe filter to be destroyed

Deallocates all the resources associated with a BPF filter.

DLLEXPORT void trace_destroy_output ( libtrace_out_t trace)

Close an output trace, freeing up any resources it may have been using.

Parameters
traceThe output trace to be destroyed

References libtrace_format_t::fin_output, libtrace_out_t::format, and libtrace_out_t::uridata.

DLLEXPORT uint8_t* trace_ether_aton ( const char *  buf,
uint8_t *  addr 
)

Convert a string to an ethernet address.

Parameters
bufA string containing an Ethernet address in hex format delimited with :'s.
addrBuffer to store the binary representation, or NULL to indicate that static storage should be used.
Returns
addr, or if addr is NULL then a statically allocated buffer.

This function is similar to the GNU ether_aton_r function, with a few minor differences. If NULL is passed as addr, then the function will use an internal static buffer. If NULL isn't passed then the function will use that buffer instead.

The address returned by this function will be in network byte order.

Note
the type of addr isn't struct ether_addr as it is with ether_aton_r, however it is bit compatible so that a cast will work.
DLLEXPORT char* trace_ether_ntoa ( const uint8_t *  addr,
char *  buf 
)

Converts an ethernet address to a printable string.

Parameters
addrEthernet address in network byte order
bufBuffer to store the ascii representation, or NULL to indicate that static storage should be used.
Returns
buf, or if buf is NULL then a statically allocated buffer.

This function is similar to the GNU ether_ntoa_r function, with a few minor differences. If NULL is passed as buf, then the function will use an internal static buffer. If NULL isn't passed then the function will use that buffer instead.

The address pointers returned by trace_get_source_mac() and trace_get_destination_mac() can be passed directly into this function.

Note
The type of addr isn't struct ether_addr as it is with ether_ntoa_r, however it is bit compatible so that a cast will work.

References snprintf().

DLLEXPORT libtrace_eventobj_t trace_event ( libtrace_t trace,
libtrace_packet_t packet 
)

Processes the next libtrace event from an input trace.

Parameters
traceThe libtrace opaque pointer for the input trace
packetThe libtrace_packet opaque pointer to use for reading packets
Returns
A libtrace_event struct containing the event type and details of the event.

Type can be: TRACE_EVENT_IOWAIT Waiting on I/O on a file descriptor TRACE_EVENT_SLEEP Wait a specified amount of time for the next event TRACE_EVENT_PACKET Packet was read from the trace TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)

References libtrace_t::format, libtrace_packet_t::trace, libtrace_format_t::trace_event, TRACE_EVENT_IOWAIT, and trace_fin_packet().

Referenced by register_format().

DLLEXPORT int trace_flush_output ( libtrace_out_t libtrace)

Flush an output trace, forcing any buffered packets to be written.

Parameters
libtraceThe output trace to be flushed

References libtrace_format_t::flush_output, and libtrace_out_t::format.

DLLEXPORT DEPRECATED uint64_t trace_get_accepted_packets ( libtrace_t trace)

Returns the number of packets that have been read from the input trace using trace_read_packet().

Parameters
traceThe input trace to examine
Returns
The number of packets that have been read by the libtrace user.

If the number is not known, this function will return UINT64_MAX

Deprecated:
This function is deprecated: Use trace_get_statistics(), this allows all statistic counters to be read in an atomic manner.

References libtrace_t::accepted_packets.

DLLEXPORT SIMPLE_FUNCTION size_t trace_get_capture_length ( const libtrace_packet_t packet)

Get the current size of the packet (in bytes), taking into account any truncation or snapping that may have previously been performed.

Parameters
packetThe packet to determine the capture length for
Returns
The size of the packet read from the input trace, i.e. what is actually available to libtrace at the moment.
Note
Most traces are header captures, so this value may not be the same as the size of the packet when it was captured. Use trace_get_wire_length() to get the original size of the packet.
This can (and often is) different for different packets in a trace!
This is sometimes called the "snaplen".
The return size refers to the network-level payload of the packet and does not include any capture framing headers. For example, an Ethernet packet with an empty TCP packet will return sizeof(ethernet_header) + sizeof(ip_header) + sizeof(tcp_header), but not the capture format (pcap/erf/etc) header.

References libtrace_packet_t::capture_length, libtrace_t::format, libtrace_format_t::get_capture_length, LIBTRACE_PACKET_BUFSIZE, libtrace_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.

Referenced by demote_packet(), promote_packet(), trace_copy_packet(), trace_get_ip(), trace_get_ip6(), trace_get_packet_buffer(), and trace_strip_packet().

DLLEXPORT SIMPLE_FUNCTION struct sockaddr* trace_get_destination_address ( const libtrace_packet_t packet,
struct sockaddr *  addr 
)

Get the destination IP address for a given packet.

Parameters
packetThe packet to extract the destination IP address from
addrA pointer to a sockaddr structure to store the address in. If NULL, static storage is used instead.
Returns
A pointer to a sockaddr holding a v4 or v6 IP address or on some platforms a sockaddr holding a MAC address. Returns NULL if no destination IP address was available.
Note
The best way to use this function is to pass in a pointer to the struct sockaddr_storage for the addr parameter. This will avoid problems with trying to shoe-horn an IPv6 address into a sockaddr that only supports IPv4.

References ports_t::dst, libtrace_ip::ip_dst, libtrace_ip6::ip_dst, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_ip(), and trace_get_payload_from_ip6().

Referenced by trace_get_destination_address_string().

DLLEXPORT SIMPLE_FUNCTION char* trace_get_destination_address_string ( const libtrace_packet_t packet,
char *  space,
int  spacelen 
)

Get the destination IP address for a packet and convert it into a string.

Parameters
packetThe packet to extract the destination IP address from
spaceA pointer to a character buffer to store the address in. If NULL, static storage is used instead.
spacelenThe size of the buffer passed in via 'space'. Set this to zero if you are going to pass in a NULL buffer.
Returns
A pointer to a character buffer containing the string representation of the destination IP address. For packets where there is no suitable IP address, the destination MAC will be returned instead. Returns NULL if no valid address is available.
Note
Be wary of the possibility of the address being an IPv6 address - make sure your buffer is large enough!

New in libtrace 3.0.17.

References trace_get_destination_address().

DLLEXPORT SIMPLE_FUNCTION uint8_t* trace_get_destination_mac ( libtrace_packet_t packet)

Gets the destination MAC address for a given packet.

Parameters
packetThe packet to extract the destination MAC address from
Returns
A pointer to the destination MAC address field in the layer 2 header, (or NULL if there is no destination MAC address or layer 2 header available)
Note
This is a zero-copy function, so the memory that the returned pointer points to is part of the packet itself.

References libtrace_ether::ether_dhost, libtrace_80211_t::mac1, trace_get_layer2(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_destination_port ( const libtrace_packet_t packet)

Gets the destination port for a given packet.

Parameters
packetThe packet to get the destination port from
Returns
The destination port in HOST byte order or 0 if no suitable port number can be extracted from the packet.

This function will return 0 if the transport protocol is known not to use port numbers, e.g. ICMP. 0 is also returned if no transport header is present in the packet or the transport header has been truncated such that the port fields are not readable.

Note
If the transport protocol is not known by libtrace, the third and fourth bytes of the transport header will be treated as the destination port field.

References ports_t::dst, trace_get_fragment_offset(), trace_get_transport(), TRACE_IPPROTO_ICMP, and TRACE_IPPROTO_ICMPV6.

DLLEXPORT SIMPLE_FUNCTION libtrace_direction_t trace_get_direction ( const libtrace_packet_t packet)

Get the direction flag for a packet, if it has one.

Parameters
packetThe packet to get the direction for
Returns
A value representing the direction flag, or -1 if this is not supported by the capture format.

The direction is defined as 0 for packets originating locally (ie, outbound) and 1 for packets originating remotely (ie, inbound). Other values are possible, which might be overloaded to mean special things for certain traces, e.g. in the Waikato traces, 2 is used to represent an "Unknown" direction.

For DAG/ERF traces, the direction is extracted from the "Interface" bits in the ERF header, which can range from 0 - 3.

References libtrace_t::format, libtrace_format_t::get_direction, libtrace_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.

DLLEXPORT DEPRECATED uint64_t trace_get_dropped_packets ( libtrace_t trace)

Returns the number of packets that have been dropped on an input trace due to lack of buffer space on the capturing device.

Parameters
traceThe input trace to examine
Returns
The number of packets captured, but dropped due to buffer overruns

If the number is not known, this function will return UINT64_MAX

Deprecated:
This function is deprecated: Use trace_get_statistics(), this allows all statistic counters to be read in an atomic manner.

References libtrace_stat_t::dropped, libtrace_t::format, libtrace_format_t::get_dropped_packets, libtrace_format_t::get_statistics, libtrace_stat_t::magic, trace_get_statistics(), and UINT64_MAX.

DLLEXPORT SIMPLE_FUNCTION uint64_t trace_get_erf_timestamp ( const libtrace_packet_t packet)

Get the packet timestamp in the DAG time format.

Parameters
packetThe packet to extract the timestamp from
Returns
a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds past 1970-01-01, the lower 32bits are partial seconds)

References libtrace_t::format, libtrace_format_t::get_erf_timestamp, libtrace_format_t::get_seconds, libtrace_format_t::get_timespec, libtrace_format_t::get_timeval, libtrace_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.

DLLEXPORT libtrace_err_t trace_get_err ( libtrace_t trace)

Check (and clear) the current error state of an input trace.

Parameters
traceThe input trace to check the error state on
Returns
The current error status and message

This reads and returns the current error state and sets the current error to "no error".

References libtrace_t::err, trace_err_t::err_num, and trace_err_t::problem.

Referenced by trace_config().

DLLEXPORT void DLLEXPORT libtrace_err_t trace_get_err_output ( libtrace_out_t trace)

Checks (and clears) the current error state for an output trace.

Parameters
traceThe output trace to check the error state on
Returns
The current error status and message

This reads and returns the current error state and sets the current error to "no error".

References libtrace_out_t::err, trace_err_t::err_num, trace_err_t::problem, and TRACE_ERR_NOERROR.

DLLEXPORT DEPRECATED uint64_t trace_get_filtered_packets ( libtrace_t trace)

Returns the number of packets that were captured, but discarded for not matching a provided filter.

Parameters
traceThe input trace to examine
Returns
The number of packets that were successfully captured, but filtered

If the number is not known, this function will return UINT64_MAX

Deprecated:
This function is deprecated: Use trace_get_statistics(), this allows all statistic counters to be read in an atomic manner.

References libtrace_stat_t::filtered, libtrace_t::filtered_packets, libtrace_t::format, libtrace_format_t::get_filtered_packets, libtrace_format_t::get_statistics, libtrace_stat_t::magic, trace_get_statistics(), and UINT64_MAX.

DLLEXPORT SIMPLE_FUNCTION unsigned char* trace_get_first_ospf_link_from_router_lsa_v2 ( libtrace_ospf_router_lsa_v2_t lsa,
uint32_t *  remaining 
)

Get a pointer to the start of the first link contained within a Router LSA.

Parameters
lsaPointer to the Router LSA
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the first link in the packet.

This function simply skips past the Router LSA header to provide a suitable pointer to pass into trace_get_next_ospf_link_v2.

If the OSPF packet is truncated, then NULL will be returned.

'remaining' MUST be set to the amount of bytes remaining in the captured packet starting from the beginning of the Router LSA (not including the LSA header) header. It will be updated to contain the number of bytes remaining from the start of the first Link.

Note
This function only works for OSPF version 2 packets.
trace_get_next_ospf_link_v2() should be subsequently used to process the links
DLLEXPORT SIMPLE_FUNCTION unsigned char* trace_get_first_ospf_lsa_from_db_desc_v2 ( libtrace_ospf_db_desc_v2_t db_desc,
uint32_t *  remaining 
)

Get a pointer to the start of the first LSA contained within an Database Description packet.

Parameters
db_descPointer to the Database Description header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the first LSA in the packet.

This function simply skips past the Database Description header to provide a suitable pointer to pass into trace_get_next_ospf_lsa_header_v2.

If the OSPF packet is truncated, then NULL will be returned.

'remaining' MUST be set to the amount of bytes remaining in the captured packet starting from the beginning of the Database Description header. It will be updated to contain the number of bytes remaining from the start of the first LSA.

Note
This function only works for OSPF version 2 packets.
trace_get_next_ospf_lsa_header_v2() should be subsequently used to process the LSA headers
DLLEXPORT SIMPLE_FUNCTION unsigned char* trace_get_first_ospf_lsa_from_update_v2 ( libtrace_ospf_ls_update_t ls_update,
uint32_t *  remaining 
)

Get a pointer to the start of the first LSA contained within an LS Update packet.

Parameters
ls_updatePointer to the LS Update header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the first LSA in the packet.

This function simply skips past the LS Update header to provide a suitable pointer to pass into trace_get_next_ospf_lsa_v2.

If the OSPF packet is truncated, then NULL will be returned.

'remaining' MUST be set to the amount of bytes remaining in the captured packet starting from the beginning of the LS Update header. It will be updated to contain the number of bytes remaining from the start of the first LSA.

Note
This function only works for OSPF version 2 packets.
trace_get_next_ospf_lsa_v2() should be subsequently used to process the LSAs
DLLEXPORT enum base_format_t trace_get_format ( struct libtrace_packet_t packet)

Gets the capture format for a given packet.

Parameters
packetThe packet to get the capture format for.
Returns
The capture format of the packet
Note
Due to ability to convert packets between formats relatively easily in Libtrace, the format of the packet right now may not be the format that the packet was originally captured with.

References libtrace_t::format, libtrace_packet_t::trace, and libtrace_format_t::type.

DLLEXPORT uint16_t trace_get_fragment_offset ( const libtrace_packet_t packet,
uint8_t *  more 
)

Calculates the fragment offset in bytes for an IP packet.

Parameters
packetThe libtrace packet to calculate the offset for
[out]moreA boolean flag to indicate whether there are more fragments after the current packet.
Returns
The fragment offset for the packet in bytes. If the packet is not an IP packet or the fragment offset is not present in packet, the return value will be 0.
Note
The value returned is in bytes, not 8-octet units as it is stored in the fragment offset field in the headers. In other words, libtrace automatically does the multiplication for you.

The value passed in for 'more' does not matter; it will be overwritten with the value of the More Fragments flag from the IP header.

New in libtrace 3.0.20

References libtrace_ip6_frag::frag_off, libtrace_ip::ip_off, libtrace_ip6::nxt, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), TRACE_IPPROTO_AH, TRACE_IPPROTO_DSTOPTS, TRACE_IPPROTO_FRAGMENT, and TRACE_IPPROTO_ROUTING.

Referenced by trace_get_destination_port(), and trace_get_source_port().

DLLEXPORT SIMPLE_FUNCTION size_t trace_get_framing_length ( const libtrace_packet_t packet)

Get the length of the capture framing headers (in bytes).

Parameters
packetThe packet to determine the framing length for
Returns
The size of the capture format header encapsulating the packet.
Note
This length corresponds to the difference between the amount of memory required to store a captured packet and the capture length reported by trace_capture_length()

References libtrace_t::format, libtrace_packet_t::framing_length, libtrace_format_t::get_framing_length, libtrace_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.

Referenced by promote_packet(), and trace_copy_packet().

DLLEXPORT SIMPLE_FUNCTION libtrace_icmp_t* trace_get_icmp ( libtrace_packet_t packet)

Get a pointer to the ICMP header (if present)

Parameters
packetThe packet to get the ICMP header from
Returns
A pointer to the ICMP header, or NULL if there is not a complete ICMP header present in the packet.

This is a short-cut function enabling quick and easy access to the ICMP header if that is all you care about. However, we recommend the use of the more generic trace_get_transport() function instead.

Note
Unlike trace_get_transport(), this function will return NULL if the ICMP header is incomplete or truncated.

References trace_get_transport(), and TRACE_IPPROTO_ICMP.

DLLEXPORT SIMPLE_FUNCTION libtrace_icmp6_t* trace_get_icmp6 ( libtrace_packet_t packet)

Get a pointer to the ICMPv6 header (if present)

Parameters
packetThe packet to get the ICMPv6 header from
Returns
A pointer to the ICMPv6 header, or NULL if there is not a complete ICMP header present in the packet.

This is a short-cut function enabling quick and easy access to the ICMPv6 header if that is all you care about. However, we recommend the use of the more generic trace_get_transport() function instead.

Note
Unlike trace_get_transport(), this function will return NULL if the ICMPv6 header is incomplete or truncated.

References trace_get_transport(), and TRACE_IPPROTO_ICMPV6.

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 following an IPv4 header (if present)

Parameters
ipThe IP header to find the subsequent ICMP header for
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the ICMP header, or NULL if no UDP header is present in the packet.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the IP header (including the IP header itself). remaining will be updated to contain the number of bytes remaining after the IP header has been skipped.

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

Note
This function is rather redundant now that the layer 3 header is cached. There should be no performance advantage for the user to call this function over just calling trace_get_transport().
The last parameter has changed from libtrace2

References libtrace_ip::ip_p, trace_get_payload_from_ip(), and TRACE_IPPROTO_ICMP.

DLLEXPORT SIMPLE_FUNCTION libtrace_ip_t* trace_get_ip ( libtrace_packet_t packet)

Get a pointer to the IPv4 header (if any) for a given packet.

Parameters
packetThe packet to get the IPv4 header for
Returns
A pointer to the IPv4 header, or NULL if there is no IPv4 header

If a partial IP header is present, i.e. the packet has been truncated before the end of the IP header, this function will return NULL.

You should consider using trace_get_layer3 instead of this function.

References TRACE_ETHERTYPE_IP, trace_get_capture_length(), and trace_get_layer3().

DLLEXPORT SIMPLE_FUNCTION libtrace_ip6_t* trace_get_ip6 ( libtrace_packet_t packet)

get a pointer to the IPv6 header (if any)

Parameters
packetThe packet to get the IPv6 header for
Returns
A pointer to the IPv6 header, or NULL if there is no IPv6 header

If a partial IPv6 header is present, i.e. the packet has been truncated before the end of the IP header, this function will return NULL.

You should consider using trace_get_layer3 instead of this function.

References TRACE_ETHERTYPE_IPV6, trace_get_capture_length(), and trace_get_layer3().

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.

Generally this is the first byte of the packet as it was seen on the wire.

This function takes a libtrace packet and skips over any metadata headers if present (such as Linux SLL or Radiotap) and returns a pointer to the first byte of the packet that was actually received by the network interface.

Parameters
packetThe libtrace packet to find the layer 2 header for
[out]linktypeThe linktype of the returned layer 2 header
[out]remainingThe number of bytes left in the packet after the returned pointer.
Returns
A pointer to the first byte of the packet as it was seen on the wire. If no layer 2 header is present, this function will return NULL.

remaining may be NULL, otherwise it will be filled in by the function.

References libtrace_packet_t::l2_header, libtrace_packet_t::l2_remaining, libtrace_packet_t::link_type, trace_get_packet_buffer(), trace_get_payload_from_meta(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_destination_mac(), trace_get_layer3(), trace_get_source_mac(), and trace_strip_packet().

DLLEXPORT void* trace_get_layer3 ( const libtrace_packet_t packet,
uint16_t *  ethertype,
uint32_t *  remaining 
)

Get a pointer to the layer 3 (e.g.

IP) header.

Parameters
packetThe libtrace packet to find the layer 3 header for
[out]ethertypeThe ethertype of the layer 3 header
[out]remainingThe amount of captured data remaining in the packet starting from the returned pointer, i.e. including the layer 3 header.
Returns
A pointer to the layer 3 header. If no layer 3 header is present in the packet, NULL is returned. If the layer 3 header is truncated, a valid pointer will still be returned so be sure to check the value of remaining before attempting to process the returned header.

remaining may be NULL, otherwise it will be set to the number of captured bytes after the pointer returned.

References libtrace_packet_t::l2_header, libtrace_packet_t::l2_remaining, libtrace_packet_t::l3_ethertype, libtrace_packet_t::l3_header, libtrace_packet_t::l3_remaining, libtrace_packet_t::link_type, TRACE_ETHERTYPE_8021Q, TRACE_ETHERTYPE_MPLS, TRACE_ETHERTYPE_PPP_SES, trace_get_layer2(), trace_get_payload_from_ethernet(), trace_get_payload_from_layer2(), trace_get_payload_from_mpls(), trace_get_payload_from_pppoe(), and trace_get_payload_from_vlan().

Referenced by promote_packet(), trace_checksum_layer3(), trace_checksum_transport(), trace_get_destination_address(), trace_get_fragment_offset(), trace_get_ip(), trace_get_ip6(), trace_get_payload_length(), trace_get_source_address(), and trace_get_transport().

DLLEXPORT SIMPLE_FUNCTION DEPRECATED void* trace_get_link ( const libtrace_packet_t packet)

Get a pointer to the link layer for a given packet.

Parameters
packetThe packet to get the link layer for
Returns
A pointer to the link layer, or NULL if there is no link layer
Deprecated:
This function is deprecated: Use trace_get_packet_buffer() or one of the trace_get_layer*() functions instead.
Note
You should call trace_get_link_type to find out what type of link layer has been returned to you.

References libtrace_packet_t::payload.

DLLEXPORT SIMPLE_FUNCTION libtrace_linktype_t trace_get_link_type ( const libtrace_packet_t packet)

Gets the link layer type for a packet.

Parameters
packetThe packet to extract the link layer type for
Returns
A libtrace_linktype_t describing the link layer protocol being used by this packet.

References libtrace_t::format, libtrace_format_t::get_link_type, libtrace_packet_t::link_type, libtrace_t::startcount, libtrace_packet_t::trace, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_UNKNOWN, and libtrace_packet_t::which_trace_start.

Referenced by demote_packet(), trace_apply_filter(), and trace_get_packet_buffer().

DLLEXPORT int trace_get_next_option ( unsigned char **  ptr,
int *  len,
unsigned char *  type,
unsigned char *  optlen,
unsigned char **  data 
)

Parses an IP or TCP option.

Parameters
[in,out]ptrThe pointer to the current option
[in,out]lenThe total length of all the remaining options
[out]typeThe type of the option
[out]optlenThe length of the option
[out]dataThe data of the option
Returns
bool true if there is another option (and the fields are filled in) or false if this was the last option.

This updates ptr to point to the next option after this one, and updates len to be the number of bytes remaining in the options area. Type is updated to be the code of this option, and data points to the data of this option, with optlen saying how many bytes there are.

Note
Beware of fragmented packets.
DLLEXPORT SIMPLE_FUNCTION int trace_get_next_ospf_link_v2 ( unsigned char **  current,
libtrace_ospf_link_v2_t **  link,
uint32_t *  remaining,
uint32_t *  link_len 
)

Parses an OSPF Router LSA Link and finds the next Link (if there is one)

Parameters
[in,out]currentPointer to the next Link (updated by this function)
[out]linkSet to point to the Link located at the original value of current
[in,out]remainingUpdated with the number of captured bytes remaining
[out]link_lenSet to the size of the Link pointed to by 'link'
Returns
0 if there are no more links after the current one, 1 otherwise.

When called, 'current' MUST point to an OSPF Router LSA link. Ideally, this would come from either a call to trace_get_first_ospf_link_from_router_lsa_v2() or a previous call of this function.

'link' will be set to the value of 'current', so that the caller may then do any processing they wish on that particular link. 'current' is advanced to point to the next link and 'link_len' is updated to report the size of the original link.

'remaining' MUST be set to the amount of bytes remaining in the captured packet starting from the beginning of the Link pointed to by 'current'. It will be updated to contain the number of bytes remaining from the start of the next link.

If this function returns 0 but 'link' is NOT NULL, that link is still valid but there are no more links after this one. If this function returns 0 AND link is NULL, the link is obviously not suitable for processing.

Note
This function only works for OSPF version 2 packets.
DLLEXPORT SIMPLE_FUNCTION int trace_get_next_ospf_lsa_header_v2 ( unsigned char **  current,
libtrace_ospf_lsa_v2_t **  lsa_hdr,
uint32_t *  remaining,
uint8_t *  lsa_type,
uint16_t *  lsa_length 
)

Parses an OSPF LSA header and finds the next LSA (if there is one)

Parameters
[in,out]currentPointer to the next LSA (updated by this function)
[out]lsa_hdrSet to point to the header of the LSA located at the original value of current
[in,out]remainingUpdated with the number of captured bytes remaining
[out]lsa_lengthSet to the size of the LSA located at the original value of current
Returns
1 if there are more LSAs after the current one, 0 if there are no more LSAs to come, and -1 if the current LSA is incomplete, truncated or invalid.

When called, 'current' MUST point to an OSPF LSA. Ideally, this would come from either a call to trace_get_first_ospf_lsa_from_db_desc_v2() or a previous call of this function.

This function should only be used to access LSA headers, i.e. LSAs that have a header only. In OSPFv2, the LSAs contained within LSA Ack and Database Description packets meet this requirement. trace_get_next_ospf_lsa_v2 should be used to read full LSAs, e.g. those present in LS Updates.

'lsa_hdr' will be set to the value of 'current', so that the caller may then do any processing they wish on that particular LSA header. 'current' is advanced to point to the next LSA header. 'lsa_length' is updated to contain the size of the parsed LSA header.

'remaining' MUST be set to the amount of bytes remaining in the captured packet starting from the beginning of the LSA pointed to by 'current'. It will be updated to contain the number of bytes remaining from the start of the next LSA.

If this function returns 0 but 'lsa_hdr' is NOT NULL, that LSA is still valid but there are no more LSAs after this one. If this function returns 0 AND 'lsa_hdr' is NULL, the LSA is obviously not suitable for processing.

Note
This function only works for OSPF version 2 packets.

References TRACE_OSPF_LS_ASBR_SUMMARY, TRACE_OSPF_LS_EXTERNAL, TRACE_OSPF_LS_NETWORK, TRACE_OSPF_LS_ROUTER, and TRACE_OSPF_LS_SUMMARY.

DLLEXPORT SIMPLE_FUNCTION int trace_get_next_ospf_lsa_v2 ( unsigned char **  current,
libtrace_ospf_lsa_v2_t **  lsa_hdr,
unsigned char **  lsa_body,
uint32_t *  remaining,
uint8_t *  lsa_type,
uint16_t *  lsa_length 
)

Parses an OSPF LSA and finds the next LSA (if there is one)

Parameters
[in,out]currentPointer to the next LSA (updated by this function)
[out]lsa_hdrSet to point to the header of the LSA located at the original value of current
[out]lsa_bodySet to point to the body of the LSA located at the original value of current
[in,out]remainingUpdated with the number of captured bytes remaining
[out]lsa_typeSet to the type of the LSA located at the original value of current
[out]lsa_lengthSet to the size of the LSA located at the original value of current
Returns
1 if there are more LSAs after the current one, 0 if there are no more LSAs to come, and -1 if the current LSA is incomplete, truncated or invalid.

When called, 'current' MUST point to an OSPF LSA. Ideally, this would come from either a call to trace_get_first_ospf_lsa_from_update_v2() or a previous call of this function.

This function should only be used to access COMPLETE LSAs, i.e. LSAs that have both a header and a body. In OSPFv2, only the LSAs contained within LSA Update packets meet this requirement. trace_get_next_ospf_lsa_header_v2 should be used to read header-only LSAs, e.g. those present in LS Acks.

'lsa_hdr' will be set to the value of 'current', so that the caller may then do any processing they wish on that particular LSA. 'lsa_body' will be set to point to the first byte after the LSA header. 'current' is advanced to point to the next LSA. 'lsa_length' is updated to contain the size of the parsed LSA, while 'lsa_type' is set to indicate the LSA type.

'remaining' MUST be set to the amount of bytes remaining in the captured packet starting from the beginning of the LSA pointed to by 'current'. It will be updated to contain the number of bytes remaining from the start of the next LSA.

If this function returns 0 but 'lsa_hdr' is NOT NULL, that LSA is still valid but there are no more LSAs after this one. If this function returns 0 AND 'lsa_hdr' is NULL, the LSA is obviously not suitable for processing.

It is also recommended to check the value of 'lsa_body' before de-referencing it. 'lsa_body' will be set to NULL if there is only an LSA header present.

Note
This function only works for OSPF version 2 packets.

References libtrace_ospf_lsa_v2_t::lsa_type, TRACE_OSPF_LS_ASBR_SUMMARY, TRACE_OSPF_LS_EXTERNAL, TRACE_OSPF_LS_NETWORK, TRACE_OSPF_LS_ROUTER, and TRACE_OSPF_LS_SUMMARY.

DLLEXPORT SIMPLE_FUNCTION void* trace_get_ospf_contents_v2 ( libtrace_ospf_v2_t header,
uint8_t *  ospf_type,
uint32_t *  remaining 
)

Get a pointer to the contents of the OSPF packet after the OSPF header.

Parameters
headerThe OSPF header to get the OSPF contents from
[out]ospf_typeThe OSPF packet type
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the first byte after the OSPF header.

This function returns a void pointer that can be cast appropriately based on the ospf_type. For example, if the ospf_type is TRACE_OSPF_HELLO then the return pointer should be cast as a libtrace_ospf_hello_v2_t structure.

If the OSPF header is truncated, then NULL will be returned. If the OSPF contents are missing or truncated, the pointer to the start of the content will still be returned so be careful to check the value of remaining.

'remaining' MUST be set to the amount of bytes remaining in the captured packet starting from the beginning of the OSPF header. It will be updated to contain the number of bytes remaining from the start of the OSPF contents.

Note
This function only works for OSPF version 2 packets.
Use trace_get_first_ospf_lsa_v2_from_X() and trace_get_next_ospf_lsa_v2() to read the LSAs from Link State Update packets.
Use trace_get_first_ospf_lsa_v2_from_X() and trace_get_next_ospf_lsa_header_v2() to read the LSA headers from Link State Ack packets.

References libtrace_ospf_v2_t::type.

DLLEXPORT SIMPLE_FUNCTION void* trace_get_ospf_header ( libtrace_packet_t packet,
uint8_t *  version,
uint32_t *  remaining 
)

Get a pointer to the OSPF header (if present)

Parameters
packetThe packet to get the OSPF header from
[out]versionThe OSPF version number
[out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the start of the OSPF header or NULL if there is no complete OSPF header present in the packet

This is a short-cut function enabling quick and easy access to the OSPF header. If you only care about the OSPF header, this function may be useful but we otherwise recommend the use of the more generic trace_get_transport() function instead.

Upon return, 'version' is updated to contain the OSPF version number for the packet so that the returned pointer may be cast to the correct type. The version parameter MUST contain a valid pointer; it MUST NOT be NULL.

'remaining' is also set to contain the number of captured bytes remaining starting from the pointer returned by this function.

Note
Unlike trace_get_transport(), this function will return NULL if the OSPF header is incomplete or truncated.

References trace_get_transport(), and TRACE_IPPROTO_OSPF.

DLLEXPORT SIMPLE_FUNCTION uint32_t trace_get_ospf_metric_from_as_external_lsa_v2 ( libtrace_ospf_as_external_lsa_v2_t as_lsa)

Extracts the metric field from an AS External LSA packet.

Parameters
as_lsaThe AS External LSA
Returns
The value of the metric field

The metric field in the AS External LSA packet is a 24-bit value, which is difficult to extract correctly. To avoid byte-ordering issues, use this function which will extract the correct value for you.

References libtrace_ospf_as_external_lsa_t::metric_a, libtrace_ospf_as_external_lsa_t::metric_b, and libtrace_ospf_as_external_lsa_t::metric_c.

DLLEXPORT SIMPLE_FUNCTION uint32_t trace_get_ospf_metric_from_summary_lsa_v2 ( libtrace_ospf_summary_lsa_v2_t sum_lsa)

Extracts the metric field from a Summary LSA packet.

Parameters
sum_lsaThe Summary LSA
Returns
The value of the metric field

The metric field in the Summary LSA packet is a 24-bit value, which is difficult to extract correctly. To avoid byte-ordering issues, use this function which will extract the correct value for you.

References libtrace_ospf_summary_lsa::metric_a, libtrace_ospf_summary_lsa::metric_b, and libtrace_ospf_summary_lsa::metric_c.

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.

Use this function instead of the deprecated trace_get_link().

Parameters
packetThe packet to get the buffer from
[out]linktypeThe linktype of the returned pointer
[out]remainingThe capture length (the number of captured bytes from the returned pointer)
Returns
A pointer to the first byte of the packet

References libtrace_packet_t::payload, trace_get_capture_length(), trace_get_link_type(), trace_get_wire_length(), and TRACE_TYPE_CONTENT_INVALID.

Referenced by pcap_get_direction(), trace_apply_filter(), trace_get_layer2(), trace_get_packet_meta(), and trace_get_payload_length().

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.

This function takes a pointer to a libtrace packet and if any metadata headers exist, returns a pointer to the first one, along with its corresponding linktype.

If no metadata headers exist in the packet, NULL is returned.

A metadata header is a header that was prepended by the capturing device, such as a Linux SLL header, or a Radiotap wireless monitoring header. Subsequent metadata headers may be accessed with the trace_get_payload_from_meta(...) function.

Parameters
packetThe libtrace packet
[out]linktypeThe linktype of the returned metadata header
[out]remainingThe number of bytes captured after the returned pointer.
Returns
A pointer to the first metadata header, or NULL if there are no metadata headers present.

remaining may be NULL, however linktype must be provided.

References trace_get_packet_buffer(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

DLLEXPORT void* trace_get_payload_from_gre ( libtrace_gre_t gre,
uint32_t *  remaining 
)

Gets a pointer to the payload following a GRE header.

Parameters
greA pointer to the beginning of the GRE header.
[in,out]remainingUpdated with the number of captured bytes remaining.
Returns
A pointer to the GRE payload, or NULL if the GRE header is truncated.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the GRE header (including the GRE header itself). remaining will be updated to contain the number of bytes remaining after the GRE header has been skipped.

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

References libtrace_gre_t::flags.

DLLEXPORT void* trace_get_payload_from_icmp ( libtrace_icmp_t icmp,
uint32_t *  remaining 
)

Gets a pointer to the payload following a ICMP header.

Parameters
icmpA pointer to the ICMP header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the ICMP payload, or NULL if the ICMP header is truncated.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the ICMP header (including the ICMP header itself). remaining will be updated to contain the number of bytes remaining after the ICMP header has been skipped.

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

Note
In the case of some ICMP messages, the payload may be the IP header from the packet that triggered the ICMP message.

Referenced by trace_checksum_transport().

DLLEXPORT void* trace_get_payload_from_icmp6 ( libtrace_icmp6_t icmp,
uint32_t *  remaining 
)

Gets a pointer to the payload following a ICMPv6 header.

Parameters
icmpA pointer to the ICMPv6 header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the ICMPv6 payload, or NULL if the ICMPv6 header is truncated.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the ICMPv6 header (including the ICMP header itself). remaining will be updated to contain the number of bytes remaining after the ICMPv6 header has been skipped.

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

Note
In the case of some ICMPv6 messages, the payload may be the IP header from the packet that triggered the ICMP message.
DLLEXPORT void* trace_get_payload_from_ip ( libtrace_ip_t ip,
uint8_t *  proto,
uint32_t *  remaining 
)

Gets a pointer to the payload following an IPv4 header.

Parameters
ipThe IPv4 Header
[out]protoThe protocol of the header following the IPv4 header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the transport layer header, or NULL if no subsequent header is present.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the IPv4 header (including the IPv4 header itself).

remaining will be decremented by the size of the IPv4 header (including any options). If the IPv4 header is complete but there are zero bytes of payload after the IPv4 header, a pointer to where the payload would be is returned and remaining will be set to 0. If the IPv4 header is incomplete, NULL will be returned and remaining will be set to 0. Therefore, it is very important to check the value of remaining after calling this function.

proto may be NULL, in which case it won't be updated.

Note
This is similar to trace_get_transport_from_ip in libtrace2

References libtrace_ip::ip_hl, libtrace_ip::ip_off, libtrace_ip::ip_p, and libtrace_ip::ip_v.

Referenced by trace_get_destination_address(), trace_get_icmp_from_ip(), trace_get_source_address(), trace_get_tcp_from_ip(), trace_get_transport(), and trace_get_udp_from_ip().

DLLEXPORT void* trace_get_payload_from_ip6 ( libtrace_ip6_t ipptr,
uint8_t *  proto,
uint32_t *  remaining 
)

Gets a pointer to the payload following an IPv6 header.

Parameters
ipptrThe IPv6 Header
[out]protoThe protocol of the header following the IPv6 header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the transport layer header, or NULL if no subsequent header is present.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the IPv6 header (including the IPv6 header itself).

remaining will be decremented by the size of the IPv6 header (including any options). If the IPv6 header is complete but there are zero bytes of payload after the IPv6 header, a pointer to where the payload would be is returned and remaining will be set to 0. If the IPv6 header is incomplete, NULL will be returned and remaining will be set to 0. Therefore, it is very important to check the value of remaining after calling this function.

proto may be NULL, in which case it won't be updated.

References libtrace_ip6::nxt, TRACE_IPPROTO_AH, TRACE_IPPROTO_DSTOPTS, TRACE_IPPROTO_ESP, TRACE_IPPROTO_FRAGMENT, and TRACE_IPPROTO_ROUTING.

Referenced by trace_get_destination_address(), trace_get_source_address(), and trace_get_transport().

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 following a layer 2 header.

Parameters
l2The pointer to the current layer 2 header
linktypeThe type of the layer 2 header
[out]ethertypeAn optional output variable of the ethernet type of the new header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the header following the provided layer 2 header, or NULL if no subsequent header is present.

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

If the layer 2 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 0. If the layer 2 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 TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_payload_from_atm(), trace_get_payload_from_ethernet(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_layer3(), and trace_get_payload_from_link().

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 following a link header.

Parameters
linkptrA pointer to the link layer header
linktypeThe linktype of the link header being examined
[out]typeAn output variable for the ethernet type
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the header following the link header, or NULL if no subsequent header is present.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the link header (including the link header itself). remaining will be updated to contain the number of bytes remaining after the link header has been skipped.

Deprecated:
This function is deprecated: you should be using trace_get_payload_from_layer2() or trace_get_payload_from_meta() instead.

References trace_get_payload_from_layer2(), and trace_get_payload_from_meta().

DLLEXPORT void* trace_get_payload_from_meta ( const void *  meta,
libtrace_linktype_t linktype,
uint32_t *  remaining 
)

Returns the payload of a metadata header.

This function takes a pointer to the start of a metadata header (either obtained via trace_get_packet_meta(...) or by a previous call to trace_get_payload_from_meta(...)) along with its corresponding linktype and returns the payload, i.e. the next header. It will also update the linktype parameter to indicate the type of payload.

If the linktype indicates that the header passed in is not a metadata header, the function returns NULL to indicate this. The linktype remains unchanged in this case.

This function allows the user to iterate through metadata headers which are sometimes present before the actual packet as it was received on the wire. Examples of metadata headers include the Linux SLL header and the Radiotap wireless monitoring header.

If the metadata header passed into this function is truncated, this function will return NULL, and remaining will be set to 0.

If there are 0 bytes of payload following the provided metadata header, the function will return a pointer to where the header would otherwise be and remaining will be 0.

Therefore, be sure to check the value of remaining after calling this function!

Parameters
[in]metaA pointer to a metadata header
[in,out]linktypeThe linktype of meta (updated to indicate the linktype of the returned header if applicable).
[in,out]remainingThe number of bytes after the meta pointer.
Returns
A pointer to the payload of the metadata header. If meta is not a pointer to a metadata header, NULL is returned and linktype remains unchanged.

All parameters are mandatory.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_layer2(), and trace_get_payload_from_link().

DLLEXPORT void* trace_get_payload_from_mpls ( void *  mpls,
uint16_t *  type,
uint32_t *  remaining 
)

Gets a pointer to the payload following an MPLS header.

Parameters
mplsA pointer to the MPLS header
[out]typeThe ethernet type, replaced by the ether type of the returned header - 0x0000 if an Ethernet header is returned
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the header beyond the MPLS label, if one is present. Will return NULL if there is not enough bytes remaining to skip past the MPLS label.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the MPLS header (including the MPLS header itself). remaining will be updated to contain the number of bytes remaining after the MPLS header has been skipped.

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

type will be set to the ethertype of the MPLS payload. This parameter is mandatory - it may not be NULL.

Note
This function will only remove one MPLS label at a time - the type will be set to 0x8847 if there is another MPLS label following the one skipped by this function.

References TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, and TRACE_ETHERTYPE_MPLS.

Referenced by trace_get_layer3(), and trace_strip_packet().

DLLEXPORT void* trace_get_payload_from_pppoe ( void *  pppoe,
uint16_t *  type,
uint32_t *  remaining 
)

Gets a pointer to the payload following a PPPoE header.

Parameters
pppoeA pointer to the PPPoE header
[out]typeThe ethernet type, replaced by the ether type of the returned header - 0x0000 if an Ethernet header is returned
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the header beyond the PPPoE header. NOTE that this function will also skip over the PPP header that will immediately follow the PPPoE header. This function will return NULL if there are not enough bytes remaining to skip past both the PPPoE and PPP headers.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the PPPoE header (including the PPPoE header itself). remaining will be updated to contain the number of bytes remaining after the PPPoE and PPP headers have been removed.

If the PPPoE and PPP headers are complete but there are zero bytes of payload after the PPP header, a pointer to where the payload would be is returned and remaining will be set to 0. If the PPPoE or PPP header is incomplete, NULL will be returned and remaining will be set to 0. Therefore, it is important to check the value of remaining after calling this function.

type will be set to the ether type of the PPP payload. This parameter is mandatory - it may not be NULL.

Referenced by trace_get_layer3(), and trace_strip_packet().

DLLEXPORT void* trace_get_payload_from_tcp ( libtrace_tcp_t tcp,
uint32_t *  remaining 
)

Gets a pointer to the payload following a TCP header.

Parameters
tcpA pointer to the TCP header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the TCP payload, or NULL if the TCP header is truncated.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the TCP header (including the TCP header itself). remaining will be updated to contain the number of bytes remaining after the TCP header has been skipped.

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

References libtrace_tcp::doff.

Referenced by trace_checksum_transport().

DLLEXPORT void* trace_get_payload_from_udp ( libtrace_udp_t udp,
uint32_t *  remaining 
)

Gets a pointer to the payload following a UDP header.

Parameters
udpA pointer to the UDP header
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the UDP payload, or NULL if the UDP header is truncated.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the UDP header (including the UDP header itself). remaining will be updated to contain the number of bytes remaining after the UDP header has been skipped.

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

Referenced by trace_checksum_transport(), and trace_get_vxlan_from_udp().

DLLEXPORT void* trace_get_payload_from_vlan ( void *  vlan,
uint16_t *  type,
uint32_t *  remaining 
)

Gets a pointer to the payload following an 802.1q (VLAN) header.

Parameters
vlanA pointer to the VLAN header
[out]typeThe ethernet type, replaced with the VLAN ether type
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the header beyond the VLAN header, if one is present. Otherwise, returns NULL.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the VLAN header (including the VLAN header itself). remaining will be updated to contain the number of bytes remaining after the VLAN header has been skipped.

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

type will be set to the ethertype of the VLAN payload. This parameter is not mandatory, but is highly recommended.

References libtrace_8021q::vlan_ether_type.

Referenced by trace_get_layer3(), and trace_strip_packet().

DLLEXPORT void* trace_get_payload_from_vxlan ( libtrace_vxlan_t vxlan,
uint32_t *  remaining 
)

Gets a pointer to the payload following a VXLAN header.

Parameters
vxlanA pointer to the beginning of the VXLAN header.
[in,out]remainingUpdated with the number of captured bytes remaining.
Returns
A pointer to the VXLAN payload, or NULL if the VXLAN header is truncated.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the VXLAN header (including the VXLAN header itself). remaining will be updated to contain the number of bytes remaining after the VXLAN header has been skipped.

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

DLLEXPORT SIMPLE_FUNCTION size_t trace_get_payload_length ( const libtrace_packet_t packet)

Get the length of the original payload content of the packet (in bytes).

Parameters
packetThe packet to determine the payload length for
Returns
The size of the packet payload (without headers). Returns 0 if unable to calculate payload length correctly.

This function reports the amount of data that followed the transport header when the packet was originally captured, i.e. prior to any snapping. Best described as the wire length minus the packet headers.

Currently only supports some protocols and will return 0 if an unsupported protocol header is encountered, or if one of the headers is truncated.

Note
Supports IPv4, IPv6, TCP, UDP and ICMP.

References libtrace_tcp::doff, libtrace_ip::ip_hl, libtrace_ip::ip_len, libtrace_ip::ip_p, libtrace_packet_t::payload_length, libtrace_ip6::plen, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_packet_buffer(), trace_get_transport(), TRACE_IPPROTO_ICMP, TRACE_IPPROTO_ICMPV6, TRACE_IPPROTO_IPV6, TRACE_IPPROTO_TCP, and TRACE_IPPROTO_UDP.

Referenced by trace_checksum_transport().

DLLEXPORT void DLLEXPORT DEPRECATED uint64_t trace_get_received_packets ( libtrace_t trace)

Returns the number of packets observed on an input trace.

Includes the number of packets counted as early as possible, before filtering, and includes dropped packets.

Parameters
traceThe input trace to examine
Returns
The number of packets seen at the capture point before filtering.

If the number is not known, this function will return UINT64_MAX

Deprecated:
This function is deprecated: Use trace_get_statistics(), this allows all statistic counters to be read in an atomic manner.

References libtrace_t::format, libtrace_format_t::get_received_packets, libtrace_format_t::get_statistics, libtrace_stat_t::magic, libtrace_stat_t::received, trace_get_statistics(), and UINT64_MAX.

DLLEXPORT SIMPLE_FUNCTION double trace_get_seconds ( const libtrace_packet_t packet)

Get the packet timestamp in floating point seconds.

Parameters
packetThe packet to extract the timestamp from
Returns
time that this packet was seen in 64-bit floating point seconds from the UNIX epoch (1970-01-01 00:00:00 UTC).

References libtrace_t::format, libtrace_format_t::get_erf_timestamp, libtrace_format_t::get_seconds, libtrace_format_t::get_timespec, libtrace_format_t::get_timeval, libtrace_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.

Referenced by trace_event_trace().

DLLEXPORT SIMPLE_FUNCTION int8_t trace_get_server_port ( uint8_t  protocol,
uint16_t  source,
uint16_t  dest 
)

Hint at which of the two provided ports is the server port.

Parameters
protocolThe IP layer protocol, eg 6 (tcp), 17 (udp)
sourceThe source port from the packet
destThe destination port from the packet
Returns
one of USE_SOURCE or USE_DEST describing on which of the two ports is most likely to be the server port.
Note
Ports must be provided in HOST byte order!

This function is based almost entirely on heuristics and should not be treated as a definitive means of identifying the server port. However, it is deterministic, so it is very handy for identifying both halves of the same flow.

DLLEXPORT SIMPLE_FUNCTION struct sockaddr* trace_get_source_address ( const libtrace_packet_t packet,
struct sockaddr *  addr 
)

Get the source IP address for a given packet.

Parameters
packetThe packet to extract the source IP address from
addrA pointer to a sockaddr structure to store the address in. If NULL, static storage is used instead.
Returns
A pointer to a sockaddr holding a v4 or v6 IP address or on some platforms a sockaddr holding a MAC address. Returns NULL if no source IP address was available.
Note
The best way to use this function is to pass in a pointer to the struct sockaddr_storage for the addr parameter. This will avoid problems with trying to shoe-horn an IPv6 address into a sockaddr that only supports IPv4.

References libtrace_ip::ip_src, libtrace_ip6::ip_src, ports_t::src, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_ip(), and trace_get_payload_from_ip6().

Referenced by trace_get_source_address_string().

DLLEXPORT SIMPLE_FUNCTION char* trace_get_source_address_string ( const libtrace_packet_t packet,
char *  space,
int  spacelen 
)

Get the source IP address for a packet and convert it into a string.

Parameters
packetThe packet to extract the source IP address from
spaceA pointer to a character buffer to store the address in. If NULL, static storage is used instead.
spacelenThe size of the buffer passed in via 'space'. Set this to zero if you are going to pass in a NULL buffer.
Returns
A pointer to a character buffer containing the string representation of the source IP address. For packets where there is no suitable IP address, the source MAC will be returned instead. Returns NULL if no valid address is available.
Note
Be wary of the possibility of the address being an IPv6 address - make sure your buffer is large enough!

New in libtrace 3.0.17.

References trace_get_source_address().

DLLEXPORT SIMPLE_FUNCTION uint8_t* trace_get_source_mac ( libtrace_packet_t packet)

Gets the source MAC address for a given packet.

Parameters
packetThe packet to extract the source MAC address from
Returns
A pointer to the source MAC address field in the layer 2 header, (or NULL if there is no source MAC address or layer 2 header available)
Note
This is a zero-copy function, so the memory that the returned pointer points to is part of the packet itself.

References trace_get_layer2(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_source_port ( const libtrace_packet_t packet)

Gets the source port for a given packet.

Parameters
packetThe packet to get the source port from
Returns
The source port in HOST byte order or 0 if no suitable port number can be extracted from the packet.

This function will return 0 if the transport protocol is known not to use port numbers, e.g. ICMP. 0 is also returned if no transport header is present in the packet or the transport header has been truncated such that the port fields are not readable.

Note
If the transport protocol is not known by libtrace, the first two bytes of the transport header will be treated as the source port field.

References ports_t::src, trace_get_fragment_offset(), trace_get_transport(), TRACE_IPPROTO_ICMP, and TRACE_IPPROTO_ICMPV6.

DLLEXPORT libtrace_stat_t* trace_get_statistics ( libtrace_t trace,
libtrace_stat_t stats 
)

Returns statistic counters for a trace, for a parallel trace this is a combined total.

Where possible these are retrieved atomically, however this behaviour depends on the underlying trace format.

Parameters
traceThe input trace to examine.
statsOptional, Filled upon return with statistics about the trace, check the flags included to see if a given statistic is valid. If NULL a statistic structure owned by libtrace is returned, this should not be free'd and will become invalid if the trace is destroyed.
Returns
A pointer to the statistics structure.
Note
Use trace_create_stat() to create the stats object, this way future versions of libtrace can add to the structure without breaking existing code.

References libtrace_stat_t::accepted, libtrace_t::accepted_packets, libtrace_stat_t::filtered, libtrace_t::filtered_packets, libtrace_t::format, libtrace_format_t::get_statistics, LIBTRACE_STAT_FIELDS, libtrace_stat_t::magic, libtrace_stat_t::reserved1, libtrace_stat_t::reserved2, libtrace_t::state, and trace_create_statistics().

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

DLLEXPORT SIMPLE_FUNCTION libtrace_tcp_t* trace_get_tcp ( libtrace_packet_t packet)

Get a pointer to the TCP header (if present)

Parameters
packetThe packet to get the TCP header from
Returns
A pointer to the TCP header, or NULL if there is not a complete TCP header present in the packet.

This is a short-cut function enabling quick and easy access to the TCP header if that is all you care about. However, we recommend the use of the more generic trace_get_transport() function instead.

Note
Unlike trace_get_transport(), this function will return NULL if the TCP header is incomplete or truncated.

References trace_get_transport(), and TRACE_IPPROTO_TCP.

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 following an IPv4 header (if present)

Parameters
ipThe IP header to find the subsequent TCP header for
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the TCP header, or NULL if no TCP header is present in the packet.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the IP header (including the IP header itself). remaining will be updated to contain the number of bytes remaining after the IP header has been skipped.

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

Note
This function is rather redundant now that the layer 3 header is cached. There should be no performance advantage for the user to call this function over just calling trace_get_transport().
The last parameter has changed from libtrace2

References libtrace_ip::ip_p, trace_get_payload_from_ip(), and TRACE_IPPROTO_TCP.

DLLEXPORT void trace_get_thread_statistics ( libtrace_t trace,
libtrace_thread_t t,
libtrace_stat_t stats 
)

Returns statistic counters for a single thread of a trace.

Where possible these are retrieved atomically, however this behaviour depends on the underlying trace format.

Parameters
traceThe input trace to examine.
tAn optional thread to received stats for or NULL to retrieve stats for the current thread
statsFilled upon return with statistics about the trace, check the flags included to see if a given statistic is valid.
Note
Use trace_create_stat() to create the stats object, this way future versions of libtrace can add to the structure without breaking existing code.

References libtrace_stat_t::accepted, libtrace_stat_t::filtered, libtrace_t::format, libtrace_format_t::get_thread_statistics, LIBTRACE_STAT_FIELDS, libtrace_stat_t::magic, libtrace_stat_t::reserved1, libtrace_stat_t::reserved2, and trace_has_dedicated_hasher().

DLLEXPORT SIMPLE_FUNCTION struct timespec trace_get_timespec ( const libtrace_packet_t packet)

Get the packet timestamp as a struct timespec.

Parameters
packetThe packet to extract the timestamp from
Returns
The time that this packet was captured in a struct timespec
DLLEXPORT SIMPLE_FUNCTION struct timeval trace_get_timeval ( const libtrace_packet_t packet)

Get the packet timestamp as a struct timeval.

Parameters
packetThe packet to extract the timestamp from
Returns
The time that this packet was captured in a struct timeval

Referenced by demote_packet(), and store_first_packet().

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)

Parameters
packetThe libtrace packet to find the transport header for
[out]protoThe protocol present at the transport layer.
[out]remainingThe amount of captured data remaining in the packet starting from the returned pointer, i.e. including the transport header.
Returns
A pointer to the transport layer header. If no transport header is present in the packet, NULL is returned. If the transport header is truncated, a valid pointer will still be returned so be sure to check the value of remaining before attempting to process the returned header.

remaining may be NULL, otherwise it will be set to the number of captured bytes after the returned pointer.

Note
proto may be NULL if proto is unneeded.

References libtrace_packet_t::l4_header, libtrace_packet_t::l4_remaining, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_ip(), trace_get_payload_from_ip6(), TRACE_IPPROTO_IPV6, and libtrace_packet_t::transport_proto.

Referenced by trace_checksum_transport(), trace_get_destination_port(), trace_get_icmp(), trace_get_icmp6(), trace_get_ospf_header(), trace_get_payload_length(), trace_get_source_port(), trace_get_tcp(), and trace_get_udp().

DLLEXPORT SIMPLE_FUNCTION libtrace_udp_t* trace_get_udp ( libtrace_packet_t packet)

Get a pointer to the UDP header (if present)

Parameters
packetThe packet to get the UDP header from
Returns
A pointer to the UDP header, or NULL if there is not a complete UDP header present in the packet.

This is a short-cut function enabling quick and easy access to the UDP header if that is all you care about. However, we recommend the use of the more generic trace_get_transport() function instead.

Note
Unlike trace_get_transport(), this function will return NULL if the UDP header is incomplete or truncated.

References trace_get_transport(), and TRACE_IPPROTO_UDP.

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 following an IPv4 header (if present)

Parameters
ipThe IP header to find the subsequent UDP header for
[in,out]remainingUpdated with the number of captured bytes remaining
Returns
A pointer to the UDP header, or NULL if no UDP header is present in the packet.

When calling this function, remaining must contain the number of captured bytes remaining in the packet starting from the IP header (including the IP header itself). remaining will be updated to contain the number of bytes remaining after the IP header has been skipped.

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

Note
This function is rather redundant now that the layer 3 header is cached. There should be no performance advantage for the user to call this function over just calling trace_get_transport().
The last parameter has changed from libtrace2

References libtrace_ip::ip_p, trace_get_payload_from_ip(), and TRACE_IPPROTO_UDP.

DLLEXPORT libtrace_vxlan_t* trace_get_vxlan_from_udp ( libtrace_udp_t udp,
uint32_t *  remaining 
)

Gets a pointer to the payload following a VXLAN header.

Parameters
udpA pointer to the beginning of the UDP header.
[in,out]remainingUpdated with the number of captured bytes remaining.
Returns
A pointer to the beginning of the VXLAN header, or NULL if the UDP header is truncated, or this is not a VXLAN packet.

References libtrace_udp::dest, and trace_get_payload_from_udp().

DLLEXPORT SIMPLE_FUNCTION size_t trace_get_wire_length ( const libtrace_packet_t packet)

Get the size of the packet as it was originally seen on the wire (in bytes).

Parameters
packetThe packet to determine the wire length for
Returns
The size of the packet as it was on the wire.
Note
This value may not be the same as the capture length, due to truncation.
trace_get_wire_length includes the Frame Check Sequence. This is different behaviour compared to most PCAP-based tools.
The return size refers to the network-level payload of the packet and does not include any capture framing headers. For example, an Ethernet packet with an empty TCP packet will return sizeof(ethernet_header) + sizeof(ip_header) + sizeof(tcp_header), but not the capture format (pcap/erf/etc) header.

References libtrace_t::format, libtrace_format_t::get_wire_length, LIBTRACE_PACKET_BUFSIZE, libtrace_t::startcount, libtrace_packet_t::trace, libtrace_packet_t::which_trace_start, and libtrace_packet_t::wire_length.

Referenced by demote_packet(), and trace_get_packet_buffer().

DLLEXPORT bool trace_get_wireless_antenna ( void *  linkptr,
libtrace_linktype_t  linktype,
uint8_t *  antenna 
)

Get the wireless antenna.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]antennaThe antenna that was used to transmit or receive the frame.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_ANTENNA, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_freq ( void *  linkptr,
libtrace_linktype_t  linktype,
uint16_t *  freq 
)

Get the wireless channel frequency.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]freqThe frequency in MHz of the channel the frame was transmitted or received on.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_CHANNEL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_noise_strength_db ( void *  linkptr,
libtrace_linktype_t  linktype,
uint8_t *  strength 
)

Get the wireless noise strength in dB.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]strengthThe RF noise power at the antenna, in dB difference from a fixed reference.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_DB_ANTNOISE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_noise_strength_dbm ( void *  linkptr,
libtrace_linktype_t  linktype,
int8_t *  strength 
)

Get the wireless noise strength in dBm.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]strengthThe RF noise power at the antenna, in dB difference from 1mW.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_DBM_ANTNOISE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_rate ( void *  linkptr,
libtrace_linktype_t  linktype,
uint8_t *  rate 
)

Get the wireless data rate.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]rateThe data-rate of the frame in units of 500kbps
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_RATE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_signal_strength_db ( void *  linkptr,
libtrace_linktype_t  linktype,
uint8_t *  strength 
)

Get the wireless signal strength in dB.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]strengthThe RF signal power at the antenna, in dB difference from a fixed reference.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_DB_ANTSIGNAL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_signal_strength_dbm ( void *  linkptr,
libtrace_linktype_t  linktype,
int8_t *  strength 
)

Get the wireless signal strength in dBm.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]strengthThe RF signal power at the antenna, in dB difference from 1mW.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_DBM_ANTSIGNAL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_tsft ( void *  linkptr,
libtrace_linktype_t  linktype,
uint64_t *  tsft 
)

Get the wireless Timer Synchronisation Function.

Gets the value of the timer synchronisation function for this frame, which is a value in microseconds indicating the time that the first bit of the MPDU was received by the MAC.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]tsftThe value of the timer synchronisation function.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_TSFT, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_tx_attenuation ( void *  linkptr,
libtrace_linktype_t  linktype,
uint16_t *  attenuation 
)

Get the wireless transmit attenuation.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]attenuationThe transmit power as a unitless distance from maximum power set at factory calibration. 0 indicates maximum transmission power.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_TX_ATTENUATION, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_tx_attenuation_db ( void *  linkptr,
libtrace_linktype_t  linktype,
uint16_t *  attenuation 
)

Get the wireless transmit attenuation in dB.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]attenuationThe transmit power as dB difference from maximum power set at factory calibration. 0 indicates maximum power.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_DB_TX_ATTENUATION, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT bool trace_get_wireless_tx_power_dbm ( void *  linkptr,
libtrace_linktype_t  linktype,
int8_t *  txpower 
)

Get the wireless transmit power in dBm.

Parameters
linkptrThe wireless meta header
linktypeThe linktype of the wireless meta header passed in
[out]txpowerThe transmit power as dB from a 1mW reference. This is the absolute power level measured at the antenna port.
Returns
true if the field was available, false if not.

References arphrd_type_to_libtrace(), trace_get_payload_from_linux_sll(), TRACE_RADIOTAP_DBM_TX_POWER, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

DLLEXPORT void trace_help ( void  )

Prints help information for libtrace.

Function prints out some basic help information regarding libtrace, and then prints out the help() function registered with each input module

References libtrace_format_t::help, and libtrace_format_t::next.

DLLEXPORT void trace_interrupt ( void  )

Causes a libtrace reader to stop blocking whilst waiting on new packets and immediately return EOF.

This function is useful if you are handling signals within your libtrace program. If a live source is not receiving any packets (or they are being filtered), a call to trace_read_packet will result in an infinite loop as it will block until a packet is received. Normally, a SIGINT would cause the program to end and thus break the loop, but if you are handling the signal yourself then that signal will never reach libtrace.

Instead this function sets a global variable within libtrace that will cause a blocking live capture to break on the next internal timeout, allowing control to be returned to the user and their own signal handling to kick in.

References libtrace_halt.

DLLEXPORT bool trace_is_err ( libtrace_t trace)

Indicate if there has been an error on an input trace.

Parameters
traceThe input trace to check the error state on
Returns
true if an error has occurred, false otherwise
Note
This does not clear the error status, and only returns true or false.

References libtrace_t::err, and trace_err_t::err_num.

Referenced by trace_config(), trace_event_device(), trace_event_trace(), trace_pstart(), trace_read_packet(), and trace_start().

DLLEXPORT bool trace_is_err_output ( libtrace_out_t trace)

Indicates if there is an error on an output trace.

Parameters
traceThe output trace to check the error state on
Returns
true if an error has occurred, false otherwise.

This does not clear the error status, and only returns true or false.

References libtrace_out_t::err, and trace_err_t::err_num.

DLLEXPORT const char* trace_parse_uri ( const char *  uri,
char **  format 
)

Takes a uri and splits it into a format and uridata component.

Parameters
uriThe uri to be parsed
[out]formatA pointer that will be updated to point to an allocated string holding the format component of the URI
Returns
NULL if an error occurred, otherwise return a pointer to the uridata component
Note
The format component is strdup'd by this function, so be sure to free it when you are done with the split URI. Similarly, do not pass a pointer to an allocated string into this function as the 'format' parameter, as that memory will be leaked and replaced with the strdup'd format.

Referenced by trace_create(), and trace_create_output().

DLLEXPORT int trace_pause ( libtrace_t libtrace)

Pauses an input trace.

Parameters
libtraceThe trace to pause
Returns
0 on success, -1 on failure

This stops an input trace that is in progress and returns you to the configuration state. Any packets that arrive on a live capture after trace_pause() has been called will be discarded. To resume the trace, call trace_start().

References libtrace_t::format, libtrace_t::last_packet, libtrace_format_t::pause_input, libtrace_t::started, TRACE_ERR_BAD_STATE, trace_fin_packet(), and trace_set_err().

Referenced by trace_ppause().

DLLEXPORT void trace_perror ( libtrace_t trace,
const char *  msg,
  ... 
)

Outputs the error message for an input trace to stderr and clear the error status.

Parameters
traceThe input trace with the error to output
msgThe message to prepend to the error

This function does clear the error status.

Referenced by trace_event_device(), and trace_event_trace().

DLLEXPORT void trace_perror_output ( libtrace_out_t trace,
const char *  msg,
  ... 
)

Outputs the error message for an output trace to stderr and clear the error status.

Parameters
traceThe output trace with the error to output
msgThe message to prepend to the error This function does clear the error status.
DLLEXPORT 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
traceAn input trace of the same format as the "packet" contained in the buffer
packetThe libtrace packet to prepare
bufferA buffer containing the packet data, including the capture format header
rt_typeThe RT type for the packet that is being prepared
flagsUsed 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.

This function is now available via the exported API, as it can have some uses outside of internal libtrace contexts. However, we strongly advise that you avoid using this function unless you really know what you are doing.

References libtrace_packet_t::buf_control, libtrace_t::format, libtrace_t::last_packet, 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, and trace_set_err().

DLLEXPORT int trace_print_statistics ( const libtrace_stat_t s,
FILE *  f,
const char *  format 
)

Prints all valid stats to a file stream, (which could be stdout/err).

By default the format "name: value" is used.

Parameters
sThe statistic structure to print
fThe output file stream
formatAn optional format string such as the default ("%s: %"PRIu64"\n") This is passed to fprintf and called with two arguments first a char* (s) and second a uint64_t (PRIu64).
Returns
-1 if an error occurs when writing to the file stream, check errno. Otherwise 0.

References LIBTRACE_STAT_FIELDS, and libtrace_stat_t::magic.

DLLEXPORT int trace_read_packet ( libtrace_t trace,
libtrace_packet_t packet 
)

Read the next packet from an input trace.

Parameters
traceThe libtrace opaque pointer for the input trace
packetThe packet opaque pointer
Returns
0 on EOF, negative value on error, number of bytes read when successful.
Note
The number of bytes read is usually (but not always) the same as trace_get_framing_length()+trace_get_capture_length() depending on the trace format.
The trace must have been started with trace_start before calling this function
When reading from a live capture, this function will block until a packet is observed on the capture interface. The libtrace event API (e.g. trace_event()) should be used if non-blocking operation is required.

References libtrace_t::accepted_packets, libtrace_packet_t::buf_control, libtrace_t::filter, libtrace_t::filtered_packets, libtrace_t::format, libtrace_t::last_packet, libtrace_packet_t::order, libtrace_format_t::read_packet, libtrace_t::sequence_number, libtrace_t::snaplen, libtrace_t::startcount, libtrace_t::started, libtrace_packet_t::trace, trace_apply_filter(), TRACE_CTRL_EXTERNAL, TRACE_CTRL_PACKET, TRACE_ERR_BAD_STATE, TRACE_ERR_UNSUPPORTED, trace_fin_packet(), trace_is_err(), trace_packet_set_order(), trace_set_capture_length(), trace_set_err(), and libtrace_packet_t::which_trace_start.

Referenced by trace_event_device(), and trace_event_trace().

DLLEXPORT int trace_seek_erf_timestamp ( libtrace_t trace,
uint64_t  ts 
)

Seek within an input trace to a time specified as an ERF timestamp.

Parameters
traceThe input trace to seek within
tsThe time to seek to, as an ERF timestamp
Returns
0 on success, -1 if the seek fails. Use trace_perror() to determine the error that occurred.

This will make the next packet read to be the first packet to occur at or after the specified time. This must be called in the configuration state (i.e. before trace_start() or after trace_pause()).

The time format accepted by this function is the ERF timestamp, which is a 64-bit value where the upper 32 bits are seconds since the UNIX epoch and the lower 32 bits are partial seconds.

Note
This function may be extremely slow.

References libtrace_t::format, libtrace_format_t::seek_erf, libtrace_format_t::seek_seconds, libtrace_format_t::seek_timeval, TRACE_ERR_OPTION_UNAVAIL, and trace_set_err().

DLLEXPORT int trace_seek_seconds ( libtrace_t trace,
double  seconds 
)

Seek within an input trace to a time specified in floating point seconds.

Parameters
traceThe input trace to seek within
secondsThe time to seek to, in floating point seconds
Returns
0 on success, -1 if the seek fails. Use trace_perror() to determine the error that occurred.

This will make the next packet read to be the first packet to occur at or after the specified time. This must be called in the configuration state (i.e. before trace_start() or after trace_pause()).

The time format accepted by this function is 64-bit floating point seconds since the UNIX epoch (1970-01-01 00:00:00 UTC), i.e. the same format as trace_get_seconds().

Note
This function may be extremely slow.

References libtrace_t::format, libtrace_format_t::seek_erf, libtrace_format_t::seek_seconds, libtrace_format_t::seek_timeval, TRACE_ERR_OPTION_UNAVAIL, and trace_set_err().

DLLEXPORT int trace_seek_timeval ( libtrace_t trace,
struct timeval  tv 
)

Seek within an input trace to a time specified as a timeval.

Parameters
traceThe input trace to seek within
tvThe time to seek to, as a timeval
Returns
0 on success, -1 if the seek fails. Use trace_perror() to determine the error that occurred.

This will make the next packet read to be the first packet to occur at or after the specified time. This must be called in the configuration state (i.e. before trace_start() or after trace_pause()).

Note
This function may be extremely slow.

References libtrace_t::format, libtrace_format_t::seek_erf, libtrace_format_t::seek_seconds, libtrace_format_t::seek_timeval, TRACE_ERR_OPTION_UNAVAIL, and trace_set_err().

DLLEXPORT size_t trace_set_capture_length ( libtrace_packet_t packet,
size_t  size 
)

Truncate ("snap") the packet to the suggested length.

Parameters
packetThe packet to truncate
sizeThe new length of the packet (in bytes)
Returns
The new capture length of the packet or the original capture length of the packet if unchanged.

This function will modify the capture length of the given packet. The wire length will not be changed, so you can always determine what the original packet size was, prior to the truncation.

Note
You can only use this function to decrease the capture length. Any attempt to increase capture length will have no effect.

References libtrace_packet_t::capture_length, libtrace_t::format, libtrace_format_t::set_capture_length, and libtrace_packet_t::trace.

Referenced by demote_packet(), trace_read_packet(), and trace_strip_packet().

DLLEXPORT libtrace_direction_t trace_set_direction ( libtrace_packet_t packet,
libtrace_direction_t  direction 
)

Set the direction flag for a packet, if the capture format supports direction tagging.

Parameters
packetThe packet to set the direction for
directionThe new direction
Returns
-1 on error, or the direction that was set.
Note
Few capture formats actually support direction tagging. Most notably, we cannot set the direction on PCAP packets.

References libtrace_t::format, libtrace_format_t::set_direction, and libtrace_packet_t::trace.

DLLEXPORT int trace_set_event_realtime ( libtrace_t trace,
bool  realtime 
)

If enabled, the libtrace event API will ignore time gaps between packets when reading from a trace file.

Parameters
libtraceThe trace object to apply the option to
realtimeTrue ignores gaps
Returns
-1 if option configuration failed, 0 otherwise

References trace_config(), and TRACE_OPTION_EVENT_REALTIME.

DLLEXPORT int trace_set_filter ( libtrace_t trace,
libtrace_filter_t filter 
)

Apply this filter to all packets read from this trace.

Parameters
libtraceThe trace object to apply the option to
filterThe filter to apply
Returns
-1 if option configuration failed, 0 otherwise

References trace_config(), and TRACE_OPTION_FILTER.

DLLEXPORT int trace_set_meta_freq ( libtrace_t trace,
int  freq 
)

Defines the frequency of meta-data reporting, e.g.

DUCK packets

Parameters
libtraceThe trace object to apply the option to
freqThe meta data frequency
Returns
-1 if option configuration failed, 0 otherwise

References trace_config(), and TRACE_OPTION_META_FREQ.

DLLEXPORT int trace_set_promisc ( libtrace_t trace,
bool  promisc 
)

If enabled, places a live capture interface into promiscuous mode.

Parameters
libtraceThe trace object to apply the option to
promisc
Returns
-1 if option configuration failed, 0 otherwise

References trace_config(), and TRACE_OPTION_PROMISC.

DLLEXPORT int trace_set_snaplen ( libtrace_t trace,
int  snaplen 
)

Maximum number of bytes to be captured for any given packet.

Parameters
libtraceThe trace object to apply the option to
snaplenThe snap length to set
Returns
-1 if option configuration failed, 0 otherwise

References trace_config(), and TRACE_OPTION_SNAPLEN.

DLLEXPORT int trace_start ( libtrace_t libtrace)

Start an input trace.

Parameters
libtraceThe trace to start
Returns
0 on success, -1 on failure

This does the actual work of starting the input trace and applying all the config options. This may fail, returning -1. The libtrace error handling functions can be used to get more information about what specifically went wrong.

References libtrace_t::format, libtrace_format_t::start_input, libtrace_t::startcount, libtrace_t::started, and trace_is_err().

DLLEXPORT int trace_start_output ( libtrace_out_t libtrace)

Start an output trace.

Parameters
libtraceThe trace to start
Returns
0 on success, -1 on failure

This does the actual work with starting a trace capable of writing packets. This generally creates the output file.

References libtrace_out_t::format, libtrace_format_t::start_output, and libtrace_out_t::started.

DLLEXPORT libtrace_packet_t* trace_strip_packet ( libtrace_packet_t packet)

Strips layer 2.5 headers from a given packet.

Parameters
packetThe packet to strip headers from.
Returns
The packet with the requested headers removed (if they were present).

This function is intended for removing those pesky layer 2.5 headers that are not supported by other packet analysis applications, e.g. VLAN and MPLS headers. If successful, the resulting packet will be a simple Ethernet-IP-Transport packet that just about anything should be able to parse without difficulty.

If this function encounters a layer 2 or 2.5 header that it does not support, stripping will cease and the packet returning will be stripped up to but not including the unsupported header.

New in libtrace 4.0.0

Note
This function only supports stripping headers from Ethernet packets for now. Passing in packets of other link types will simply result in the original packet being returned unmodified.

References libtrace_ether::ether_type, libtrace_packet_t::l2_header, libtrace_packet_t::payload, TRACE_ETHERTYPE_8021Q, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, TRACE_ETHERTYPE_MPLS, TRACE_ETHERTYPE_PPP_SES, trace_get_capture_length(), trace_get_layer2(), trace_get_payload_from_mpls(), trace_get_payload_from_pppoe(), trace_get_payload_from_vlan(), trace_set_capture_length(), and TRACE_TYPE_ETH.

DLLEXPORT void trace_subtract_statistics ( const libtrace_stat_t a,
const libtrace_stat_t b,
libtrace_stat_t c 
)

Performs the operation c=a-b accounting for valid fields.

c is allowed to be a or b.

Parameters
aThe minuend
bThe subtrahend
cThe resulting difference

References LIBTRACE_STAT_FIELDS, and libtrace_stat_t::magic.

DLLEXPORT int trace_write_packet ( libtrace_out_t trace,
libtrace_packet_t packet 
)

Write one packet out to the output trace.

Parameters
traceThe libtrace_out opaque pointer for the output trace
packetThe packet opaque pointer of the packet to be written
Returns
The number of bytes written out, if zero or negative then an error has occured.

References libtrace_t::format, libtrace_out_t::format, libtrace_format_t::name, libtrace_out_t::started, libtrace_packet_t::trace, TRACE_ERR_BAD_STATE, TRACE_ERR_UNSUPPORTED, trace_set_err_out(), and libtrace_format_t::write_packet.