source: lib/libtrace_int.h @ 17a3dff

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

Rename from google map/reduce framework names to something more meaningful.
Rename mapper to perpkt since this is what it actually is in libtrace.

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