Trace file processing library header. More...

This graph shows which files directly or indirectly include 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...
Defines
#define	ct_assert(e) extern char (ct_assert(void)) [sizeof(char[1 - 2!(e)])]
#define	LIBTRACE_API_VERSION ((4<<16)\|(0<<8)\|(0))
	API version as 2 byte hex digits, eg 0xXXYYZZ.
#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.
#define	DAG_DRIVER_V ""
	DAG driver version installed on the current system.
#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.
#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.
#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.
typedef struct libtrace_t	libtrace_t
	Opaque structure holding information about a trace.
typedef struct libtrace_filter_t	libtrace_filter_t
	Opaque structure holding information about a bpf filter.
typedef struct libtrace_thread_t	libtrace_thread_t
	Opaque structure holding information about libtrace thread.
typedef struct callback_set	libtrace_callback_set_t
	Opaque structure holding callback functions for libtrace threads.
typedef struct trace_err_t	libtrace_err_t
	Libtrace error information.
typedef struct libtrace_packet_t	libtrace_packet_t
	The libtrace packet structure.
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 }
	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_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 }
	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 }
	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_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_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_LAST = 4000 }
	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.
DLLEXPORT void	trace_interrupt (void)
	Causes a libtrace reader to stop blocking whilst waiting on new packets and immediately return EOF.
DLLEXPORT SIMPLE_FUNCTION libtrace_linktype_t	trace_get_link_type (const libtrace_packet_t *packet)
	Gets the link layer type for a 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.
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.
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 2/Link layer/Datalink header -- This can be retrieved by trace_get_layer2(), or skipped using trace_get_payload_from_layer2(). Layer 3/IP/IPv6 -- This can be retrieved by trace_get_layer3(). As a convenience trace_get_ip()/trace_get_ip6() can be used to find an IPv4/IPv6 header. 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.
DLLEXPORT SIMPLE_FUNCTION DEPRECATED void *	trace_get_link (const libtrace_packet_t *packet)
	Get a pointer to the link layer for a given packet.
DLLEXPORT libtrace_packet_t *	trace_strip_packet (libtrace_packet_t *packet)
	Strips layer 2.5 headers from a given packet.
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.
DLLEXPORT SIMPLE_FUNCTION libtrace_ip6_t *	trace_get_ip6 (libtrace_packet_t *packet)
	get a pointer to the IPv6 header (if any)
DLLEXPORT void *	trace_get_packet_meta (const libtrace_packet_t packet, libtrace_linktype_t linktype, uint32_t *remaining)
	Return a pointer to the first metadata header in a packet, if present.
DLLEXPORT void *	trace_get_payload_from_meta (const void meta, libtrace_linktype_t linktype, uint32_t *remaining)
	Returns the payload of a metadata header.
DLLEXPORT void *	trace_get_layer2 (const libtrace_packet_t packet, libtrace_linktype_t linktype, uint32_t *remaining)
	Get a pointer to the layer 2 header.
DLLEXPORT void *	trace_get_payload_from_layer2 (void l2, libtrace_linktype_t linktype, uint16_t ethertype, uint32_t *remaining)
	Gets a pointer to the next header following a layer 2 header.
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.
DLLEXPORT uint16_t *	trace_checksum_layer3 (libtrace_packet_t packet, uint16_t csum)
	Calculates the expected IP checksum for a packet.
DLLEXPORT uint16_t *	trace_checksum_transport (libtrace_packet_t packet, uint16_t csum)
	Calculates the expected checksum for the transport header in a packet.
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.
DLLEXPORT void *	trace_get_transport (const libtrace_packet_t packet, uint8_t proto, uint32_t *remaining)
	Gets a pointer to the transport layer header (if any).
DLLEXPORT void *	trace_get_payload_from_ip (libtrace_ip_t ip, uint8_t proto, uint32_t *remaining)
	Gets a pointer to the payload following an IPv4 header.
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.
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.
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.
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.
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.
DLLEXPORT void *	trace_get_payload_from_tcp (libtrace_tcp_t tcp, uint32_t remaining)
	Gets a pointer to the payload following a TCP header.
DLLEXPORT void *	trace_get_payload_from_udp (libtrace_udp_t udp, uint32_t remaining)
	Gets a pointer to the payload following a UDP header.
DLLEXPORT void *	trace_get_payload_from_icmp (libtrace_icmp_t icmp, uint32_t remaining)
	Gets a pointer to the payload following a ICMP header.
DLLEXPORT void *	trace_get_payload_from_icmp6 (libtrace_icmp6_t icmp, uint32_t remaining)
	Gets a pointer to the payload following a ICMPv6 header.
DLLEXPORT void *	trace_get_payload_from_gre (libtrace_gre_t gre, uint32_t remaining)
	Gets a pointer to the payload following a GRE header.
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.
DLLEXPORT void *	trace_get_payload_from_vxlan (libtrace_vxlan_t vxlan, uint32_t remaining)
	Gets a pointer to the payload following a VXLAN header.
DLLEXPORT SIMPLE_FUNCTION libtrace_tcp_t *	trace_get_tcp (libtrace_packet_t *packet)
	Get a pointer to the TCP header (if present).
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).
DLLEXPORT SIMPLE_FUNCTION libtrace_udp_t *	trace_get_udp (libtrace_packet_t *packet)
	Get a pointer to the UDP header (if present).
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).
DLLEXPORT SIMPLE_FUNCTION libtrace_icmp_t *	trace_get_icmp (libtrace_packet_t *packet)
	Get a pointer to the ICMP header (if present).
DLLEXPORT SIMPLE_FUNCTION libtrace_icmp6_t *	trace_get_icmp6 (libtrace_packet_t *packet)
	Get a pointer to the ICMPv6 header (if present).
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).
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).
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.
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.
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.
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.
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).
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).
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).
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.
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.
DLLEXPORT SIMPLE_FUNCTION uint8_t *	trace_get_destination_mac (libtrace_packet_t *packet)
	Gets the destination MAC address for a given packet.
DLLEXPORT SIMPLE_FUNCTION uint8_t *	trace_get_source_mac (libtrace_packet_t *packet)
	Gets the source MAC address for a given packet.
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.
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.
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.
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.
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.
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.
DLLEXPORT SIMPLE_FUNCTION struct timeval	trace_get_timeval (const libtrace_packet_t *packet)
	Get the packet timestamp as a struct timeval.
DLLEXPORT SIMPLE_FUNCTION struct timespec	trace_get_timespec (const libtrace_packet_t *packet)
	Get the packet timestamp as a struct timespec.
DLLEXPORT SIMPLE_FUNCTION double	trace_get_seconds (const libtrace_packet_t *packet)
	Get the packet timestamp in floating point seconds.
DLLEXPORT int	trace_seek_seconds (libtrace_t *trace, double seconds)
	Seek within an input trace to a time specified in floating point seconds.
DLLEXPORT int	trace_seek_timeval (libtrace_t *trace, struct timeval tv)
	Seek within an input trace to a time specified as a timeval.
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.
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.
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).
DLLEXPORT SIMPLE_FUNCTION size_t	trace_get_framing_length (const libtrace_packet_t *packet)
	Get the length of the capture framing headers (in bytes).
DLLEXPORT 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).
DLLEXPORT size_t	trace_set_capture_length (libtrace_packet_t *packet, size_t size)
	Truncate ("snap") the packet to the suggested length.
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.
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.
DLLEXPORT int	trace_apply_filter (libtrace_filter_t filter, const libtrace_packet_t packet)
	Apply a BPF filter to a packet.
