source: lib/libtrace_int.h @ 3799f51

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 3799f51 was 3799f51, checked in by Richard Sanger <rjs51@…>, 8 years ago

Accidently reversed changeset 1842 with the last commit

  • Property mode set to 100644
File size: 35.4 KB
RevLine 
[4dedc28]1/*
2 * This file is part of libtrace
3 *
[8488c15]4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
[4dedc28]7 * Authors: Daniel Lawson
[8488c15]8 *          Perry Lorier
9 *          Shane Alcock
[4dedc28]10 *         
11 * All rights reserved.
12 *
13 * This code has been developed by the University of Waikato WAND
14 * research group. For further information please see http://www.wand.net.nz/
15 *
16 * libtrace is free software; you can redistribute it and/or modify
17 * it under the terms of the GNU General Public License as published by
18 * the Free Software Foundation; either version 2 of the License, or
19 * (at your option) any later version.
20 *
21 * libtrace is distributed in the hope that it will be useful,
22 * but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24 * GNU General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with libtrace; if not, write to the Free Software
28 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29 *
30 * $Id$
31 *
32 */
33
[8488c15]34/** @file
35 *
36 * @brief Header file containing definitions for structures and functions that
37 * are internal
38 *
39 * @author Daniel Lawson
40 * @author Perry Lorier
41 * @author Shane Alcock
42 *
43 * @version $Id$
44 *
45 * All of the structures and functions defined in this header file are intended
46 * for internal use within Libtrace only. They should not be exported as part
47 * of the library API as we don't want users accessing things like the
48 * contents of the libtrace packet structure directly!
49 */
[9e2a109]50#ifndef LIBTRACE_INT_H
51#define LIBTRACE_INT_H
[4dedc28]52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57#include "config.h"
[1326d5f]58#include "common.h"
[4dedc28]59#include "libtrace.h"
[91b72d3]60#include "wandio.h"
[af52072]61
62#ifdef _MSC_VER
[6ed6c4a]63// warning: deprecated function
[af52072]64#pragma warning(disable:4996)
[6ed6c4a]65// warning: benign redefinitions of types
66#pragma warning(disable:4142)
[af52072]67#endif
68
69#ifdef HAVE_INTTYPES_H
70# include <inttypes.h>
71#else
72# include "lt_inttypes.h"
73#endif
74
75#ifdef HAVE_STDDEF_H
76# include <stddef.h>
77#else
78#ifndef WIN32
79# error "Can't find stddev.h -- do you define ptrdiff_t elsewhere?"
80#endif
81#endif
82
83
[afd0b73]84#include "rt_protocol.h"
[c1f2553]85       
[1f47cdd]86/* Prefer net/bpf.h over pcap-bpf.h for format_bpf.c on MacOS */
[5361eae]87#ifdef HAVE_NET_BPF_H
88#    include <net/bpf.h>
89#    define HAVE_BPF 1
90#else
[e5c2bc4]91#ifdef HAVE_PCAP_BPF_H
[4dedc28]92#  include <pcap-bpf.h>
[e5c2bc4]93#  define HAVE_BPF 1
[5361eae]94#endif
[4dedc28]95#endif
96
[e5c2bc4]97#ifdef HAVE_PCAP_H
[4dedc28]98#  include <pcap.h>
99#  ifdef HAVE_PCAP_INT_H
100#    include <pcap-int.h>
101#  endif
102#endif
103
[e5c2bc4]104#ifdef HAVE_ZLIB_H
[4dedc28]105#  include <zlib.h>
106#endif
107
[1576a3b]108#ifndef HAVE_STRNDUP
109char *strndup(const char *s, size_t size);
110#endif
111
[39e141f]112#ifndef HAVE_STRNCASECMP
113# ifndef HAVE__STRNICMP
[8488c15]114/** A local implementation of strncasecmp (as some systems do not have it) */
[39e141f]115int strncasecmp(const char *str1, const char *str2, size_t n);
116# else
117# define strncasecmp _strnicmp
118# endif
119#endif
120
121#ifndef HAVE_SNPRINTF
122# ifndef HAVE_SPRINTF_S
[8488c15]123/** A local implementation of snprintf (as some systems do not have it) */
[39e141f]124int snprintf(char *str, size_t size, const char *format, ...);
125# else
126# define snprintf sprintf_s
127# endif
128#endif
[4dedc28]129
[f9374e9]130#include "daglegacy.h"
131       
[4dedc28]132#ifdef HAVE_DAG_API
133#  include "dagnew.h"
134#  include "dagapi.h"
[2317d78]135#       if DAG_VERSION == 24
[2faa57e]136#               include <erftypes.h>
[2317d78]137#       else
138#               include <daginf.h>
[deed208]139#       endif
[ae3779b]140#  include "erftypes.h"
[4dedc28]141#else
142#  include "dagformat.h"
143#endif
144
[31a15db]145#ifdef HAVE_LLVM
146#include "bpf-jit/bpf-jit.h"
147#endif
148
[8488c15]149//#define RP_BUFSIZE 65536U
[4dedc28]150
[8488c15]151/** Data about the most recent event from a trace file */
[67a14d4]152struct libtrace_event_status_t {
[8488c15]153        /** A libtrace packet to store the packet when a PACKET event occurs */
[0d57541]154        libtrace_packet_t *packet;
[8488c15]155        /** Time between the timestamp for the current packet and the current
156         * walltime */
[4dedc28]157        double tdelta;
[8488c15]158        /** The timestamp of the previous PACKET event */
[4dedc28]159        double trace_last_ts;
[8488c15]160        /** The size of the current PACKET event */
[25024fd]161        int psize;
[9cc1266]162        /** Whether there is a packet stored in *packet above waiting for an
163         * event to occur */
164        bool waiting;
[4dedc28]165};
166
[8488c15]167/** A libtrace input trace
[9e2a109]168 * @internal
169 */
170struct libtrace_t {
[8488c15]171        /** The capture format for the input trace */
172        struct libtrace_format_t *format; 
173        /** Details of the most recent PACKET event reported by the trace */
174        struct libtrace_event_status_t event;
175        /** Pointer to the "global" data for the capture format module */       
176        void *format_data;             
177        /** A BPF filter to be applied to all packets read by the trace -
178         * used only if the capture format does not support filters natively */
179        struct libtrace_filter_t *filter; 
180        /** The snap length to be applied to all packets read by the trace -
181         * used only if the capture format does not support snapping natively */
182        size_t snaplen;                 
183        /** Count of the number of packets returned to the libtrace user */
184        uint64_t accepted_packets;     
185        /** Count of the number of packets filtered by libtrace */
186        uint64_t filtered_packets;     
187        /** The filename from the uri for the trace */
188        char *uridata;                 
189        /** The libtrace IO reader for this trace (if applicable) */
190        io_t *io;                       
191        /** Error information for the trace */
192        libtrace_err_t err;             
193        /** Boolean flag indicating whether the trace has been started */
194        bool started;                   
[9e2a109]195};
[1fc2f6a]196
[8488c15]197/** A libtrace output trace
[2e223eca]198 * @internal
199 */
[9e2a109]200struct libtrace_out_t {
[8488c15]201        /** The capture format for the output trace */
202        struct libtrace_format_t *format;
203        /** Pointer to the "global" data for the capture format module */
204        void *format_data;             
205        /** The filename for the uri for the output trace */
206        char *uridata;                 
207        /** Error information for the output trace */
208        libtrace_err_t err;
209        /** Boolean flag indicating whether the trace has been started */
210        bool started;                   
[1fc2f6a]211};
212
[8488c15]213/** Sets the error status on an input trace
214 *
215 * @param trace         The input trace to set the error status for
216 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
217 * @param msg           A message to print when reporting the error
218 */
[e1868fb]219void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...) 
[8488c15]220
[e1868fb]221                                                                PRINTF(3,4);
[8488c15]222/** Sets the error status on an output trace
223 *
224 * @param trace         The output trace to set the error status for
225 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
226 * @param msg           A message to print when reporting the error
227 */
[e1868fb]228void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...)
229                                                                PRINTF(3,4);
[1fc2f6a]230
[9cc1266]231/** Clears the cached values for a libtrace packet
232 *
233 * @param packet        The libtrace packet that requires a cache reset
234 */
235void trace_clear_cache(libtrace_packet_t *packet);
[f0fb38f]236
[8488c15]237/** Converts the data provided in buffer into a valid libtrace packet
238 *
239 * @param trace         An input trace of the same format as the "packet"
240 *                      contained in the buffer
241 * @param packet        The libtrace packet to prepare
242 * @param buffer        A buffer containing the packet data, including the
243 *                      capture format header
244 * @param rt_type       The RT type for the packet that is being prepared
245 * @param flags         Used to specify options for the preparation function,
246 *                      e.g. who owns the packet buffer
247 *
248 * @return -1 if an error occurs, 0 otherwise
249 *
250 * Packet preparation is a tricky concept - the idea is to take the data
251 * pointed to by 'buffer' and treat it as a packet record of the same capture
252 * format as that used by the input trace. The provided libtrace packet then
253 * has its internal pointers and values set to describe the packet record in
254 * the buffer.
255 *
256 * The primary use of this function is to allow the RT packet reader to
257 * easily and safely convert packets from the RT format back into the format
258 * that they were originally captured with., essentially removing the RT
259 * encapsulation.
260 *
261 * We've decided not to make this function available via the exported API
262 * because there are several issues that can arise if it is not used very
263 * carefully and it is not very useful outside of internal contexts anyway.
[f0fb38f]264 */
265int trace_prepare_packet(libtrace_t *trace, libtrace_packet_t *packet,
266                void *buffer, libtrace_rt_types_t rt_type, uint32_t flags);
267
[8488c15]268/** Flags for prepare_packet functions */
[590fb30]269enum {
[8488c15]270        /** The buffer memory has been allocated by libtrace and should be
271         * freed when the packet is destroyed. */
[590fb30]272        TRACE_PREP_OWN_BUFFER           =1,
[8488c15]273       
274        /** The buffer memory is externally-owned and must not be freed by
275         * libtrace when the packet is destroyed. */
[590fb30]276        TRACE_PREP_DO_NOT_OWN_BUFFER    =0
277};
278
[1c1e4a2]279
[4dedc28]280#ifndef PF_RULESET_NAME_SIZE
281#define PF_RULESET_NAME_SIZE 16
282#endif
283
284#ifndef IFNAMSIZ
285#define IFNAMSIZ 16
286#endif
287
[8488c15]288
289/** A local definition of a PFLOG header */
[67a14d4]290typedef struct libtrace_pflog_header_t {
[8488c15]291        uint8_t    length;     
[4dedc28]292        sa_family_t   af;
293        uint8_t    action;
294        uint8_t    reason;
295        char       ifname[IFNAMSIZ];
296        char       ruleset[PF_RULESET_NAME_SIZE];
297        uint32_t   rulenr;
298        uint32_t   subrulenr;
299        uint8_t    dir;
300        uint8_t    pad[3];
[25024fd]301} PACKED libtrace_pflog_header_t;
[4dedc28]302
[d5879cc]303
304
[8488c15]305/** A libtrace capture format module */
306/* All functions should return -1, or NULL on failure */
[9e2a109]307struct libtrace_format_t {
[8488c15]308        /** The name of this module, used in the libtrace URI to identify the
309         * capture format */
[4746c71]310        const char *name;
[8488c15]311        /** The version of this module */
[4746c71]312        const char *version;
[8488c15]313        /** The RT protocol type of this module */
[6dbc47a]314        enum base_format_t type;
[3c26e2a]315
316
[8488c15]317        /** Given a filename, return if this is the most likely capture format
318         * (used for devices). Used to "guess" the capture format when the
319         * URI is not fully specified.
320         *
321         * @param fname         The name of the device or file to examine
322         * @return 1 if the name matches the capture format, 0 otherwise
[91b72d3]323         */
324        int (*probe_filename)(const char *fname);
[8488c15]325       
326        /** Given a file, looks at the start of the file to determine if this
327         * is the capture format. Used to "guess" the capture format when the
328         * URI is not fully specified.
329         *
330         * @param io            An open libtrace IO reader for the file to check
331         * @return 1 if the file matches the capture format, 0 otherwise
332         */
[91b72d3]333        int (*probe_magic)(io_t *io);
[8488c15]334
335        /** Initialises an input trace using the capture format.
336         *
337         * @param libtrace      The input trace to be initialised
338         * @return 0 if successful, -1 in the event of error
339         */
[1fbd938]340        int (*init_input)(libtrace_t *libtrace);
[8488c15]341       
342        /** Applies a configuration option to an input trace.
343         *
344         * @param libtrace      The input trace to apply the option to
345         * @param option        The option that is being configured
346         * @param value         A pointer to the value that the option is to be
347         *                      set to
348         * @return 0 if successful, -1 if the option is unsupported or an error
349         * occurs
350         */
[1fbd938]351        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
[8488c15]352        /** Starts or unpauses an input trace - note that this function is
353         * often the one that opens the file or device for reading.
354         *
355         * @param libtrace      The input trace to be started or unpaused
356         * @return 0 if successful, -1 in the event of error */
[1fbd938]357        int (*start_input)(libtrace_t *libtrace);
[8488c15]358
359        /** Pauses an input trace - this function should close or detach the
360         * file or device that is being read from.
361         *
362         * @param libtrace      The input trace to be paused
363         * @return 0 if successful, -1 in the event of error
364         */
[1fbd938]365        int (*pause_input)(libtrace_t *libtrace);
[8488c15]366
367        /** Initialises an output trace using the capture format.
368         *
369         * @param libtrace      The output trace to be initialised
370         * @return 0 if successful, -1 in the event of error
371         */
[1fbd938]372        int (*init_output)(libtrace_out_t *libtrace);
[8488c15]373       
374        /** Applies a configuration option to an output trace.
375         *
376         * @param libtrace      The output trace to apply the option to
377         * @param option        The option that is being configured
378         * @param value         A pointer to the value that the option is to be
379         *                      set to
380         * @return 0 if successful, -1 if the option is unsupported or an error
381         * occurs
382         * */
383        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value);
384
385        /** Starts an output trace - note that this function is often the one
386         * that opens the file or device for writing.
387         *
388         * @param libtrace      The output trace to be started
389         * @return 0 if successful, -1 if an error occurs
390         *
391         * There is no pause for output traces, as writing is not performed
392         * asynchronously.
[9de8150]393         */
[1fbd938]394        int (*start_output)(libtrace_out_t *libtrace);
[8488c15]395
396        /** Concludes an input trace and cleans up the capture format data.
397         *
398         * @param libtrace      The input trace to be concluded
399         * @return 0 if successful, -1 if an error occurs
400         *
401         * Libtrace will call the pause_input function if the input trace is
402         * currently active prior to calling this function.
[ab4cb04]403         */
[1fbd938]404        int (*fin_input)(libtrace_t *libtrace);
[8488c15]405
406        /** Concludes an output trace and cleans up the capture format data.
407         *
408         * @param libtrace      The output trace to be concluded
409         * @return 0 if successful, -1 if an error occurs
410         */
[1fbd938]411        int (*fin_output)(libtrace_out_t *libtrace);
[8488c15]412
413        /** Reads the next packet from an input trace into the provided packet
414         * structure.
415         *
416         * @param libtrace      The input trace to read from
417         * @param packet        The libtrace packet to read into
418         * @return The size of the packet read (in bytes) including the capture
419         * framing header, or -1 if an error occurs. 0 is returned in the
420         * event of an EOF.
421         *
422         * If no packets are available for reading, this function should block
423         * until one appears or return 0 if the end of a trace file has been
424         * reached.
[9de8150]425         */
[97e39a7]426        int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet);
[8488c15]427       
428        /** Converts a buffer containing a packet record into a libtrace packet
429         *
430         * @param libtrace      An input trace in the capture format for the
431         *                      packet
432         * @param packet        A libtrace packet to put the prepared packet
433         *                      into
434         * @param buffer        The buffer containing the packet record
435         *                      (including the capture format header)
436         * @param rt_type       The RT type for the packet
437         * @param flags         Flags describing properties that should be
438         *                      applied to the new packet
439         * @return 0 if successful, -1 if an error occurs.
440         *
441         * Updates internal trace and packet details, such as payload pointers,
442         * loss counters and packet types to match the packet record provided
443         * in the buffer. This is a zero-copy function.
444         *
[f0fb38f]445         * Intended (at this stage) only for internal use, particularly by
446         * RT which needs to decapsulate RT packets */
447        int (*prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet,
448                        void *buffer, libtrace_rt_types_t rt_type, 
449                        uint32_t flags);
[8488c15]450       
451        /** Frees any resources allocated by the capture format module for a
452         * libtrace packet.
453         *
454         * @param The packet to be finalised
455         *       */
[eeab9832]456        void (*fin_packet)(libtrace_packet_t *packet);
[8488c15]457
458        /** Write a libtrace packet to an output trace.
459         *
460         * @param libtrace      The output trace to write the packet to
461         * @param packet        The packet to be written out
462         * @return The number of bytes written, or -1 if an error occurs
[9de8150]463         */
[3a169d7]464        int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet);
[8488c15]465        /** Returns the libtrace link type for a packet.
466         *
467         * @param packet        The packet to get the link type for
468         * @return The libtrace link type, or -1 if this link type is unknown
[9de8150]469         */ 
[1fbd938]470        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
[8488c15]471
472        /** Returns the direction of a packet.
473         *
474         * @param packet        The packet to get the direction for
475         * @return The direction of the packet, or -1 if no direction tag is
476         * present or an error occurs
[9de8150]477         */ 
[431548c5]478        libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet);
[8488c15]479       
480        /** Sets the direction of a packet.
481         *
482         * @param packet        The packet to set the direction for
483         * @param direction     The direction to assign to the packet
484         * @return The updated direction for the packet, or -1 if an error
485         * occurs
486         *
487         * @note Some capture formats do not feature direction tagging, so it
488         * will not make sense to implement a set_direction function for them.
[9de8150]489         */ 
[431548c5]490        libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction);
[8488c15]491       
492        /** Returns the timestamp for a packet in the ERF timestamp format.
493         *
494         * @param packet        The packet to get the timestamp from
495         * @return The 64-bit ERF timestamp
496         *
497         * @note Each format must implement at least one of the four "get
498         * timestamp" functions.
499         *
500         * If not implemented, libtrace will convert the result of one of the
501         * other timestamp functions into the appropriate format instead.
502         * This means each capture format only needs to implement the most
503         * sensible of the four and let libtrace handle any conversions.
504         *
[9de8150]505         */
[1fbd938]506        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
[8488c15]507
508        /** Returns the timestamp for a packet in the timeval format
509         *
510         * @param packet        The packet to get the timestamp from
511         * @return The timestamp from the packet as a timeval
512         *
513         * @note Each format must implement at least one of the four "get
514         * timestamp" functions.
515         *
516         * If not implemented, libtrace will convert the result of one of the
517         * other timestamp functions into the appropriate format instead.
518         * This means each capture format only needs to implement the most
519         * sensible of the four and let libtrace handle any conversions.
[9de8150]520         */
[1fbd938]521        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
[8488c15]522       
523        /** Returns the timestamp for a packet in the timespec format.
524         *
525         * @param packet        The packet to get the timestamp from
526         * @return The timestamp from the packet as a timespec
527         *
528         * @note Each format must implement at least one of the four "get
529         * timestamp" functions.
530         *
531         * If not implemented, libtrace will convert the result of one of the
532         * other timestamp functions into the appropriate format instead.
533         * This means each capture format only needs to implement the most
534         * sensible of the four and let libtrace handle any conversions.
[1aa4bf7]535         */
536        struct timespec (*get_timespec)(const libtrace_packet_t *packet);
[8488c15]537       
538        /** Returns the timestamp for a packet in floating point seconds.
539         *
540         * @param packet        The packet to get the timestamp from
541         * @return The timestamp from the packet as a floating point number of
542         * seconds since 1970-01-01 00:00:00 UTC
543         *
544         * @note Each format must implement at least one of the four "get
545         * timestamp" functions.
546         *
547         * If not implemented, libtrace will convert the result of one of the
548         * other timestamp functions into the appropriate format instead.
549         * This means each capture format only needs to implement the most
550         * sensible of the four and let libtrace handle any conversions.
[9de8150]551         */
[1fbd938]552        double (*get_seconds)(const libtrace_packet_t *packet);
[8488c15]553       
554        /** Moves the read pointer to a certain ERF timestamp within an input
555         * trace file.
556         *
557         * @param trace         The input trace to seek within
558         * @param timestamp     The timestamp to seek to, as an ERF timestamp
559         *
[9de8150]560         * @return 0 on success, -1 on failure.
[8488c15]561         *
562         * The next packet read from this trace will now be the first packet
563         * to have a timestamp equal to or greater than the provided timestamp.
564         *
565         * @note Each format that supports seeking must implement at least one
566         * of the seek functions.
567         *
568         * If not implemented, libtrace will convert the timestamp into the
569         * appropriate format to use a seek function that has been implemented.
570         * This means each capture format only needs to implement the seek
571         * function that matches the native timestamp format for that capture.
572         *
[9de8150]573         */
[1fbd938]574        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
[8488c15]575        /** Moves the read pointer to a certain timestamp represented using a
576         * timeval within an input trace file.
577         *
578         * @param trace         The input trace to seek within
579         * @param timestamp     The timestamp to seek to, as a timeval
580         *
[9de8150]581         * @return 0 on success, -1 on failure.
[8488c15]582         *
583         * The next packet read from this trace will now be the first packet
584         * to have a timestamp equal to or greater than the provided timestamp.
585         *
586         * @note Each format that supports seeking must implement at least one
587         * of the seek functions.
588         *
589         * If not implemented, libtrace will convert the timestamp into the
590         * appropriate format to use a seek function that has been implemented.
591         * This means each capture format only needs to implement the seek
592         * function that matches the native timestamp format for that capture.
593         *
[9de8150]594         */
[1fbd938]595        int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
[8488c15]596       
597        /** Moves the read pointer to a certain timestamp represented using
598         * floating point seconds within an input trace file.
599         *
600         * @param trace         The input trace to seek within
601         * @param timestamp     The timestamp to seek to, as floating point
602         *                      seconds since 1970-01-01 00:00:00 UTC
603         *
[9de8150]604         * @return 0 on success, -1 on failure.
[8488c15]605         *
606         * The next packet read from this trace will now be the first packet
607         * to have a timestamp equal to or greater than the provided timestamp.
608         *
609         * @note Each format that supports seeking must implement at least one
610         * of the seek functions.
611         *
612         * If not implemented, libtrace will convert the timestamp into the
613         * appropriate format to use a seek function that has been implemented.
614         * This means each capture format only needs to implement the seek
615         * function that matches the native timestamp format for that capture.
616         *
[9de8150]617         */
[1fbd938]618        int (*seek_seconds)(libtrace_t *trace, double seconds);
[8488c15]619       
620        /** Returns the payload length of the captured packet record.
621         *
622         * @param packet        The packet to get the capture length from
623         * @return The capture length for the packet, or -1 if an error occurs
624         *
625         * Capture length is the current size of the packet record itself,
626         * following any truncation that may have occurred during the capture
627         * process. This length does not include the capture format framing
628         * header.
[9de8150]629         */
[1fbd938]630        int (*get_capture_length)(const libtrace_packet_t *packet);
[8488c15]631
632        /** Returns the original length of the packet as it was on the wire.
633         *
634         * @param packet        The packet to get the wire length from
635         * @return The length of the packet on the wire at the time of capture,
636         * or -1 if an error occurs
637         *
638         * Wire length is the original size of the packet prior to any
639         * truncation that may have occurred as part of the capture process.
640         * This length does not include the capture format framing header.
[9de8150]641         */
[1fbd938]642        int (*get_wire_length)(const libtrace_packet_t *packet);
[8488c15]643       
644        /** Returns the length of the capture format framing header
645         *
646         * @param packet        The packet to get the framing length from
647         * @return The length of the framing header, or -1 if an error occurs
648         *
649         * The framing header is the extra metadata that the capture process
650         * records about a packet.  The framing length does not include any
651         * of the packet payload itself. The total size of the packet record
652         * can be calculated be adding this value with the capture length.
[9de8150]653         */
[1fbd938]654        int (*get_framing_length)(const libtrace_packet_t *packet);
[8488c15]655
656        /** Sets the capture length for a packet.
657         *
658         * @param packet        The packet to adjust the capture length for.
659         * @param size          The new capture length
660         * @return The new capture length of the packet, or -1 if an error
661         * occurs
662         *
663         * @note This function should only reduce the capture length. If the
664         * provided length is larger than the current capture length, -1 should
665         * be returned.
[9de8150]666         */
[c95b923]667        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
[8488c15]668        /** Returns the number of packets observed by an input trace.
669         *
670         * @param trace         The input trace to get the packet count for
671         * @return The number of packets observed by an input trace, or
672         * UINT64_MAX if the number is unknown
673         *
674         * This count includes packets that have been filtered and dropped.
[f2fae49]675         */
[50bbce8]676        uint64_t (*get_received_packets)(libtrace_t *trace);
[8488c15]677
678        /** Returns the number of packets filtered by an input trace.
679         *
680         * @param trace         The input trace to get the filtered count for
681         * @return The number of packets filtered by the input trace, or
682         * UINT64_MAX if the number is unknown
683         *
[f2fae49]684         */
[50bbce8]685        uint64_t (*get_filtered_packets)(libtrace_t *trace);
[8488c15]686       
687        /** Returns the number of packets dropped by an input trace.
688         *
689         * @param trace         The input trace to get the dropped count for
690         * @return The number of packets dropped by the input trace, or
691         * UINT64_MAX if the number is unknown
692         *
693         */
[50bbce8]694        uint64_t (*get_dropped_packets)(libtrace_t *trace);
[8488c15]695       
696        /** Returns the number of packets captured and returned by an input
697         * trace.
698         *
699         * @param trace         The input trace to get the capture count for
700         * @return The number of packets returned to the libtrace user, or
701         * UINT64_MAX if the number is unknown
702         *
703         * This is the number of packets that have been successfully returned
704         * to the libtrace user via the read_packet() function.
705         *
[f2fae49]706         */
[50bbce8]707        uint64_t (*get_captured_packets)(libtrace_t *trace);
[8488c15]708       
709        /** Returns the file descriptor used by the input trace.
710         *
711         * @param trace         The input trace to get the file descriptor for
712         * @return The file descriptor used by the input trace to read packets
713         *
[9de8150]714         */
[52f8fc2]715        int (*get_fd)(const libtrace_t *trace);
[8488c15]716       
717        /** Returns the next libtrace event for the input trace.
718         *
719         * @param trace         The input trace to get the next event from
720         * @param packet        A libtrace packet to read a packet into
721         * @return A libtrace event describing the event that occured
722         *
723         * The event API allows for non-blocking reading of packets from an
724         * input trace. If a packet is available and ready to be read, a packet
725         * event should be returned. Otherwise a sleep or fd event should be
726         * returned to indicate that the caller needs to wait. If the input
727         * trace has an error or reaches EOF, a terminate event should be
728         * returned.
[9de8150]729         */
[1fbd938]730        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
[8488c15]731
732        /** Prints some useful help information to standard output. */
[33d83d4]733        void (*help)(void);
[8488c15]734
735        /** Next pointer, should always be NULL - used by the format module
736         * manager. */
[eeab9832]737        struct libtrace_format_t *next;
[4dedc28]738};
739
[8488c15]740/** The list of registered capture formats */
[c0506ea]741//extern struct libtrace_format_t *form;
742
743/** Specifies whether any blocking packet readers should cease reading
744 * immediately
745 */
746extern int libtrace_halt;
[4dedc28]747
[8488c15]748/** Registers a new capture format module.
749 *
750 * @param format        The format module to be registered
751 */
[9e2a109]752void register_format(struct libtrace_format_t *format);
[7068467]753
[8488c15]754/** Converts a PCAP DLT into a libtrace link type.
755 *
756 * @param linktype      The PCAP DLT to be converted
757 * @return The libtrace link type that is equivalent to the provided DLT, or
758 * -1 if the DLT is unknown
759 */
[4c00a35]760libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype);
[8488c15]761
762/** Converts a PCAP DLT into an RT protocol type.
763 *
764 * @param linktype      The PCAP DLT to be converted
765 * @return The RT type that is equivalent to the provided DLT
766 */
[ce0bf2c]767libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype);
[8488c15]768
769/** Converts a libtrace link type into a PCAP linktype.
770 *
771 * @param type          The libtrace link type to be converted
772 * @return The PCAP linktype that is equivalent to the provided libtrace link
773 * type, or -1 if the link type is unknown
774 */
[4c00a35]775libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type);
[8488c15]776
777/** Converts a libtrace link type into a PCAP DLT.
778 *
779 * @param type          The libtrace link type to be converted
780 * @return The PCAP DLT that is equivalent to the provided libtrace link
781 * type, or -1 if the link type is unknown
782 */
[4c00a35]783libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type);
[8488c15]784
785/** Converts an RT protocol type into a PCAP DLT.
786 *
787 * @param rt_type       The RT type to be converted
788 * @return The PCAP DLT that is equivalent to the provided RT protocol
789 */
[4c00a35]790libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type);
[8488c15]791
[f00c146]792/** Converts a PCAP DLT into an RT protocol type for the BPF format.
793 *
794 * @param linktype      The PCAP DLT to be converted
795 * @return The RT type that is equivalent to the provided DLT for BPF
796 */
797libtrace_rt_types_t bpf_linktype_to_rt(libtrace_dlt_t linktype);
798
[8488c15]799/** Converts an ERF type into a libtrace link type.
800 *
801 * @param erf           The ERF type to be converted
802 * @return The libtrace link type that is equivalent to the provided ERF type,
803 * or -1 if the ERF type is unknown
804 */
[4bd8a5b]805libtrace_linktype_t erf_type_to_libtrace(uint8_t erf);
[8488c15]806
807/** Converts a libtrace link type into an ERF type.
808 *
809 * @param linktype      The libtrace link type to be converted
810 * @return The ERF type that is equivalent to the provided libtrace link type,
811 * or -1 if the link type cannot be matched to an ERF type.
812 */
[4bd8a5b]813uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype);
[7068467]814
[8488c15]815/** Converts an ARPHRD type into a libtrace link type.
816 *
817 * @param arphrd        The ARPHRD type to be converted
818 * @return The libtrace link type that is equivalent to the provided ARPHRD
819 * type, or -1 if the ARPHRD type is unknown
820 */
821libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd);
822
823/** Converts a libtrace link type into an ARPHRD type.
824 *
825 * @param type          The libtrace link type to be converted
826 * @return The ARPHRD type that is equivalent to the provided libtrace link
827 * type, or -1 if the link type cannot be matched to an ARPHRD type
828 */
829unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type);
830
831/** Converts a libtrace packet to the Linux SLL type.
832 *
833 * @param packet        The packet to be promoted
834 *
835 * @note This will involve memcpy() so use sparingly.
836 *
837 * This function prepends a Linux SLL header to a packet so that we can store
838 * direction tagging information.
839 */
[81f9b6e]840void promote_packet(libtrace_packet_t *packet);
[8488c15]841
842/** Attempts to demote a packet by removing the first header.
843 *
844 * @param packet        The packet to be demoted
845 * @return True if the packet was demoted, false otherwise.
846 *
847 * Essentially the opposite of promote_packet, except that it will also remove
848 * an ATM header as well as Linux SLL.
849 *
850 */
[0ff6ddf]851bool demote_packet(libtrace_packet_t *packet);
[81f9b6e]852
[8488c15]853/** Returns a pointer to the header following a Linux SLL header.
854 *
855 * @param link          A pointer to the Linux SLL header to be skipped
[9cc1266]856 * @param[out] arphrd_type      The arp hardware type of the packet
857 * @param[out] next_header      The ethertype of the next header
[8488c15]858 * @param[in,out] remaining     Updated with the number of captured bytes
859 *                              remaining
860 * @return A pointer to the header following the Linux SLL header, or NULL if
861 * no subsequent header is present.
862 *
863 * Remaining must point to the number of bytes captured from the Linux SLL
864 * header and beyond.  It will be decremented by the number of bytes skipped
865 * to find the payload.
866 *
867 * If the Linux SLL header is complete but there are zero bytes of payload
868 * after the end of the header, a pointer to where the payload would be is
869 * returned and remaining will be set to zero. If the Linux SLL header is
870 * incomplete (truncated), then NULL is returned and remaining will be set to
871 * 0. Therefore, it is very important to check the value of remaining after
872 * calling this function.
873 */     
[9cc1266]874void *trace_get_payload_from_linux_sll(const void *link,
875                uint16_t *arphrd_type, 
876                uint16_t *next_header, 
[8488c15]877                uint32_t *remaining);
878
879/** Returns a pointer to the header following an ATM header.
880 *
881 * @param link          A pointer to the ATM header to be skipped
882 * @param[out] type     The ethertype of the next header
883 * @param[in,out] remaining     Updated with the number of captured bytes
884 *                              remaining
885 * @return A pointer to the header following the ATM header, or NULL if
886 * no subsequent header is present.
887 *
888 * Remaining must point to the number of bytes captured from the ATM header
889 * and beyond.  It will be decremented by the number of bytes skipped to find
890 * the payload.
891 *
892 * If the ATM header is complete but there are zero bytes of payload
893 * after the end of the header, a pointer to where the payload would be is
894 * returned and remaining will be set to zero. If the ATM header is
895 * incomplete (truncated), then NULL is returned and remaining will be set to
896 * 0. Therefore, it is very important to check the value of remaining after
897 * calling this function.
898 */     
899DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type, 
900                uint32_t *remaining);
[94af885]901
[8488c15]902/** Byteswaps a 64-bit value.
903 *
904 * @param num           The value to be byteswapped.
905 * @return The byteswapped 64-bit number
906 *
907 */
[94af885]908uint64_t byteswap64(uint64_t num);
[8488c15]909
910/** Byteswaps a 32-bit value.
911 *
912 * @param num           The value to be byteswapped.
913 * @return The byteswapped 32-bit number
914 *
915 */
[94af885]916uint32_t byteswap32(uint32_t num);
[8488c15]917
918/** Byteswaps a 16-bit value.
919 *
920 * @param num           The value to be byteswapped.
921 * @return The byteswapped 16-bit number
922 *
923 */
[94af885]924uint16_t byteswap16(uint16_t num);
925
[8488c15]926/** @name Byte ordering
927 * Macros that define how to convert a value into a particular byte-order
928 *
929 * @{
[94af885]930 */
[3799f51]931#if __BYTE_ORDER == __BIG_ENDIAN
[94af885]932#define bswap_host_to_be64(num) ((uint64_t)(num))
933#define bswap_host_to_le64(num) byteswap64(num)
934#define bswap_host_to_be32(num) ((uint32_t)(num))
935#define bswap_host_to_le32(num) byteswap32(num)
936#define bswap_host_to_be16(num) ((uint16_t)(num))
937#define bswap_host_to_le16(num) byteswap16(num)
938
939#define bswap_be_to_host64(num) ((uint64_t)(num))
940#define bswap_le_to_host64(num) byteswap64(num)
941#define bswap_be_to_host32(num) ((uint32_t)(num))
942#define bswap_le_to_host32(num) byteswap32(num)
943#define bswap_be_to_host16(num) ((uint16_t)(num))
944#define bswap_le_to_host16(num) byteswap16(num)
945
946/* We use ntoh*() here, because the compiler may
947 * attempt to optimise it
948 */
[3799f51]949#elif __BYTE_ORDER == __LITTLE_ENDIAN
[94af885]950#define bswap_host_to_be64(num) (byteswap64(num))
951#define bswap_host_to_le64(num) ((uint64_t)(num))
952#define bswap_host_to_be32(num) (htonl(num))
953#define bswap_host_to_le32(num) ((uint32_t)(num))
954#define bswap_host_to_be16(num) (htons(num))
955#define bswap_host_to_le16(num) ((uint16_t)(num))
956
957#define bswap_be_to_host64(num) (byteswap64(num))
958#define bswap_le_to_host64(num) ((uint64_t)(num))
959#define bswap_be_to_host32(num) (ntohl(num))
960#define bswap_le_to_host32(num) ((uint32_t)(num))
961#define bswap_be_to_host16(num) (ntohs(num))
962#define bswap_le_to_host16(num) ((uint16_t)(num))
963
964#else
965#error "Unknown byte order"
966#endif
[8488c15]967/** @} */
[94af885]968
[e5c2bc4]969#ifdef HAVE_BPF
[df338b3]970/* A type encapsulating a bpf filter
971 * This type covers the compiled bpf filter, as well as the original filter
972 * string
973 *
974 */
[8488c15]975
976/** Internal representation of a BPF filter */
[df338b3]977struct libtrace_filter_t {
[8488c15]978        struct bpf_program filter;      /**< The BPF program itself */
979        char * filterstring;            /**< The filter string */
980        int flag;                       /**< Indicates if the filter is valid */
[31a15db]981        struct bpf_jit_t *jitfilter;
[df338b3]982};
[e5c2bc4]983#else
[8488c15]984/** BPF not supported by this system, but we still need to define a structure
985 * for the filter */
[e5c2bc4]986struct libtrace_filter_t {};
[df338b3]987#endif
[45dfddc]988
[8488c15]989/** Local definition of a PCAP header */
[45dfddc]990typedef struct libtrace_pcapfile_pkt_hdr_t {
[8488c15]991        uint32_t ts_sec;        /* Seconds portion of the timestamp */
992        uint32_t ts_usec;       /* Microseconds portion of the timestamp */
993        uint32_t caplen;        /* Capture length of the packet */
994        uint32_t wirelen;       /* The wire length of the packet */
[45dfddc]995} libtrace_pcapfile_pkt_hdr_t;
996
[5d56d34]997#ifdef HAVE_DAG
[8488c15]998/** Constructor for the DAG format module */
[5d56d34]999void dag_constructor(void);
1000#endif
[8488c15]1001/** Constructor for the ERF format module */
[cab58c5]1002void erf_constructor(void);
[8488c15]1003/** Constructor for the TSH format module */
[e01a738]1004void tsh_constructor(void);
[8488c15]1005/** Constructor for the Legacy DAG format module */
[cab58c5]1006void legacy_constructor(void);
[8488c15]1007/** Constructor for the Linux Native format module */
[cab58c5]1008void linuxnative_constructor(void);
[8488c15]1009/** Constructor for the PCAP format module */
[cab58c5]1010void pcap_constructor(void);
[8488c15]1011/** Constructor for the PCAP File format module */
[cab58c5]1012void pcapfile_constructor(void);
[8488c15]1013/** Constructor for the RT format module */
[cab58c5]1014void rt_constructor(void);
[8488c15]1015/** Constructor for the DUCK format module */
[cab58c5]1016void duck_constructor(void);
[8488c15]1017/** Constructor for the ATM Header format module */
[e1fdc05]1018void atmhdr_constructor(void);
[3512119]1019#ifdef HAVE_BPF
[8488c15]1020/** Constructor for the BPF format module */
[3512119]1021void bpf_constructor(void);
1022#endif
[c04929c]1023#if HAVE_DPDK
1024/** Constructor for Intels DPDK format module */
1025void dpdk_constructor(void);
1026#endif
[cab58c5]1027
[8488c15]1028/** Extracts the RadioTap flags from a wireless link header
1029 *
1030 * @param link          A pointer to the wireless link header
1031 * @param linktype      The link type of the wireless header
1032 * @param[out] flags    Space to store the extracted flags
1033 * @return True if libtrace was able to extract flags from the link header,
1034 * false otherwise.
1035 *
1036 * This function has been left internal because it is not portable across
1037 * drivers.
1038 */
[f0c639b]1039bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags);
1040#define TRACE_RADIOTAP_F_FCS 0x10
[4dedc28]1041       
1042#ifdef __cplusplus
1043}
1044#endif
1045
[7068467]1046#endif /* LIBTRACE_INT_H */
Note: See TracBrowser for help on using the repository browser.