source: lib/libtrace_int.h @ 04bf7c5

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

Remove unused sliding window code.
Refactored pstart and added some proper error handling.

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