source: lib/libtrace_int.h @ 8753bb8

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