source: lib/libtrace_int.h @ 5ba34eb

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

Remove inlines for BSD support

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