DLLEXPORT void	trace_destroy_filter (libtrace_filter_t *filter)
	Destroy a BPF filter.
Portability
This section 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.
DLLEXPORT uint8_t *	trace_ether_aton (const char buf, uint8_t addr)
	Convert a string to an ethernet address.
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	TRACE_SLL_HOST 0
	Packet was addressed for the local host.
#define	TRACE_SLL_BROADCAST 1
	Packet was addressed for a broadcast address.
#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.
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.
typedef struct libtrace_ip6_ext	libtrace_ip6_ext_t
	IPv6 header extension structure.
typedef struct libtrace_ip6_frag	libtrace_ip6_frag_t
	IPv6 fragmentation header.
typedef struct libtrace_ip6	libtrace_ip6_t
	Generic IPv6 header structure.
typedef struct libtrace_tcp	libtrace_tcp_t
	Generic TCP header structure.
typedef struct libtrace_udp	libtrace_udp_t
	Generic UDP header structure.
typedef struct libtrace_icmp	libtrace_icmp_t
	Generic ICMP header structure.
typedef struct libtrace_icmp6	libtrace_icmp6_t
	Generic ICMPv6 header structure.
typedef struct libtrace_llcsnap	libtrace_llcsnap_t
	Generic LLC/SNAP header structure.
typedef struct libtrace_ether	libtrace_ether_t
	802.3 frame
typedef struct libtrace_8021q	libtrace_8021q_t
	802.1Q frame
typedef struct libtrace_atm_cell	libtrace_atm_cell_t
	ATM User Network Interface (UNI) Cell.
typedef struct libtrace_atm_nni_cell	libtrace_atm_nni_cell_t
	ATM Network Node/Network Interface (NNI) Cell.
typedef struct libtrace_atm_capture_cell	libtrace_atm_capture_cell_t
	Captured UNI cell.
typedef struct libtrace_atm_nni_capture_cell	libtrace_atm_nni_capture_cell_t
	Captured NNI cell.
typedef struct libtrace_ppp	libtrace_ppp_t
	PPP header.
typedef struct libtrace_pppoe	libtrace_pppoe_t
	PPPoE header.
typedef struct libtrace_gre_t	libtrace_gre_t
	Libtrace local definition of GRE (Generalised Routing Protocol) header RFC2890.
typedef struct libtrace_vxlan_t	libtrace_vxlan_t
	Libtrace local definition of VXLAN Header (draft-mahalingam-dutt-dcops-vxlan).
typedef struct libtrace_80211_t	libtrace_80211_t
	802.11 header
typedef struct libtrace_radiotap_t	libtrace_radiotap_t
	The Radiotap header pre-amble.
typedef struct libtrace_ospf_v2_t	libtrace_ospf_v2_t
	OSPF header.
typedef struct libtrace_ospf_options_t	libtrace_ospf_options_t
	Options Field present in some OSPFv2 packets.
typedef struct libtrace_ospf_lsa_v2_t	libtrace_ospf_lsa_v2_t
	LSA Header for OSPFv2.
typedef struct libtrace_ospf_hello_v2_t	libtrace_ospf_hello_v2_t
	OSPFv2 Hello Packet.
typedef struct libtrace_ospf_db_desc_v2_t	libtrace_ospf_db_desc_v2_t
	OSPFv2 Database Description packet.
typedef struct libtrace_ospf_ls_req_t	libtrace_ospf_ls_req_t
	OSPF Link State Request Packet.
typedef struct libtrace_ospf_ls_update_t	libtrace_ospf_ls_update_t
	OSPF Link State Update Packet.
typedef struct libtrace_ospf_as_external_lsa_t	libtrace_ospf_as_external_lsa_v2_t
	OSPFv2 AS External LSA Body.
typedef struct libtrace_ospf_summary_lsa	libtrace_ospf_summary_lsa_v2_t
	OSPFv2 Summary LSA Body.
typedef struct libtrace_ospf_network_lsa_t	libtrace_ospf_network_lsa_v2_t
	OSPFv2 Network LSA Body.
typedef struct libtrace_ospf_link_t	libtrace_ospf_link_v2_t
	OSPFv2 Router Link structure.
typedef struct libtrace_ospf_router_lsa_t	libtrace_ospf_router_lsa_v2_t
	OSPFv2 Router LSA.
typedef struct libtrace_sll_header_t	libtrace_sll_header_t
	A local definition of an SLL header.
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.
enum	trace_option_t { TRACE_OPTION_SNAPLEN, TRACE_OPTION_PROMISC, TRACE_OPTION_FILTER, TRACE_OPTION_META_FREQ, TRACE_OPTION_EVENT_REALTIME, TRACE_OPTION_HASHER }
	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.
DLLEXPORT const char *	trace_parse_uri (const char uri, char *format)
	Takes a uri and splits it into a format and uridata component.
DLLEXPORT libtrace_t *	trace_create (const char *uri)
	Create an input trace from a URI.
DLLEXPORT libtrace_t *	trace_create_dead (const char *uri)
	Creates a "dummy" trace file that has only the format type set.
DLLEXPORT libtrace_out_t *	trace_create_output (const char *uri)
	Creates a trace output file from a URI.
DLLEXPORT int	trace_start (libtrace_t *libtrace)
	Start an input trace.
DLLEXPORT int	trace_pause (libtrace_t *libtrace)
	Pauses an input trace.
DLLEXPORT int	trace_start_output (libtrace_out_t *libtrace)
	Start an output trace.
DLLEXPORT int	trace_config (libtrace_t libtrace, trace_option_t option, void value)
	Sets an input config option.
DLLEXPORT int	trace_set_snaplen (libtrace_t *trace, int snaplen)
	Maximum number of bytes to be captured for any given packet.
DLLEXPORT int	trace_set_promisc (libtrace_t *trace, bool promisc)
	If enabled, places a live capture interface into promiscuous mode.
DLLEXPORT int	trace_set_filter (libtrace_t trace, libtrace_filter_t filter)
	Apply this filter to all packets read from this trace.
DLLEXPORT int	trace_set_meta_freq (libtrace_t *trace, int freq)
	Defines the frequency of meta-data reporting, e.g.
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.
	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.
DLLEXPORT void	trace_destroy (libtrace_t *trace)
	Close an input trace, freeing up any resources it may have been using.
DLLEXPORT void	trace_destroy_dead (libtrace_t *trace)
	Close a dummy trace file, freeing up any resources it may have been using.
DLLEXPORT void	trace_destroy_output (libtrace_out_t *trace)
	Close an output trace, freeing up any resources it may have been using.
DLLEXPORT libtrace_err_t	trace_get_err (libtrace_t *trace)
	Check (and clear) the current error state of an input trace.
DLLEXPORT bool	trace_is_err (libtrace_t *trace)
	Indicate if there has been an error on an input trace.
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.
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.
DLLEXPORT bool	trace_is_err_output (libtrace_out_t *trace)
	Indicates if there is an error on an output trace.
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.
DLLEXPORT void DLLEXPORT DEPRECATED uint64_t	trace_get_received_packets (libtrace_t *trace)
	Returns the number of packets observed on an input trace.
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.
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.
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().
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.
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.
DLLEXPORT libtrace_stat_t *	trace_create_statistics (void)
	Creates and returns a zeroed libtrace_stat_t structure.
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.
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.
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).
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
DLLEXPORT bool	trace_get_wireless_tsft (void linkptr, libtrace_linktype_t linktype, uint64_t tsft)
	Get the wireless Timer Synchronisation Function.
