source: lib/libtrace_int.h @ ae3779b

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since ae3779b was ae3779b, checked in by Shane Alcock <salcock@…>, 11 years ago
  • Make sure we always include erftypes.h when the DAG API is available, as older API versions (e.g. 2.5.5) don't include all the erf types that we use in format_erf now
  • Property mode set to 100644
File size: 35.3 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
62#ifdef _MSC_VER
63// warning: deprecated function
64#pragma warning(disable:4996)
65// warning: benign redefinitions of types
66#pragma warning(disable:4142)
67#endif
68
69#ifdef HAVE_INTTYPES_H
70# include <inttypes.h>
71#else
72# include "lt_inttypes.h"
73#endif
74
75#ifdef HAVE_STDDEF_H
76# include <stddef.h>
77#else
78#ifndef WIN32
79# error "Can't find stddev.h -- do you define ptrdiff_t elsewhere?"
80#endif
81#endif
82
83
84#include "rt_protocol.h"
85       
86/* Prefer net/bpf.h over pcap-bpf.h for format_bpf.c on MacOS */
87#ifdef HAVE_NET_BPF_H
88#    include <net/bpf.h>
89#    define HAVE_BPF 1
90#else
91#ifdef HAVE_PCAP_BPF_H
92#  include <pcap-bpf.h>
93#  define HAVE_BPF 1
94#endif
95#endif
96
97#ifdef HAVE_PCAP_H
98#  include <pcap.h>
99#  ifdef HAVE_PCAP_INT_H
100#    include <pcap-int.h>
101#  endif
102#endif
103
104#ifdef HAVE_ZLIB_H
105#  include <zlib.h>
106#endif
107
108#ifndef HAVE_STRNDUP
109char *strndup(const char *s, size_t size);
110#endif
111
112#ifndef HAVE_STRNCASECMP
113# ifndef HAVE__STRNICMP
114/** A local implementation of strncasecmp (as some systems do not have it) */
115int strncasecmp(const char *str1, const char *str2, size_t n);
116# else
117# define strncasecmp _strnicmp
118# endif
119#endif
120
121#ifndef HAVE_SNPRINTF
122# ifndef HAVE_SPRINTF_S
123/** A local implementation of snprintf (as some systems do not have it) */
124int snprintf(char *str, size_t size, const char *format, ...);
125# else
126# define snprintf sprintf_s
127# endif
128#endif
129
130#include "daglegacy.h"
131       
132#ifdef HAVE_DAG_API
133#  include "dagnew.h"
134#  include "dagapi.h"
135#       if DAG_VERSION == 24
136#               include <erftypes.h>
137#       else
138#               include <daginf.h>
139#       endif
140#  include "erftypes.h"
141#else
142#  include "dagformat.h"
143#endif
144
145#ifdef HAVE_LLVM
146#include "bpf-jit/bpf-jit.h"
147#endif
148
149//#define RP_BUFSIZE 65536U
150
151/** Data about the most recent event from a trace file */
152struct libtrace_event_status_t {
153        /** A libtrace packet to store the packet when a PACKET event occurs */
154        libtrace_packet_t *packet;
155        /** Time between the timestamp for the current packet and the current
156         * walltime */
157        double tdelta;
158        /** The timestamp of the previous PACKET event */
159        double trace_last_ts;
160        /** The size of the current PACKET event */
161        int psize;
162};
163
164/** A libtrace input trace
165 * @internal
166 */
167struct libtrace_t {
168        /** The capture format for the input trace */
169        struct libtrace_format_t *format; 
170        /** Details of the most recent PACKET event reported by the trace */
171        struct libtrace_event_status_t event;
172        /** Pointer to the "global" data for the capture format module */       
173        void *format_data;             
174        /** A BPF filter to be applied to all packets read by the trace -
175         * used only if the capture format does not support filters natively */
176        struct libtrace_filter_t *filter; 
177        /** The snap length to be applied to all packets read by the trace -
178         * used only if the capture format does not support snapping natively */
179        size_t snaplen;                 
180        /** Count of the number of packets returned to the libtrace user */
181        uint64_t accepted_packets;     
182        /** Count of the number of packets filtered by libtrace */
183        uint64_t filtered_packets;     
184        /** The filename from the uri for the trace */
185        char *uridata;                 
186        /** The libtrace IO reader for this trace (if applicable) */
187        io_t *io;                       
188        /** Error information for the trace */
189        libtrace_err_t err;             
190        /** Boolean flag indicating whether the trace has been started */
191        bool started;                   
192};
193
194/** A libtrace output trace
195 * @internal
196 */
197struct libtrace_out_t {
198        /** The capture format for the output trace */
199        struct libtrace_format_t *format;
200        /** Pointer to the "global" data for the capture format module */
201        void *format_data;             
202        /** The filename for the uri for the output trace */
203        char *uridata;                 
204        /** Error information for the output trace */
205        libtrace_err_t err;
206        /** Boolean flag indicating whether the trace has been started */
207        bool started;                   
208};
209
210/** Sets the error status on an input trace
211 *
212 * @param trace         The input trace to set the error status for
213 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
214 * @param msg           A message to print when reporting the error
215 */
216void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...) 
217
218                                                                PRINTF(3,4);
219/** Sets the error status on an output trace
220 *
221 * @param trace         The output trace to set the error status for
222 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
223 * @param msg           A message to print when reporting the error
224 */
225void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...)
226                                                                PRINTF(3,4);
227
228
229/** Converts the data provided in buffer into a valid libtrace packet
230 *
231 * @param trace         An input trace of the same format as the "packet"
232 *                      contained in the buffer
233 * @param packet        The libtrace packet to prepare
234 * @param buffer        A buffer containing the packet data, including the
235 *                      capture format header
236 * @param rt_type       The RT type for the packet that is being prepared
237 * @param flags         Used to specify options for the preparation function,
238 *                      e.g. who owns the packet buffer
239 *
240 * @return -1 if an error occurs, 0 otherwise
241 *
242 * Packet preparation is a tricky concept - the idea is to take the data
243 * pointed to by 'buffer' and treat it as a packet record of the same capture
244 * format as that used by the input trace. The provided libtrace packet then
245 * has its internal pointers and values set to describe the packet record in
246 * the buffer.
247 *
248 * The primary use of this function is to allow the RT packet reader to
249 * easily and safely convert packets from the RT format back into the format
250 * that they were originally captured with., essentially removing the RT
251 * encapsulation.
252 *
253 * We've decided not to make this function available via the exported API
254 * because there are several issues that can arise if it is not used very
255 * carefully and it is not very useful outside of internal contexts anyway.
256 */
257int trace_prepare_packet(libtrace_t *trace, libtrace_packet_t *packet,
258                void *buffer, libtrace_rt_types_t rt_type, uint32_t flags);
259
260/** Flags for prepare_packet functions */
261enum {
262        /** The buffer memory has been allocated by libtrace and should be
263         * freed when the packet is destroyed. */
264        TRACE_PREP_OWN_BUFFER           =1,
265       
266        /** The buffer memory is externally-owned and must not be freed by
267         * libtrace when the packet is destroyed. */
268        TRACE_PREP_DO_NOT_OWN_BUFFER    =0
269};
270
271/** A local definition of an SLL header */
272typedef struct libtrace_sll_header_t {
273        uint16_t pkttype;               /**< Packet type */
274        uint16_t hatype;                /**< Link-layer address type */
275        uint16_t halen;                 /**< Link-layer address length */
276        unsigned char addr[8];          /**< Link-layer address */
277        uint16_t protocol;              /**< Protocol */
278} libtrace_sll_header_t;
279
280
281/* SLL packet types */
282
283/** Packet was addressed for the local host */
284#define TRACE_SLL_HOST          0
285/** Packet was addressed for a broadcast address */
286#define TRACE_SLL_BROADCAST     1
287/** Packet was addressed for a multicast address */
288#define TRACE_SLL_MULTICAST     2
289/** Packet was addressed for another host but was captured by a promiscuous
290 * device */
291#define TRACE_SLL_OTHERHOST     3
292/** Packet originated from the local host */
293#define TRACE_SLL_OUTGOING      4
294
295#ifndef PF_RULESET_NAME_SIZE
296#define PF_RULESET_NAME_SIZE 16
297#endif
298
299#ifndef IFNAMSIZ
300#define IFNAMSIZ 16
301#endif
302
303
304/** A local definition of a PFLOG header */
305typedef struct libtrace_pflog_header_t {
306        uint8_t    length;     
307        sa_family_t   af;
308        uint8_t    action;
309        uint8_t    reason;
310        char       ifname[IFNAMSIZ];
311        char       ruleset[PF_RULESET_NAME_SIZE];
312        uint32_t   rulenr;
313        uint32_t   subrulenr;
314        uint8_t    dir;
315        uint8_t    pad[3];
316} PACKED libtrace_pflog_header_t;
317
318
319
320/** A libtrace capture format module */
321/* All functions should return -1, or NULL on failure */
322struct libtrace_format_t {
323        /** The name of this module, used in the libtrace URI to identify the
324         * capture format */
325        const char *name;
326        /** The version of this module */
327        const char *version;
328        /** The RT protocol type of this module */
329        enum base_format_t type;
330
331
332        /** Given a filename, return if this is the most likely capture format
333         * (used for devices). Used to "guess" the capture format when the
334         * URI is not fully specified.
335         *
336         * @param fname         The name of the device or file to examine
337         * @return 1 if the name matches the capture format, 0 otherwise
338         */
339        int (*probe_filename)(const char *fname);
340       
341        /** Given a file, looks at the start of the file to determine if this
342         * is the capture format. Used to "guess" the capture format when the
343         * URI is not fully specified.
344         *
345         * @param io            An open libtrace IO reader for the file to check
346         * @return 1 if the file matches the capture format, 0 otherwise
347         */
348        int (*probe_magic)(io_t *io);
349
350        /** Initialises an input trace using the capture format.
351         *
352         * @param libtrace      The input trace to be initialised
353         * @return 0 if successful, -1 in the event of error
354         */
355        int (*init_input)(libtrace_t *libtrace);
356       
357        /** Applies a configuration option to an input trace.
358         *
359         * @param libtrace      The input trace to apply the option to
360         * @param option        The option that is being configured
361         * @param value         A pointer to the value that the option is to be
362         *                      set to
363         * @return 0 if successful, -1 if the option is unsupported or an error
364         * occurs
365         */
366        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
367        /** Starts or unpauses an input trace - note that this function is
368         * often the one that opens the file or device for reading.
369         *
370         * @param libtrace      The input trace to be started or unpaused
371         * @return 0 if successful, -1 in the event of error */
372        int (*start_input)(libtrace_t *libtrace);
373
374        /** Pauses an input trace - this function should close or detach the
375         * file or device that is being read from.
376         *
377         * @param libtrace      The input trace to be paused
378         * @return 0 if successful, -1 in the event of error
379         */
380        int (*pause_input)(libtrace_t *libtrace);
381
382        /** Initialises an output trace using the capture format.
383         *
384         * @param libtrace      The output trace to be initialised
385         * @return 0 if successful, -1 in the event of error
386         */
387        int (*init_output)(libtrace_out_t *libtrace);
388       
389        /** Applies a configuration option to an output trace.
390         *
391         * @param libtrace      The output trace to apply the option to
392         * @param option        The option that is being configured
393         * @param value         A pointer to the value that the option is to be
394         *                      set to
395         * @return 0 if successful, -1 if the option is unsupported or an error
396         * occurs
397         * */
398        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value);
399
400        /** Starts an output trace - note that this function is often the one
401         * that opens the file or device for writing.
402         *
403         * @param libtrace      The output trace to be started
404         * @return 0 if successful, -1 if an error occurs
405         *
406         * There is no pause for output traces, as writing is not performed
407         * asynchronously.
408         */
409        int (*start_output)(libtrace_out_t *libtrace);
410
411        /** Concludes an input trace and cleans up the capture format data.
412         *
413         * @param libtrace      The input trace to be concluded
414         * @return 0 if successful, -1 if an error occurs
415         *
416         * Libtrace will call the pause_input function if the input trace is
417         * currently active prior to calling this function.
418         */
419        int (*fin_input)(libtrace_t *libtrace);
420
421        /** Concludes an output trace and cleans up the capture format data.
422         *
423         * @param libtrace      The output trace to be concluded
424         * @return 0 if successful, -1 if an error occurs
425         */
426        int (*fin_output)(libtrace_out_t *libtrace);
427
428        /** Reads the next packet from an input trace into the provided packet
429         * structure.
430         *
431         * @param libtrace      The input trace to read from
432         * @param packet        The libtrace packet to read into
433         * @return The size of the packet read (in bytes) including the capture
434         * framing header, or -1 if an error occurs. 0 is returned in the
435         * event of an EOF.
436         *
437         * If no packets are available for reading, this function should block
438         * until one appears or return 0 if the end of a trace file has been
439         * reached.
440         */
441        int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet);
442       
443        /** Converts a buffer containing a packet record into a libtrace packet
444         *
445         * @param libtrace      An input trace in the capture format for the
446         *                      packet
447         * @param packet        A libtrace packet to put the prepared packet
448         *                      into
449         * @param buffer        The buffer containing the packet record
450         *                      (including the capture format header)
451         * @param rt_type       The RT type for the packet
452         * @param flags         Flags describing properties that should be
453         *                      applied to the new packet
454         * @return 0 if successful, -1 if an error occurs.
455         *
456         * Updates internal trace and packet details, such as payload pointers,
457         * loss counters and packet types to match the packet record provided
458         * in the buffer. This is a zero-copy function.
459         *
460         * Intended (at this stage) only for internal use, particularly by
461         * RT which needs to decapsulate RT packets */
462        int (*prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet,
463                        void *buffer, libtrace_rt_types_t rt_type, 
464                        uint32_t flags);
465       
466        /** Frees any resources allocated by the capture format module for a
467         * libtrace packet.
468         *
469         * @param The packet to be finalised
470         *       */
471        void (*fin_packet)(libtrace_packet_t *packet);
472
473        /** Write a libtrace packet to an output trace.
474         *
475         * @param libtrace      The output trace to write the packet to
476         * @param packet        The packet to be written out
477         * @return The number of bytes written, or -1 if an error occurs
478         */
479        int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet);
480        /** Returns the libtrace link type for a packet.
481         *
482         * @param packet        The packet to get the link type for
483         * @return The libtrace link type, or -1 if this link type is unknown
484         */ 
485        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
486
487        /** Returns the direction of a packet.
488         *
489         * @param packet        The packet to get the direction for
490         * @return The direction of the packet, or -1 if no direction tag is
491         * present or an error occurs
492         */ 
493        libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet);
494       
495        /** Sets the direction of a packet.
496         *
497         * @param packet        The packet to set the direction for
498         * @param direction     The direction to assign to the packet
499         * @return The updated direction for the packet, or -1 if an error
500         * occurs
501         *
502         * @note Some capture formats do not feature direction tagging, so it
503         * will not make sense to implement a set_direction function for them.
504         */ 
505        libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction);
506       
507        /** Returns the timestamp for a packet in the ERF timestamp format.
508         *
509         * @param packet        The packet to get the timestamp from
510         * @return The 64-bit ERF timestamp
511         *
512         * @note Each format must implement at least one of the four "get
513         * timestamp" functions.
514         *
515         * If not implemented, libtrace will convert the result of one of the
516         * other timestamp functions into the appropriate format instead.
517         * This means each capture format only needs to implement the most
518         * sensible of the four and let libtrace handle any conversions.
519         *
520         */
521        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
522
523        /** Returns the timestamp for a packet in the timeval format
524         *
525         * @param packet        The packet to get the timestamp from
526         * @return The timestamp from the packet as a timeval
527         *
528         * @note Each format must implement at least one of the four "get
529         * timestamp" functions.
530         *
531         * If not implemented, libtrace will convert the result of one of the
532         * other timestamp functions into the appropriate format instead.
533         * This means each capture format only needs to implement the most
534         * sensible of the four and let libtrace handle any conversions.
535         */
536        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
537       
538        /** Returns the timestamp for a packet in the timespec format.
539         *
540         * @param packet        The packet to get the timestamp from
541         * @return The timestamp from the packet as a timespec
542         *
543         * @note Each format must implement at least one of the four "get
544         * timestamp" functions.
545         *
546         * If not implemented, libtrace will convert the result of one of the
547         * other timestamp functions into the appropriate format instead.
548         * This means each capture format only needs to implement the most
549         * sensible of the four and let libtrace handle any conversions.
550         */
551        struct timespec (*get_timespec)(const libtrace_packet_t *packet);
552       
553        /** Returns the timestamp for a packet in floating point seconds.
554         *
555         * @param packet        The packet to get the timestamp from
556         * @return The timestamp from the packet as a floating point number of
557         * seconds since 1970-01-01 00:00:00 UTC
558         *
559         * @note Each format must implement at least one of the four "get
560         * timestamp" functions.
561         *
562         * If not implemented, libtrace will convert the result of one of the
563         * other timestamp functions into the appropriate format instead.
564         * This means each capture format only needs to implement the most
565         * sensible of the four and let libtrace handle any conversions.
566         */
567        double (*get_seconds)(const libtrace_packet_t *packet);
568       
569        /** Moves the read pointer to a certain ERF timestamp within an input
570         * trace file.
571         *
572         * @param trace         The input trace to seek within
573         * @param timestamp     The timestamp to seek to, as an ERF timestamp
574         *
575         * @return 0 on success, -1 on failure.
576         *
577         * The next packet read from this trace will now be the first packet
578         * to have a timestamp equal to or greater than the provided timestamp.
579         *
580         * @note Each format that supports seeking must implement at least one
581         * of the seek functions.
582         *
583         * If not implemented, libtrace will convert the timestamp into the
584         * appropriate format to use a seek function that has been implemented.
585         * This means each capture format only needs to implement the seek
586         * function that matches the native timestamp format for that capture.
587         *
588         */
589        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
590        /** Moves the read pointer to a certain timestamp represented using a
591         * timeval within an input trace file.
592         *
593         * @param trace         The input trace to seek within
594         * @param timestamp     The timestamp to seek to, as a timeval
595         *
596         * @return 0 on success, -1 on failure.
597         *
598         * The next packet read from this trace will now be the first packet
599         * to have a timestamp equal to or greater than the provided timestamp.
600         *
601         * @note Each format that supports seeking must implement at least one
602         * of the seek functions.
603         *
604         * If not implemented, libtrace will convert the timestamp into the
605         * appropriate format to use a seek function that has been implemented.
606         * This means each capture format only needs to implement the seek
607         * function that matches the native timestamp format for that capture.
608         *
609         */
610        int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
611       
612        /** Moves the read pointer to a certain timestamp represented using
613         * floating point seconds within an input trace file.
614         *
615         * @param trace         The input trace to seek within
616         * @param timestamp     The timestamp to seek to, as floating point
617         *                      seconds since 1970-01-01 00:00:00 UTC
618         *
619         * @return 0 on success, -1 on failure.
620         *
621         * The next packet read from this trace will now be the first packet
622         * to have a timestamp equal to or greater than the provided timestamp.
623         *
624         * @note Each format that supports seeking must implement at least one
625         * of the seek functions.
626         *
627         * If not implemented, libtrace will convert the timestamp into the
628         * appropriate format to use a seek function that has been implemented.
629         * This means each capture format only needs to implement the seek
630         * function that matches the native timestamp format for that capture.
631         *
632         */
633        int (*seek_seconds)(libtrace_t *trace, double seconds);
634       
635        /** Returns the payload length of the captured packet record.
636         *
637         * @param packet        The packet to get the capture length from
638         * @return The capture length for the packet, or -1 if an error occurs
639         *
640         * Capture length is the current size of the packet record itself,
641         * following any truncation that may have occurred during the capture
642         * process. This length does not include the capture format framing
643         * header.
644         */
645        int (*get_capture_length)(const libtrace_packet_t *packet);
646
647        /** Returns the original length of the packet as it was on the wire.
648         *
649         * @param packet        The packet to get the wire length from
650         * @return The length of the packet on the wire at the time of capture,
651         * or -1 if an error occurs
652         *
653         * Wire length is the original size of the packet prior to any
654         * truncation that may have occurred as part of the capture process.
655         * This length does not include the capture format framing header.
656         */
657        int (*get_wire_length)(const libtrace_packet_t *packet);
658       
659        /** Returns the length of the capture format framing header
660         *
661         * @param packet        The packet to get the framing length from
662         * @return The length of the framing header, or -1 if an error occurs
663         *
664         * The framing header is the extra metadata that the capture process
665         * records about a packet.  The framing length does not include any
666         * of the packet payload itself. The total size of the packet record
667         * can be calculated be adding this value with the capture length.
668         */
669        int (*get_framing_length)(const libtrace_packet_t *packet);
670
671        /** Sets the capture length for a packet.
672         *
673         * @param packet        The packet to adjust the capture length for.
674         * @param size          The new capture length
675         * @return The new capture length of the packet, or -1 if an error
676         * occurs
677         *
678         * @note This function should only reduce the capture length. If the
679         * provided length is larger than the current capture length, -1 should
680         * be returned.
681         */
682        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
683        /** Returns the number of packets observed by an input trace.
684         *
685         * @param trace         The input trace to get the packet count for
686         * @return The number of packets observed by an input trace, or
687         * UINT64_MAX if the number is unknown
688         *
689         * This count includes packets that have been filtered and dropped.
690         */
691        uint64_t (*get_received_packets)(libtrace_t *trace);
692
693        /** Returns the number of packets filtered by an input trace.
694         *
695         * @param trace         The input trace to get the filtered count for
696         * @return The number of packets filtered by the input trace, or
697         * UINT64_MAX if the number is unknown
698         *
699         */
700        uint64_t (*get_filtered_packets)(libtrace_t *trace);
701       
702        /** Returns the number of packets dropped by an input trace.
703         *
704         * @param trace         The input trace to get the dropped count for
705         * @return The number of packets dropped by the input trace, or
706         * UINT64_MAX if the number is unknown
707         *
708         */
709        uint64_t (*get_dropped_packets)(libtrace_t *trace);
710       
711        /** Returns the number of packets captured and returned by an input
712         * trace.
713         *
714         * @param trace         The input trace to get the capture count for
715         * @return The number of packets returned to the libtrace user, or
716         * UINT64_MAX if the number is unknown
717         *
718         * This is the number of packets that have been successfully returned
719         * to the libtrace user via the read_packet() function.
720         *
721         */
722        uint64_t (*get_captured_packets)(libtrace_t *trace);
723       
724        /** Returns the file descriptor used by the input trace.
725         *
726         * @param trace         The input trace to get the file descriptor for
727         * @return The file descriptor used by the input trace to read packets
728         *
729         */
730        int (*get_fd)(const libtrace_t *trace);
731       
732        /** Returns the next libtrace event for the input trace.
733         *
734         * @param trace         The input trace to get the next event from
735         * @param packet        A libtrace packet to read a packet into
736         * @return A libtrace event describing the event that occured
737         *
738         * The event API allows for non-blocking reading of packets from an
739         * input trace. If a packet is available and ready to be read, a packet
740         * event should be returned. Otherwise a sleep or fd event should be
741         * returned to indicate that the caller needs to wait. If the input
742         * trace has an error or reaches EOF, a terminate event should be
743         * returned.
744         */
745        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
746
747        /** Prints some useful help information to standard output. */
748        void (*help)(void);
749
750        /** Next pointer, should always be NULL - used by the format module
751         * manager. */
752        struct libtrace_format_t *next;
753};
754
755/** The list of registered capture formats */
756extern struct libtrace_format_t *form;
757
758/** Registers a new capture format module.
759 *
760 * @param format        The format module to be registered
761 */
762void register_format(struct libtrace_format_t *format);
763
764/** Converts a PCAP DLT into a libtrace link type.
765 *
766 * @param linktype      The PCAP DLT to be converted
767 * @return The libtrace link type that is equivalent to the provided DLT, or
768 * -1 if the DLT is unknown
769 */
770libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype);
771
772/** Converts a PCAP DLT into an RT protocol type.
773 *
774 * @param linktype      The PCAP DLT to be converted
775 * @return The RT type that is equivalent to the provided DLT
776 */
777libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype);
778
779/** Converts a libtrace link type into a PCAP linktype.
780 *
781 * @param type          The libtrace link type to be converted
782 * @return The PCAP linktype that is equivalent to the provided libtrace link
783 * type, or -1 if the link type is unknown
784 */
785libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type);
786
787/** Converts a libtrace link type into a PCAP DLT.
788 *
789 * @param type          The libtrace link type to be converted
790 * @return The PCAP DLT that is equivalent to the provided libtrace link
791 * type, or -1 if the link type is unknown
792 */
793libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type);
794
795/** Converts an RT protocol type into a PCAP DLT.
796 *
797 * @param rt_type       The RT type to be converted
798 * @return The PCAP DLT that is equivalent to the provided RT protocol
799 */
800libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type);
801
802/** Converts an ERF type into a libtrace link type.
803 *
804 * @param erf           The ERF type to be converted
805 * @return The libtrace link type that is equivalent to the provided ERF type,
806 * or -1 if the ERF type is unknown
807 */
808libtrace_linktype_t erf_type_to_libtrace(uint8_t erf);
809
810/** Converts a libtrace link type into an ERF type.
811 *
812 * @param linktype      The libtrace link type to be converted
813 * @return The ERF type that is equivalent to the provided libtrace link type,
814 * or -1 if the link type cannot be matched to an ERF type.
815 */
816uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype);
817
818/** Converts an ARPHRD type into a libtrace link type.
819 *
820 * @param arphrd        The ARPHRD type to be converted
821 * @return The libtrace link type that is equivalent to the provided ARPHRD
822 * type, or -1 if the ARPHRD type is unknown
823 */
824libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd);
825
826/** Converts a libtrace link type into an ARPHRD type.
827 *
828 * @param type          The libtrace link type to be converted
829 * @return The ARPHRD type that is equivalent to the provided libtrace link
830 * type, or -1 if the link type cannot be matched to an ARPHRD type
831 */
832unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type);
833
834/** Converts a libtrace packet to the Linux SLL type.
835 *
836 * @param packet        The packet to be promoted
837 *
838 * @note This will involve memcpy() so use sparingly.
839 *
840 * This function prepends a Linux SLL header to a packet so that we can store
841 * direction tagging information.
842 */
843void promote_packet(libtrace_packet_t *packet);
844
845/** Attempts to demote a packet by removing the first header.
846 *
847 * @param packet        The packet to be demoted
848 * @return True if the packet was demoted, false otherwise.
849 *
850 * Essentially the opposite of promote_packet, except that it will also remove
851 * an ATM header as well as Linux SLL.
852 *
853 */
854bool demote_packet(libtrace_packet_t *packet);
855
856/** Returns a pointer to the header following a Linux SLL header.
857 *
858 * @param link          A pointer to the Linux SLL header to be skipped
859 * @param[out] type     The ethertype of the next header
860 * @param[in,out] remaining     Updated with the number of captured bytes
861 *                              remaining
862 * @return A pointer to the header following the Linux SLL header, or NULL if
863 * no subsequent header is present.
864 *
865 * Remaining must point to the number of bytes captured from the Linux SLL
866 * header and beyond.  It will be decremented by the number of bytes skipped
867 * to find the payload.
868 *
869 * If the Linux SLL header is complete but there are zero bytes of payload
870 * after the end of the header, a pointer to where the payload would be is
871 * returned and remaining will be set to zero. If the Linux SLL header is
872 * incomplete (truncated), then NULL is returned and remaining will be set to
873 * 0. Therefore, it is very important to check the value of remaining after
874 * calling this function.
875 */     
876void *trace_get_payload_from_linux_sll(const void *link, uint16_t *type, 
877                uint32_t *remaining);
878
879/** Returns a pointer to the header following an ATM header.
880 *
881 * @param link          A pointer to the ATM header to be skipped
882 * @param[out] type     The ethertype of the next header
883 * @param[in,out] remaining     Updated with the number of captured bytes
884 *                              remaining
885 * @return A pointer to the header following the ATM header, or NULL if
886 * no subsequent header is present.
887 *
888 * Remaining must point to the number of bytes captured from the ATM header
889 * and beyond.  It will be decremented by the number of bytes skipped to find
890 * the payload.
891 *
892 * If the ATM header is complete but there are zero bytes of payload
893 * after the end of the header, a pointer to where the payload would be is
894 * returned and remaining will be set to zero. If the ATM header is
895 * incomplete (truncated), then NULL is returned and remaining will be set to
896 * 0. Therefore, it is very important to check the value of remaining after
897 * calling this function.
898 */     
899DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type, 
900                uint32_t *remaining);
901
902/** Byteswaps a 64-bit value.
903 *
904 * @param num           The value to be byteswapped.
905 * @return The byteswapped 64-bit number
906 *
907 */
908uint64_t byteswap64(uint64_t num);
909
910/** Byteswaps a 32-bit value.
911 *
912 * @param num           The value to be byteswapped.
913 * @return The byteswapped 32-bit number
914 *
915 */
916uint32_t byteswap32(uint32_t num);
917
918/** Byteswaps a 16-bit value.
919 *
920 * @param num           The value to be byteswapped.
921 * @return The byteswapped 16-bit number
922 *
923 */
924uint16_t byteswap16(uint16_t num);
925
926/** @name Byte ordering
927 * Macros that define how to convert a value into a particular byte-order
928 *
929 * @{
930 */
931#if BYTE_ORDER == BIG_ENDIAN
932#define bswap_host_to_be64(num) ((uint64_t)(num))
933#define bswap_host_to_le64(num) byteswap64(num)
934#define bswap_host_to_be32(num) ((uint32_t)(num))
935#define bswap_host_to_le32(num) byteswap32(num)
936#define bswap_host_to_be16(num) ((uint16_t)(num))
937#define bswap_host_to_le16(num) byteswap16(num)
938
939#define bswap_be_to_host64(num) ((uint64_t)(num))
940#define bswap_le_to_host64(num) byteswap64(num)
941#define bswap_be_to_host32(num) ((uint32_t)(num))
942#define bswap_le_to_host32(num) byteswap32(num)
943#define bswap_be_to_host16(num) ((uint16_t)(num))
944#define bswap_le_to_host16(num) byteswap16(num)
945
946/* We use ntoh*() here, because the compiler may
947 * attempt to optimise it
948 */
949#elif BYTE_ORDER == LITTLE_ENDIAN
950#define bswap_host_to_be64(num) (byteswap64(num))
951#define bswap_host_to_le64(num) ((uint64_t)(num))
952#define bswap_host_to_be32(num) (htonl(num))
953#define bswap_host_to_le32(num) ((uint32_t)(num))
954#define bswap_host_to_be16(num) (htons(num))
955#define bswap_host_to_le16(num) ((uint16_t)(num))
956
957#define bswap_be_to_host64(num) (byteswap64(num))
958#define bswap_le_to_host64(num) ((uint64_t)(num))
959#define bswap_be_to_host32(num) (ntohl(num))
960#define bswap_le_to_host32(num) ((uint32_t)(num))
961#define bswap_be_to_host16(num) (ntohs(num))
962#define bswap_le_to_host16(num) ((uint16_t)(num))
963
964#else
965#error "Unknown byte order"
966#endif
967/** @} */
968
969#ifdef HAVE_BPF
970/* A type encapsulating a bpf filter
971 * This type covers the compiled bpf filter, as well as the original filter
972 * string
973 *
974 */
975
976/** Internal representation of a BPF filter */
977struct libtrace_filter_t {
978        struct bpf_program filter;      /**< The BPF program itself */
979        char * filterstring;            /**< The filter string */
980        int flag;                       /**< Indicates if the filter is valid */
981        struct bpf_jit_t *jitfilter;
982};
983#else
984/** BPF not supported by this system, but we still need to define a structure
985 * for the filter */
986struct libtrace_filter_t {};
987#endif
988
989/** Local definition of a PCAP header */
990typedef struct libtrace_pcapfile_pkt_hdr_t {
991        uint32_t ts_sec;        /* Seconds portion of the timestamp */
992        uint32_t ts_usec;       /* Microseconds portion of the timestamp */
993        uint32_t caplen;        /* Capture length of the packet */
994        uint32_t wirelen;       /* The wire length of the packet */
995} libtrace_pcapfile_pkt_hdr_t;
996
997#ifdef HAVE_DAG
998/** Constructor for the DAG format module */
999void dag_constructor(void);
1000#endif
1001/** Constructor for the ERF format module */
1002void erf_constructor(void);
1003/** Constructor for the TSH format module */
1004void tsh_constructor(void);
1005/** Constructor for the Legacy DAG format module */
1006void legacy_constructor(void);
1007/** Constructor for the Linux Native format module */
1008void linuxnative_constructor(void);
1009/** Constructor for the PCAP format module */
1010void pcap_constructor(void);
1011/** Constructor for the PCAP File format module */
1012void pcapfile_constructor(void);
1013/** Constructor for the RT format module */
1014void rt_constructor(void);
1015/** Constructor for the DUCK format module */
1016void duck_constructor(void);
1017/** Constructor for the ATM Header format module */
1018void atmhdr_constructor(void);
1019#ifdef HAVE_BPF
1020/** Constructor for the BPF format module */
1021void bpf_constructor(void);
1022#endif
1023
1024/** Extracts the RadioTap flags from a wireless link header
1025 *
1026 * @param link          A pointer to the wireless link header
1027 * @param linktype      The link type of the wireless header
1028 * @param[out] flags    Space to store the extracted flags
1029 * @return True if libtrace was able to extract flags from the link header,
1030 * false otherwise.
1031 *
1032 * This function has been left internal because it is not portable across
1033 * drivers.
1034 */
1035bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags);
1036#define TRACE_RADIOTAP_F_FCS 0x10
1037       
1038#ifdef __cplusplus
1039}
1040#endif
1041
1042#endif /* LIBTRACE_INT_H */
Note: See TracBrowser for help on using the repository browser.