source: lib/libtrace_int.h @ 60e8e86

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 60e8e86 was d6a56b6, checked in by Richard Sanger <rsangerarj@…>, 8 years ago

Move the data structures out of the way and into there own folder and tidy file naming.

  • Property mode set to 100644
File size: 39.6 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
7 * Authors: Daniel Lawson
8 *          Perry Lorier
9 *          Shane Alcock
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
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 */
50#ifndef LIBTRACE_INT_H
51#define LIBTRACE_INT_H
52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57#include "config.h"
58#include "common.h"
59#include "libtrace.h"
60#include "wandio.h"
61#include "lt_bswap.h"
62
63#ifdef _MSC_VER
64// warning: deprecated function
65#pragma warning(disable:4996)
66// warning: benign redefinitions of types
67#pragma warning(disable:4142)
68#endif
69
70#ifdef HAVE_INTTYPES_H
71# include <inttypes.h>
72#else
73# include "lt_inttypes.h"
74#endif
75
76#ifdef HAVE_STDDEF_H
77# include <stddef.h>
78#else
79#ifndef WIN32
80# error "Can't find stddev.h -- do you define ptrdiff_t elsewhere?"
81#endif
82#endif
83
84
85#include "rt_protocol.h"
86       
87/* Prefer net/bpf.h over pcap-bpf.h for format_bpf.c on MacOS */
88#ifdef HAVE_NET_BPF_H
89#    include <net/bpf.h>
90#    define HAVE_BPF 1
91#else
92#ifdef HAVE_PCAP_BPF_H
93#  include <pcap-bpf.h>
94#  define HAVE_BPF 1
95#endif
96#endif
97
98#ifdef HAVE_PCAP_H
99#  include <pcap.h>
100#  ifdef HAVE_PCAP_INT_H
101#    include <pcap-int.h>
102#  endif
103#endif
104
105#ifdef HAVE_ZLIB_H
106#  include <zlib.h>
107#endif
108
109#ifndef HAVE_STRNDUP
110char *strndup(const char *s, size_t size);
111#endif
112
113#ifndef HAVE_STRNCASECMP
114# ifndef HAVE__STRNICMP
115/** A local implementation of strncasecmp (as some systems do not have it) */
116int strncasecmp(const char *str1, const char *str2, size_t n);
117# else
118# define strncasecmp _strnicmp
119# endif
120#endif
121
122#ifndef HAVE_SNPRINTF
123# ifndef HAVE_SPRINTF_S
124/** A local implementation of snprintf (as some systems do not have it) */
125int snprintf(char *str, size_t size, const char *format, ...);
126# else
127# define snprintf sprintf_s
128# endif
129#endif
130
131#include "daglegacy.h"
132       
133#ifdef HAVE_DAG_API
134#  include "dagnew.h"
135#  include "dagapi.h"
136#       if DAG_VERSION == 24
137#               include <erftypes.h>
138#       else
139#               include <daginf.h>
140#       endif
141#  include "erftypes.h"
142#else
143#  include "dagformat.h"
144#endif
145
146#ifdef HAVE_LLVM
147#include "bpf-jit/bpf-jit.h"
148#endif
149
150#include "data-struct/ring_buffer.h"
151#include "data-struct/vector.h"
152#include "data-struct/message_queue.h"
153#include "data-struct/deque.h"
154#include "data-struct/sliding_window.h"
155
156//#define RP_BUFSIZE 65536U
157
158/** Data about the most recent event from a trace file */
159struct libtrace_event_status_t {
160        /** A libtrace packet to store the packet when a PACKET event occurs */
161        libtrace_packet_t *packet;
162        /** Time between the timestamp for the current packet and the current
163         * walltime */
164        double tdelta;
165        /** The timestamp of the previous PACKET event */
166        double trace_last_ts;
167        /** The size of the current PACKET event */
168        int psize;
169        /** Whether there is a packet stored in *packet above waiting for an
170         * event to occur */
171        bool waiting;
172};
173
174enum thread_types {
175        THREAD_EMPTY,
176        THREAD_HASHER,
177        THREAD_MAPPER,
178        THREAD_REDUCER
179};
180
181enum thread_states {
182        THREAD_RUNNING,
183        THREAD_FINISHING,
184        THREAD_FINISHED,
185        THREAD_PAUSED
186};
187
188enum hasher_types {
189        HASHER_BALANCE, /** Balance load across CPUs best as possible this is basically to say don't care about hash, but this might still might be implemented using a hash or round robin etc.. */
190        HASHER_BIDIRECTIONAL, /** Use a hash which is uni-directional for TCP flows (IP src dest,TCP port src dest), non TCP
191                                                        Will be sent to the same place, with the exception of UDP which may or may not be sent to separate cores */
192        HASHER_UNIDIRECTIONAL, /** Use a hash which is uni-directional across TCP flow */
193        HASHER_CUSTOM, /** Always use the user supplied hasher */
194        HASHER_HARDWARE, /** Set by the format if the hashing is going to be done in hardware */
195};
196
197// Reduce expects sequential data
198#define REDUCE_SEQUENTIAL 0x1
199// Reduce is working on ordered data
200#define REDUCE_ORDERED 0x2
201// Reduce should sort the data
202#define REDUCE_SORT 0x4
203// Drop out of order valid with
204#define REDUCE_DROP_OOO 0x8
205// Reduce reads all queues with same key
206#define REDUCE_STEPPING 0x10
207
208#define MAPPER_USE_SLIDING_WINDOW 0x20
209
210/**
211 * Information of this thread
212 */
213typedef struct libtrace_thread_t {
214        libtrace_t * trace;
215        void* ret;
216        enum thread_types type;
217        enum thread_states state;
218        void* user_data; // TLS for the user to use
219        pthread_t tid;
220        int map_num; // A number from 0-X that represents this mapper number
221                                // in the table, intended to quickly identify this thread
222                                // -1 represents NA (such as in the case this is not a mapper thread)
223        libtrace_ringbuffer_t rbuffer; // Input
224        libtrace_vector_t vector; // Output
225        libtrace_queue_t deque; // Real Output type makes more sense
226        libtrace_message_queue_t messages; // Message handling
227        // Temp storage for time sensitive results
228        uint64_t tmp_key;
229        void *tmp_data;
230        pthread_spinlock_t tmp_spinlock;
231        // Set to true once the first packet has been stored
232        bool recorded_first;
233        // For thread safety reason we actually must store this here
234        int64_t tracetime_offset_usec;
235} libtrace_thread_t;
236
237/**
238 * Storage to note time value against each.
239 * Used both internally to do trace time playback
240 * and can be used externally to assist applications which need
241 * a trace starting time such as tracertstats.
242 */
243struct first_packets {
244        pthread_spinlock_t lock;
245        size_t count; // If == mappers we have all
246        size_t first; // Valid if count != 0
247        struct __packet_storage_magic_type {
248                libtrace_packet_t * packet;
249                struct timeval tv;
250        } * packets;
251};
252
253
254/** A libtrace input trace
255 * @internal
256 */
257struct libtrace_t {
258        /** The capture format for the input trace */
259        struct libtrace_format_t *format; 
260        /** Details of the most recent PACKET event reported by the trace */
261        struct libtrace_event_status_t event;
262        /** Pointer to the "global" data for the capture format module */       
263        void *format_data;             
264        /** A BPF filter to be applied to all packets read by the trace -
265         * used only if the capture format does not support filters natively */
266        struct libtrace_filter_t *filter; 
267        /** The snap length to be applied to all packets read by the trace -
268         * used only if the capture format does not support snapping natively */
269        size_t snaplen;                 
270        /** Count of the number of packets returned to the libtrace user */
271        uint64_t accepted_packets;     
272        /** Count of the number of packets filtered by libtrace */
273        uint64_t filtered_packets;     
274        /** The filename from the uri for the trace */
275        char *uridata;
276        /** The libtrace IO reader for this trace (if applicable) */
277        io_t *io;
278        /** Error information for the trace */
279        libtrace_err_t err;
280        /** Boolean flag indicating whether the trace has been started */
281        bool started;
282        /** Synchronise writes/reads across this format object and attached threads etc */
283        pthread_mutex_t libtrace_lock;
284       
285        /** Use to control pausing threads and finishing threads etc always used with libtrace_lock */
286        pthread_cond_t perpkt_cond;
287        /** Set to the number of mapper threads that are finishing (or have finished), or to -1 once all have been joined, 0 implies all are running */
288        int mappers_finishing;
289        /** A count of mappers that are pausing */
290        int perpkt_pausing;
291       
292        /** For the sliding window hasher implementation */
293        pthread_rwlock_t window_lock;
294        /** Set once trace_join has been called */
295        bool joined;
296        /** Set to indicate a mappers queue is full and such the writing mapper cannot proceed */
297        bool mapper_queue_full;
298        /** Global storage for this trace, shared among all the threads  */
299        void* global_blob;
300        /** Requested size of the pkt buffer (currently only used if using dedicated hasher thread) */
301        int packet_freelist_size;
302        /** The actual freelist */
303        libtrace_ringbuffer_t packet_freelist;
304        /** The number of packets that can queue per mapper thread - XXX consider deadlocks with non malloc()'d packets that need to be released */
305        int mapper_buffer_size;
306        /** The reducer flags */
307        int reducer_flags;
308        /** Used to track the next expected key */
309        uint64_t expected_key;
310        /** User defined per_pkt function called when a pkt is ready */
311        fn_per_pkt per_pkt;
312        /** User defined reducer function entry point XXX not hooked up */
313        fn_reducer reducer;
314        /** The hasher function */
315        enum hasher_types hasher_type;
316        /** The hasher function - NULL implies they don't care or balance */
317        fn_hasher hasher; // If valid using a separate thread
318        void *hasher_data;
319       
320        libtrace_thread_t hasher_thread;
321        libtrace_thread_t reducer_thread;
322        int mapper_thread_count;
323        libtrace_thread_t * mapper_threads; // All our mapper threads
324        libtrace_slidingwindow_t sliding_window;
325        sem_t sem;
326        // Used to keep track of the first packet seen on each thread
327        struct first_packets first_packets;
328        int tracetime;
329};
330
331inline void libtrace_zero_thread(libtrace_thread_t * t);
332inline void store_first_packet(libtrace_t *libtrace, libtrace_packet_t *packet, libtrace_thread_t *t);
333
334/** A libtrace output trace
335 * @internal
336 */
337struct libtrace_out_t {
338        /** The capture format for the output trace */
339        struct libtrace_format_t *format;
340        /** Pointer to the "global" data for the capture format module */
341        void *format_data;             
342        /** The filename for the uri for the output trace */
343        char *uridata;                 
344        /** Error information for the output trace */
345        libtrace_err_t err;
346        /** Boolean flag indicating whether the trace has been started */
347        bool started;
348};
349
350/** Sets the error status on an input trace
351 *
352 * @param trace         The input trace to set the error status for
353 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
354 * @param msg           A message to print when reporting the error
355 */
356void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...) 
357
358                                                                PRINTF(3,4);
359/** Sets the error status on an output trace
360 *
361 * @param trace         The output trace to set the error status for
362 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
363 * @param msg           A message to print when reporting the error
364 */
365void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...)
366                                                                PRINTF(3,4);
367
368/** Clears the cached values for a libtrace packet
369 *
370 * @param packet        The libtrace packet that requires a cache reset
371 */
372void trace_clear_cache(libtrace_packet_t *packet);
373
374/** Converts the data provided in buffer into a valid libtrace packet
375 *
376 * @param trace         An input trace of the same format as the "packet"
377 *                      contained in the buffer
378 * @param packet        The libtrace packet to prepare
379 * @param buffer        A buffer containing the packet data, including the
380 *                      capture format header
381 * @param rt_type       The RT type for the packet that is being prepared
382 * @param flags         Used to specify options for the preparation function,
383 *                      e.g. who owns the packet buffer
384 *
385 * @return -1 if an error occurs, 0 otherwise
386 *
387 * Packet preparation is a tricky concept - the idea is to take the data
388 * pointed to by 'buffer' and treat it as a packet record of the same capture
389 * format as that used by the input trace. The provided libtrace packet then
390 * has its internal pointers and values set to describe the packet record in
391 * the buffer.
392 *
393 * The primary use of this function is to allow the RT packet reader to
394 * easily and safely convert packets from the RT format back into the format
395 * that they were originally captured with., essentially removing the RT
396 * encapsulation.
397 *
398 * We've decided not to make this function available via the exported API
399 * because there are several issues that can arise if it is not used very
400 * carefully and it is not very useful outside of internal contexts anyway.
401 */
402int trace_prepare_packet(libtrace_t *trace, libtrace_packet_t *packet,
403                void *buffer, libtrace_rt_types_t rt_type, uint32_t flags);
404
405/** Flags for prepare_packet functions */
406enum {
407        /** The buffer memory has been allocated by libtrace and should be
408         * freed when the packet is destroyed. */
409        TRACE_PREP_OWN_BUFFER           =1,
410       
411        /** The buffer memory is externally-owned and must not be freed by
412         * libtrace when the packet is destroyed. */
413        TRACE_PREP_DO_NOT_OWN_BUFFER    =0
414};
415
416
417#ifndef PF_RULESET_NAME_SIZE
418#define PF_RULESET_NAME_SIZE 16
419#endif
420
421#ifndef IFNAMSIZ
422#define IFNAMSIZ 16
423#endif
424
425
426/** A local definition of a PFLOG header */
427typedef struct libtrace_pflog_header_t {
428        uint8_t    length;     
429        sa_family_t   af;
430        uint8_t    action;
431        uint8_t    reason;
432        char       ifname[IFNAMSIZ];
433        char       ruleset[PF_RULESET_NAME_SIZE];
434        uint32_t   rulenr;
435        uint32_t   subrulenr;
436        uint8_t    dir;
437        uint8_t    pad[3];
438} PACKED libtrace_pflog_header_t;
439
440
441
442/** A libtrace capture format module */
443/* All functions should return -1, or NULL on failure */
444struct libtrace_format_t {
445        /** The name of this module, used in the libtrace URI to identify the
446         * capture format */
447        const char *name;
448        /** The version of this module */
449        const char *version;
450        /** The RT protocol type of this module */
451        enum base_format_t type;
452
453
454        /** Given a filename, return if this is the most likely capture format
455         * (used for devices). Used to "guess" the capture format when the
456         * URI is not fully specified.
457         *
458         * @param fname         The name of the device or file to examine
459         * @return 1 if the name matches the capture format, 0 otherwise
460         */
461        int (*probe_filename)(const char *fname);
462       
463        /** Given a file, looks at the start of the file to determine if this
464         * is the capture format. Used to "guess" the capture format when the
465         * URI is not fully specified.
466         *
467         * @param io            An open libtrace IO reader for the file to check
468         * @return 1 if the file matches the capture format, 0 otherwise
469         */
470        int (*probe_magic)(io_t *io);
471
472        /** Initialises an input trace using the capture format.
473         *
474         * @param libtrace      The input trace to be initialised
475         * @return 0 if successful, -1 in the event of error
476         */
477        int (*init_input)(libtrace_t *libtrace);
478       
479        /** Applies a configuration option to an input trace.
480         *
481         * @param libtrace      The input trace to apply the option to
482         * @param option        The option that is being configured
483         * @param value         A pointer to the value that the option is to be
484         *                      set to
485         * @return 0 if successful, -1 if the option is unsupported or an error
486         * occurs
487         */
488        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
489        /** Starts or unpauses an input trace - note that this function is
490         * often the one that opens the file or device for reading.
491         *
492         * @param libtrace      The input trace to be started or unpaused
493         * @return 0 if successful, -1 in the event of error */
494        int (*start_input)(libtrace_t *libtrace);
495
496        /** Pauses an input trace - this function should close or detach the
497         * file or device that is being read from.
498         *
499         * @param libtrace      The input trace to be paused
500         * @return 0 if successful, -1 in the event of error
501         */
502        int (*pause_input)(libtrace_t *libtrace);
503
504        /** Initialises an output trace using the capture format.
505         *
506         * @param libtrace      The output trace to be initialised
507         * @return 0 if successful, -1 in the event of error
508         */
509        int (*init_output)(libtrace_out_t *libtrace);
510       
511        /** Applies a configuration option to an output trace.
512         *
513         * @param libtrace      The output trace to apply the option to
514         * @param option        The option that is being configured
515         * @param value         A pointer to the value that the option is to be
516         *                      set to
517         * @return 0 if successful, -1 if the option is unsupported or an error
518         * occurs
519         * */
520        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value);
521
522        /** Starts an output trace - note that this function is often the one
523         * that opens the file or device for writing.
524         *
525         * @param libtrace      The output trace to be started
526         * @return 0 if successful, -1 if an error occurs
527         *
528         * There is no pause for output traces, as writing is not performed
529         * asynchronously.
530         */
531        int (*start_output)(libtrace_out_t *libtrace);
532
533        /** Concludes an input trace and cleans up the capture format data.
534         *
535         * @param libtrace      The input trace to be concluded
536         * @return 0 if successful, -1 if an error occurs
537         *
538         * Libtrace will call the pause_input function if the input trace is
539         * currently active prior to calling this function.
540         */
541        int (*fin_input)(libtrace_t *libtrace);
542
543        /** Concludes an output trace and cleans up the capture format data.
544         *
545         * @param libtrace      The output trace to be concluded
546         * @return 0 if successful, -1 if an error occurs
547         */
548        int (*fin_output)(libtrace_out_t *libtrace);
549
550        /** Reads the next packet from an input trace into the provided packet
551         * structure.
552         *
553         * @param libtrace      The input trace to read from
554         * @param packet        The libtrace packet to read into
555         * @return The size of the packet read (in bytes) including the capture
556         * framing header, or -1 if an error occurs. 0 is returned in the
557         * event of an EOF.
558         *
559         * If no packets are available for reading, this function should block
560         * until one appears or return 0 if the end of a trace file has been
561         * reached.
562         */
563        int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet);
564       
565        /** Converts a buffer containing a packet record into a libtrace packet
566         *
567         * @param libtrace      An input trace in the capture format for the
568         *                      packet
569         * @param packet        A libtrace packet to put the prepared packet
570         *                      into
571         * @param buffer        The buffer containing the packet record
572         *                      (including the capture format header)
573         * @param rt_type       The RT type for the packet
574         * @param flags         Flags describing properties that should be
575         *                      applied to the new packet
576         * @return 0 if successful, -1 if an error occurs.
577         *
578         * Updates internal trace and packet details, such as payload pointers,
579         * loss counters and packet types to match the packet record provided
580         * in the buffer. This is a zero-copy function.
581         *
582         * Intended (at this stage) only for internal use, particularly by
583         * RT which needs to decapsulate RT packets */
584        int (*prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet,
585                        void *buffer, libtrace_rt_types_t rt_type, 
586                        uint32_t flags);
587       
588        /** Frees any resources allocated by the capture format module for a
589         * libtrace packet.
590         *
591         * @param The packet to be finalised
592         *       */
593        void (*fin_packet)(libtrace_packet_t *packet);
594
595        /** Write a libtrace packet to an output trace.
596         *
597         * @param libtrace      The output trace to write the packet to
598         * @param packet        The packet to be written out
599         * @return The number of bytes written, or -1 if an error occurs
600         */
601        int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet);
602        /** Returns the libtrace link type for a packet.
603         *
604         * @param packet        The packet to get the link type for
605         * @return The libtrace link type, or -1 if this link type is unknown
606         */ 
607        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
608
609        /** Returns the direction of a packet.
610         *
611         * @param packet        The packet to get the direction for
612         * @return The direction of the packet, or -1 if no direction tag is
613         * present or an error occurs
614         */ 
615        libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet);
616       
617        /** Sets the direction of a packet.
618         *
619         * @param packet        The packet to set the direction for
620         * @param direction     The direction to assign to the packet
621         * @return The updated direction for the packet, or -1 if an error
622         * occurs
623         *
624         * @note Some capture formats do not feature direction tagging, so it
625         * will not make sense to implement a set_direction function for them.
626         */ 
627        libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction);
628       
629        /** Returns the timestamp for a packet in the ERF timestamp format.
630         *
631         * @param packet        The packet to get the timestamp from
632         * @return The 64-bit ERF timestamp
633         *
634         * @note Each format must implement at least one of the four "get
635         * timestamp" functions.
636         *
637         * If not implemented, libtrace will convert the result of one of the
638         * other timestamp functions into the appropriate format instead.
639         * This means each capture format only needs to implement the most
640         * sensible of the four and let libtrace handle any conversions.
641         *
642         */
643        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
644
645        /** Returns the timestamp for a packet in the timeval format
646         *
647         * @param packet        The packet to get the timestamp from
648         * @return The timestamp from the packet as a timeval
649         *
650         * @note Each format must implement at least one of the four "get
651         * timestamp" functions.
652         *
653         * If not implemented, libtrace will convert the result of one of the
654         * other timestamp functions into the appropriate format instead.
655         * This means each capture format only needs to implement the most
656         * sensible of the four and let libtrace handle any conversions.
657         */
658        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
659       
660        /** Returns the timestamp for a packet in the timespec format.
661         *
662         * @param packet        The packet to get the timestamp from
663         * @return The timestamp from the packet as a timespec
664         *
665         * @note Each format must implement at least one of the four "get
666         * timestamp" functions.
667         *
668         * If not implemented, libtrace will convert the result of one of the
669         * other timestamp functions into the appropriate format instead.
670         * This means each capture format only needs to implement the most
671         * sensible of the four and let libtrace handle any conversions.
672         */
673        struct timespec (*get_timespec)(const libtrace_packet_t *packet);
674       
675        /** Returns the timestamp for a packet in floating point seconds.
676         *
677         * @param packet        The packet to get the timestamp from
678         * @return The timestamp from the packet as a floating point number of
679         * seconds since 1970-01-01 00:00:00 UTC
680         *
681         * @note Each format must implement at least one of the four "get
682         * timestamp" functions.
683         *
684         * If not implemented, libtrace will convert the result of one of the
685         * other timestamp functions into the appropriate format instead.
686         * This means each capture format only needs to implement the most
687         * sensible of the four and let libtrace handle any conversions.
688         */
689        double (*get_seconds)(const libtrace_packet_t *packet);
690       
691        /** Moves the read pointer to a certain ERF timestamp within an input
692         * trace file.
693         *
694         * @param trace         The input trace to seek within
695         * @param timestamp     The timestamp to seek to, as an ERF timestamp
696         *
697         * @return 0 on success, -1 on failure.
698         *
699         * The next packet read from this trace will now be the first packet
700         * to have a timestamp equal to or greater than the provided timestamp.
701         *
702         * @note Each format that supports seeking must implement at least one
703         * of the seek functions.
704         *
705         * If not implemented, libtrace will convert the timestamp into the
706         * appropriate format to use a seek function that has been implemented.
707         * This means each capture format only needs to implement the seek
708         * function that matches the native timestamp format for that capture.
709         *
710         */
711        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
712        /** Moves the read pointer to a certain timestamp represented using a
713         * timeval within an input trace file.
714         *
715         * @param trace         The input trace to seek within
716         * @param timestamp     The timestamp to seek to, as a timeval
717         *
718         * @return 0 on success, -1 on failure.
719         *
720         * The next packet read from this trace will now be the first packet
721         * to have a timestamp equal to or greater than the provided timestamp.
722         *
723         * @note Each format that supports seeking must implement at least one
724         * of the seek functions.
725         *
726         * If not implemented, libtrace will convert the timestamp into the
727         * appropriate format to use a seek function that has been implemented.
728         * This means each capture format only needs to implement the seek
729         * function that matches the native timestamp format for that capture.
730         *
731         */
732        int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
733       
734        /** Moves the read pointer to a certain timestamp represented using
735         * floating point seconds within an input trace file.
736         *
737         * @param trace         The input trace to seek within
738         * @param timestamp     The timestamp to seek to, as floating point
739         *                      seconds since 1970-01-01 00:00:00 UTC
740         *
741         * @return 0 on success, -1 on failure.
742         *
743         * The next packet read from this trace will now be the first packet
744         * to have a timestamp equal to or greater than the provided timestamp.
745         *
746         * @note Each format that supports seeking must implement at least one
747         * of the seek functions.
748         *
749         * If not implemented, libtrace will convert the timestamp into the
750         * appropriate format to use a seek function that has been implemented.
751         * This means each capture format only needs to implement the seek
752         * function that matches the native timestamp format for that capture.
753         *
754         */
755        int (*seek_seconds)(libtrace_t *trace, double seconds);
756       
757        /** Returns the payload length of the captured packet record.
758         *
759         * @param packet        The packet to get the capture length from
760         * @return The capture length for the packet, or -1 if an error occurs
761         *
762         * Capture length is the current size of the packet record itself,
763         * following any truncation that may have occurred during the capture
764         * process. This length does not include the capture format framing
765         * header.
766         */
767        int (*get_capture_length)(const libtrace_packet_t *packet);
768
769        /** Returns the original length of the packet as it was on the wire.
770         *
771         * @param packet        The packet to get the wire length from
772         * @return The length of the packet on the wire at the time of capture,
773         * or -1 if an error occurs
774         *
775         * Wire length is the original size of the packet prior to any
776         * truncation that may have occurred as part of the capture process.
777         * This length does not include the capture format framing header.
778         */
779        int (*get_wire_length)(const libtrace_packet_t *packet);
780       
781        /** Returns the length of the capture format framing header
782         *
783         * @param packet        The packet to get the framing length from
784         * @return The length of the framing header, or -1 if an error occurs
785         *
786         * The framing header is the extra metadata that the capture process
787         * records about a packet.  The framing length does not include any
788         * of the packet payload itself. The total size of the packet record
789         * can be calculated be adding this value with the capture length.
790         */
791        int (*get_framing_length)(const libtrace_packet_t *packet);
792
793        /** Sets the capture length for a packet.
794         *
795         * @param packet        The packet to adjust the capture length for.
796         * @param size          The new capture length
797         * @return The new capture length of the packet, or -1 if an error
798         * occurs
799         *
800         * @note This function should only reduce the capture length. If the
801         * provided length is larger than the current capture length, -1 should
802         * be returned.
803         */
804        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
805        /** Returns the number of packets observed by an input trace.
806         *
807         * @param trace         The input trace to get the packet count for
808         * @return The number of packets observed by an input trace, or
809         * UINT64_MAX if the number is unknown
810         *
811         * This count includes packets that have been filtered and dropped.
812         */
813        uint64_t (*get_received_packets)(libtrace_t *trace);
814
815        /** Returns the number of packets filtered by an input trace.
816         *
817         * @param trace         The input trace to get the filtered count for
818         * @return The number of packets filtered by the input trace, or
819         * UINT64_MAX if the number is unknown
820         *
821         */
822        uint64_t (*get_filtered_packets)(libtrace_t *trace);
823       
824        /** Returns the number of packets dropped by an input trace.
825         *
826         * @param trace         The input trace to get the dropped count for
827         * @return The number of packets dropped by the input trace, or
828         * UINT64_MAX if the number is unknown
829         *
830         */
831        uint64_t (*get_dropped_packets)(libtrace_t *trace);
832       
833        /** Returns the number of packets captured and returned by an input
834         * trace.
835         *
836         * @param trace         The input trace to get the capture count for
837         * @return The number of packets returned to the libtrace user, or
838         * UINT64_MAX if the number is unknown
839         *
840         * This is the number of packets that have been successfully returned
841         * to the libtrace user via the read_packet() function.
842         *
843         */
844        uint64_t (*get_captured_packets)(libtrace_t *trace);
845       
846        /** Returns the file descriptor used by the input trace.
847         *
848         * @param trace         The input trace to get the file descriptor for
849         * @return The file descriptor used by the input trace to read packets
850         *
851         */
852        int (*get_fd)(const libtrace_t *trace);
853       
854        /** Returns the next libtrace event for the input trace.
855         *
856         * @param trace         The input trace to get the next event from
857         * @param packet        A libtrace packet to read a packet into
858         * @return A libtrace event describing the event that occured
859         *
860         * The event API allows for non-blocking reading of packets from an
861         * input trace. If a packet is available and ready to be read, a packet
862         * event should be returned. Otherwise a sleep or fd event should be
863         * returned to indicate that the caller needs to wait. If the input
864         * trace has an error or reaches EOF, a terminate event should be
865         * returned.
866         */
867        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
868
869        /** Prints some useful help information to standard output. */
870        void (*help)(void);
871       
872        /** Starts or unpauses an input trace in parallel mode - note that
873         * this function is often the one that opens the file or device for
874         * reading.
875         *
876         * @param libtrace      The input trace to be started or unpaused
877         * @return If successful the number of threads started, 0 indicates
878         *                 no threads started and this should be done automatically.
879         *                 Otherwise in event of an error -1 is returned.
880         *
881         */
882        int (*pstart_input)(libtrace_t *trace);
883       
884        /** Read a packet in the new parallel mode
885         * @return same as read_packet, with the addition of return -2 to represent
886         * interrupted due to message waiting. */
887        int (*pread_packet)(libtrace_t *trace, libtrace_packet_t *packet);
888       
889        /** Pause a parallel trace */
890        int (*ppause_input)(libtrace_t *trace);
891       
892        /** Called after all threads have been paused, Finish (close) a parallel trace */
893        int (*pfin_input)(libtrace_t *trace);
894       
895        /** Applies a configuration option to an input trace.
896         *
897         * @param libtrace      The input trace to apply the option to
898         * @param option        The option that is being configured
899         * @param value         A pointer to the value that the option is to be
900         *                      set to
901         * @return 0 if successful, -1 if the option is unsupported or an error
902         * occurs
903         */
904        int (*pconfig_input)(libtrace_t *libtrace,trace_parallel_option_t option,void *value);
905       
906        /** Next pointer, should always be NULL - used by the format module
907         * manager. */
908        struct libtrace_format_t *next;
909};
910
911/** The list of registered capture formats */
912//extern struct libtrace_format_t *form;
913
914/** Specifies whether any blocking packet readers should cease reading
915 * immediately
916 */
917extern int libtrace_halt;
918
919/** Registers a new capture format module.
920 *
921 * @param format        The format module to be registered
922 */
923void register_format(struct libtrace_format_t *format);
924
925/** Converts a PCAP DLT into a libtrace link type.
926 *
927 * @param linktype      The PCAP DLT to be converted
928 * @return The libtrace link type that is equivalent to the provided DLT, or
929 * -1 if the DLT is unknown
930 */
931libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype);
932
933/** Converts a PCAP DLT into an RT protocol type.
934 *
935 * @param linktype      The PCAP DLT to be converted
936 * @return The RT type that is equivalent to the provided DLT
937 */
938libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype);
939
940/** Converts a libtrace link type into a PCAP linktype.
941 *
942 * @param type          The libtrace link type to be converted
943 * @return The PCAP linktype that is equivalent to the provided libtrace link
944 * type, or -1 if the link type is unknown
945 */
946libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type);
947
948/** Converts a libtrace link type into a PCAP DLT.
949 *
950 * @param type          The libtrace link type to be converted
951 * @return The PCAP DLT that is equivalent to the provided libtrace link
952 * type, or -1 if the link type is unknown
953 */
954libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type);
955
956/** Converts an RT protocol type into a PCAP DLT.
957 *
958 * @param rt_type       The RT type to be converted
959 * @return The PCAP DLT that is equivalent to the provided RT protocol
960 */
961libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type);
962
963/** Converts a PCAP DLT into an RT protocol type for the BPF format.
964 *
965 * @param linktype      The PCAP DLT to be converted
966 * @return The RT type that is equivalent to the provided DLT for BPF
967 */
968libtrace_rt_types_t bpf_linktype_to_rt(libtrace_dlt_t linktype);
969
970/** Converts an ERF type into a libtrace link type.
971 *
972 * @param erf           The ERF type to be converted
973 * @return The libtrace link type that is equivalent to the provided ERF type,
974 * or -1 if the ERF type is unknown
975 */
976libtrace_linktype_t erf_type_to_libtrace(uint8_t erf);
977
978/** Converts a libtrace link type into an ERF type.
979 *
980 * @param linktype      The libtrace link type to be converted
981 * @return The ERF type that is equivalent to the provided libtrace link type,
982 * or -1 if the link type cannot be matched to an ERF type.
983 */
984uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype);
985
986/** Converts an ARPHRD type into a libtrace link type.
987 *
988 * @param arphrd        The ARPHRD type to be converted
989 * @return The libtrace link type that is equivalent to the provided ARPHRD
990 * type, or -1 if the ARPHRD type is unknown
991 */
992libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd);
993
994/** Converts a libtrace link type into an ARPHRD type.
995 *
996 * @param type          The libtrace link type to be converted
997 * @return The ARPHRD type that is equivalent to the provided libtrace link
998 * type, or -1 if the link type cannot be matched to an ARPHRD type
999 */
1000unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type);
1001
1002/** Converts a libtrace packet to the Linux SLL type.
1003 *
1004 * @param packet        The packet to be promoted
1005 *
1006 * @note This will involve memcpy() so use sparingly.
1007 *
1008 * This function prepends a Linux SLL header to a packet so that we can store
1009 * direction tagging information.
1010 */
1011void promote_packet(libtrace_packet_t *packet);
1012
1013/** Attempts to demote a packet by removing the first header.
1014 *
1015 * @param packet        The packet to be demoted
1016 * @return True if the packet was demoted, false otherwise.
1017 *
1018 * Essentially the opposite of promote_packet, except that it will also remove
1019 * an ATM header as well as Linux SLL.
1020 *
1021 */
1022bool demote_packet(libtrace_packet_t *packet);
1023
1024/** Returns a pointer to the header following a Linux SLL header.
1025 *
1026 * @param link          A pointer to the Linux SLL header to be skipped
1027 * @param[out] arphrd_type      The arp hardware type of the packet
1028 * @param[out] next_header      The ethertype of the next header
1029 * @param[in,out] remaining     Updated with the number of captured bytes
1030 *                              remaining
1031 * @return A pointer to the header following the Linux SLL header, or NULL if
1032 * no subsequent header is present.
1033 *
1034 * Remaining must point to the number of bytes captured from the Linux SLL
1035 * header and beyond.  It will be decremented by the number of bytes skipped
1036 * to find the payload.
1037 *
1038 * If the Linux SLL header is complete but there are zero bytes of payload
1039 * after the end of the header, a pointer to where the payload would be is
1040 * returned and remaining will be set to zero. If the Linux SLL header is
1041 * incomplete (truncated), then NULL is returned and remaining will be set to
1042 * 0. Therefore, it is very important to check the value of remaining after
1043 * calling this function.
1044 */     
1045void *trace_get_payload_from_linux_sll(const void *link,
1046                uint16_t *arphrd_type, 
1047                uint16_t *next_header, 
1048                uint32_t *remaining);
1049
1050/** Returns a pointer to the header following an ATM header.
1051 *
1052 * @param link          A pointer to the ATM header to be skipped
1053 * @param[out] type     The ethertype of the next header
1054 * @param[in,out] remaining     Updated with the number of captured bytes
1055 *                              remaining
1056 * @return A pointer to the header following the ATM header, or NULL if
1057 * no subsequent header is present.
1058 *
1059 * Remaining must point to the number of bytes captured from the ATM header
1060 * and beyond.  It will be decremented by the number of bytes skipped to find
1061 * the payload.
1062 *
1063 * If the ATM header is complete but there are zero bytes of payload
1064 * after the end of the header, a pointer to where the payload would be is
1065 * returned and remaining will be set to zero. If the ATM header is
1066 * incomplete (truncated), then NULL is returned and remaining will be set to
1067 * 0. Therefore, it is very important to check the value of remaining after
1068 * calling this function.
1069 */     
1070DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type, 
1071                uint32_t *remaining);
1072
1073
1074#ifdef HAVE_BPF
1075/* A type encapsulating a bpf filter
1076 * This type covers the compiled bpf filter, as well as the original filter
1077 * string
1078 *
1079 */
1080
1081/** Internal representation of a BPF filter */
1082struct libtrace_filter_t {
1083        struct bpf_program filter;      /**< The BPF program itself */
1084        char * filterstring;            /**< The filter string */
1085        int flag;                       /**< Indicates if the filter is valid */
1086        struct bpf_jit_t *jitfilter;
1087};
1088#else
1089/** BPF not supported by this system, but we still need to define a structure
1090 * for the filter */
1091struct libtrace_filter_t {};
1092#endif
1093
1094/** Local definition of a PCAP header */
1095typedef struct libtrace_pcapfile_pkt_hdr_t {
1096        uint32_t ts_sec;        /* Seconds portion of the timestamp */
1097        uint32_t ts_usec;       /* Microseconds portion of the timestamp */
1098        uint32_t caplen;        /* Capture length of the packet */
1099        uint32_t wirelen;       /* The wire length of the packet */
1100} libtrace_pcapfile_pkt_hdr_t;
1101
1102#ifdef HAVE_DAG
1103/** Constructor for the DAG format module */
1104void dag_constructor(void);
1105#endif
1106/** Constructor for the ERF format module */
1107void erf_constructor(void);
1108/** Constructor for the TSH format module */
1109void tsh_constructor(void);
1110/** Constructor for the Legacy DAG format module */
1111void legacy_constructor(void);
1112/** Constructor for the Linux Native format module */
1113void linuxnative_constructor(void);
1114/** Constructor for the PCAP format module */
1115void pcap_constructor(void);
1116/** Constructor for the PCAP File format module */
1117void pcapfile_constructor(void);
1118/** Constructor for the RT format module */
1119void rt_constructor(void);
1120/** Constructor for the DUCK format module */
1121void duck_constructor(void);
1122/** Constructor for the ATM Header format module */
1123void atmhdr_constructor(void);
1124#ifdef HAVE_BPF
1125/** Constructor for the BPF format module */
1126void bpf_constructor(void);
1127#endif
1128#if HAVE_DPDK
1129/** Constructor for Intels DPDK format module */
1130void dpdk_constructor(void);
1131#endif
1132
1133/** Extracts the RadioTap flags from a wireless link header
1134 *
1135 * @param link          A pointer to the wireless link header
1136 * @param linktype      The link type of the wireless header
1137 * @param[out] flags    Space to store the extracted flags
1138 * @return True if libtrace was able to extract flags from the link header,
1139 * false otherwise.
1140 *
1141 * This function has been left internal because it is not portable across
1142 * drivers.
1143 */
1144bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags);
1145#define TRACE_RADIOTAP_F_FCS 0x10
1146       
1147#ifdef __cplusplus
1148}
1149#endif
1150
1151#endif /* LIBTRACE_INT_H */
Note: See TracBrowser for help on using the repository browser.