DLLEXPORT bool	trace_get_wireless_rate (void linkptr, libtrace_linktype_t linktype, uint8_t rate)
	Get the wireless data rate.
DLLEXPORT bool	trace_get_wireless_freq (void linkptr, libtrace_linktype_t linktype, uint16_t freq)
	Get the wireless channel frequency.
DLLEXPORT bool	trace_get_wireless_signal_strength_dbm (void linkptr, libtrace_linktype_t linktype, int8_t strength)
	Get the wireless signal strength in dBm.
DLLEXPORT bool	trace_get_wireless_noise_strength_dbm (void linkptr, libtrace_linktype_t linktype, int8_t strength)
	Get the wireless noise strength in dBm.
DLLEXPORT bool	trace_get_wireless_signal_strength_db (void linkptr, libtrace_linktype_t linktype, uint8_t strength)
	Get the wireless signal strength in dB.
DLLEXPORT bool	trace_get_wireless_noise_strength_db (void linkptr, libtrace_linktype_t linktype, uint8_t strength)
	Get the wireless noise strength in dB.
DLLEXPORT bool	trace_get_wireless_tx_attenuation (void linkptr, libtrace_linktype_t linktype, uint16_t attenuation)
	Get the wireless transmit attenuation.
DLLEXPORT bool	trace_get_wireless_tx_attenuation_db (void linkptr, libtrace_linktype_t linktype, uint16_t attenuation)
	Get the wireless transmit attenuation in dB.
DLLEXPORT bool	trace_get_wireless_tx_power_dbm (void linkptr, libtrace_linktype_t linktype, int8_t txpower)
	Get the wireless transmit power in dBm.
DLLEXPORT bool	trace_get_wireless_antenna (void linkptr, libtrace_linktype_t linktype, uint8_t antenna)
	Get the wireless antenna.
Reading / Writing packets
These members deal with creating, reading and writing packets
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.
DLLEXPORT libtrace_packet_t *	trace_create_packet (void)
	Create a new packet object.
DLLEXPORT libtrace_packet_t *	trace_copy_packet (const libtrace_packet_t *packet)
	Copy a packet object.
DLLEXPORT void	trace_destroy_packet (libtrace_packet_t *packet)
	Destroy a packet object.
DLLEXPORT int	trace_read_packet (libtrace_t trace, libtrace_packet_t packet)
	Read the next packet from an input trace.
DLLEXPORT libtrace_eventobj_t	trace_event (libtrace_t trace, libtrace_packet_t packet)
	Processes the next libtrace event from an input trace.
DLLEXPORT int	trace_write_packet (libtrace_out_t trace, libtrace_packet_t packet)
	Write one packet out to the output trace.
DLLEXPORT enum base_format_t	trace_get_format (struct libtrace_packet_t *packet)
	Gets the capture format for a given packet.
DLLEXPORT void	trace_construct_packet (libtrace_packet_t packet, libtrace_linktype_t linktype, const void data, uint16_t len)
	Construct a libtrace packet from a buffer containing the packet payload.
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.
DLLEXPORT SIMPLE_FUNCTION uint16_t	trace_get_destination_port (const libtrace_packet_t *packet)
	Gets the destination port for a given packet.
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.

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.

Define 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)|(0))

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_get_capture_length(), and trace_get_wire_length().

#define LIBTRACE_STAT_FIELDS

Value:

X(accepted) \
        X(filtered) \
        X(received) \
        X(dropped) \
        X(captured) \
        X(errors)

An X Macro set for libtrace stat fields.

Referenced by trace_add_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.

Typedef Documentation

typedef struct libtrace_80211_t libtrace_80211_t

802.11 header

typedef struct libtrace_8021q libtrace_8021q_t

802.1Q frame

typedef struct libtrace_atm_capture_cell libtrace_atm_capture_cell_t

Captured UNI cell.

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.

typedef struct libtrace_atm_cell libtrace_atm_cell_t

ATM User Network Interface (UNI) Cell.

typedef struct libtrace_atm_nni_capture_cell libtrace_atm_nni_capture_cell_t

Captured NNI cell.

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.

typedef struct libtrace_atm_nni_cell libtrace_atm_nni_cell_t

ATM Network Node/Network Interface (NNI) Cell.

typedef struct callback_set libtrace_callback_set_t

Opaque structure holding callback functions for libtrace threads.

typedef struct trace_err_t libtrace_err_t

Libtrace error information.

typedef struct libtrace_ether libtrace_ether_t

802.3 frame

typedef struct libtrace_eventobj_t libtrace_eventobj_t

Structure returned by libtrace_event explaining what the current event is.

typedef struct libtrace_filter_t libtrace_filter_t

Opaque structure holding information about a bpf filter.

typedef struct libtrace_gre_t libtrace_gre_t

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

typedef struct libtrace_icmp6 libtrace_icmp6_t

Generic ICMPv6 header structure.

typedef struct libtrace_icmp libtrace_icmp_t

Generic ICMP header structure.

typedef struct libtrace_ip6_ext libtrace_ip6_ext_t

IPv6 header extension structure.

typedef struct libtrace_ip6_frag libtrace_ip6_frag_t

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.

typedef struct libtrace_llcsnap libtrace_llcsnap_t

Generic LLC/SNAP header structure.

typedef struct libtrace_ospf_as_external_lsa_t libtrace_ospf_as_external_lsa_v2_t

OSPFv2 AS External LSA Body.

typedef struct libtrace_ospf_db_desc_v2_t libtrace_ospf_db_desc_v2_t

OSPFv2 Database Description packet.

typedef struct libtrace_ospf_hello_v2_t libtrace_ospf_hello_v2_t

OSPFv2 Hello Packet.

typedef struct libtrace_ospf_link_t libtrace_ospf_link_v2_t

OSPFv2 Router Link structure.

typedef struct libtrace_ospf_ls_req_t libtrace_ospf_ls_req_t

OSPF Link State Request Packet.

typedef struct libtrace_ospf_ls_update_t libtrace_ospf_ls_update_t

OSPF Link State Update Packet.

typedef struct libtrace_ospf_lsa_v2_t libtrace_ospf_lsa_v2_t

LSA Header for OSPFv2.

typedef struct libtrace_ospf_network_lsa_t libtrace_ospf_network_lsa_v2_t

OSPFv2 Network LSA Body.

typedef struct libtrace_ospf_options_t libtrace_ospf_options_t

Options Field present in some OSPFv2 packets.

typedef struct libtrace_ospf_router_lsa_t libtrace_ospf_router_lsa_v2_t

OSPFv2 Router LSA.

typedef struct libtrace_ospf_summary_lsa libtrace_ospf_summary_lsa_v2_t

OSPFv2 Summary LSA Body.

typedef struct libtrace_ospf_v2_t libtrace_ospf_v2_t

OSPF header.

typedef struct libtrace_out_t libtrace_out_t

Opaque structure holding information about an output trace.

typedef struct libtrace_packet_t libtrace_packet_t

The libtrace packet structure.

Applications shouldn't be meddling around in here

typedef struct libtrace_ppp libtrace_ppp_t

PPP header.

typedef struct libtrace_pppoe libtrace_pppoe_t

PPPoE header.

typedef struct libtrace_radiotap_t libtrace_radiotap_t

The Radiotap header pre-amble.

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

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

typedef struct libtrace_sll_header_t libtrace_sll_header_t

A local definition of an SLL header.

typedef struct libtrace_stat_t libtrace_stat_t

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.

typedef struct libtrace_thread_t libtrace_thread_t

