source: lib/libtrace.h.in @ 509ee47

develop
Last change on this file since 509ee47 was 509ee47, checked in by Shane Alcock <salcock@…>, 3 years ago

Add option to allow users to specify a constant ERF framing length.

This can be useful for situations where

a) the input uses ERF (or some derivative thereof)
b) the link type and ERF record type are constant for the

duration of the capture

c) performance is critical

This option allows users to simply tell libtrace what the ERF
framing length on every packet is going to be, so libtrace
doesn't have to repeatedly derive the framing length for each
packet it processes. At high packet rates, the time taken to
do this calculation can really add up and it makes no sense
to risk dropping packets because you're busy calculating a value
that is always a single constant value.

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