source: lib/libtrace_int.h @ 8b49230

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 8b49230 was 8b49230, checked in by Shane Alcock <salcock@…>, 8 years ago

Fixed problems with decoding RadioTap? headers with libpacketdump on big endian
hosts

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