Opaque structure holding information about libtrace thread.

typedef struct libtrace_udp libtrace_udp_t

Generic UDP header structure.

typedef struct libtrace_vxlan_t libtrace_vxlan_t

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 occured.... yet.
TRACE_ERR_BAD_FORMAT	The URI passed to trace_create() is unsupported, or badly formed.
TRACE_ERR_INIT_FAILED	The trace failed to initialise.
TRACE_ERR_UNKNOWN_OPTION	Unknown config option.
TRACE_ERR_NO_CONVERSION	This output uri cannot write packets of this type.
TRACE_ERR_BAD_PACKET	This packet is corrupt, or unusable for the action required.
TRACE_ERR_OPTION_UNAVAIL	Option known, but unsupported by this format.
TRACE_ERR_UNSUPPORTED	This feature is unsupported.
TRACE_ERR_BAD_STATE	Illegal use of the API.
TRACE_ERR_BAD_FILTER	Failed to compile a BPF filter.
TRACE_ERR_RT_FAILURE	RT communication breakdown.
TRACE_ERR_UNSUPPORTED_COMPRESS	Compression format unsupported.

enum base_format_t

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.

enum buf_control_t

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

enum libtrace_direction_t

Trace directions.

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

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.

enum libtrace_dlt_t

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 explainations of pain.
TRACE_DLT_IEEE802_11_RADIO	Radiotap.

enum libtrace_ethertype_t

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.

enum libtrace_event_t

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.

enum libtrace_ipproto_t

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.

enum libtrace_linktype_t

Enumeration of link layer types supported by libtrace.

Enumerator:

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.

enum libtrace_ospf_ls_types_t

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.

enum libtrace_ospf_types_t

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.

enum libtrace_radiotap_field_t

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 attenutation as dB from max power (uint16).
TRACE_RADIOTAP_DBM_TX_POWER	TX Power in dBm (int8).
TRACE_RADIOTAP_ANTENNA	Antenna frame was rx'd or tx'd on (uint8).
TRACE_RADIOTAP_DB_ANTSIGNAL	Signal power in dB from a fixed reference (uint8).
TRACE_RADIOTAP_DB_ANTNOISE	Noise power in dB from a fixed reference (uint8).
TRACE_RADIOTAP_TX_FLAGS	Properties of received frame (uint16).
TRACE_RADIOTAP_RTS_RETRIES	Properties of transmitted frame (uint16).
TRACE_RADIOTAP_DATA_RETRIES	Number of rts retries frame used (uint8).
TRACE_RADIOTAP_EXT	Number of unicast retries a transmitted frame used (uint8).

enum libtrace_rt_types_t

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

enum serverport_t

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.

enum trace_option_compresstype_t

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.

enum trace_option_output_t

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.

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

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:

	a	The first operand
	b	The second operand
	c	The result

References LIBTRACE_STAT_FIELDS, libtrace_stat_t::magic, and trace_add_statistics().

Referenced by trace_add_statistics().

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

Apply a BPF filter to a packet.

Parameters:

	filter	The filter to be applied
	packet	The 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_apply_filter(), trace_copy_packet(), trace_destroy_packet(), TRACE_ERR_NO_CONVERSION, trace_get_link_type(), trace_get_packet_buffer(), trace_set_err(), and TRACE_TYPE_NONDATA.

Referenced by trace_apply_filter(), and 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:

	packet	The libtrace packet to calculate the checksum for
`[out]`	csum	The 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_checksum_layer3(), TRACE_ETHERTYPE_IP, and trace_get_layer3().

Referenced by trace_checksum_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:

	packet	The libtrace packet to calculate the checksum for
`[out]`	csum	The 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_udp::check, libtrace_tcp::check, libtrace_icmp::checksum, libtrace_tcp::doff, trace_checksum_transport(), 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.

Referenced by trace_checksum_transport().

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

Sets an input config option.

Parameters:

	libtrace	The trace object to apply the option to
	option	The option to set
	value	The value to set the option to

Returns:: -1 if option configuration failed, 0 otherwise

This should be called after trace_create(), and before trace_start()

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::snaplen, trace_config(), 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_SNAPLEN, trace_set_err(), and trace_set_hasher().

Referenced by trace_config(), 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:

	libtrace	The output trace object to apply the option to
	option	The option to set
	value	The value to set the option to

Returns:: -1 if option configuration failed, 0 otherwise This should be called after trace_create_output, and before trace_start_output

References libtrace_format_t::config_output, libtrace_out_t::format, and trace_config_output().

