source: lib/libtrace.h.in @ 5ab626a

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 5ab626a was 5ab626a, checked in by Richard Sanger <rsangerarj@…>, 6 years ago

Deprecate trace_get_filtered/accepted/recevied/dropped() in favour of a single function

Adds the single trace_get_statistics function. This allows the structure to be filled
at a point in time, rather than making multiple calls to the library during which state
might have changed.

This has been designed such that the structure can be added to in the future without
breaking old code.

The old internal get_captured_packets was removed from the formats as it was never used.
Eventually we should completely remove get_filtered and received from the formats and replace
them with get_statistics.

In additon some extra fields have added, such as error and captured and the pre-existing
fields are better defined.

The linux formats have been updated to use this new API, which combined with reading
/proc/net/dev returns a full set of statistics.

  • Property mode set to 100644
File size: 152.8 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
7 * Authors: Daniel Lawson
8 *          Perry Lorier
9 *          Shane Alcock
10 *         
11 * All rights reserved.
12 *
13 * This code has been developed by the University of Waikato WAND
14 * research group. For further information please see http://www.wand.net.nz/
15 *
16 * libtrace is free software; you can redistribute it and/or modify
17 * it under the terms of the GNU General Public License as published by
18 * the Free Software Foundation; either version 2 of the License, or
19 * (at your option) any later version.
20 *
21 * libtrace is distributed in the hope that it will be useful,
22 * but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24 * GNU General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with libtrace; if not, write to the Free Software
28 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29 *
30 * $Id$
31 *
32 */
33
34#ifndef LIBTRACE_H
35#define LIBTRACE_H
36
37/** @file
38 *
39 * @brief Trace file processing library header
40 *
41 * @author Daniel Lawson
42 * @author Perry Lorier
43 * @author Shane Alcock
44 *
45 * @version $Id$
46 *
47 * This library provides a per packet interface into a trace file, or a live
48 * captures.  It supports ERF, DAG cards, PCAP, Linux and BSD native sockets,
49 * legacy ERF formats etc.
50 *
51 * @par Usage
52 * See the example/ directory in the source distribution for some simple
53 * examples
54 *
55 * @par Linking
56 * To use this library you need to link against libtrace by passing -ltrace
57 * to your linker. You may also need to link against a version of libpcap
58 * and of zlib which are compiled for largefile support (if you wish to access
59 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
60 * Woody, at least, does not support large file offsets.
61 *
62 */
63
64#include <sys/types.h>
65#include <stddef.h>
66#include <stdio.h>
67/* Compile time assertion. Sourced from:
68 * http://www.pixelbeat.org/programming/gcc/static_assert.html */
69#define ct_assert(e) extern char (*ct_assert(void)) [sizeof(char[1 - 2*!(e)])]
70
71#ifndef WIN32
72#include <sys/time.h>
73#endif
74
75/* Deal with missing byte order macros */
76#include <sys/param.h>
77
78#if defined(BYTE_ORDER) && !defined(__BYTE_ORDER)
79#define __BYTE_ORDER    BYTE_ORDER
80#endif
81
82#if defined(BIG_ENDIAN) && !defined(__BIG_ENDIAN)
83#define __BIG_ENDIAN    BIG_ENDIAN
84#endif
85
86#if defined(LITTLE_ENDIAN) && !defined(__LITTLE_ENDIAN)
87#define __LITTLE_ENDIAN LITTLE_ENDIAN
88#endif
89
90#ifdef WIN32
91#   include <winsock2.h>
92#   include <ws2tcpip.h>
93    typedef short sa_family_t;
94    /* Make up for a lack of stdbool.h */
95#    define bool signed char
96#    define false 0
97#    define true 1
98#    if !defined(ssize_t)
99     /* XXX: Not 64-bit safe! */
100#    define ssize_t int
101#    endif   
102#else
103#    include <netinet/in.h>
104
105#ifndef __cplusplus
106#    include <stdbool.h>
107#endif
108
109#    include <sys/types.h>
110#    include <sys/socket.h>
111#endif
112
113/** API version as 2 byte hex digits, eg 0xXXYYZZ */
114#define LIBTRACE_API_VERSION \
115            ((@LIBTRACE_MAJOR@<<16)|(@LIBTRACE_MID@<<8)|(@LIBTRACE_MINOR@))
116
117/** This used to be replaced with the current SVN revision number when
118 * 'make dist' was invoked to create a distributable tarball. We don't use
119 * SVN anymore and there probably isn't any need to know the exact revision
120 * number either these days. */
121#define LIBTRACE_SVN_REVISION LIBTRACE_API_VERSION
122
123/** DAG driver version installed on the current system */
124#define DAG_DRIVER_V "@DAG_VERSION_NUM@"
125
126/**
127  * A version of assert that always runs the first argument even
128  * when not debugging, however only asserts the condition if debugging
129  * Intended for use mainly with pthread locks etc. which have error
130  * returns but *should* never actually fail.
131  */
132#ifdef NDEBUG
133#define ASSERT_RET(run, cond) run
134#else
135#define ASSERT_RET(run, cond) assert(run cond)
136//#define ASSERT_RET(run, cond) run
137#endif
138   
139#ifdef __cplusplus
140extern "C" {
141#endif
142
143#ifdef _MSC_VER
144    /* define the following from MSVC's internal types */
145    typedef             __int8  int8_t;
146    typedef             __int16 int16_t;
147    typedef             __int32 int32_t;
148    typedef             __int64 int64_t;
149    typedef unsigned    __int8  uint8_t;
150    typedef unsigned    __int16 uint16_t;
151    typedef unsigned    __int32 uint32_t;
152    typedef unsigned    __int64 uint64_t;
153   
154    /* Windows pads bitfields out to to the size of their parent type
155     * however gcc warns that this doesn't meet with the iso C specification
156     * so produces warnings for this behaviour.  sigh.
157     */
158    #define LT_BITFIELD8        uint8_t
159    #define LT_BITFIELD16       uint16_t
160    #define LT_BITFIELD32       uint32_t
161    #define LT_BITFIELD64       uint64_t
162#else
163    #ifdef HAVE_STDINT_H
164        #   include <stdint.h>
165    #endif
166    /* GCC warns if the bitfield type is not "unsigned int", however windows
167     * generates incorrect code for this (see above), so we define these
168     * macros.  How Hideous.  So much for C's portability.
169     */
170    #define LT_BITFIELD8        unsigned int
171    #define LT_BITFIELD16       unsigned int
172    #define LT_BITFIELD32       unsigned int
173    #define LT_BITFIELD64       unsigned int
174#endif
175
176/* Ensure these gcc optimisation attributes are defined consistently,
177 * without requiring users to need to have access to the config.h
178 * generated by running configure.
179 */
180
181#define LT_USE_PACKED @HAVE_ATTRIBUTE_PACKED@
182#define LT_USE_UNUSED @HAVE_ATTRIBUTE_UNUSED@
183#define LT_USE_DEPRECATED @HAVE_ATTRIBUTE_DEPRECATED@
184#define LT_USE_PURE @HAVE_ATTRIBUTE_PURE@
185#define LT_USE_PRINTF @HAVE_ATTRIBUTE_FORMAT@
186#define LT_USE_VISIBILITY @HAVE_VISIBILITY@
187
188#if LT_USE_PACKED
189#  define PACKED __attribute__((packed))
190#else
191#  define PACKED
192#endif
193
194#if LT_USE_UNUSED
195#  define UNUSED __attribute__((unused))
196#else
197#  define UNUSED
198#endif
199
200#if LT_USE_DEPRECATED
201#  define DEPRECATED __attribute__((deprecated))
202#else
203#  define DEPRECATED
204#endif
205
206#if LT_USE_PURE
207#  define SIMPLE_FUNCTION __attribute__((pure))
208#else
209#  define SIMPLE_FUNCTION
210#endif
211
212#if LT_USE_PRINTF
213#  define PRINTF(formatpos, argpos) __attribute__((format(printf,formatpos, argpos)))
214#else
215#  define PRINTF(formatpos, argpos)
216#endif
217
218// Used to fight against false sharing
219#define CACHE_LINE_SIZE 64
220#define ALIGN_STRUCT(x) __attribute__((aligned(x)))
221
222#ifdef _MSC_VER
223    #ifdef LT_BUILDING_DLL
224        #define DLLEXPORT __declspec(dllexport)
225    #else
226        #define DLLEXPORT __declspec(dllimport)
227    #endif
228    #define DLLLOCAL
229#else
230    #ifndef DLLEXPORT
231        #if LT_USE_VISIBILITY && LT_BUILDING_DLL
232            #define DLLEXPORT __attribute__ ((visibility("default")))
233            #define DLLLOCAL __attribute__ ((visibility("hidden")))
234        #else
235            #define DLLEXPORT
236            #define DLLLOCAL
237        #endif
238    #endif
239#endif
240
241       
242/** Opaque structure holding information about an output trace */
243typedef struct libtrace_out_t libtrace_out_t;
244       
245/** Opaque structure holding information about a trace */
246typedef struct libtrace_t libtrace_t;
247       
248/** Opaque structure holding information about a bpf filter */
249typedef struct libtrace_filter_t libtrace_filter_t;
250
251typedef struct libtrace_thread_t libtrace_thread_t;
252
253/** If the packet has allocated its own memory the buffer_control should be
254 * set to TRACE_CTRL_PACKET, so that the memory will be freed when the packet
255 * is destroyed. If the packet has been zerocopied out of memory owned by
256 * something else, e.g. a DAG card, it should be TRACE_CTRL_EXTERNAL.
257 *
258 * @note The letters p and e are magic numbers used to detect if the packet
259 * wasn't created properly.
260 */
261typedef enum {
262        TRACE_CTRL_PACKET='p',  /**< Buffer memory is owned by the packet */
263        TRACE_CTRL_EXTERNAL='e' /**< Buffer memory is owned by an external source */
264} buf_control_t;
265
266/** The size of a packet's buffer when managed by libtrace */
267#define LIBTRACE_PACKET_BUFSIZE 65536
268
269/** Libtrace error information */
270typedef struct trace_err_t{
271        int err_num;            /**< error code */
272        char problem[255];      /**< the format, uri etc that caused the error for reporting purposes */
273} libtrace_err_t;
274
275/** Enumeration of error codes */
276enum {
277        /** No Error has occured.... yet. */
278        TRACE_ERR_NOERROR       = 0,
279        /** The URI passed to trace_create() is unsupported, or badly formed */
280        TRACE_ERR_BAD_FORMAT    = -1,
281        /** The trace failed to initialise */
282        TRACE_ERR_INIT_FAILED   = -2,
283        /** Unknown config option */
284        TRACE_ERR_UNKNOWN_OPTION= -3,
285        /** This output uri cannot write packets of this type */
286        TRACE_ERR_NO_CONVERSION = -4,
287        /** This packet is corrupt, or unusable for the action required */
288        TRACE_ERR_BAD_PACKET    = -5,
289        /** Option known, but unsupported by this format */
290        TRACE_ERR_OPTION_UNAVAIL= -6,
291        /** This feature is unsupported */
292        TRACE_ERR_UNSUPPORTED   = -7,
293        /** Illegal use of the API */
294        TRACE_ERR_BAD_STATE     = -8,
295        /** Failed to compile a BPF filter */
296        TRACE_ERR_BAD_FILTER    = -9,
297        /** RT communication breakdown */
298        TRACE_ERR_RT_FAILURE    = -10,
299        /** Compression format unsupported */
300        TRACE_ERR_UNSUPPORTED_COMPRESS  = -11
301};
302
303/** Enumeration of DLTs supported by libtrace
304 */
305typedef enum {
306        /* Special value used to indicate a failure to convert to libtrace
307         * DLT */
308        TRACE_DLT_ERROR = -1,
309       
310        /** pcap documents this as having the Address Family value in host byte order as the
311          * framing.  Ugly? Yes.
312          */
313        TRACE_DLT_NULL = 0,
314        TRACE_DLT_EN10MB = 1,
315        TRACE_DLT_PPP = 9,
316        TRACE_DLT_ATM_RFC1483 = 11,
317       
318        /** Ok, so OpenBSD has a different value for DLT_RAW as the rest of the planet, so detect
319          * this.  When reading to/from files we should be using TRACE_DLT_LINKTYPE_RAW instead.
320          * When talking about DLT's inside libtrace tho, we should be using /these/ DLT's.
321          */
322#ifdef __OpenBSD__
323        TRACE_DLT_OPENBSD_LOOP=12,
324        TRACE_DLT_RAW = 14,     
325#else
326        TRACE_DLT_RAW = 12,
327        TRACE_DLT_OPENBSD_LOOP = 108,
328#endif
329        TRACE_DLT_PPP_SERIAL = 50,
330        TRACE_DLT_LINKTYPE_RAW = 101, /**< See TRACE_DLT_RAW for explainations of pain. */
331        TRACE_DLT_C_HDLC = 104,
332        TRACE_DLT_IEEE802_11 = 105,
333        TRACE_DLT_LINUX_SLL = 113,
334        TRACE_DLT_PFLOG = 117,
335        TRACE_DLT_IEEE802_11_RADIO = 127 /**< Radiotap */
336} libtrace_dlt_t ;
337
338/** Enumeration of link layer types supported by libtrace */
339typedef enum {
340       TRACE_TYPE_UNKNOWN = -1,         /**< Unable to determine link type */
341    /* TRACE_TYPE_LEGACY = 0            Obsolete */
342       TRACE_TYPE_HDLC_POS = 1,         /**< HDLC over POS */
343       TRACE_TYPE_ETH = 2,              /**< 802.3 style Ethernet */
344       TRACE_TYPE_ATM = 3,              /**< ATM frame */
345       TRACE_TYPE_80211 = 4,            /**< 802.11 frames */
346       TRACE_TYPE_NONE = 5,             /**< Raw IP frames */
347       TRACE_TYPE_LINUX_SLL = 6,        /**< Linux "null" framing */
348       TRACE_TYPE_PFLOG = 7,            /**< FreeBSD's PFlog */
349    /* TRACE_TYPE_LEGACY_DEFAULT        Obsolete */
350       TRACE_TYPE_POS = 9,              /**< Packet-over-SONET */
351    /* TRACE_TYPE_LEGACY_ATM            Obsolete */
352    /* TRACE_TYPE_LEGACY_ETH            Obsolete */
353       TRACE_TYPE_80211_PRISM = 12,     /**< 802.11 Prism frames */
354       TRACE_TYPE_AAL5 = 13,            /**< ATM Adaptation Layer 5 frames */
355       TRACE_TYPE_DUCK = 14,         /**< Pseudo link layer for DUCK packets */
356       TRACE_TYPE_80211_RADIO = 15,  /**< Radiotap + 802.11 */
357       TRACE_TYPE_LLCSNAP = 16,      /**< Raw LLC/SNAP */
358       TRACE_TYPE_PPP = 17,          /**< PPP frames */
359       TRACE_TYPE_METADATA = 18,        /**< WDCAP-style meta-data */
360       TRACE_TYPE_NONDATA = 19,         /**< Not a data packet */
361       TRACE_TYPE_OPENBSD_LOOP = 20     /**< OpenBSD loopback */
362} libtrace_linktype_t;
363
364/** RT protocol base format identifiers.
365 * This is used to describe the capture format of the packet is being sent
366 * using the RT protocol.
367 */
368enum base_format_t {
369        TRACE_FORMAT_ERF          =1,   /**< ERF (DAG capture format) */
370        TRACE_FORMAT_PCAP         =2,   /**< Live PCAP capture */
371        TRACE_FORMAT_PCAPFILE     =3,   /**< PCAP trace file */
372        TRACE_FORMAT_WAG          =4,   /**< WAG live capture (Obsolete) */
373        TRACE_FORMAT_RT           =5,   /**< RT network protocol */
374        TRACE_FORMAT_LEGACY_ATM   =6,   /**< Legacy ERF for ATM capture */
375        TRACE_FORMAT_LEGACY_POS   =7,   /**< Legacy ERF for POS capture */
376        TRACE_FORMAT_LEGACY_ETH   =8,   /**< Legacy ERF for ETH capture */
377        TRACE_FORMAT_LINUX_NATIVE =9,   /**< Linux native interface capture */
378        TRACE_FORMAT_DUCK         =10,  /**< DAG Clock information */
379        TRACE_FORMAT_BPF          =11,  /**< BSD native interface capture */
380        TRACE_FORMAT_TSH          =12,  /**< TSH trace format */
381        TRACE_FORMAT_ATMHDR       =13,  /**< Legacy ATM header capture */
382        TRACE_FORMAT_LEGACY_NZIX  =14,  /**< Legacy format used for NZIX traces */
383        TRACE_FORMAT_LINUX_RING   =15,  /**< Linux native interface capture PACKET_MMAP */
384        TRACE_FORMAT_RAWERF       =16,  /**< Special format for reading uncompressed ERF traces without checking for compression */
385    TRACE_FORMAT_DPDK     =17, /**< The Intel Data Plane Development Kit format */
386};
387
388/** RT protocol packet types */
389typedef enum {
390        TRACE_RT_HELLO          =1, /**< Connection accepted */
391        TRACE_RT_START          =2, /**< Request for data transmission to begin
392                                    */
393        TRACE_RT_ACK            =3, /**< Data acknowledgement */
394        TRACE_RT_STATUS         =4, /**< Fifo status packet */
395        TRACE_RT_DUCK           =5, /**< Dag duck info packet */
396        TRACE_RT_END_DATA       =6, /**< Server is exiting message */
397        TRACE_RT_CLOSE          =7, /**< Client is exiting message */
398        TRACE_RT_DENY_CONN      =8, /**< Connection has been denied */
399        TRACE_RT_PAUSE          =9, /**< Request server to suspend sending data
400                                     */
401        TRACE_RT_PAUSE_ACK      =10,/**< Server is paused message */
402        TRACE_RT_OPTION         =11,/**< Option request */
403        TRACE_RT_KEYCHANGE      =12,/**< Anonymisation key has changed */
404        TRACE_RT_DUCK_2_4       =13,/**< Dag 2.4 Duck */
405        TRACE_RT_DUCK_2_5       =14,/**< Dag 2.5 Duck */
406        TRACE_RT_LOSTCONN       =15,/**< Lost connection to server */
407        TRACE_RT_SERVERSTART    =16,/**< Reliable server has been restarted */
408        TRACE_RT_CLIENTDROP     =17,/**< Reliable client was lost */
409        TRACE_RT_METADATA       =18,/**< Packet contains server meta-data */
410        TRACE_RT_DUCK_5_0       =19,/**< Dag 5.0 Duck */
411
412        /** Not actually used - all DATA types begin from this value */
413        TRACE_RT_DATA_SIMPLE    = 1000,
414       
415        /** RT is encapsulating an ERF capture record */
416        TRACE_RT_DATA_ERF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_ERF,
417        /** RT is encapsulating a WAG capture record */
418        TRACE_RT_DATA_WAG       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_WAG,
419        /** RT is encapsulating a Legacy ATM capture record */
420        TRACE_RT_DATA_LEGACY_ATM=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ATM,
421        /** RT is encapsulating a Legacy POS capture record */
422        TRACE_RT_DATA_LEGACY_POS=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_POS,
423        /** RT is encapsulating a Legacy ETH capture record */
424        TRACE_RT_DATA_LEGACY_ETH=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LEGACY_ETH,
425        /** RT is encapsulating a Linux native capture record */
426        TRACE_RT_DATA_LINUX_NATIVE=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_NATIVE,
427        /** RT is encapsulating a BSD native capture record */
428        //TRACE_RT_DATA_BPF       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_BPF,
429        /** RT is encapsulating a TSH capture record */
430        TRACE_RT_DATA_TSH       =TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_TSH,
431        /** RT is encapsulating an ATM header capture record */
432        TRACE_RT_DATA_ATMHDR = TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_ATMHDR,
433        /** RT is encapsulating a Legacy NZIX capture record */
434        TRACE_RT_DATA_LEGACY_NZIX=TRACE_RT_DATA_SIMPLE + TRACE_FORMAT_LEGACY_NZIX,
435        /** RT is encapsulating a Linux native PACKET_MMAP capture record */
436        TRACE_RT_DATA_LINUX_RING=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_LINUX_RING,
437    /** RT is encapsulating a Intel DPDK capture record */
438        TRACE_RT_DATA_DPDK=TRACE_RT_DATA_SIMPLE+TRACE_FORMAT_DPDK,
439
440        /** As PCAP does not store the linktype with the packet, we need to
441         * create a separate RT type for each supported DLT, starting from
442         * this value */
443        TRACE_RT_DATA_DLT               = 2000,
444        /** RT is encapsulating a PCAP capture record with a NULL linktype */
445        TRACE_RT_DLT_NULL               =TRACE_RT_DATA_DLT+TRACE_DLT_NULL,
446        /** RT is encapsulating a PCAP capture record with an Ethernet
447         * linktype */
448        TRACE_RT_DLT_EN10MB             =TRACE_RT_DATA_DLT+TRACE_DLT_EN10MB,
449        /** RT is encapsulating a PCAP capture record with an 802.11
450         * linktype */
451        TRACE_RT_DLT_IEEE802_11         =TRACE_RT_DATA_DLT+TRACE_DLT_IEEE802_11,
452        /** RT is encapsulating a PCAP capture record with a Linux SLL
453         * linktype */
454        TRACE_RT_DLT_LINUX_SLL          =TRACE_RT_DATA_DLT+TRACE_DLT_LINUX_SLL,
455        /** RT is encapsulating a PCAP capture record with a PFlog linktype */
456        TRACE_RT_DLT_PFLOG              =TRACE_RT_DATA_DLT+TRACE_DLT_PFLOG,
457        /** RT is encapsulating a PCAP capture record with an AAL5 linktype */
458        TRACE_RT_DLT_ATM_RFC1483        =TRACE_RT_DATA_DLT+TRACE_DLT_ATM_RFC1483,
459        /** Unused value marking the end of the valid range for PCAP RT
460         * encapsulation */
461        TRACE_RT_DATA_DLT_END           = 2999,
462        /** BPF does not store the linktype with the packet, so we need a
463         * separate RT type for each supported DLT. This value represents the
464         * starting point */
465        TRACE_RT_DATA_BPF               = 3000,
466
467        TRACE_RT_BPF_NULL               = TRACE_RT_DATA_BPF+TRACE_DLT_NULL,
468        TRACE_RT_BPF_EN10MB             = TRACE_RT_DATA_BPF+TRACE_DLT_EN10MB,
469        TRACE_RT_BPF_IEEE802_11         = TRACE_RT_DATA_BPF+TRACE_DLT_IEEE802_11,
470        TRACE_RT_BPF_PFLOG              =TRACE_RT_DATA_BPF+TRACE_DLT_PFLOG,
471        TRACE_RT_BPF_ATM_RFC1483        =TRACE_RT_DATA_BPF+TRACE_DLT_ATM_RFC1483,
472
473        TRACE_RT_DATA_BPF_END           = 3999,
474        /** Unused value marking the end of the valid range for all RT packet
475         * types */
476        TRACE_RT_LAST                   = 4000
477} libtrace_rt_types_t;
478
479/** IP Protocol values */
480typedef enum {
481        TRACE_IPPROTO_IP        = 0,    /**< IP pseudo protocol number */
482        TRACE_IPPROTO_ICMP      = 1,    /**< Internet Control Message protocol */
483        TRACE_IPPROTO_IGMP      = 2,    /**< Internet Group Management Protocol */
484        TRACE_IPPROTO_IPIP      = 4,    /**< IP encapsulated in IP */
485        TRACE_IPPROTO_TCP       = 6,    /**< Transmission Control Protocol */
486        TRACE_IPPROTO_UDP       = 17,   /**< User Datagram Protocol */
487        TRACE_IPPROTO_IPV6      = 41,   /**< IPv6 over IPv4 */
488        TRACE_IPPROTO_ROUTING   = 43,   /**< IPv6 Routing header */
489        TRACE_IPPROTO_FRAGMENT  = 44,   /**< IPv6 Fragmentation header */
490        TRACE_IPPROTO_RSVP      = 46,   /**< Resource Reservation Protocol */
491        TRACE_IPPROTO_GRE       = 47,   /**< General Routing Encapsulation */
492        TRACE_IPPROTO_ESP       = 50,   /**< Encapsulated Security Payload [RFC2406] */
493        TRACE_IPPROTO_AH        = 51,   /**< Authentication Header [RFC2402] */
494        TRACE_IPPROTO_ICMPV6    = 58,   /**< ICMPv6 */
495        TRACE_IPPROTO_NONE      = 59,   /**< IPv6 no next header */
496        TRACE_IPPROTO_DSTOPTS   = 60,   /**< IPv6 destination options */
497        TRACE_IPPROTO_OSPF      = 89,   /**< Open Shortest Path First routing protocol */
498        TRACE_IPPROTO_PIM       = 103,  /**< Protocol Independant Multicast */
499        TRACE_IPPROTO_SCTP      = 132   /**< Stream Control Transmission Protocol */
500} libtrace_ipproto_t;
501
502/** Ethertypes supported by Libtrace */
503typedef enum {
504        /* Numbers <=1500 are of course, LLC/SNAP */
505        TRACE_ETHERTYPE_LOOPBACK= 0x0060,       /**< Ethernet Loopback */
506        TRACE_ETHERTYPE_IP      = 0x0800,       /**< IPv4 */
507        TRACE_ETHERTYPE_ARP     = 0x0806,       /**< Address resolution protocol */
508        TRACE_ETHERTYPE_RARP    = 0x8035,       /**< Reverse ARP */
509        TRACE_ETHERTYPE_8021Q   = 0x8100,       /**< 802.1q VLAN Extended Header */
510        TRACE_ETHERTYPE_IPV6    = 0x86DD,       /**< IPv6 */
511        TRACE_ETHERTYPE_MPLS    = 0x8847,       /**< MPLS Unicast traffic */
512        TRACE_ETHERTYPE_MPLS_MC = 0x8848,       /**< MPLS Multicast traffic */
513        TRACE_ETHERTYPE_PPP_DISC= 0x8863,       /**< PPPoE Service Discovery */
514        TRACE_ETHERTYPE_PPP_SES = 0x8864        /**< PPPoE Session Messages */
515} libtrace_ethertype_t;
516
517/** The libtrace packet structure. Applications shouldn't be
518 * meddling around in here
519 */
520typedef struct libtrace_packet_t {
521        struct libtrace_t *trace;       /**< Pointer to the trace */
522        void *header;                   /**< Pointer to the framing header */
523        void *payload;                  /**< Pointer to the link layer */
524        void *buffer;                   /**< Allocated buffer */
525        libtrace_rt_types_t  type;      /**< RT protocol type for the packet */
526        buf_control_t buf_control;      /**< Describes memory ownership */
527        int capture_length;             /**< Cached capture length */
528        int wire_length;                /**< Cached wire length */
529        int payload_length;             /**< Cached payload length */
530        void *l2_header;                /**< Cached link header */
531        libtrace_linktype_t link_type;  /**< Cached link type */
532        uint32_t l2_remaining;          /**< Cached link remaining */
533        void *l3_header;                /**< Cached l3 header */
534        uint16_t l3_ethertype;          /**< Cached l3 ethertype */
535        uint32_t l3_remaining;          /**< Cached l3 remaining */
536        void *l4_header;                /**< Cached transport header */
537        uint8_t transport_proto;        /**< Cached transport protocol */
538        uint32_t l4_remaining;          /**< Cached transport remaining */
539        uint64_t order; /**< Notes the order of this packet in relation to the input */
540        uint64_t hash; /**< A hash of the packet as supplied by the user */
541        int error; /**< The error status of pread_packet */
542} libtrace_packet_t;
543
544
545/** Trace directions.
546 * Note that these are the directions used by convention. More directions
547 * are possible, not just these 3, and that they may not conform to this
548 * convention.
549 */
550typedef enum {
551        TRACE_DIR_OUTGOING = 0,         /**< Packets originating "inside" */
552        TRACE_DIR_INCOMING = 1,         /**< Packets originating "outside" */
553        TRACE_DIR_OTHER    = 2,         /**< Packets with an unknown direction, or one that's unknown */
554        TRACE_DIR_UNKNOWN = -1,         /**< No direction information available */
555} libtrace_direction_t;
556
557/** Enumeration of Radiotap fields */
558typedef enum {
559    TRACE_RADIOTAP_TSFT = 0, /**< Timer synchronisation function, in microseconds (uint64) */
560    TRACE_RADIOTAP_FLAGS = 1, /**< Wireless flags (uint8) */
561    TRACE_RADIOTAP_RATE = 2, /**< Bitrate in units of 500kbps (uint8) */
562    TRACE_RADIOTAP_CHANNEL = 3, /**< Frequency in MHz (uint16) and channel flags (uint16) */
563    TRACE_RADIOTAP_FHSS = 4, /**< FHSS hop set (uint8) and hopping pattern (uint8) */
564    TRACE_RADIOTAP_DBM_ANTSIGNAL = 5, /**< Signal power in dBm (int8) */
565    TRACE_RADIOTAP_DBM_ANTNOISE = 6, /**< Noise power in dBm (int8) */
566    TRACE_RADIOTAP_LOCK_QUALITY = 7, /**< Barker Code lock quality (uint16) */
567    TRACE_RADIOTAP_TX_ATTENUATION = 8, /**< TX attenuation as unitless distance from max power (uint16) */
568    TRACE_RADIOTAP_DB_TX_ATTENUATION = 9, /**< TX attenutation as dB from max power (uint16) */
569    TRACE_RADIOTAP_DBM_TX_POWER = 10, /**< TX Power in dBm (int8) */
570    TRACE_RADIOTAP_ANTENNA = 11, /**< Antenna frame was rx'd or tx'd on (uint8) */
571    TRACE_RADIOTAP_DB_ANTSIGNAL = 12, /**< Signal power in dB from a fixed reference (uint8) */
572    TRACE_RADIOTAP_DB_ANTNOISE = 13, /**< Noise power in dB from a fixed reference (uint8) */
573    TRACE_RADIOTAP_RX_FLAGS = 14, /** Properties of received frame (uint16) */
574    TRACE_RADIOTAP_TX_FLAGS = 15, /** Properties of transmitted frame (uint16) */
575    TRACE_RADIOTAP_RTS_RETRIES = 16, /** Number of rts retries frame used (uint8) */
576    TRACE_RADIOTAP_DATA_RETRIES = 17, /** Number of unicast retries a transmitted frame used (uint8) */
577    TRACE_RADIOTAP_EXT = 31
578} libtrace_radiotap_field_t;
579
580
581/** @name Protocol structures
582 * These convenience structures provide portable versions of the headers
583 * for a variety of protocols.
584 * @{
585 */
586
587#ifdef WIN32
588#pragma pack(push)
589#pragma pack(1)
590#endif
591
592/** Generic IP header structure */
593typedef struct libtrace_ip
594{
595#if __BYTE_ORDER == __LITTLE_ENDIAN
596    LT_BITFIELD8 ip_hl:4;               /**< Header Length */
597    LT_BITFIELD8 ip_v:4;                /**< Version */
598#elif __BYTE_ORDER == __BIG_ENDIAN
599    LT_BITFIELD8 ip_v:4;                /**< Version */
600    LT_BITFIELD8 ip_hl:4;               /**< Header Length */
601#else
602#   error "Adjust your <bits/endian.h> defines"
603#endif
604    uint8_t  ip_tos;                    /**< Type of Service */
605    uint16_t ip_len;                    /**< Total Length */
606    int16_t  ip_id;                     /**< Identification */
607    uint16_t ip_off;                    /**< IP Fragment offset (and flags) */
608    uint8_t  ip_ttl;                    /**< Time to Live */
609    uint8_t  ip_p;                      /**< Protocol */
610    uint16_t ip_sum;                    /**< Checksum */
611    struct in_addr ip_src;              /**< Source Address */
612    struct in_addr ip_dst;              /**< Destination Address */
613} PACKED libtrace_ip_t;
614
615/** IPv6 header extension structure */
616typedef struct libtrace_ip6_ext
617{
618        uint8_t nxt;    /**< Next header */
619        uint8_t len;    /**< Length of the current header */
620} PACKED libtrace_ip6_ext_t;
621
622typedef struct libtrace_ip6_frag
623{
624        uint8_t nxt;    /**< Next header */
625        uint8_t res;    /**< Reserved */
626        uint16_t frag_off;      /**< Fragment Offset (includes M flag) */
627        uint32_t ident; /** Fragment identification */
628} PACKED libtrace_ip6_frag_t;
629
630/** Generic IPv6 header structure
631 *
632 * @note The flow label field also includes the Version and Traffic Class
633 * fields, because we haven't figured out a nice way to deal with fields
634 * crossing byte boundaries on both Big and Little Endian machines */
635typedef struct libtrace_ip6
636{
637    uint32_t flow;                      /**< Flow label */
638    uint16_t plen;                      /**< Payload length */
639    uint8_t nxt;                        /**< Next header */
640    uint8_t hlim;                       /**< Hop limit */
641    struct in6_addr ip_src;             /**< Source address */
642    struct in6_addr ip_dst;             /**< Destination address */
643} PACKED libtrace_ip6_t;
644
645/** Generic TCP header structure */
646typedef struct libtrace_tcp
647  {
648    uint16_t source;            /**< Source Port */
649    uint16_t dest;              /**< Destination port */
650    uint32_t seq;               /**< Sequence number */
651    uint32_t ack_seq;           /**< Acknowledgement Number */
652#  if __BYTE_ORDER == __LITTLE_ENDIAN
653    LT_BITFIELD8 ecn_ns:1;      /**< ECN Nonce Sum */
654    LT_BITFIELD8 res1:3;        /**< Reserved bits */
655    LT_BITFIELD8 doff:4;        /**< Data Offset */
656    LT_BITFIELD8 fin:1;         /**< FIN */
657    LT_BITFIELD8 syn:1;         /**< SYN flag */
658    LT_BITFIELD8 rst:1;         /**< RST flag */
659    LT_BITFIELD8 psh:1;         /**< PuSH flag */
660    LT_BITFIELD8 ack:1;         /**< ACK flag */
661    LT_BITFIELD8 urg:1;         /**< URG flag */
662    LT_BITFIELD8 ece:1;         /**< ECN Echo */
663    LT_BITFIELD8 cwr:1;         /**< ECN CWR */
664#  elif __BYTE_ORDER == __BIG_ENDIAN
665    LT_BITFIELD8 doff:4;        /**< Data offset */
666    LT_BITFIELD8 res1:3;        /**< Reserved bits */
667    LT_BITFIELD8 ecn_ns:1;      /**< ECN Nonce Sum */
668    LT_BITFIELD8 cwr:1;         /**< ECN CWR */
669    LT_BITFIELD8 ece:1;         /**< ECN Echo */
670    LT_BITFIELD8 urg:1;         /**< URG flag */
671    LT_BITFIELD8 ack:1;         /**< ACK flag */
672    LT_BITFIELD8 psh:1;         /**< PuSH flag */
673    LT_BITFIELD8 rst:1;         /**< RST flag */
674    LT_BITFIELD8 syn:1;         /**< SYN flag */
675    LT_BITFIELD8 fin:1;         /**< FIN flag */
676#  else
677#   error "Adjust your <bits/endian.h> defines"
678#  endif
679    uint16_t window;            /**< Window Size */
680    uint16_t check;             /**< Checksum */
681    uint16_t urg_ptr;           /**< Urgent Pointer */
682} PACKED libtrace_tcp_t;
683
684/** Generic UDP header structure */
685typedef struct libtrace_udp {
686  uint16_t      source;         /**< Source port */
687  uint16_t      dest;           /**< Destination port */
688  uint16_t      len;            /**< Length */
689  uint16_t      check;          /**< Checksum */
690} PACKED libtrace_udp_t;
691
692/** Generic ICMP header structure */
693typedef struct libtrace_icmp
694{
695  uint8_t type;         /**< Message Type */
696  uint8_t code;         /**< Type Sub-code */
697  uint16_t checksum;            /**< Checksum */
698  union
699  {
700    struct
701    {
702      uint16_t  id;             /**< ID of the Echo request */
703      uint16_t  sequence;       /**< Sequence number of the Echo request */
704    } echo;                     /**< Echo Datagram */
705    uint32_t    gateway;        /**< Gateway Address */
706    struct
707    {
708      uint16_t  unused;         /**< Unused */
709      uint16_t  mtu;            /**< Next-hop MTU */
710    } frag;                     /**< Path MTU Discovery */
711  } un;                         /**< Union for Payloads of Various ICMP Codes */
712} PACKED libtrace_icmp_t;
713
714typedef struct libtrace_icmp6 {
715  uint8_t type;         /**< Message Type */
716  uint8_t code;         /**< Type Sub-code */
717  uint16_t checksum;    /**< Checksum */
718
719  union {
720    struct {
721        uint8_t length;   /**< Length of original datagram content in 64 bit words */
722        uint8_t unused;   /**< Unused */       
723        uint8_t unused1;  /**< Unused */
724    } extend;   /**< Extensions added in RFC 4884 for Time Exceeded and Destination Unreachable Messages */
725
726    uint32_t mtu;       /**< MTU from Packet Too Big Message */
727    uint32_t pointer;   /**< Pointer from Parameter Problem Message */
728    struct {
729        uint16_t id;    /**< Echo Identifier */
730        uint16_t sequence; /**< Echo Sequence Number */
731    } echo; /**< Data required for Echo Request and Reply messages */
732  } un;
733} PACKED libtrace_icmp6_t;
734
735/** Generic LLC/SNAP header structure */
736typedef struct libtrace_llcsnap
737{
738/* LLC */
739  uint8_t dsap;                 /**< Destination Service Access Point */
740  uint8_t ssap;                 /**< Source Service Access Point */
741  uint8_t control;              /**< Control field */
742/* SNAP */
743  LT_BITFIELD32 oui:24;         /**< Organisationally Unique Identifier (scope)*/
744  uint16_t type;                /**< Protocol within OUI */
745} PACKED libtrace_llcsnap_t;
746
747/** 802.3 frame */
748typedef struct libtrace_ether
749{
750  uint8_t ether_dhost[6];       /**< Destination Ether Addr */
751  uint8_t ether_shost[6];       /**< Source Ether Addr */
752  uint16_t ether_type;          /**< Packet Type ID Field (next-header) */
753} PACKED libtrace_ether_t;
754
755/** 802.1Q frame */
756typedef struct libtrace_8021q
757{
758  LT_BITFIELD16 vlan_pri:3;      /**< VLAN User Priority */
759  LT_BITFIELD16 vlan_cfi:1;      /**< VLAN Format Indicator,
760                                   * 0 for ethernet, 1 for token ring */
761  LT_BITFIELD16 vlan_id:12;      /**< VLAN Id */
762  uint16_t vlan_ether_type;      /**< VLAN Sub-packet Type ID Field
763                                   * (next-header)*/
764} PACKED libtrace_8021q_t;
765
766/** ATM User Network Interface (UNI) Cell. */
767typedef struct libtrace_atm_cell
768{
769  LT_BITFIELD32 gfc:4;          /**< Generic Flow Control */
770  LT_BITFIELD32 vpi:8;          /**< Virtual Path Identifier */
771  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
772  LT_BITFIELD32 pt:3;           /**< Payload Type */
773  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
774  LT_BITFIELD32 hec:8;          /**< Header Error Control */
775} PACKED libtrace_atm_cell_t;
776
777/** ATM Network Node/Network Interface (NNI) Cell. */
778typedef struct libtrace_atm_nni_cell
779{
780  LT_BITFIELD32 vpi:12;         /**< Virtual Path Identifier */
781  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
782  LT_BITFIELD32 pt:3;           /**< Payload Type */
783  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
784  LT_BITFIELD32 hec:8;          /**< Header Error Control */
785} PACKED libtrace_atm_nni_cell_t;
786
787/** Captured UNI cell.
788 *
789 * Endace don't capture the HEC, presumably to keep alignment.  This
790 * version of the \ref libtrace_atm_cell is used when dealing with DAG
791 * captures of uni cells.
792 *
793 */
794typedef struct libtrace_atm_capture_cell
795{
796  LT_BITFIELD32 gfc:4;          /**< Generic Flow Control */
797  LT_BITFIELD32 vpi:8;          /**< Virtual Path Identifier */
798  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
799  LT_BITFIELD32 pt:3;           /**< Payload Type */
800  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
801} PACKED libtrace_atm_capture_cell_t;
802
803/** Captured NNI cell.
804 *
805 * Endace don't capture the HEC, presumably to keep alignment.  This
806 * version of the \ref libtrace_atm_nni_cell is used when dealing with DAG
807 * captures of nni cells.
808 *
809 */
810typedef struct libtrace_atm_nni_capture_cell
811{
812  LT_BITFIELD32 vpi:12;         /**< Virtual Path Identifier */
813  LT_BITFIELD32 vci:16;         /**< Virtual Channel Identifier */
814  LT_BITFIELD32 pt:3;           /**< Payload Type */
815  LT_BITFIELD32 clp:1;          /**< Cell Loss Priority */
816  LT_BITFIELD32 hec:8;          /**< Header Error Control */
817} PACKED libtrace_atm_nni_capture_cell_t;
818
819/** PPP header */
820typedef struct libtrace_ppp
821{
822 /* I can't figure out where the hell these two variables come from. They're
823  * definitely not in RFC 1661 which defines PPP. Probably some weird thing
824  * relating to the lack of distinction between PPP, HDLC and CHDLC */
825       
826/* uint8_t address; */          /**< PPP Address (0xFF - All stations) */
827/* uint8_t header;  */          /**< PPP Control (0x03 - Unnumbered info) */
828 uint16_t protocol;             /**< PPP Protocol (htons(0x0021) - IPv4 */
829} PACKED libtrace_ppp_t;
830
831/** PPPoE header */
832typedef struct libtrace_pppoe
833{
834 LT_BITFIELD8 version:4;        /**< Protocol version number */
835 LT_BITFIELD8 type:4;           /**< PPPoE Type */
836 uint8_t code;                  /**< PPPoE Code */
837 uint16_t session_id;           /**< Session Identifier */
838 uint16_t length;               /**< Total Length of the PPP packet */
839} PACKED libtrace_pppoe_t;
840
841/** Libtrace local definition of GRE (Generalised Routing Protocol) header
842 * RFC2890
843 */
844typedef struct libtrace_gre_t
845{
846    uint16_t flags;         /**< Flags and version */
847    uint16_t ethertype;     /**< Payload ethertype */
848    uint16_t checksum;      /**< Optional checksum */
849    uint16_t reserved1;     /**< Optional reserved */
850    uint16_t key;           /**< Optional key (or Tenant Network ID) */
851    uint16_t seq;           /**< Optional sequence number */
852} PACKED libtrace_gre_t;
853
854#define LIBTRACE_GRE_FLAG_CHECKSUM 0x8000
855#define LIBTRACE_GRE_FLAG_KEY      0x2000
856#define LIBTRACE_GRE_FLAG_SEQ      0x1000
857#define LIBTRACE_GRE_FLAG_VERMASK  0x0007
858
859/** Libtrace local definition of VXLAN Header
860 * (draft-mahalingam-dutt-dcops-vxlan)
861 */
862typedef struct libtrace_vxlan_t
863{
864    uint8_t flags;          /**< Flags */
865    uint8_t reserved1[3];   /**< Reserved */
866    uint8_t vni[3];         /**< VXLAN Network Identifier (VNI) */
867    uint8_t reserved2;
868} PACKED libtrace_vxlan_t;
869
870/** 802.11 header */
871typedef struct libtrace_80211_t {
872#if __BYTE_ORDER == __LITTLE_ENDIAN
873        LT_BITFIELD32      protocol:2;  /**< Protocol Version */
874        LT_BITFIELD32      type:2;      /**< Frame Type */
875        LT_BITFIELD32      subtype:4;   /**< Frame Subtype */
876#else
877        LT_BITFIELD32      subtype:4;   /**< Frame Subtype */
878        LT_BITFIELD32      type:2;      /**< Frame Type */
879        LT_BITFIELD32      protocol:2;  /**< Protocol Version */
880#endif
881
882#if __BYTE_ORDER == __LITTLE_ENDIAN
883        LT_BITFIELD32      to_ds:1;     /**< Packet to Distribution Service */
884        LT_BITFIELD32      from_ds:1;   /**< Packet from Distribution Service */
885        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
886        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
887        LT_BITFIELD32      power:1;     /**< Power Management mode */
888        LT_BITFIELD32      more_data:1; /**< More data is buffered at station */
889        LT_BITFIELD32      wep:1;       /**< WEP encryption indicator */
890        LT_BITFIELD32      order:1;     /**< Strictly-Ordered class indicator */
891#else
892        LT_BITFIELD32      order:1;     /**< Strictly-Ordered class indicator */
893        LT_BITFIELD32      wep:1;       /**< WEP encryption indicator */
894        LT_BITFIELD32      more_data:1; /**< More data is buffered at station */
895        LT_BITFIELD32      power:1;     /**< Power Management mode */
896        LT_BITFIELD32      retry:1;     /**< Packet is a retry */
897        LT_BITFIELD32      more_frag:1; /**< Packet has more fragments */
898        LT_BITFIELD32      from_ds:1;   /**< Packet from Distribution Service */
899        LT_BITFIELD32      to_ds:1;     /**< Packet to Distribution Service */
900#endif
901       
902        uint16_t     duration;  /**< Duration value for NAV calculation */
903        uint8_t      mac1[6];   /**< MAC Address 1 */
904        uint8_t      mac2[6];   /**< MAC Address 2 */
905        uint8_t      mac3[6];   /**< MAC Address 3 */
906        uint16_t     SeqCtl;    /**< Sequence Control */       
907        uint8_t      mac4[6];   /**< MAC Address 4 */
908} PACKED libtrace_80211_t;
909
910/** The Radiotap header pre-amble
911 *
912 * All Radiotap headers start with this pre-amble, followed by the fields
913 * specified in the it_present bitmask. If bit 31 of it_present is set, then
914 * another bitmask follows.
915 * @note All of the radiotap data fields are in little-endian byte-order.
916 */
917typedef struct libtrace_radiotap_t {
918    uint8_t     it_version; /**< Radiotap version */
919    uint8_t     it_pad; /**< Padding for natural alignment */
920    uint16_t    it_len; /**< Length in bytes of the entire Radiotap header */
921    uint32_t    it_present; /**< Which Radiotap fields are present */
922} PACKED libtrace_radiotap_t;
923
924/** OSPF header */
925typedef struct libtrace_ospf_v2_t
926{
927        uint8_t ospf_v;         /**< OSPF Version, should be 2 */
928        uint8_t type;           /**< OSPF Packet Type */
929        uint16_t ospf_len;      /**< Packet length, including OSPF header */
930        struct in_addr router;  /**< Router ID of the packet source */
931        struct in_addr area;    /**< Area the packet belongs to */
932        uint16_t sum;           /**< Checksum */
933        uint16_t au_type;       /**< Authentication procedure */
934        uint16_t zero;          /**< Always zero */
935        uint8_t au_key_id;      /**< Authentication Key ID */
936        uint8_t au_data_len;    /**< Authentication Data Length */
937        uint32_t au_seq_num;    /**< Cryptographic Sequence Number */
938} PACKED libtrace_ospf_v2_t;
939
940/** Options Field present in some OSPFv2 packets */
941typedef struct libtrace_ospf_options_t {
942#if __BYTE_ORDER == __LITTLE_ENDIAN
943        LT_BITFIELD8 unused1:1;
944        LT_BITFIELD8 e_bit:1;
945        LT_BITFIELD8 mc_bit:1;
946        LT_BITFIELD8 np_bit:1;
947        LT_BITFIELD8 ea_bit:1;
948        LT_BITFIELD8 dc_bit:1;
949        LT_BITFIELD8 unused2:2;
950#elif __BYTE_ORDER == __BIG_ENDIAN
951        LT_BITFIELD8 unused2:2;
952        LT_BITFIELD8 dc_bit:1;
953        LT_BITFIELD8 ea_bit:1;
954        LT_BITFIELD8 np_bit:1;
955        LT_BITFIELD8 mc_bit:1;
956        LT_BITFIELD8 e_bit:1;
957        LT_BITFIELD8 unused1:1;
958#endif
959} PACKED libtrace_ospf_options_t;
960
961/** LSA Header for OSPFv2 */
962typedef struct libtrace_ospf_lsa_v2_t
963{
964        uint16_t age;           /**< Time in seconds since LSA originated */
965        libtrace_ospf_options_t lsa_options;    /**< Options */
966        uint8_t lsa_type;       /**< LSA type */
967        struct in_addr ls_id;   /**< Link State ID */
968        struct in_addr adv_router; /**< Router that originated this LSA */
969        uint32_t seq;           /**< LS sequence number */
970        uint16_t checksum;      /**< Checksum */
971        uint16_t length;        /**< Length of the LSA including LSA header */
972} PACKED libtrace_ospf_lsa_v2_t;
973
974/** OSPFv2 Hello Packet */
975typedef struct libtrace_ospf_hello_v2_t
976{
977        struct in_addr mask;    /**< Network mask for this interface */
978        uint16_t interval;      /**< Interval between Hello packets (secs) */
979        libtrace_ospf_options_t hello_options;  /**< Options */
980        uint8_t priority;       /**< Router Priority */
981        uint32_t deadint;       /**< Interval before declaring a router down */
982        struct in_addr designated;      /**< Designated router for the network */
983        struct in_addr backup;  /**< Backup designated router */
984
985        /** Neighbors follow from here, but there can be anywhere from 1 to N
986         * neighbors so I can't include that here */
987} PACKED libtrace_ospf_hello_v2_t;
988
989/** OSPFv2 Database Description packet */
990typedef struct libtrace_ospf_db_desc_v2_t
991{
992        uint16_t mtu;           /**< Interface MTU */
993        libtrace_ospf_options_t db_desc_options;        /**< Options */
994#if __BYTE_ORDER == __LITTLE_ENDIAN
995        LT_BITFIELD8 db_desc_ms:1;      /**< If set, this router is the master */
996        LT_BITFIELD8 db_desc_m:1;       /**< If set, more packets to follow */
997        LT_BITFIELD8 db_desc_i:1;       /**< If set, this is the first packet in sequence */
998        LT_BITFIELD8 zero:5;
999#elif __BYTE_ORDER == __BIG_ENDIAN
1000        LT_BITFIELD8 zero:5;
1001        LT_BITFIELD8 db_desc_i:1;       /**< If set, this is the first packet in sequence */
1002        LT_BITFIELD8 db_desc_m:1;       /**< If set, more packets to follow */
1003        LT_BITFIELD8 db_desc_ms:1;      /**< If set, this router is the master */
1004#endif
1005        uint32_t seq;           /**< Sequence number for DD packets */
1006} PACKED libtrace_ospf_db_desc_v2_t;
1007
1008/** OSPF Link State Request Packet */
1009typedef struct libtrace_ospf_ls_req_t
1010{
1011        uint32_t ls_type;       /**< Link State Type */
1012        uint32_t ls_id;         /**< Link State Id */
1013        uint32_t advertising_router;    /**< Advertising Router */
1014} PACKED libtrace_ospf_ls_req_t;
1015
1016/** OSPF Link State Update Packet */
1017typedef struct libtrace_ospf_ls_update_t
1018{
1019        uint32_t ls_num_adv;    /**< Number of LSAs in this packet */
1020
1021        /* Followed by LSAs, use API functions to access these */
1022} PACKED libtrace_ospf_ls_update_t;
1023
1024/** OSPFv2 AS External LSA Body */
1025typedef struct libtrace_ospf_as_external_lsa_t
1026{
1027        struct in_addr netmask; /**< Netmask for the destination */
1028#if __BYTE_ORDER == __LITTLE_ENDIAN
1029        LT_BITFIELD8 tos:7;
1030        LT_BITFIELD8 e:1;       /**< If set, metric is Type 2. Else, Type 1 */
1031#elif __BYTE_ORDER == __BIG_ENDIAN
1032        LT_BITFIELD8 e:1;       /**< If set, metric is Type 2. Else, Type 1 */
1033        LT_BITFIELD8 tos:7;
1034#endif
1035        uint8_t metric_a;       /**< Byte 1 of the Metric field */
1036        uint8_t metric_b;       /**< Byte 2 of the Metric field */
1037        uint8_t metric_c;       /**< Byte 3 of the Metric field */
1038        struct in_addr forwarding;      /**< Forwarding address */
1039        uint32_t external_tag;          /**< External Route Tag */
1040} PACKED libtrace_ospf_as_external_lsa_v2_t;
1041
1042/** OSPFv2 Summary LSA Body */
1043typedef struct libtrace_ospf_summary_lsa
1044{
1045        struct in_addr netmask; /**< Netmask for the destination */
1046        uint8_t zero;           /**< Always zero */
1047        uint8_t metric_a;       /**< Byte 1 of the Metric field */
1048        uint8_t metric_b;       /**< Byte 2 of the Metric field */
1049        uint8_t metric_c;       /**< Byte 3 of the Metric field */
1050       
1051} PACKED libtrace_ospf_summary_lsa_v2_t;
1052
1053/** OSPFv2 Network LSA Body */
1054typedef struct libtrace_ospf_network_lsa_t
1055{
1056        struct in_addr netmask; /**< Netmask for the network */
1057        /* Followed by IDs of attached routers */
1058} PACKED libtrace_ospf_network_lsa_v2_t;
1059
1060/** OSPFv2 Router Link structure */
1061typedef struct libtrace_ospf_link_t
1062{
1063        struct in_addr link_id;         /**< Object that link connects to */
1064        struct in_addr link_data;       /**< Link Data field */
1065        uint8_t type;                   /**< Link Type */
1066        uint8_t num_tos;                /**< Number of TOS metrics */
1067        uint16_t tos_metric;            /**< Cost of router link */
1068} PACKED libtrace_ospf_link_v2_t;
1069
1070/** OSPFv2 Router LSA */
1071typedef struct libtrace_ospf_router_lsa_t
1072{
1073#if __BYTE_ORDER == __LITTLE_ENDIAN
1074        LT_BITFIELD8 b:1;       /**< Area Border Router Flag */
1075        LT_BITFIELD8 e:1;       /**< External Router Flag */
1076        LT_BITFIELD8 v:1;       /**< Virtual Endpoint Flag */
1077        LT_BITFIELD8 zero:5;
1078#elif __BYTE_ORDER == __BIG_ENDIAN
1079        LT_BITFIELD8 zero:5;
1080        LT_BITFIELD8 v:1;       /**< Virtual Endpoint Flag */
1081        LT_BITFIELD8 e:1;       /**< External Router Flag */
1082        LT_BITFIELD8 b:1;       /**< Area Border Router Flag */
1083#endif
1084        uint8_t zero2;          /**< Always zero */
1085        uint16_t num_links;     /**< Number of links in LSA */
1086} PACKED libtrace_ospf_router_lsa_v2_t;
1087
1088typedef enum {
1089        TRACE_OSPF_HELLO = 1,           /**< OSPF Hello */
1090        TRACE_OSPF_DATADESC = 2,        /**< OSPF Database Description */
1091        TRACE_OSPF_LSREQ = 3,           /**< OSPF Link State Request */
1092        TRACE_OSPF_LSUPDATE = 4,        /**< OSPF Link State Update */
1093        TRACE_OSPF_LSACK = 5            /**< OSPF Link State Acknowledgement */
1094} libtrace_ospf_types_t;
1095
1096typedef enum {
1097        TRACE_OSPF_LS_ROUTER = 1,       /**< OSPF Router LSA */
1098        TRACE_OSPF_LS_NETWORK = 2,      /**< OSPF Network LSA */
1099        TRACE_OSPF_LS_SUMMARY = 3,      /**< OSPF Summary LSA */
1100        TRACE_OSPF_LS_ASBR_SUMMARY = 4, /**< OSPF Summary LSA (ASBR) */
1101        TRACE_OSPF_LS_EXTERNAL = 5      /**< OSPF AS External LSA */
1102} libtrace_ospf_ls_types_t;
1103
1104/** A local definition of an SLL header */
1105typedef struct libtrace_sll_header_t {
1106        uint16_t pkttype;               /**< Packet type */
1107        uint16_t hatype;                /**< Link-layer address type */
1108        uint16_t halen;                 /**< Link-layer address length */
1109        unsigned char addr[8];          /**< Link-layer address */
1110        uint16_t protocol;              /**< Protocol */
1111} libtrace_sll_header_t;
1112
1113
1114/* SLL packet types */
1115
1116/** Packet was addressed for the local host */
1117#define TRACE_SLL_HOST          0
1118/** Packet was addressed for a broadcast address */
1119#define TRACE_SLL_BROADCAST     1
1120/** Packet was addressed for a multicast address */
1121#define TRACE_SLL_MULTICAST     2
1122/** Packet was addressed for another host but was captured by a promiscuous
1123 * device */
1124#define TRACE_SLL_OTHERHOST     3
1125/** Packet originated from the local host */
1126#define TRACE_SLL_OUTGOING      4
1127
1128
1129#ifdef WIN32
1130#pragma pack(pop)
1131#endif
1132
1133
1134/*@}*/
1135
1136/** Prints help information for libtrace
1137 *
1138 * Function prints out some basic help information regarding libtrace,
1139 * and then prints out the help() function registered with each input module
1140 */
1141DLLEXPORT void trace_help(void);
1142
1143/** Causes a libtrace reader to stop blocking whilst waiting on new packets
1144 * and immediately return EOF.
1145 *
1146 * This function is useful if you are handling signals within your libtrace
1147 * program. If a live source is not receiving any packets (or they are being
1148 * filtered), a call to trace_read_packet will result in an infinite loop as
1149 * it will block until a packet is received. Normally, a SIGINT would cause the
1150 * program to end and thus break the loop, but if you are handling the signal
1151 * yourself then that signal will never reach libtrace.
1152 *
1153 * Instead this function sets a global variable within libtrace that will
1154 * cause a blocking live capture to break on the next internal timeout,
1155 * allowing control to be returned to the user and their own signal handling
1156 * to kick in.
1157 */
1158DLLEXPORT void trace_interrupt(void);
1159
1160/** @name Trace management
1161 * These members deal with creating, configuring, starting, pausing and
1162 * cleaning up a trace object
1163 *@{
1164 */
1165
1166/** Takes a uri and splits it into a format and uridata component.
1167 * @param uri           The uri to be parsed
1168 * @param [out] format  A pointer that will be updated to point to an allocated
1169 *                      string holding the format component of the URI
1170 * @return NULL if an error occured, otherwise return a pointer to the uridata
1171 * component
1172 *
1173 * @note The format component is strdup'd by this function, so be sure to free
1174 * it when you are done with the split URI. Similarly, do not pass a pointer
1175 * to an allocated string into this function as the 'format' parameter, as
1176 * that memory will be leaked and replaced with the strdup'd format.
1177 */
1178DLLEXPORT const char *trace_parse_uri(const char *uri, char **format);
1179
1180/** Create an input trace from a URI
1181 *
1182 * @param uri A valid libtrace URI to be opened
1183 * @return An opaque pointer to a libtrace_t
1184 *
1185 * Some valid URI's are:
1186 *  - erf:/path/to/erf/file
1187 *  - erf:-  (stdin)
1188 *  - dag:/dev/dagcard                 
1189 *  - pcapint:pcapinterface                (eg: pcap:eth0)
1190 *  - pcap:/path/to/pcap/file
1191 *  - pcap:-
1192 *  - rt:hostname
1193 *  - rt:hostname:port
1194 *
1195 *  If an error occured when attempting to open the trace file, a
1196 *  trace is still returned so trace_is_err() should be called to find out
1197 *  if an error occured. The trace is created in the configuration state, you
1198 *  must call trace_start before attempting to read packets from the trace.
1199 */
1200DLLEXPORT libtrace_t *trace_create(const char *uri);
1201
1202/** Creates a "dummy" trace file that has only the format type set.
1203 *
1204 * @param uri A valid (but fake) URI indicating the format of the dummy trace that is to be created.
1205 * @return An opaque pointer to a (sparsely initialised) libtrace_t
1206 *
1207 * Only the format portion of the uri parameter matters - the 'file' being
1208 * opened does not have to exist.
1209 *
1210 * @note IMPORTANT: Do not attempt to call trace_read_packet or other such
1211 * functions with the dummy trace. Its intended purpose is to provide access
1212 * to the format functions where the original trace may no longer exist or is
1213 * not the correct format, e.g. reading ERF packets from an RT input.
1214 */
1215DLLEXPORT libtrace_t *trace_create_dead(const char *uri);
1216
1217/** Creates a trace output file from a URI.
1218 *
1219 * @param uri The uri string describing the output format and destination
1220 * @return An opaque pointer to a libtrace_output_t
1221 *
1222 * Valid URIs include:
1223 *  - erf:/path/to/erf/file
1224 *  - pcap:/path/to/pcap/file
1225 *
1226 *  If an error occured when attempting to open the output trace, a trace is
1227 *  still returned but trace_errno will be set. Use trace_is_err_out() and
1228 *  trace_perror_output() to get more information.
1229 */
1230DLLEXPORT libtrace_out_t *trace_create_output(const char *uri);
1231
1232/** Start an input trace
1233 * @param libtrace      The trace to start
1234 * @return 0 on success, -1 on failure
1235 *
1236 * This does the actual work of starting the input trace and applying
1237 * all the config options.  This may fail, returning -1. The libtrace error
1238 * handling functions can be used to get more information about what
1239 * specifically went wrong.
1240 */
1241DLLEXPORT int trace_start(libtrace_t *libtrace);
1242
1243/** Pauses an input trace
1244 * @param libtrace      The trace to pause
1245 * @return 0 on success, -1 on failure
1246 *
1247 * This stops an input trace that is in progress and returns you to the
1248 * configuration state.  Any packets that arrive on a live capture after
1249 * trace_pause() has been called will be discarded.  To resume the trace, call
1250 * trace_start().
1251 */
1252DLLEXPORT int trace_pause(libtrace_t *libtrace);
1253
1254/** Start an output trace
1255 * @param libtrace      The trace to start
1256 * @return 0 on success, -1 on failure
1257 *
1258 * This does the actual work with starting a trace capable of writing packets. 
1259 * This generally creates the output file.
1260 */
1261DLLEXPORT int trace_start_output(libtrace_out_t *libtrace);
1262
1263/** Valid configuration options for input traces */
1264typedef enum {
1265        /** Maximum number of bytes to be captured for any given packet */
1266        TRACE_OPTION_SNAPLEN,   
1267
1268        /** If enabled, places a live capture interface into promiscuous mode */
1269        TRACE_OPTION_PROMISC,   
1270
1271        /** Apply this filter to all packets read from this trace */
1272        TRACE_OPTION_FILTER,   
1273
1274        /** Defines the frequency of meta-data reporting, e.g. DUCK packets */
1275        TRACE_OPTION_META_FREQ,
1276
1277        /** If enabled, the libtrace event API will ignore time gaps between
1278         * packets when reading from a trace file */
1279        TRACE_OPTION_EVENT_REALTIME
1280} trace_option_t;
1281
1282/** Sets an input config option
1283 * @param libtrace      The trace object to apply the option to
1284 * @param option        The option to set
1285 * @param value         The value to set the option to
1286 * @return -1 if option configuration failed, 0 otherwise
1287 * This should be called after trace_create, and before trace_start
1288 */
1289DLLEXPORT int trace_config(libtrace_t *libtrace,
1290                trace_option_t option,
1291                void *value);
1292
1293/** Valid compression types
1294 * Note, this must be kept in sync with WANDIO_COMPRESS_* numbers in wandio.h
1295 */
1296typedef enum {
1297        TRACE_OPTION_COMPRESSTYPE_NONE = 0, /**< No compression */
1298        TRACE_OPTION_COMPRESSTYPE_ZLIB = 1, /**< GZip Compression */
1299        TRACE_OPTION_COMPRESSTYPE_BZ2  = 2, /**< BZip2 Compression */
1300        TRACE_OPTION_COMPRESSTYPE_LZO  = 3,  /**< LZO Compression */
1301        TRACE_OPTION_COMPRESSTYPE_LZMA  = 4,  /**< LZO Compression */
1302        TRACE_OPTION_COMPRESSTYPE_LAST
1303} trace_option_compresstype_t;
1304
1305/** Valid configuration options for output traces */
1306typedef enum {
1307        /** File flags to use when opening an output file, e.g. O_APPEND */
1308        TRACE_OPTION_OUTPUT_FILEFLAGS,
1309        /** Compression level: 0 = no compression, 1 = faster compression,
1310         * 9 = better compression */
1311        TRACE_OPTION_OUTPUT_COMPRESS,
1312        /** Compression type, see trace_option_compresstype_t */
1313        TRACE_OPTION_OUTPUT_COMPRESSTYPE
1314} trace_option_output_t;
1315
1316/* To add a new stat field update this list, and the relevent places in
1317 * libtrace_stat_t structure.
1318 */
1319/** An X Macro set for libtrace stat fields */
1320#define LIBTRACE_STAT_FIELDS \
1321        X(accepted) \
1322        X(filtered) \
1323        X(received) \
1324        X(dropped) \
1325        X(captured) \
1326        X(errors)
1327
1328/**
1329 * Statistic counters are cumulative from the time the trace is started.
1330 * Trace pause will reset the counters, to zero.
1331 * Always check \a{field}_valid is set before attempting to read the stored value.
1332 *
1333 * @note Always allocate this structure using trace_create_statistics().
1334 *       This allows us to extend the structure in the future.
1335 */
1336typedef struct libtrace_stat_t {
1337        // Align to 64 bits, because the compiler is likely to do this anyway.
1338#if __BYTE_ORDER == __LITTLE_ENDIAN
1339#define X(name) LT_BITFIELD64 name ##_valid : 1;
1340        LIBTRACE_STAT_FIELDS
1341#undef X
1342        /* We use the remaining space as magic to ensure the structure
1343         * was alloc'd by us. We can easily decrease the no. bits without
1344         * problems as long as we update any asserts as needed */
1345        LT_BITFIELD64 reserved1: 26; /**< Bits reserved for future fields */
1346        LT_BITFIELD64 reserved2: 24; /**< Bits reserved for future fields */
1347        LT_BITFIELD64 magic: 8; /**< A number stored against the format to
1348                                  ensure the struct was allocated correctly */
1349#else
1350        LT_BITFIELD64 magic: 8;
1351        LT_BITFIELD64 reserved2: 24;
1352        LT_BITFIELD64 reserved1: 26;
1353        LT_BITFIELD64 dropped_valid: 1;
1354        LT_BITFIELD64 received_valid: 1;
1355        LT_BITFIELD64 filtered_valid: 1;
1356        LT_BITFIELD64 accepted_valid: 1;
1357#endif
1358        /* These must all be uint64_t's, match this order with the X macro */
1359        uint64_t accepted;
1360        /**< The number of packets that have been read from the input trace
1361         * using trace_read_packet(). In the parallel framework this may include
1362         * some packets waiting in a batch yet to be seen by the user's
1363         * application.
1364         *
1365         * This does not include filtered packets because these do not make it
1366         * to trace_read_packet().
1367         *
1368         * @note This field replaces trace_get_accepted_packets()
1369         */
1370        uint64_t filtered;
1371        /**< The number of packets that were captured, but discarded for not
1372         * matching a provided filter.
1373         *
1374         * @note This field replaces trace_get_filtered_packets()
1375         */
1376        uint64_t received;
1377        /**< The total number of good packets which have been recevied. Including
1378         * those which are dropped and filtered. This does not include errors.
1379         *
1380         * @note This may include a small number of buffered packets
1381         *       not yet included in accepted.
1382         *
1383         * @note This field replaces trace_get_received_packets()
1384         */
1385        uint64_t dropped;
1386        /**< The number of packets that have been dropped on an input trace
1387         * due to lack of buffer space on the capturing device. This does not
1388         * included errored packets which are dropped directly by the card.
1389         *
1390         * @note This field replaces trace_get_dropped_packets()
1391         */
1392        uint64_t captured;
1393        /**< The number of received packets that have not been dropped. This
1394         * includes filtered packets.
1395         *
1396         * This is equivalent to received-dropped.
1397         *
1398         * @note This may include a small number of buffered packets
1399         *       not yet included in accepted.
1400         */
1401        uint64_t errors;
1402        /**< The number of packets that have been discarded by the network card
1403         * because they are invalid. That includes FCS mismatches, incorrect
1404         * packet lengths etc.
1405         */
1406} libtrace_stat_t;
1407
1408ct_assert(offsetof(libtrace_stat_t, accepted) == 8);
1409
1410/** Sets an output config option
1411 *
1412 * @param libtrace      The output trace object to apply the option to
1413 * @param option        The option to set
1414 * @param value         The value to set the option to
1415 * @return -1 if option configuration failed, 0 otherwise
1416 * This should be called after trace_create_output, and before
1417 * trace_start_output
1418 */
1419DLLEXPORT int trace_config_output(libtrace_out_t *libtrace,
1420                trace_option_output_t option,
1421                void *value
1422                );
1423
1424/** Close an input trace, freeing up any resources it may have been using
1425 *
1426 * @param trace         The input trace to be destroyed
1427 *
1428 */
1429DLLEXPORT void trace_destroy(libtrace_t *trace);
1430
1431/** Close a dummy trace file, freeing up any resources it may have been using
1432 * @param trace         The dummy trace to be destroyed
1433 */
1434DLLEXPORT void trace_destroy_dead(libtrace_t *trace);
1435
1436/** Close an output trace, freeing up any resources it may have been using
1437 * @param trace         The output trace to be destroyed
1438 */
1439DLLEXPORT void trace_destroy_output(libtrace_out_t *trace);
1440
1441/** Check (and clear) the current error state of an input trace
1442 * @param trace         The input trace to check the error state on
1443 * @return The current error status and message
1444 *
1445 * This reads and returns the current error state and sets the current error
1446 * to "no error".
1447 */
1448DLLEXPORT libtrace_err_t trace_get_err(libtrace_t *trace);
1449
1450/** Indicate if there has been an error on an input trace
1451 * @param trace         The input trace to check the error state on
1452 * @return true if an error has occurred, false otherwise
1453 *
1454 * @note This does not clear the error status, and only returns true or false.
1455 */
1456DLLEXPORT bool trace_is_err(libtrace_t *trace);
1457
1458/** Outputs the error message for an input trace to stderr and clear the error
1459 * status.
1460 * @param trace         The input trace with the error to output
1461 * @param msg           The message to prepend to the error
1462 *
1463 * This function does clear the error status.
1464 */
1465DLLEXPORT void trace_perror(libtrace_t *trace, const char *msg,...) PRINTF(2,3);
1466
1467/** Checks (and clears) the current error state for an output trace
1468 * @param trace         The output trace to check the error state on
1469 * @return The current error status and message
1470 *
1471 * This reads and returns the current error state and sets the current error
1472 * to "no error".
1473 */
1474DLLEXPORT libtrace_err_t trace_get_err_output(libtrace_out_t *trace);
1475
1476/** Indicates if there is an error on an output trace
1477 * @param trace         The output trace to check the error state on
1478 * @return true if an error has occurred, false otherwise.
1479 *
1480 * This does not clear the error status, and only returns true or false.
1481 */
1482DLLEXPORT bool trace_is_err_output(libtrace_out_t *trace);
1483
1484/** Outputs the error message for an output trace to stderr and clear the error
1485 * status.
1486 * @param trace         The output trace with the error to output
1487 * @param msg           The message to prepend to the error
1488 * This function does clear the error status.
1489 */
1490DLLEXPORT void trace_perror_output(libtrace_out_t *trace, const char *msg,...)
1491        PRINTF(2,3);
1492
1493/** Returns the number of packets observed on an input trace.
1494 * Includes the number of packets counted as early as possible, before
1495 * filtering, and includes dropped packets.
1496 *
1497 * @param trace         The input trace to examine
1498 * @returns The number of packets seen at the capture point before filtering.
1499 *
1500 * If the number is not known, this function will return UINT64_MAX
1501 *
1502 * @deprecated This function is deprecated: Use trace_get_statistics(), this
1503 *             allows all statistic counters to be read in an atomic manner.
1504 */
1505DLLEXPORT DEPRECATED
1506uint64_t trace_get_received_packets(libtrace_t *trace);
1507
1508/** Returns the number of packets that were captured, but discarded for not
1509 * matching a provided filter.
1510 *
1511 * @param trace         The input trace to examine
1512 * @returns The number of packets that were successfully captured, but filtered
1513 *
1514 * If the number is not known, this function will return UINT64_MAX
1515 *
1516 * @deprecated This function is deprecated: Use trace_get_statistics(), this
1517 *             allows all statistic counters to be read in an atomic manner.
1518 */
1519DLLEXPORT DEPRECATED
1520uint64_t trace_get_filtered_packets(libtrace_t *trace);
1521
1522/** Returns the number of packets that have been dropped on an input trace due
1523 * to lack of buffer space on the capturing device.
1524 *
1525 * @param trace         The input trace to examine
1526 * @returns The number of packets captured, but dropped due to buffer overruns
1527 *
1528 * If the number is not known, this function will return UINT64_MAX
1529 *
1530 * @deprecated This function is deprecated: Use trace_get_statistics(), this
1531 *             allows all statistic counters to be read in an atomic manner.
1532 */
1533DLLEXPORT DEPRECATED
1534uint64_t trace_get_dropped_packets(libtrace_t *trace);
1535
1536/** Returns the number of packets that have been read from the input trace using
1537 * trace_read_packet().
1538 *
1539 * @param trace         The input trace to examine
1540 * @returns The number of packets that have been read by the libtrace user.
1541 *
1542 * If the number is not known, this function will return UINT64_MAX
1543 *
1544 * @deprecated This function is deprecated: Use trace_get_statistics(), this
1545 *             allows all statistic counters to be read in an atomic manner.
1546 */
1547DLLEXPORT DEPRECATED
1548uint64_t trace_get_accepted_packets(libtrace_t *trace);
1549
1550/**
1551 * Returns statistic counters for a trace, for a parallel trace this is a
1552 * combined total.
1553 * Where possible these are retrived atomically, however this behaviour depends
1554 * on the underlying trace format.
1555 *
1556 * @param trace The input trace to examine.
1557 * @param stats Optional, Filled upon return with statistics about the trace,
1558 *              check the flags included to see if a given statistic is valid.
1559 *              If NULL a statistic structure owned by libtrace is returned, this
1560 *              should not be free'd and will become invalid if the trace is
1561 *              destroyed.
1562 *
1563 * @return A pointer to the statistics structure.
1564 * @note Use trace_create_stat() to create the stats object, this way future
1565 *       versions of libtrace can add to the structure without breaking existing
1566 *       code.
1567 */
1568DLLEXPORT
1569libtrace_stat_t *trace_get_statistics(libtrace_t *trace, libtrace_stat_t *stats);
1570
1571
1572/**
1573 * Returns statistic counters for a single thread of a trace.
1574 * Where possible these are retrived atomically, however this behaviour depends
1575 * on the underlying trace format.
1576 *
1577 * @param trace The input trace to examine.
1578 * @param t An optional thread to received stats for or NULL to retrive stats
1579 *          for the current thread
1580 * @param stats Filled upon return with statistics about the trace, check the
1581 *              flags included to see if a given statistic is valid.
1582 *
1583 * @note Use trace_create_stat() to create the stats object, this way future
1584 *       versions of libtrace can add to the structure without breaking existing
1585 *       code.
1586 */
1587DLLEXPORT
1588void trace_get_thread_statistics(libtrace_t *trace, libtrace_thread_t *t,
1589                                 libtrace_stat_t *stats);
1590
1591/**
1592 * Creates and returns a zeroed libtrace_stat_t structure.
1593 *
1594 * This allows us to add extra fields increasing the size of the structure
1595 * without breaking existing libtrace applications.
1596 *
1597 * This structure should be free'd using free().
1598 *
1599 * @return A valid pointer to a libtrace_stat_t struct otherwise NULL if
1600 *         memory was not available.
1601 */
1602DLLEXPORT libtrace_stat_t* trace_create_statistics(void);
1603
1604/**
1605 * Performs the operation c=a-b accounting for valid fields.
1606 * c is allowed to be a or b.
1607 *
1608 * @param a The minuend
1609 * @param b The subtrahend
1610 * @param c The resulting difference
1611 */
1612DLLEXPORT
1613void trace_subtract_statistics(const libtrace_stat_t *a,
1614                               const libtrace_stat_t *b, libtrace_stat_t *c);
1615
1616/**
1617 * Performs operation c=a+b accounting for valid fields.
1618 * c is allowed to be a or b.
1619 *
1620 * @param a The first operand
1621 * @param b The second operand
1622 * @param c The result
1623 */
1624DLLEXPORT
1625void trace_add_statistics(const libtrace_stat_t *a,
1626                          const libtrace_stat_t *b, libtrace_stat_t *c);
1627
1628/**
1629 * Prints all valid stats to a file stream, (which could be stdout/err).
1630 * By default the format "name: value" is used.
1631 *
1632 * @param s The statistic structure to print
1633 * @param f The output file stream
1634 * @param format An optional format string such as the default ("%s: %"PRIu64"\n")
1635 *               This is passed to fprintf and called with two arguments
1636 *               first a char* (%s) and second a uint64_t (%PRIu64).
1637 *
1638 * @return -1 if an error occurs when writing to the file stream, check errno.
1639 *         Otherwise 0.
1640 */
1641DLLEXPORT
1642int trace_print_statistics(const libtrace_stat_t *s, FILE *f,
1643                           const char *format);
1644
1645
1646/*@}*/
1647
1648/** @name Reading / Writing packets
1649 * These members deal with creating, reading and writing packets
1650 *
1651 * @{
1652 */
1653
1654/** Create a new packet object
1655 *
1656 * @return A pointer to an initialised libtrace_packet_t object
1657 */
1658DLLEXPORT libtrace_packet_t *trace_create_packet(void);
1659
1660/** Copy a packet object
1661 * @param packet        The source packet to copy
1662 * @return A new packet which has the same content as the source packet
1663 *
1664 * @note This always involves a copy, which can be slow.  Use of this
1665 * function should be avoided where possible.
1666 *
1667 * @par The reason you would want to use this function is that a zerocopied
1668 * packet from a device will be stored using memory owned by the device which
1669 * may be a limited resource. Copying the packet will ensure that the packet
1670 * is now stored in memory owned and managed by libtrace.
1671 */
1672DLLEXPORT libtrace_packet_t *trace_copy_packet(const libtrace_packet_t *packet);
1673
1674/** Destroy a packet object
1675 * @param packet        The packet to be destroyed
1676 *
1677 */
1678DLLEXPORT void trace_destroy_packet(libtrace_packet_t *packet);
1679
1680
1681/** Read the next packet from an input trace
1682 *
1683 * @param trace         The libtrace opaque pointer for the input trace
1684 * @param packet        The packet opaque pointer
1685 * @return 0 on EOF, negative value on error, number of bytes read when successful.
1686 *
1687 * @note The number of bytes read is usually (but not always) the same as
1688 * trace_get_framing_length()+trace_get_capture_length() depending on the
1689 * trace format.
1690 *
1691 * @note The trace must have been started with trace_start before calling
1692 * this function
1693 *
1694 * @note When reading from a live capture, this function will block until a
1695 * packet is observed on the capture interface. The libtrace event API
1696 * (e.g. trace_event()) should be used if non-blocking operation is required.
1697 */
1698DLLEXPORT int trace_read_packet(libtrace_t *trace, libtrace_packet_t *packet);
1699
1700/** Event types
1701 * see \ref libtrace_eventobj_t and \ref trace_event
1702 */
1703typedef enum {
1704        TRACE_EVENT_IOWAIT,     /**< Wait on the given file descriptor */
1705        TRACE_EVENT_SLEEP,      /**< Sleep for the given amount of time */
1706        TRACE_EVENT_PACKET,     /**< Packet has been read from input trace */
1707        TRACE_EVENT_TERMINATE   /**< End of input trace */
1708} libtrace_event_t;
1709
1710/** Structure returned by libtrace_event explaining what the current event is */
1711typedef struct libtrace_eventobj_t {
1712        libtrace_event_t type; /**< Event type (iowait,sleep,packet) */
1713       
1714        /** If the event is IOWAIT, the file descriptor to wait on */
1715        int fd;               
1716        /** If the event is SLEEP, the amount of time to sleep for in seconds */
1717        double seconds;       
1718        /** If the event is PACKET, the value returned by trace_read_packet() */
1719        int size;
1720} libtrace_eventobj_t;
1721
1722/** Processes the next libtrace event from an input trace.
1723 * @param trace The libtrace opaque pointer for the input trace
1724 * @param packet The libtrace_packet opaque pointer to use for reading packets
1725 * @return A libtrace_event struct containing the event type and details of the event.
1726 *
1727 * Type can be:
1728 *  TRACE_EVENT_IOWAIT  Waiting on I/O on a file descriptor
1729 *  TRACE_EVENT_SLEEP   Wait a specified amount of time for the next event
1730 *  TRACE_EVENT_PACKET  Packet was read from the trace
1731 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
1732 */
1733DLLEXPORT libtrace_eventobj_t trace_event(libtrace_t *trace,
1734                libtrace_packet_t *packet);
1735
1736
1737/** Write one packet out to the output trace
1738 *
1739 * @param trace         The libtrace_out opaque pointer for the output trace
1740 * @param packet        The packet opaque pointer of the packet to be written
1741 * @return The number of bytes written out, if zero or negative then an error has occured.
1742 */
1743DLLEXPORT int trace_write_packet(libtrace_out_t *trace, libtrace_packet_t *packet);
1744
1745/** Gets the capture format for a given packet.
1746 * @param packet        The packet to get the capture format for.
1747 * @return The capture format of the packet
1748 *
1749 * @note Due to ability to convert packets between formats relatively easily
1750 * in Libtrace, the format of the packet right now may not be the format that
1751 * the packet was originally captured with.
1752 */
1753DLLEXPORT
1754enum base_format_t trace_get_format(struct libtrace_packet_t *packet);
1755
1756/** Construct a libtrace packet from a buffer containing the packet payload.
1757 * @param[in,out] packet        Libtrace Packet object to update with the new
1758 *                              data.
1759 * @param linktype              The linktype of the packet data.
1760 * @param[in] data              The packet data (including linklayer).
1761 * @param len                   Length of packet data provided in the buffer.
1762 *
1763 * @note The constructed packet will be in the PCAP format.
1764 *
1765 * @note To be useful, the provided buffer must start with the layer 2 header
1766 * (or a metadata header, if desired).
1767 */
1768DLLEXPORT
1769void trace_construct_packet(libtrace_packet_t *packet,
1770                libtrace_linktype_t linktype, const void *data, uint16_t len);
1771
1772/*@}*/
1773
1774/** @name Protocol decodes
1775 * These functions locate and return a pointer to various headers inside a
1776 * packet
1777 *
1778 * A packet is divided up into several "layers.":
1779 *
1780 * @li Framing header -- This is the header provided by the capture format
1781 * itself rather than anything that was sent over the network. This provides
1782 * basic details about the packet record including capture lengths, wire
1783 * lengths, timestamps, direction information and any other metadata that is
1784 * part of the capture format. 
1785 *
1786 * @li Metadata header (optional) -- A header containing metadata about a
1787 * packet that was captured, but the metadata was not transmitted over the
1788 * wire.  Some examples include RadioTap and Linux_sll headers.  This can be
1789 * retrieved by trace_get_packet_meta(), or skipped using
1790 * trace_get_payload_from_meta(). There may be multiple "metadata" headers on
1791 * a packet.
1792 *
1793 * @li Layer 2/Link layer/Datalink header -- This can be retrieved by
1794 * trace_get_layer2(), or skipped using trace_get_payload_from_layer2().
1795 *
1796 * @li Layer 3/IP/IPv6 -- This can be retrieved by trace_get_layer3().  As a
1797 * convenience trace_get_ip()/trace_get_ip6() can be used to find an IPv4/IPv6
1798 * header.
1799 *
1800 * @li Layer 5/transport -- These are protocols carried in IPv4/IPv6 frames.
1801 * These can be retrieved using trace_get_transport().
1802 *
1803 * @{
1804 */
1805
1806
1807/** Gets a pointer to the first byte of the packet as it was captured and
1808 * returns its corresponding linktype and capture length.
1809 *
1810 * Use this function instead of the deprecated trace_get_link().
1811 *
1812 * @param packet The packet to get the buffer from
1813 * @param[out] linktype The linktype of the returned pointer
1814 * @param[out] remaining The capture length (the number of captured bytes from
1815 * the returned pointer)
1816 * @return A pointer to the first byte of the packet
1817 */
1818DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet,
1819                libtrace_linktype_t *linktype, uint32_t *remaining);
1820
1821/** Get a pointer to the link layer for a given packet
1822 * @param packet        The packet to get the link layer for
1823 *
1824 * @return A pointer to the link layer, or NULL if there is no link layer
1825 *
1826 * @deprecated This function is deprecated: Use trace_get_packet_buffer() or
1827 * one of the trace_get_layer*() functions instead.
1828 * @note You should call trace_get_link_type to find out what type of link
1829 * layer has been returned to you.
1830 */
1831DLLEXPORT SIMPLE_FUNCTION DEPRECATED
1832void *trace_get_link(const libtrace_packet_t *packet);
1833
1834/** Get a pointer to the IPv4 header (if any) for a given packet
1835 * @param packet        The packet to get the IPv4 header for
1836 *
1837 * @return A pointer to the IPv4 header, or NULL if there is no IPv4 header
1838 *
1839 * If a partial IP header is present, i.e. the packet has been truncated before
1840 * the end of the IP header, this function will return NULL.
1841 *
1842 * You should consider using \ref trace_get_layer3 instead of this function.
1843 */
1844DLLEXPORT SIMPLE_FUNCTION
1845libtrace_ip_t *trace_get_ip(libtrace_packet_t *packet);
1846
1847/** get a pointer to the IPv6 header (if any)
1848 * @param packet        The packet to get the IPv6 header for
1849 *
1850 * @return A pointer to the IPv6 header, or NULL if there is no IPv6 header
1851 *
1852 * If a partial IPv6 header is present, i.e. the packet has been truncated
1853 * before the end of the IP header, this function will return NULL.
1854 *
1855 * You should consider using \ref trace_get_layer3 instead of this function.
1856 */
1857DLLEXPORT SIMPLE_FUNCTION
1858libtrace_ip6_t *trace_get_ip6(libtrace_packet_t *packet);
1859
1860/** Return a pointer to the first metadata header in a packet, if present.
1861 *
1862 * This function takes a pointer to a libtrace packet and if any metadata
1863 * headers exist, returns a pointer to the first one, along with its
1864 * corresponding linktype.
1865 *
1866 * If no metadata headers exist in the packet, NULL is returned.
1867 *
1868 * A metadata header is a header that was prepended by the capturing device,
1869 * such as a Linux SLL header, or a Radiotap wireless monitoring header.
1870 * Subsequent metadata headers may be accessed with the
1871 * trace_get_payload_from_meta(...) function.
1872 *
1873 * @param packet The libtrace packet
1874 * @param[out] linktype The linktype of the returned metadata header
1875 * @param[out] remaining The number of bytes captured after the returned
1876 * pointer.
1877 * @return A pointer to the first metadata header, or NULL if there are no
1878 * metadata headers present.
1879 *
1880 * remaining may be NULL, however linktype must be provided.
1881 */
1882DLLEXPORT void *trace_get_packet_meta(const libtrace_packet_t *packet,
1883                libtrace_linktype_t *linktype,
1884                uint32_t *remaining);
1885
1886/** Returns the payload of a metadata header.
1887 *
1888 * This function takes a pointer to the start of a metadata header (either
1889 * obtained via trace_get_packet_meta(...) or by a previous call to
1890 * trace_get_payload_from_meta(...)) along with its corresponding linktype and
1891 * returns the payload, i.e. the next header. It will also update the linktype
1892 * parameter to indicate the type of payload.
1893 * 
1894 * If the linktype indicates that the header passed in is not a metadata
1895 * header, the function returns NULL to indicate this. The linktype remains
1896 * unchanged in this case.
1897 *
1898 * This function allows the user to iterate through metadata headers which are
1899 * sometimes present before the actual packet as it was received on the wire.
1900 * Examples of metadata headers include the Linux SLL header and the Radiotap
1901 * wireless monitoring header.
1902 *
1903 * If the metadata header passed into this function is truncated, this
1904 * function will return NULL, and remaining will be set to 0.
1905 *
1906 * If there are 0 bytes of payload following the provided metadata header, the
1907 * function will return a pointer to where the header would otherwise be and
1908 * remaining will be 0.
1909 *
1910 * Therefore, be sure to check the value of remaining after calling this
1911 * function!
1912 *
1913 * @param[in] meta A pointer to a metadata header
1914 * @param[in,out] linktype The linktype of meta (updated to indicate the
1915 * linktype of the returned header if applicable).
1916 * @param[in,out] remaining The number of bytes after the meta pointer.
1917 * @return A pointer to the payload of the metadata header. If meta is not a
1918 * pointer to a metadata header, NULL is returned and linktype remains
1919 * unchanged.
1920 *
1921 * All parameters are mandatory.
1922 */
1923DLLEXPORT void *trace_get_payload_from_meta(const void *meta,
1924                libtrace_linktype_t *linktype,
1925                uint32_t *remaining);
1926
1927
1928/** Get a pointer to the layer 2 header. Generally this is the first byte of the
1929 * packet as it was seen on the wire.
1930 *
1931 * This function takes a libtrace packet and skips over any metadata headers if
1932 * present (such as Linux SLL or Radiotap) and returns a pointer to the first
1933 * byte of the packet that was actually received by the network interface.
1934 *
1935 * @param packet The libtrace packet to find the layer 2 header for
1936 * @param[out] linktype The linktype of the returned layer 2 header
1937 * @param[out] remaining The number of bytes left in the packet after the
1938 * returned pointer.
1939 * @return A pointer to the first byte of the packet as it was seen on the
1940 * wire. If no layer 2 header is present, this function will return NULL.
1941 *
1942 * remaining may be NULL, otherwise it will be filled in by the function.
1943 */
1944DLLEXPORT void *trace_get_layer2(const libtrace_packet_t *packet,
1945                libtrace_linktype_t *linktype,
1946                uint32_t *remaining);
1947
1948/** Gets a pointer to the next header following a layer 2 header
1949 *
1950 * @param l2                    The pointer to the current layer 2 header
1951 * @param linktype              The type of the layer 2 header
1952 * @param[out] ethertype        An optional output variable of the ethernet type of the new header
1953 * @param[in,out] remaining     Updated with the number of captured bytes
1954                                remaining
1955 *
1956 * @return A pointer to the header following the provided layer 2 header, or
1957 * NULL if no subsequent header is present.
1958 *
1959 * Remaining must point to the number of bytes captured from the layer 2 header
1960 * and beyond.  It will be decremented by the number of bytes skipped to find
1961 * the payload.
1962 *
1963 * If the layer 2 header is complete but there are zero bytes of payload after
1964 * the end of the header, a pointer to where the payload would be is returned
1965 * and remaining will be set to 0.  If the layer 2 header is incomplete
1966 * (truncated), then NULL is returned and remaining will be set to 0.
1967 * Therefore, it is very important to check the value of remaining after
1968 * calling this function.
1969 *
1970 */
1971DLLEXPORT void *trace_get_payload_from_layer2(void *l2,
1972                libtrace_linktype_t linktype,
1973                uint16_t *ethertype,
1974                uint32_t *remaining);
1975
1976
1977/** Get a pointer to the layer 3 (e.g. IP) header.
1978 * @param packet  The libtrace packet to find the layer 3 header for
1979 * @param[out] ethertype The ethertype of the layer 3 header
1980 * @param[out] remaining The amount of captured data remaining in the packet starting from the returned pointer, i.e. including the layer 3 header.
1981 *
1982 * @return A pointer to the layer 3 header. If no layer 3 header is present in
1983 * the packet, NULL is returned. If the layer 3 header is truncated, a valid
1984 * pointer will still be returned so be sure to check the value of remaining
1985 * before attempting to process the returned header.
1986 *
1987 * remaining may be NULL, otherwise it will be set to the number of captured
1988 * bytes after the pointer returned.
1989 */
1990DLLEXPORT
1991void *trace_get_layer3(const libtrace_packet_t *packet,
1992                uint16_t *ethertype, uint32_t *remaining);
1993
1994/** Calculates the expected IP checksum for a packet.
1995 * @param packet        The libtrace packet to calculate the checksum for
1996 * @param[out] csum     The checksum that is calculated by this function. This
1997 *                      may not be NULL.
1998 *
1999 * @return A pointer to the original checksum field within the IP
2000 * header. If the checksum field is not present in the packet, NULL is returned.
2001 *
2002 * @note The return value points to the checksum that exists within the current
2003 * packet. The value in csum is the value that the checksum should be, given
2004 * the current packet contents. 
2005 *
2006 * @note This function involves the use of a memcpy, so be careful about
2007 * calling it excessively if performance is a concern for you.
2008 *
2009 * New in libtrace 3.0.17
2010 */
2011DLLEXPORT uint16_t *trace_checksum_layer3(libtrace_packet_t *packet,
2012                uint16_t *csum);
2013
2014/** Calculates the expected checksum for the transport header in a packet.
2015 * @param packet        The libtrace packet to calculate the checksum for
2016 * @param[out] csum     The checksum that is calculated by this function. This
2017 *                      may not be NULL.
2018 *
2019 * @return A pointer to the original checksum field within the transport
2020 * header. If the checksum field is not present in the packet, NULL is returned.
2021 *
2022 * @note The return value points to the checksum that exists within the current
2023 * packet. The value in csum is the value that the checksum should be, given
2024 * the current packet contents. 
2025 *
2026 * @note This function involves the use of a memcpy, so be careful about
2027 * calling it excessively if performance is a concern for you.
2028 *
2029 * @note Because transport checksums are calculated across the entire payload,
2030 * truncated packets will result in NULL being returned.
2031 *
2032 * This function will determine the appropriate checksum for whatever transport
2033 * layer header is present in the provided packet. At this stage, this only
2034 * currently works for TCP, UDP and ICMP packets.
2035 *
2036 * Be wary of TCP checksum offloading if you are examining the checksum of
2037 * packets captured on the same host that generated them!
2038 *
2039 * New in libtrace 3.0.17
2040 */
2041DLLEXPORT uint16_t *trace_checksum_transport(libtrace_packet_t *packet,
2042                uint16_t *csum);
2043
2044/** Calculates the fragment offset in bytes for an IP packet
2045 * @param packet        The libtrace packet to calculate the offset for
2046 * @param[out] more     A boolean flag to indicate whether there are more
2047 *                      fragments after the current packet.
2048 * @return The fragment offset for the packet in bytes. If the packet is not
2049 * an IP packet or the fragment offset is not present in packet, the return
2050 * value will be 0.
2051 *
2052 * @note The value returned is in bytes, not 8-octet units as it is stored
2053 * in the fragment offset field in the headers. In other words, libtrace
2054 * automatically does the multiplication for you.
2055 *
2056 * The value passed in for 'more' does not matter; it will be overwritten
2057 * with the value of the More Fragments flag from the IP header.
2058 *
2059 * New in libtrace 3.0.20
2060 */
2061DLLEXPORT uint16_t trace_get_fragment_offset(const libtrace_packet_t *packet,
2062                uint8_t *more);
2063
2064/** Gets a pointer to the transport layer header (if any)
2065 * @param packet   The libtrace packet to find the transport header for
2066 * @param[out] proto    The protocol present at the transport layer.
2067 * @param[out] remaining The amount of captured data remaining in the packet
2068 * starting from the returned pointer, i.e. including the transport header.
2069 *
2070 * @return A pointer to the transport layer header. If no transport header is
2071 * present in the packet, NULL is returned. If the transport header is
2072 * truncated, a valid pointer will still be returned so be sure to check the
2073 * value of remaining before attempting to process the returned header.
2074 *
2075 * remaining may be NULL, otherwise it will be set to the number of captured
2076 * bytes after the returned pointer.
2077 *
2078 * @note proto may be NULL if proto is unneeded.
2079 */
2080DLLEXPORT void *trace_get_transport(const libtrace_packet_t *packet,
2081                uint8_t *proto, uint32_t *remaining);
2082
2083/** Gets a pointer to the payload following an IPv4 header
2084 * @param ip            The IPv4 Header
2085 * @param[out] proto    The protocol of the header following the IPv4 header
2086 * @param[in,out] remaining Updated with the number of captured bytes remaining
2087 *
2088 * @return A pointer to the transport layer header, or NULL if no subsequent
2089 * header is present.
2090 *
2091 * When calling this function, remaining must contain the number of captured
2092 * bytes remaining in the packet starting from the IPv4 header (including the
2093 * IPv4 header itself).
2094 *
2095 * remaining will be decremented by the size of the IPv4 header (including any
2096 * options). If the IPv4 header is complete but there are zero bytes of payload
2097 * after the IPv4 header, a pointer to where the payload would be is returned
2098 * and remaining will be set to 0.  If the IPv4 header is incomplete, NULL will
2099 * be returned and remaining will be set to 0. Therefore, it is very important
2100 * to check the value of remaining after calling this function.
2101 *
2102 * proto may be NULL, in which case it won't be updated.
2103 *
2104 * @note This is similar to trace_get_transport_from_ip in libtrace2
2105 */
2106DLLEXPORT void *trace_get_payload_from_ip(libtrace_ip_t *ip, uint8_t *proto,
2107                uint32_t *remaining);
2108
2109/** Gets a pointer to the payload following an IPv6 header
2110 * @param ipptr         The IPv6 Header
2111 * @param[out] proto    The protocol of the header following the IPv6 header
2112 * @param[in,out] remaining Updated with the number of captured bytes remaining
2113 *
2114 * @return A pointer to the transport layer header, or NULL if no subsequent
2115 * header is present.
2116 *
2117 * When calling this function, remaining must contain the number of captured
2118 * bytes remaining in the packet starting from the IPv6 header (including the
2119 * IPv6 header itself).
2120 *
2121 * remaining will be decremented by the size of the IPv6 header (including any
2122 * options). If the IPv6 header is complete but there are zero bytes of payload
2123 * after the IPv6 header, a pointer to where the payload would be is returned
2124 * and remaining will be set to 0.  If the IPv6 header is incomplete, NULL will
2125 * be returned and remaining will be set to 0. Therefore, it is very important
2126 * to check the value of remaining after calling this function.
2127 *
2128 * proto may be NULL, in which case it won't be updated.
2129 *
2130 */
2131DLLEXPORT void *trace_get_payload_from_ip6(libtrace_ip6_t *ipptr,
2132                uint8_t *proto, uint32_t *remaining);
2133
2134/** Gets a pointer to the payload following a link header
2135 * @param linkptr       A pointer to the link layer header
2136 * @param linktype      The linktype of the link header being examined
2137 * @param[out] type     An output variable for the ethernet type
2138 * @param[in,out] remaining Updated with the number of captured bytes remaining
2139 *
2140 * @return A pointer to the header following the link header, or NULL if no
2141 * subsequent header is present.
2142 *
2143 * When calling this function, remaining must contain the number of captured
2144 * bytes remaining in the packet starting from the link header (including the
2145 * link header itself). remaining will be updated to contain the number of
2146 * bytes remaining after the link header has been skipped.
2147 *
2148 * @deprecated This function is deprecated: you should be using
2149 * trace_get_payload_from_layer2() or trace_get_payload_from_meta() instead.
2150 *
2151 */
2152DLLEXPORT void *trace_get_payload_from_link(void *linkptr,
2153                libtrace_linktype_t linktype,
2154                uint16_t *type, uint32_t *remaining);
2155
2156/** Gets a pointer to the payload following an 802.1q (VLAN) header.
2157 * @param vlan      A pointer to the VLAN header
2158 * @param[out] type  The ethernet type, replaced with the VLAN ether type
2159 * @param[in,out] remaining Updated with the number of captured bytes remaining
2160 *
2161 * @return A pointer to the header beyond the VLAN header, if one is present.
2162 * Otherwise, returns NULL. 
2163 *
2164 * When calling this function, remaining must contain the number of captured
2165 * bytes remaining in the packet starting from the VLAN header (including the
2166 * VLAN header itself). remaining will be updated to contain the number of
2167 * bytes remaining after the VLAN header has been skipped.
2168 *
2169 * If the VLAN header is complete but there are zero bytes of payload after
2170 * the VLAN header, a pointer to where the payload would be is returned and
2171 * remaining will be set to 0.  If the VLAN header is incomplete, NULL will be
2172 * returned and remaining will be set to 0. Therefore, it is important to check
2173 * the value of remaining after calling this function.
2174 *
2175 * type will be set to the ethertype of the VLAN payload. This parameter is not
2176 * mandatory, but is highly recommended.
2177 *
2178 */
2179DLLEXPORT void *trace_get_payload_from_vlan(
2180                void *vlan, uint16_t *type, uint32_t *remaining);
2181
2182/** Gets a pointer to the payload following an MPLS header.
2183 * @param mpls      A pointer to the MPLS header
2184 * @param[out] type  The ethernet type, replaced by the ether type of the
2185 * returned header - 0x0000 if an Ethernet header is returned
2186 * @param[in,out] remaining Updated with the number of captured bytes remaining
2187 *
2188 * @return A pointer to the header beyond the MPLS label, if one is present.
2189 * Will return NULL if there is not enough bytes remaining to skip past the
2190 * MPLS label.
2191 *
2192 * When calling this function, remaining must contain the number of captured
2193 * bytes remaining in the packet starting from the MPLS header (including the
2194 * MPLS header itself). remaining will be updated to contain the number of
2195 * bytes remaining after the MPLS header has been skipped.
2196 *
2197 * If the MPLS header is complete but there are zero bytes of payload after
2198 * the MPLS header, a pointer to where the payload would be is returned and
2199 * remaining will be set to 0.  If the MPLS header is incomplete, NULL will be
2200 * returned and remaining will be set to 0. Therefore, it is important to check
2201 * the value of remaining after calling this function.
2202 *
2203 * type will be set to the ethertype of the MPLS payload. This parameter is
2204 * mandatory - it may not be NULL.
2205 *
2206 * @note This function will only remove one MPLS label at a time - the type
2207 * will be set to 0x8847 if there is another MPLS label following the one
2208 * skipped by this function.
2209 *
2210 */
2211DLLEXPORT void *trace_get_payload_from_mpls(
2212                void *mpls, uint16_t *type, uint32_t *remaining);
2213
2214/** Gets a pointer to the payload following a PPPoE header
2215 * @param pppoe      A pointer to the PPPoE header
2216 * @param[out] type  The ethernet type, replaced by the ether type of the
2217 * returned header - 0x0000 if an Ethernet header is returned
2218 * @param[in,out] remaining  Updated with the number of captured bytes remaining
2219 *
2220 * @return A pointer to the header beyond the PPPoE header. NOTE that this
2221 * function will also skip over the PPP header that will immediately follow
2222 * the PPPoE header. This function will return NULL if there are not enough
2223 * bytes remaining to skip past both the PPPoE and PPP headers.
2224 *
2225 * When calling this function, remaining must contain the number of captured
2226 * bytes remaining in the packet starting from the PPPoE header (including the
2227 * PPPoE header itself). remaining will be updated to contain the number of
2228 * bytes remaining after the PPPoE and PPP headers have been removed.
2229 *
2230 * If the PPPoE and PPP headers are complete but there are zero bytes of
2231 * payload after the PPP header, a pointer to where the payload would be is
2232 * returned and remaining will be set to 0.  If the PPPoE or PPP header is
2233 * incomplete, NULL will be returned and remaining will be set to 0. Therefore,
2234 * it is important to check the value of remaining after calling this function.
2235 *
2236 * type will be set to the ether type of the PPP payload. This parameter is
2237 * mandatory - it may not be NULL.
2238 *
2239 */
2240DLLEXPORT void *trace_get_payload_from_pppoe(
2241                void *pppoe, uint16_t *type, uint32_t *remaining);
2242
2243/** Gets a pointer to the payload following a TCP header
2244 * @param tcp           A pointer to the TCP header
2245 * @param[in,out] remaining Updated with the number of captured bytes remaining
2246 *
2247 * @return A pointer to the TCP payload, or NULL if the TCP header is truncated.
2248 *
2249 * When calling this function, remaining must contain the number of captured
2250 * bytes remaining in the packet starting from the TCP header (including the
2251 * TCP header itself). remaining will be updated to contain the number of
2252 * bytes remaining after the TCP header has been skipped.
2253 *
2254 * If the TCP header is complete but there are zero bytes of payload after
2255 * the TCP header, a pointer to where the payload would be is returned and
2256 * remaining will be set to 0.  If the TCP header is incomplete, NULL will be
2257 * returned and remaining will be set to 0. Therefore, it is important to check
2258 * the value of remaining after calling this function.
2259 *
2260 */
2261DLLEXPORT void *trace_get_payload_from_tcp(libtrace_tcp_t *tcp,
2262                uint32_t *remaining);
2263
2264/** Gets a pointer to the payload following a UDP header
2265 * @param udp           A pointer to the UDP header
2266 * @param[in,out] remaining Updated with the number of captured bytes remaining
2267 *
2268 * @return A pointer to the UDP payload, or NULL if the UDP header is truncated.
2269 *
2270 * When calling this function, remaining must contain the number of captured
2271 * bytes remaining in the packet starting from the UDP header (including the
2272 * UDP header itself). remaining will be updated to contain the number of
2273 * bytes remaining after the UDP header has been skipped.
2274 *
2275 * If the UDP header is complete but there are zero bytes of payload after
2276 * the UDP header, a pointer to where the payload would be is returned and
2277 * remaining will be set to 0.  If the UDP header is incomplete, NULL will be
2278 * returned and remaining will be set to 0. Therefore, it is important to check
2279 * the value of remaining after calling this function.
2280 *
2281 */
2282DLLEXPORT void *trace_get_payload_from_udp(libtrace_udp_t *udp, uint32_t *remaining);
2283
2284/** Gets a pointer to the payload following a ICMP header
2285 * @param icmp           A pointer to the ICMP header
2286 * @param[in,out] remaining Updated with the number of captured bytes remaining
2287 *
2288 * @return A pointer to the ICMP payload, or NULL if the ICMP header is
2289 * truncated.
2290 *
2291 * When calling this function, remaining must contain the number of captured
2292 * bytes remaining in the packet starting from the ICMP header (including the
2293 * ICMP header itself). remaining will be updated to contain the number of
2294 * bytes remaining after the ICMP header has been skipped.
2295 *
2296 * If the ICMP header is complete but there are zero bytes of payload after
2297 * the ICMP header, a pointer to where the payload would be is returned and
2298 * remaining will be set to 0.  If the ICMP header is incomplete, NULL will be
2299 * returned and remaining will be set to 0. Therefore, it is important to check
2300 * the value of remaining after calling this function.
2301 *
2302 * @note In the case of some ICMP messages, the payload may be the IP header
2303 * from the packet that triggered the ICMP message.
2304 *
2305 */
2306DLLEXPORT void *trace_get_payload_from_icmp(libtrace_icmp_t *icmp,
2307                uint32_t *remaining);
2308
2309/** Gets a pointer to the payload following a ICMPv6 header
2310 * @param icmp           A pointer to the ICMPv6 header
2311 * @param[in,out] remaining Updated with the number of captured bytes remaining
2312 *
2313 * @return A pointer to the ICMPv6 payload, or NULL if the ICMPv6 header is
2314 * truncated.
2315 *
2316 * When calling this function, remaining must contain the number of captured
2317 * bytes remaining in the packet starting from the ICMPv6 header (including the
2318 * ICMP header itself). remaining will be updated to contain the number of
2319 * bytes remaining after the ICMPv6 header has been skipped.
2320 *
2321 * If the ICMPv6 header is complete but there are zero bytes of payload after
2322 * the header, a pointer to where the payload would be is returned and
2323 * remaining will be set to 0.  If the ICMPv6 header is incomplete, NULL will be
2324 * returned and remaining will be set to 0. Therefore, it is important to check
2325 * the value of remaining after calling this function.
2326 *
2327 * @note In the case of some ICMPv6 messages, the payload may be the IP header
2328 * from the packet that triggered the ICMP message.
2329 *
2330 */
2331DLLEXPORT void *trace_get_payload_from_icmp6(libtrace_icmp6_t *icmp,
2332                uint32_t *remaining);
2333
2334/** Gets a pointer to the payload following a GRE header
2335 * @param         gre       A pointer to the beginning of the GRE header.
2336 * @param[in,out] remaining Updated with the number of captured bytes remaining.
2337 *
2338 * @return A pointer to the GRE payload, or NULL if the GRE header is truncated.
2339 *
2340 * When calling this function, remaining must contain the number of captured
2341 * bytes remaining in the packet starting from the GRE header (including the
2342 * GRE header itself). remaining will be updated to contain the number of
2343 * bytes remaining after the GRE header has been skipped.
2344 *
2345 * If the GRE header is complete but there are zero bytes of payload after
2346 * the header, a pointer to where the payload would be is returned and
2347 * remaining will be set to 0.  If the GRE header is incomplete, NULL will be
2348 * returned and remaining will be set to 0. Therefore, it is important to check
2349 * the value of remaining after calling this function.
2350 */
2351DLLEXPORT void *trace_get_payload_from_gre(libtrace_gre_t *gre,
2352                uint32_t *remaining);
2353
2354/** Gets a pointer to the payload following a VXLAN header
2355 * @param         udp       A pointer to the beginning of the UDP header.
2356 * @param[in,out] remaining Updated with the number of captured bytes remaining.
2357 *
2358 * @return A pointer to the beginning of the VXLAN header, or NULL if the UDP
2359 * header is truncated, or this is not a VXLAN packet.
2360 *
2361 */
2362DLLEXPORT libtrace_vxlan_t *trace_get_vxlan_from_udp(libtrace_udp_t *udp,
2363                uint32_t *remaining);
2364
2365/** Gets a pointer to the payload following a VXLAN header
2366 * @param         vxlan       A pointer to the beginning of the VXLAN header.
2367 * @param[in,out] remaining Updated with the number of captured bytes remaining.
2368 *
2369 * @return A pointer to the VXLAN payload, or NULL if the VXLAN header is
2370 * truncated.
2371 *
2372 * When calling this function, remaining must contain the number of captured
2373 * bytes remaining in the packet starting from the VXLAN header (including the
2374 * VXLAN header itself). remaining will be updated to contain the number of
2375 * bytes remaining after the VXLAN header has been skipped.
2376 *
2377 * If the VXLAN header is complete but there are zero bytes of payload after
2378 * the header, a pointer to where the payload would be is returned and
2379 * remaining will be set to 0.  If the VXLAN header is incomplete, NULL will be
2380 * returned and remaining will be set to 0. Therefore, it is important to check
2381 * the value of remaining after calling this function.
2382 */
2383DLLEXPORT void *trace_get_payload_from_vxlan(libtrace_vxlan_t *vxlan,
2384                uint32_t *remaining);
2385
2386/** Get a pointer to the TCP header (if present)
2387 * @param packet        The packet to get the TCP header from
2388 *
2389 * @return A pointer to the TCP header, or NULL if there is not a complete TCP
2390 * header present in the packet.
2391 *
2392 * This is a short-cut function enabling quick and easy access to the TCP
2393 * header if that is all you care about. However, we recommend the use of the
2394 * more generic trace_get_transport() function instead.
2395 *
2396 * @note Unlike trace_get_transport(), this function will return NULL if the
2397 * TCP header is incomplete or truncated.
2398 */
2399DLLEXPORT SIMPLE_FUNCTION
2400libtrace_tcp_t *trace_get_tcp(libtrace_packet_t *packet);
2401
2402/** Get a pointer to the TCP header following an IPv4 header (if present)
2403 * @param ip            The IP header to find the subsequent TCP header for
2404 * @param[in,out] remaining Updated with the number of captured bytes remaining
2405 *
2406 * @return A pointer to the TCP header, or NULL if no TCP header is present in
2407 * the packet.
2408 *
2409 * When calling this function, remaining must contain the number of captured
2410 * bytes remaining in the packet starting from the IP header (including the
2411 * IP header itself). remaining will be updated to contain the number of
2412 * bytes remaining after the IP header has been skipped.
2413 *
2414 * If the IP header is complete but there are zero bytes of payload after
2415 * the IP header, a pointer to where the payload would be is returned and
2416 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
2417 * returned and remaining will be set to 0. Therefore, it is important to check
2418 * the value of remaining after calling this function.
2419 *
2420 * @note This function is rather redundant now that the layer 3 header is
2421 * cached. There should be no performance advantage for the user to call this
2422 * function over just calling trace_get_transport().
2423 *
2424 * @note The last parameter has changed from libtrace2
2425 */
2426DLLEXPORT SIMPLE_FUNCTION
2427libtrace_tcp_t *trace_get_tcp_from_ip(libtrace_ip_t *ip, uint32_t *remaining);
2428
2429/** Get a pointer to the UDP header (if present)
2430 * @param packet        The packet to get the UDP header from
2431 *
2432 * @return A pointer to the UDP header, or NULL if there is not a complete UDP
2433 * header present in the packet.
2434 *
2435 * This is a short-cut function enabling quick and easy access to the UDP
2436 * header if that is all you care about. However, we recommend the use of the
2437 * more generic trace_get_transport() function instead.
2438 *
2439 * @note Unlike trace_get_transport(), this function will return NULL if the
2440 * UDP header is incomplete or truncated.
2441 */
2442DLLEXPORT SIMPLE_FUNCTION
2443libtrace_udp_t *trace_get_udp(libtrace_packet_t *packet);
2444
2445/** Get a pointer to the UDP header following an IPv4 header (if present)
2446 * @param ip            The IP header to find the subsequent UDP header for
2447 * @param[in,out] remaining Updated with the number of captured bytes remaining
2448 *
2449 * @return A pointer to the UDP header, or NULL if no UDP header is present in
2450 * the packet.
2451 *
2452 * When calling this function, remaining must contain the number of captured
2453 * bytes remaining in the packet starting from the IP header (including the
2454 * IP header itself). remaining will be updated to contain the number of
2455 * bytes remaining after the IP header has been skipped.
2456 *
2457 * If the IP header is complete but there are zero bytes of payload after
2458 * the IP header, a pointer to where the payload would be is returned and
2459 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
2460 * returned and remaining will be set to 0. Therefore, it is important to check
2461 * the value of remaining after calling this function.
2462 *
2463 * @note This function is rather redundant now that the layer 3 header is
2464 * cached. There should be no performance advantage for the user to call this
2465 * function over just calling trace_get_transport().
2466 *
2467 * @note The last parameter has changed from libtrace2
2468 */
2469DLLEXPORT SIMPLE_FUNCTION
2470libtrace_udp_t *trace_get_udp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
2471
2472/** Get a pointer to the ICMP header (if present)
2473 * @param packet        The packet to get the ICMP header from
2474 *
2475 * @return A pointer to the ICMP header, or NULL if there is not a complete
2476 * ICMP header present in the packet.
2477 *
2478 * This is a short-cut function enabling quick and easy access to the ICMP
2479 * header if that is all you care about. However, we recommend the use of the
2480 * more generic trace_get_transport() function instead.
2481 *
2482 * @note Unlike trace_get_transport(), this function will return NULL if the
2483 * ICMP header is incomplete or truncated.
2484 */
2485DLLEXPORT SIMPLE_FUNCTION
2486libtrace_icmp_t *trace_get_icmp(libtrace_packet_t *packet);
2487
2488/** Get a pointer to the ICMPv6 header (if present)
2489 * @param packet        The packet to get the ICMPv6 header from
2490 *
2491 * @return A pointer to the ICMPv6 header, or NULL if there is not a complete
2492 * ICMP header present in the packet.
2493 *
2494 * This is a short-cut function enabling quick and easy access to the ICMPv6
2495 * header if that is all you care about. However, we recommend the use of the
2496 * more generic trace_get_transport() function instead.
2497 *
2498 * @note Unlike trace_get_transport(), this function will return NULL if the
2499 * ICMPv6 header is incomplete or truncated.
2500 */
2501DLLEXPORT SIMPLE_FUNCTION
2502libtrace_icmp6_t *trace_get_icmp6(libtrace_packet_t *packet);
2503
2504/** Get a pointer to the ICMP header following an IPv4 header (if present)
2505 * @param ip            The IP header to find the subsequent ICMP header for
2506 * @param[in,out] remaining Updated with the number of captured bytes remaining
2507 *
2508 * @return A pointer to the ICMP header, or NULL if no UDP header is present in
2509 * the packet.
2510 *
2511 * When calling this function, remaining must contain the number of captured
2512 * bytes remaining in the packet starting from the IP header (including the
2513 * IP header itself). remaining will be updated to contain the number of
2514 * bytes remaining after the IP header has been skipped.
2515 *
2516 * If the IP header is complete but there are zero bytes of payload after
2517 * the IP header, a pointer to where the payload would be is returned and
2518 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
2519 * returned and remaining will be set to 0. Therefore, it is important to check
2520 * the value of remaining after calling this function.
2521 *
2522 * @note This function is rather redundant now that the layer 3 header is
2523 * cached. There should be no performance advantage for the user to call this
2524 * function over just calling trace_get_transport().
2525 *
2526 * @note The last parameter has changed from libtrace2
2527 */
2528DLLEXPORT SIMPLE_FUNCTION
2529libtrace_icmp_t *trace_get_icmp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
2530
2531/** Get a pointer to the OSPF header (if present)
2532 * @param packet        The packet to get the OSPF header from
2533 * @param[out] version  The OSPF version number
2534 * @param[out] remaining        Updated with the number of captured bytes remaining
2535 * @return A pointer to the start of the OSPF header or NULL if there is no
2536 * complete OSPF header present in the packet
2537 *
2538 * This is a short-cut function enabling quick and easy access to the OSPF
2539 * header. If you only care about the OSPF header, this function may be useful
2540 * but we otherwise recommend the use of the more generic trace_get_transport()
2541 * function instead.
2542 *
2543 * Upon return, 'version' is updated to contain the OSPF version number for the
2544 * packet so that the returned pointer may be cast to the correct type.
2545 * The version parameter MUST contain a valid pointer; it MUST NOT be NULL.
2546 *
2547 * 'remaining' is also set to contain the number of captured bytes remaining
2548 * starting from the pointer returned by this function.
2549 *
2550 * @note Unlike trace_get_transport(), this function will return NULL if the
2551 * OSPF header is incomplete or truncated.
2552 */
2553DLLEXPORT SIMPLE_FUNCTION
2554void *trace_get_ospf_header(libtrace_packet_t *packet, uint8_t *version,
2555                uint32_t *remaining);
2556
2557/** Get a pointer to the contents of the OSPF packet *after* the OSPF header
2558 * @param header        The OSPF header to get the OSPF contents from
2559 * @param[out] ospf_type        The OSPF packet type
2560 * @param[in, out] remaining    Updated with the number of captured bytes remaining
2561 * @return A pointer to the first byte after the OSPF header.
2562 *
2563 * This function returns a void pointer that can be cast appropriately
2564 * based on the ospf_type. For example, if the ospf_type is TRACE_OSPF_HELLO
2565 * then the return pointer should be cast as a libtrace_ospf_hello_v2_t
2566 * structure.
2567 *
2568 * If the OSPF header is truncated, then NULL will be returned. If the OSPF
2569 * contents are missing or truncated, the pointer to the start of the content
2570 * will still be returned so be careful to check the value of remaining.
2571 *
2572 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2573 * packet starting from the beginning of the OSPF header. It will be updated
2574 * to contain the number of bytes remaining from the start of the OSPF contents.
2575 *
2576 * @note This function only works for OSPF version 2 packets.
2577 * @note 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.
2578 * @note 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.
2579 *
2580 */
2581DLLEXPORT SIMPLE_FUNCTION
2582void *trace_get_ospf_contents_v2(libtrace_ospf_v2_t *header,
2583                uint8_t *ospf_type, uint32_t *remaining);
2584
2585/** Get a pointer to the start of the first LSA contained within an LS Update packet
2586 * @param ls_update     Pointer to the LS Update header
2587 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2588 * @return A pointer to the first LSA in the packet.
2589 *
2590 * This function simply skips past the LS Update header to provide a suitable
2591 * pointer to pass into trace_get_next_ospf_lsa_v2.
2592 *
2593 * If the OSPF packet is truncated, then NULL will be returned.
2594 *
2595 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2596 * packet starting from the beginning of the LS Update header. It will be
2597 * updated to contain the number of bytes remaining from the start of the
2598 * first LSA.
2599 *
2600 * @note This function only works for OSPF version 2 packets.
2601 * @note trace_get_next_ospf_lsa_v2() should be subequently used to process the LSAs
2602 */
2603DLLEXPORT SIMPLE_FUNCTION
2604unsigned char *trace_get_first_ospf_lsa_from_update_v2(
2605                libtrace_ospf_ls_update_t *ls_update,
2606                uint32_t *remaining);
2607
2608/** Get a pointer to the start of the first LSA contained within an Database Description packet
2609 * @param db_desc       Pointer to the Database Description header
2610 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2611 * @return A pointer to the first LSA in the packet.
2612 *
2613 * This function simply skips past the Database Description header to provide a
2614 * suitable pointer to pass into trace_get_next_ospf_lsa_header_v2.
2615 *
2616 * If the OSPF packet is truncated, then NULL will be returned.
2617 *
2618 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2619 * packet starting from the beginning of the Database Description header. It
2620 * will be updated to contain the number of bytes remaining from the start of
2621 * the first LSA.
2622 *
2623 * @note This function only works for OSPF version 2 packets.
2624 * @note trace_get_next_ospf_lsa_header_v2() should be subequently used to process the LSA headers
2625 */
2626DLLEXPORT SIMPLE_FUNCTION
2627unsigned char *trace_get_first_ospf_lsa_from_db_desc_v2(
2628                libtrace_ospf_db_desc_v2_t *db_desc,
2629                uint32_t *remaining);
2630
2631/** Get a pointer to the start of the first link contained within a Router LSA
2632 * @param lsa   Pointer to the Router LSA
2633 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2634 * @return A pointer to the first link in the packet.
2635 *
2636 * This function simply skips past the Router LSA header to provide a
2637 * suitable pointer to pass into trace_get_next_ospf_link_v2.
2638 *
2639 * If the OSPF packet is truncated, then NULL will be returned.
2640 *
2641 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2642 * packet starting from the beginning of the Router LSA (not including the LSA
2643 * header) header. It will be updated to contain the number of bytes remaining
2644 * from the start of the first Link.
2645 *
2646 * @note This function only works for OSPF version 2 packets.
2647 * @note trace_get_next_ospf_link_v2() should be subequently used to process
2648 * the links
2649 */
2650DLLEXPORT SIMPLE_FUNCTION
2651unsigned char *trace_get_first_ospf_link_from_router_lsa_v2(
2652                libtrace_ospf_router_lsa_v2_t *lsa,
2653                uint32_t *remaining);
2654
2655/** Parses an OSPF Router LSA Link and finds the next Link (if there is one)
2656 * @param[in,out] current       Pointer to the next Link (updated by this function)
2657 * @param[out] link             Set to point to the Link located at the original value of current
2658 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2659 * @param[out] link_len         Set to the size of the Link pointed to by 'link'
2660 * @return 0 if there are no more links after the current one, 1 otherwise.
2661 *
2662 * When called, 'current' MUST point to an OSPF Router LSA link. Ideally, this
2663 * would come from either a call to
2664 * trace_get_first_ospf_link_from_router_lsa_v2() or a previous call of this
2665 * function.
2666 *
2667 * 'link' will be set to the value of 'current', so that the caller may then
2668 * do any processing they wish on that particular link. 'current' is advanced
2669 * to point to the next link and 'link_len' is updated to report the size of
2670 * the original link.
2671 *
2672 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2673 * packet starting from the beginning of the Link pointed to by 'current'.
2674 * It will be updated to contain the number of bytes remaining from the start
2675 * of the next link.
2676 *
2677 * If this function returns 0 but 'link' is NOT NULL, that link is still valid
2678 * but there are no more links after this one.
2679 * If this function returns 0 AND link is NULL, the link is obviously not
2680 * suitable for processing.
2681 *
2682 * @note This function only works for OSPF version 2 packets.
2683 */
2684DLLEXPORT SIMPLE_FUNCTION
2685int trace_get_next_ospf_link_v2(unsigned char **current,
2686                libtrace_ospf_link_v2_t **link,
2687                uint32_t *remaining,
2688                uint32_t *link_len);
2689
2690/** Parses an OSPF LSA and finds the next LSA (if there is one)
2691 * @param[in,out] current       Pointer to the next LSA (updated by this function)
2692 * @param[out] lsa_hdr          Set to point to the header of the LSA located at the original value of current
2693 * @param[out] lsa_body         Set to point to the body of the LSA located at the original value of current
2694 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2695 * @param[out] lsa_type         Set to the type of the LSA located at the original value of current
2696 * @param[out] lsa_length       Set to the size of the LSA located at the original value of current
2697 * @return 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.
2698 *
2699 * When called, 'current' MUST point to an OSPF LSA. Ideally, this would come
2700 * from either a call to trace_get_first_ospf_lsa_from_update_v2() or a
2701 * previous call of this function.
2702 *
2703 * This function should only be used to access COMPLETE LSAs, i.e. LSAs that
2704 * have both a header and a body. In OSPFv2, only the LSAs contained within
2705 * LSA Update packets meet this requirement. trace_get_next_ospf_lsa_header_v2
2706 * should be used to read header-only LSAs, e.g. those present in LS Acks.
2707 *
2708 * 'lsa_hdr' will be set to the value of 'current', so that the caller may then
2709 * do any processing they wish on that particular LSA. 'lsa_body' will be set
2710 * to point to the first byte after the LSA header. 'current' is advanced
2711 * to point to the next LSA. 'lsa_length' is updated to contain the size of
2712 * the parsed LSA, while 'lsa_type' is set to indicate the LSA type.
2713 *
2714 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2715 * packet starting from the beginning of the LSA pointed to by 'current'.
2716 * It will be updated to contain the number of bytes remaining from the start
2717 * of the next LSA.
2718 *
2719 * If this function returns 0 but 'lsa_hdr' is NOT NULL, that LSA is still
2720 * valid but there are no more LSAs after this one.
2721 * If this function returns 0 AND 'lsa_hdr' is NULL, the LSA is obviously not
2722 * suitable for processing.
2723 *
2724 * It is also recommended to check the value of 'lsa_body' before
2725 * de-referencing it. 'lsa_body' will be set to NULL if there is only an LSA
2726 * header present.
2727 *
2728 * @note This function only works for OSPF version 2 packets.
2729 *
2730 */
2731DLLEXPORT SIMPLE_FUNCTION
2732int trace_get_next_ospf_lsa_v2(unsigned char **current,
2733                libtrace_ospf_lsa_v2_t **lsa_hdr,
2734                unsigned char **lsa_body,
2735                uint32_t *remaining,
2736                uint8_t *lsa_type,
2737                uint16_t *lsa_length);
2738
2739/** Parses an OSPF LSA header and finds the next LSA (if there is one)
2740 * @param[in,out] current       Pointer to the next LSA (updated by this function)
2741 * @param[out] lsa_hdr          Set to point to the header of the LSA located at the original value of current
2742 * @param[in,out] remaining     Updated with the number of captured bytes remaining
2743 * @param[out] lsa_length       Set to the size of the LSA located at the original value of current
2744 * @return 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.
2745 *
2746 * When called, 'current' MUST point to an OSPF LSA. Ideally, this would come
2747 * from either a call to trace_get_first_ospf_lsa_from_db_desc_v2() or a
2748 * previous call of this function.
2749 *
2750 * This function should only be used to access LSA headers, i.e. LSAs that
2751 * have a header only. In OSPFv2, the LSAs contained within LSA Ack and
2752 * Database Description packets meet this requirement.
2753 * trace_get_next_ospf_lsa_v2 should be used to read full LSAs, e.g. those
2754 * present in LS Updates.
2755 *
2756 * 'lsa_hdr' will be set to the value of 'current', so that the caller may then
2757 * do any processing they wish on that particular LSA header. 'current' is
2758 * advanced to point to the next LSA header. 'lsa_length' is updated to contain
2759 * the size of the parsed LSA header.
2760 *
2761 * 'remaining' MUST be set to the amount of bytes remaining in the captured
2762 * packet starting from the beginning of the LSA pointed to by 'current'.
2763 * It will be updated to contain the number of bytes remaining from the start
2764 * of the next LSA.
2765 *
2766 * If this function returns 0 but 'lsa_hdr' is NOT NULL, that LSA is still
2767 * valid but there are no more LSAs after this one.
2768 * If this function returns 0 AND 'lsa_hdr' is NULL, the LSA is obviously not
2769 * suitable for processing.
2770 *
2771 * @note This function only works for OSPF version 2 packets.
2772 *
2773 */
2774DLLEXPORT SIMPLE_FUNCTION
2775int trace_get_next_ospf_lsa_header_v2(unsigned char **current,
2776                libtrace_ospf_lsa_v2_t **lsa_hdr,
2777                uint32_t *remaining,
2778                uint8_t *lsa_type,
2779                uint16_t *lsa_length);
2780
2781/** Extracts the metric field from an AS External LSA packet
2782 *
2783 * @param as_lsa        The AS External LSA
2784 * @returns The value of the metric field
2785 *
2786 * The metric field in the AS External LSA packet is a 24-bit value, which
2787 * is difficult to extract correctly. To avoid byte-ordering issues, use this
2788 * function which will extract the correct value for you.
2789 */
2790DLLEXPORT SIMPLE_FUNCTION
2791uint32_t trace_get_ospf_metric_from_as_external_lsa_v2(
2792                libtrace_ospf_as_external_lsa_v2_t *as_lsa);
2793
2794/** Extracts the metric field from a Summary LSA packet
2795 *
2796 * @param sum_lsa       The Summary LSA
2797 * @returns The value of the metric field
2798 *
2799 * The metric field in the Summary LSA packet is a 24-bit value, which
2800 * is difficult to extract correctly. To avoid byte-ordering issues, use this
2801 * function which will extract the correct value for you.
2802 */
2803DLLEXPORT SIMPLE_FUNCTION
2804uint32_t trace_get_ospf_metric_from_summary_lsa_v2(
2805                libtrace_ospf_summary_lsa_v2_t *sum_lsa);
2806
2807
2808/** Gets the destination MAC address for a given packet
2809 * @param packet        The packet to extract the destination MAC address from
2810 *
2811 * @return A pointer to the destination MAC address field in the layer 2
2812 * header, (or NULL if there is no destination MAC address or layer 2 header
2813 * available)
2814 *
2815 * @note This is a zero-copy function, so the memory that the returned pointer
2816 * points to is part of the packet itself.
2817 */
2818DLLEXPORT SIMPLE_FUNCTION
2819uint8_t *trace_get_destination_mac(libtrace_packet_t *packet);
2820
2821/** Gets the source MAC address for a given packet
2822 * @param packet        The packet to extract the source MAC address from
2823 *
2824 * @return A pointer to the source MAC address field in the layer 2
2825 * header, (or NULL if there is no source MAC address or layer 2 header
2826 * available)
2827 *
2828 * @note This is a zero-copy function, so the memory that the returned pointer
2829 * points to is part of the packet itself.
2830 */
2831DLLEXPORT SIMPLE_FUNCTION
2832uint8_t *trace_get_source_mac(libtrace_packet_t *packet);
2833
2834/** Get the source IP address for a given packet
2835 * @param packet        The packet to extract the source IP address from
2836 * @param addr          A pointer to a sockaddr structure to store the address
2837 *                      in. If NULL, static storage is used instead.
2838 * @return A pointer to a sockaddr holding a v4 or v6 IP address or on some
2839 * platforms a sockaddr holding a MAC address. Returns NULL if no source IP
2840 * address was available.
2841 *
2842 * @note The best way to use this function is to pass in a pointer to the
2843 * struct sockaddr_storage for the addr parameter. This will avoid problems
2844 * with trying to shoe-horn an IPv6 address into a sockaddr that only supports
2845 * IPv4.
2846 */
2847DLLEXPORT SIMPLE_FUNCTION
2848struct sockaddr *trace_get_source_address(const libtrace_packet_t *packet,
2849                struct sockaddr *addr);
2850
2851/** Get the source IP address for a packet and convert it into a string
2852 * @param packet        The packet to extract the source IP address from
2853 * @param space         A pointer to a character buffer to store the address
2854 *                      in. If NULL, static storage is used instead.
2855 * @param spacelen      The size of the buffer passed in via 'space'. Set this
2856 *                      to zero if you are going to pass in a NULL buffer.
2857 * @return A pointer to a character buffer containing the string representation
2858 * of the source IP address. For packets where there is no suitable IP address,
2859 * the source MAC will be returned instead. Returns NULL if no valid address
2860 * is available.
2861 *
2862 * @note Be wary of the possibility of the address being an IPv6 address - make
2863 * sure your buffer is large enough!
2864 *
2865 * New in libtrace 3.0.17.
2866 */
2867DLLEXPORT SIMPLE_FUNCTION
2868char *trace_get_source_address_string(const libtrace_packet_t *packet,
2869                char *space, int spacelen);
2870
2871/** Get the destination IP address for a given packet
2872 * @param packet        The packet to extract the destination IP address from
2873 * @param addr          A pointer to a sockaddr structure to store the address
2874 *                      in. If NULL, static storage is used instead.
2875 * @return A pointer to a sockaddr holding a v4 or v6 IP address or on some
2876 * platforms a sockaddr holding a MAC address. Returns NULL if no destination
2877 * IP address was available.
2878 *
2879 * @note The best way to use this function is to pass in a pointer to the
2880 * struct sockaddr_storage for the addr parameter. This will avoid problems
2881 * with trying to shoe-horn an IPv6 address into a sockaddr that only supports
2882 * IPv4.
2883 */
2884DLLEXPORT SIMPLE_FUNCTION
2885struct sockaddr *trace_get_destination_address(const libtrace_packet_t *packet,
2886                struct sockaddr *addr);
2887
2888/** Get the destination IP address for a packet and convert it into a string
2889 * @param packet        The packet to extract the destination IP address from
2890 * @param space         A pointer to a character buffer to store the address
2891 *                      in. If NULL, static storage is used instead.
2892 * @param spacelen      The size of the buffer passed in via 'space'. Set this
2893 *                      to zero if you are going to pass in a NULL buffer.
2894 * @return A pointer to a character buffer containing the string representation
2895 * of the destination IP address. For packets where there is no suitable IP
2896 * address, the destination MAC will be returned instead. Returns NULL if no
2897 * valid address is available.
2898 *
2899 * @note Be wary of the possibility of the address being an IPv6 address - make
2900 * sure your buffer is large enough!
2901 *
2902 * New in libtrace 3.0.17.
2903 */
2904DLLEXPORT SIMPLE_FUNCTION
2905char *trace_get_destination_address_string(const libtrace_packet_t *packet,
2906                char *space, int spacelen);
2907
2908/** Parses an IP or TCP option
2909 * @param[in,out] ptr   The pointer to the current option
2910 * @param[in,out] len   The total length of all the remaining options
2911 * @param[out] type     The type of the option
2912 * @param[out] optlen   The length of the option
2913 * @param[out] data     The data of the option
2914 *
2915 * @return bool true if there is another option (and the fields are filled in)
2916 *               or false if this was the last option.
2917 *
2918 * This updates ptr to point to the next option after this one, and updates
2919 * len to be the number of bytes remaining in the options area.  Type is updated
2920 * to be the code of this option, and data points to the data of this option,
2921 * with optlen saying how many bytes there are.
2922 *
2923 * @note Beware of fragmented packets.
2924 */
2925DLLEXPORT int trace_get_next_option(unsigned char **ptr,int *len,
2926                        unsigned char *type,
2927                        unsigned char *optlen,
2928                        unsigned char **data);
2929
2930/*@}*/
2931
2932/** @name Time
2933 * These functions deal with the timestamp describing when a packet was
2934 * captured and can convert it into various formats
2935 * @{
2936 */
2937
2938/** Get the packet timestamp in the DAG time format
2939 * @param packet        The packet to extract the timestamp from
2940 *
2941 * @return a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
2942 * past 1970-01-01, the lower 32bits are partial seconds)
2943 */
2944DLLEXPORT SIMPLE_FUNCTION
2945uint64_t trace_get_erf_timestamp(const libtrace_packet_t *packet);
2946
2947/** Get the packet timestamp as a struct timeval
2948 * @param packet        The packet to extract the timestamp from
2949 *
2950 * @return The time that this packet was captured in a struct timeval
2951 */
2952DLLEXPORT SIMPLE_FUNCTION
2953struct timeval trace_get_timeval(const libtrace_packet_t *packet);
2954
2955/** Get the packet timestamp as a struct timespec
2956 * @param packet        The packet to extract the timestamp from
2957 *
2958 * @return The time that this packet was captured in a struct timespec
2959 */
2960DLLEXPORT SIMPLE_FUNCTION
2961struct timespec trace_get_timespec(const libtrace_packet_t *packet);
2962
2963/** Get the packet timestamp in floating point seconds
2964 * @param packet        The packet to extract the timestamp from
2965 *
2966 * @return time that this packet was seen in 64-bit floating point seconds from
2967 * the UNIX epoch (1970-01-01 00:00:00 UTC).
2968 */
2969DLLEXPORT SIMPLE_FUNCTION
2970double trace_get_seconds(const libtrace_packet_t *packet);
2971
2972/** Seek within an input trace to a time specified in floating point seconds
2973 * @param trace         The input trace to seek within
2974 * @param seconds       The time to seek to, in floating point seconds
2975 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
2976 * the error that occurred.
2977 *
2978 * This will make the next packet read to be the first packet to occur at or
2979 * after the specified time.  This must be called in the configuration state
2980 * (i.e. before trace_start() or after trace_pause()).
2981 *
2982 * The time format accepted by this function is 64-bit floating point seconds
2983 * since the UNIX epoch (1970-01-01 00:00:00 UTC), i.e. the same format as
2984 * trace_get_seconds().
2985 *
2986 * @note This function may be extremely slow.
2987 */
2988DLLEXPORT int trace_seek_seconds(libtrace_t *trace, double seconds);
2989
2990/** Seek within an input trace to a time specified as a timeval
2991 * @param trace         The input trace to seek within
2992 * @param tv            The time to seek to, as a timeval
2993 *
2994 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
2995 * the error that occurred.
2996 *
2997 * This will make the next packet read to be the first packet to occur at or
2998 * after the specified time.  This must be called in the configuration state
2999 * (i.e. before trace_start() or after trace_pause()).
3000 *
3001 * @note This function may be extremely slow.
3002 */
3003DLLEXPORT int trace_seek_timeval(libtrace_t *trace, struct timeval tv);
3004
3005/** Seek within an input trace to a time specified as an ERF timestamp
3006 * @param trace         The input trace to seek within
3007 * @param ts            The time to seek to, as an ERF timestamp
3008 *
3009 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
3010 * the error that occurred.
3011 *
3012 * This will make the next packet read to be the first packet to occur at or
3013 * after the specified time.  This must be called in the configuration state
3014 * (i.e. before trace_start() or after trace_pause()).
3015 *
3016 * The time format accepted by this function is the ERF timestamp, which is a
3017 * 64-bit value where the upper 32 bits are seconds since the UNIX epoch and
3018 * the lower 32 bits are partial seconds.
3019 *
3020 * @note This function may be extremely slow.
3021 */
3022DLLEXPORT int trace_seek_erf_timestamp(libtrace_t *trace, uint64_t ts);
3023
3024/*@}*/
3025
3026/** @name Sizes
3027 * This section deals with finding or setting the various different lengths
3028 * that a packet can have, e.g. capture lengths, wire lengths, etc.
3029 * @{
3030 */
3031/** Get the current size of the packet (in bytes), taking into account any
3032 * truncation or snapping that may have previously been performed.
3033 *
3034 * @param packet        The packet to determine the capture length for
3035 * @return The size of the packet read from the input trace, i.e. what is
3036 * actually available to libtrace at the moment.
3037 *
3038 * @note Most traces are header captures, so this value may not be the same
3039 * as the size of the packet when it was captured. Use trace_get_wire_length()
3040 * to get the original size of the packet.
3041 
3042 * @note This can (and often is) different for different packets in a trace!
3043 
3044 * @note This is sometimes called the "snaplen".
3045 *
3046 * @note The return size refers to the network-level payload of the packet and
3047 * does not include any capture framing headers. For example, an Ethernet
3048 * packet with an empty TCP packet will return sizeof(ethernet_header) +
3049 * sizeof(ip_header) + sizeof(tcp_header), but not the capture format
3050 * (pcap/erf/etc) header.
3051 */
3052DLLEXPORT SIMPLE_FUNCTION
3053size_t trace_get_capture_length(const libtrace_packet_t *packet);
3054
3055/** Get the size of the packet as it was originally seen on the wire (in bytes).
3056 * @param packet        The packet to determine the wire length for
3057 * @return The size of the packet as it was on the wire.
3058 *
3059 * @note This value may not be the same as the capture length, due to
3060 * truncation.
3061 *
3062 * @note trace_get_wire_length \em includes  the Frame Check Sequence. This is
3063 * different behaviour compared to most PCAP-based tools.
3064 *
3065 * @note The return size refers to the network-level payload of the packet and
3066 * does not include any capture framing headers. For example, an Ethernet
3067 * packet with an empty TCP packet will return sizeof(ethernet_header) +
3068 * sizeof(ip_header) + sizeof(tcp_header), but not the capture format
3069 * (pcap/erf/etc) header.
3070 */
3071DLLEXPORT SIMPLE_FUNCTION
3072size_t trace_get_wire_length(const libtrace_packet_t *packet);
3073
3074/** Get the length of the capture framing headers (in bytes).
3075 * @param packet        The packet to determine the framing length for
3076 * @return The size of the capture format header encapsulating the packet.
3077 *
3078 * @note This length corresponds to the difference between the amount of
3079 * memory required to store a captured packet and the capture length reported
3080 * by trace_capture_length()
3081 */
3082DLLEXPORT SIMPLE_FUNCTION
3083size_t trace_get_framing_length(const libtrace_packet_t *packet);
3084
3085/** Get the length of the original payload content of the packet (in bytes).
3086 * @param packet        The packet to determine the payload length for
3087 * @return The size of the packet payload (without headers). Returns 0 if
3088 * unable to calculate payload length correctly.
3089 *
3090 * This function reports the amount of data that followed the transport header
3091 * when the packet was originally captured, i.e. prior to any snapping. Best
3092 * described as the wire length minus the packet headers.
3093 *
3094 * Currently only supports some protocols and will return 0 if an unsupported
3095 * protocol header is encountered, or if one of the headers is truncated.
3096 *
3097 * @note Supports IPv4, IPv6, TCP, UDP and ICMP.
3098 */
3099DLLEXPORT SIMPLE_FUNCTION
3100size_t trace_get_payload_length(const libtrace_packet_t *packet);
3101
3102/** Truncate ("snap") the packet to the suggested length
3103 * @param packet        The packet to truncate
3104 * @param size          The new length of the packet (in bytes)
3105 *
3106 * @return The new capture length of the packet or the original capture
3107 * length of the packet if unchanged.
3108 *
3109 * This function will modify the capture length of the given packet. The wire
3110 * length will not be changed, so you can always determine what the original
3111 * packet size was, prior to the truncation.
3112 *
3113 * @note You can only use this function to decrease the capture length. Any
3114 * attempt to increase capture length will have no effect.
3115 */
3116DLLEXPORT size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
3117
3118/*@}*/
3119
3120
3121/** Gets the link layer type for a packet
3122 * @param packet        The packet to extract the link layer type for
3123 * @return A libtrace_linktype_t describing the link layer protocol being used
3124 * by this packet.
3125 */
3126DLLEXPORT SIMPLE_FUNCTION
3127libtrace_linktype_t trace_get_link_type(const libtrace_packet_t *packet);
3128
3129/** Set the direction flag for a packet, if the capture format supports
3130 * direction tagging.
3131 *
3132 * @param packet        The packet to set the direction for
3133 * @param direction     The new direction
3134 * @returns -1 on error, or the direction that was set.
3135 *
3136 * @note Few capture formats actually support direction tagging. Most notably,
3137 * we cannot set the direction on PCAP packets.
3138 */
3139DLLEXPORT libtrace_direction_t trace_set_direction(libtrace_packet_t *packet, libtrace_direction_t direction);
3140
3141/** Get the direction flag for a packet, if it has one.
3142 * @param packet  The packet to get the direction for
3143 *
3144 * @return A value representing the direction flag, or -1 if this is not
3145 * supported by the capture format.
3146 *
3147 * The direction is defined as 0 for packets originating locally (ie, outbound)
3148 * and 1 for packets originating remotely (ie, inbound). Other values are
3149 * possible, which might be overloaded to mean special things for certain
3150 * traces, e.g. in the Waikato traces, 2 is used to represent an "Unknown"
3151 * direction.
3152 *
3153 * For DAG/ERF traces, the direction is extracted from the "Interface" bits in
3154 * the ERF header, which can range from 0 - 3.
3155 */
3156DLLEXPORT SIMPLE_FUNCTION
3157libtrace_direction_t trace_get_direction(const libtrace_packet_t *packet);
3158
3159/** @name BPF
3160 * This section deals with using Berkley Packet Filters to filter input traces
3161 * @{
3162 */
3163/** Creates a BPF filter
3164 * @param filterstring The filter string describing the BPF filter to create
3165 * @return An opaque pointer to a libtrace_filter_t object
3166 *
3167 * @note The filter is not actually compiled at this point, so no correctness
3168 * tests are performed here. trace_create_filter() will always return ok, but
3169 * if the filter is poorly constructed an error will be generated when the
3170 * filter is actually used.
3171 */
3172DLLEXPORT SIMPLE_FUNCTION
3173libtrace_filter_t *trace_create_filter(const char *filterstring);
3174
3175/** Create a BPF filter based on pre-compiled byte-code.
3176 * @param bf_insns      A pointer to the start of the byte-code
3177 * @param bf_len        The number of BPF instructions 
3178 * @return              An opaque pointer to a libtrace_filter_t object
3179 * @note                The supplied byte-code is not checked for correctness.
3180 *                      Instead, incorrect byte-code will generate an error
3181 *                      once the filter is actually used.
3182 * @author              Scott Raynel
3183 */
3184DLLEXPORT libtrace_filter_t *
3185trace_create_filter_from_bytecode(void *bf_insns, unsigned int bf_len);
3186
3187/** Apply a BPF filter to a packet
3188 * @param filter        The filter to be applied       
3189 * @param packet        The packet to be matched against the filter
3190 * @return >0 if the filter matches, 0 if it doesn't, -1 on error.
3191 *
3192 * @note Due to the way BPF filters are built, the filter is not actually
3193 * compiled until the first time trace_create_filter is called. If your filter
3194 * is incorrect, it will generate an error message and assert, exiting the
3195 * program. This behaviour may change to a more graceful handling of this error
3196 * in the future.
3197 */
3198DLLEXPORT int trace_apply_filter(libtrace_filter_t *filter,
3199                const libtrace_packet_t *packet);
3200
3201/** Destroy a BPF filter
3202 * @param filter        The filter to be destroyed
3203 *
3204 * Deallocates all the resources associated with a BPF filter.
3205 */
3206DLLEXPORT void trace_destroy_filter(libtrace_filter_t *filter);
3207/*@}*/
3208
3209/** @name Portability
3210 * This section contains functions that deal with portability issues, e.g. byte
3211 * ordering.
3212 * @{
3213 */
3214
3215/** Converts an ethernet address to a printable string
3216 * @param addr  Ethernet address in network byte order
3217 * @param buf   Buffer to store the ascii representation, or NULL to indicate
3218 * that static storage should be used.
3219 * @return buf, or if buf is NULL then a statically allocated buffer.
3220 *
3221 * This function is similar to the GNU ether_ntoa_r function, with a few
3222 * minor differences.  If NULL is passed as buf, then the function will
3223 * use an internal static buffer. If NULL isn't passed then the function
3224 * will use that buffer instead.
3225 *
3226 * The address pointers returned by trace_get_source_mac() and
3227 * trace_get_destination_mac() can be passed directly into this function.
3228 *
3229 * @note The type of addr isn't struct ether_addr as it is with ether_ntoa_r,
3230 * however it is bit compatible so that a cast will work.
3231 */
3232DLLEXPORT char *trace_ether_ntoa(const uint8_t *addr, char *buf);
3233
3234/** Convert a string to an ethernet address
3235 * @param buf   A string containing an Ethernet address in hex format
3236 * delimited with :'s.
3237 * @param addr  Buffer to store the binary representation, or NULL to indicate
3238 * that static storage should be used.
3239 * @return addr, or if addr is NULL then a statically allocated buffer.
3240 *
3241 * This function is similar to the GNU ether_aton_r function, with a few
3242 * minor differences.  If NULL is passed as addr, then the function will
3243 * use an internal static buffer. If NULL isn't passed then the function will
3244 * use that buffer instead.
3245 *
3246 * The address returned by this function will be in network byte order.
3247 *
3248 * @note the type of addr isn't struct ether_addr as it is with ether_aton_r,
3249 * however it is bit compatible so that a cast will work.
3250 */
3251DLLEXPORT uint8_t *trace_ether_aton(const char *buf, uint8_t *addr);
3252
3253/*@}*/
3254
3255/** @name Ports
3256 * This section contains functions for dealing with port numbers at the
3257 * transport layer.
3258 *
3259 * @{
3260 */
3261
3262/** An indication of which port is the "server" port for a given port pair */
3263typedef enum {
3264        USE_DEST,       /**< Destination port is the server port */
3265        USE_SOURCE      /**< Source port is the server port */
3266} serverport_t;
3267
3268/** Gets the source port for a given packet
3269 * @param packet        The packet to get the source port from
3270 * @return The source port in HOST byte order or 0 if no suitable port number
3271 * can be extracted from the packet.
3272 *
3273 * This function will return 0 if the transport protocol is known not to
3274 * use port numbers, e.g. ICMP. 0 is also returned if no transport header is
3275 * present in the packet or the transport header has been truncated such that
3276 * the port fields are not readable.
3277 *
3278 * @note If the transport protocol is not known by libtrace, the first two
3279 * bytes of the transport header will be treated as the source port field.
3280 */
3281DLLEXPORT SIMPLE_FUNCTION
3282uint16_t trace_get_source_port(const libtrace_packet_t *packet);
3283
3284/** Gets the destination port for a given packet
3285 * @param packet        The packet to get the destination port from
3286 * @return The destination port in HOST byte order or 0 if no suitable port
3287 * number can be extracted from the packet.
3288 *
3289 * This function will return 0 if the transport protocol is known not to
3290 * use port numbers, e.g. ICMP. 0 is also returned if no transport header is
3291 * present in the packet or the transport header has been truncated such that
3292 * the port fields are not readable.
3293 *
3294 * @note If the transport protocol is not known by libtrace, the third and
3295 * fourth bytes of the transport header will be treated as the destination
3296 * port field.
3297 *
3298 */
3299DLLEXPORT SIMPLE_FUNCTION
3300uint16_t trace_get_destination_port(const libtrace_packet_t *packet);
3301
3302/** Hint at which of the two provided ports is the server port.
3303 *
3304 * @param protocol      The IP layer protocol, eg 6 (tcp), 17 (udp)
3305 * @param source        The source port from the packet
3306 * @param dest          The destination port from the packet
3307 *
3308 * @return one of USE_SOURCE or USE_DEST describing on which of the two ports
3309 * is most likely to be the server port.
3310 *
3311 * @note Ports must be provided in HOST byte order!
3312 *
3313 * This function is based almost entirely on heuristics and should not be
3314 * treated as a definitive means of identifying the server port. However, it
3315 * is deterministic, so it is very handy for identifying both halves of the
3316 * same flow.
3317 */
3318DLLEXPORT SIMPLE_FUNCTION
3319int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
3320
3321/*@}*/
3322
3323/** @name Wireless trace support
3324 * Functions to access wireless information from packets that have wireless
3325 * monitoring headers such as Radiotap or Prism.
3326 *
3327 * The trace_get_wireless_* functions provide an abstract interface for
3328 * retrieving information from wireless traces. They take a pointer to the
3329 * wireless monitoring header (usually found with trace_get_packet_meta()) and
3330 * the linktype of the header passed in.
3331 *
3332 * All of the trace_get_wireless_* functions return false if the requested
3333 * information was unavailable, or true if it was. The actual data is stored
3334 * in an output variable supplied by the caller. Values returned into the
3335 * output variable will always be returned in host byte order.
3336 * @{
3337 */
3338
3339
3340#ifndef ARPHRD_80211_RADIOTAP
3341/** libc doesn't define this yet, so we have to do so ourselves */
3342#define ARPHRD_80211_RADIOTAP 803
3343#endif
3344
3345/** Get the wireless Timer Synchronisation Function
3346 *
3347 * Gets the value of the timer synchronisation function for this frame, which
3348 * is a value in microseconds indicating the time that the first bit of the
3349 * MPDU was received by the MAC.
3350 *
3351 * @param linkptr The wireless meta header
3352 * @param linktype The linktype of the wireless meta header passed in
3353 * @param[out] tsft The value of the timer synchronisation function.
3354 * @return true if the field was available, false if not.
3355 */
3356DLLEXPORT bool trace_get_wireless_tsft(void *linkptr,
3357        libtrace_linktype_t linktype, uint64_t *tsft);
3358
3359/** Get the wireless data rate
3360 *
3361 * @param linkptr The wireless meta header
3362 * @param linktype The linktype of the wireless meta header passed in
3363 * @param[out] rate The data-rate of the frame in units of 500kbps
3364 * @return true if the field was available, false if not.
3365 */
3366DLLEXPORT bool trace_get_wireless_rate(void *linkptr,
3367        libtrace_linktype_t linktype, uint8_t *rate);
3368
3369/** Get the wireless channel frequency
3370 * @param linkptr The wireless meta header
3371 * @param linktype The linktype of the wireless meta header passed in
3372 * @param[out] freq The frequency in MHz of the channel the frame was
3373 * transmitted or received on.
3374 * @return true if the field was available, false if not.
3375 */
3376DLLEXPORT bool trace_get_wireless_freq(void *linkptr,
3377        libtrace_linktype_t linktype, uint16_t *freq);
3378
3379/** Get the wireless signal strength in dBm
3380 * @param linkptr The wireless meta header
3381 * @param linktype The linktype of the wireless meta header passed in
3382 * @param[out] strength The RF signal power at the antenna, in dB difference
3383 * from 1mW.
3384 * @return true if the field was available, false if not.
3385 */
3386DLLEXPORT bool trace_get_wireless_signal_strength_dbm(void *linkptr,
3387        libtrace_linktype_t linktype, int8_t *strength);
3388
3389/** Get the wireless noise strength in dBm
3390 * @param linkptr The wireless meta header
3391 * @param linktype The linktype of the wireless meta header passed in
3392 * @param[out] strength The RF noise power at the antenna, in dB difference
3393 * from 1mW.
3394 * @return true if the field was available, false if not.
3395 */
3396DLLEXPORT bool trace_get_wireless_noise_strength_dbm(void *linkptr,
3397        libtrace_linktype_t linktype, int8_t *strength);
3398
3399/** Get the wireless signal strength in dB
3400 * @param linkptr The wireless meta header
3401 * @param linktype The linktype of the wireless meta header passed in
3402 * @param[out] strength The RF signal power at the antenna, in dB difference
3403 * from a fixed reference.
3404 * @return true if the field was available, false if not.
3405 */
3406DLLEXPORT bool trace_get_wireless_signal_strength_db(void *linkptr,
3407        libtrace_linktype_t linktype, uint8_t *strength);
3408
3409/** Get the wireless noise strength in dB
3410 * @param linkptr The wireless meta header
3411 * @param linktype The linktype of the wireless meta header passed in
3412 * @param[out] strength The RF noise power at the antenna, in dB difference
3413 * from a fixed reference.
3414 * @return true if the field was available, false if not.
3415 */
3416DLLEXPORT bool trace_get_wireless_noise_strength_db(void *linkptr,
3417        libtrace_linktype_t linktype, uint8_t *strength);
3418
3419/** Get the wireless transmit attenuation
3420 * @param linkptr The wireless meta header
3421 * @param linktype The linktype of the wireless meta header passed in
3422 * @param[out] attenuation The transmit power as a unitless distance from
3423 * maximum power set at factory calibration. 0 indicates maximum transmission
3424 * power.
3425 * @return true if the field was available, false if not.
3426 */
3427DLLEXPORT bool trace_get_wireless_tx_attenuation(void *linkptr,
3428        libtrace_linktype_t linktype, uint16_t *attenuation);
3429
3430/** Get the wireless transmit attenuation in dB
3431 * @param linkptr The wireless meta header
3432 * @param linktype The linktype of the wireless meta header passed in
3433 * @param[out] attenuation The transmit power as dB difference from maximum
3434 * power set at factory calibration. 0 indicates maximum power.
3435 * @return true if the field was available, false if not.
3436 */
3437DLLEXPORT bool trace_get_wireless_tx_attenuation_db(void *linkptr,
3438        libtrace_linktype_t linktype, uint16_t *attenuation);
3439
3440/** Get the wireless transmit power in dBm
3441 * @param linkptr The wireless meta header
3442 * @param linktype The linktype of the wireless meta header passed in
3443 * @param[out] txpower The transmit power as dB from a 1mW reference. This is
3444 * the absolute power level measured at the antenna port. 
3445 * @return true if the field was available, false if not.
3446 */
3447DLLEXPORT bool trace_get_wireless_tx_power_dbm(void *linkptr,
3448                libtrace_linktype_t linktype, int8_t *txpower);
3449
3450/** Get the wireless antenna
3451 * @param linkptr The wireless meta header
3452 * @param linktype The linktype of the wireless meta header passed in
3453 * @param[out] antenna The antenna that was used to transmit or receive the
3454 * frame.
3455 * @return true if the field was available, false if not.
3456 */
3457DLLEXPORT bool trace_get_wireless_antenna(void *linkptr,
3458        libtrace_linktype_t linktype, uint8_t *antenna);
3459
3460/*@}*/
3461
3462/**
3463 * A collection of types for convenience used in place of a
3464 * simple void* to allow a any type of data to be stored.
3465 *
3466 * This is expected to be 8 bytes in length.
3467 */
3468typedef union {
3469        /* Pointers */
3470        void *ptr;
3471        libtrace_packet_t *pkt;
3472
3473        /* C99 Integer types */
3474        /* NOTE: Standard doesn't require 64-bit
3475         * but x32 and x64 gcc does */
3476        int64_t sint64;
3477        uint64_t uint64;
3478
3479        uint32_t uint32s[2];
3480        int32_t sint32s[2];
3481        uint32_t uint32;
3482        int32_t sint32;
3483
3484        uint16_t uint16s[4];
3485        int16_t sint16s[4];
3486        uint16_t uint16;
3487        int16_t sint16;
3488
3489        uint8_t uint8s[8];
3490        int8_t sint8s[8];
3491        uint8_t uint8;
3492        int8_t sint8;
3493
3494        size_t size;
3495
3496        /* C basic types - we cannot be certian of the size */
3497        int sint;
3498        unsigned int uint;
3499
3500        signed char schars[8];
3501        unsigned char uchars[8];
3502        signed char schar;
3503        unsigned char uchar;
3504
3505        /* Real numbers */
3506        float rfloat;
3507        double rdouble;
3508} libtrace_generic_types_t;
3509
3510typedef struct libtrace_message_t {
3511        int code;
3512        libtrace_generic_types_t additional;
3513        libtrace_thread_t *sender;
3514} libtrace_message_t;
3515
3516/** Structure holding information about a result */
3517typedef struct libtrace_result_t {
3518        uint64_t key;
3519        libtrace_generic_types_t value;
3520        int type;
3521} libtrace_result_t;
3522#define RESULT_NORMAL 0
3523#define RESULT_PACKET 1
3524#define RESULT_TICK   2
3525
3526
3527typedef void* (*fn_per_pkt)(libtrace_t* trace, libtrace_packet_t *p, libtrace_message_t *m, libtrace_thread_t *thread);
3528typedef void (*fn_reporter)(libtrace_t* trace, libtrace_result_t *r, libtrace_message_t *m);
3529typedef uint64_t (*fn_hasher)(const libtrace_packet_t* packet, void *data);
3530
3531DLLEXPORT int trace_pstart(libtrace_t *libtrace, void* global_blob, fn_per_pkt per_pkt, fn_reporter reporter);
3532DLLEXPORT int trace_ppause(libtrace_t *libtrace);
3533DLLEXPORT int trace_pstop(libtrace_t *libtrace);
3534DLLEXPORT void trace_join(libtrace_t * trace);
3535DLLEXPORT void print_contention_stats (libtrace_t *libtrace);
3536
3537DLLEXPORT void libtrace_result_set_key(libtrace_result_t * result, uint64_t key);
3538DLLEXPORT uint64_t libtrace_result_get_key(libtrace_result_t * result);
3539DLLEXPORT void libtrace_result_set_value(libtrace_result_t * result, libtrace_generic_types_t value);
3540DLLEXPORT libtrace_generic_types_t libtrace_result_get_value(libtrace_result_t * result);
3541DLLEXPORT void libtrace_result_set_key_value(libtrace_result_t * result, uint64_t key, libtrace_generic_types_t value);
3542DLLEXPORT void trace_destroy_result(libtrace_result_t ** result);
3543
3544// Ways to access Global and TLS storage that we provide the user
3545DLLEXPORT void * trace_get_global(libtrace_t *trace);
3546DLLEXPORT void * trace_set_global(libtrace_t *trace, void * data);
3547DLLEXPORT void * trace_set_tls(libtrace_thread_t *t, void * data);
3548DLLEXPORT void * trace_get_tls(libtrace_thread_t *t);
3549
3550
3551DLLEXPORT void trace_publish_result(libtrace_t *libtrace, libtrace_thread_t *t, uint64_t key, libtrace_generic_types_t value, int type);
3552typedef struct libtrace_vector libtrace_vector_t;
3553
3554DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);
3555DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace);
3556DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace, libtrace_message_t * message);
3557DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace, libtrace_message_t * message);
3558DLLEXPORT int trace_send_message_to_reporter(libtrace_t * libtrace, libtrace_message_t * message);
3559DLLEXPORT int trace_send_message_to_perpkts(libtrace_t * libtrace, libtrace_message_t * message);
3560DLLEXPORT int trace_send_message_to_thread(libtrace_t * libtrace, libtrace_thread_t *t, libtrace_message_t * message);
3561DLLEXPORT int trace_finished(libtrace_t * libtrace);
3562DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
3563DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
3564DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
3565DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
3566DLLEXPORT uint64_t tv_to_usec(struct timeval *tv);
3567
3568DLLEXPORT int retrive_first_packet(libtrace_t *libtrace, libtrace_packet_t **packet, struct timeval **tv);
3569
3570DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);
3571DLLEXPORT void libtrace_make_result_safe(libtrace_result_t *res);
3572
3573typedef enum {
3574        /**
3575         * Sets the hasher function, if NULL(default) no hashing is used a
3576         * cores will get packets on a first in first served basis
3577         */
3578        TRACE_OPTION_SET_HASHER,
3579       
3580        /**
3581         * Libtrace set perpkt thread count
3582         */
3583        TRACE_OPTION_SET_PERPKT_THREAD_COUNT,
3584       
3585        /**
3586         * Delays packets so they are played back in trace-time rather than as fast
3587         * as possible.
3588         */
3589        TRACE_OPTION_TRACETIME,
3590
3591        /**
3592         * Specifies the interval between tick packets in milliseconds, if 0
3593         * or less this is ignored.
3594         */
3595        TRACE_OPTION_TICK_INTERVAL,
3596        TRACE_OPTION_GET_CONFIG,
3597        TRACE_OPTION_SET_CONFIG
3598} trace_parallel_option_t;
3599
3600enum libtrace_messages {
3601        MESSAGE_STARTING,
3602        MESSAGE_RESUMING,
3603        MESSAGE_STOPPING,
3604        MESSAGE_PAUSING,
3605        MESSAGE_DO_PAUSE,
3606        MESSAGE_DO_STOP,
3607        MESSAGE_FIRST_PACKET,
3608        MESSAGE_PERPKT_ENDED,
3609        MESSAGE_PERPKT_RESUMED,
3610        MESSAGE_PERPKT_PAUSED,
3611        MESSAGE_PERPKT_EOF,
3612        MESSAGE_POST_REPORTER,
3613        MESSAGE_POST_RANGE,
3614        MESSAGE_TICK,
3615        MESSAGE_USER
3616};
3617
3618enum hasher_types {
3619        /**
3620         * Balance load across CPUs best as possible, this is basically to say do
3621         * not care about hash. This might still might be implemented
3622         * using a hash or round robin etc. under the hood depending on the format
3623         */
3624        HASHER_BALANCE,
3625
3626        /** Use a hash which is bi-directional for TCP flows, that is packets with
3627         * the same hash are sent to the same thread. All non TCP packets will be
3628         * sent to the same thread. UDP may or may not be sent to separate
3629         * threads like TCP, this depends on the format support.
3630         */
3631        HASHER_BIDIRECTIONAL,
3632       
3633        /**
3634         * Use a hash which is uni-directional across TCP flows, that means the
3635         * opposite directions of the same 5 tuple might end up on separate cores.
3636         * Otherwise is identical to HASHER_BIDIRECTIONAL
3637         */
3638        HASHER_UNIDIRECTIONAL,
3639
3640        /**
3641         * Always use the user supplied hasher, this currently disables native
3642         * support and is likely significantly slower.
3643         */
3644        HASHER_CUSTOM,
3645
3646        /**
3647         * This is not a valid option, used internally only!!! TODO remove
3648         * Set by the format if the hashing is going to be done in hardware
3649         */
3650        HASHER_HARDWARE
3651};
3652
3653typedef struct libtrace_info_t {
3654        /**
3655         * True if a live format (i.e. packets have to be tracetime).
3656         * Otherwise false, indicating packets can be read as fast
3657         * as possible from the format.
3658         */
3659        bool live;
3660
3661        /**
3662         * The maximum number of threads supported by a parallel trace. 1
3663         * if parallel support is not native (in this case libtrace will simulate
3664         * an unlimited number of threads), -1 means unlimited and 0 unknown.
3665         */
3666        int max_threads;
3667
3668        /* TODO hash fn supported list */
3669
3670        /* TODO consider time/clock details?? */
3671} libtrace_info_t;
3672
3673DLLEXPORT int trace_parallel_config(libtrace_t *libtrace, trace_parallel_option_t option, void *value);
3674DLLEXPORT libtrace_packet_t* trace_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
3675DLLEXPORT void trace_free_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
3676DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type, fn_hasher hasher, void *data);
3677DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);
3678
3679/**
3680 * Tuning the parallel sizes
3681 */
3682struct user_configuration {
3683        // Packet memory cache settings (ocache_init) total
3684        /**
3685         * See diagrams, this sets the maximum size of freelist used to
3686         * maintain packets and their memory buffers.
3687         * NOTE setting this to less than recommend could cause deadlock a
3688         * trace that manages its own packets.
3689         * A unblockable error message will be printed.
3690         */
3691        size_t packet_cache_size;
3692        /**
3693         * Per thread local cache size for the packet freelist
3694         */
3695        size_t packet_thread_cache_size;
3696        /**
3697         * If true the total number of packets that can be created by a trace is limited
3698         * to the packet_cache_size, otherwise once packet_cache_size is exceeded alloc
3699         * and free will be used to create and free packets, this will be slower than
3700         * using the freelist and could run a machine out of memory.
3701         *
3702         * However this does make it easier to ensure that deadlocks will not occur
3703         * due to running out of packets
3704         */
3705        bool fixed_packet_count;
3706        /**
3707         * When reading from a single threaded input source to reduce
3708         * lock contention a 'burst' of packets is read per pkt thread
3709         * this determines the bursts size.
3710         */
3711        size_t burst_size;
3712        // Each perpkt thread has a queue leading into the reporter
3713        //size_t reporter_queue_size;
3714
3715        /**
3716         * The tick interval - in milliseconds
3717         * When a live trace is used messages are sent at the tick
3718         * interval to ensure that all perpkt threads receive data
3719         * this allows results to be printed in cases flows are
3720         * not being directed to a certian thread, while still
3721         * maintaining order.
3722         */
3723        size_t tick_interval;
3724
3725        /**
3726         * Like the tick interval but used in the case of file format
3727         * This specifies the number of packets before inserting a tick to
3728         * every thread.
3729         */
3730        size_t tick_count;
3731
3732        /**
3733         * The number of per packet threads requested, 0 means use default.
3734         * Default typically be the number of processor threads detected less one or two.
3735         */
3736        size_t perpkt_threads;
3737
3738        /**
3739         * See diagrams, this sets the maximum size of buffers used between
3740         * the single hasher thread and the buffer.
3741         * NOTE setting this to less than recommend could cause deadlock a
3742         * trace that manages its own packets.
3743         * A unblockable warning message will be printed to stderr in this case.
3744         */
3745        /** The number of packets that can queue per thread from hasher thread */
3746        size_t hasher_queue_size;
3747
3748        /**
3749         * If true use a polling hasher queue, that means that we will spin/or yeild
3750         * when rather than blocking on a lock. This applies to both the hasher thread
3751         * and perpkts reading the queues.
3752         */
3753        bool hasher_polling;
3754
3755        /**
3756         * If true the reporter thread will continuously poll waiting for results
3757         * if false they are only checked when a message is received, this message
3758         * is controlled by reporter_thold.
3759         */
3760        bool reporter_polling;
3761
3762        /**
3763         * Perpkt thread result queue size before triggering the reporter step to read results
3764         */
3765        size_t reporter_thold;
3766
3767        /**
3768         * Prints a line to standard error for every state change
3769         * for both the trace as a whole and for each thread.
3770         */
3771        bool debug_state;
3772};
3773#include <stdio.h>
3774DLLEXPORT void parse_user_config(struct user_configuration* uc, char * str);
3775DLLEXPORT void parse_user_config_file(struct user_configuration* uc, FILE *file);
3776DLLEXPORT int libtrace_get_perpkt_count(libtrace_t* t);
3777
3778/**
3779 * The methods we use to combine multiple outputs into a single output
3780 * This is not considered a stable API however is public.
3781 * Where possible use built in combiners
3782 *
3783 * NOTE this structure is duplicated per trace and as such can
3784 * have functions rewritten, and in fact should if possible.
3785 */
3786typedef struct libtrace_combine libtrace_combine_t;
3787struct libtrace_combine {
3788
3789        /**
3790         * Called at the start of the trace to allow datastructures
3791         * to be initilised and allow functions to be swapped if approriate.
3792         *
3793         * Also factors such as whether the trace is live or not can
3794         * be used to determine the functions used.
3795         * @return 0 if successful, -1 if an error occurs
3796         */
3797        int (*initialise)(libtrace_t *,libtrace_combine_t *);
3798
3799        /**
3800         * Called when the trace ends, clean up any memory here
3801         * from libtrace_t * init.
3802         */
3803        void (*destroy)(libtrace_t *, libtrace_combine_t *);
3804
3805        /**
3806         * Publish a result against it's a threads queue.
3807         * If null publish directly, expected to be used
3808         * as a single threaded optimisation and can be
3809         * set to NULL by init if this case is detected.
3810         */
3811        void (*publish)(libtrace_t *, int thread_id, libtrace_combine_t *, libtrace_result_t *);
3812
3813        /**
3814         * Read as many results as possible from the trace.
3815         * Directy calls the users code to handle results from here.
3816         *
3817         * THIS SHOULD BE NON-BLOCKING AND READ AS MANY AS POSSIBLE
3818         * If publish is NULL, this probably should be NULL also otherwise
3819         * it will not be called.
3820         */
3821        void (*read)(libtrace_t *, libtrace_combine_t *);
3822
3823        /**
3824         * Called when the trace is finished to flush the final
3825         * results to the reporter thread.
3826         *
3827         * There may be no results, in which case this should
3828         * just return.
3829         *
3830         * Libtrace state:
3831         * Called from reporter thread
3832         * No perpkt threads will be running, i.e. publish will not be
3833         * called again.
3834         *
3835         * If publish is NULL, this probably should be NULL also otherwise
3836         * it will not be called.
3837         */
3838        void (*read_final)(libtrace_t *, libtrace_combine_t *);
3839
3840        /**
3841         * Pause must make sure any results of the type packet are safe.
3842         * That means trace_copy_packet() and destroy the original.
3843         * This also should be NULL if publish is NULL.
3844         */
3845        void (*pause)(libtrace_t *, libtrace_combine_t *);
3846
3847        /**
3848         * Data storage for all the combiner threads
3849         */
3850        void *queues;
3851
3852        /**
3853         * Configuration options, what this does is upto the combiner
3854         * chosen.
3855         */
3856        libtrace_generic_types_t configuration;
3857};
3858
3859DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_types_t config);
3860
3861#define READ_EOF 0
3862#define READ_ERROR -1
3863#define READ_MESSAGE -2
3864// Used for inband tick message
3865#define READ_TICK -3
3866
3867#define ZERO_USER_CONFIG(config) memset(&config, 0, sizeof(struct user_configuration));
3868
3869#ifdef __cplusplus
3870} /* extern "C" */
3871#endif /* #ifdef __cplusplus */
3872#endif /* LIBTRACE_H_ */
Note: See TracBrowser for help on using the repository browser.