Trace file processing library header. More...
Go to the source code of this file.
Data Structures | |
| struct | trace_err_t |
| Libtrace error information. More... | |
| struct | libtrace_packet_t |
| The libtrace packet structure. More... | |
| struct | libtrace_ip |
| Generic IP header structure. More... | |
| struct | libtrace_ip6_ext |
| IPv6 header extension structure. More... | |
| struct | libtrace_ip6_frag |
| IPv6 fragmentation header. More... | |
| struct | libtrace_ip6 |
| Generic IPv6 header structure. More... | |
| struct | libtrace_tcp |
| Generic TCP header structure. More... | |
| struct | libtrace_udp |
| Generic UDP header structure. More... | |
| struct | libtrace_icmp |
| Generic ICMP header structure. More... | |
| struct | libtrace_icmp6 |
| Generic ICMPv6 header structure. More... | |
| struct | libtrace_llcsnap |
| Generic LLC/SNAP header structure. More... | |
| struct | libtrace_ether |
| 802.3 frame More... | |
| struct | libtrace_8021q |
| 802.1Q frame More... | |
| struct | libtrace_atm_cell |
| ATM User Network Interface (UNI) Cell. More... | |
| struct | libtrace_atm_nni_cell |
| ATM Network Node/Network Interface (NNI) Cell. More... | |
| struct | libtrace_atm_capture_cell |
| Captured UNI cell. More... | |
| struct | libtrace_atm_nni_capture_cell |
| Captured NNI cell. More... | |
| struct | libtrace_ppp |
| PPP header. More... | |
| struct | libtrace_pppoe |
| PPPoE header. More... | |
| struct | libtrace_gre_t |
| Libtrace local definition of GRE (Generalised Routing Protocol) header RFC2890. More... | |
| struct | libtrace_vxlan_t |
| Libtrace local definition of VXLAN Header (draft-mahalingam-dutt-dcops-vxlan) More... | |
| struct | libtrace_80211_t |
| 802.11 header More... | |
| struct | libtrace_radiotap_t |
| The Radiotap header pre-amble. More... | |
| struct | libtrace_ospf_v2_t |
| OSPF header. More... | |
| struct | libtrace_ospf_options_t |
| Options Field present in some OSPFv2 packets. More... | |
| struct | libtrace_ospf_lsa_v2_t |
| LSA Header for OSPFv2. More... | |
| struct | libtrace_ospf_hello_v2_t |
| OSPFv2 Hello Packet. More... | |
| struct | libtrace_ospf_db_desc_v2_t |
| OSPFv2 Database Description packet. More... | |
| struct | libtrace_ospf_ls_req_t |
| OSPF Link State Request Packet. More... | |
| struct | libtrace_ospf_ls_update_t |
| OSPF Link State Update Packet. More... | |
| struct | libtrace_ospf_as_external_lsa_t |
| OSPFv2 AS External LSA Body. More... | |
| struct | libtrace_ospf_summary_lsa |
| OSPFv2 Summary LSA Body. More... | |
| struct | libtrace_ospf_network_lsa_t |
| OSPFv2 Network LSA Body. More... | |
| struct | libtrace_ospf_link_t |
| OSPFv2 Router Link structure. More... | |
| struct | libtrace_ospf_router_lsa_t |
| OSPFv2 Router LSA. More... | |
| struct | libtrace_sll_header_t |
| A local definition of an SLL header. More... | |
| struct | libtrace_stat_t |
| Statistic counters are cumulative from the time the trace is started. More... | |
| struct | libtrace_eventobj_t |
| Structure returned by libtrace_event explaining what the current event is. More... | |
Macros | |
| #define | ct_assert(e) extern char (*ct_assert(void)) [sizeof(char[1 - 2*!(e)])] |
| #define | LIBTRACE_API_VERSION ((4<<16)|(0<<8)|(5)) |
| API version as 2 byte hex digits, eg 0xXXYYZZ. More... | |
| #define | LIBTRACE_SVN_REVISION LIBTRACE_API_VERSION |
| This used to be replaced with the current SVN revision number when 'make dist' was invoked to create a distributable tarball. More... | |
| #define | DAG_DRIVER_V "" |
| DAG driver version installed on the current system. More... | |
| #define | ASSERT_RET(run, cond) assert(run cond) |
| A version of assert that always runs the first argument even when not debugging, however only asserts the condition if debugging Intended for use mainly with pthread locks etc. More... | |
| #define | LT_BITFIELD8 unsigned int |
| #define | LT_BITFIELD16 unsigned int |
| #define | LT_BITFIELD32 unsigned int |
| #define | LT_BITFIELD64 unsigned int |
| #define | LT_USE_PACKED 1 |
| #define | LT_USE_UNUSED 1 |
| #define | LT_USE_DEPRECATED 1 |
| #define | LT_USE_PURE 1 |
| #define | LT_USE_PRINTF 1 |
| #define | LT_USE_VISIBILITY 1 |
| #define | PACKED __attribute__((packed)) |
| #define | UNUSED __attribute__((unused)) |
| #define | DEPRECATED __attribute__((deprecated)) |
| #define | SIMPLE_FUNCTION __attribute__((pure)) |
| #define | PRINTF(formatpos, argpos) __attribute__((format(printf,formatpos, argpos))) |
| #define | CACHE_LINE_SIZE 64 |
| #define | ALIGN_STRUCT(x) __attribute__((aligned(x))) |
| #define | DLLEXPORT |
| #define | DLLLOCAL |
| #define | LIBTRACE_PACKET_BUFSIZE 65536 |
| The size of a packet's buffer when managed by libtrace. More... | |
| #define | IS_LIBTRACE_META_PACKET(packet) (packet->type < TRACE_RT_DATA_SIMPLE) |
| #define | X(name) LT_BITFIELD64 name ##_valid : 1; |
Typedefs | |
| typedef struct libtrace_out_t | libtrace_out_t |
| Opaque structure holding information about an output trace. More... | |
| typedef struct libtrace_t | libtrace_t |
| Opaque structure holding information about a trace. More... | |
| typedef struct libtrace_filter_t | libtrace_filter_t |
| Opaque structure holding information about a bpf filter. More... | |
| typedef struct libtrace_thread_t | libtrace_thread_t |
| Opaque structure holding information about libtrace thread. More... | |
| typedef struct callback_set | libtrace_callback_set_t |
| Opaque structure holding callback functions for libtrace threads. More... | |
| typedef struct trace_err_t | libtrace_err_t |
| Libtrace error information. More... | |
| typedef struct libtrace_packet_t | libtrace_packet_t |
| The libtrace packet structure. More... | |
Functions | |
| DLLEXPORT void | trace_help (void) |
| Prints help information for libtrace. More... | |
| DLLEXPORT void | trace_interrupt (void) |
| Causes a libtrace reader to stop blocking whilst waiting on new packets and immediately return EOF. More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_linktype_t | trace_get_link_type (const libtrace_packet_t *packet) |
| Gets the link layer type for a packet. More... | |
| DLLEXPORT libtrace_direction_t | trace_set_direction (libtrace_packet_t *packet, libtrace_direction_t direction) |
| Set the direction flag for a packet, if the capture format supports direction tagging. More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_direction_t | trace_get_direction (const libtrace_packet_t *packet) |
| Get the direction flag for a packet, if it has one. More... | |
Protocol decodes | |
These functions locate and return a pointer to various headers inside a packet A packet is divided up into several "layers.":
| |
| DLLEXPORT void * | trace_get_packet_buffer (const libtrace_packet_t *packet, libtrace_linktype_t *linktype, uint32_t *remaining) |
| Gets a pointer to the first byte of the packet as it was captured and returns its corresponding linktype and capture length. More... | |
| DLLEXPORT SIMPLE_FUNCTION DEPRECATED void * | trace_get_link (const libtrace_packet_t *packet) |
| Get a pointer to the link layer for a given packet. More... | |
| DLLEXPORT libtrace_packet_t * | trace_strip_packet (libtrace_packet_t *packet) |
| Strips layer 2.5 headers from a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_ip_t * | trace_get_ip (libtrace_packet_t *packet) |
| Get a pointer to the IPv4 header (if any) for a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_ip6_t * | trace_get_ip6 (libtrace_packet_t *packet) |
| get a pointer to the IPv6 header (if any) More... | |
| DLLEXPORT void * | trace_get_packet_meta (const libtrace_packet_t *packet, libtrace_linktype_t *linktype, uint32_t *remaining) |
| Return a pointer to the first metadata header in a packet, if present. More... | |
| DLLEXPORT void * | trace_get_payload_from_meta (const void *meta, libtrace_linktype_t *linktype, uint32_t *remaining) |
| Returns the payload of a metadata header. More... | |
| DLLEXPORT void * | trace_get_layer2 (const libtrace_packet_t *packet, libtrace_linktype_t *linktype, uint32_t *remaining) |
| Get a pointer to the layer 2 header. More... | |
| DLLEXPORT void * | trace_get_payload_from_layer2 (void *l2, libtrace_linktype_t linktype, uint16_t *ethertype, uint32_t *remaining) |
| Gets a pointer to the next header following a layer 2 header. More... | |
| DLLEXPORT void * | trace_get_layer3 (const libtrace_packet_t *packet, uint16_t *ethertype, uint32_t *remaining) |
| Get a pointer to the layer 3 (e.g. More... | |
| DLLEXPORT uint16_t * | trace_checksum_layer3 (libtrace_packet_t *packet, uint16_t *csum) |
| Calculates the expected IP checksum for a packet. More... | |
| DLLEXPORT uint16_t * | trace_checksum_transport (libtrace_packet_t *packet, uint16_t *csum) |
| Calculates the expected checksum for the transport header in a packet. More... | |
| DLLEXPORT uint16_t | trace_get_fragment_offset (const libtrace_packet_t *packet, uint8_t *more) |
| Calculates the fragment offset in bytes for an IP packet. More... | |
| DLLEXPORT void * | trace_get_transport (const libtrace_packet_t *packet, uint8_t *proto, uint32_t *remaining) |
| Gets a pointer to the transport layer header (if any) More... | |
| DLLEXPORT void * | trace_get_payload_from_ip (libtrace_ip_t *ip, uint8_t *proto, uint32_t *remaining) |
| Gets a pointer to the payload following an IPv4 header. More... | |
| DLLEXPORT void * | trace_get_payload_from_ip6 (libtrace_ip6_t *ipptr, uint8_t *proto, uint32_t *remaining) |
| Gets a pointer to the payload following an IPv6 header. More... | |
| DLLEXPORT void * | trace_get_payload_from_link (void *linkptr, libtrace_linktype_t linktype, uint16_t *type, uint32_t *remaining) |
| Gets a pointer to the payload following a link header. More... | |
| DLLEXPORT void * | trace_get_payload_from_vlan (void *vlan, uint16_t *type, uint32_t *remaining) |
| Gets a pointer to the payload following an 802.1q (VLAN) header. More... | |
| DLLEXPORT void * | trace_get_payload_from_mpls (void *mpls, uint16_t *type, uint32_t *remaining) |
| Gets a pointer to the payload following an MPLS header. More... | |
| DLLEXPORT void * | trace_get_payload_from_pppoe (void *pppoe, uint16_t *type, uint32_t *remaining) |
| Gets a pointer to the payload following a PPPoE header. More... | |
| DLLEXPORT void * | trace_get_payload_from_tcp (libtrace_tcp_t *tcp, uint32_t *remaining) |
| Gets a pointer to the payload following a TCP header. More... | |
| DLLEXPORT void * | trace_get_payload_from_udp (libtrace_udp_t *udp, uint32_t *remaining) |
| Gets a pointer to the payload following a UDP header. More... | |
| DLLEXPORT void * | trace_get_payload_from_icmp (libtrace_icmp_t *icmp, uint32_t *remaining) |
| Gets a pointer to the payload following a ICMP header. More... | |
| DLLEXPORT void * | trace_get_payload_from_icmp6 (libtrace_icmp6_t *icmp, uint32_t *remaining) |
| Gets a pointer to the payload following a ICMPv6 header. More... | |
| DLLEXPORT void * | trace_get_payload_from_gre (libtrace_gre_t *gre, uint32_t *remaining) |
| Gets a pointer to the payload following a GRE header. More... | |
| DLLEXPORT libtrace_vxlan_t * | trace_get_vxlan_from_udp (libtrace_udp_t *udp, uint32_t *remaining) |
| Gets a pointer to the payload following a VXLAN header. More... | |
| DLLEXPORT void * | trace_get_payload_from_vxlan (libtrace_vxlan_t *vxlan, uint32_t *remaining) |
| Gets a pointer to the payload following a VXLAN header. More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_tcp_t * | trace_get_tcp (libtrace_packet_t *packet) |
| Get a pointer to the TCP header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_tcp_t * | trace_get_tcp_from_ip (libtrace_ip_t *ip, uint32_t *remaining) |
| Get a pointer to the TCP header following an IPv4 header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_udp_t * | trace_get_udp (libtrace_packet_t *packet) |
| Get a pointer to the UDP header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_udp_t * | trace_get_udp_from_ip (libtrace_ip_t *ip, uint32_t *remaining) |
| Get a pointer to the UDP header following an IPv4 header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_icmp_t * | trace_get_icmp (libtrace_packet_t *packet) |
| Get a pointer to the ICMP header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_icmp6_t * | trace_get_icmp6 (libtrace_packet_t *packet) |
| Get a pointer to the ICMPv6 header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_icmp_t * | trace_get_icmp_from_ip (libtrace_ip_t *ip, uint32_t *remaining) |
| Get a pointer to the ICMP header following an IPv4 header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION void * | trace_get_ospf_header (libtrace_packet_t *packet, uint8_t *version, uint32_t *remaining) |
| Get a pointer to the OSPF header (if present) More... | |
| DLLEXPORT SIMPLE_FUNCTION void * | trace_get_ospf_contents_v2 (libtrace_ospf_v2_t *header, uint8_t *ospf_type, uint32_t *remaining) |
| Get a pointer to the contents of the OSPF packet after the OSPF header. More... | |
| DLLEXPORT SIMPLE_FUNCTION unsigned char * | trace_get_first_ospf_lsa_from_update_v2 (libtrace_ospf_ls_update_t *ls_update, uint32_t *remaining) |
| Get a pointer to the start of the first LSA contained within an LS Update packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION unsigned char * | trace_get_first_ospf_lsa_from_db_desc_v2 (libtrace_ospf_db_desc_v2_t *db_desc, uint32_t *remaining) |
| Get a pointer to the start of the first LSA contained within an Database Description packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION unsigned char * | trace_get_first_ospf_link_from_router_lsa_v2 (libtrace_ospf_router_lsa_v2_t *lsa, uint32_t *remaining) |
| Get a pointer to the start of the first link contained within a Router LSA. More... | |
| DLLEXPORT SIMPLE_FUNCTION int | trace_get_next_ospf_link_v2 (unsigned char **current, libtrace_ospf_link_v2_t **link, uint32_t *remaining, uint32_t *link_len) |
| Parses an OSPF Router LSA Link and finds the next Link (if there is one) More... | |
| DLLEXPORT SIMPLE_FUNCTION int | trace_get_next_ospf_lsa_v2 (unsigned char **current, libtrace_ospf_lsa_v2_t **lsa_hdr, unsigned char **lsa_body, uint32_t *remaining, uint8_t *lsa_type, uint16_t *lsa_length) |
| Parses an OSPF LSA and finds the next LSA (if there is one) More... | |
| DLLEXPORT SIMPLE_FUNCTION int | trace_get_next_ospf_lsa_header_v2 (unsigned char **current, libtrace_ospf_lsa_v2_t **lsa_hdr, uint32_t *remaining, uint8_t *lsa_type, uint16_t *lsa_length) |
| Parses an OSPF LSA header and finds the next LSA (if there is one) More... | |
| DLLEXPORT SIMPLE_FUNCTION uint32_t | trace_get_ospf_metric_from_as_external_lsa_v2 (libtrace_ospf_as_external_lsa_v2_t *as_lsa) |
| Extracts the metric field from an AS External LSA packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION uint32_t | trace_get_ospf_metric_from_summary_lsa_v2 (libtrace_ospf_summary_lsa_v2_t *sum_lsa) |
| Extracts the metric field from a Summary LSA packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION uint8_t * | trace_get_destination_mac (libtrace_packet_t *packet) |
| Gets the destination MAC address for a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION uint8_t * | trace_get_source_mac (libtrace_packet_t *packet) |
| Gets the source MAC address for a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION struct sockaddr * | trace_get_source_address (const libtrace_packet_t *packet, struct sockaddr *addr) |
| Get the source IP address for a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION char * | trace_get_source_address_string (const libtrace_packet_t *packet, char *space, int spacelen) |
| Get the source IP address for a packet and convert it into a string. More... | |
| DLLEXPORT SIMPLE_FUNCTION struct sockaddr * | trace_get_destination_address (const libtrace_packet_t *packet, struct sockaddr *addr) |
| Get the destination IP address for a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION char * | trace_get_destination_address_string (const libtrace_packet_t *packet, char *space, int spacelen) |
| Get the destination IP address for a packet and convert it into a string. More... | |
| DLLEXPORT int | trace_get_next_option (unsigned char **ptr, int *len, unsigned char *type, unsigned char *optlen, unsigned char **data) |
| Parses an IP or TCP option. More... | |
Time | |
These functions deal with the timestamp describing when a packet was captured and can convert it into various formats | |
| DLLEXPORT SIMPLE_FUNCTION uint64_t | trace_get_erf_timestamp (const libtrace_packet_t *packet) |
| Get the packet timestamp in the DAG time format. More... | |
| DLLEXPORT SIMPLE_FUNCTION struct timeval | trace_get_timeval (const libtrace_packet_t *packet) |
| Get the packet timestamp as a struct timeval. More... | |
| DLLEXPORT SIMPLE_FUNCTION struct timespec | trace_get_timespec (const libtrace_packet_t *packet) |
| Get the packet timestamp as a struct timespec. More... | |
| DLLEXPORT SIMPLE_FUNCTION double | trace_get_seconds (const libtrace_packet_t *packet) |
| Get the packet timestamp in floating point seconds. More... | |
| DLLEXPORT int | trace_seek_seconds (libtrace_t *trace, double seconds) |
| Seek within an input trace to a time specified in floating point seconds. More... | |
| DLLEXPORT int | trace_seek_timeval (libtrace_t *trace, struct timeval tv) |
| Seek within an input trace to a time specified as a timeval. More... | |
| DLLEXPORT int | trace_seek_erf_timestamp (libtrace_t *trace, uint64_t ts) |
| Seek within an input trace to a time specified as an ERF timestamp. More... | |
Sizes | |
This section deals with finding or setting the various different lengths that a packet can have, e.g. capture lengths, wire lengths, etc. | |
| DLLEXPORT SIMPLE_FUNCTION size_t | trace_get_capture_length (const libtrace_packet_t *packet) |
| Get the current size of the packet (in bytes), taking into account any truncation or snapping that may have previously been performed. More... | |
| DLLEXPORT SIMPLE_FUNCTION size_t | trace_get_wire_length (const libtrace_packet_t *packet) |
| Get the size of the packet as it was originally seen on the wire (in bytes). More... | |
| DLLEXPORT SIMPLE_FUNCTION size_t | trace_get_framing_length (const libtrace_packet_t *packet) |
| Get the length of the capture framing headers (in bytes). More... | |
| DLLEXPORT SIMPLE_FUNCTION size_t | trace_get_payload_length (const libtrace_packet_t *packet) |
| Get the length of the original payload content of the packet (in bytes). More... | |
| DLLEXPORT size_t | trace_set_capture_length (libtrace_packet_t *packet, size_t size) |
| Truncate ("snap") the packet to the suggested length. More... | |
BPF | |
This section deals with using Berkley Packet Filters to filter input traces | |
| DLLEXPORT SIMPLE_FUNCTION libtrace_filter_t * | trace_create_filter (const char *filterstring) |
| Creates a BPF filter. More... | |
| DLLEXPORT libtrace_filter_t * | trace_create_filter_from_bytecode (void *bf_insns, unsigned int bf_len) |
| Create a BPF filter based on pre-compiled byte-code. More... | |
| DLLEXPORT int | trace_apply_filter (libtrace_filter_t *filter, const libtrace_packet_t *packet) |
| Apply a BPF filter to a packet. More... | |
| DLLEXPORT void | trace_destroy_filter (libtrace_filter_t *filter) |
| Destroy a BPF filter. More... | |
Portability | |
This section contains functions that deal with portability issues, e.g. byte ordering. | |
| DLLEXPORT char * | trace_ether_ntoa (const uint8_t *addr, char *buf) |
| Converts an ethernet address to a printable string. More... | |
| DLLEXPORT uint8_t * | trace_ether_aton (const char *buf, uint8_t *addr) |
| Convert a string to an ethernet address. More... | |
Protocol structures | |
These convenience structures provide portable versions of the headers for a variety of protocols. | |
| #define | LIBTRACE_GRE_FLAG_CHECKSUM 0x8000 |
| #define | LIBTRACE_GRE_FLAG_KEY 0x2000 |
| #define | LIBTRACE_GRE_FLAG_SEQ 0x1000 |
| #define | LIBTRACE_GRE_FLAG_VERMASK 0x0007 |
| #define | LIBTRACE_GRE_FLAG_ACK 0x0080 |
| #define | LIBTRACE_GRE_PPTP_VERSION 0x0001 |
| #define | TRACE_SLL_HOST 0 |
| Packet was addressed for the local host. More... | |
| #define | TRACE_SLL_BROADCAST 1 |
| Packet was addressed for a broadcast address. More... | |
| #define | TRACE_SLL_MULTICAST 2 |
| Packet was addressed for a multicast address. More... | |
| #define | TRACE_SLL_OTHERHOST 3 |
| Packet was addressed for another host but was captured by a promiscuous device. More... | |
| #define | TRACE_SLL_OUTGOING 4 |
| Packet originated from the local host. More... | |
| enum | libtrace_ospf_types_t { TRACE_OSPF_HELLO = 1, TRACE_OSPF_DATADESC = 2, TRACE_OSPF_LSREQ = 3, TRACE_OSPF_LSUPDATE = 4, TRACE_OSPF_LSACK = 5 } |
| OSPF message types. More... | |
| enum | libtrace_ospf_ls_types_t { TRACE_OSPF_LS_ROUTER = 1, TRACE_OSPF_LS_NETWORK = 2, TRACE_OSPF_LS_SUMMARY = 3, TRACE_OSPF_LS_ASBR_SUMMARY = 4, TRACE_OSPF_LS_EXTERNAL = 5 } |
| OSPF link state acknowledgement types. More... | |
| typedef struct libtrace_ip | libtrace_ip_t |
| Generic IP header structure. More... | |
| typedef struct libtrace_ip6_ext | libtrace_ip6_ext_t |
| IPv6 header extension structure. More... | |
| typedef struct libtrace_ip6_frag | libtrace_ip6_frag_t |
| IPv6 fragmentation header. More... | |
| typedef struct libtrace_ip6 | libtrace_ip6_t |
| Generic IPv6 header structure. More... | |
| typedef struct libtrace_tcp | libtrace_tcp_t |
| Generic TCP header structure. More... | |
| typedef struct libtrace_udp | libtrace_udp_t |
| Generic UDP header structure. More... | |
| typedef struct libtrace_icmp | libtrace_icmp_t |
| Generic ICMP header structure. More... | |
| typedef struct libtrace_icmp6 | libtrace_icmp6_t |
| Generic ICMPv6 header structure. More... | |
| typedef struct libtrace_llcsnap | libtrace_llcsnap_t |
| Generic LLC/SNAP header structure. More... | |
| typedef struct libtrace_ether | libtrace_ether_t |
| 802.3 frame More... | |
| typedef struct libtrace_8021q | libtrace_8021q_t |
| 802.1Q frame More... | |
| typedef struct libtrace_atm_cell | libtrace_atm_cell_t |
| ATM User Network Interface (UNI) Cell. More... | |
| typedef struct libtrace_atm_nni_cell | libtrace_atm_nni_cell_t |
| ATM Network Node/Network Interface (NNI) Cell. More... | |
| typedef struct libtrace_atm_capture_cell | libtrace_atm_capture_cell_t |
| Captured UNI cell. More... | |
| typedef struct libtrace_atm_nni_capture_cell | libtrace_atm_nni_capture_cell_t |
| Captured NNI cell. More... | |
| typedef struct libtrace_ppp | libtrace_ppp_t |
| PPP header. More... | |
| typedef struct libtrace_pppoe | libtrace_pppoe_t |
| PPPoE header. More... | |
| typedef struct libtrace_gre_t | libtrace_gre_t |
| Libtrace local definition of GRE (Generalised Routing Protocol) header RFC2890. More... | |
| typedef struct libtrace_vxlan_t | libtrace_vxlan_t |
| Libtrace local definition of VXLAN Header (draft-mahalingam-dutt-dcops-vxlan) More... | |
| typedef struct libtrace_80211_t | libtrace_80211_t |
| 802.11 header More... | |
| typedef struct libtrace_radiotap_t | libtrace_radiotap_t |
| The Radiotap header pre-amble. More... | |
| typedef struct libtrace_ospf_v2_t | libtrace_ospf_v2_t |
| OSPF header. More... | |
| typedef struct libtrace_ospf_options_t | libtrace_ospf_options_t |
| Options Field present in some OSPFv2 packets. More... | |
| typedef struct libtrace_ospf_lsa_v2_t | libtrace_ospf_lsa_v2_t |
| LSA Header for OSPFv2. More... | |
| typedef struct libtrace_ospf_hello_v2_t | libtrace_ospf_hello_v2_t |
| OSPFv2 Hello Packet. More... | |
| typedef struct libtrace_ospf_db_desc_v2_t | libtrace_ospf_db_desc_v2_t |
| OSPFv2 Database Description packet. More... | |
| typedef struct libtrace_ospf_ls_req_t | libtrace_ospf_ls_req_t |
| OSPF Link State Request Packet. More... | |
| typedef struct libtrace_ospf_ls_update_t | libtrace_ospf_ls_update_t |
| OSPF Link State Update Packet. More... | |
| typedef struct libtrace_ospf_as_external_lsa_t | libtrace_ospf_as_external_lsa_v2_t |
| OSPFv2 AS External LSA Body. More... | |
| typedef struct libtrace_ospf_summary_lsa | libtrace_ospf_summary_lsa_v2_t |
| OSPFv2 Summary LSA Body. More... | |
| typedef struct libtrace_ospf_network_lsa_t | libtrace_ospf_network_lsa_v2_t |
| OSPFv2 Network LSA Body. More... | |
| typedef struct libtrace_ospf_link_t | libtrace_ospf_link_v2_t |
| OSPFv2 Router Link structure. More... | |
| typedef struct libtrace_ospf_router_lsa_t | libtrace_ospf_router_lsa_v2_t |
| OSPFv2 Router LSA. More... | |
| typedef struct libtrace_sll_header_t | libtrace_sll_header_t |
| A local definition of an SLL header. More... | |
Trace management | |
These members deal with creating, configuring, starting, pausing and cleaning up a trace object | |
| #define | LIBTRACE_STAT_FIELDS |
| An X Macro set for libtrace stat fields. More... | |
| enum | trace_option_t { TRACE_OPTION_SNAPLEN, TRACE_OPTION_PROMISC, TRACE_OPTION_FILTER, TRACE_OPTION_META_FREQ, TRACE_OPTION_EVENT_REALTIME, TRACE_OPTION_HASHER, TRACE_OPTION_REPLAY_SPEEDUP } |
| Valid configuration options for input traces. More... | |
| enum | trace_option_compresstype_t { TRACE_OPTION_COMPRESSTYPE_NONE = 0, TRACE_OPTION_COMPRESSTYPE_ZLIB = 1, TRACE_OPTION_COMPRESSTYPE_BZ2 = 2, TRACE_OPTION_COMPRESSTYPE_LZO = 3, TRACE_OPTION_COMPRESSTYPE_LZMA = 4, TRACE_OPTION_COMPRESSTYPE_LAST } |
| Valid compression types Note, this must be kept in sync with WANDIO_COMPRESS_* numbers in wandio.h. More... | |
| enum | trace_option_output_t { TRACE_OPTION_OUTPUT_FILEFLAGS, TRACE_OPTION_OUTPUT_COMPRESS, TRACE_OPTION_OUTPUT_COMPRESSTYPE } |
| Valid configuration options for output traces. More... | |
| typedef struct libtrace_stat_t | libtrace_stat_t |
| Statistic counters are cumulative from the time the trace is started. More... | |
| DLLEXPORT const char * | trace_parse_uri (const char *uri, char **format) |
| Takes a uri and splits it into a format and uridata component. More... | |
| DLLEXPORT libtrace_t * | trace_create (const char *uri) |
| Create an input trace from a URI. More... | |
| DLLEXPORT libtrace_t * | trace_create_dead (const char *uri) |
| Creates a "dummy" trace file that has only the format type set. More... | |
| DLLEXPORT libtrace_out_t * | trace_create_output (const char *uri) |
| Creates a trace output file from a URI. More... | |
| DLLEXPORT int | trace_start (libtrace_t *libtrace) |
| Start an input trace. More... | |
| DLLEXPORT int | trace_pause (libtrace_t *libtrace) |
| Pauses an input trace. More... | |
| DLLEXPORT int | trace_start_output (libtrace_out_t *libtrace) |
| Start an output trace. More... | |
| DLLEXPORT int | trace_config (libtrace_t *libtrace, trace_option_t option, void *value) |
| Sets an input config option. More... | |
| DLLEXPORT int | trace_set_snaplen (libtrace_t *trace, int snaplen) |
| Maximum number of bytes to be captured for any given packet. More... | |
| DLLEXPORT int | trace_set_promisc (libtrace_t *trace, bool promisc) |
| If enabled, places a live capture interface into promiscuous mode. More... | |
| DLLEXPORT int | trace_set_filter (libtrace_t *trace, libtrace_filter_t *filter) |
| Apply this filter to all packets read from this trace. More... | |
| DLLEXPORT int | trace_set_meta_freq (libtrace_t *trace, int freq) |
| Defines the frequency of meta-data reporting, e.g. More... | |
| DLLEXPORT int | trace_set_event_realtime (libtrace_t *trace, bool realtime) |
| If enabled, the libtrace event API will ignore time gaps between packets when reading from a trace file. More... | |
| ct_assert (offsetof(libtrace_stat_t, accepted)==8) | |
| DLLEXPORT int | trace_config_output (libtrace_out_t *libtrace, trace_option_output_t option, void *value) |
| Sets an output config option. More... | |
| DLLEXPORT void | trace_destroy (libtrace_t *trace) |
| Close an input trace, freeing up any resources it may have been using. More... | |
| DLLEXPORT void | trace_destroy_dead (libtrace_t *trace) |
| Close a dummy trace file, freeing up any resources it may have been using. More... | |
| DLLEXPORT void | trace_destroy_output (libtrace_out_t *trace) |
| Close an output trace, freeing up any resources it may have been using. More... | |
| DLLEXPORT int | trace_flush_output (libtrace_out_t *libtrace) |
| Flush an output trace, forcing any buffered packets to be written. More... | |
| DLLEXPORT libtrace_err_t | trace_get_err (libtrace_t *trace) |
| Check (and clear) the current error state of an input trace. More... | |
| DLLEXPORT bool | trace_is_err (libtrace_t *trace) |
| Indicate if there has been an error on an input trace. More... | |
| DLLEXPORT void | trace_perror (libtrace_t *trace, const char *msg,...) PRINTF(2 |
| Outputs the error message for an input trace to stderr and clear the error status. More... | |
| DLLEXPORT void DLLEXPORT libtrace_err_t | trace_get_err_output (libtrace_out_t *trace) |
| Checks (and clears) the current error state for an output trace. More... | |
| DLLEXPORT bool | trace_is_err_output (libtrace_out_t *trace) |
| Indicates if there is an error on an output trace. More... | |
| DLLEXPORT void | trace_perror_output (libtrace_out_t *trace, const char *msg,...) PRINTF(2 |
| Outputs the error message for an output trace to stderr and clear the error status. More... | |
| DLLEXPORT void DLLEXPORT DEPRECATED uint64_t | trace_get_received_packets (libtrace_t *trace) |
| Returns the number of packets observed on an input trace. More... | |
| DLLEXPORT DEPRECATED uint64_t | trace_get_filtered_packets (libtrace_t *trace) |
| Returns the number of packets that were captured, but discarded for not matching a provided filter. More... | |
| DLLEXPORT DEPRECATED uint64_t | trace_get_dropped_packets (libtrace_t *trace) |
| Returns the number of packets that have been dropped on an input trace due to lack of buffer space on the capturing device. More... | |
| DLLEXPORT DEPRECATED uint64_t | trace_get_accepted_packets (libtrace_t *trace) |
| Returns the number of packets that have been read from the input trace using trace_read_packet(). More... | |
| DLLEXPORT libtrace_stat_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. More... | |
| DLLEXPORT void | trace_get_thread_statistics (libtrace_t *trace, libtrace_thread_t *t, libtrace_stat_t *stats) |
| Returns statistic counters for a single thread of a trace. More... | |
| DLLEXPORT libtrace_stat_t * | trace_create_statistics (void) |
| Creates and returns a zeroed libtrace_stat_t structure. More... | |
| DLLEXPORT void | trace_clear_statistics (libtrace_stat_t *s) |
| Clear all fields of given statistic. More... | |
| DLLEXPORT void | trace_subtract_statistics (const libtrace_stat_t *a, const libtrace_stat_t *b, libtrace_stat_t *c) |
| Performs the operation c=a-b accounting for valid fields. More... | |
| DLLEXPORT void | trace_add_statistics (const libtrace_stat_t *a, const libtrace_stat_t *b, libtrace_stat_t *c) |
| Performs operation c=a+b accounting for valid fields. More... | |
| DLLEXPORT int | trace_print_statistics (const libtrace_stat_t *s, FILE *f, const char *format) |
| Prints all valid stats to a file stream, (which could be stdout/err). More... | |
Reading / Writing packets | |
These members deal with creating, reading and writing packets | |
| enum | { TRACE_PREP_OWN_BUFFER =1, TRACE_PREP_DO_NOT_OWN_BUFFER =0 } |
| Flags for prepare_packet functions. More... | |
| enum | libtrace_event_t { TRACE_EVENT_IOWAIT, TRACE_EVENT_SLEEP, TRACE_EVENT_PACKET, TRACE_EVENT_TERMINATE } |
| Event types see libtrace_eventobj_t and trace_event. More... | |
| typedef struct libtrace_eventobj_t | libtrace_eventobj_t |
| Structure returned by libtrace_event explaining what the current event is. More... | |
| DLLEXPORT libtrace_packet_t * | trace_create_packet (void) |
| Create a new packet object. More... | |
| DLLEXPORT libtrace_packet_t * | trace_copy_packet (const libtrace_packet_t *packet) |
| Copy a packet object. More... | |
| DLLEXPORT void | trace_destroy_packet (libtrace_packet_t *packet) |
| Destroy a packet object. More... | |
| DLLEXPORT int | trace_read_packet (libtrace_t *trace, libtrace_packet_t *packet) |
| Read the next packet from an input trace. More... | |
| DLLEXPORT int | trace_prepare_packet (libtrace_t *trace, libtrace_packet_t *packet, void *buffer, libtrace_rt_types_t rt_type, uint32_t flags) |
| Converts the data provided in buffer into a valid libtrace packet. More... | |
| DLLEXPORT libtrace_eventobj_t | trace_event (libtrace_t *trace, libtrace_packet_t *packet) |
| Processes the next libtrace event from an input trace. More... | |
| DLLEXPORT int | trace_write_packet (libtrace_out_t *trace, libtrace_packet_t *packet) |
| Write one packet out to the output trace. More... | |
| DLLEXPORT enum base_format_t | trace_get_format (struct libtrace_packet_t *packet) |
| Gets the capture format for a given packet. More... | |
| DLLEXPORT void | trace_construct_packet (libtrace_packet_t *packet, libtrace_linktype_t linktype, const void *data, uint16_t len) |
| Construct a libtrace packet from a buffer containing the packet payload. More... | |
Ports | |
This section contains functions for dealing with port numbers at the transport layer. | |
| enum | serverport_t { USE_DEST, USE_SOURCE } |
| An indication of which port is the "server" port for a given port pair. More... | |
| DLLEXPORT SIMPLE_FUNCTION uint16_t | trace_get_source_port (const libtrace_packet_t *packet) |
| Gets the source port for a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION uint16_t | trace_get_destination_port (const libtrace_packet_t *packet) |
| Gets the destination port for a given packet. More... | |
| DLLEXPORT SIMPLE_FUNCTION int8_t | trace_get_server_port (uint8_t protocol, uint16_t source, uint16_t dest) |
| Hint at which of the two provided ports is the server port. More... | |
Wireless trace support | |
Functions to access wireless information from packets that have wireless monitoring headers such as Radiotap or Prism. The trace_get_wireless_* functions provide an abstract interface for retrieving information from wireless traces. They take a pointer to the wireless monitoring header (usually found with trace_get_packet_meta()) and the linktype of the header passed in. All of the trace_get_wireless_* functions return false if the requested information was unavailable, or true if it was. The actual data is stored in an output variable supplied by the caller. Values returned into the output variable will always be returned in host byte order. | |
| #define | ARPHRD_80211_RADIOTAP 803 |
| libc doesn't define this yet, so we have to do so ourselves More... | |
| DLLEXPORT bool | trace_get_wireless_tsft (void *linkptr, libtrace_linktype_t linktype, uint64_t *tsft) |
| Get the wireless Timer Synchronisation Function. More... | |
| DLLEXPORT bool | trace_get_wireless_rate (void *linkptr, libtrace_linktype_t linktype, uint8_t *rate) |
| Get the wireless data rate. More... | |
| DLLEXPORT bool | trace_get_wireless_freq (void *linkptr, libtrace_linktype_t linktype, uint16_t *freq) |
| Get the wireless channel frequency. More... | |
| DLLEXPORT bool | trace_get_wireless_signal_strength_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *strength) |
| Get the wireless signal strength in dBm. More... | |
| DLLEXPORT bool | trace_get_wireless_noise_strength_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *strength) |
| Get the wireless noise strength in dBm. More... | |
| DLLEXPORT bool | trace_get_wireless_signal_strength_db (void *linkptr, libtrace_linktype_t linktype, uint8_t *strength) |
| Get the wireless signal strength in dB. More... | |
| DLLEXPORT bool | trace_get_wireless_noise_strength_db (void *linkptr, libtrace_linktype_t linktype, uint8_t *strength) |
| Get the wireless noise strength in dB. More... | |
| DLLEXPORT bool | trace_get_wireless_tx_attenuation (void *linkptr, libtrace_linktype_t linktype, uint16_t *attenuation) |
| Get the wireless transmit attenuation. More... | |
| DLLEXPORT bool | trace_get_wireless_tx_attenuation_db (void *linkptr, libtrace_linktype_t linktype, uint16_t *attenuation) |
| Get the wireless transmit attenuation in dB. More... | |
| DLLEXPORT bool | trace_get_wireless_tx_power_dbm (void *linkptr, libtrace_linktype_t linktype, int8_t *txpower) |
| Get the wireless transmit power in dBm. More... | |
| DLLEXPORT bool | trace_get_wireless_antenna (void *linkptr, libtrace_linktype_t linktype, uint8_t *antenna) |
| Get the wireless antenna. More... | |
Detailed Description
Trace file processing library header.
- Version
- $Id$
This library provides a per packet interface into a trace file, or a live captures. It supports ERF, DAG cards, PCAP, Linux and BSD native sockets, legacy ERF formats etc.
- Usage
- See the example/ directory in the source distribution for some simple examples
- Linking
- To use this library you need to link against libtrace by passing -ltrace to your linker.
See libtrace_parallel.h for a description of the parallel API that allows programmers to spread packet processing across multiple threads.
Macro Definition Documentation
| #define ARPHRD_80211_RADIOTAP 803 |
libc doesn't define this yet, so we have to do so ourselves
| #define ASSERT_RET | ( | run, | |
| cond | |||
| ) | assert(run cond) |
A version of assert that always runs the first argument even when not debugging, however only asserts the condition if debugging Intended for use mainly with pthread locks etc.
which have error returns but should never actually fail.
Referenced by store_first_packet(), trace_apply_filter(), trace_create(), trace_create_dead(), trace_destroy(), trace_destroy_dead(), trace_get_first_packet(), trace_join(), trace_ppause(), and trace_pstart().
| #define DAG_DRIVER_V "" |
DAG driver version installed on the current system.
| #define LIBTRACE_API_VERSION ((4<<16)|(0<<8)|(5)) |
API version as 2 byte hex digits, eg 0xXXYYZZ.
| #define LIBTRACE_PACKET_BUFSIZE 65536 |
The size of a packet's buffer when managed by libtrace.
Referenced by trace_config(), trace_construct_packet(), trace_get_capture_length(), and trace_get_wire_length().
| #define LIBTRACE_STAT_FIELDS |
An X Macro set for libtrace stat fields.
Referenced by trace_add_statistics(), trace_get_statistics(), trace_get_thread_statistics(), trace_print_statistics(), and trace_subtract_statistics().
| #define LIBTRACE_SVN_REVISION LIBTRACE_API_VERSION |
This used to be replaced with the current SVN revision number when 'make dist' was invoked to create a distributable tarball.
We don't use SVN anymore and there probably isn't any need to know the exact revision number either these days.
| #define TRACE_SLL_BROADCAST 1 |
Packet was addressed for a broadcast address.
| #define TRACE_SLL_HOST 0 |
Packet was addressed for the local host.
| #define TRACE_SLL_MULTICAST 2 |
Packet was addressed for a multicast address.
| #define TRACE_SLL_OTHERHOST 3 |
Packet was addressed for another host but was captured by a promiscuous device.
| #define TRACE_SLL_OUTGOING 4 |
Packet originated from the local host.
Referenced by promote_packet().
Typedef Documentation
| 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.
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 occurred.... yet. |
| TRACE_ERR_BAD_FORMAT |
The URI passed to trace_create() is unsupported, or badly formed. |
| TRACE_ERR_INIT_FAILED |
The trace failed to initialise. |
| TRACE_ERR_UNKNOWN_OPTION |
Unknown config option. |
| TRACE_ERR_NO_CONVERSION |
This output uri cannot write packets of this type. |
| TRACE_ERR_BAD_PACKET |
This packet is corrupt, or unusable for the action required. |
| TRACE_ERR_OPTION_UNAVAIL |
Option known, but unsupported by this format. |
| TRACE_ERR_UNSUPPORTED |
This feature is unsupported. |
| TRACE_ERR_BAD_STATE |
Illegal use of the API. |
| TRACE_ERR_BAD_FILTER |
Failed to compile a BPF filter. |
| TRACE_ERR_RT_FAILURE |
RT communication breakdown. |
| TRACE_ERR_UNSUPPORTED_COMPRESS |
Compression format unsupported. |
| TRACE_ERR_WANDIO_FAILED |
Wandio has returned an error. |
| anonymous enum |
| 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.
| 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 zero-copied out of memory owned by something else, e.g. a DAG card, it should be TRACE_CTRL_EXTERNAL.
- Note
- The letters p and e are magic numbers used to detect if the packet wasn't created properly.
| Enumerator | |
|---|---|
| TRACE_CTRL_PACKET |
Buffer memory is owned by the packet. |
| TRACE_CTRL_EXTERNAL |
Buffer memory is owned by an external source. |
| 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.
| enum libtrace_dlt_t |
Enumeration of DLTs supported by libtrace.
| enum libtrace_ethertype_t |
Ethertypes supported by Libtrace.
| enum libtrace_event_t |
Event types see libtrace_eventobj_t and trace_event.
| enum libtrace_ipproto_t |
IP Protocol values.
| enum libtrace_linktype_t |
Enumeration of link layer types supported by libtrace.
Enumeration of Radiotap fields.
| enum libtrace_rt_types_t |
RT protocol packet types.
| enum serverport_t |
Valid compression types Note, this must be kept in sync with WANDIO_COMPRESS_* numbers in wandio.h.
Valid configuration options for output traces.
| 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(). |
| TRACE_OPTION_REPLAY_SPEEDUP |
Speed up trace file replays (via trace_event()) by this factor. |
Function Documentation
| DLLEXPORT void trace_add_statistics | ( | const libtrace_stat_t * | a, |
| const libtrace_stat_t * | b, | ||
| libtrace_stat_t * | c | ||
| ) |
Performs operation c=a+b accounting for valid fields.
c is allowed to be a or b.
- Parameters
-
a The first operand b The second operand c The result
References LIBTRACE_STAT_FIELDS, and libtrace_stat_t::magic.
| DLLEXPORT int trace_apply_filter | ( | libtrace_filter_t * | filter, |
| const libtrace_packet_t * | packet | ||
| ) |
Apply a BPF filter to a packet.
- Parameters
-
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_copy_packet(), trace_destroy_packet(), TRACE_ERR_NO_CONVERSION, trace_get_link_type(), trace_get_packet_buffer(), trace_set_err(), TRACE_TYPE_ERF_META, and TRACE_TYPE_NONDATA.
Referenced by trace_read_packet().
| DLLEXPORT uint16_t* trace_checksum_layer3 | ( | libtrace_packet_t * | packet, |
| uint16_t * | csum | ||
| ) |
Calculates the expected IP checksum for a packet.
- Parameters
-
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_ETHERTYPE_IP, and trace_get_layer3().
| DLLEXPORT uint16_t* trace_checksum_transport | ( | libtrace_packet_t * | packet, |
| uint16_t * | csum | ||
| ) |
Calculates the expected checksum for the transport header in a packet.
- Parameters
-
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_tcp::check, libtrace_udp::check, libtrace_icmp::checksum, libtrace_tcp::doff, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_icmp(), trace_get_payload_from_tcp(), trace_get_payload_from_udp(), trace_get_payload_length(), trace_get_transport(), TRACE_IPPROTO_ICMP, TRACE_IPPROTO_TCP, and TRACE_IPPROTO_UDP.
| DLLEXPORT void trace_clear_statistics | ( | libtrace_stat_t * | s | ) |
Clear all fields of given statistic.
This api doesn't verify the magic field unlike other stat apis.
- Parameters
-
s The statistic structure to clear
References libtrace_stat_t::magic.
| DLLEXPORT int trace_config | ( | libtrace_t * | libtrace, |
| trace_option_t | option, | ||
| void * | value | ||
| ) |
Sets an input config option.
- Parameters
-
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::replayspeedup, libtrace_t::snaplen, TRACE_ERR_BAD_STATE, TRACE_ERR_OPTION_UNAVAIL, TRACE_ERR_UNKNOWN_OPTION, trace_get_err(), trace_is_err(), TRACE_OPTION_EVENT_REALTIME, TRACE_OPTION_FILTER, TRACE_OPTION_HASHER, TRACE_OPTION_META_FREQ, TRACE_OPTION_PROMISC, TRACE_OPTION_REPLAY_SPEEDUP, TRACE_OPTION_SNAPLEN, trace_set_err(), and trace_set_hasher().
Referenced by trace_set_event_realtime(), trace_set_filter(), trace_set_meta_freq(), trace_set_promisc(), and trace_set_snaplen().
| DLLEXPORT int trace_config_output | ( | libtrace_out_t * | libtrace, |
| trace_option_output_t | option, | ||
| void * | value | ||
| ) |
Sets an output config option.
- Parameters
-
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, and libtrace_out_t::format.
| DLLEXPORT void trace_construct_packet | ( | libtrace_packet_t * | packet, |
| libtrace_linktype_t | linktype, | ||
| const void * | data, | ||
| uint16_t | len | ||
| ) |
Construct a libtrace packet from a buffer containing the packet payload.
- Parameters
-
[in,out] 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_PACKET_BUFSIZE, libtrace_to_pcap_linktype(), libtrace_packet_t::payload, pcap_linktype_to_rt(), libtrace_packet_t::trace, trace_clear_cache(), trace_create_dead(), TRACE_CTRL_PACKET, and libtrace_packet_t::type.
| DLLEXPORT libtrace_packet_t* trace_copy_packet | ( | const libtrace_packet_t * | packet | ) |
Copy a packet object.
- Parameters
-
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 zero-copied
- packet from a device will be stored using memory owned by the device which may be a limited resource. Copying the packet will ensure that the packet is now stored in memory owned and managed by libtrace.
References libtrace_packet_t::buf_control, libtrace_packet_t::buffer, libtrace_packet_t::error, libtrace_packet_t::hash, libtrace_packet_t::header, libtrace_packet_t::order, libtrace_packet_t::payload, libtrace_t::startcount, libtrace_packet_t::trace, trace_clear_cache(), TRACE_CTRL_PACKET, trace_get_capture_length(), trace_get_framing_length(), libtrace_packet_t::type, and libtrace_packet_t::which_trace_start.
Referenced by libtrace_make_packet_safe(), store_first_packet(), and trace_apply_filter().
| DLLEXPORT libtrace_t* trace_create | ( | const char * | uri | ) |
Create an input trace from a URI.
- Parameters
-
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 occurred when attempting to open the trace file, a trace is still returned so trace_is_err() should be called to find out if an error occurred. The trace is created in the configuration state, you must call trace_start before attempting to read packets from the trace.
References libtrace_t::accepted_packets, ASSERT_RET, libtrace_t::err, trace_err_t::err_num, libtrace_t::event, libtrace_t::filter, libtrace_t::filtered_packets, libtrace_t::format, libtrace_t::global_blob, libtrace_t::hasher, libtrace_format_t::init_input, libtrace_t::io, libtrace_t::last_packet, libtrace_t::libtrace_lock, libtrace_format_t::name, libtrace_format_t::next, libtrace_event_status_t::packet, libtrace_t::packet_freelist, libtrace_t::perpkt_cond, libtrace_t::perpkt_queue_full, libtrace_t::pread, trace_err_t::problem, libtrace_event_status_t::psize, libtrace_t::read_packet_lock, libtrace_t::replayspeedup, libtrace_t::sequence_number, libtrace_t::snaplen, libtrace_t::startcount, libtrace_t::started, libtrace_t::state, strncasecmp(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_NOERROR, TRACE_ERR_UNSUPPORTED, trace_parse_uri(), trace_set_err(), libtrace_t::uridata, and libtrace_event_status_t::waiting.
| DLLEXPORT libtrace_t* trace_create_dead | ( | const char * | uri | ) |
Creates a "dummy" trace file that has only the format type set.
- Parameters
-
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::read_packet_lock, libtrace_t::sequence_number, libtrace_t::snaplen, libtrace_t::started, libtrace_t::state, strncasecmp(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_NOERROR, trace_set_err(), and libtrace_t::uridata.
Referenced by demote_packet(), and trace_construct_packet().
| DLLEXPORT SIMPLE_FUNCTION libtrace_filter_t* trace_create_filter | ( | const char * | filterstring | ) |
Creates a BPF filter.
- Parameters
-
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.
| 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.
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.
| 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 occurred when attempting to open the output trace, a trace is still returned but trace_errno will be set. Use trace_is_err_out() and trace_perror_output() to get more information.
References libtrace_out_t::err, trace_err_t::err_num, libtrace_out_t::format, libtrace_format_t::init_output, libtrace_format_t::name, libtrace_format_t::next, trace_err_t::problem, libtrace_out_t::started, strncasecmp(), TRACE_ERR_BAD_FORMAT, TRACE_ERR_NOERROR, TRACE_ERR_UNSUPPORTED, trace_parse_uri(), trace_set_err_out(), and libtrace_out_t::uridata.
| DLLEXPORT libtrace_packet_t* trace_create_packet | ( | void | ) |
Create a new packet object.
- Returns
- A pointer to an initialised libtrace_packet_t object, or NULL if libtrace is unable to allocate space for a new packet.
References libtrace_packet_t::buf_control, libtrace_packet_t::ref_lock, trace_clear_cache(), TRACE_CTRL_PACKET, and libtrace_packet_t::which_trace_start.
Referenced by trace_event_trace(), and trace_pstart().
| DLLEXPORT libtrace_stat_t* trace_create_statistics | ( | void | ) |
Creates and returns a zeroed libtrace_stat_t structure.
This allows us to add extra fields increasing the size of the structure without breaking existing libtrace applications.
This structure should be free'd using free().
- Returns
- A valid pointer to a libtrace_stat_t struct otherwise NULL if memory was not available.
References libtrace_stat_t::magic.
Referenced by trace_get_statistics(), and trace_ppause().
| DLLEXPORT void trace_destroy | ( | 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::read_packet_lock, libtrace_t::started, libtrace_t::state, trace_destroy_callback_set(), trace_destroy_packet(), trace_fin_packet(), and libtrace_t::uridata.
| 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 libtrace_t::read_packet_lock.
| 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.
| 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, and libtrace_out_t::uridata.
| 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::ref_lock, libtrace_packet_t::trace, and TRACE_CTRL_PACKET.
Referenced by trace_apply_filter(), trace_destroy(), 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.
| 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().
| 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_IOWAIT, and trace_fin_packet().
Referenced by register_format().
| DLLEXPORT int trace_flush_output | ( | libtrace_out_t * | libtrace | ) |
Flush an output trace, forcing any buffered packets to be written.
- Parameters
-
libtrace The output trace to be flushed
References libtrace_format_t::flush_output, and libtrace_out_t::format.
| DLLEXPORT DEPRECATED uint64_t trace_get_accepted_packets | ( | libtrace_t * | trace | ) |
Returns the number of packets that have been read from the input trace using trace_read_packet().
- Parameters
-
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.
| 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_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.
Referenced by demote_packet(), promote_packet(), trace_copy_packet(), trace_get_ip(), trace_get_ip6(), trace_get_packet_buffer(), and trace_strip_packet().
| DLLEXPORT SIMPLE_FUNCTION struct sockaddr* trace_get_destination_address | ( | const libtrace_packet_t * | packet, |
| struct sockaddr * | addr | ||
| ) |
Get the destination IP address for a given packet.
- Parameters
-
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_ip::ip_dst, libtrace_ip6::ip_dst, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_ip(), and trace_get_payload_from_ip6().
Referenced by trace_get_destination_address_string().
| DLLEXPORT SIMPLE_FUNCTION char* trace_get_destination_address_string | ( | const libtrace_packet_t * | packet, |
| char * | space, | ||
| int | spacelen | ||
| ) |
Get the destination IP address for a packet and convert it into a string.
- Parameters
-
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().
| 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_layer2(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.
| DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_destination_port | ( | const libtrace_packet_t * | packet | ) |
Gets the destination port for a given packet.
- Parameters
-
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_fragment_offset(), trace_get_transport(), TRACE_IPPROTO_ICMP, and TRACE_IPPROTO_ICMPV6.
| DLLEXPORT SIMPLE_FUNCTION libtrace_direction_t trace_get_direction | ( | const libtrace_packet_t * | packet | ) |
Get the direction flag for a packet, if it has one.
- Parameters
-
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_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.
| DLLEXPORT DEPRECATED uint64_t trace_get_dropped_packets | ( | libtrace_t * | trace | ) |
Returns the number of packets that have been dropped on an input trace due to lack of buffer space on the capturing device.
- Parameters
-
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_statistics(), and UINT64_MAX.
| DLLEXPORT SIMPLE_FUNCTION uint64_t trace_get_erf_timestamp | ( | const libtrace_packet_t * | packet | ) |
Get the packet timestamp in the DAG time format.
- Parameters
-
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_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.
| DLLEXPORT libtrace_err_t trace_get_err | ( | libtrace_t * | trace | ) |
Check (and clear) the current error state of an input trace.
- Parameters
-
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, and trace_err_t::problem.
Referenced by trace_config().
| DLLEXPORT void DLLEXPORT libtrace_err_t trace_get_err_output | ( | libtrace_out_t * | trace | ) |
Checks (and clears) the current error state for an output trace.
- Parameters
-
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_ERR_NOERROR.
| DLLEXPORT DEPRECATED uint64_t trace_get_filtered_packets | ( | libtrace_t * | trace | ) |
Returns the number of packets that were captured, but discarded for not matching a provided filter.
- Parameters
-
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_statistics(), and UINT64_MAX.
| DLLEXPORT SIMPLE_FUNCTION unsigned char* trace_get_first_ospf_link_from_router_lsa_v2 | ( | libtrace_ospf_router_lsa_v2_t * | lsa, |
| uint32_t * | remaining | ||
| ) |
Get a pointer to the start of the first link contained within a Router LSA.
- Parameters
-
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 subsequently used to process the links
| DLLEXPORT SIMPLE_FUNCTION unsigned char* trace_get_first_ospf_lsa_from_db_desc_v2 | ( | libtrace_ospf_db_desc_v2_t * | db_desc, |
| uint32_t * | remaining | ||
| ) |
Get a pointer to the start of the first LSA contained within an Database Description packet.
- Parameters
-
db_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 subsequently used to process the LSA headers
| DLLEXPORT SIMPLE_FUNCTION unsigned char* trace_get_first_ospf_lsa_from_update_v2 | ( | libtrace_ospf_ls_update_t * | ls_update, |
| uint32_t * | remaining | ||
| ) |
Get a pointer to the start of the first LSA contained within an LS Update packet.
- Parameters
-
ls_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 subsequently used to process the LSAs
| DLLEXPORT enum base_format_t trace_get_format | ( | struct libtrace_packet_t * | packet | ) |
Gets the capture format for a given packet.
- Parameters
-
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, and libtrace_format_t::type.
| DLLEXPORT uint16_t trace_get_fragment_offset | ( | const libtrace_packet_t * | packet, |
| uint8_t * | more | ||
| ) |
Calculates the fragment offset in bytes for an IP packet.
- Parameters
-
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_layer3(), TRACE_IPPROTO_AH, TRACE_IPPROTO_DSTOPTS, TRACE_IPPROTO_FRAGMENT, and TRACE_IPPROTO_ROUTING.
Referenced by trace_get_destination_port(), and trace_get_source_port().
| DLLEXPORT SIMPLE_FUNCTION size_t trace_get_framing_length | ( | const libtrace_packet_t * | packet | ) |
Get the length of the capture framing headers (in bytes).
- Parameters
-
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_packet_t::framing_length, libtrace_format_t::get_framing_length, libtrace_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.
Referenced by promote_packet(), and trace_copy_packet().
| DLLEXPORT SIMPLE_FUNCTION libtrace_icmp_t* trace_get_icmp | ( | libtrace_packet_t * | packet | ) |
Get a pointer to the ICMP header (if present)
- Parameters
-
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_transport(), and TRACE_IPPROTO_ICMP.
| DLLEXPORT SIMPLE_FUNCTION libtrace_icmp6_t* trace_get_icmp6 | ( | libtrace_packet_t * | packet | ) |
Get a pointer to the ICMPv6 header (if present)
- Parameters
-
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_transport(), and TRACE_IPPROTO_ICMPV6.
| DLLEXPORT SIMPLE_FUNCTION libtrace_icmp_t* trace_get_icmp_from_ip | ( | libtrace_ip_t * | ip, |
| uint32_t * | remaining | ||
| ) |
Get a pointer to the ICMP header following an IPv4 header (if present)
- Parameters
-
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_payload_from_ip(), and TRACE_IPPROTO_ICMP.
| DLLEXPORT SIMPLE_FUNCTION libtrace_ip_t* trace_get_ip | ( | libtrace_packet_t * | packet | ) |
Get a pointer to the IPv4 header (if any) for a given packet.
- Parameters
-
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(), and trace_get_layer3().
| DLLEXPORT SIMPLE_FUNCTION libtrace_ip6_t* trace_get_ip6 | ( | libtrace_packet_t * | packet | ) |
get a pointer to the IPv6 header (if any)
- Parameters
-
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(), and trace_get_layer3().
| DLLEXPORT void* trace_get_layer2 | ( | const libtrace_packet_t * | packet, |
| libtrace_linktype_t * | linktype, | ||
| uint32_t * | remaining | ||
| ) |
Get a pointer to the layer 2 header.
Generally this is the first byte of the packet as it was seen on the wire.
This function takes a libtrace packet and skips over any metadata headers if present (such as Linux SLL or Radiotap) and returns a pointer to the first byte of the packet that was actually received by the network interface.
- Parameters
-
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_packet_buffer(), trace_get_payload_from_meta(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.
Referenced by trace_get_destination_mac(), trace_get_layer3(), trace_get_source_mac(), and trace_strip_packet().
| DLLEXPORT void* trace_get_layer3 | ( | const libtrace_packet_t * | packet, |
| uint16_t * | ethertype, | ||
| uint32_t * | remaining | ||
| ) |
Get a pointer to the layer 3 (e.g.
IP) header.
- Parameters
-
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_payload_from_ethernet(), trace_get_payload_from_layer2(), trace_get_payload_from_mpls(), trace_get_payload_from_pppoe(), and trace_get_payload_from_vlan().
Referenced by promote_packet(), trace_checksum_layer3(), trace_checksum_transport(), trace_get_destination_address(), trace_get_fragment_offset(), trace_get_ip(), trace_get_ip6(), trace_get_payload_length(), trace_get_source_address(), and trace_get_transport().
| DLLEXPORT SIMPLE_FUNCTION DEPRECATED void* trace_get_link | ( | const libtrace_packet_t * | packet | ) |
Get a pointer to the link layer for a given packet.
- Parameters
-
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.
| 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_t::startcount, libtrace_packet_t::trace, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_UNKNOWN, and libtrace_packet_t::which_trace_start.
Referenced by demote_packet(), trace_apply_filter(), and trace_get_packet_buffer().
| DLLEXPORT int trace_get_next_option | ( | unsigned char ** | ptr, |
| int * | len, | ||
| unsigned char * | type, | ||
| unsigned char * | optlen, | ||
| unsigned char ** | data | ||
| ) |
Parses an IP or TCP option.
- Parameters
-
[in,out] 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.
| 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.
| 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_OSPF_LS_ASBR_SUMMARY, TRACE_OSPF_LS_EXTERNAL, TRACE_OSPF_LS_NETWORK, TRACE_OSPF_LS_ROUTER, and TRACE_OSPF_LS_SUMMARY.
| DLLEXPORT SIMPLE_FUNCTION int trace_get_next_ospf_lsa_v2 | ( | unsigned char ** | current, |
| libtrace_ospf_lsa_v2_t ** | lsa_hdr, | ||
| unsigned char ** | lsa_body, | ||
| uint32_t * | remaining, | ||
| uint8_t * | lsa_type, | ||
| uint16_t * | lsa_length | ||
| ) |
Parses an OSPF LSA and finds the next LSA (if there is one)
- Parameters
-
[in,out] 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_OSPF_LS_ASBR_SUMMARY, TRACE_OSPF_LS_EXTERNAL, TRACE_OSPF_LS_NETWORK, TRACE_OSPF_LS_ROUTER, and TRACE_OSPF_LS_SUMMARY.
| DLLEXPORT SIMPLE_FUNCTION void* trace_get_ospf_contents_v2 | ( | libtrace_ospf_v2_t * | header, |
| uint8_t * | ospf_type, | ||
| uint32_t * | remaining | ||
| ) |
Get a pointer to the contents of the OSPF packet after the OSPF header.
- Parameters
-
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 libtrace_ospf_v2_t::type.
| DLLEXPORT SIMPLE_FUNCTION void* trace_get_ospf_header | ( | libtrace_packet_t * | packet, |
| uint8_t * | version, | ||
| uint32_t * | remaining | ||
| ) |
Get a pointer to the OSPF header (if present)
- Parameters
-
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_transport(), and TRACE_IPPROTO_OSPF.
| DLLEXPORT SIMPLE_FUNCTION uint32_t trace_get_ospf_metric_from_as_external_lsa_v2 | ( | libtrace_ospf_as_external_lsa_v2_t * | as_lsa | ) |
Extracts the metric field from an AS External LSA packet.
- Parameters
-
as_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, and libtrace_ospf_as_external_lsa_t::metric_c.
| DLLEXPORT SIMPLE_FUNCTION uint32_t trace_get_ospf_metric_from_summary_lsa_v2 | ( | libtrace_ospf_summary_lsa_v2_t * | sum_lsa | ) |
Extracts the metric field from a Summary LSA packet.
- Parameters
-
sum_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, and libtrace_ospf_summary_lsa::metric_c.
| DLLEXPORT void* trace_get_packet_buffer | ( | const libtrace_packet_t * | packet, |
| libtrace_linktype_t * | linktype, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the first byte of the packet as it was captured and returns its corresponding linktype and capture length.
Use this function instead of the deprecated trace_get_link().
- Parameters
-
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_wire_length(), and TRACE_TYPE_CONTENT_INVALID.
Referenced by pcap_get_direction(), trace_apply_filter(), trace_get_layer2(), trace_get_packet_meta(), and trace_get_payload_length().
| DLLEXPORT void* trace_get_packet_meta | ( | const libtrace_packet_t * | packet, |
| libtrace_linktype_t * | linktype, | ||
| uint32_t * | remaining | ||
| ) |
Return a pointer to the first metadata header in a packet, if present.
This function takes a pointer to a libtrace packet and if any metadata headers exist, returns a pointer to the first one, along with its corresponding linktype.
If no metadata headers exist in the packet, NULL is returned.
A metadata header is a header that was prepended by the capturing device, such as a Linux SLL header, or a Radiotap wireless monitoring header. Subsequent metadata headers may be accessed with the trace_get_payload_from_meta(...) function.
- Parameters
-
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_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.
| DLLEXPORT void* trace_get_payload_from_gre | ( | libtrace_gre_t * | gre, |
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a GRE header.
- Parameters
-
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.
| 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.
Referenced by trace_checksum_transport().
| DLLEXPORT void* trace_get_payload_from_icmp6 | ( | libtrace_icmp6_t * | icmp, |
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a ICMPv6 header.
- Parameters
-
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.
| 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, and libtrace_ip::ip_v.
Referenced by trace_get_destination_address(), trace_get_icmp_from_ip(), trace_get_source_address(), trace_get_tcp_from_ip(), trace_get_transport(), and trace_get_udp_from_ip().
| DLLEXPORT void* trace_get_payload_from_ip6 | ( | libtrace_ip6_t * | ipptr, |
| uint8_t * | proto, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following an IPv6 header.
- Parameters
-
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_IPPROTO_AH, TRACE_IPPROTO_DSTOPTS, TRACE_IPPROTO_ESP, TRACE_IPPROTO_FRAGMENT, and TRACE_IPPROTO_ROUTING.
Referenced by trace_get_destination_address(), trace_get_source_address(), and trace_get_transport().
| DLLEXPORT void* trace_get_payload_from_layer2 | ( | void * | l2, |
| libtrace_linktype_t | linktype, | ||
| uint16_t * | ethertype, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the next header following a layer 2 header.
- Parameters
-
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_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_payload_from_atm(), trace_get_payload_from_ethernet(), TRACE_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.
Referenced by trace_get_layer3(), and trace_get_payload_from_link().
| DLLEXPORT void* trace_get_payload_from_link | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint16_t * | type, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a link header.
- Parameters
-
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(), and trace_get_payload_from_meta().
| DLLEXPORT void* trace_get_payload_from_meta | ( | const void * | meta, |
| libtrace_linktype_t * | linktype, | ||
| uint32_t * | remaining | ||
| ) |
Returns the payload of a metadata header.
This function takes a pointer to the start of a metadata header (either obtained via trace_get_packet_meta(...) or by a previous call to trace_get_payload_from_meta(...)) along with its corresponding linktype and returns the payload, i.e. the next header. It will also update the linktype parameter to indicate the type of payload.
If the linktype indicates that the header passed in is not a metadata header, the function returns NULL to indicate this. The linktype remains unchanged in this case.
This function allows the user to iterate through metadata headers which are sometimes present before the actual packet as it was received on the wire. Examples of metadata headers include the Linux SLL header and the Radiotap wireless monitoring header.
If the metadata header passed into this function is truncated, this function will return NULL, and remaining will be set to 0.
If there are 0 bytes of payload following the provided metadata header, the function will return a pointer to where the header would otherwise be and remaining will be 0.
Therefore, be sure to check the value of remaining after calling this function!
- Parameters
-
[in] 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_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.
Referenced by trace_get_layer2(), and trace_get_payload_from_link().
| DLLEXPORT void* trace_get_payload_from_mpls | ( | void * | mpls, |
| uint16_t * | type, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following an MPLS header.
- Parameters
-
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_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, and TRACE_ETHERTYPE_MPLS.
Referenced by trace_get_layer3(), and trace_strip_packet().
| DLLEXPORT void* trace_get_payload_from_pppoe | ( | void * | pppoe, |
| uint16_t * | type, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a PPPoE header.
- Parameters
-
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.
Referenced by trace_get_layer3(), and trace_strip_packet().
| DLLEXPORT void* trace_get_payload_from_tcp | ( | libtrace_tcp_t * | tcp, |
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a TCP header.
- Parameters
-
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.
Referenced by trace_checksum_transport().
| DLLEXPORT void* trace_get_payload_from_udp | ( | libtrace_udp_t * | udp, |
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a UDP header.
- Parameters
-
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.
Referenced by trace_checksum_transport(), and trace_get_vxlan_from_udp().
| DLLEXPORT void* trace_get_payload_from_vlan | ( | void * | vlan, |
| uint16_t * | type, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following an 802.1q (VLAN) header.
- Parameters
-
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 libtrace_8021q::vlan_ether_type.
Referenced by trace_get_layer3(), and trace_strip_packet().
| DLLEXPORT void* trace_get_payload_from_vxlan | ( | libtrace_vxlan_t * | vxlan, |
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a VXLAN header.
- Parameters
-
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.
| 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_packet_buffer(), trace_get_transport(), TRACE_IPPROTO_ICMP, TRACE_IPPROTO_ICMPV6, TRACE_IPPROTO_IPV6, TRACE_IPPROTO_TCP, and TRACE_IPPROTO_UDP.
Referenced by trace_checksum_transport().
| DLLEXPORT void DLLEXPORT DEPRECATED uint64_t trace_get_received_packets | ( | libtrace_t * | trace | ) |
Returns the number of packets observed on an input trace.
Includes the number of packets counted as early as possible, before filtering, and includes dropped packets.
- Parameters
-
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_statistics(), and UINT64_MAX.
| DLLEXPORT SIMPLE_FUNCTION double trace_get_seconds | ( | const libtrace_packet_t * | packet | ) |
Get the packet timestamp in floating point seconds.
- Parameters
-
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_t::startcount, libtrace_packet_t::trace, and libtrace_packet_t::which_trace_start.
Referenced by trace_event_trace().
| DLLEXPORT SIMPLE_FUNCTION int8_t trace_get_server_port | ( | uint8_t | protocol, |
| uint16_t | source, | ||
| uint16_t | dest | ||
| ) |
Hint at which of the two provided ports is the server port.
- Parameters
-
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 | ||
| ) |
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_ip::ip_src, libtrace_ip6::ip_src, ports_t::src, TRACE_ETHERTYPE_IP, TRACE_ETHERTYPE_IPV6, trace_get_layer3(), trace_get_payload_from_ip(), and trace_get_payload_from_ip6().
Referenced by trace_get_source_address_string().
| DLLEXPORT SIMPLE_FUNCTION char* trace_get_source_address_string | ( | const libtrace_packet_t * | packet, |
| char * | space, | ||
| int | spacelen | ||
| ) |
Get the source IP address for a packet and convert it into a string.
- Parameters
-
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().
| 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_TYPE_80211, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, TRACE_TYPE_AAL5, TRACE_TYPE_ATM, TRACE_TYPE_CONTENT_INVALID, TRACE_TYPE_DUCK, TRACE_TYPE_ERF_META, TRACE_TYPE_ETH, TRACE_TYPE_ETSILI, TRACE_TYPE_HDLC_POS, TRACE_TYPE_LINUX_SLL, TRACE_TYPE_LLCSNAP, TRACE_TYPE_METADATA, TRACE_TYPE_NONDATA, TRACE_TYPE_NONE, TRACE_TYPE_OPENBSD_LOOP, TRACE_TYPE_PFLOG, TRACE_TYPE_POS, TRACE_TYPE_PPP, and TRACE_TYPE_UNKNOWN.
| DLLEXPORT SIMPLE_FUNCTION uint16_t trace_get_source_port | ( | const libtrace_packet_t * | packet | ) |
Gets the source port for a given packet.
- Parameters
-
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_transport(), TRACE_IPPROTO_ICMP, and TRACE_IPPROTO_ICMPV6.
| DLLEXPORT libtrace_stat_t* trace_get_statistics | ( | libtrace_t * | trace, |
| libtrace_stat_t * | stats | ||
| ) |
Returns statistic counters for a trace, for a parallel trace this is a combined total.
Where possible these are retrieved atomically, however this behaviour depends on the underlying trace format.
- Parameters
-
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_FIELDS, libtrace_stat_t::magic, libtrace_stat_t::reserved1, libtrace_stat_t::reserved2, libtrace_t::state, and trace_create_statistics().
Referenced by trace_get_dropped_packets(), trace_get_filtered_packets(), trace_get_received_packets(), and trace_ppause().
| DLLEXPORT SIMPLE_FUNCTION libtrace_tcp_t* trace_get_tcp | ( | libtrace_packet_t * | packet | ) |
Get a pointer to the TCP header (if present)
- Parameters
-
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_transport(), and TRACE_IPPROTO_TCP.
| DLLEXPORT SIMPLE_FUNCTION libtrace_tcp_t* trace_get_tcp_from_ip | ( | libtrace_ip_t * | ip, |
| uint32_t * | remaining | ||
| ) |
Get a pointer to the TCP header following an IPv4 header (if present)
- Parameters
-
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(), and TRACE_IPPROTO_TCP.
| DLLEXPORT void trace_get_thread_statistics | ( | libtrace_t * | trace, |
| libtrace_thread_t * | t, | ||
| libtrace_stat_t * | stats | ||
| ) |
Returns statistic counters for a single thread of a trace.
Where possible these are retrieved atomically, however this behaviour depends on the underlying trace format.
- Parameters
-
trace The input trace to examine. t An optional thread to received stats for or NULL to retrieve 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_FIELDS, libtrace_stat_t::magic, libtrace_stat_t::reserved1, libtrace_stat_t::reserved2, and trace_has_dedicated_hasher().
| DLLEXPORT SIMPLE_FUNCTION struct timespec trace_get_timespec | ( | const libtrace_packet_t * | packet | ) |
Get the packet timestamp as a struct timespec.
- Parameters
-
packet The packet to extract the timestamp from
- Returns
- The time that this packet was captured in a struct timespec
| DLLEXPORT SIMPLE_FUNCTION struct timeval trace_get_timeval | ( | const libtrace_packet_t * | packet | ) |
Get the packet timestamp as a struct timeval.
- Parameters
-
packet The packet to extract the timestamp from
- Returns
- The time that this packet was captured in a struct timeval
Referenced by demote_packet(), and store_first_packet().
| DLLEXPORT void* trace_get_transport | ( | const libtrace_packet_t * | packet, |
| uint8_t * | proto, | ||
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the transport layer header (if any)
- Parameters
-
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_IPPROTO_IPV6, and libtrace_packet_t::transport_proto.
Referenced by trace_checksum_transport(), trace_get_destination_port(), trace_get_icmp(), trace_get_icmp6(), trace_get_ospf_header(), trace_get_payload_length(), trace_get_source_port(), trace_get_tcp(), and trace_get_udp().
| DLLEXPORT SIMPLE_FUNCTION libtrace_udp_t* trace_get_udp | ( | libtrace_packet_t * | packet | ) |
Get a pointer to the UDP header (if present)
- Parameters
-
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(), and TRACE_IPPROTO_UDP.
| DLLEXPORT SIMPLE_FUNCTION libtrace_udp_t* trace_get_udp_from_ip | ( | libtrace_ip_t * | ip, |
| uint32_t * | remaining | ||
| ) |
Get a pointer to the UDP header following an IPv4 header (if present)
- Parameters
-
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(), and TRACE_IPPROTO_UDP.
| DLLEXPORT libtrace_vxlan_t* trace_get_vxlan_from_udp | ( | libtrace_udp_t * | udp, |
| uint32_t * | remaining | ||
| ) |
Gets a pointer to the payload following a VXLAN header.
- Parameters
-
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, and trace_get_payload_from_udp().
| DLLEXPORT SIMPLE_FUNCTION size_t trace_get_wire_length | ( | const libtrace_packet_t * | packet | ) |
Get the size of the packet as it was originally seen on the wire (in bytes).
- Parameters
-
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_t::startcount, libtrace_packet_t::trace, libtrace_packet_t::which_trace_start, and libtrace_packet_t::wire_length.
Referenced by demote_packet(), and trace_get_packet_buffer().
| DLLEXPORT bool trace_get_wireless_antenna | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint8_t * | antenna | ||
| ) |
Get the wireless antenna.
- Parameters
-
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_RADIOTAP_ANTENNA, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_freq | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint16_t * | freq | ||
| ) |
Get the wireless channel frequency.
- Parameters
-
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_RADIOTAP_CHANNEL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_noise_strength_db | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint8_t * | strength | ||
| ) |
Get the wireless noise strength in dB.
- Parameters
-
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_RADIOTAP_DB_ANTNOISE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_noise_strength_dbm | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| int8_t * | strength | ||
| ) |
Get the wireless noise strength in dBm.
- Parameters
-
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_RADIOTAP_DBM_ANTNOISE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_rate | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint8_t * | rate | ||
| ) |
Get the wireless data rate.
- Parameters
-
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_RADIOTAP_RATE, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_signal_strength_db | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint8_t * | strength | ||
| ) |
Get the wireless signal strength in dB.
- Parameters
-
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_RADIOTAP_DB_ANTSIGNAL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_signal_strength_dbm | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| int8_t * | strength | ||
| ) |
Get the wireless signal strength in dBm.
- Parameters
-
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_RADIOTAP_DBM_ANTSIGNAL, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_tsft | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint64_t * | tsft | ||
| ) |
Get the wireless Timer Synchronisation Function.
Gets the value of the timer synchronisation function for this frame, which is a value in microseconds indicating the time that the first bit of the MPDU was received by the MAC.
- Parameters
-
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_RADIOTAP_TSFT, TRACE_TYPE_80211_PRISM, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_tx_attenuation | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint16_t * | attenuation | ||
| ) |
Get the wireless transmit attenuation.
- Parameters
-
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_RADIOTAP_TX_ATTENUATION, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_tx_attenuation_db | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| uint16_t * | attenuation | ||
| ) |
Get the wireless transmit attenuation in dB.
- Parameters
-
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_RADIOTAP_DB_TX_ATTENUATION, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT bool trace_get_wireless_tx_power_dbm | ( | void * | linkptr, |
| libtrace_linktype_t | linktype, | ||
| int8_t * | txpower | ||
| ) |
Get the wireless transmit power in dBm.
- Parameters
-
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_RADIOTAP_DBM_TX_POWER, TRACE_TYPE_80211_RADIO, and TRACE_TYPE_LINUX_SLL.
| DLLEXPORT void trace_help | ( | void | ) |
Prints help information for libtrace.
Function prints out some basic help information regarding libtrace, and then prints out the help() function registered with each input module
References libtrace_format_t::help, and libtrace_format_t::next.
| DLLEXPORT void trace_interrupt | ( | void | ) |
Causes a libtrace reader to stop blocking whilst waiting on new packets and immediately return EOF.
This function is useful if you are handling signals within your libtrace program. If a live source is not receiving any packets (or they are being filtered), a call to trace_read_packet will result in an infinite loop as it will block until a packet is received. Normally, a SIGINT would cause the program to end and thus break the loop, but if you are handling the signal yourself then that signal will never reach libtrace.
Instead this function sets a global variable within libtrace that will cause a blocking live capture to break on the next internal timeout, allowing control to be returned to the user and their own signal handling to kick in.
References libtrace_halt.
| DLLEXPORT bool trace_is_err | ( | libtrace_t * | trace | ) |
Indicate if there has been an error on an input trace.
- Parameters
-
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, and trace_err_t::err_num.
Referenced by trace_config(), trace_event_device(), trace_event_trace(), trace_pstart(), trace_read_packet(), and trace_start().
| DLLEXPORT bool trace_is_err_output | ( | libtrace_out_t * | trace | ) |
Indicates if there is an error on an output trace.
- Parameters
-
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, and trace_err_t::err_num.
| DLLEXPORT const char* trace_parse_uri | ( | const char * | uri, |
| char ** | format | ||
| ) |
Takes a uri and splits it into a format and uridata component.
- Parameters
-
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 occurred, otherwise return a pointer to the uridata component
- Note
- The format component is strdup'd by this function, so be sure to free it when you are done with the split URI. Similarly, do not pass a pointer to an allocated string into this function as the 'format' parameter, as that memory will be leaked and replaced with the strdup'd format.
Referenced by trace_create(), and trace_create_output().
| DLLEXPORT int trace_pause | ( | libtrace_t * | libtrace | ) |
Pauses an input trace.
- Parameters
-
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(), and trace_set_err().
Referenced by trace_ppause().
| DLLEXPORT void trace_perror | ( | libtrace_t * | trace, |
| const char * | msg, | ||
| ... | |||
| ) |
Outputs the error message for an input trace to stderr and clear the error status.
- Parameters
-
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_prepare_packet | ( | libtrace_t * | trace, |
| libtrace_packet_t * | packet, | ||
| void * | buffer, | ||
| libtrace_rt_types_t | rt_type, | ||
| uint32_t | flags | ||
| ) |
Converts the data provided in buffer into a valid libtrace packet.
- Parameters
-
trace An input trace of the same format as the "packet" contained in the buffer packet The libtrace packet to prepare buffer A buffer containing the packet data, including the capture format header rt_type The RT type for the packet that is being prepared flags Used to specify options for the preparation function, e.g. who owns the packet buffer
- Returns
- -1 if an error occurs, 0 otherwise
Packet preparation is a tricky concept - the idea is to take the data pointed to by 'buffer' and treat it as a packet record of the same capture format as that used by the input trace. The provided libtrace packet then has its internal pointers and values set to describe the packet record in the buffer.
The primary use of this function is to allow the RT packet reader to easily and safely convert packets from the RT format back into the format that they were originally captured with., essentially removing the RT encapsulation.
This function is now available via the exported API, as it can have some uses outside of internal libtrace contexts. However, we strongly advise that you avoid using this function unless you really know what you are doing.
References libtrace_packet_t::buf_control, libtrace_t::format, libtrace_t::last_packet, libtrace_format_t::prepare_packet, libtrace_packet_t::trace, trace_clear_cache(), TRACE_CTRL_EXTERNAL, TRACE_CTRL_PACKET, TRACE_ERR_BAD_STATE, TRACE_ERR_UNSUPPORTED, and trace_set_err().
| DLLEXPORT int trace_print_statistics | ( | const libtrace_stat_t * | s, |
| FILE * | f, | ||
| const char * | format | ||
| ) |
Prints all valid stats to a file stream, (which could be stdout/err).
By default the format "name: value" is used.
- Parameters
-
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, and libtrace_stat_t::magic.
| DLLEXPORT int trace_read_packet | ( | libtrace_t * | trace, |
| libtrace_packet_t * | packet | ||
| ) |
Read the next packet from an input trace.
- Parameters
-
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_packet_t::order, libtrace_format_t::read_packet, libtrace_t::sequence_number, libtrace_t::snaplen, libtrace_t::startcount, libtrace_t::started, libtrace_packet_t::trace, trace_apply_filter(), TRACE_CTRL_EXTERNAL, TRACE_CTRL_PACKET, TRACE_ERR_BAD_STATE, TRACE_ERR_UNSUPPORTED, trace_fin_packet(), trace_is_err(), trace_packet_set_order(), trace_set_capture_length(), trace_set_err(), and libtrace_packet_t::which_trace_start.
Referenced by trace_event_device(), and trace_event_trace().
| DLLEXPORT int trace_seek_erf_timestamp | ( | libtrace_t * | trace, |
| uint64_t | ts | ||
| ) |
Seek within an input trace to a time specified as an ERF timestamp.
- Parameters
-
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, and trace_set_err().
| DLLEXPORT int trace_seek_seconds | ( | libtrace_t * | trace, |
| double | seconds | ||
| ) |
Seek within an input trace to a time specified in floating point seconds.
- Parameters
-
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, and trace_set_err().
| DLLEXPORT int trace_seek_timeval | ( | libtrace_t * | trace, |
| struct timeval | tv | ||
| ) |
Seek within an input trace to a time specified as a timeval.
- Parameters
-
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, and trace_set_err().
| DLLEXPORT size_t trace_set_capture_length | ( | libtrace_packet_t * | packet, |
| size_t | size | ||
| ) |
Truncate ("snap") the packet to the suggested length.
- Parameters
-
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, and libtrace_packet_t::trace.
Referenced by demote_packet(), trace_read_packet(), and trace_strip_packet().
| DLLEXPORT libtrace_direction_t trace_set_direction | ( | libtrace_packet_t * | packet, |
| libtrace_direction_t | direction | ||
| ) |
Set the direction flag for a packet, if the capture format supports direction tagging.
- Parameters
-
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, and libtrace_packet_t::trace.
| DLLEXPORT int trace_set_event_realtime | ( | libtrace_t * | trace, |
| bool | realtime | ||
| ) |
If enabled, the libtrace event API will ignore time gaps between packets when reading from a trace file.
- Parameters
-
libtrace The trace object to apply the option to realtime True ignores gaps
- Returns
- -1 if option configuration failed, 0 otherwise
References trace_config(), and TRACE_OPTION_EVENT_REALTIME.
| DLLEXPORT int trace_set_filter | ( | libtrace_t * | trace, |
| libtrace_filter_t * | filter | ||
| ) |
Apply this filter to all packets read from this trace.
- Parameters
-
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(), and TRACE_OPTION_FILTER.
| DLLEXPORT int trace_set_meta_freq | ( | libtrace_t * | trace, |
| int | freq | ||
| ) |
Defines the frequency of meta-data reporting, e.g.
DUCK packets
- Parameters
-
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(), and TRACE_OPTION_META_FREQ.
| DLLEXPORT int trace_set_promisc | ( | libtrace_t * | trace, |
| bool | promisc | ||
| ) |
If enabled, places a live capture interface into promiscuous mode.
- Parameters
-
libtrace The trace object to apply the option to promisc
- Returns
- -1 if option configuration failed, 0 otherwise
References trace_config(), and TRACE_OPTION_PROMISC.
| DLLEXPORT int trace_set_snaplen | ( | libtrace_t * | trace, |
| int | snaplen | ||
| ) |
Maximum number of bytes to be captured for any given packet.
- Parameters
-
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(), and TRACE_OPTION_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::startcount, libtrace_t::started, and trace_is_err().
| 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, and libtrace_out_t::started.
| DLLEXPORT libtrace_packet_t* trace_strip_packet | ( | libtrace_packet_t * | packet | ) |
Strips layer 2.5 headers from a given packet.
- Parameters
-
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(), and TRACE_TYPE_ETH.
| DLLEXPORT void trace_subtract_statistics | ( | const libtrace_stat_t * | a, |
| const libtrace_stat_t * | b, | ||
| libtrace_stat_t * | c | ||
| ) |
Performs the operation c=a-b accounting for valid fields.
c is allowed to be a or b.
- Parameters
-
a The minuend b The subtrahend c The resulting difference
References LIBTRACE_STAT_FIELDS, and libtrace_stat_t::magic.
| DLLEXPORT int trace_write_packet | ( | libtrace_out_t * | trace, |
| libtrace_packet_t * | packet | ||
| ) |
Write one packet out to the output trace.
- Parameters
-
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_t::format, libtrace_out_t::format, libtrace_format_t::name, libtrace_out_t::started, libtrace_packet_t::trace, TRACE_ERR_BAD_STATE, TRACE_ERR_UNSUPPORTED, trace_set_err_out(), and libtrace_format_t::write_packet.