Referenced by trace_config_output().

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]`	packet	Libtrace Packet object to update with the new data.
	linktype	The linktype of the packet data.
`[in]`	data	The packet data (including linklayer).
	len	Length 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_to_pcap_linktype(), libtrace_packet_t::payload, pcap_linktype_to_rt(), libtrace_packet_t::trace, trace_clear_cache(), trace_construct_packet(), trace_create_dead(), TRACE_CTRL_PACKET, and libtrace_packet_t::type.

Referenced by trace_construct_packet().

DLLEXPORT libtrace_packet_t* trace_copy_packet ( const libtrace_packet_t * packet )

Copy a packet object.

Parameters:

packet

The source packet to copy

Returns:: A new packet which has the same content as the source packet

Note:: This always involves a copy, which can be slow. Use of this function should be avoided where possible.

The reason you would want to use this function is that a zerocopied: packet from a device 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_packet_t::trace, trace_clear_cache(), trace_copy_packet(), trace_get_capture_length(), trace_get_framing_length(), and libtrace_packet_t::type.

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

DLLEXPORT libtrace_t* trace_create ( const char * uri )

Create an input trace from a URI.

Parameters:

uri

A 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 occured 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 occured. 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::sequence_number, libtrace_t::snaplen, libtrace_t::started, libtrace_t::state, strncasecmp(), libtrace_event_status_t::tdelta, trace_create(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_UNSUPPORTED, libtrace_event_status_t::trace_last_ts, trace_parse_uri(), trace_set_err(), libtrace_t::uridata, and libtrace_event_status_t::waiting.

Referenced by trace_create().

DLLEXPORT libtrace_t* trace_create_dead ( const char * uri )

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

Parameters:

uri

A 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::sequence_number, libtrace_t::snaplen, libtrace_t::started, libtrace_t::state, strncasecmp(), libtrace_event_status_t::tdelta, trace_create_dead(), TRACE_ERR_BAD_FORMAT, libtrace_event_status_t::trace_last_ts, trace_set_err(), and libtrace_t::uridata.

Referenced by demote_packet(), trace_construct_packet(), and trace_create_dead().

DLLEXPORT SIMPLE_FUNCTION libtrace_filter_t* trace_create_filter ( const char * filterstring )

Creates a BPF filter.

Parameters:

filterstring

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

References trace_create_filter().

Referenced by trace_create_filter().

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_insns	A pointer to the start of the byte-code
	bf_len	The number of BPF instructions

Returns:: An opaque pointer to a libtrace_filter_t object

Note:: The supplied byte-code is not checked for correctness. 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_insns	A pointer to the start of the byte-code
	bf_len	The number of BPF instructions

Returns:: an opaque pointer to a libtrace_filter_t object

Note:: The supplied byte-code is not checked for correctness.

Author:: Scott Raynel

References trace_create_filter_from_bytecode().

Referenced by trace_create_filter_from_bytecode().

DLLEXPORT libtrace_out_t* trace_create_output ( const char * uri )

Creates a trace output file from a URI.

Parameters:

uri

The 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 occured 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_create_output(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_UNSUPPORTED, trace_parse_uri(), trace_set_err_out(), and libtrace_out_t::uridata.

Referenced by trace_create_output().

DLLEXPORT libtrace_packet_t* trace_create_packet ( void )

Create a new packet object.

Returns:: A pointer to an initialised libtrace_packet_t object

References libtrace_packet_t::buf_control, trace_clear_cache(), and trace_create_packet().

Referenced by trace_create_packet(), 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, and trace_create_statistics().

Referenced by trace_create_statistics(), trace_get_statistics(), and trace_ppause().

DLLEXPORT void trace_destroy ( libtrace_t * trace )

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

Parameters:

trace

The input trace to be destroyed

References ASSERT_RET, libtrace_combine::destroy, libtrace_t::event, libtrace_format_t::fin_input, libtrace_t::format, libtrace_t::last_packet, libtrace_t::libtrace_lock, libtrace_event_status_t::packet, libtrace_t::packet_freelist, libtrace_format_t::pause_input, libtrace_t::perpkt_cond, libtrace_t::started, libtrace_t::state, trace_destroy(), trace_destroy_callback_set(), trace_destroy_packet(), trace_fin_packet(), and libtrace_t::uridata.

Referenced by trace_destroy().

DLLEXPORT void trace_destroy_dead ( libtrace_t * trace )

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

Parameters:

trace

The dummy trace to be destroyed

References ASSERT_RET, libtrace_t::format_data, libtrace_t::libtrace_lock, libtrace_t::perpkt_cond, and trace_destroy_dead().

Referenced by trace_destroy_dead().

DLLEXPORT void trace_destroy_filter ( libtrace_filter_t * filter )

Destroy a BPF filter.

Parameters:

filter

The filter to be destroyed

Deallocates all the resources associated with a BPF filter.

References trace_destroy_filter().

Referenced by trace_destroy_filter().

DLLEXPORT void trace_destroy_output ( libtrace_out_t * trace )

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

Parameters:

trace

The output trace to be destroyed

References libtrace_format_t::fin_output, libtrace_out_t::format, trace_destroy_output(), and libtrace_out_t::uridata.

Referenced by trace_destroy_output().

DLLEXPORT void trace_destroy_packet ( libtrace_packet_t * packet )

Destroy a packet object.

Parameters:

packet

The packet to be destroyed

References libtrace_packet_t::buf_control, libtrace_packet_t::buffer, libtrace_format_t::fin_packet, libtrace_t::format, libtrace_t::last_packet, libtrace_packet_t::trace, TRACE_CTRL_PACKET, and trace_destroy_packet().

Referenced by trace_apply_filter(), trace_destroy(), trace_destroy_packet(), trace_event_trace(), trace_join(), and trace_pstart().

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

Convert a string to an ethernet address.

Parameters:

	buf	A string containing an Ethernet address in hex format delimited with :'s.
	addr	Buffer 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.

References trace_ether_aton().

Referenced by trace_ether_aton().

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

Converts an ethernet address to a printable string.

Parameters:

	addr	Ethernet address in network byte order
	buf	Buffer 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(), and trace_ether_ntoa().

Referenced by trace_ether_ntoa().

DLLEXPORT libtrace_eventobj_t trace_event	(	libtrace_t *	trace,
		libtrace_packet_t *	packet
	)

Processes the next libtrace event from an input trace.

Parameters:

	trace	The libtrace opaque pointer for the input trace
	packet	The 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(), and trace_fin_packet().

Referenced by register_format(), and trace_event().

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:

trace

The 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, and trace_get_accepted_packets().

Referenced by trace_get_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:

packet

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

Referenced by demote_packet(), promote_packet(), trace_copy_packet(), trace_get_capture_length(), 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
	)			`[read]`

Get the destination IP address for a given packet.

Parameters:

	packet	The packet to extract the destination IP address from
	addr	A 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_ip6::ip_dst, libtrace_ip::ip_dst, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_destination_address(), trace_get_layer3(), trace_get_payload_from_ip(), and trace_get_payload_from_ip6().

Referenced by trace_get_destination_address(), and 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:

	packet	The packet to extract the destination IP address from
	space	A pointer to a character buffer to store the address in. If NULL, static storage is used instead.
	spacelen	The 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(), and trace_get_destination_address_string().

Referenced by trace_get_destination_address_string().

DLLEXPORT SIMPLE_FUNCTION uint8_t* trace_get_destination_mac ( libtrace_packet_t * packet )

Gets the destination MAC address for a given packet.

Parameters:

packet

The 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_destination_mac(), trace_get_layer2(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_destination_mac().

DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_destination_port ( const libtrace_packet_t * packet )

Gets the destination port for a given packet.

Parameters:

packet

The 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_destination_port(), trace_get_fragment_offset(), trace_get_transport(), TRACE_IPPROTO_ICMP, and TRACE_IPPROTO_ICMPV6.

Referenced by trace_get_destination_port().

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:

packet

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

Referenced by trace_get_direction().

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:

trace

The 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_dropped_packets(), trace_get_statistics(), and UINT64_MAX.

Referenced by trace_get_dropped_packets().

DLLEXPORT SIMPLE_FUNCTION uint64_t trace_get_erf_timestamp ( const libtrace_packet_t * packet )

Get the packet timestamp in the DAG time format.

Parameters:

packet

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

Referenced by trace_get_erf_timestamp().

DLLEXPORT libtrace_err_t trace_get_err ( libtrace_t * trace )

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

Parameters:

trace

The 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, trace_err_t::problem, and trace_get_err().

Referenced by trace_config(), and trace_get_err().

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:

trace

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

Referenced by trace_get_err_output().

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:

trace

The 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_filtered_packets(), trace_get_statistics(), and UINT64_MAX.

Referenced by trace_get_filtered_packets().

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:

	lsa	Pointer to the Router LSA
`[in,out]`	remaining	Updated 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 subequently used to process the links

References trace_get_first_ospf_link_from_router_lsa_v2().

Referenced by trace_get_first_ospf_link_from_router_lsa_v2().

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_desc	Pointer to the Database Description header
`[in,out]`	remaining	Updated 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 subequently used to process the LSA headers

References trace_get_first_ospf_lsa_from_db_desc_v2().

Referenced by trace_get_first_ospf_lsa_from_db_desc_v2().

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_update	Pointer to the LS Update header
`[in,out]`	remaining	Updated 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 subequently used to process the LSAs

References trace_get_first_ospf_lsa_from_update_v2().

Referenced by trace_get_first_ospf_lsa_from_update_v2().

DLLEXPORT enum base_format_t trace_get_format ( struct libtrace_packet_t * packet )

Gets the capture format for a given packet.

Parameters:

packet

The 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, trace_get_format(), and libtrace_format_t::type.

Referenced by trace_get_format().

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:

	packet	The libtrace packet to calculate the offset for
`[out]`	more	A 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_fragment_offset(), trace_get_layer3(), TRACE_IPPROTO_AH, TRACE_IPPROTO_DSTOPTS, TRACE_IPPROTO_FRAGMENT, and TRACE_IPPROTO_ROUTING.

Referenced by trace_get_destination_port(), trace_get_fragment_offset(), 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:

packet

The 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_format_t::get_framing_length, libtrace_packet_t::trace, and trace_get_framing_length().

Referenced by promote_packet(), trace_copy_packet(), and trace_get_framing_length().

DLLEXPORT SIMPLE_FUNCTION libtrace_icmp_t* trace_get_icmp ( libtrace_packet_t * packet )

Get a pointer to the ICMP header (if present).

Parameters:

packet

The 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_icmp(), trace_get_transport(), and TRACE_IPPROTO_ICMP.

Referenced by trace_get_icmp().

DLLEXPORT SIMPLE_FUNCTION libtrace_icmp6_t* trace_get_icmp6 ( libtrace_packet_t * packet )

Get a pointer to the ICMPv6 header (if present).

Parameters:

packet

The 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_icmp6(), trace_get_transport(), and TRACE_IPPROTO_ICMPV6.

Referenced by trace_get_icmp6().

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:

	ip	The IP header to find the subsequent ICMP header for
`[in,out]`	remaining	Updated 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_icmp_from_ip(), trace_get_payload_from_ip(), and TRACE_IPPROTO_ICMP.

Referenced by trace_get_icmp_from_ip().

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:

packet

The 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(), trace_get_ip(), and trace_get_layer3().

Referenced by trace_get_ip().

DLLEXPORT SIMPLE_FUNCTION libtrace_ip6_t* trace_get_ip6 ( libtrace_packet_t * packet )

get a pointer to the IPv6 header (if any)

Parameters:

packet

The 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(), trace_get_ip6(), and trace_get_layer3().

Referenced by trace_get_ip6().

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:

	packet	The libtrace packet to find the layer 2 header for
`[out]`	linktype	The linktype of the returned layer 2 header
`[out]`	remaining	The 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_layer2(), 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_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_destination_mac(), trace_get_layer2(), 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:

	packet	The libtrace packet to find the layer 3 header for
`[out]`	ethertype	The ethertype of the layer 3 header
`[out]`	remaining	The 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_layer3(), 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_layer3(), 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:

packet

The 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, and trace_get_link().

Referenced by trace_get_link().

DLLEXPORT SIMPLE_FUNCTION libtrace_linktype_t trace_get_link_type ( const libtrace_packet_t * packet )

Gets the link layer type for a packet.

Parameters:

packet

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

Referenced by demote_packet(), trace_apply_filter(), trace_get_link_type(), 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]`	ptr	The pointer to the current option
`[in,out]`	len	The total length of all the remaining options
`[out]`	type	The type of the option
`[out]`	optlen	The length of the option
`[out]`	data	The 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.

