source: lib/libtrace_int.h @ 32ee9b2

cachetimestampsdeveloprc-4.0.4ringdecrementfixringperformance
Last change on this file since 32ee9b2 was 32ee9b2, checked in by Shane Alcock <salcock@…>, 2 years ago

Add new trace_flush_output() to public API

Can be used to force a libtrace output to dump any buffered output
to disk immediately.

Note that if the file is compressed or the output trace format
requires a trailer, the flushed file will still not be properly
readable afterwards as this will not result in any trailers
being written. You'll still have to close the file for that.

Mainly this is useful for ensuring that output file sizes grow
over time in situations where the amount of output is relatively
small, rather than staying stuck at 0 bytes until we either reach
1MB of output or the file is closed. For instance, you could have
a timer that calls trace_flush_output() every 30 seconds so that
the output file size will grow if any packets were written in the
last 30 seconds.

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