source: lib/libtrace.h.in @ cd7eec7

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since cd7eec7 was cd7eec7, checked in by Shane Alcock <salcock@…>, 15 years ago

Added a new format for reading and writing DUCK packets
Added corresponding test cases for DUCK
Removed references to RT_DUCK_* from format_rt
Added a configuration option for meta-data frequency (used solely for DUCK frequency at the moment) and updated other formats to ignore the option

  • Property mode set to 100644
File size: 42.2 KB
RevLine 
[a79ddbe]1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2004 The University of Waikato, Hamilton, New Zealand.
5 * Authors: Daniel Lawson
6 *          Perry Lorier
7 *         
8 * All rights reserved.
9 *
10 * This code has been developed by the University of Waikato WAND
11 * research group. For further information please see http://www.wand.net.nz/
12 *
13 * libtrace is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * libtrace is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with libtrace; if not, write to the Free Software
25 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 *
[e5f1431]27 * $Id: libtrace.h 773 2006-05-01 12:58:09Z perry $
[a79ddbe]28 *
29 */
30
[2137b49]31#ifndef LIBTRACE_H
32#define LIBTRACE_H
[27615e9]33
[2c060e3]34/** @file
35 *
36 * @brief Trace file processing library header
37 *
38 * @author Daniel Lawson
39 * @author Perry Lorier
40 *
[e5f1431]41 * @version $Id: libtrace.h 773 2006-05-01 12:58:09Z perry $
[2c060e3]42 *
43 * This library provides a per packet interface into a trace file, or a live
44 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
45 * pcap etc.
46 *
47 * @par Usage
[fba4ca0]48 * See the example/ directory in the source distribution for some simple examples
[2c060e3]49 * @par Linking
[90e4aa4]50 * To use this library you need to link against libtrace by passing -ltrace
51 * to your linker. You may also need to link against a version of libpcap
52 * and of zlib which are compiled for largefile support (if you wish to access
53 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
[d95447b]54 * Woody, at least, does not support large file offsets.
[2c060e3]55 *
56 */
57
[803ea87]58#include <sys/types.h>
[77285d9]59#include <sys/time.h>
60
[ce0d2cc]61#ifdef _MSC_VER
62    /* define the following from MSVC's internal types */
63    typedef             __int8  int8_t;
64    typedef             __int16 int16_t;
65    typedef             __int32 int32_t;
66    typedef             __int64 int64_t;
67    typedef unsigned    __int8  uint8_t;
68    typedef unsigned    __int16 uint16_t;
69    typedef unsigned    __int32 uint32_t;
70    typedef unsigned    __int64 uint64_t;
[39e141f]71        #ifdef BUILDING_DLL
72                #define DLLEXPORT __declspec(dllexport)
73        #else
74                #define DLLEXPORT __declspec(dllimport)
75        #endif
76        #define DLLLOCAL
77#else
78        #ifdef HAVE_GCCVISIBILITYPATCH
79                #define DLLEXPORT __attribute__ (visibility("default"))
80                #define DLLLOCAL __attribute__ (visibility("hidden"))
81        #else
82                #define DLLEXPORT
83                #define DLLLOCAL
84        #endif
[ce0d2cc]85#endif
86
87#ifdef WIN32
88#   include <winsock2.h>
89#   include <ws2tcpip.h>
90    typedef short sa_family_t;
91    /* Make up for a lack of stdbool.h */
92#    define bool signed char
93#    define false 0
94#    define true 1
[39e141f]95#    if !defined(ssize_t)
96     /* XXX: Not 64-bit safe! */
97#    define ssize_t int
98#    endif   
[ce0d2cc]99#else
100#    include <netinet/in.h>
[3fcb8b4]101
102#ifndef __cplusplus
[ce0d2cc]103#    include <stdbool.h>
[3fcb8b4]104#endif
105
[77285d9]106#    include <sys/types.h>
107#    include <sys/socket.h>
[ce0d2cc]108#endif
109
[803ea87]110/** API version as 2 byte hex digits, eg 0xXXYYZZ */
[e5f1431]111#define LIBTRACE_API_VERSION \
112            ((@LIBTRACE_MAJOR@<<16)|(@LIBTRACE_MID@<<8)|(@LIBTRACE_MINOR@))
[803ea87]113
114#ifdef __cplusplus
115extern "C" {
116#endif
117
118/* Function does not depend on anything but its
119 * parameters, used to hint gcc's optimisations
120 */
121#if __GNUC__ >= 3
122#  define SIMPLE_FUNCTION __attribute__((pure))
[3b8a5ef]123#  define UNUSED __attribute__((unused))
[7068467]124#  define PACKED __attribute__((packed))
[23971d0]125#  define CONSTRUCTOR __attribute__((constructor))
[803ea87]126#else
127#  define SIMPLE_FUNCTION
[3b8a5ef]128#  define UNUSED
[77285d9]129#  define PACKED
[23971d0]130#  define CONSTRUCTOR
[803ea87]131#endif
132       
[5eae97a]133/** Opaque structure holding information about an output trace */
[5a67294]134typedef struct libtrace_out_t libtrace_out_t;
[5eae97a]135       
[2c060e3]136/** Opaque structure holding information about a trace */
[5a67294]137typedef struct libtrace_t libtrace_t;
[2c060e3]138       
[c5a22ec]139/** Opaque structure holding information about a bpf filter */
[5a67294]140typedef struct libtrace_filter_t libtrace_filter_t;
[2137b49]141
[83445f0]142/** If a packet has memory allocated
[2e223eca]143 * If the packet has allocated it's own memory it's buffer_control should
144 * be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be
145 * free()'d.  If it's doing zerocopy out of memory owned by something else
146 * it should be TRACE_CTRL_EXTERNAL.
147 * @note the letters p and e are magic numbers used to detect if the packet
[0a6638f]148 * wasn't created properly
149 */
[2e223eca]150typedef enum {
151        TRACE_CTRL_PACKET='p',
152        TRACE_CTRL_EXTERNAL='e'
153} buf_control_t;
[83445f0]154/** The size of a packet's buffer when managed by libtrace */
[8283f05]155#define LIBTRACE_PACKET_BUFSIZE 65536
[d3b2234]156
[83445f0]157/** The libtrace packet structure, applications shouldn't be
158 * meddling around in here
[d3b2234]159 */
[5a67294]160typedef struct libtrace_packet_t {
[0d768c8]161        struct libtrace_t *trace; /**< pointer to the trace */
162        void *header;           /**< pointer to the framing header */
163        void *payload;          /**< pointer to the link layer */
164        buf_control_t buf_control; /**< who owns the memory */
165        void *buffer;           /**< allocated buffer */
[d3b2234]166        size_t size;            /**< trace_get_framing_length()
167                                 * +trace_get_capture_length() */
[7ac9705]168        uint32_t type;          /**< rt protocol type for the packet */
[7068467]169} libtrace_packet_t;
[0ea3526]170
171/** libtrace error information */
172typedef struct trace_err_t{
173        int err_num;            /**< error code */
174        char problem[255];      /**< the format, uri etc that caused the error for reporting purposes */
175} libtrace_err_t;
[2137b49]176
[ffc8c8d]177/** Enumeration of error codes */
[880aa58]178enum {
[91db67b]179        /** No Error has occured.... yet. */
[880aa58]180        TRACE_ERR_NOERROR       = 0,
[91db67b]181        /** The URI passed to trace_create() is unsupported, or badly formed */
[880aa58]182        TRACE_ERR_BAD_FORMAT    = -1,
[91db67b]183        /** The trace failed to initialise */
184        TRACE_ERR_INIT_FAILED   = -2,
185        /** Unknown config option */
186        TRACE_ERR_UNKNOWN_OPTION= -3,
187        /** This output uri cannot write packets of this type */
188        TRACE_ERR_NO_CONVERSION = -4,
189        /** This packet is corrupt, or unusable for the action required */
190        TRACE_ERR_BAD_PACKET    = -5,
[83445f0]191        /** Option known, but unsupported by this format */
192        TRACE_ERR_OPTION_UNAVAIL= -6,
[91db67b]193        /** This feature is unsupported */
194        TRACE_ERR_UNSUPPORTED   = -7
[880aa58]195};
[ffc8c8d]196
[83445f0]197/** Enumeration of DLT types supported by libtrace */
[114b8d6]198typedef enum {
199        TRACE_DLT_NULL = 0,
200        TRACE_DLT_EN10MB = 1,
201        TRACE_DLT_ATM_RFC1483 = 11,
202        TRACE_DLT_IEEE802_11 = 105,
203        TRACE_DLT_LINUX_SLL = 113,
204        TRACE_DLT_PFLOG = 117
205} libtrace_dlt_t ;
206
[83445f0]207/** Enumeration of link layer types supported by libtrace */
[c37ab9f]208typedef enum {
209       TRACE_TYPE_HDLC_POS = 1,
210       TRACE_TYPE_ETH,                  /**< 802.3 style Ethernet */
[83445f0]211       TRACE_TYPE_ATM,                  /**< ATM frame */
[c37ab9f]212       TRACE_TYPE_AAL5,
213       TRACE_TYPE_80211,                /**< 802.11 frames */
214       TRACE_TYPE_NONE,                 /**< Raw IP frames */
215       TRACE_TYPE_LINUX_SLL,            /**< Linux "null" framing */
216       TRACE_TYPE_PFLOG,                /**< FreeBSD's PFlug */
217       TRACE_TYPE_POS,
218       TRACE_TYPE_80211_PRISM = 12
219     } libtrace_linktype_t;
220
221/** Trace directions
222 * Note that these are the directions used by convention, more directions
223 * are possible, not just these 3, and that they may not conform to this
224 * convention.
225 */
226typedef enum {
227        TRACE_DIR_OUTGOING = 0,         /**< Packets originating "outside" */
228        TRACE_DIR_INCOMING = 1,         /**< Packets originating "inside" */
229        TRACE_DIR_OTHER    = 2          /**< Packets with an unknown direction, or one that's unknown */
230} libtrace_direction_t;
[114b8d6]231
[91c9552]232/** @name Protocol structures
[7068467]233 * These convenience structures are here as they are portable ways of dealing
234 * with various protocols.
235 * @{
236 */
237
[ce0d2cc]238#ifdef WIN32
239#pragma pack(push)
240#pragma pack(1)
241#endif
242
[83445f0]243/** Generic IP header structure */
[ce0d2cc]244typedef struct libtrace_ip
[fba4ca0]245{
[568dc0e]246#if BYTE_ORDER == LITTLE_ENDIAN
[83445f0]247    uint8_t ip_hl:4;            /**< Header Length */
248    uint8_t ip_v:4;             /**< Version */
[568dc0e]249#elif BYTE_ORDER == BIG_ENDIAN
[83445f0]250    uint8_t ip_v:4;             /**< Version */
251    uint8_t ip_hl:4;            /**< Header Length */
[568dc0e]252#else
253#   error "Adjust your <bits/endian.h> defines"
[2c060e3]254#endif
[83445f0]255    uint8_t  ip_tos;                    /**< Type of Service */
256    uint16_t ip_len;                    /**< Total Length */
257    int16_t  ip_id;                     /**< Identification */
[7068467]258#if BYTE_ORDER == LITTLE_ENDIAN
[83445f0]259    uint16_t ip_off:12;         /**< Fragment Offset */
260    uint16_t ip_mf:1;           /**< More Fragments Flag */
261    uint16_t ip_df:1;           /**< Dont Fragment Flag */
262    uint16_t ip_rf:1;           /**< Reserved Fragment Flag */
[7068467]263#elif BYTE_ORDER == BIG_ENDIAN
[83445f0]264    uint16_t ip_rf:1;           /**< Fragment Offset */
265    uint16_t ip_df:1;           /**< More Fragments Flag */
266    uint16_t ip_mf:1;           /**< Dont Fragment Flag */
267    uint16_t ip_off:12;         /**< Reserved Fragment Flag */
[7068467]268#else
269#   error "Adjust your <bits/endian.h> defines"
270#endif
[83445f0]271    uint8_t  ip_ttl;                    /**< Time to Live */
272    uint8_t  ip_p;                      /**< Protocol */
273    uint16_t ip_sum;                    /**< Checksum */
274    struct in_addr ip_src;              /**< Source Address */
275    struct in_addr ip_dst;              /**< Destination Address */
[ce0d2cc]276} PACKED libtrace_ip_t;
[4af54d1]277
[83445f0]278/** IPv6 header extension structure */
[ce0d2cc]279typedef struct libtrace_ip6_ext
[a842286]280{
281        uint8_t nxt;
282        uint8_t len;
[ce0d2cc]283} PACKED libtrace_ip6_ext_t;
[a842286]284
[83445f0]285/** Generic IPv6 header structure */
[e7bc155]286typedef struct libtrace_ip6
[a842286]287{
288    uint32_t flow;
289    uint16_t plen;                      /**< Payload length */
290    uint8_t nxt;                        /**< Next header */
[4af54d1]291    uint8_t hlim;                       /**< Hop limit */
292    struct in6_addr ip_src;             /**< source address */
293    struct in6_addr ip_dst;             /**< dest address */
[e7bc155]294} PACKED libtrace_ip6_t;
[2c060e3]295
[83445f0]296/** Generic TCP header structure */
[5a67294]297typedef struct libtrace_tcp
[2c060e3]298  {
[e7bc155]299    uint16_t source;            /**< Source Port */
300    uint16_t dest;              /**< Destination port */
301    uint32_t seq;               /**< Sequence number */
302    uint32_t ack_seq;           /**< Acknowledgement Number */
[568dc0e]303#  if BYTE_ORDER == LITTLE_ENDIAN
[7fc01569]304    uint8_t res1:4;     /**< Reserved bits */
[83445f0]305    uint8_t doff:4;     /**< Data Offset */     
[7fc01569]306    uint8_t fin:1;              /**< FIN */
307    uint8_t syn:1;              /**< SYN flag */
308    uint8_t rst:1;              /**< RST flag */
309    uint8_t psh:1;              /**< PuSH flag */
310    uint8_t ack:1;              /**< ACK flag */
311    uint8_t urg:1;              /**< URG flag */
312    uint8_t res2:2;     /**< Reserved */
[568dc0e]313#  elif BYTE_ORDER == BIG_ENDIAN
[7fc01569]314    uint8_t doff:4;     /**< Data offset */
315    uint8_t res1:4;     /**< Reserved bits */
316    uint8_t res2:2;     /**< Reserved */
317    uint8_t urg:1;              /**< URG flag */
318    uint8_t ack:1;              /**< ACK flag */
319    uint8_t psh:1;              /**< PuSH flag */
320    uint8_t rst:1;              /**< RST flag */
321    uint8_t syn:1;              /**< SYN flag */
322    uint8_t fin:1;              /**< FIN flag */
[2c060e3]323#  else
324#   error "Adjust your <bits/endian.h> defines"
325#  endif
[e7bc155]326    uint16_t window;            /**< Window Size */
327    uint16_t check;             /**< Checksum */
328    uint16_t urg_ptr;           /**< Urgent Pointer */
329} PACKED libtrace_tcp_t;
[2c060e3]330
[83445f0]331/** Generic UDP header structure */
[5a67294]332typedef struct libtrace_udp {
[e7bc155]333  uint16_t      source;         /**< Source port */
334  uint16_t      dest;           /**< Destination port */
335  uint16_t      len;            /**< Length */
336  uint16_t      check;          /**< Checksum */
337} PACKED libtrace_udp_t;
[2c060e3]338
[83445f0]339/** Generic ICMP header structure */
[5a67294]340typedef struct libtrace_icmp
[2c060e3]341{
[83445f0]342  uint8_t type;         /**< Message Type */
343  uint8_t code;         /**< Type Sub-code */
344  uint16_t checksum;            /**< Checksum */
[2c060e3]345  union
346  {
347    struct
348    {
[e7bc155]349      uint16_t  id;
350      uint16_t  sequence;
[83445f0]351    } echo;                     /**< Echo Datagram */
352    uint32_t    gateway;        /**< Gateway Address */
[2c060e3]353    struct
354    {
[e7bc155]355      uint16_t  unused;
356      uint16_t  mtu;
[83445f0]357    } frag;                     /**< Path MTU Discovery */
358  } un;                         /**< Union for Payloads of Various ICMP Codes */
[e7bc155]359} PACKED libtrace_icmp_t;
[fba4ca0]360
[83445f0]361/** Generic LLC/SNAP header structure */
[3b8a5ef]362typedef struct libtrace_llcsnap
363{
[12778c2]364/* LLC */
365  uint8_t dsap;                 /**< Destination Service Access Point */
366  uint8_t ssap;                 /**< Source Service Access Point */
[e7bc155]367  uint8_t control;
[12778c2]368/* SNAP */
369  uint32_t oui:24;              /**< Organisationally Unique Identifier (scope)*/
370  uint16_t type;                /**< Protocol within OUI */
[e7bc155]371} PACKED libtrace_llcsnap_t;
[3b8a5ef]372
[fba4ca0]373/** 802.3 frame */
[3b8338b]374typedef struct libtrace_ether
[fba4ca0]375{
[83445f0]376  uint8_t ether_dhost[6];       /**< Destination Ether Addr */
377  uint8_t ether_shost[6];       /**< Source Ether Addr */
378  uint16_t ether_type;          /**< Packet Type ID Field (next-header) */
[e7bc155]379} PACKED libtrace_ether_t;
[2c060e3]380
[5bbe424]381/** 802.1Q frame */
[3b8338b]382typedef struct libtrace_8021q
[5bbe424]383{
[83445f0]384  uint16_t vlan_pri:3;   /**< VLAN User Priority */
385  uint16_t vlan_cfi:1;   /**< VLAN Format Indicator,
[2e223eca]386                                   * 0 for ethernet, 1 for token ring */
[83445f0]387  uint16_t vlan_id:12;   /**< VLAN Id */
388  uint16_t vlan_ether_type;      /**< VLAN Sub-packet Type ID Field
[2e223eca]389                                   * (next-header)*/
[e7bc155]390} PACKED libtrace_8021q_t;
[2c060e3]391
[f04e489]392/** ATM cell */
[5a67294]393typedef struct libtrace_atm_cell
[f04e489]394{
[7fc01569]395  uint32_t gfc:4;               /**< Generic Flow Control */
396  uint32_t vpi:8;               /**< Virtual Path Identifier */
397  uint32_t vci:8;               /**< Virtual Channel Identifier */
398  uint32_t pt:3;                /**< Payload Type */
399  uint32_t clp:1;               /**< Cell Loss Priority */
400  uint32_t hec:8;               /**< Header Error Control */
[e7bc155]401} PACKED libtrace_atm_cell_t;
[f04e489]402
403/** POS header */
[5a67294]404typedef struct libtrace_pos
[f04e489]405{
[e7bc155]406 uint16_t header;
[83445f0]407 uint16_t ether_type;           /**< Ether Type */
[e7bc155]408} PACKED libtrace_pos_t;
[4af54d1]409
410/** 802.11 header */
411typedef struct libtrace_80211_t {
[7fc01569]412        uint16_t      protocol:2;
413        uint16_t      type:2;
414        uint16_t      subtype:4;
415        uint16_t      to_ds:1;          /**< Packet to Distribution Service */
416        uint16_t      from_ds:1;        /**< Packet from Distribution Service */
417        uint16_t      more_frag:1;      /**< Packet has more fragments */
418        uint16_t      retry:1;          /**< Packet is a retry */
419        uint16_t      power:1;
420        uint16_t      more_data:1;
421        uint16_t      wep:1;
422        uint16_t      order:1;
423        uint16_t     duration;
[4af54d1]424        uint8_t      mac1[6];
425        uint8_t      mac2[6];
426        uint8_t      mac3[6];
427        uint16_t     SeqCtl;
428        uint8_t      mac4[6];
[e7bc155]429} PACKED libtrace_80211_t;
430
431#ifdef WIN32
432#pragma pack(pop)
433#endif
[4af54d1]434
435
[7068467]436/*@}*/
[f04e489]437
[40ba6ad]438/** Prints help information for libtrace
439 *
440 * Function prints out some basic help information regarding libtrace,
441 * and then prints out the help() function registered with each input module
442 */
[39e141f]443DLLEXPORT void trace_help();
[2c060e3]444
[91c9552]445/** @name Trace management
446 * These members deal with creating, configuring, starting, pausing and
447 * cleaning up a trace object
[7068467]448 *@{
[7f32bb5]449 */
450
[2c060e3]451/** Create a trace file from a URI
452 *
[31709e8d]453 * @param uri containing a valid libtrace URI
[83445f0]454 * @return an opaque pointer to a libtrace_t
[2c060e3]455 *
456 * Valid URI's are:
457 *  - erf:/path/to/erf/file
458 *  - erf:-  (stdin)
[fba4ca0]459 *  - dag:/dev/dagcard                 
[fe43699]460 *  - pcapint:pcapinterface                (eg: pcap:eth0)
[2c060e3]461 *  - pcap:/path/to/pcap/file
462 *  - pcap:-
[83445f0]463 *  - rt:hostname
464 *  - rt:hostname:port
465 *  - rtclient:hostname (deprecated)
466 *  - rtclient:hostname:port (deprecated)
467 *  - wag:/dev/wagcard
468 *  - wtf:-
469 *  - wtf:/path/to/wtf/file
[2c060e3]470 *
[2e223eca]471 *  If an error occured when attempting to open the trace file, an error
472 *  trace is returned and trace_get_error should be called to find out
473 *  if an error occured, and what that error was.  The trace is created in the
474 *  configuration state, you must call trace_start to start the capture.
[2c060e3]475 */
[39e141f]476DLLEXPORT libtrace_t *trace_create(const char *uri);
[2c060e3]477
[084d95a]478/** Creates a "dummy" trace file that has only the format type set.
479 *
[83445f0]480 * @return an opaque pointer to a (sparsely initialised) libtrace_t
[084d95a]481 *
[2e223eca]482 * IMPORTANT: Do not attempt to call trace_read_packet or other such functions
483 * with the dummy trace. Its intended purpose is to act as a packet->trace for
484 * libtrace_packet_t's that are not associated with a libtrace_t structure.
[084d95a]485 */
[39e141f]486DLLEXPORT libtrace_t *trace_create_dead(const char *uri);
[084d95a]487
[5eae97a]488/** Creates a trace output file from a URI.
489 *
[fba4ca0]490 * @param uri   the uri string describing the output format and destination
[83445f0]491 * @return an opaque pointer to a libtrace_output_t
[5eae97a]492 *
493 * Valid URI's are:
[83445f0]494 *  - erf:/path/to/erf/file
495 *  - pcap:/path/to/pcap/file
496 *  - wtf:/path/to/wtf/file
[5eae97a]497 *
[fba4ca0]498 *  If an error occured when attempting to open the output trace, NULL is returned
499 *  and trace_errno is set. Use trace_perror() to get more information
[5eae97a]500 */
[39e141f]501DLLEXPORT libtrace_out_t *trace_create_output(const char *uri);
[5eae97a]502
[7068467]503/** Start the capture
504 * @param libtrace      The trace to start
[83445f0]505 * @return 0 on success, -1 on failure
[f99a183]506 *
[7068467]507 * This does the actual work with starting the trace capture, and applying
508 * all the config options.  This may fail.
509 */
[39e141f]510DLLEXPORT int trace_start(libtrace_t *libtrace);
[7068467]511
[1fbd938]512/** Pause the capture
513 * @param libtrace      The trace to pause
[83445f0]514 * @return 0 on success, -1 on failure
[1fbd938]515 *
516 * This stops a capture in progress and returns you to the configuration
517 * state.  Any packets that arrive after trace_pause() has been called
518 * will be discarded.  To resume capture, call trace_start().
519 */
[39e141f]520DLLEXPORT int trace_pause(libtrace_t *libtrace);
[1fbd938]521
[7068467]522/** Start an output trace
523 * @param libtrace      The trace to start
[83445f0]524 * @return 0 on success, -1 on failure
[fba4ca0]525 *
[7068467]526 * This does the actual work with starting a trace for write.  This generally
527 * creates the file.
[f99a183]528 */
[39e141f]529DLLEXPORT int trace_start_output(libtrace_out_t *libtrace);
[7068467]530
531/** Valid trace capture options */
532typedef enum {
533        TRACE_OPTION_SNAPLEN, /**< Number of bytes captured */
534        TRACE_OPTION_PROMISC, /**< Capture packets to other hosts */
[cd7eec7]535        TRACE_OPTION_FILTER,  /**< Apply this filter to all packets recieved */
536        TRACE_META_FREQ       /**< Frequency of meta-data information, e.g. DUCK packets */
[7068467]537} trace_option_t;
538
539/** Sets an input config option
540 * @param libtrace      the trace object to apply the option to
541 * @param option        the option to set
542 * @param value         the value to set the option to
543 * @return -1 if option configuration failed, 0 otherwise
544 * This should be called after trace_create, and before trace_start
545 */
[39e141f]546DLLEXPORT int trace_config(libtrace_t *libtrace,
[7068467]547                trace_option_t option,
548                void *value);
549
550typedef enum {
551        TRACE_OPTION_OUTPUT_FILEFLAGS, /**< File flags to open the trace file
552                                        * with.  eg O_APPEND
553                                        */
554        TRACE_OPTION_OUTPUT_COMPRESS   /**< Compression level, eg 6. */
555} trace_option_output_t;
556
557/** Sets an output config option
558 *
559 * @param libtrace      the output trace object to apply the option to
560 * @param option        the option to set
561 * @param value         the value to set the option to
562 * @return -1 if option configuration failed, 0 otherwise
563 * This should be called after trace_create_output, and before
564 * trace_start_output
565 */
[39e141f]566DLLEXPORT int trace_config_output(libtrace_out_t *libtrace,
[7068467]567                trace_option_output_t option,
568                void *value
569                );
[91ebc50]570
[2c060e3]571/** Close a trace file, freeing up any resources it may have been using
572 *
573 */
[39e141f]574DLLEXPORT void trace_destroy(libtrace_t *trace);
[2c060e3]575
[31709e8d]576/** Close a trace file, freeing up any resources it may have been using
577 * @param trace         trace file to be destroyed
578 */
[39e141f]579DLLEXPORT void trace_destroy_dead(libtrace_t *trace);
[084d95a]580
[5eae97a]581/** Close a trace output file, freeing up any resources it may have been using
[31709e8d]582 * @param trace         the output trace file to be destroyed
[5eae97a]583 */
[39e141f]584DLLEXPORT void trace_destroy_output(libtrace_out_t *trace);
[1fbd938]585
[0ea3526]586/** Check (and clear) the current error state of an input trace
587 * @param trace         the trace file to check the error state on
588 * @return Error report
589 * This reads and returns the current error state and sets the current error
590 * to "no error".
591 */
[39e141f]592DLLEXPORT libtrace_err_t trace_get_err(libtrace_t *trace);
[0ea3526]593
[eeab9832]594/** Return if there is an error
595 * @param trace         the trace file to check the error state on
596 * This does not clear the error status, and only returns true or false.
597 */
[39e141f]598DLLEXPORT bool trace_is_err(libtrace_t *trace);
[eeab9832]599
600/** Output an error message to stderr and clear the error status.
601 * @param trace         the trace with the error to output
602 * @param msg           the message to prefix to the error
603 * This function does clear the error status.
604 */
[39e141f]605DLLEXPORT void trace_perror(libtrace_t *trace, const char *msg,...);
[eeab9832]606
[0ea3526]607/** Check (and clear) the current error state of an output trace
608 * @param trace         the output trace file to check the error state on
609 * @return Error report
610 * This reads and returns the current error state and sets the current error
611 * to "no error".
612 */
[39e141f]613DLLEXPORT libtrace_err_t trace_get_err_output(libtrace_out_t *trace);
[0ea3526]614
[eeab9832]615/** Return if there is an error
616 * @param trace         the trace file to check the error state on
617 * This does not clear the error status, and only returns true or false.
618 */
[39e141f]619DLLEXPORT bool trace_is_err_output(libtrace_out_t *trace);
[eeab9832]620
621/** Output an error message to stderr and clear the error status.
622 * @param trace         the trace with the error to output
623 * @param msg           the message to prefix to the error
624 * This function does clear the error status.
625 */
[39e141f]626DLLEXPORT void trace_perror_output(libtrace_out_t *trace, const char *msg,...);
[eeab9832]627
628
[7068467]629/*@}*/
[7f32bb5]630
631/** @name Reading/Writing packets
632 * These members deal with creating, reading and writing packets
[7068467]633 *
634 * @{
[7f32bb5]635 */
[5eae97a]636
[14d8a63]637/** Create a new packet object
638 *
639 * @return a pointer to an initialised libtrace_packet_t object
640 */
[39e141f]641DLLEXPORT libtrace_packet_t *trace_create_packet();
[14d8a63]642
[91c9552]643/** Copy a packet
644 * @param packet        the source packet to copy
645 * @return a new packet which has the same content as the source packet
646 * @note This always involves a copy, which can be slow.  Use of this
647 * function should be avoided where possible.
648 * @par The reason you would want to use this function is that a zerocopied
649 * packet from a device is using the devices memory which may be a limited
650 * resource.  Copying the packet will cause it to be copied into the systems
651 * memory.
652 */
[39e141f]653DLLEXPORT libtrace_packet_t *trace_copy_packet(const libtrace_packet_t *packet);
[91c9552]654
[14d8a63]655/** Destroy a packet object
656 *
657 * sideeffect: sets packet to NULL
658 */
[39e141f]659DLLEXPORT void trace_destroy_packet(libtrace_packet_t **packet);
[14d8a63]660
661
[83445f0]662/** Read one packet from the trace
[2c060e3]663 *
[5eae97a]664 * @param trace         the libtrace opaque pointer
[2137b49]665 * @param packet        the packet opaque pointer
[9d7d9e9]666 * @return 0 on EOF, negative value on error, number of bytes read when
667 * successful.
[7068467]668 *
[9d7d9e9]669 * @note the number of bytes read is usually (but not always) the same as
670 * trace_get_framing_length()+trace_get_capture_length() depending on the
671 * trace format.
[7068467]672 * @note the trace must have been started with trace_start before calling
673 * this function
674 */
[39e141f]675DLLEXPORT int trace_read_packet(libtrace_t *trace, libtrace_packet_t *packet);
[7068467]676
677/** Event types
678 * see \ref libtrace_eventobj_t and \ref trace_event
679 */
680typedef enum {
681        TRACE_EVENT_IOWAIT,     /**< Need to block on fd */
682        TRACE_EVENT_SLEEP,      /**< Sleep for some time */
683        TRACE_EVENT_PACKET,     /**< packet has arrived */
684        TRACE_EVENT_TERMINATE   /**< End of trace */
685} libtrace_event_t;
686
[83445f0]687/** Structure returned by libtrace_event explaining what the current event is */
[7068467]688typedef struct libtrace_eventobj_t {
689        libtrace_event_t type; /**< event type (iowait,sleep,packet) */
690        int fd;                /**< if IOWAIT, the fd to sleep on */
[ed7c716]691        double seconds;        /**< if SLEEP, the amount of time to sleep for
692                                */
693        int size;              /**< if PACKET, the value returned from
694                                *  trace_read_packet
695                                */
[7068467]696} libtrace_eventobj_t;
697
[83445f0]698/** Processes the next libtrace event
[7068467]699 * @param trace the libtrace opaque pointer
700 * @param packet the libtrace_packet opaque pointer
701 * @return libtrace_event struct containing the type, and potential
702 *      fd or seconds to sleep on
[2c060e3]703 *
[7068467]704 * Type can be:
705 *  TRACE_EVENT_IOWAIT  Waiting on I/O on fd
706 *  TRACE_EVENT_SLEEP   Next event in seconds
707 *  TRACE_EVENT_PACKET  Packet arrived in buffer with size size
708 *  TRACE_EVENT_TERMINATE Trace terminated (perhaps with an error condition)
[2c060e3]709 */
[39e141f]710DLLEXPORT libtrace_eventobj_t trace_event(libtrace_t *trace,
[7068467]711                libtrace_packet_t *packet);
712
[2c060e3]713
[5eae97a]714/** Write one packet out to the output trace
715 *
716 * @param trace         the libtrace_out opaque pointer
717 * @param packet        the packet opaque pointer
[7068467]718 * @return the number of bytes written out, if zero or negative then an error has occured.
[5eae97a]719 */
[39e141f]720DLLEXPORT int trace_write_packet(libtrace_out_t *trace, const libtrace_packet_t *packet);
[7068467]721/*@}*/
[7f32bb5]722
[91c9552]723/** @name Protocol decodes
724 * These functions locate and return a pointer to various headers inside a
725 * packet
[7068467]726 * @{
[7f32bb5]727 */
[5eae97a]728
[2c060e3]729/** get a pointer to the link layer
[2137b49]730 * @param packet        the packet opaque pointer
[2c060e3]731 *
[7068467]732 * @return a pointer to the link layer, or NULL if there is no link layer
[2c060e3]733 *
[83445f0]734 * @note you should call trace_get_link_type to find out what type of link
735 * layer this is
[2c060e3]736 */
[39e141f]737DLLEXPORT SIMPLE_FUNCTION
[7068467]738void *trace_get_link(const libtrace_packet_t *packet);
[2c060e3]739
740/** get a pointer to the IP header (if any)
[2137b49]741 * @param packet        the packet opaque pointer
[2c060e3]742 *
[83445f0]743 * @return a pointer to the IP header, or NULL if there is no IP header
[2c060e3]744 */
[2ba89b7]745DLLEXPORT SIMPLE_FUNCTION
[9231fe5]746libtrace_ip_t *trace_get_ip(libtrace_packet_t *packet);
[2c060e3]747
[9c87732]748/** Gets a pointer to the transport layer header (if any)
749 * @param packet        a pointer to a libtrace_packet structure
[a842286]750 * @param[out] proto    transport layer protocol
[9c87732]751 *
[7068467]752 * @return a pointer to the transport layer header, or NULL if there is no header
[a842286]753 *
754 * @note proto may be NULL if proto is unneeded.
[9c87732]755 */
[39e141f]756DLLEXPORT void *trace_get_transport(libtrace_packet_t *packet, uint8_t *proto,
[9231fe5]757                uint32_t *remaining);
[9c87732]758
[4af54d1]759/** Gets a pointer to the payload given a pointer to the IP header
[9c87732]760 * @param ip            The IP Header
[a842286]761 * @param[out] proto    An output variable of the IP protocol
[9231fe5]762 * @param[in,out] remaining Updated with the number of bytes remaining
[9c87732]763 *
[9231fe5]764 * @return a pointer to the transport layer header, or NULL if header isn't present.
765 *
766 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
767 * of bytes captured of the IP header and beyond.  It will be updated after this
768 * function to the number of bytes remaining after the IP header (and any IP options)
769 * have been removed.
[9c87732]770 *
[9231fe5]771 * proto may be NULL if not needed.
772 *
773 * @note This is similar to trace_get_transport_from_ip in libtrace2
[4af54d1]774 */
[39e141f]775DLLEXPORT void *trace_get_payload_from_ip(libtrace_ip_t *ip, uint8_t *proto,
[9231fe5]776                uint32_t *remaining);
[4af54d1]777
778/** Gets a pointer to the payload given a pointer to a tcp header
779 * @param tcp           The tcp Header
[9231fe5]780 * @param[in,out] remaining Updated with the number of bytes remaining
[4af54d1]781 *
[9231fe5]782 * @return a pointer to the tcp payload, or NULL if the payload isn't present.
[4af54d1]783 *
[9231fe5]784 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
785 * of bytes captured of the TCP header and beyond.  It will be updated after this
786 * function to the number of bytes remaining after the TCP header (and any TCP options)
787 * have been removed.
788 *
789 * @note This is similar to trace_get_transport_from_ip in libtrace2
[4af54d1]790 */
[39e141f]791DLLEXPORT void *trace_get_payload_from_tcp(libtrace_tcp_t *tcp, uint32_t *remaining);
[4af54d1]792
793/** Gets a pointer to the payload given a pointer to a udp header
794 * @param udp           The udp Header
[9231fe5]795 * @param[in,out] remaining Updated with the number of bytes remaining
[4af54d1]796 *
[9231fe5]797 * @return a pointer to the udp payload, or NULL if the payload isn't present.
798 *
799 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
800 * of bytes captured of the TCP header and beyond.  It will be updated after this
801 * function to the number of bytes remaining after the TCP header (and any TCP options)
802 * have been removed.
[4af54d1]803 *
[9231fe5]804 * @note This is similar trace_get_transport_from_ip in libtrace2
[4af54d1]805 */
[39e141f]806DLLEXPORT void *trace_get_payload_from_udp(libtrace_udp_t *udp, uint32_t *remaining);
[4af54d1]807
808/** Gets a pointer to the payload given a pointer to a icmp header
[9231fe5]809 * @param icmp          The icmp Header
810 * @param[in,out] remaining Updated with the number of bytes remaining
[4af54d1]811 *
[9231fe5]812 * @return a pointer to the icmp payload, or NULL if the payload isn't present.
813 *
814 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
815 * of bytes captured of the TCP header and beyond.  It will be updated after this
816 * function to the number of bytes remaining after the TCP header (and any TCP options)
817 * have been removed.
[4af54d1]818 *
[9231fe5]819 * @note This is similar to trace_get_payload_from_icmp in libtrace2
[9c87732]820 */
[83445f0]821DLLEXPORT void *trace_get_payload_from_icmp(libtrace_icmp_t *icmp, uint32_t *remaining);
[9c87732]822
[2c060e3]823/** get a pointer to the TCP header (if any)
[2137b49]824 * @param packet        the packet opaque pointer
[2c060e3]825 *
[7068467]826 * @return a pointer to the TCP header, or NULL if there is not a TCP packet
[2c060e3]827 */
[39e141f]828DLLEXPORT SIMPLE_FUNCTION
[9231fe5]829libtrace_tcp_t *trace_get_tcp(libtrace_packet_t *packet);
[2c060e3]830
[68667ee]831/** get a pointer to the TCP header (if any) given a pointer to the IP header
832 * @param ip            The IP header
[9231fe5]833 * @param[in,out] remaining Updated with the number of bytes remaining
[68667ee]834 *
[7068467]835 * @return a pointer to the TCP header, or NULL if this is not a TCP packet
[68667ee]836 *
[9231fe5]837 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
838 * of bytes captured of the TCP header and beyond.  It will be updated after this
839 * function to the number of bytes remaining after the TCP header (and any TCP options)
840 * have been removed.
[68667ee]841 *
[9231fe5]842 * @note The last parameter has changed from libtrace2
[68667ee]843 */
[39e141f]844DLLEXPORT SIMPLE_FUNCTION
[9231fe5]845libtrace_tcp_t *trace_get_tcp_from_ip(libtrace_ip_t *ip, uint32_t *remaining);
[68667ee]846
[2c060e3]847/** get a pointer to the UDP header (if any)
[2137b49]848 * @param packet        the packet opaque pointer
[2c060e3]849 *
[7068467]850 * @return a pointer to the UDP header, or NULL if this is not a UDP packet
[2c060e3]851 */
[39e141f]852DLLEXPORT SIMPLE_FUNCTION
[4af54d1]853libtrace_udp_t *trace_get_udp(libtrace_packet_t *packet);
[2c060e3]854
[68667ee]855/** get a pointer to the UDP header (if any) given a pointer to the IP header
856 * @param       ip      The IP header
[9231fe5]857 * @param[in,out] remaining Updated with the number of bytes remaining
[68667ee]858 *
[7068467]859 * @return a pointer to the UDP header, or NULL if this is not an UDP packet
[68667ee]860 *
[9231fe5]861 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
862 * of bytes captured of the TCP header and beyond.  It will be updated after this
863 * function to the number of bytes remaining after the TCP header (and any TCP options)
864 * have been removed.
865 *
866 * @note Beware the change from libtrace2 from skipped to remaining
[68667ee]867 */
[39e141f]868DLLEXPORT SIMPLE_FUNCTION
[9231fe5]869libtrace_udp_t *trace_get_udp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
[68667ee]870
[2c060e3]871/** get a pointer to the ICMP header (if any)
[2137b49]872 * @param packet        the packet opaque pointer
[2c060e3]873 *
[7068467]874 * @return a pointer to the ICMP header, or NULL if this is not a ICMP packet
[2c060e3]875 */
[39e141f]876DLLEXPORT SIMPLE_FUNCTION
[9231fe5]877libtrace_icmp_t *trace_get_icmp(libtrace_packet_t *packet);
[2c060e3]878
[68667ee]879/** get a pointer to the ICMP header (if any) given a pointer to the IP header
880 * @param ip            The IP header
[9231fe5]881 * @param[in,out] remaining Updated with the number of bytes remaining
[68667ee]882 *
[7068467]883 * @return a pointer to the ICMP header, or NULL if this is not an ICMP packet
[68667ee]884 *
[9231fe5]885 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
886 * of bytes captured of the TCP header and beyond.  It will be updated after this
887 * function to the number of bytes remaining after the TCP header (and any TCP options)
888 * have been removed.
889 *
890 * @note Beware the change from libtrace2 from skipped to remaining
891 */
[39e141f]892DLLEXPORT SIMPLE_FUNCTION
[9231fe5]893libtrace_icmp_t *trace_get_icmp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
894
895/** Get the destination MAC addres
896 * @param packet        the packet opaque pointer
897 * @return a pointer to the destination mac, (or NULL if there is no
898 * destination MAC)
899 */
[39e141f]900DLLEXPORT SIMPLE_FUNCTION
[9231fe5]901uint8_t *trace_get_destination_mac(libtrace_packet_t *packet);
902
903/** Get the source MAC addres
904 * @param packet        the packet opaque pointer
905 * @return a pointer to the source mac, (or NULL if there is no source MAC)
[68667ee]906 */
[e093e5c]907DLLEXPORT SIMPLE_FUNCTION
[9231fe5]908uint8_t *trace_get_source_mac(libtrace_packet_t *packet);
909
910/** Get the source addres
911 * @param packet        the packet opaque pointer
912 * @param addr          a pointer to a sockaddr to store the address in, or NULL to use
913 *                      static storage.
914 * @return NULL if there is no source address, or a sockaddr holding a v4 or v6 address
915 */
[39e141f]916DLLEXPORT SIMPLE_FUNCTION
[9231fe5]917struct sockaddr *trace_get_source_address(const libtrace_packet_t *packet,
918                struct sockaddr *addr);
919
920/** Get the source addres
921 * @param packet        the packet opaque pointer
922 * @param addr          a pointer to a sockaddr to store the address in, or NULL to use
923 *                      static storage.
924 * @return NULL if there is no source address, or a sockaddr holding a v4 or v6 address
925 */
[39e141f]926DLLEXPORT SIMPLE_FUNCTION
[9231fe5]927struct sockaddr *trace_get_destination_address(const libtrace_packet_t *packet,
928                struct sockaddr *addr);
929
[7068467]930/*@}*/
[68667ee]931
932/** parse an ip or tcp option
933 * @param[in,out] ptr   the pointer to the current option
934 * @param[in,out] len   the length of the remaining buffer
935 * @param[out] type     the type of the option
936 * @param[out] optlen   the length of the option
937 * @param[out] data     the data of the option
938 *
[7068467]939 * @return bool true if there is another option (and the fields are filled in)
[68667ee]940 *               or false if this was the last option.
941 *
942 * This updates ptr to point to the next option after this one, and updates
943 * len to be the number of bytes remaining in the options area.  Type is updated
944 * to be the code of this option, and data points to the data of this option,
945 * with optlen saying how many bytes there are.
946 *
947 * @note Beware of fragmented packets.
948 */
[39e141f]949DLLEXPORT int trace_get_next_option(unsigned char **ptr,int *len,
[68667ee]950                        unsigned char *type,
951                        unsigned char *optlen,
952                        unsigned char **data);
953
954
[7f32bb5]955/** @name Time
956 * These functions deal with time that a packet arrived and return it
957 * in various formats
[7068467]958 * @{
[7f32bb5]959 */
[2c060e3]960/** Get the current time in DAG time format
[2137b49]961 * @param packet        the packet opaque pointer
962 *
[7068467]963 * @return a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
[2c060e3]964 * past 1970-01-01, the lower 32bits are partial seconds)
965 */
[39e141f]966DLLEXPORT SIMPLE_FUNCTION
[7068467]967uint64_t trace_get_erf_timestamp(const libtrace_packet_t *packet);
[2c060e3]968
969/** Get the current time in struct timeval
[2137b49]970 * @param packet        the packet opaque pointer
971 *
[7068467]972 * @return time that this packet was seen in a struct timeval
[2c060e3]973 */
[39e141f]974DLLEXPORT SIMPLE_FUNCTION
[7068467]975struct timeval trace_get_timeval(const libtrace_packet_t *packet);
[2c060e3]976
977/** Get the current time in floating point seconds
[2137b49]978 * @param packet        the packet opaque pointer
979 *
[7068467]980 * @return time that this packet was seen in 64bit floating point seconds
[2c060e3]981 */
[39e141f]982DLLEXPORT SIMPLE_FUNCTION
[7068467]983double trace_get_seconds(const libtrace_packet_t *packet);
[91c9552]984
985/** Seek within a trace
986 * @param trace         trace to seek
987 * @param seconds       time to seek to
988 * @return 0 on success.
989 * Make the next packet read to be the first packet to occur at or after the
990 * time searched for.  This must be called in the configuration state (ie,
991 * before trace_start() or after trace_pause().
992 * @note This function may be extremely slow.
993 */
[39e141f]994DLLEXPORT int trace_seek_seconds(libtrace_t *trace, double seconds);
[91c9552]995
996/** Seek within a trace
997 * @param trace         trace to seek
998 * @param tv            time to seek to
999 * @return 0 on success.
1000 * Make the next packet read to be the first packet to occur at or after the
1001 * time searched for.  This must be called in the configuration state (ie,
1002 * before trace_start() or after trace_pause().
1003 * @note This function may be extremely slow.
1004 */
[39e141f]1005DLLEXPORT int trace_seek_timeval(libtrace_t *trace, struct timeval tv);
[91c9552]1006
[0d57541]1007/** Seek within a trace
1008 * @param trace         trace to seek
1009 * @param ts            erf timestamp
1010 * @return 0 on success.
1011 * Make the next packet read to be the first packet to occur at or after the
1012 * time searched for.  This must be called in the configuration state (ie,
1013 * before trace_start() or after trace_pause().
1014 * @note This function may be extremely slow.
1015 */
[39e141f]1016DLLEXPORT int trace_seek_erf_timestamp(libtrace_t *trace, uint64_t ts);
[0d57541]1017
[7068467]1018/*@}*/
[2c060e3]1019
[7f32bb5]1020/** @name Sizes
1021 * This section deals with finding or setting the various different lengths
1022 * a packet can have
[7068467]1023 * @{
[7f32bb5]1024 */
[2c060e3]1025/** Get the size of the packet in the trace
[2137b49]1026 * @param packet        the packet opaque pointer
[7068467]1027 * @return the size of the packet in the trace
[2c060e3]1028 * @note Due to this being a header capture, or anonymisation, this may not
[52f8fc2]1029 * be the same size as the original packet.  See get_wire_length() for the
1030 * original size of the packet.
[2c060e3]1031 * @note This can (and often is) different for different packets in a trace!
[52f8fc2]1032 * @note This is sometimes called the "snaplen".
1033 * @note The return size refers to the network-level payload of the packet and
[83445f0]1034 * does not include any capture framing headers. For example, an Ethernet
1035 * packet with an empty TCP packet will return sizeof(ethernet_header) +
1036 * sizeof(ip_header) + sizeof(tcp_header).
[2c060e3]1037 */
[39e141f]1038DLLEXPORT SIMPLE_FUNCTION
[d8f02df]1039size_t trace_get_capture_length(const libtrace_packet_t *packet);
[2c060e3]1040
1041/** Get the size of the packet as it was seen on the wire.
[2137b49]1042 * @param packet        the packet opaque pointer
[7068467]1043 * @return the size of the packet as it was on the wire.
[2c060e3]1044 * @note Due to the trace being a header capture, or anonymisation this may
1045 * not be the same as the Capture Len.
[ed636fb4]1046 * @note trace_getwire_length \em{includes} FCS.
[2c060e3]1047 */
[39e141f]1048DLLEXPORT SIMPLE_FUNCTION
[d8f02df]1049size_t trace_get_wire_length(const libtrace_packet_t *packet);
[2c060e3]1050
[7c8eacf]1051/** Get the length of the capture framing headers.
1052 * @param packet        the packet opaque pointer
[1fbd938]1053 * @return the size of the packet as it was on the wire.
[7c8eacf]1054 * @note this length corresponds to the difference between the size of a
1055 * captured packet in memory, and the captured length of the packet
1056 */
[39e141f]1057DLLEXPORT SIMPLE_FUNCTION
[d8f02df]1058size_t trace_get_framing_length(const libtrace_packet_t *packet);
[7c8eacf]1059
[91c9552]1060/** Truncate ("snap") the packet at the suggested length
[7f32bb5]1061 * @param packet        the packet opaque pointer
1062 * @param size          the new length of the packet
[d3b2234]1063 * @return the new capture length of the packet, or the original capture
1064 * length of the packet if unchanged
[7f32bb5]1065 */
[39e141f]1066DLLEXPORT size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
[7f32bb5]1067
[7068467]1068/*@}*/
[7f32bb5]1069
[7c8eacf]1070
[2c060e3]1071/** Get the type of the link layer
[2137b49]1072 * @param packet        the packet opaque pointer
[7068467]1073 * @return libtrace_linktype_t
[2c060e3]1074 */
[39e141f]1075DLLEXPORT SIMPLE_FUNCTION
[eeab9832]1076libtrace_linktype_t trace_get_link_type(const libtrace_packet_t *packet);
[2c060e3]1077
[80a2e99]1078/** Set the direction flag, if it has one
1079 * @param packet        the packet opaque pointer
[c37ab9f]1080 * @param direction     the new direction
1081 * @returns -1 on error, or the direction that was set.
[80a2e99]1082 */
[c37ab9f]1083DLLEXPORT libtrace_direction_t trace_set_direction(libtrace_packet_t *packet, libtrace_direction_t direction);
[80a2e99]1084
[14a9d05]1085/** Get the direction flag, if it has one
[2137b49]1086 * @param packet        the packet opaque pointer
[c37ab9f]1087 * @return a value containing the direction flag, or -1 if this is not supported
[9075d49]1088 * The direction is defined as 0 for packets originating locally (ie, outbound)
1089 * and 1 for packets originating remotely (ie, inbound).
1090 * Other values are possible, which might be overloaded to mean special things
1091 * for a special trace.
[14a9d05]1092 */
[39e141f]1093DLLEXPORT SIMPLE_FUNCTION
[c37ab9f]1094libtrace_direction_t trace_get_direction(const libtrace_packet_t *packet);
[2c060e3]1095
[7f32bb5]1096/** @name BPF
1097 * This section deals with using Berkley Packet Filters
[7068467]1098 * @{
[7f32bb5]1099 */
[c681e86]1100/** setup a BPF filter
1101 * @param filterstring a char * containing the bpf filter string
[7068467]1102 * @return opaque pointer pointer to a libtrace_filter_t object
[fba4ca0]1103 * @note The filter is not actually compiled at this point, so no correctness
1104 * tests are performed here. trace_bpf_setfilter will always return ok, but
1105 * if the filter is poorly constructed an error will be generated when the
1106 * filter is actually used
[c681e86]1107 */
[39e141f]1108DLLEXPORT SIMPLE_FUNCTION
[7068467]1109libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
[c681e86]1110
1111/** apply a BPF filter
[2137b49]1112 * @param filter        the filter opaque pointer
1113 * @param packet        the packet opaque pointer
[91c9552]1114 * @return 1 if the filter matches, 0 if it doesn't.
1115 * @note Due to the way BPF filters are built, the filter is not actually
1116 * compiled until the first time trace_bpf_filter is called. If your filter is
1117 * incorrect, it will generate an error message and assert, exiting the
1118 * program. This behaviour may change to more graceful handling of this error
1119 * in the future.
[c681e86]1120 */
[39e141f]1121DLLEXPORT int trace_bpf_filter(libtrace_filter_t *filter,
[7068467]1122                const libtrace_packet_t *packet);
[747c501]1123
1124/** destory of BPF filter
1125 * @param filter        the filter opaque pointer
1126 * Deallocate all the resources associated with a BPF filter
1127 */
1128DLLEXPORT void trace_destroy_bpf(libtrace_filter_t *filter);
[7068467]1129/*@}*/
[83e0a25]1130
[752709f]1131/** @name Portability
1132 * This section has functions that causes annoyances to portability for one
1133 * reason or another.
1134 * @{
1135 */
1136
1137/** Convert an ethernet address to a string
1138 * @param addr  Ethernet address in network byte order
1139 * @param buf   Buffer to store the ascii representation, or NULL
1140 * @return buf, or if buf is NULL then a statically allocated buffer.
1141 *
1142 * This function is similar to the GNU ether_ntoa_r function, with a few
1143 * minor differences.  if NULL is passed as buf, then the function will
1144 * use an internal static buffer, if NULL isn't passed then the function
1145 * will use that buffer instead.
1146 *
1147 * @note the type of addr isn't struct ether_addr as it is with ether_ntoa_r,
1148 * however it is bit compatible so that a cast will work.
1149 */
[39e141f]1150DLLEXPORT char *trace_ether_ntoa(const uint8_t *addr, char *buf);
[752709f]1151
1152/** Convert a string to an ethernet address
1153 * @param buf   Ethernet address in hex format delimited with :'s.
1154 * @param addr  buffer to store the binary representation, or NULL
1155 * @return addr, or if addr is NULL, then a statically allocated buffer.
1156 *
1157 * This function is similar to the GNU ether_aton_r function, with a few
1158 * minor differences.  if NULL is passed as addr, then the function will
1159 * use an internal static buffer, if NULL isn't passed then the function will
1160 * use that buffer instead.
1161 *
1162 * @note the type of addr isn't struct ether_addr as it is with ether_aton_r,
1163 * however it is bit compatible so that a cast will work.
1164 */
[39e141f]1165DLLEXPORT uint8_t *trace_ether_aton(const char *buf, uint8_t *addr);
[752709f]1166
1167/*@}*/
1168
1169
[31709e8d]1170/** Which port is the server port */
1171typedef enum {
1172        USE_DEST,       /**< Destination port is the server port */
1173        USE_SOURCE      /**< Source port is the server port */
1174} serverport_t;
[83e0a25]1175
[58e9e02]1176/** Get the source port
1177 * @param packet        the packet to read from
[83445f0]1178 * @return a port in \em HOST byte order, or equivalent to ports for this
[58e9e02]1179 * protocol, or 0 if this protocol has no ports.
1180 */
[39e141f]1181DLLEXPORT SIMPLE_FUNCTION
[7068467]1182uint16_t trace_get_source_port(const libtrace_packet_t *packet);
[58e9e02]1183
1184/** Get the destination port
1185 * @param packet        the packet to read from
[7068467]1186 * @return a port in \em HOST byte order, or equivilent to ports for this
[58e9e02]1187 * protocol, or 0 if this protocol has no ports.
1188 */
[39e141f]1189DLLEXPORT SIMPLE_FUNCTION
[7068467]1190uint16_t trace_get_destination_port(const libtrace_packet_t *packet);
[58e9e02]1191
[83e0a25]1192/** hint at the server port in specified protocol
1193 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
1194 * @param source        the source port from the packet
1195 * @param dest          the destination port from the packet
[7068467]1196 * @return one of USE_SOURCE or USE_DEST depending on which one you should use
[fba4ca0]1197 * @note ports must be in \em HOST byte order!
[83e0a25]1198 */
[39e141f]1199DLLEXPORT SIMPLE_FUNCTION
[83e0a25]1200int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
1201
[de8c420b]1202/** Takes a uri and splits it into a format and uridata component.
1203 * @param uri           the uri to be parsed
1204 * @param format        destination location for the format component of the uri
[7068467]1205 * @return 0 if an error occured, otherwise return the uridata component
[de8c420b]1206 */
[39e141f]1207DLLEXPORT const char *trace_parse_uri(const char *uri, char **format);
[3d4d52d]1208
[2e223eca]1209/** RT protocol base format identifiers
1210 * This is used to say what kind of packet is being sent over the rt protocol
1211 */
[6dbc47a]1212enum base_format_t {
1213        TRACE_FORMAT_ERF          =1,
1214        TRACE_FORMAT_PCAP         =2,
[dd2eaee]1215        TRACE_FORMAT_PCAPFILE     =3,
1216        TRACE_FORMAT_WAG          =4,
1217        TRACE_FORMAT_RT           =5,
1218        TRACE_FORMAT_LEGACY_ATM   =6,
1219        TRACE_FORMAT_LEGACY_POS   =7,
1220        TRACE_FORMAT_LEGACY_ETH   =8,
[cd7eec7]1221        TRACE_FORMAT_LINUX_NATIVE =9,
1222        TRACE_FORMAT_DUCK         =10
[6dbc47a]1223};
1224
[83445f0]1225/** Gets the format type for a given packet.
[6dbc47a]1226 * @param packet        the packet opaque pointer
1227 * @return the format of the packet
1228 */
[e093e5c]1229DLLEXPORT
[6dbc47a]1230enum base_format_t trace_get_format(struct libtrace_packet_t *packet);
1231
[83445f0]1232
[27615e9]1233#ifdef __cplusplus
[7068467]1234} /* extern "C" */
1235#endif /* #ifdef __cplusplus */
1236#endif /* LIBTRACE_H_ */
Note: See TracBrowser for help on using the repository browser.