source: lib/libtrace.h.in @ b148e3b

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivendag_formatrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since b148e3b was b148e3b, checked in by Richard Sanger <rsanger@…>, 4 years ago

Updates DPDK to latest release and improves performance

Thanks to Richard Cziva for supplying an intial patch for this.

We now recommend using the latest release of DPDK, ideally 16.04 or newer

To support newer releases

  • Fixes RSS hashing renames
  • Fixes deprecated rte_mempool_count
  • Fixes ETH_LINK_SPEED_X rename
  • Fixes TX minimum memory requirement
  • Fixes dropped vs errored counting in recent versions (for best results use 16.04 or newer)

Tuned to allow DPDK's SSE vector in supporting drivers mode for better performance.
Bumps default internal batch size up to 32 to matches DPDK in SSE vector mode.

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