References trace_get_next_option().

Referenced by trace_get_next_option().

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]`	current	Pointer to the next Link (updated by this function)
`[out]`	link	Set to point to the Link located at the original value of current
`[in,out]`	remaining	Updated with the number of captured bytes remaining
`[out]`	link_len	Set 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.

References trace_get_next_ospf_link_v2().

Referenced by trace_get_next_ospf_link_v2().

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]`	current	Pointer to the next LSA (updated by this function)
`[out]`	lsa_hdr	Set to point to the header of the LSA located at the original value of current
`[in,out]`	remaining	Updated with the number of captured bytes remaining
`[out]`	lsa_length	Set 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_get_next_ospf_lsa_header_v2(), TRACE_OSPF_LS_ASBR_SUMMARY, TRACE_OSPF_LS_EXTERNAL, TRACE_OSPF_LS_NETWORK, TRACE_OSPF_LS_ROUTER, and TRACE_OSPF_LS_SUMMARY.

Referenced by trace_get_next_ospf_lsa_header_v2().

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]`	current	Pointer to the next LSA (updated by this function)
`[out]`	lsa_hdr	Set to point to the header of the LSA located at the original value of current
`[out]`	lsa_body	Set to point to the body of the LSA located at the original value of current
`[in,out]`	remaining	Updated with the number of captured bytes remaining
`[out]`	lsa_type	Set to the type of the LSA located at the original value of current
`[out]`	lsa_length	Set 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_get_next_ospf_lsa_v2(), TRACE_OSPF_LS_ASBR_SUMMARY, TRACE_OSPF_LS_EXTERNAL, TRACE_OSPF_LS_NETWORK, TRACE_OSPF_LS_ROUTER, and TRACE_OSPF_LS_SUMMARY.

Referenced by trace_get_next_ospf_lsa_v2().

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:

	header	The OSPF header to get the OSPF contents from
`[out]`	ospf_type	The OSPF packet type
`[in,out]`	remaining	Updated 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 trace_get_ospf_contents_v2(), and libtrace_ospf_v2_t::type.

Referenced by trace_get_ospf_contents_v2().

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:

	packet	The packet to get the OSPF header from
`[out]`	version	The OSPF version number
`[out]`	remaining	Updated 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_ospf_header(), trace_get_transport(), and TRACE_IPPROTO_OSPF.

Referenced by trace_get_ospf_header().

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_lsa

The 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, libtrace_ospf_as_external_lsa_t::metric_c, and trace_get_ospf_metric_from_as_external_lsa_v2().

Referenced by trace_get_ospf_metric_from_as_external_lsa_v2().

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_lsa

The 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, libtrace_ospf_summary_lsa::metric_c, and trace_get_ospf_metric_from_summary_lsa_v2().

Referenced by trace_get_ospf_metric_from_summary_lsa_v2().

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:

	packet	The packet to get the buffer from
`[out]`	linktype	The linktype of the returned pointer
`[out]`	remaining	The 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_packet_buffer(), and trace_get_wire_length().

Referenced by trace_apply_filter(), trace_get_layer2(), trace_get_packet_buffer(), and trace_get_packet_meta().

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:

	packet	The libtrace packet
`[out]`	linktype	The linktype of the returned metadata header
`[out]`	remaining	The 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_get_packet_meta(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_packet_meta().

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:

	gre	A pointer to the beginning of the GRE header.
`[in,out]`	remaining	Updated 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, and trace_get_payload_from_gre().

Referenced by trace_get_payload_from_gre().

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:

	icmp	A pointer to the ICMP header
`[in,out]`	remaining	Updated 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.

References trace_get_payload_from_icmp().

Referenced by trace_checksum_transport(), and trace_get_payload_from_icmp().

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:

	icmp	A pointer to the ICMPv6 header
`[in,out]`	remaining	Updated 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.

References trace_get_payload_from_icmp6().

Referenced by trace_get_payload_from_icmp6().

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:

	ip	The IPv4 Header
`[out]`	proto	The protocol of the header following the IPv4 header
`[in,out]`	remaining	Updated 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, libtrace_ip::ip_v, and trace_get_payload_from_ip().

Referenced by trace_get_destination_address(), trace_get_icmp_from_ip(), trace_get_payload_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:

	ipptr	The IPv6 Header
`[out]`	proto	The protocol of the header following the IPv6 header
`[in,out]`	remaining	Updated 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_get_payload_from_ip6(), TRACE_IPPROTO_AH, TRACE_IPPROTO_DSTOPTS, TRACE_IPPROTO_ESP, TRACE_IPPROTO_FRAGMENT, and TRACE_IPPROTO_ROUTING.

Referenced by trace_get_destination_address(), trace_get_payload_from_ip6(), 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:

	l2	The pointer to the current layer 2 header
	linktype	The type of the layer 2 header
`[out]`	ethertype	An optional output variable of the ethernet type of the new header
`[in,out]`	remaining	Updated 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_get_payload_from_atm(), trace_get_payload_from_ethernet(), trace_get_payload_from_layer2(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_layer3(), trace_get_payload_from_layer2(), 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:

	linkptr	A pointer to the link layer header
	linktype	The linktype of the link header being examined
`[out]`	type	An output variable for the ethernet type
`[in,out]`	remaining	Updated 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(), trace_get_payload_from_link(), and trace_get_payload_from_meta().

Referenced by trace_get_payload_from_link().

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]`	meta	A pointer to a metadata header
`[in,out]`	linktype	The linktype of meta (updated to indicate the linktype of the returned header if applicable).
`[in,out]`	remaining	The 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_get_payload_from_meta(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_layer2(), trace_get_payload_from_link(), and trace_get_payload_from_meta().

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:

	mpls	A pointer to the MPLS header
`[out]`	type	The ethernet type, replaced by the ether type of the returned header - 0x0000 if an Ethernet header is returned
`[in,out]`	remaining	Updated 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_get_payload_from_mpls().

Referenced by trace_get_layer3(), trace_get_payload_from_mpls(), 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:

	pppoe	A pointer to the PPPoE header
`[out]`	type	The ethernet type, replaced by the ether type of the returned header - 0x0000 if an Ethernet header is returned
`[in,out]`	remaining	Updated 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.

References trace_get_payload_from_pppoe().

Referenced by trace_get_layer3(), trace_get_payload_from_pppoe(), 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:

	tcp	A pointer to the TCP header
`[in,out]`	remaining	Updated 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, and trace_get_payload_from_tcp().

Referenced by trace_checksum_transport(), and trace_get_payload_from_tcp().

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:

	udp	A pointer to the UDP header
`[in,out]`	remaining	Updated 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.

References trace_get_payload_from_udp().

Referenced by trace_checksum_transport(), trace_get_payload_from_udp(), 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:

	vlan	A pointer to the VLAN header
`[out]`	type	The ethernet type, replaced with the VLAN ether type
`[in,out]`	remaining	Updated 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 trace_get_payload_from_vlan(), and libtrace_8021q::vlan_ether_type.

Referenced by trace_get_layer3(), trace_get_payload_from_vlan(), 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:

	vxlan	A pointer to the beginning of the VXLAN header.
`[in,out]`	remaining	Updated 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.

References trace_get_payload_from_vxlan().

Referenced by trace_get_payload_from_vxlan().

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:

packet

The 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_payload_length(), trace_get_transport(), TRACE_IPPROTO_ICMP, TRACE_IPPROTO_ICMPV6, TRACE_IPPROTO_IPV6, TRACE_IPPROTO_TCP, and TRACE_IPPROTO_UDP.

Referenced by trace_checksum_transport(), and trace_get_payload_length().

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:

trace

The 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_received_packets(), trace_get_statistics(), and UINT64_MAX.

Referenced by trace_get_received_packets().

DLLEXPORT SIMPLE_FUNCTION double trace_get_seconds ( const libtrace_packet_t * packet )

Get the packet timestamp in floating point seconds.

Parameters:

packet

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

Referenced by store_first_packet(), trace_event_trace(), and trace_get_seconds().

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:

	protocol	The IP layer protocol, eg 6 (tcp), 17 (udp)
	source	The source port from the packet
	dest	The 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
	)			`[read]`

