source: lib/libtrace_int.h @ e375e0f

cachetimestampsdevelopetsiliverc-4.0.3rc-4.0.4ringdecrementfixringperformance
Last change on this file since e375e0f was e375e0f, checked in by Shane Alcock <salcock@…>, 3 years ago

Fix bug where libtrace-created hasher_data was leaked.

If trace_set_hasher was called with a null hasher, libtrace
would malloc memory for storing hasher_data. However, that
memory was never freed, since we had no way of telling whether
that memory had been externally allocated and passed in to
trace_set_hasher or if the memory had been allocated by libtrace.

Added a flag to the libtrace_t structure that records who owns
hasher_data and will now free it during trace_destroy if the
memory was allocated by libtrace.

  • Property mode set to 100644
File size: 42.5 KB
Line 
1/*
2 *
3 * Copyright (c) 2007-2016 The University of Waikato, Hamilton, New Zealand.
4 * All rights reserved.
5 *
6 * This file is part of libtrace.
7 *
8 * This code has been developed by the University of Waikato WAND
9 * research group. For further information please see http://www.wand.net.nz/
10 *
11 * libtrace is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License as published by
13 * the Free Software Foundation; either version 3 of the License, or
14 * (at your option) any later version.
15 *
16 * libtrace is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
23 *
24 *
25 */
26/** @file
27 *
28 * @brief Header file containing definitions for structures and functions that
29 * are internal
30 *
31 * @author Daniel Lawson
32 * @author Perry Lorier
33 * @author Shane Alcock
34 *
35 * @version $Id$
36 *
37 * All of the structures and functions defined in this header file are intended
38 * for internal use within Libtrace only. They should not be exported as part
39 * of the library API as we don't want users accessing things like the
40 * contents of the libtrace packet structure directly!
41 */
42#ifndef LIBTRACE_INT_H
43#define LIBTRACE_INT_H
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49#include "config.h"
50#include "common.h"
51#include "libtrace_parallel.h"
52#include "wandio.h"
53#include "lt_bswap.h"
54
55#ifdef _MSC_VER
56// warning: deprecated function
57#pragma warning(disable:4996)
58// warning: benign redefinitions of types
59#pragma warning(disable:4142)
60#endif
61
62#ifdef HAVE_INTTYPES_H
63# include <inttypes.h>
64#else
65# include "lt_inttypes.h"
66#endif
67
68#ifdef HAVE_STDDEF_H
69# include <stddef.h>
70#else
71#ifndef WIN32
72# error "Can't find stddev.h -- do you define ptrdiff_t elsewhere?"
73#endif
74#endif
75
76
77#include "rt_protocol.h"
78       
79/* Prefer net/bpf.h over pcap-bpf.h for format_bpf.c on MacOS */
80#ifdef HAVE_NET_BPF_H
81#    include <net/bpf.h>
82#    define HAVE_BPF 1
83#else
84#ifdef HAVE_PCAP_BPF_H
85#  include <pcap-bpf.h>
86#  define HAVE_BPF 1
87#endif
88#endif
89
90#ifdef HAVE_PCAP_H
91#  include <pcap.h>
92#  ifdef HAVE_PCAP_INT_H
93#    include <pcap-int.h>
94#  endif
95#endif
96
97#ifdef HAVE_ZLIB_H
98#  include <zlib.h>
99#endif
100
101#ifndef HAVE_STRNDUP
102char *strndup(const char *s, size_t size);
103#endif
104
105#ifndef HAVE_STRNCASECMP
106# ifndef HAVE__STRNICMP
107/** A local implementation of strncasecmp (as some systems do not have it) */
108int strncasecmp(const char *str1, const char *str2, size_t n);
109# else
110# define strncasecmp _strnicmp
111# endif
112#endif
113
114#ifndef HAVE_SNPRINTF
115# ifndef HAVE_SPRINTF_S
116/** A local implementation of snprintf (as some systems do not have it) */
117int snprintf(char *str, size_t size, const char *format, ...);
118# else
119# define snprintf sprintf_s
120# endif
121#endif
122
123#include "daglegacy.h"
124       
125#ifdef HAVE_DAG_API
126#  include "dagnew.h"
127#  include "dagapi.h"
128#       if DAG_VERSION == 24
129#               include <erftypes.h>
130#       else
131#               include <daginf.h>
132#       endif
133#  include "erftypes.h"
134#else
135#  include "dagformat.h"
136#endif
137
138#ifdef HAVE_LLVM
139#include "bpf-jit/bpf-jit.h"
140#endif
141
142#include "data-struct/ring_buffer.h"
143#include "data-struct/object_cache.h"
144#include "data-struct/vector.h"
145#include "data-struct/message_queue.h"
146#include "data-struct/deque.h"
147#include "data-struct/linked_list.h"
148#include "data-struct/sliding_window.h"
149#include "data-struct/buckets.h"
150#include "pthread_spinlock.h"
151
152//#define RP_BUFSIZE 65536U
153
154/** Data about the most recent event from a trace file */
155struct libtrace_event_status_t {
156        /** A libtrace packet to store the packet when a PACKET event occurs */
157        libtrace_packet_t *packet;
158        /** Time between the timestamp for the current packet and the current
159         * walltime */
160        double tdelta;
161        /** The timestamp of the previous PACKET event */
162        double trace_last_ts;
163        /** The size of the current PACKET event */
164        int psize;
165        /** Whether there is a packet stored in *packet above waiting for an
166         * event to occur */
167        bool waiting;
168};
169
170enum thread_types {
171        THREAD_EMPTY,
172        THREAD_HASHER,
173        THREAD_PERPKT,
174        THREAD_REPORTER,
175        THREAD_KEEPALIVE
176};
177
178enum thread_states {
179        THREAD_RUNNING,
180        THREAD_FINISHING,
181        THREAD_FINISHED,
182        THREAD_PAUSED,
183        THREAD_STATE_MAX
184};
185
186enum hash_owner {
187        HASH_OWNED_LIBTRACE,
188        HASH_OWNED_EXTERNAL,
189};
190
191/**
192 * Information of this thread
193 */
194struct libtrace_thread_t {
195        uint64_t accepted_packets; // The number of packets accepted only used if pread
196        uint64_t filtered_packets;
197        // is retreving packets
198        // Set to true once the first packet has been stored
199        bool recorded_first;
200        // For thread safety reason we actually must store this here
201        int64_t tracetime_offset_usec;
202        void* user_data; // TLS for the user to use
203        void* format_data; // TLS for the format to use
204        libtrace_message_queue_t messages; // Message handling
205        libtrace_ringbuffer_t rbuffer; // Input
206        libtrace_t * trace;
207        void* ret;
208        enum thread_types type;
209        enum thread_states state;
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} ALIGN_STRUCT(CACHE_LINE_SIZE);
215
216/**
217 * Storage to note time value against each.
218 * Used both internally to do trace time playback
219 * and can be used externally to assist applications which need
220 * a trace starting time such as tracertstats.
221 */
222struct first_packets {
223        pthread_spinlock_t lock;
224        size_t count; // If == perpkt_thread_count threads we have all
225        size_t first; // Valid if count != 0
226        struct {
227                libtrace_packet_t * packet;
228                struct timeval tv;
229        } * packets;
230};
231
232#define TRACE_STATES \
233        X(STATE_NEW) \
234        X(STATE_RUNNING) \
235        X(STATE_PAUSING) \
236        X(STATE_PAUSED) \
237        X(STATE_FINISHED) \
238        X(STATE_FINISHING) \
239        X(STATE_DESTROYED) \
240        X(STATE_JOINED) \
241        X(STATE_ERROR)
242
243#define X(a) a,
244enum trace_state {
245        TRACE_STATES
246};
247#undef X
248
249#define X(a) case a: return #a;
250static inline char *get_trace_state_name(enum trace_state ts){
251        switch(ts) {
252                TRACE_STATES
253                default:
254                        return "UNKNOWN";
255        }
256}
257#undef X
258
259#define READ_EOF 0
260#define READ_ERROR -1
261#define READ_MESSAGE -2
262// Used for inband tick message
263#define READ_TICK -3
264
265/**
266 * Tuning the parallel sizes
267 * See the user documentation trace_set_x
268 */
269struct user_configuration {
270        size_t cache_size;
271        size_t thread_cache_size;
272        bool fixed_count;
273        size_t burst_size;
274        size_t tick_interval;
275        size_t tick_count;
276        size_t perpkt_threads;
277        size_t hasher_queue_size;
278        bool hasher_polling;
279        bool reporter_polling;
280        size_t reporter_thold;
281        bool debug_state;
282};
283#define ZERO_USER_CONFIG(config) memset(&config, 0, sizeof(struct user_configuration));
284
285struct callback_set {
286
287        fn_cb_starting message_starting;
288        fn_cb_dataless message_stopping;
289        fn_cb_dataless message_resuming;
290        fn_cb_dataless message_pausing;
291        fn_cb_packet message_packet;
292        fn_cb_result message_result;
293        fn_cb_first_packet message_first_packet;
294        fn_cb_tick message_tick_count;
295        fn_cb_tick message_tick_interval;
296        fn_cb_usermessage message_user;
297};
298
299/** A libtrace input trace
300 * @internal
301 */
302struct libtrace_t {
303        /** The capture format for the input trace */
304        struct libtrace_format_t *format; 
305        /** Details of the most recent PACKET event reported by the trace */
306        struct libtrace_event_status_t event;
307        /** Pointer to the "global" data for the capture format module */       
308        void *format_data;             
309        /** A BPF filter to be applied to all packets read by the trace -
310         * used only if the capture format does not support filters natively */
311        struct libtrace_filter_t *filter; 
312        /** The snap length to be applied to all packets read by the trace -
313         * used only if the capture format does not support snapping natively */
314        size_t snaplen;                 
315        /** Count of the number of packets returned to the libtrace user */
316        uint64_t accepted_packets;
317        /** Count of the number of packets filtered by libtrace */
318        uint64_t filtered_packets;
319        /** The sequence is like accepted_packets but we don't reset this after a pause. */
320        uint64_t sequence_number;
321        /** The packet read out by the trace, backwards compatibility to allow us to finalise
322         * a packet when the trace is destroyed */
323        libtrace_packet_t *last_packet;
324        /** The filename from the uri for the trace */
325        char *uridata;
326        /** The libtrace IO reader for this trace (if applicable) */
327        io_t *io;
328        /** Error information for the trace */
329        libtrace_err_t err;
330        /** Boolean flag indicating whether the trace has been started */
331        bool started;
332        /** Synchronise writes/reads across this format object and attached threads etc */
333        pthread_mutex_t libtrace_lock;
334        /** Packet read lock, seperate from libtrace_lock as to not block while reading a burst */
335        pthread_mutex_t read_packet_lock;
336        /** State */
337        enum trace_state state;
338        /** Use to control pausing threads and finishing threads etc always used with libtrace_lock */
339        pthread_cond_t perpkt_cond;
340        /** Keeps track of counts of threads in any given state */
341        int perpkt_thread_states[THREAD_STATE_MAX]; 
342
343        /** Set to indicate a perpkt's queue is full as such the writing perpkt cannot proceed */
344        bool perpkt_queue_full;
345        /** Global storage for this trace, shared among all the threads  */
346        void* global_blob;
347        /** The actual freelist */
348        libtrace_ocache_t packet_freelist;
349        /** The hasher function */
350        enum hasher_types hasher_type;
351        /** The hasher function - NULL implies they don't care or balance */
352        fn_hasher hasher;
353        void *hasher_data;
354        enum hash_owner hasher_owner;
355        /** The pread_packet choosen path for the configuration */
356        int (*pread)(libtrace_t *, libtrace_thread_t *, libtrace_packet_t **, size_t);
357
358        libtrace_thread_t hasher_thread;
359        libtrace_thread_t reporter_thread;
360        libtrace_thread_t keepalive_thread;
361        int perpkt_thread_count;
362        libtrace_thread_t * perpkt_threads; // All our perpkt threads
363        // Used to keep track of the first packet seen on each thread
364        struct first_packets first_packets;
365        int tracetime;
366
367        /*
368         * Caches statistic counters in the case that our trace is
369         * paused or stopped before this counter is taken
370         */
371        libtrace_stat_t *stats;
372        struct user_configuration config;
373        libtrace_combine_t combiner;
374       
375        /* Set of callbacks to be executed by per packet threads in response
376         * to various messages. */
377        struct callback_set *perpkt_cbs;
378        /* Set of callbacks to be executed by the reporter thread in response
379         * to various messages. */
380        struct callback_set *reporter_cbs;
381};
382
383#define LIBTRACE_STAT_MAGIC 0x41
384
385void trace_fin_packet(libtrace_packet_t *packet);
386void libtrace_zero_thread(libtrace_thread_t * t);
387void store_first_packet(libtrace_t *libtrace, libtrace_packet_t *packet, libtrace_thread_t *t);
388libtrace_thread_t * get_thread_table(libtrace_t *libtrace);
389
390
391void send_message(libtrace_t *trace, libtrace_thread_t *target,
392                const enum libtrace_messages type,
393                libtrace_generic_t data, libtrace_thread_t *sender);
394
395/** A libtrace output trace
396 * @internal
397 */
398struct libtrace_out_t {
399        /** The capture format for the output trace */
400        struct libtrace_format_t *format;
401        /** Pointer to the "global" data for the capture format module */
402        void *format_data;             
403        /** The filename for the uri for the output trace */
404        char *uridata;                 
405        /** Error information for the output trace */
406        libtrace_err_t err;
407        /** Boolean flag indicating whether the trace has been started */
408        bool started;
409};
410
411/** Sets the error status on an input trace
412 *
413 * @param trace         The input trace to set the error status for
414 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
415 * @param msg           A message to print when reporting the error
416 */
417void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...) 
418
419                                                                PRINTF(3,4);
420/** Sets the error status on an output trace
421 *
422 * @param trace         The output trace to set the error status for
423 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
424 * @param msg           A message to print when reporting the error
425 */
426void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...)
427                                                                PRINTF(3,4);
428
429/** Clears the cached values for a libtrace packet
430 *
431 * @param packet        The libtrace packet that requires a cache reset
432 */
433void trace_clear_cache(libtrace_packet_t *packet);
434
435
436#ifndef PF_RULESET_NAME_SIZE
437#define PF_RULESET_NAME_SIZE 16
438#endif
439
440#ifndef IFNAMSIZ
441#define IFNAMSIZ 16
442#endif
443
444
445/** A local definition of a PFLOG header */
446typedef struct libtrace_pflog_header_t {
447        uint8_t    length;     
448        sa_family_t   af;
449        uint8_t    action;
450        uint8_t    reason;
451        char       ifname[IFNAMSIZ];
452        char       ruleset[PF_RULESET_NAME_SIZE];
453        uint32_t   rulenr;
454        uint32_t   subrulenr;
455        uint8_t    dir;
456        uint8_t    pad[3];
457} PACKED libtrace_pflog_header_t;
458
459/** A libtrace capture format module */
460/* All functions should return -1, or NULL on failure */
461struct libtrace_format_t {
462        /** The name of this module, used in the libtrace URI to identify the
463         * capture format */
464        const char *name;
465        /** The version of this module */
466        const char *version;
467        /** The RT protocol type of this module */
468        enum base_format_t type;
469
470
471        /** Given a filename, return if this is the most likely capture format
472         * (used for devices). Used to "guess" the capture format when the
473         * URI is not fully specified.
474         *
475         * @param fname         The name of the device or file to examine
476         * @return 1 if the name matches the capture format, 0 otherwise
477         */
478        int (*probe_filename)(const char *fname);
479       
480        /** Given a file, looks at the start of the file to determine if this
481         * is the capture format. Used to "guess" the capture format when the
482         * URI is not fully specified.
483         *
484         * @param io            An open libtrace IO reader for the file to check
485         * @return 1 if the file matches the capture format, 0 otherwise
486         */
487        int (*probe_magic)(io_t *io);
488
489        /** Initialises an input trace using the capture format.
490         *
491         * @param libtrace      The input trace to be initialised
492         * @return 0 if successful, -1 in the event of error
493         */
494        int (*init_input)(libtrace_t *libtrace);
495       
496        /** Applies a configuration option to an input trace.
497         *
498         * @param libtrace      The input trace to apply the option to
499         * @param option        The option that is being configured
500         * @param value         A pointer to the value that the option is to be
501         *                      set to
502         * @return 0 if successful, -1 if the option is unsupported or an error
503         * occurs
504         */
505        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
506        /** Starts or unpauses an input trace - note that this function is
507         * often the one that opens the file or device for reading.
508         *
509         * @param libtrace      The input trace to be started or unpaused
510         * @return 0 if successful, -1 in the event of error */
511        int (*start_input)(libtrace_t *libtrace);
512
513        /** Pauses an input trace - this function should close or detach the
514         * file or device that is being read from.
515         *
516         * @param libtrace      The input trace to be paused
517         * @return 0 if successful, -1 in the event of error
518         */
519        int (*pause_input)(libtrace_t *libtrace);
520
521        /** Initialises an output trace using the capture format.
522         *
523         * @param libtrace      The output trace to be initialised
524         * @return 0 if successful, -1 in the event of error
525         */
526        int (*init_output)(libtrace_out_t *libtrace);
527       
528        /** Applies a configuration option to an output trace.
529         *
530         * @param libtrace      The output trace to apply the option to
531         * @param option        The option that is being configured
532         * @param value         A pointer to the value that the option is to be
533         *                      set to
534         * @return 0 if successful, -1 if the option is unsupported or an error
535         * occurs
536         * */
537        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value);
538
539        /** Starts an output trace - note that this function is often the one
540         * that opens the file or device for writing.
541         *
542         * @param libtrace      The output trace to be started
543         * @return 0 if successful, -1 if an error occurs
544         *
545         * There is no pause for output traces, as writing is not performed
546         * asynchronously.
547         */
548        int (*start_output)(libtrace_out_t *libtrace);
549
550        /** Concludes an input trace and cleans up the capture format data.
551         *
552         * @param libtrace      The input trace to be concluded
553         * @return 0 if successful, -1 if an error occurs
554         *
555         * Libtrace will call the pause_input function if the input trace is
556         * currently active prior to calling this function.
557         */
558        int (*fin_input)(libtrace_t *libtrace);
559
560        /** Concludes an output trace and cleans up the capture format data.
561         *
562         * @param libtrace      The output trace to be concluded
563         * @return 0 if successful, -1 if an error occurs
564         */
565        int (*fin_output)(libtrace_out_t *libtrace);
566
567        /** Reads the next packet from an input trace into the provided packet
568         * structure.
569         *
570         * @param libtrace      The input trace to read from
571         * @param packet        The libtrace packet to read into
572         * @return The size of the packet read (in bytes) including the capture
573         * framing header, or -1 if an error occurs. 0 is returned in the
574         * event of an EOF or -2 in the case of interrupting the parallel API.
575         *
576         * If no packets are available for reading, this function should block
577         * until one appears or return 0 if the end of a trace file has been
578         * reached.
579         */
580        int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet);
581       
582        /** Converts a buffer containing a packet record into a libtrace packet
583         *
584         * @param libtrace      An input trace in the capture format for the
585         *                      packet
586         * @param packet        A libtrace packet to put the prepared packet
587         *                      into
588         * @param buffer        The buffer containing the packet record
589         *                      (including the capture format header)
590         * @param rt_type       The RT type for the packet
591         * @param flags         Flags describing properties that should be
592         *                      applied to the new packet
593         * @return 0 if successful, -1 if an error occurs.
594         *
595         * Updates internal trace and packet details, such as payload pointers,
596         * loss counters and packet types to match the packet record provided
597         * in the buffer. This is a zero-copy function.
598         *
599         * Intended (at this stage) only for internal use, particularly by
600         * RT which needs to decapsulate RT packets */
601        int (*prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet,
602                        void *buffer, libtrace_rt_types_t rt_type, 
603                        uint32_t flags);
604       
605        /** Frees any resources allocated by the capture format module for a
606         * libtrace packet.
607         *
608         * @param The packet to be finalised
609         *       */
610        void (*fin_packet)(libtrace_packet_t *packet);
611
612        /** Write a libtrace packet to an output trace.
613         *
614         * @param libtrace      The output trace to write the packet to
615         * @param packet        The packet to be written out
616         * @return The number of bytes written, or -1 if an error occurs
617         */
618        int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet);
619        /** Returns the libtrace link type for a packet.
620         *
621         * @param packet        The packet to get the link type for
622         * @return The libtrace link type, or -1 if this link type is unknown
623         */ 
624        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
625
626        /** Returns the direction of a packet.
627         *
628         * @param packet        The packet to get the direction for
629         * @return The direction of the packet, or -1 if no direction tag is
630         * present or an error occurs
631         */ 
632        libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet);
633       
634        /** Sets the direction of a packet.
635         *
636         * @param packet        The packet to set the direction for
637         * @param direction     The direction to assign to the packet
638         * @return The updated direction for the packet, or -1 if an error
639         * occurs
640         *
641         * @note Some capture formats do not feature direction tagging, so it
642         * will not make sense to implement a set_direction function for them.
643         */ 
644        libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction);
645       
646        /** Returns the timestamp for a packet in the ERF timestamp format.
647         *
648         * @param packet        The packet to get the timestamp from
649         * @return The 64-bit ERF timestamp
650         *
651         * @note Each format must implement at least one of the four "get
652         * timestamp" functions.
653         *
654         * If not implemented, libtrace will convert the result of one of the
655         * other timestamp functions into the appropriate format instead.
656         * This means each capture format only needs to implement the most
657         * sensible of the four and let libtrace handle any conversions.
658         *
659         */
660        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
661
662        /** Returns the timestamp for a packet in the timeval format
663         *
664         * @param packet        The packet to get the timestamp from
665         * @return The timestamp from the packet as a timeval
666         *
667         * @note Each format must implement at least one of the four "get
668         * timestamp" functions.
669         *
670         * If not implemented, libtrace will convert the result of one of the
671         * other timestamp functions into the appropriate format instead.
672         * This means each capture format only needs to implement the most
673         * sensible of the four and let libtrace handle any conversions.
674         */
675        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
676       
677        /** Returns the timestamp for a packet in the timespec format.
678         *
679         * @param packet        The packet to get the timestamp from
680         * @return The timestamp from the packet as a timespec
681         *
682         * @note Each format must implement at least one of the four "get
683         * timestamp" functions.
684         *
685         * If not implemented, libtrace will convert the result of one of the
686         * other timestamp functions into the appropriate format instead.
687         * This means each capture format only needs to implement the most
688         * sensible of the four and let libtrace handle any conversions.
689         */
690        struct timespec (*get_timespec)(const libtrace_packet_t *packet);
691       
692        /** Returns the timestamp for a packet in floating point seconds.
693         *
694         * @param packet        The packet to get the timestamp from
695         * @return The timestamp from the packet as a floating point number of
696         * seconds since 1970-01-01 00:00:00 UTC
697         *
698         * @note Each format must implement at least one of the four "get
699         * timestamp" functions.
700         *
701         * If not implemented, libtrace will convert the result of one of the
702         * other timestamp functions into the appropriate format instead.
703         * This means each capture format only needs to implement the most
704         * sensible of the four and let libtrace handle any conversions.
705         */
706        double (*get_seconds)(const libtrace_packet_t *packet);
707       
708        /** Moves the read pointer to a certain ERF timestamp within an input
709         * trace file.
710         *
711         * @param trace         The input trace to seek within
712         * @param timestamp     The timestamp to seek to, as an ERF timestamp
713         *
714         * @return 0 on success, -1 on failure.
715         *
716         * The next packet read from this trace will now be the first packet
717         * to have a timestamp equal to or greater than the provided timestamp.
718         *
719         * @note Each format that supports seeking must implement at least one
720         * of the seek functions.
721         *
722         * If not implemented, libtrace will convert the timestamp into the
723         * appropriate format to use a seek function that has been implemented.
724         * This means each capture format only needs to implement the seek
725         * function that matches the native timestamp format for that capture.
726         *
727         */
728        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
729        /** Moves the read pointer to a certain timestamp represented using a
730         * timeval within an input trace file.
731         *
732         * @param trace         The input trace to seek within
733         * @param timestamp     The timestamp to seek to, as a timeval
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_timeval)(libtrace_t *trace, struct timeval tv);
750       
751        /** Moves the read pointer to a certain timestamp represented using
752         * floating point seconds within an input trace file.
753         *
754         * @param trace         The input trace to seek within
755         * @param timestamp     The timestamp to seek to, as floating point
756         *                      seconds since 1970-01-01 00:00:00 UTC
757         *
758         * @return 0 on success, -1 on failure.
759         *
760         * The next packet read from this trace will now be the first packet
761         * to have a timestamp equal to or greater than the provided timestamp.
762         *
763         * @note Each format that supports seeking must implement at least one
764         * of the seek functions.
765         *
766         * If not implemented, libtrace will convert the timestamp into the
767         * appropriate format to use a seek function that has been implemented.
768         * This means each capture format only needs to implement the seek
769         * function that matches the native timestamp format for that capture.
770         *
771         */
772        int (*seek_seconds)(libtrace_t *trace, double seconds);
773       
774        /** Returns the payload length of the captured packet record.
775         *
776         * @param packet        The packet to get the capture length from
777         * @return The capture length for the packet, or -1 if an error occurs
778         *
779         * Capture length is the current size of the packet record itself,
780         * following any truncation that may have occurred during the capture
781         * process. This length does not include the capture format framing
782         * header.
783         */
784        int (*get_capture_length)(const libtrace_packet_t *packet);
785
786        /** Returns the original length of the packet as it was on the wire.
787         *
788         * @param packet        The packet to get the wire length from
789         * @return The length of the packet on the wire at the time of capture,
790         * or -1 if an error occurs
791         *
792         * Wire length is the original size of the packet prior to any
793         * truncation that may have occurred as part of the capture process.
794         * This length does not include the capture format framing header.
795         */
796        int (*get_wire_length)(const libtrace_packet_t *packet);
797       
798        /** Returns the length of the capture format framing header
799         *
800         * @param packet        The packet to get the framing length from
801         * @return The length of the framing header, or -1 if an error occurs
802         *
803         * The framing header is the extra metadata that the capture process
804         * records about a packet.  The framing length does not include any
805         * of the packet payload itself. The total size of the packet record
806         * can be calculated be adding this value with the capture length.
807         */
808        int (*get_framing_length)(const libtrace_packet_t *packet);
809
810        /** Sets the capture length for a packet.
811         *
812         * @param packet        The packet to adjust the capture length for.
813         * @param size          The new capture length
814         * @return The new capture length of the packet, or -1 if an error
815         * occurs
816         *
817         * @note This function should only reduce the capture length. If the
818         * provided length is larger than the current capture length, -1 should
819         * be returned.
820         */
821        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
822        /** Returns the number of packets observed by an input trace.
823         *
824         * @param trace         The input trace to get the packet count for
825         * @return The number of packets observed by an input trace, or
826         * UINT64_MAX if the number is unknown
827         *
828         * This count includes packets that have been filtered and dropped.
829         */
830        uint64_t (*get_received_packets)(libtrace_t *trace);
831
832        /** Returns the number of packets filtered by an input trace.
833         *
834         * @param trace         The input trace to get the filtered count for
835         * @return The number of packets filtered by the input trace, or
836         * UINT64_MAX if the number is unknown
837         *
838         */
839        uint64_t (*get_filtered_packets)(libtrace_t *trace);
840       
841        /** Returns the number of packets dropped by an input trace.
842         *
843         * @param trace         The input trace to get the dropped count for
844         * @return The number of packets dropped by the input trace, or
845         * UINT64_MAX if the number is unknown
846         *
847         */
848        uint64_t (*get_dropped_packets)(libtrace_t *trace);
849
850        /** Returns statistics about a trace.
851         *
852         * @param trace The libtrace object
853         * @param stat [in,out] A statistics structure ready to be filled
854         *
855         * The filtered and accepted statistics will be set to the values
856         * stored in the library. All other statistics are not set.
857         *
858         * @note If filtering of packets is performed by a trace and the number
859         * of filtered packets is unknown this should be marked as invalid by
860         * the format.
861         */
862        void (*get_statistics)(libtrace_t *trace, libtrace_stat_t *stat);
863       
864        /** Returns the file descriptor used by the input trace.
865         *
866         * @param trace         The input trace to get the file descriptor for
867         * @return The file descriptor used by the input trace to read packets
868         *
869         */
870        int (*get_fd)(const libtrace_t *trace);
871       
872        /** Returns the next libtrace event for the input trace.
873         *
874         * @param trace         The input trace to get the next event from
875         * @param packet        A libtrace packet to read a packet into
876         * @return A libtrace event describing the event that occured
877         *
878         * The event API allows for non-blocking reading of packets from an
879         * input trace. If a packet is available and ready to be read, a packet
880         * event should be returned. Otherwise a sleep or fd event should be
881         * returned to indicate that the caller needs to wait. If the input
882         * trace has an error or reaches EOF, a terminate event should be
883         * returned.
884         */
885        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
886
887        /** Prints some useful help information to standard output. */
888        void (*help)(void);
889       
890        /** Next pointer, should always be NULL - used by the format module
891         * manager. */
892        struct libtrace_format_t *next;
893
894        /** Holds information about the trace format */
895        struct libtrace_info_t info;
896
897        /**
898         * Starts or unpauses an input trace in parallel mode - note that
899         * this function is often the one that opens the file or device for
900         * reading.
901         *
902         * @param libtrace      The input trace to be started or unpaused
903         * @return 0 upon success.
904         *         Otherwise in event of an error -1 is returned.
905         *
906         */
907        int (*pstart_input)(libtrace_t *trace);
908       
909        /**
910         * Read a batch of packets from the input stream related to thread.
911         * At most read nb_packets, however should return with less if packets
912         * are not waiting. However still must return at least 1, 0 still indicates
913         * EOF.
914         *
915         * @param libtrace      The input trace
916         * @param t     The thread
917         * @param packets       An array of packets
918         * @param nb_packets    The number of packets in the array (the maximum to read)
919         * @return The number of packets read, or 0 in the case of EOF or -1 in error or -2 to represent
920         * interrupted due to message waiting before packets had been read.
921         */
922        int (*pread_packets)(libtrace_t *trace, libtrace_thread_t *t, libtrace_packet_t **packets, size_t nb_packets);
923       
924        /** Pause a parallel trace
925         *
926         * @param libtrace      The input trace to be paused
927         */
928        int (*ppause_input)(libtrace_t *trace);
929       
930        /** Called after all threads have been paused, Finish (close) a parallel trace
931         *
932         * @param libtrace      The input trace to be stopped
933         */
934        int (*pfin_input)(libtrace_t *trace);
935
936        /**
937         * Register a thread for use with the format or using the packets produced
938         * by it. This is NOT only used for threads reading packets in fact all
939         * threads use this.
940         *
941         * The libtrace lock is not held by this format but can be aquired
942         * by the format.
943         *
944         * Some use cases include setting up any thread local storage required for
945         * to read packets and free packets. For DPDK we require any thread that
946         * may release or read a packet to have have an internal number associated
947         * with it.
948         *
949         * The thread type can be used to see if this thread is going to be used
950         * to read packets or otherwise.
951         *
952         * @return 0 if successful, -1 if the option is unsupported or an error
953         * occurs (such as a maximum of threads being reached)
954         */
955        int (*pregister_thread)(libtrace_t *libtrace, libtrace_thread_t *t, bool reader);
956
957        /**
958         * If needed any memory allocated with pregister_thread can be released
959         * in this function. The thread will be destroyed directly after this
960         * function is called.
961         */
962        void (*punregister_thread)(libtrace_t *libtrace, libtrace_thread_t *t);
963
964        /** Returns statistics for a single thread.
965         *
966         * @param trace The libtrace object
967         * @param t The thread to return statistics for
968         * @param stat [in,out] A statistics structure ready to be filled
969         *
970         * The filtered and accepted statistics will be set to the values
971         * stored in the library. All other statistics are not set.
972         *
973         * @note If filtering of packets is performed by a trace and the number
974         * of filtered packets is unknown this should be marked as invalid by
975         * the format.
976         */
977        void (*get_thread_statistics)(libtrace_t *libtrace,
978                                      libtrace_thread_t *t,
979                                      libtrace_stat_t *stat);
980};
981
982/** Macro to zero out a single thread format */
983#define NON_PARALLEL(live) \
984        {live, 1},              /* trace info */ \
985        NULL,                   /* pstart_input */ \
986        NULL,                   /* pread_packet */ \
987        NULL,                   /* ppause_input */ \
988        NULL,                   /* pfin_input */ \
989        NULL,                   /* pregister_thread */ \
990        NULL,                   /* punregister_thread */ \
991        NULL,                   /* get_thread_statistics */
992
993/** The list of registered capture formats */
994//extern struct libtrace_format_t *form;
995
996/** Specifies whether any blocking packet readers should cease reading
997 * immediately
998 */
999extern volatile int libtrace_halt;
1000
1001/**
1002 * Used by a format to check if trace_interrupt or if a trace_pause/stop has
1003 * been called. Provides backwards compatibility with traditional read
1004 * functions when trace_read_packet() is used by the parallel API.
1005 *
1006 * Returns -1 if not halting otherwise returns the code that the read
1007 * operation should pass on.
1008 */
1009static inline int is_halted(libtrace_t *trace) {
1010        if (!(libtrace_halt || trace->state == STATE_PAUSING)) {
1011                return -1;
1012        } else if (libtrace_halt) {
1013                return READ_EOF;
1014        } else {
1015                return READ_MESSAGE;
1016        }
1017}
1018
1019/** Registers a new capture format module.
1020 *
1021 * @param format        The format module to be registered
1022 */
1023void register_format(struct libtrace_format_t *format);
1024
1025/** Converts a timeval into a timestamp in microseconds since the epoch.
1026 *
1027 * @param tv    The timeval to be converted.
1028 * @return A 64 bit timestamp in microseconds since the epoch.
1029 */
1030uint64_t tv_to_usec(const struct timeval *tv);
1031
1032/** Converts a PCAP DLT into a libtrace link type.
1033 *
1034 * @param linktype      The PCAP DLT to be converted
1035 * @return The libtrace link type that is equivalent to the provided DLT, or
1036 * -1 if the DLT is unknown
1037 */
1038libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype);
1039
1040/** Converts a PCAP DLT into an RT protocol type.
1041 *
1042 * @param linktype      The PCAP DLT to be converted
1043 * @return The RT type that is equivalent to the provided DLT
1044 */
1045libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype);
1046
1047/** Converts a PCAP-NG DLT into an RT protocol type.
1048 *
1049 * @param linktype      The PCAP DLT to be converted
1050 * @return The RT type that is equivalent to the provided DLT
1051 */
1052libtrace_rt_types_t pcapng_linktype_to_rt(libtrace_dlt_t linktype);
1053
1054/** Converts a libtrace link type into a PCAP linktype.
1055 *
1056 * @param type          The libtrace link type to be converted
1057 * @return The PCAP linktype that is equivalent to the provided libtrace link
1058 * type, or -1 if the link type is unknown
1059 */
1060libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type);
1061
1062/** Converts a libtrace link type into a PCAP DLT.
1063 *
1064 * @param type          The libtrace link type to be converted
1065 * @return The PCAP DLT that is equivalent to the provided libtrace link
1066 * type, or -1 if the link type is unknown
1067 */
1068libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type);
1069
1070/** Converts an RT protocol type into a PCAP DLT.
1071 *
1072 * @param rt_type       The RT type to be converted
1073 * @return The PCAP DLT that is equivalent to the provided RT protocol
1074 */
1075libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type);
1076
1077/** Converts a PCAP DLT into an RT protocol type for the BPF format.
1078 *
1079 * @param linktype      The PCAP DLT to be converted
1080 * @return The RT type that is equivalent to the provided DLT for BPF
1081 */
1082libtrace_rt_types_t bpf_linktype_to_rt(libtrace_dlt_t linktype);
1083
1084/** Converts an ERF type into a libtrace link type.
1085 *
1086 * @param erf           The ERF type to be converted
1087 * @return The libtrace link type that is equivalent to the provided ERF type,
1088 * or -1 if the ERF type is unknown
1089 */
1090libtrace_linktype_t erf_type_to_libtrace(uint8_t erf);
1091
1092/** Converts a libtrace link type into an ERF type.
1093 *
1094 * @param linktype      The libtrace link type to be converted
1095 * @return The ERF type that is equivalent to the provided libtrace link type,
1096 * or -1 if the link type cannot be matched to an ERF type.
1097 */
1098uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype);
1099
1100/** Converts an ARPHRD type into a libtrace link type.
1101 *
1102 * @param arphrd        The ARPHRD type to be converted
1103 * @return The libtrace link type that is equivalent to the provided ARPHRD
1104 * type, or -1 if the ARPHRD type is unknown
1105 */
1106libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd);
1107
1108/** Converts a libtrace link type into an ARPHRD type.
1109 *
1110 * @param type          The libtrace link type to be converted
1111 * @return The ARPHRD type that is equivalent to the provided libtrace link
1112 * type, or -1 if the link type cannot be matched to an ARPHRD type
1113 */
1114unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type);
1115
1116/** Converts a libtrace packet to the Linux SLL type.
1117 *
1118 * @param packet        The packet to be promoted
1119 *
1120 * @note This will involve memcpy() so use sparingly.
1121 *
1122 * This function prepends a Linux SLL header to a packet so that we can store
1123 * direction tagging information.
1124 */
1125void promote_packet(libtrace_packet_t *packet);
1126
1127/** Attempts to demote a packet by removing the first header.
1128 *
1129 * @param packet        The packet to be demoted
1130 * @return True if the packet was demoted, false otherwise.
1131 *
1132 * Essentially the opposite of promote_packet, except that it will also remove
1133 * an ATM header as well as Linux SLL.
1134 *
1135 */
1136bool demote_packet(libtrace_packet_t *packet);
1137
1138/** Returns a pointer to the header following a Linux SLL header.
1139 *
1140 * @param link          A pointer to the Linux SLL header to be skipped
1141 * @param[out] arphrd_type      The arp hardware type of the packet
1142 * @param[out] next_header      The ethertype of the next header
1143 * @param[in,out] remaining     Updated with the number of captured bytes
1144 *                              remaining
1145 * @return A pointer to the header following the Linux SLL header, or NULL if
1146 * no subsequent header is present.
1147 *
1148 * Remaining must point to the number of bytes captured from the Linux SLL
1149 * header and beyond.  It will be decremented by the number of bytes skipped
1150 * to find the payload.
1151 *
1152 * If the Linux SLL header is complete but there are zero bytes of payload
1153 * after the end of the header, a pointer to where the payload would be is
1154 * returned and remaining will be set to zero. If the Linux SLL header is
1155 * incomplete (truncated), then NULL is returned and remaining will be set to
1156 * 0. Therefore, it is very important to check the value of remaining after
1157 * calling this function.
1158 */     
1159void *trace_get_payload_from_linux_sll(const void *link,
1160                uint16_t *arphrd_type, 
1161                uint16_t *next_header, 
1162                uint32_t *remaining);
1163
1164/** Returns a pointer to the header following an ATM header.
1165 *
1166 * @param link          A pointer to the ATM header to be skipped
1167 * @param[out] type     The ethertype of the next header
1168 * @param[in,out] remaining     Updated with the number of captured bytes
1169 *                              remaining
1170 * @return A pointer to the header following the ATM header, or NULL if
1171 * no subsequent header is present.
1172 *
1173 * Remaining must point to the number of bytes captured from the ATM header
1174 * and beyond.  It will be decremented by the number of bytes skipped to find
1175 * the payload.
1176 *
1177 * If the ATM header is complete but there are zero bytes of payload
1178 * after the end of the header, a pointer to where the payload would be is
1179 * returned and remaining will be set to zero. If the ATM header is
1180 * incomplete (truncated), then NULL is returned and remaining will be set to
1181 * 0. Therefore, it is very important to check the value of remaining after
1182 * calling this function.
1183 */     
1184DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type, 
1185                uint32_t *remaining);
1186
1187
1188#ifdef HAVE_BPF
1189/* A type encapsulating a bpf filter
1190 * This type covers the compiled bpf filter, as well as the original filter
1191 * string
1192 *
1193 */
1194
1195/** Internal representation of a BPF filter */
1196struct libtrace_filter_t {
1197        struct bpf_program filter;      /**< The BPF program itself */
1198        char * filterstring;            /**< The filter string */
1199        int flag;                       /**< Indicates if the filter is valid */
1200        struct bpf_jit_t *jitfilter;
1201};
1202#else
1203/** BPF not supported by this system, but we still need to define a structure
1204 * for the filter */
1205struct libtrace_filter_t {};
1206#endif
1207
1208/** Local definition of a PCAP header */
1209typedef struct libtrace_pcapfile_pkt_hdr_t {
1210        uint32_t ts_sec;        /* Seconds portion of the timestamp */
1211        uint32_t ts_usec;       /* Microseconds portion of the timestamp */
1212        uint32_t caplen;        /* Capture length of the packet */
1213        uint32_t wirelen;       /* The wire length of the packet */
1214} libtrace_pcapfile_pkt_hdr_t;
1215
1216#ifdef HAVE_DAG
1217/** Constructor for the DAG format module */
1218void dag_constructor(void);
1219#endif
1220/** Constructor for the ERF format module */
1221void erf_constructor(void);
1222/** Constructor for the TSH format module */
1223void tsh_constructor(void);
1224/** Constructor for the Legacy DAG format module */
1225void legacy_constructor(void);
1226/** Constructor for the Linux Native format module */
1227void linuxnative_constructor(void);
1228/** Constructor for the Linux Ring format module */
1229void linuxring_constructor(void);
1230/** Constructor for the PCAP format module */
1231void pcap_constructor(void);
1232/** Constructor for the PCAP File format module */
1233void pcapfile_constructor(void);
1234/** Constructor for the PCAP-NG File format module */
1235void pcapng_constructor(void);
1236/** Constructor for the RT format module */
1237void rt_constructor(void);
1238/** Constructor for the DUCK format module */
1239void duck_constructor(void);
1240/** Constructor for the ATM Header format module */
1241void atmhdr_constructor(void);
1242/** Constructor for the network DAG format module */
1243void ndag_constructor(void);
1244#ifdef HAVE_BPF
1245/** Constructor for the BPF format module */
1246void bpf_constructor(void);
1247#endif
1248#if HAVE_DPDK
1249/** Constructor for Intels DPDK format module */
1250void dpdk_constructor(void);
1251
1252/** Constructor for receiving network DAG via Intels DPDK format module */
1253void dpdkndag_constructor(void);
1254
1255#endif
1256
1257/** Extracts the RadioTap flags from a wireless link header
1258 *
1259 * @param link          A pointer to the wireless link header
1260 * @param linktype      The link type of the wireless header
1261 * @param[out] flags    Space to store the extracted flags
1262 * @return True if libtrace was able to extract flags from the link header,
1263 * false otherwise.
1264 *
1265 * This function has been left internal because it is not portable across
1266 * drivers.
1267 */
1268bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags);
1269#define TRACE_RADIOTAP_F_FCS 0x10
1270       
1271#ifdef __cplusplus
1272}
1273#endif
1274
1275#endif /* LIBTRACE_INT_H */
Note: See TracBrowser for help on using the repository browser.