source: lib/libtrace.h.in @ 32ee9b2

cachetimestampsdeveloprc-4.0.4ringdecrementfixringperformance
Last change on this file since 32ee9b2 was 32ee9b2, checked in by Shane Alcock <salcock@…>, 3 years ago

Add new trace_flush_output() to public API

Can be used to force a libtrace output to dump any buffered output
to disk immediately.

Note that if the file is compressed or the output trace format
requires a trailer, the flushed file will still not be properly
readable afterwards as this will not result in any trailers
being written. You'll still have to close the file for that.

Mainly this is useful for ensuring that output file sizes grow
over time in situations where the amount of output is relatively
small, rather than staying stuck at 0 bytes until we either reach
1MB of output or the file is closed. For instance, you could have
a timer that calls trace_flush_output() every 30 seconds so that
the output file size will grow if any packets were written in the
last 30 seconds.

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