Get the source IP address for a given packet.

Parameters:

	packet	The packet to extract the source IP address from
	addr	A 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_ip6::ip_src, libtrace_ip::ip_src, ports_t::src, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_ip(), trace_get_payload_from_ip6(), and trace_get_source_address().

Referenced by trace_get_source_address(), and 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:

	packet	The packet to extract the source IP address from
	space	A pointer to a character buffer to store the address in. If NULL, static storage is used instead.
	spacelen	The 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(), and trace_get_source_address_string().

Referenced by trace_get_source_address_string().

DLLEXPORT SIMPLE_FUNCTION uint8_t* trace_get_source_mac ( libtrace_packet_t * packet )

Gets the source MAC address for a given packet.

Parameters:

packet

The 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_get_source_mac(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_DUCK, TRACE_TYPE_ETH, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.

Referenced by trace_get_source_mac().

DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_source_port ( const libtrace_packet_t * packet )

Gets the source port for a given packet.

Parameters:

packet

The 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_source_port(), trace_get_transport(), TRACE_IPPROTO_ICMP, and TRACE_IPPROTO_ICMPV6.

Referenced by trace_get_source_port().

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 retrived atomically, however this behaviour depends on the underlying trace format.

Parameters:

	trace	The input trace to examine.
	stats	Optional, 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_t::magic, libtrace_stat_t::reserved1, libtrace_stat_t::reserved2, libtrace_t::state, trace_create_statistics(), and trace_get_statistics().

Referenced by trace_get_dropped_packets(), trace_get_filtered_packets(), trace_get_received_packets(), trace_get_statistics(), 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:

packet

The 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_tcp(), trace_get_transport(), and TRACE_IPPROTO_TCP.

Referenced by trace_get_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:

	ip	The IP header to find the subsequent TCP header for
`[in,out]`	remaining	Updated 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(), trace_get_tcp_from_ip(), and TRACE_IPPROTO_TCP.

Referenced by trace_get_tcp_from_ip().

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 retrived atomically, however this behaviour depends on the underlying trace format.

Parameters:

	trace	The input trace to examine.
	t	An optional thread to received stats for or NULL to retrive stats for the current thread
	stats	Filled 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_t::magic, libtrace_stat_t::reserved1, libtrace_stat_t::reserved2, trace_get_thread_statistics(), and trace_has_dedicated_hasher().

Referenced by trace_get_thread_statistics().

DLLEXPORT SIMPLE_FUNCTION struct timespec trace_get_timespec ( const libtrace_packet_t * packet ) [read]

Get the packet timestamp as a struct timespec.

Parameters:

packet

The packet to extract the timestamp from

Returns:: The time that this packet was captured in a struct timespec

References trace_get_timespec().

Referenced by trace_get_timespec().

DLLEXPORT SIMPLE_FUNCTION struct timeval trace_get_timeval ( const libtrace_packet_t * packet ) [read]

Get the packet timestamp as a struct timeval.

Parameters:

packet

The packet to extract the timestamp from

Returns:: The time that this packet was captured in a struct timeval

References trace_get_timeval().

Referenced by demote_packet(), and trace_get_timeval().

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:

	packet	The libtrace packet to find the transport header for
`[out]`	proto	The protocol present at the transport layer.
`[out]`	remaining	The 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_get_transport(), 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(), trace_get_transport(), 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:

packet

The 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(), trace_get_udp(), and TRACE_IPPROTO_UDP.

Referenced by trace_get_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:

	ip	The IP header to find the subsequent UDP header for
`[in,out]`	remaining	Updated 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(), trace_get_udp_from_ip(), and TRACE_IPPROTO_UDP.

Referenced by trace_get_udp_from_ip().

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:

	udp	A pointer to the beginning of the UDP header.
`[in,out]`	remaining	Updated 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, trace_get_payload_from_udp(), and trace_get_vxlan_from_udp().

Referenced by trace_get_vxlan_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:

packet

The 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_packet_t::trace, trace_get_wire_length(), and libtrace_packet_t::wire_length.

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

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

Get the wireless antenna.

Parameters:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	antenna	The 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_get_wireless_antenna(), TRACE_RADIOTAP_ANTENNA, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_antenna().

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

Get the wireless channel frequency.

Parameters:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	freq	The 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_get_wireless_freq(), TRACE_RADIOTAP_CHANNEL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_freq().

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:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	strength	The 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_get_wireless_noise_strength_db(), TRACE_RADIOTAP_DB_ANTNOISE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_noise_strength_db().

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:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	strength	The 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_get_wireless_noise_strength_dbm(), TRACE_RADIOTAP_DBM_ANTNOISE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_noise_strength_dbm().

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

Get the wireless data rate.

Parameters:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	rate	The 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_get_wireless_rate(), TRACE_RADIOTAP_RATE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_rate().

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:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	strength	The 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_get_wireless_signal_strength_db(), TRACE_RADIOTAP_DB_ANTSIGNAL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_signal_strength_db().

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:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	strength	The 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_get_wireless_signal_strength_dbm(), TRACE_RADIOTAP_DBM_ANTSIGNAL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_signal_strength_dbm().

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:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	tsft	The 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_get_wireless_tsft(), TRACE_RADIOTAP_TSFT, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_tsft().

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

Get the wireless transmit attenuation.

Parameters:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	attenuation	The 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_get_wireless_tx_attenuation(), TRACE_RADIOTAP_TX_ATTENUATION, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_tx_attenuation().

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

Get the wireless transmit attenuation in dB.

Parameters:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	attenuation	The 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_get_wireless_tx_attenuation_db(), TRACE_RADIOTAP_DB_TX_ATTENUATION, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_tx_attenuation_db().

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

Get the wireless transmit power in dBm.

Parameters:

	linkptr	The wireless meta header
	linktype	The linktype of the wireless meta header passed in
`[out]`	txpower	The 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_get_wireless_tx_power_dbm(), TRACE_RADIOTAP_DBM_TX_POWER, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.

Referenced by trace_get_wireless_tx_power_dbm().

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, libtrace_format_t::next, and trace_help().

Referenced by trace_help().

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, and trace_interrupt().

Referenced by trace_interrupt().

DLLEXPORT bool trace_is_err ( libtrace_t * trace )

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

Parameters:

trace

The 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, trace_err_t::err_num, and trace_is_err().

Referenced by trace_config(), trace_event_device(), trace_event_trace(), trace_is_err(), 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:

trace

The 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, trace_err_t::err_num, and trace_is_err_output().

Referenced by trace_is_err_output().

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

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

Parameters:

	uri	The uri to be parsed
`[out]`	format	A pointer that will be updated to point to an allocated string holding the format component of the URI

Returns:: NULL if an error occured, 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.

References trace_parse_uri().

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

DLLEXPORT int trace_pause ( libtrace_t * libtrace )

Pauses an input trace.

Parameters:

libtrace

The 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(), trace_pause(), and trace_set_err().

Referenced by trace_pause(), and 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:

	trace	The input trace with the error to output
	msg	The 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:

	trace	The output trace with the error to output
	msg	The message to prepend to the error This function does clear the error status.

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:

	s	The statistic structure to print
	f	The output file stream
	format	An 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, libtrace_stat_t::magic, and trace_print_statistics().

Referenced by trace_print_statistics().

DLLEXPORT int trace_read_packet	(	libtrace_t *	trace,
		libtrace_packet_t *	packet
	)

Read the next packet from an input trace.

Parameters:

	trace	The libtrace opaque pointer for the input trace
	packet	The 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_format_t::read_packet, libtrace_t::sequence_number, libtrace_t::snaplen, 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_read_packet(), trace_set_capture_length(), and trace_set_err().

Referenced by trace_event_device(), trace_event_trace(), and trace_read_packet().

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:

	trace	The input trace to seek within
	ts	The 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, trace_seek_erf_timestamp(), and trace_set_err().

Referenced by trace_seek_erf_timestamp().

DLLEXPORT int trace_seek_seconds	(	libtrace_t *	trace,
		double	seconds
	)

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

Parameters:

	trace	The input trace to seek within
	seconds	The 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, trace_seek_seconds(), and trace_set_err().

Referenced by trace_seek_seconds().

DLLEXPORT int trace_seek_timeval	(	libtrace_t *	trace,
		struct timeval	tv
	)

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

Parameters:

	trace	The input trace to seek within
	tv	The 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, trace_seek_timeval(), and trace_set_err().

Referenced by trace_seek_timeval().

DLLEXPORT size_t trace_set_capture_length	(	libtrace_packet_t *	packet,
		size_t	size
	)

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

Parameters:

	packet	The packet to truncate
	size	The 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, libtrace_packet_t::trace, and trace_set_capture_length().

Referenced by demote_packet(), trace_read_packet(), trace_set_capture_length(), 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:

	packet	The packet to set the direction for
	direction	The 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, libtrace_packet_t::trace, and trace_set_direction().

Referenced by trace_set_direction().

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:

	libtrace	The trace object to apply the option to
	realtime	True ignores gaps

Returns:: -1 if option configuration failed, 0 otherwise

References trace_config(), TRACE_OPTION_EVENT_REALTIME, and trace_set_event_realtime().

Referenced by trace_set_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:

	libtrace	The trace object to apply the option to
	filter	The filter to apply

Returns:: -1 if option configuration failed, 0 otherwise

References trace_config(), TRACE_OPTION_FILTER, and trace_set_filter().

Referenced by trace_set_filter().

DLLEXPORT int trace_set_meta_freq	(	libtrace_t *	trace,
		int	freq
	)

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

DUCK packets

Parameters:

	libtrace	The trace object to apply the option to
	freq	The meta data frequency

Returns:: -1 if option configuration failed, 0 otherwise

References trace_config(), TRACE_OPTION_META_FREQ, and trace_set_meta_freq().

Referenced by trace_set_meta_freq().

DLLEXPORT int trace_set_promisc	(	libtrace_t *	trace,
		bool	promisc
	)

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

Parameters:

	libtrace	The trace object to apply the option to
	promisc

Returns:: -1 if option configuration failed, 0 otherwise

References trace_config(), TRACE_OPTION_PROMISC, and trace_set_promisc().

Referenced by trace_set_promisc().

DLLEXPORT int trace_set_snaplen	(	libtrace_t *	trace,
		int	snaplen
	)

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

Parameters:

	libtrace	The trace object to apply the option to
	snaplen	The snap length to set

Returns:: -1 if option configuration failed, 0 otherwise

References trace_config(), TRACE_OPTION_SNAPLEN, and trace_set_snaplen().

Referenced by trace_set_snaplen().

DLLEXPORT int trace_start ( libtrace_t * libtrace )

Start an input trace.

Parameters:

libtrace

The 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::started, trace_is_err(), and trace_start().

Referenced by trace_start().

DLLEXPORT int trace_start_output ( libtrace_out_t * libtrace )

Start an output trace.

Parameters:

libtrace

The 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, libtrace_out_t::started, and trace_start_output().

Referenced by trace_start_output().

DLLEXPORT libtrace_packet_t* trace_strip_packet ( libtrace_packet_t * packet )

Strips layer 2.5 headers from a given packet.

Parameters:

packet

The 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(), trace_strip_packet(), and TRACE_TYPE_ETH.

Referenced by trace_strip_packet().

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:

	a	The minuend
	b	The subtrahend
	c	The resulting difference

References LIBTRACE_STAT_FIELDS, libtrace_stat_t::magic, and trace_subtract_statistics().

Referenced by trace_subtract_statistics().

DLLEXPORT int trace_write_packet	(	libtrace_out_t *	trace,
		libtrace_packet_t *	packet
	)

Write one packet out to the output trace.

Parameters:

	trace	The libtrace_out opaque pointer for the output trace
	packet	The 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_out_t::format, libtrace_out_t::started, TRACE_ERR_BAD_STATE, TRACE_ERR_UNSUPPORTED, trace_set_err_out(), trace_write_packet(), and libtrace_format_t::write_packet.

Referenced by trace_write_packet().

libtrace.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Protocol structures

Trace management

Wireless trace support

Reading / Writing packets

Ports

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation