source: lib/libtrace_int.h @ 1576a3b

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