Changeset 8488c15


Ignore:
Timestamp:
02/05/10 16:22:42 (12 years ago)
Author:
Shane Alcock <salcock@…>
Branches:
4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, getfragoff, help, libtrace4, master, ndag_format, pfring, rc-4.0.1, rc-4.0.2, rc-4.0.3, rc-4.0.4, ringdecrementfix, ringperformance, ringtimestampfixes
Children:
30892b0
Parents:
43c00e5
Message:
  • Updated the documentation for the internal header file
  • Also removed the reference to trace_get_payload_from_pos() which doesn't exist and the define for RP_BUFSIZE which is never used
File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace_int.h

    reade363 r8488c15  
    22 * This file is part of libtrace
    33 *
    4  * Copyright (c) 2007,2008 The University of Waikato, Hamilton, New Zealand.
     4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
     5 * New Zealand.
     6 *
    57 * Authors: Daniel Lawson
    6  *          Perry Lorier
     8 *          Perry Lorier
     9 *          Shane Alcock
    710 *         
    811 * All rights reserved.
     
    2831 *
    2932 */
    30 /** @file */
    31 
     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 */
    3250#ifndef LIBTRACE_INT_H
    3351#define LIBTRACE_INT_H
     
    90108#ifndef HAVE_STRNCASECMP
    91109# ifndef HAVE__STRNICMP
     110/** A local implementation of strncasecmp (as some systems do not have it) */
    92111int strncasecmp(const char *str1, const char *str2, size_t n);
    93112# else
     
    98117#ifndef HAVE_SNPRINTF
    99118# ifndef HAVE_SPRINTF_S
     119/** A local implementation of snprintf (as some systems do not have it) */
    100120int snprintf(char *str, size_t size, const char *format, ...);
    101121# else
     
    118138#endif
    119139
    120 #define RP_BUFSIZE 65536U
    121 
     140//#define RP_BUFSIZE 65536U
     141
     142/** Data about the most recent event from a trace file */
    122143struct libtrace_event_status_t {
     144        /** A libtrace packet to store the packet when a PACKET event occurs */
    123145        libtrace_packet_t *packet;
     146        /** Time between the timestamp for the current packet and the current
     147         * walltime */
    124148        double tdelta;
     149        /** The timestamp of the previous PACKET event */
    125150        double trace_last_ts;
     151        /** The size of the current PACKET event */
    126152        int psize;
    127153};
    128154
    129 /** The information about traces that are open
     155/** A libtrace input trace
    130156 * @internal
    131157 */
    132158struct libtrace_t {
    133         struct libtrace_format_t *format; /**< format driver pointer */
    134         struct libtrace_event_status_t event;   /**< the next event */
    135         void *format_data;              /**<format data pointer */
    136         struct libtrace_filter_t *filter; /**< used by libtrace if the module
    137                                             * doesn't support filters natively
    138                                             */
    139         size_t snaplen;                 /**< used by libtrace if the module
    140                                           * doesn't support snapping natively
    141                                           */
    142         uint64_t accepted_packets;      /**< Number of packets returned to the
    143                                           * user
    144                                           */
    145         uint64_t filtered_packets;      /**< Number of packets filtered by
    146                                           * libtrace
    147                                           */
    148         char *uridata;                  /**< the uri of this trace */
    149         io_t *io;                       /**< The tracefile (if applicable) */
    150 
    151         libtrace_err_t err;             /**< error information */
    152         bool started;                   /**< if this trace has started */
     159        /** The capture format for the input trace */
     160        struct libtrace_format_t *format;
     161        /** Details of the most recent PACKET event reported by the trace */
     162        struct libtrace_event_status_t event;
     163        /** Pointer to the "global" data for the capture format module */       
     164        void *format_data;             
     165        /** A BPF filter to be applied to all packets read by the trace -
     166         * used only if the capture format does not support filters natively */
     167        struct libtrace_filter_t *filter;
     168        /** The snap length to be applied to all packets read by the trace -
     169         * used only if the capture format does not support snapping natively */
     170        size_t snaplen;                 
     171        /** Count of the number of packets returned to the libtrace user */
     172        uint64_t accepted_packets;     
     173        /** Count of the number of packets filtered by libtrace */
     174        uint64_t filtered_packets;     
     175        /** The filename from the uri for the trace */
     176        char *uridata;                 
     177        /** The libtrace IO reader for this trace (if applicable) */
     178        io_t *io;                       
     179        /** Error information for the trace */
     180        libtrace_err_t err;             
     181        /** Boolean flag indicating whether the trace has been started */
     182        bool started;                   
    153183};
    154184
    155 /** Information about output traces
     185/** A libtrace output trace
    156186 * @internal
    157187 */
    158188struct libtrace_out_t {
    159         struct libtrace_format_t *format;       /**< format driver */
    160         void *format_data;              /**< format data */
    161         char *uridata;                  /**< URI associated with this trace */
    162         libtrace_err_t err;             /**< Associated error */
    163         bool started;                   /**< trace started */
     189        /** The capture format for the output trace */
     190        struct libtrace_format_t *format;
     191        /** Pointer to the "global" data for the capture format module */
     192        void *format_data;             
     193        /** The filename for the uri for the output trace */
     194        char *uridata;                 
     195        /** Error information for the output trace */
     196        libtrace_err_t err;
     197        /** Boolean flag indicating whether the trace has been started */
     198        bool started;                   
    164199};
    165200
     201/** Sets the error status on an input trace
     202 *
     203 * @param trace         The input trace to set the error status for
     204 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
     205 * @param msg           A message to print when reporting the error
     206 */
    166207void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...)
     208
    167209                                                                PRINTF(3,4);
     210/** Sets the error status on an output trace
     211 *
     212 * @param trace         The output trace to set the error status for
     213 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
     214 * @param msg           A message to print when reporting the error
     215 */
    168216void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...)
    169217                                                                PRINTF(3,4);
    170218
    171219
    172 /*
    173  *
    174  * The basic idea of this function is that it will take the data pointed to
    175  * by 'buffer' and treat it as a packet of the same format type as the
    176  * libtrace_t pointed to by 'trace', including the format framing (e.g. an
    177  * erf header for erf and dag formats, a pcap header for pcap formats).
    178  *
    179  * The libtrace packet pointed to by 'packet' will then have its internal
    180  * pointers and values replaced with ones that describe the packet in 'buffer'.
    181  *
    182  * 'rt_type' is used to set packet->type while 'flags' is relatively
    183  * self-explanatory. Definitions of the accepted flags will be provided below.
    184  *
    185  * The primary use of this function is to allow rt_read_packet to nicely
    186  * convert packets from the RT format back to the format that they were
    187  * originally captured with, as RT essentially encapsulates the original trace
    188  * format. We've decided to not make this function available via the API
    189  * because there are a number of issues that can arise if it is not used
    190  * very carefully and there are few situations outside of the RT case where
    191  * you'd want to do something like this anyway.
    192  *
    193  * Returns 0 if successful, -1 if something goes horribly wrong
     220/** Converts the data provided in buffer into a valid libtrace packet
     221 *
     222 * @param trace         An input trace of the same format as the "packet"
     223 *                      contained in the buffer
     224 * @param packet        The libtrace packet to prepare
     225 * @param buffer        A buffer containing the packet data, including the
     226 *                      capture format header
     227 * @param rt_type       The RT type for the packet that is being prepared
     228 * @param flags         Used to specify options for the preparation function,
     229 *                      e.g. who owns the packet buffer
     230 *
     231 * @return -1 if an error occurs, 0 otherwise
     232 *
     233 * Packet preparation is a tricky concept - the idea is to take the data
     234 * pointed to by 'buffer' and treat it as a packet record of the same capture
     235 * format as that used by the input trace. The provided libtrace packet then
     236 * has its internal pointers and values set to describe the packet record in
     237 * the buffer.
     238 *
     239 * The primary use of this function is to allow the RT packet reader to
     240 * easily and safely convert packets from the RT format back into the format
     241 * that they were originally captured with., essentially removing the RT
     242 * encapsulation.
     243 *
     244 * We've decided not to make this function available via the exported API
     245 * because there are several issues that can arise if it is not used very
     246 * carefully and it is not very useful outside of internal contexts anyway.
    194247 */
    195248int trace_prepare_packet(libtrace_t *trace, libtrace_packet_t *packet,
    196249                void *buffer, libtrace_rt_types_t rt_type, uint32_t flags);
    197250
    198 /* Flags for prepare_packet functions */
    199 /*-------------------------------------*/
     251/** Flags for prepare_packet functions */
    200252enum {
    201         /* If set, the memory pointed to by 'buffer' is malloc()'d and
    202          * libtrace should undertake ownership of that memory. If not set,
    203          * the memory is treated as externally-owned and will not be freed by
     253        /** The buffer memory has been allocated by libtrace and should be
     254         * freed when the packet is destroyed. */
     255        TRACE_PREP_OWN_BUFFER           =1,
     256       
     257        /** The buffer memory is externally-owned and must not be freed by
    204258         * libtrace when the packet is destroyed. */
    205         TRACE_PREP_OWN_BUFFER           =1,
    206259        TRACE_PREP_DO_NOT_OWN_BUFFER    =0
    207260};
    208261
    209 #define TRACE_PREP_OWN_BUFFER   1
    210 
    211                                                                
     262/** A local definition of an SLL header */
    212263typedef struct libtrace_sll_header_t {
    213         uint16_t pkttype;               /* packet type */
    214         uint16_t hatype;                /* link-layer address type */
    215         uint16_t halen;                 /* link-layer address length */
    216         unsigned char addr[8];          /* link-layer address */
    217         uint16_t protocol;              /* protocol */
     264        uint16_t pkttype;               /**< Packet type */
     265        uint16_t hatype;                /**< Link-layer address type */
     266        uint16_t halen;                 /**< Link-layer address length */
     267        unsigned char addr[8];          /**< Link-layer address */
     268        uint16_t protocol;              /**< Protocol */
    218269} libtrace_sll_header_t;
    219270
     271
     272/* SLL packet types */
     273
     274/** Packet was addressed for the local host */
    220275#define TRACE_SLL_HOST          0
     276/** Packet was addressed for a broadcast address */
    221277#define TRACE_SLL_BROADCAST     1
     278/** Packet was addressed for a multicast address */
    222279#define TRACE_SLL_MULTICAST     2
     280/** Packet was addressed for another host but was captured by a promiscuous
     281 * device */
    223282#define TRACE_SLL_OTHERHOST     3
     283/** Packet originated from the local host */
    224284#define TRACE_SLL_OUTGOING      4
    225285
     
    232292#endif
    233293
     294
     295/** A local definition of a PFLOG header */
    234296typedef struct libtrace_pflog_header_t {
    235         uint8_t    length;
     297        uint8_t    length;     
    236298        sa_family_t   af;
    237299        uint8_t    action;
     
    247309
    248310
    249 /** Module definition structure */
    250 /* all of these should return -1, or NULL on failure */
     311/** A libtrace capture format module */
     312/* All functions should return -1, or NULL on failure */
    251313struct libtrace_format_t {
    252         /** the uri name of this module */
     314        /** The name of this module, used in the libtrace URI to identify the
     315         * capture format */
    253316        const char *name;
    254         /** the version of this module */
     317        /** The version of this module */
    255318        const char *version;
    256         /** the RT protocol type of this module */
     319        /** The RT protocol type of this module */
    257320        enum base_format_t type;
    258321
    259 /* Padding inserted here to make the enum fit properly */
    260 
    261         /** stuff that deals with input @{ */
    262         /** Given a filename, return if this format is responsible
    263          * (used for devices)
     322
     323        /** Given a filename, return if this is the most likely capture format
     324         * (used for devices). Used to "guess" the capture format when the
     325         * URI is not fully specified.
     326         *
     327         * @param fname         The name of the device or file to examine
     328         * @return 1 if the name matches the capture format, 0 otherwise
    264329         */
    265330        int (*probe_filename)(const char *fname);
    266         /** Given a file, look for file magic. */
     331       
     332        /** Given a file, looks at the start of the file to determine if this
     333         * is the capture format. Used to "guess" the capture format when the
     334         * URI is not fully specified.
     335         *
     336         * @param io            An open libtrace IO reader for the file to check
     337         * @return 1 if the file matches the capture format, 0 otherwise
     338         */
    267339        int (*probe_magic)(io_t *io);
    268         /** initialise an trace (or NULL if input is not supported) */
     340
     341        /** Initialises an input trace using the capture format.
     342         *
     343         * @param libtrace      The input trace to be initialised
     344         * @return 0 if successful, -1 in the event of error
     345         */
    269346        int (*init_input)(libtrace_t *libtrace);
    270         /** configure an trace (or NULL if input is not supported) */
     347       
     348        /** Applies a configuration option to an input trace.
     349         *
     350         * @param libtrace      The input trace to apply the option to
     351         * @param option        The option that is being configured
     352         * @param value         A pointer to the value that the option is to be
     353         *                      set to
     354         * @return 0 if successful, -1 if the option is unsupported or an error
     355         * occurs
     356         */
    271357        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
    272         /** start/unpause an trace (or NULL if input not supported) */
     358        /** Starts or unpauses an input trace - note that this function is
     359         * often the one that opens the file or device for reading.
     360         *
     361         * @param libtrace      The input trace to be started or unpaused
     362         * @return 0 if successful, -1 in the event of error */
    273363        int (*start_input)(libtrace_t *libtrace);
    274         /** pause an trace (or NULL if input not supported) */
     364
     365        /** Pauses an input trace - this function should close or detach the
     366         * file or device that is being read from.
     367         *
     368         * @param libtrace      The input trace to be paused
     369         * @return 0 if successful, -1 in the event of error
     370         */
    275371        int (*pause_input)(libtrace_t *libtrace);
    276         /** @} */
    277         /** stuff that deals with output @{ */
    278         /** initialise output traces (or NULL if output not supported) */
     372
     373        /** Initialises an output trace using the capture format.
     374         *
     375         * @param libtrace      The output trace to be initialised
     376         * @return 0 if successful, -1 in the event of error
     377         */
    279378        int (*init_output)(libtrace_out_t *libtrace);
    280         /** configure output traces (or NULL if output not supported) */
    281         int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *);
    282         /** start output traces (or NULL if output not supported)
    283          * There is no pause for output traces, as packets are not arriving
    284          * asyncronously
     379       
     380        /** Applies a configuration option to an output trace.
     381         *
     382         * @param libtrace      The output trace to apply the option to
     383         * @param option        The option that is being configured
     384         * @param value         A pointer to the value that the option is to be
     385         *                      set to
     386         * @return 0 if successful, -1 if the option is unsupported or an error
     387         * occurs
     388         * */
     389        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value);
     390
     391        /** Starts an output trace - note that this function is often the one
     392         * that opens the file or device for writing.
     393         *
     394         * @param libtrace      The output trace to be started
     395         * @return 0 if successful, -1 if an error occurs
     396         *
     397         * There is no pause for output traces, as writing is not performed
     398         * asynchronously.
    285399         */
    286400        int (*start_output)(libtrace_out_t *libtrace);
    287         /** @} */
    288         /** finish an input trace, cleanup (or NULL if input not supported)
    289          * if the trace is not paused, libtrace will pause the trace before
    290          * calling this function.
     401
     402        /** Concludes an input trace and cleans up the capture format data.
     403         *
     404         * @param libtrace      The input trace to be concluded
     405         * @return 0 if successful, -1 if an error occurs
     406         *
     407         * Libtrace will call the pause_input function if the input trace is
     408         * currently active prior to calling this function.
    291409         */
    292410        int (*fin_input)(libtrace_t *libtrace);
    293         /** finish an output trace, cleanup (or NULL if output not supported) */
     411
     412        /** Concludes an output trace and cleans up the capture format data.
     413         *
     414         * @param libtrace      The output trace to be concluded
     415         * @return 0 if successful, -1 if an error occurs
     416         */
    294417        int (*fin_output)(libtrace_out_t *libtrace);
    295         /** read a packet from a trace into the provided packet structure
    296          * @returns -1 on error, or get_framing_length()+get_capture_length() \
    297          * on success.
    298          * if this function is not supported, this field may be NULL.
     418
     419        /** Reads the next packet from an input trace into the provided packet
     420         * structure.
     421         *
     422         * @param libtrace      The input trace to read from
     423         * @param packet        The libtrace packet to read into
     424         * @return The size of the packet read (in bytes) including the capture
     425         * framing header, or -1 if an error occurs. 0 is returned in the
     426         * event of an EOF.
     427         *
     428         * If no packets are available for reading, this function should block
     429         * until one appears or return 0 if the end of a trace file has been
     430         * reached.
    299431         */
    300432        int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet);
    301         /** prepares a packet for general libtrace usage
    302          * updates internal trace and packet details, such as payload pointers,
    303          * loss counters and packet types.
     433       
     434        /** Converts a buffer containing a packet record into a libtrace packet
     435         *
     436         * @param libtrace      An input trace in the capture format for the
     437         *                      packet
     438         * @param packet        A libtrace packet to put the prepared packet
     439         *                      into
     440         * @param buffer        The buffer containing the packet record
     441         *                      (including the capture format header)
     442         * @param rt_type       The RT type for the packet
     443         * @param flags         Flags describing properties that should be
     444         *                      applied to the new packet
     445         * @return 0 if successful, -1 if an error occurs.
     446         *
     447         * Updates internal trace and packet details, such as payload pointers,
     448         * loss counters and packet types to match the packet record provided
     449         * in the buffer. This is a zero-copy function.
     450         *
    304451         * Intended (at this stage) only for internal use, particularly by
    305452         * RT which needs to decapsulate RT packets */
     
    307454                        void *buffer, libtrace_rt_types_t rt_type,
    308455                        uint32_t flags);
    309         /** finalise a packet
    310          * cleanup any resources used by a packet that can't be reused for
    311          * the next packet.
    312          */
     456       
     457        /** Frees any resources allocated by the capture format module for a
     458         * libtrace packet.
     459         *
     460         * @param The packet to be finalised
     461         *       */
    313462        void (*fin_packet)(libtrace_packet_t *packet);
    314         /** write a packet to a trace from the provided packet
    315          * (or NULL if output not supported)
     463
     464        /** Write a libtrace packet to an output trace.
     465         *
     466         * @param libtrace      The output trace to write the packet to
     467         * @param packet        The packet to be written out
     468         * @return The number of bytes written, or -1 if an error occurs
    316469         */
    317470        int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet);
    318         /** return the libtrace link type for this packet
    319          * @return the libtrace link type, or -1 if this link type is unknown
     471        /** Returns the libtrace link type for a packet.
     472         *
     473         * @param packet        The packet to get the link type for
     474         * @return The libtrace link type, or -1 if this link type is unknown
    320475         */
    321476        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
    322         /** return the direction of this packet
    323          * @note This callback may be NULL if not supported.
     477
     478        /** Returns the direction of a packet.
     479         *
     480         * @param packet        The packet to get the direction for
     481         * @return The direction of the packet, or -1 if no direction tag is
     482         * present or an error occurs
    324483         */
    325484        libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet);
    326         /** set the direction of this packet
    327          * @note This callback may be NULL if not supported.
     485       
     486        /** Sets the direction of a packet.
     487         *
     488         * @param packet        The packet to set the direction for
     489         * @param direction     The direction to assign to the packet
     490         * @return The updated direction for the packet, or -1 if an error
     491         * occurs
     492         *
     493         * @note Some capture formats do not feature direction tagging, so it
     494         * will not make sense to implement a set_direction function for them.
    328495         */
    329496        libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction);
    330         /** return the erf timestamp of the packet.
    331          * @return the 64bit erf timestamp
    332          * This field may be NULL in the structure, and libtrace will
    333          * synthesise the result from get_timeval or get_seconds if they
    334          * exist.  AT least one of get_erf_timestamp, get_timeval or
    335          * get_seconds must be implemented.
     497       
     498        /** Returns the timestamp for a packet in the ERF timestamp format.
     499         *
     500         * @param packet        The packet to get the timestamp from
     501         * @return The 64-bit ERF timestamp
     502         *
     503         * @note Each format must implement at least one of the four "get
     504         * timestamp" functions.
     505         *
     506         * If not implemented, libtrace will convert the result of one of the
     507         * other timestamp functions into the appropriate format instead.
     508         * This means each capture format only needs to implement the most
     509         * sensible of the four and let libtrace handle any conversions.
     510         *
    336511         */
    337512        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
    338         /** return the timeval of this packet.
    339          * @return the timeval
    340          * This field may be NULL in the structure, and libtrace will
    341          * synthesise the result from get_erf_timestamp or get_seconds if they
    342          * exist.  AT least one of get_erf_timestamp, get_timeval or
    343          * get_seconds must be implemented.
     513
     514        /** Returns the timestamp for a packet in the timeval format
     515         *
     516         * @param packet        The packet to get the timestamp from
     517         * @return The timestamp from the packet as a timeval
     518         *
     519         * @note Each format must implement at least one of the four "get
     520         * timestamp" functions.
     521         *
     522         * If not implemented, libtrace will convert the result of one of the
     523         * other timestamp functions into the appropriate format instead.
     524         * This means each capture format only needs to implement the most
     525         * sensible of the four and let libtrace handle any conversions.
    344526         */
    345527        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
    346         /** return the timespec of this packet.
    347          * @return the timespec
    348          * This field may be NULL in the structure, and libtrace will
    349          * synthesise the result from get_erf_timestamp or get_seconds if they
    350          * exist.  AT least one of get_erf_timestamp, get_timeval or
    351          * get_seconds must be implemented.
     528       
     529        /** Returns the timestamp for a packet in the timespec format.
     530         *
     531         * @param packet        The packet to get the timestamp from
     532         * @return The timestamp from the packet as a timespec
     533         *
     534         * @note Each format must implement at least one of the four "get
     535         * timestamp" functions.
     536         *
     537         * If not implemented, libtrace will convert the result of one of the
     538         * other timestamp functions into the appropriate format instead.
     539         * This means each capture format only needs to implement the most
     540         * sensible of the four and let libtrace handle any conversions.
    352541         */
    353542        struct timespec (*get_timespec)(const libtrace_packet_t *packet);
    354         /** return the timestamp of this packet.
    355          * @return the floating point seconds since 1970-01-01 00:00:00
    356          * This field may be NULL in the structure, and libtrace will
    357          * synthesise the result from get_timeval or get_erf_timestamp if they
    358          * exist.  AT least one of get_erf_timestamp, get_timeval or
    359          * get_seconds must be implemented.
     543       
     544        /** Returns the timestamp for a packet in floating point seconds.
     545         *
     546         * @param packet        The packet to get the timestamp from
     547         * @return The timestamp from the packet as a floating point number of
     548         * seconds since 1970-01-01 00:00:00 UTC
     549         *
     550         * @note Each format must implement at least one of the four "get
     551         * timestamp" functions.
     552         *
     553         * If not implemented, libtrace will convert the result of one of the
     554         * other timestamp functions into the appropriate format instead.
     555         * This means each capture format only needs to implement the most
     556         * sensible of the four and let libtrace handle any conversions.
    360557         */
    361558        double (*get_seconds)(const libtrace_packet_t *packet);
    362         /** move the pointer within the trace.
     559       
     560        /** Moves the read pointer to a certain ERF timestamp within an input
     561         * trace file.
     562         *
     563         * @param trace         The input trace to seek within
     564         * @param timestamp     The timestamp to seek to, as an ERF timestamp
     565         *
    363566         * @return 0 on success, -1 on failure.
    364          * The next packet returned by read_packet be the first
    365          * packet in the trace to have a timestamp equal or greater than
    366          * timestamp.
    367          * @note this function may be NULL if the format does not support
    368          * this feature.  If the format implements seek_timeval and/or
    369          * seek_seconds then libtrace will call those functions instead.
     567         *
     568         * The next packet read from this trace will now be the first packet
     569         * to have a timestamp equal to or greater than the provided timestamp.
     570         *
     571         * @note Each format that supports seeking must implement at least one
     572         * of the seek functions.
     573         *
     574         * If not implemented, libtrace will convert the timestamp into the
     575         * appropriate format to use a seek function that has been implemented.
     576         * This means each capture format only needs to implement the seek
     577         * function that matches the native timestamp format for that capture.
     578         *
    370579         */
    371580        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
    372         /** move the pointer within the trace.
     581        /** Moves the read pointer to a certain timestamp represented using a
     582         * timeval within an input trace file.
     583         *
     584         * @param trace         The input trace to seek within
     585         * @param timestamp     The timestamp to seek to, as a timeval
     586         *
    373587         * @return 0 on success, -1 on failure.
    374          * The next packet returned by read_packet be the first
    375          * packet in the trace to have a timestamp equal or greater than
    376          * timestamp.
    377          * @note this function may be NULL if the format does not support
    378          * this feature.  If the format implements seek_erf and/or
    379          * seek_seconds then libtrace will call those functions instead.
     588         *
     589         * The next packet read from this trace will now be the first packet
     590         * to have a timestamp equal to or greater than the provided timestamp.
     591         *
     592         * @note Each format that supports seeking must implement at least one
     593         * of the seek functions.
     594         *
     595         * If not implemented, libtrace will convert the timestamp into the
     596         * appropriate format to use a seek function that has been implemented.
     597         * This means each capture format only needs to implement the seek
     598         * function that matches the native timestamp format for that capture.
     599         *
    380600         */
    381601        int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
    382         /** move the pointer within the trace.
     602       
     603        /** Moves the read pointer to a certain timestamp represented using
     604         * floating point seconds within an input trace file.
     605         *
     606         * @param trace         The input trace to seek within
     607         * @param timestamp     The timestamp to seek to, as floating point
     608         *                      seconds since 1970-01-01 00:00:00 UTC
     609         *
    383610         * @return 0 on success, -1 on failure.
    384          * The next packet returned by read_packet be the first
    385          * packet in the trace to have a timestamp equal or greater than
    386          * tv.
    387          * @note this function may be NULL if the format does not support
    388          * this feature.  If the format implements seek_erf and/or
    389          * seek_timeval then libtrace will call those functions instead.
     611         *
     612         * The next packet read from this trace will now be the first packet
     613         * to have a timestamp equal to or greater than the provided timestamp.
     614         *
     615         * @note Each format that supports seeking must implement at least one
     616         * of the seek functions.
     617         *
     618         * If not implemented, libtrace will convert the timestamp into the
     619         * appropriate format to use a seek function that has been implemented.
     620         * This means each capture format only needs to implement the seek
     621         * function that matches the native timestamp format for that capture.
     622         *
    390623         */
    391624        int (*seek_seconds)(libtrace_t *trace, double seconds);
    392         /** return the captured payload length
    393          * @return the amount of data captured in a trace.
    394          * This is the number of bytes actually in the trace.  This does not
    395          * include the trace framing length.  This is usually shorter or
    396          * equal to the wire length.
     625       
     626        /** Returns the payload length of the captured packet record.
     627         *
     628         * @param packet        The packet to get the capture length from
     629         * @return The capture length for the packet, or -1 if an error occurs
     630         *
     631         * Capture length is the current size of the packet record itself,
     632         * following any truncation that may have occurred during the capture
     633         * process. This length does not include the capture format framing
     634         * header.
    397635         */
    398636        int (*get_capture_length)(const libtrace_packet_t *packet);
    399         /** return the original length of the packet on the wire.
    400          * @return the length of the packet on the wire before truncation.
    401          * This is the number of bytes actually in the trace.  This does not
    402          * include the trace framing length.  This is usually shorter or
    403          * equal to the wire length.
     637
     638        /** Returns the original length of the packet as it was on the wire.
     639         *
     640         * @param packet        The packet to get the wire length from
     641         * @return The length of the packet on the wire at the time of capture,
     642         * or -1 if an error occurs
     643         *
     644         * Wire length is the original size of the packet prior to any
     645         * truncation that may have occurred as part of the capture process.
     646         * This length does not include the capture format framing header.
    404647         */
    405648        int (*get_wire_length)(const libtrace_packet_t *packet);
    406         /** return the length of the trace framing header
    407          * @return the length of the framing header
    408          * The framing header is the extra metadata a trace stores about
    409          * a packet.  This does not include the wire or capture length
    410          * of the packet.  Usually get_framing_length()+get_capture_length()
    411          * is the size returned by read_packet
     649       
     650        /** Returns the length of the capture format framing header
     651         *
     652         * @param packet        The packet to get the framing length from
     653         * @return The length of the framing header, or -1 if an error occurs
     654         *
     655         * The framing header is the extra metadata that the capture process
     656         * records about a packet.  The framing length does not include any
     657         * of the packet payload itself. The total size of the packet record
     658         * can be calculated be adding this value with the capture length.
    412659         */
    413660        int (*get_framing_length)(const libtrace_packet_t *packet);
    414         /** truncate (snap) the packet
    415          * @returns the new size
    416          * @note This callback may be NULL if not supported.
     661
     662        /** Sets the capture length for a packet.
     663         *
     664         * @param packet        The packet to adjust the capture length for.
     665         * @param size          The new capture length
     666         * @return The new capture length of the packet, or -1 if an error
     667         * occurs
     668         *
     669         * @note This function should only reduce the capture length. If the
     670         * provided length is larger than the current capture length, -1 should
     671         * be returned.
    417672         */
    418673        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
    419         /** Report the number of packets ever seen as early as possible
     674        /** Returns the number of packets observed by an input trace.
     675         *
     676         * @param trace         The input trace to get the packet count for
     677         * @return The number of packets observed by an input trace, or
     678         * UINT64_MAX if the number is unknown
     679         *
     680         * This count includes packets that have been filtered and dropped.
    420681         */
    421682        uint64_t (*get_received_packets)(libtrace_t *trace);
    422         /** Report the number of filtered packets.
     683
     684        /** Returns the number of packets filtered by an input trace.
     685         *
     686         * @param trace         The input trace to get the filtered count for
     687         * @return The number of packets filtered by the input trace, or
     688         * UINT64_MAX if the number is unknown
     689         *
    423690         */
    424691        uint64_t (*get_filtered_packets)(libtrace_t *trace);
    425         /** Return the number of dropped packets */
     692       
     693        /** Returns the number of packets dropped by an input trace.
     694         *
     695         * @param trace         The input trace to get the dropped count for
     696         * @return The number of packets dropped by the input trace, or
     697         * UINT64_MAX if the number is unknown
     698         *
     699         */
    426700        uint64_t (*get_dropped_packets)(libtrace_t *trace);
    427         /** Report number of captured packets
     701       
     702        /** Returns the number of packets captured and returned by an input
     703         * trace.
     704         *
     705         * @param trace         The input trace to get the capture count for
     706         * @return The number of packets returned to the libtrace user, or
     707         * UINT64_MAX if the number is unknown
     708         *
     709         * This is the number of packets that have been successfully returned
     710         * to the libtrace user via the read_packet() function.
     711         *
    428712         */
    429713        uint64_t (*get_captured_packets)(libtrace_t *trace);
    430         /** return the filedescriptor associated with this interface.
    431          * @note This callback may be NULL if not supported.
    432          * This function is only needed if you use trace_event_interface
    433          * as the pointer for trace_event
     714       
     715        /** Returns the file descriptor used by the input trace.
     716         *
     717         * @param trace         The input trace to get the file descriptor for
     718         * @return The file descriptor used by the input trace to read packets
     719         *
    434720         */
    435721        int (*get_fd)(const libtrace_t *trace);
    436         /** return the next event from this source
    437          * @note may be NULL if not supported.
     722       
     723        /** Returns the next libtrace event for the input trace.
     724         *
     725         * @param trace         The input trace to get the next event from
     726         * @param packet        A libtrace packet to read a packet into
     727         * @return A libtrace event describing the event that occured
     728         *
     729         * The event API allows for non-blocking reading of packets from an
     730         * input trace. If a packet is available and ready to be read, a packet
     731         * event should be returned. Otherwise a sleep or fd event should be
     732         * returned to indicate that the caller needs to wait. If the input
     733         * trace has an error or reaches EOF, a terminate event should be
     734         * returned.
    438735         */
    439736        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
    440         /** return information about this trace format to standard out */
     737
     738        /** Prints some useful help information to standard output. */
    441739        void (*help)(void);
    442         /** next pointer, should be NULL */
     740
     741        /** Next pointer, should always be NULL - used by the format module
     742         * manager. */
    443743        struct libtrace_format_t *next;
    444744};
    445745
     746/** The list of registered capture formats */
    446747extern struct libtrace_format_t *form;
    447748
     749/** Registers a new capture format module.
     750 *
     751 * @param format        The format module to be registered
     752 */
    448753void register_format(struct libtrace_format_t *format);
    449754
     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 */
    450761libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype);
     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 */
    451768libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype);
     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 */
    452776libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type);
     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 */
    453784libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type);
     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 */
    454791libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type);
     792
     793/** Converts an ERF type into a libtrace link type.
     794 *
     795 * @param erf           The ERF type to be converted
     796 * @return The libtrace link type that is equivalent to the provided ERF type,
     797 * or -1 if the ERF type is unknown
     798 */
    455799libtrace_linktype_t erf_type_to_libtrace(uint8_t erf);
     800
     801/** Converts a libtrace link type into an ERF type.
     802 *
     803 * @param linktype      The libtrace link type to be converted
     804 * @return The ERF type that is equivalent to the provided libtrace link type,
     805 * or -1 if the link type cannot be matched to an ERF type.
     806 */
    456807uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype);
    457 libtrace_linktype_t arphrd_type_to_libtrace(unsigned int);
    458 unsigned int libtrace_to_arphrd_type(libtrace_linktype_t);
    459 
     808
     809/** Converts an ARPHRD type into a libtrace link type.
     810 *
     811 * @param arphrd        The ARPHRD type to be converted
     812 * @return The libtrace link type that is equivalent to the provided ARPHRD
     813 * type, or -1 if the ARPHRD type is unknown
     814 */
     815libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd);
     816
     817/** Converts a libtrace link type into an ARPHRD type.
     818 *
     819 * @param type          The libtrace link type to be converted
     820 * @return The ARPHRD type that is equivalent to the provided libtrace link
     821 * type, or -1 if the link type cannot be matched to an ARPHRD type
     822 */
     823unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type);
     824
     825/** Converts a libtrace packet to the Linux SLL type.
     826 *
     827 * @param packet        The packet to be promoted
     828 *
     829 * @note This will involve memcpy() so use sparingly.
     830 *
     831 * This function prepends a Linux SLL header to a packet so that we can store
     832 * direction tagging information.
     833 */
    460834void promote_packet(libtrace_packet_t *packet);
     835
     836/** Attempts to demote a packet by removing the first header.
     837 *
     838 * @param packet        The packet to be demoted
     839 * @return True if the packet was demoted, false otherwise.
     840 *
     841 * Essentially the opposite of promote_packet, except that it will also remove
     842 * an ATM header as well as Linux SLL.
     843 *
     844 */
    461845bool demote_packet(libtrace_packet_t *packet);
    462846
    463 void *trace_get_payload_from_linux_sll(const void *, uint16_t *, uint32_t *);
    464 void *trace_get_payload_from_pos(void *, uint16_t *, uint32_t *);
    465 DLLEXPORT void *trace_get_payload_from_atm(void *, uint8_t *, uint32_t *);
    466 
     847/** Returns a pointer to the header following a Linux SLL header.
     848 *
     849 * @param link          A pointer to the Linux SLL header to be skipped
     850 * @param[out] type     The ethertype of the next header
     851 * @param[in,out] remaining     Updated with the number of captured bytes
     852 *                              remaining
     853 * @return A pointer to the header following the Linux SLL header, or NULL if
     854 * no subsequent header is present.
     855 *
     856 * Remaining must point to the number of bytes captured from the Linux SLL
     857 * header and beyond.  It will be decremented by the number of bytes skipped
     858 * to find the payload.
     859 *
     860 * If the Linux SLL header is complete but there are zero bytes of payload
     861 * after the end of the header, a pointer to where the payload would be is
     862 * returned and remaining will be set to zero. If the Linux SLL header is
     863 * incomplete (truncated), then NULL is returned and remaining will be set to
     864 * 0. Therefore, it is very important to check the value of remaining after
     865 * calling this function.
     866 */     
     867void *trace_get_payload_from_linux_sll(const void *link, uint16_t *type,
     868                uint32_t *remaining);
     869
     870/** Returns a pointer to the header following an ATM header.
     871 *
     872 * @param link          A pointer to the ATM header to be skipped
     873 * @param[out] type     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 ATM header, or NULL if
     877 * no subsequent header is present.
     878 *
     879 * Remaining must point to the number of bytes captured from the ATM header
     880 * and beyond.  It will be decremented by the number of bytes skipped to find
     881 * the payload.
     882 *
     883 * If the ATM 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 ATM 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 */     
     890DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type,
     891                uint32_t *remaining);
     892
     893/** Byteswaps a 64-bit value.
     894 *
     895 * @param num           The value to be byteswapped.
     896 * @return The byteswapped 64-bit number
     897 *
     898 */
    467899uint64_t byteswap64(uint64_t num);
     900
     901/** Byteswaps a 32-bit value.
     902 *
     903 * @param num           The value to be byteswapped.
     904 * @return The byteswapped 32-bit number
     905 *
     906 */
    468907uint32_t byteswap32(uint32_t num);
     908
     909/** Byteswaps a 16-bit value.
     910 *
     911 * @param num           The value to be byteswapped.
     912 * @return The byteswapped 16-bit number
     913 *
     914 */
    469915uint16_t byteswap16(uint16_t num);
    470916
    471 /* Because some traces/protocols are defined as
    472  * being "big endian" or "little endian" we have
    473  * this series of macros.
     917/** @name Byte ordering
     918 * Macros that define how to convert a value into a particular byte-order
     919 *
     920 * @{
    474921 */
    475922#if BYTE_ORDER == BIG_ENDIAN
     
    509956#error "Unknown byte order"
    510957#endif
     958/** @} */
    511959
    512960#ifdef HAVE_BPF
     
    516964 *
    517965 */
     966
     967/** Internal representation of a BPF filter */
    518968struct libtrace_filter_t {
    519         struct bpf_program filter;
    520         char * filterstring;
    521         int flag;
     969        struct bpf_program filter;      /**< The BPF program itself */
     970        char * filterstring;            /**< The filter string */
     971        int flag;                       /**< Indicates if the filter is valid */
    522972};
    523973#else
     974/** BPF not supported by this system, but we still need to define a structure
     975 * for the filter */
    524976struct libtrace_filter_t {};
    525977#endif
    526978
    527 /** libtrace packet
    528  */
     979/** Local definition of a PCAP header */
    529980typedef struct libtrace_pcapfile_pkt_hdr_t {
    530         uint32_t ts_sec;
    531         uint32_t ts_usec;
    532         uint32_t caplen;
    533         uint32_t wirelen;
     981        uint32_t ts_sec;        /* Seconds portion of the timestamp */
     982        uint32_t ts_usec;       /* Microseconds portion of the timestamp */
     983        uint32_t caplen;        /* Capture length of the packet */
     984        uint32_t wirelen;       /* The wire length of the packet */
    534985} libtrace_pcapfile_pkt_hdr_t;
    535986
    536987#ifdef HAVE_DAG
     988/** Constructor for the DAG format module */
    537989void dag_constructor(void);
    538990#endif
     991/** Constructor for the ERF format module */
    539992void erf_constructor(void);
     993/** Constructor for the TSH format module */
    540994void tsh_constructor(void);
     995/** Constructor for the Legacy DAG format module */
    541996void legacy_constructor(void);
     997/** Constructor for the Linux Native format module */
    542998void linuxnative_constructor(void);
     999/** Constructor for the PCAP format module */
    5431000void pcap_constructor(void);
     1001/** Constructor for the PCAP File format module */
    5441002void pcapfile_constructor(void);
     1003/** Constructor for the RT format module */
    5451004void rt_constructor(void);
     1005/** Constructor for the DUCK format module */
    5461006void duck_constructor(void);
     1007/** Constructor for the ATM Header format module */
    5471008void atmhdr_constructor(void);
    5481009#ifdef HAVE_BPF
     1010/** Constructor for the BPF format module */
    5491011void bpf_constructor(void);
    5501012#endif
    5511013
    552 /* Used internally by get_wire_length() methods */
     1014/** Extracts the RadioTap flags from a wireless link header
     1015 *
     1016 * @param link          A pointer to the wireless link header
     1017 * @param linktype      The link type of the wireless header
     1018 * @param[out] flags    Space to store the extracted flags
     1019 * @return True if libtrace was able to extract flags from the link header,
     1020 * false otherwise.
     1021 *
     1022 * This function has been left internal because it is not portable across
     1023 * drivers.
     1024 */
    5531025bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags);
    5541026#define TRACE_RADIOTAP_F_FCS 0x10
Note: See TracChangeset for help on using the changeset viewer.